Use when the user wants to start working on a task, ticket, or feature. Triggered by: ticket URLs (Jira, GitHub Issues, Linear, etc.), task descriptions, or requests like 'work on this', 'implement X', 'fix X', 'これをすすめて', 'これやって'. IMPORTANT: Before creating a new workspace, ALWAYS run /workspace-list first to check if a workspace already exists for the same ticket/task. If one exists, use /workspace-execute or /workspace-show-status instead. Creates workspace with README, clones repos, and plans TODO items via agents.
Instalar com Codex ou Claude Copie este prompt, cole no Codex, Claude ou outro assistente e deixe que ele revise a página da skill e instale para você.
Um comando direto ignora o prompt de revisão. Verifique a origem antes de executá-lo.
Use when the user wants to start working on a task, ticket, or feature. Triggered by: ticket URLs (Jira, GitHub Issues, Linear, etc.), task descriptions, or requests like 'work on this', 'implement X', 'fix X', 'これをすすめて', 'これやって'. IMPORTANT: Before creating a new workspace, ALWAYS run /workspace-list first to check if a workspace already exists for the same ticket/task. If one exists, use /workspace-execute or /workspace-show-status instead. Creates workspace with README, clones repos, and plans TODO items via agents.
workspace-init
Overview
This skill initializes a working environment for development tasks. It orchestrates:
Arguments may also be natural language (e.g., "implement retry logic in github.com/org/api")
If $ARGUMENTS is empty or missing required information, use AskUserQuestion to gather it.
--interactive flag: When present, TODO planning runs in the foreground with user checkpoints. Planners run sequentially (not in parallel) so the user can review each one. The reviewer step is skipped since the user already approved during planning. When absent, the default autonomous behavior is used.
Steps
1. Understand the Task Requirements
Before running the setup scripts, ensure you have:
Task type (feature, bugfix, research, etc.)
Brief description
Target repository path(s) in org/repo format (e.g., github.com/sters/ai-workspace)
Ticket ID (optional)
Note: Base branch is automatically detected from the remote default (main/master). You don't need to specify it.
Alias syntax: If you need to use the same repository multiple times (e.g., separate PRs for dev/prod environments), use the :alias suffix:
github.com/org/repo:dev → Creates worktree at github.com/org/repo___dev/
github.com/org/repo:prod → Creates worktree at github.com/org/repo___prod/
# Basic usage
./.claude/scripts/setup-repository.sh feature-user-auth-20260206 github.com/org/repo
# Override base branch (when user explicitly specifies)
BASE_BRANCH=develop ./.claude/scripts/setup-repository.sh feature-user-auth-20260206 github.com/org/repo
# With alias (for multiple worktrees from same repo)
./.claude/scripts/setup-repository.sh feature-user-auth-20260206 github.com/org/repo:dev
The script will:
Clone the repository if not already cloned (to repositories/ directory)
Update the repository with git fetch --all --prune
Auto-detect the base branch from remote default
Create a git worktree in the workspace with a new feature branch
After running the script, update the README.md Repositories section:
After setup completes, update the generated README.md with:
Clear objective description
Context and background
Requirements and acceptance criteria
Related resources (issues, docs, etc.)
IMPORTANT: Write only confirmed facts, never assumptions or guesses.
Only include information that is explicitly provided by the user or retrieved from linked resources
If essential information is missing (objective, requirements, context), use AskUserQuestion to ask the user
Do NOT fill in placeholder text or make up details
Leave sections empty with <!-- TBD --> if information is not available and user cannot provide it
Read linked resources (Jira tickets, PRs, documentation) using appropriate tools to get accurate details
DO NOT explore or analyze the repository codebase at this step. Repository analysis is done by the TODO planner agents in the next step. This step focuses only on capturing task requirements from the user and linked resources.
This README is the source of truth that the TODO planner agents will read. Accuracy is critical.
4. Task Type Branching
After filling in README.md, check the task type to determine the next steps:
If **Task Type** is research, investigation, documentation, or design-doc → Skip Steps 5-7 (TODO planning is not needed). Go directly to Step 8 (Commit).
For all other task types (feature, bugfix, etc.) → Continue with Step 5 below.
Why skip? These task types use the workspace-researcher agent (invoked via /workspace-execute) which reads directly from README.md. The agent explores repositories and produces a document (research report, design doc, etc.) as its output. Creating TODO items would cause duplicate work — the planner would explore the codebase to create TODOs, then the researcher would explore the same codebase again.
Guideline: Use this path for tasks whose primary output is a document based on cross-repository exploration, not code changes.
5. Call workspace-repo-todo-planner for Each Repository
For each repository in the workspace, invoke the workspace-repo-todo-planner agent.
Run multiple reviewers in parallel for all repositories.
What the agent does (defined in agent, not by prompt):
Validates each TODO item for specificity, actionability, and alignment
Marks unclear items with [NEEDS_CLARIFICATION] tags
Returns a summary of issues (BLOCKING and UNCLEAR)
After all reviewers complete:
Collect results from all reviewers
If any BLOCKING issues exist:
Use AskUserQuestion to ask the user for clarification
Update the TODO files with the answers
Re-run reviewers if significant changes were made
If only UNCLEAR issues exist:
Present them to the user and ask whether to proceed or clarify
If no issues (STATUS: CLEAN for all repos):
Proceed to commit
8. Commit Workspace Files
After review completes (and any clarifications are resolved), or directly after Step 3 for research tasks, commit the workspace files:
# For research/investigation tasks (no TODO files):
./.claude/scripts/commit-workspace-snapshot.sh {workspace-name} "Initialize research workspace"# For standard tasks (with TODO files):
./.claude/scripts/commit-workspace-snapshot.sh {workspace-name} "Add TODO items for all repositories"
9. Display Workspace Files
After committing, display the relative paths of all workspace files for the user:
List all TODO files that were created (one per repository).
Example Usage
Example 1: Single Repository (Feature)
User: Initialize a workspace for user authentication feature in github.com/org/repo
Assistant:
1. [Runs setup-workspace.sh] → Creates workspace/feature-user-auth-20260206
2. [Runs setup-repository.sh] → Clones repo, creates worktree
3. [Updates README.md with task details]
4. [Task Type: feature → Continue to Step 5]
5. [Calls workspace-repo-todo-planner] → Creates TODO-repo.md
6. [Calls workspace-todo-coordinator] → Optimizes (single repo, minimal changes)
7. [Calls workspace-repo-todo-reviewer] → Validates TODO items
8. [Commits workspace files]
9. [Displays workspace files]
Done! Ready to execute with /workspace-execute.
Example 2: Multiple Repositories (Feature)
User: Initialize a workspace for adding product IDs to cart, involving:
- github.com/org/proto, github.com/org/api, github.com/org/frontend
Assistant:
1. [Runs setup-workspace.sh] → Creates workspace/feature-product-ids-20260206
2. [Runs setup-repository.sh 3 times] → Adds 3 repos
3. [Updates README.md with task details]
4. [Task Type: feature → Continue to Step 5]
5. [Calls 3 workspace-repo-todo-planner agents in parallel] → Creates TODO files
6. [Calls workspace-todo-coordinator] → Optimizes for parallel execution
7. [Calls 3 workspace-repo-todo-reviewer agents in parallel] → Validates TODOs
8. [Commits workspace files]
9. [Displays workspace files]
Done! Ready to execute with /workspace-execute.
Example 3: Research Task (Skips TODO Planning)
User: Investigate how authentication works across github.com/org/api and github.com/org/gateway
Assistant:
1. [Runs setup-workspace.sh] → Creates workspace/research-auth-flow-20260206
2. [Runs setup-repository.sh 2 times] → Adds 2 repos
3. [Updates README.md with research objectives]
4. [Task Type: research → Skip Steps 5-7]
8. [Commits workspace files]
9. [Displays workspace files]
Done! Ready to execute with /workspace-execute.
After Completion
After committing and displaying workspace files, report directly to the user:
Workspace name and task type
Number of repositories and TODO items created
Then use AskUserQuestion to let the user choose the next action:
AskUserQuestion:question:"What would you like to do next?"header:"Next step"options:-label:"/workspace-execute (Recommended)"description:"Start executing TODO items in the workspace"-label:"/workspace-update-todo"description:"Modify TODO items before execution"-label:"/workspace-show-status"description:"Check workspace status"
After the user selects an option, invoke the corresponding skill with the workspace name as argument. Do NOT invoke other skills automatically before asking.
Notes
Base branch is auto-detected from remote default unless explicitly specified
setup-workspace.sh creates the workspace directory and README.md template
setup-repository.sh handles cloning, updating, and worktree creation
TODO files are created by planner agents, not by the setup scripts
Workspace naming convention: {task-type}-{ticket-id}-{description}-{date} or {task-type}-{description}-{date}
Alias syntax: Use repo:alias to create multiple worktrees from the same repository (e.g., github.com/org/repo:dev)
For single repository workspaces, the coordinator step is still run but makes minimal changes
This skill runs inline and waits for background agents (planner → coordinator → reviewer) to complete before returning. This allows user interaction (AskUserQuestion) during the review step if clarifications are needed.
Interactive mode (--interactive): Planners run sequentially in the foreground with Mode: interactive, enabling two user checkpoints per repository (approach approval + draft review). The reviewer step (Step 7) is skipped since the user already approved during planning. The coordinator still runs autonomously. run_in_background: false still provides context isolation (sub-agent context doesn't leak to parent).
