create-plan

What this skill does

## 1. Gather task description

If `$ARGUMENTS` is empty, ask the user in plain text what they want to do. Do NOT use `AskUserQuestion` here — just output the question as regular text and wait for their free-form response.

## 2. Explore the project

Launch one Explore agent (medium thoroughness). Instruct it to use Glob, Grep, and Read exclusively — never Bash.

Explore the areas of the codebase relevant to the user's task description. Look for:
- Existing patterns, conventions, and architecture in the affected areas
- Related modules, types, and interfaces
- How similar functionality is structured elsewhere in the codebase
- How existing tests are written in the affected areas — test patterns, helpers, co-location conventions, naming conventions
- How similar features are tested (unit, e2e) to replicate the same approach

After the agent returns, present a concise summary to the user covering relevant code areas, patterns, architecture, and how the task fits into the existing codebase. This checkpoint lets the user correct misunderstandings before the interview.

## 3. Bootstrap plan.config.yml (if needed)

Check whether `.agents/plan.config.yml` exists:

- If it exists, read it and skip to the next step.
- If it does not exist, read `references/plan-config-file-contract.md` and follow its "Initial population" section to create the file. This involves asking the user about their testing, verification, and refactoring skills/commands.

## 4. Interview the user

Read `references/interview-guidelines.md` and follow its methodology to interview the user until you reach a complete, shared understanding of the task.

## 5. Targeted re-exploration

The interview likely revealed areas of the codebase not covered in the initial exploration — specific modules, patterns, edge cases, or integration points that came up in the user's answers.

Launch another Explore agent (medium thoroughness) targeting ONLY the new areas uncovered by the interview. Instruct it to use Glob, Grep, and Read exclusively — never Bash.

After the agent returns, briefly share any significant new findings with the user before proceeding.

## 6. Check for missing skills

This step is MANDATORY — never skip it. Must happen BEFORE generating plan files (new skills affect task file resources).

1. List every technology, library, framework, and domain involved in the task
2. For each one, check if there is an installed skill that covers it (scan skills listed in the system prompt)
3. For any technology/domain NOT covered by an installed skill, invoke `/find-skills` to search for a matching skill
4. Present results to the user and ask which (if any) to install. Install at project scope only — never global
5. Only after confirming all technologies are covered (or the user explicitly declines installing), proceed to the next step

## 7. Propose tasks

Read `references/task-decomposition-guidelines.md` and follow it to propose, present, and iterate on an ordered list of atomic tasks with the user until approved.

## 8. Generate plan files

Read the following references and generate the plan artifacts:

1. Read `references/plan-file-contract.md` — generate `plan.yml` and `state.yml`
2. Read `references/task-file-contract.md` — generate a task YAML file for each task in plan.yml, one at a time, in order

The generated plan must be detailed enough to be executed in a fresh session with zero prior context.

## 9. Commit the plan

Stage all generated files (`.agents/plans/<plan-id>/` and `.agents/plan.config.yml` if created) and commit with message: `chore(plan): <plan-name>` (e.g., `chore(plan): user-notifications`). Check if a commit-related skill is available and follow its conventions.

## 10. Final instructions

After the commit, instruct the user:

1. Run `/clear` to free context
2. Run `/execute-plan` (or `/execute-plan <plan-id>`) to begin execution

## Acceptance checklist

- [ ] User's task fully understood through exploration and interview
- [ ] Targeted re-exploration completed after interview
- [ ] `plan.config.yml` exists (created or pre-existing)
- [ ] Missing skills identified and offered via /find-skills
- [ ] Task breakdown proposed, iterated, and approved by user
- [ ] `plan.yml` generated with all fields populated from exploration and interview
- [ ] `state.yml` initialized
- [ ] Task files generated for every task in plan.yml
- [ ] All YAML content written in English
- [ ] Plan detailed enough to execute in a fresh session with zero context
- [ ] Plan files committed with `chore(plan): <plan-name>`
- [ ] User instructed to /clear and /execute-plan