git:20260420.e5e8b79 to git:20260723.1db5b32

- # Create Plan

-

- Create a detailed implementation plan before any coding begins. The plan is a markdown file with checkboxes that `/implement-plan` will later execute and update.

-

- ## Arguments

-

- The user provides a description of the work to be done. For example:

- - `/create-plan Add Google OAuth to the login flow`

- - `/create-plan Migrate user table to new schema`

- - `/create-plan Update API rate limiting across all services`

-

- ## Steps

-

- ### 1. Determine Scope

-

- Based on the user's description, determine which repos are involved:

-

- 1. Read `repos/repos.yaml` to get the list of repos/folders

- 2. Identify which repos are relevant to the work

- 3. Ask the user to clarify scope only if it's genuinely ambiguous

-

- ### 2. Generate the Filename

-

- Format: `YYYYMMDD-<plan-name>.plan.md`

-

- - Use today's date as the prefix (e.g., `20260409`)

- - Create a short, descriptive plan name from the description:

- - Lowercase, hyphen-separated

- - 2-4 words maximum

- - Example: "Add Google OAuth to login" -> `20260409-google-oauth.plan.md`

-

- ### 3. Gather Context

-

- Use the explorer agent pattern (read-only) to gather relevant context from the repos in scope:

-

- 1. Read `repos/repos.md` for an overview

- 2. For each repo in scope, identify and read:

- - API endpoints or routes relevant to the work

- - Type definitions, interfaces, or schemas involved

- - Key files that will need changes

- - Any existing tests for the affected code

- 3. Distill this into compact summaries — don't paste entire files

-

- ### 4. Write the Plan File

-

- Create `_plans/YYYYMMDD-<plan-name>.plan.md` with this structure:

-

- ```markdown

- ---

- status: draft

- repos: [<repo-names>]

- created: <today's date>

- ---

-

- # Plan: <descriptive title>

-

- ## Context

- <1-3 sentences: what needs to happen and why>

-

- ## Repo Context

- <embedded API surfaces, types, schemas from relevant repos>

-

- ### <repo-name>

- - <key files with brief descriptions>

- - <exported types or endpoints relevant to this work>

- - <architectural constraints or patterns to follow>

-

- (repeat for each repo in scope)

-

- ## Steps

-

- - [ ] Step 1: <brief title>

- - **Task**: <detailed explanation of what to do>

- - **Files**: <list of files to create or modify, with full paths>

- - **Pseudocode**: <high-level pseudocode, NOT real code>

-

- - [ ] Step 2: <brief title>

- - **Task**: <detailed explanation>

- - **Files**: <file list>

- - **Pseudocode**: <pseudocode>

-

- (continue for all steps)

-

- - [ ] Step N: Validate

- - **Task**: Run the application and tests, verify everything works

- - **Files**: <test files>

- ```

-

- ### 5. Plan Quality Checklist

-

- Before finishing, verify the plan:

- - [ ] Steps are ordered by dependency (do X before Y if Y depends on X)

- - [ ] Each step is small enough to implement and verify independently

- - [ ] Pseudocode is used, not real code — implementation details are for `/implement-plan`

- - [ ] Files listed actually exist (or are clearly marked as "new file")

- - [ ] A validation step exists at the end

- - [ ] Any user intervention points are called out

-

- ### 6. Report

-

- Tell the user:

- - The plan file path

- - A brief summary of the steps

- - Which repos are in scope

- - Suggested next step: "Run `/implement-plan _plans/<filename>` when ready to build."

-

- ## Notes

-

- - Always read from repos to gather real context — don't fabricate API surfaces or types

- - If a repo in scope has no code yet, note that in the context section

- - Keep it simple — avoid over-architecture. The plan should be the simplest path to done.

- - Use pseudocode only, not real code

- - Call out any points where user input or decisions are needed

- - Plans are tracked in git — they're workspace artifacts

- - Review the plan with the user before they run `/implement-plan`