workspace-init

WILLOSCAR's avatarfrom WILLOSCAR

Initialize a new workspace by copying the standard artifact template (STATUS.md, CHECKPOINTS.md, UNITS.csv, DECISIONS.md + folders).**Trigger**: workspace init, initialize workspace, workspace template, 初始化 workspace.**Use when**: 启动任何 pipeline run（必须先有 workspace 工件与目录骨架）。**Skip if**: workspace 已初始化且不希望覆盖既有文件（除非显式 `--overwrite`）。**Network**: none.**Guardrail**: 不要修改 `.codex/skills/workspace-init/assets/` 模板；默认不覆盖已有文件。

⭐1stars🔀0forks📁View on GitHub🕐Updated Jan 8, 2026
[Developer Tools]

When & Why to Use This Skill

The Workspace Init skill streamlines the setup of standardized project environments for Claude agents by automating the creation of essential artifact templates. It ensures every new pipeline run begins with a consistent directory structure and core tracking files—such as STATUS.md, CHECKPOINTS.md, and DECISIONS.md—to enhance project organization, traceability, and workflow efficiency.

Use Cases

  • Project Kickoff Automation: Instantly generate a professional workspace structure with predefined folders and markdown templates to eliminate manual setup time.
  • Standardizing Agent Workflows: Ensure that all agentic pipeline runs follow a uniform organizational schema, making it easier to monitor progress and audit results across different tasks.
  • Artifact-First Development: Automatically initialize critical documentation files like UNITS.csv and GOAL.md to enforce best practices in task tracking and decision logging from the very start.
nameworkspace-init
description|
**Trigger**workspace init, initialize workspace, workspace template, 初始化 workspace.
**Use when**启动任何 pipeline run（必须先有 workspace 工件与目录骨架）。
**Skip if**workspace 已初始化且不希望覆盖既有文件（除非显式 `--overwrite`）。
**Network**none.
**Guardrail**不要修改 `.codex/skills/workspace-init/assets/` 模板；默认不覆盖已有文件。

Workspace Init

Create an artifact-first workspace using the standard template under assets/workspace-template/.

This skill is intentionally simple and deterministic.

Input

  • Target workspace directory (usually the current working directory for the run).

Outputs

  • STATUS.md, CHECKPOINTS.md, UNITS.csv, DECISIONS.md
  • GOAL.md
  • queries.md
  • papers/, outline/, citations/, output/ (with placeholder files)

Workflow

  1. Create the target workspace directory if it does not exist.
  2. Copy the contents of assets/workspace-template/ into the workspace.
  3. Do not overwrite existing files unless explicitly requested; prefer merge/append when safe.
  4. Ensure the four core files exist: STATUS.md, UNITS.csv, CHECKPOINTS.md, DECISIONS.md.

Quality checklist

  • Workspace contains the template files and folders.
  • UNITS.csv is valid CSV with the required header.

Side effects

  • Allowed: create missing workspace files/directories.
  • Not allowed: modify the template under .codex/skills/workspace-init/assets/.

Script

Quick Start

  • python .codex/skills/workspace-init/scripts/run.py --help
  • python .codex/skills/workspace-init/scripts/run.py --workspace <workspace_dir>

All Options

  • --overwrite: allow overwriting existing files in the target workspace

Examples

  • Create a new workspace:
    • python .codex/skills/workspace-init/scripts/run.py --workspace workspaces/my-run
  • Re-init and overwrite template files (be careful):
    • python .codex/skills/workspace-init/scripts/run.py --workspace workspaces/my-run --overwrite

Troubleshooting

Issue: workspace already exists and files were not overwritten

Fix:

  • This is the default behavior. Re-run with --overwrite only if you want to replace template files.

Issue: you accidentally tried to use the repo root as a workspace

Fix:

  • Always use workspaces/<name>/ (the runner refuses to use the repo root).