[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M75QA5PZMACY07ZKPAFYTYBA":3,"skill-same:01M75QA5PZMACY07ZKPAFYTYBA":49},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":18,"publishedAt":19,"linkOnly":20,"markdownContent":21,"markdownBody":22,"frontMatter":23,"refName":28,"commitSha":29,"skillDirectory":30,"forksCount":14,"repositoryHtmlUrl":31,"repositoryHomepageUrl":6,"ownerHtmlUrl":32,"ownerBlogUrl":33,"ownerDescription":6,"updatedAt":34,"install":35,"resources":48},"01M75QA5PZMACY07ZKPAFYTYBA","speckit-companion-plan",null,"Companion plan — implementation plan with research & design artifacts","mictlanix\u002Fmbe-ui","mictlanix","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F703184?v=4","01M75Q1XD9477GXRKPM6JVVC11","Mictlanix","01M75Q1XDXKYX3VS9T3CS2XEFR",0,"MIT","https:\u002F\u002Fgithub.com\u002Fmictlanix\u002Fmbe-ui\u002Fblob\u002Fmain\u002F.claude\u002Fskills\u002Fspeckit-companion-plan\u002FSKILL.md",[],[],"2026-11-12 13:55:43",false,"---\nname: speckit-companion-plan\ndescription: Companion plan — implementation plan with research & design artifacts\ncompatibility: Requires spec-kit project structure with .specify\u002F directory\nmetadata:\n  author: github-spec-kit\n  source: companion:commands\u002Fspeckit.companion.plan.md\n---\n\n## User Input\n\n```text\n$ARGUMENTS\n```\n\n\u003C!-- speckit-companion:part step-start -->\n## Record this step's start, before anything else runs\n\nLet `\u003Cstep>`\u002F`\u003Cstatus>` be this command's phase and in-progress status: `specify`\u002F`specifying`, `plan`\u002F`planning`, `tasks`\u002F`tasking`, `implement`\u002F`implementing`. A step that mints its own feature directory (`specify`, `auto`) resolves it first, because `.specify\u002Ffeature.json` still points at the previous spec; every other step stamps at once, before any hook or node:\n\n```bash\npython3 .specify\u002Fextensions\u002Fcompanion\u002Fscripts\u002Fwrite-context.py --feature-dir \u003Cfeature_directory> --step \u003Cstep> --status \u003Cstatus> --kind start --by extension\n```\n\nAdd `--at \"\u003Cdispatch time>\"` when the dispatcher printed one. Run it, never hand-write it. A second start is refused, so running it is always safe.\n\u003C!-- \u002Fspeckit-companion:part step-start -->\n\n\u003C!-- speckit-companion:part command-spelling -->\n## Name every command the way this project registers it\n\nCommands are named in dot form throughout this body, `speckit.companion.plan`, because that is their canonical id, and without a leading slash, because the spelling a host actually registers is not always this one. Claude Code installs `\u002Fspeckit-companion-plan`. Look at how the commands are installed in this project, under the agent's own commands or skills directory, and use that spelling every time you name one to the developer or dispatch one yourself. A dotted name typed into a host that registered dashes resolves to nothing at all.\n\u003C!-- \u002Fspeckit-companion:part command-spelling -->\n\n\u003C!-- speckit-companion:part speckit-hooks -->\n## Stock spec-kit extension hooks\n\nOnly if `.specify\u002Fextensions.yml` lists entries under `hooks.before_\u003Cstep>` or `hooks.after_\u003Cstep>`, where `\u003Cstep>` is this command's phase, read `.specify\u002Fextensions\u002Fcompanion\u002Fcommands\u002Freference\u002Fspeckit-hooks.md` and follow it: the `before_` pass now, before any work below, and the `after_` pass once this command's work is reported. Otherwise skip this.\n\u003C!-- \u002Fspeckit-companion:part speckit-hooks -->\n\n\u003C!-- speckit-companion:part concise -->\n## The smallest thing that works\n\n**Stop at the first rung that holds:** does it need to exist; does this codebase already have it; does the platform or an installed dependency do it; can it be one line; only then, the minimum code. Fix the cause where every caller passes through. No interface with one implementation, no factory for one product, no scaffolding for later. Lean governs what you build, not how work is split.\n\n**Write it the way you would say it.** One idea per sentence, no em-dashes, no \"shall be capable of\", no section that says \"N\u002FA\". Then reread and cut: the sentence that restates the one before, the example longer than its rule, the clause defending a choice nobody challenged.\n\n**Never simplify away** validation at a trust boundary, error handling that prevents data loss, security, accessibility, or anything the spec asks for. **A corner cut on purpose** carries `\u002F\u002F simplified: \u003Cceiling>, \u003Cwhat to do when it binds>` in the code and one `concerns` entry in this step's capture.\n\u003C!-- \u002Fspeckit-companion:part concise -->\n\n## Outline\n\nProduce an implementation plan and its design artifacts in phases: load context → write `plan.md` (Summary, Constitution Check, Project Structure) → Phase 0 research → Phase 1 design (data model, contracts).\n\u003C!-- speckit-companion:phase gather -->\n\u003C!-- speckit-companion:node size-budget -->\n**Right-size this plan to the change.** Before anything else, read the recorded size from the spec's context: `.spec-context.json` → the `size` field (a missing value means `normal`). That size sets the budget for the steps below. **Apply it to them, omitting anything it says to skip.**\n\n- **`normal`**: produce the full plan and every design artifact exactly as the step describes. No trimming.\n- **`oversized`**: produce the same full plan and every design artifact, and open it with a short **Scale note**: one or two sentences naming how many files and areas the change spans and what a reader should watch for. Size never trims here. An oversized change gets *more* signposting, not less.\n- **`simple`**: produce a **lean** plan:\n  - `plan.md`: keep the **Summary** only. **Skip the Project Structure section** (the task list already names every file) and **skip the Constitution Check** unless there is a real violation to flag.\n  - **Skip `data-model.md`**; fold the one or two types into the plan's prose.\n  - Write the design rationale as a short **Key Decisions** note folded into `plan.md` (a few Decision\u002Fwhy lines), not a separate `research.md`, unless a decision genuinely needs its own page.\n  - Skip the plan's blocks (calls, code, states, screens).\n  - Generate `contracts\u002F` only if the feature exposes an interface a consumer or test codes against.\n\nThis budget governs every step that follows. Where a later step would produce something the budget skips, omit it. Do not produce it and then delete it.\n\u003C!-- \u002Fspeckit-companion:node size-budget -->\n\u003C!-- speckit-companion:node gather-context -->\n1. Read `.specify\u002Ffeature.json` for the feature directory. The step's start is already stamped, above. Load the feature spec (`\u003Cfeature_directory>\u002Fspec.md`, or `\u003Cshort-name>.spec.md` in a project written before this) and `.specify\u002Fmemory\u002Fconstitution.md` if present. Those are the inputs the plan must satisfy. **Read what `specify` recorded before you open a file.** `specify` writes what it read onto `.spec-context.json` under `context`: the code areas it looked at and the constraints it found there. Read those entries first. They name where the feature attaches, so open the files they point at instead of rediscovering them. They carry locations, not content, so you still open the files that matter, filling gaps in a map you were handed. If no `context` entries were recorded, investigate from scratch as below. **Plan against the words the person used.** The record holds the request this run started from under `request`, word for word. Read it beside the spec, and where the two differ, the request is what was asked.\n\nThen **investigate the codebase** to understand where this feature attaches: the patterns it must follow (state\u002Fstore, routing, persistence, component and test conventions) and the exact files it will touch.\n\n**Before you open a source file, run this and do exactly what it prints:**\n\n```bash\npython3 .specify\u002Fextensions\u002Fcompanion\u002Fscripts\u002Fdispatch-briefs.py --feature-dir \u003Cfeature_directory>\n```\n\nWhen it prints reader briefs, dispatch every one of them in a single message, unedited. That is not a judgement call: it holds in an auto run, for short features, and when specify already sent readers, because those mapped where the feature lands and these find the pattern to copy. When it prints `Working inline`, read the code yourself. Hand each worker the slice the load above already resolved for its area, so it reads code to fill the gaps rather than to relearn what is written down. Each worker returns a **distilled finding**: the pattern to copy, the concrete file paths, the conventions to match, and anything the code does that its slice does not account for. Never file contents. One area, or no subagent tool: read it yourself. Collect the findings as the research basis for the plan.\n\u003C!-- \u002Fspeckit-companion:node gather-context -->\n\u003C!-- \u002Fspeckit-companion:phase gather -->\n\u003C!-- speckit-companion:phase author -->\n\u003C!-- speckit-companion:node plan-doc -->\n2. Create `\u003Cfeature_directory>\u002Fplan.md` with these sections, in order. This is the full `normal`\u002F`oversized` shape and the **size budget above governs**: at `simple` size it keeps only the Summary and skips the rest unless genuinely needed. Lead each section with prose. Reserve `inline code` for real identifiers (paths, types, packages), not ordinary nouns: a sentence that is mostly code spans is a rewrite.\n   - **Summary**: 2–4 plain-language sentences giving the primary requirement plus the technical approach. If a stack choice genuinely isn't obvious from the codebase (a new language, a newly-added dependency, a non-default storage or test setup), name it in a sentence here. Otherwise don't restate the project's known stack.\n   - **Project Structure**: the concrete source layout this feature touches, as a short tree of real directories\u002Ffiles, plus a one-line **Structure Decision**. Use the actual paths; do not leave placeholder option-trees in the output. *(Skipped at `simple` size per the budget.)*\n\u003C!-- \u002Fspeckit-companion:node plan-doc -->\n\u003C!-- speckit-companion:node pick-blocks -->\n   **Add a block to `plan.md` only where the change needs one.** Skip this at `simple` size. Decide each row, then run the command with the names that apply, or `none`, and write what it prints into `plan.md`.\n\n   | Block | Write it when |\n   |---|---|\n   | `calls` | the change crosses functions or files |\n   | `code` | one line needs a note to be understood |\n   | `states` | the change adds or alters a lifecycle |\n   | `screens` | the change alters what a person sees |\n\n   ```bash\n   python3 .specify\u002Fextensions\u002Fcompanion\u002Fscripts\u002Fplan-blocks.py --feature-dir \u003Cfeature_directory> \u003Cnames>\n   ```\n\u003C!-- \u002Fspeckit-companion:node pick-blocks -->\n\u003C!-- \u002Fspeckit-companion:phase author -->\n\u003C!-- speckit-companion:phase check -->\n\u003C!-- speckit-companion:node constitution-check -->\n3. **Constitution Check**: add a `## Constitution Check` section to `plan.md` as a table: one row per constitution principle with a PASS \u002F justified-violation assessment. This is a gate before Phase 0 research, re-checked after Phase 1 design. If a violation is genuinely necessary, justify it in a short **Complexity Tracking** table (violation | why needed | simpler alternative rejected). Omit Complexity Tracking when there are no violations; ERROR on an unjustified gate failure.\n\u003C!-- \u002Fspeckit-companion:node constitution-check -->\n\u003C!-- \u002Fspeckit-companion:phase check -->\n\u003C!-- speckit-companion:phase wrap-up -->\n\u003C!-- speckit-companion:node side-files -->\n4. **Phase 0, research first.** Write `\u003Cfeature_directory>\u002Fresearch.md` before the Phase 1 docs, which build on its decisions. *(The size budget above governs: at `simple` size, fold the rationale into a short Key Decisions note in `plan.md` instead of a separate `research.md`.)* For each genuine unknown the plan leaves open (a stack or dependency choice the codebase doesn't already settle, an integration, or a significant design choice) record a short entry as **Decision** (what you chose) \u002F **Rationale** (why) \u002F **Alternatives considered** (what else, and why not). Resolve every `NEEDS CLARIFICATION` here.\n\n5. **Phase 1, design and contracts.** With research settled, generate the design artifacts the size budget keeps. They share no evolving state, so once `research.md` is on disk run `python3 .specify\u002Fextensions\u002Fcompanion\u002Fscripts\u002Fdispatch-briefs.py --feature-dir \u003Cfeature_directory> --docs` and do exactly what it prints: writer briefs are dispatched in a single message, unedited, however short the documents look; `Working inline` means you write them yourself.\n   - `\u003Cfeature_directory>\u002Fdata-model.md`: the entities this feature introduces or reshapes, with fields, relationships, validation rules drawn from the requirements, and any state transitions.\n   - `\u003Cfeature_directory>\u002Fcontracts\u002F`: the interface the feature exposes (API \u002F CLI \u002F schema, or a UI contract listing routes and the identifiers a consumer\u002Ftest codes against). **Copy every identifier from the spec's Verbatim Constraints exactly. Never rename, recase, pluralize, or invent an identifier the spec already pinned: those exact strings *are* the contract.** Skip the directory only when the feature exposes no interface at all.\n   After the documents return, re-check the Constitution Check against the final design.\n\n   **`design` closes after `contracts\u002F`, not after the last document you happened to write.** Record the `design` substep finish only once every Phase 1 artifact this size budget keeps is on disk.\n\n6. **Capture the plan's reasoning** so the *why* survives the session (best-effort; JSON when you can produce it, bare text when not; skip silently if `python3` is unavailable):\n   ```bash\n   python3 .specify\u002Fextensions\u002Fcompanion\u002Fscripts\u002Fwrite-context.py --feature-dir \u003Cfeature_directory> --step plan --batch '{\n     \"decisions\": [{\"decision\": \"\u003Cwhat you chose>\", \"why\": \"\u003Cwhy>\", \"rejected\": \"\u003Cthe alternative not taken>\"}],\n     \"step_summary\": {\"summary\": \"\u003Cone-line rollup>\", \"key_finding\": \"\u003Cthe most load-bearing thing you learned>\"},\n     \"set\": {\"approach\": \"\u003C2-3 sentence how-summary>\"}\n   }'\n   ```\n   Record one `decisions` entry per genuine choice from Phase 0; skip trivia. These are additive and de-duped, so re-running them never duplicates. **One call, not one per item.** `--batch` takes the whole volley as a single JSON object and applies each writer additively, so the shared context file is read and rewritten once instead of once per entry. Emit one `--batch`.\n\n**Output**: `\u003Cfeature_directory>\u002Fplan.md` plus `research.md`, `data-model.md`, and `contracts\u002F` when applicable.\n\u003C!-- \u002Fspeckit-companion:node side-files -->\n\u003C!-- speckit-companion:node handoff -->\n\u003C!-- speckit-companion:part timing -->\n## Timing: keep `.spec-context.json` honest\n\nRecord every boundary by **running the writer script**, never by editing `.spec-context.json`. The model is **finish-only**: one finish per task and per substep, timed from the previous one; never a `start`+`complete` pair. **One shell call per moment**: writes that happen together go in one call chained with `&&`, because every separate call is a turn that re-reads the whole session. **In a single-quoted `--batch '{…}'`, write an apostrophe as `'`**, or pass `--batch -` with the JSON on stdin; never debug the quoting by reading the script.\n\n- **Close your own step** as your last action, after any mandatory after-hook block. Specify already closed itself in its wrap-up; clarify and analyze use `--finish` instead. Implement ends at `implemented`; converge completes the spec.\n\n  ```bash\n  python3 .specify\u002Fextensions\u002Fcompanion\u002Fscripts\u002Fwrite-context.py --feature-dir \u003Cfeature_dir> --step \u003Cthis step> --advance --by ai\n  ```\n\n- **One finish per substep, the moment it ends, when the step runs on its own**; inside an auto run, skip them. Plan records `research` and `design`, tasks `generate`.\n\n  ```bash\n  python3 .specify\u002Fextensions\u002Fcompanion\u002Fscripts\u002Fwrite-context.py --feature-dir \u003Cfeature_dir> --step \u003Cstep> --substep \u003Cname> --finish --by ai\n  ```\n\n- **Close each wave the moment its last task is done**, in one call listing its tasks. It checks their boxes and times the wave as one unit. Never hand-edit a box; closing several waves at once is a defect the doctor reports.\n\n  ```bash\n  python3 .specify\u002Fextensions\u002Fcompanion\u002Fscripts\u002Fwrite-context.py --feature-dir \u003Cfeature_dir> --close-task \u003CT001,T002,…> --by ai --did \"\u003Cone line>\" --files \"\u003Cfiles>\"\n  ```\n\n  **A fanned-out worker appends only**, because two folders contend; the main agent folds each returned result with `--materialize`, one at a time:\n\n  ```bash\n  python3 .specify\u002Fextensions\u002Fcompanion\u002Fscripts\u002Fwrite-context.py --feature-dir \u003Cfeature_dir> --task \u003CTaskID> --kind complete --by ai --did \"\u003Cone line>\" --files \"\u003Cfiles>\" --append\n  ```\n\n- **Never write the next step's start.** The next command owns it.\n\u003C!-- \u002Fspeckit-companion:part timing -->\n\n**The next step is `tasks`.** Dispatch `speckit.companion.tasks \u003Cfeature_dir>`.\n\n\u003C!-- speckit-companion:part self-advance -->\n## After this step\n\nInside a Companion auto run, or when the input says `workflow engine step`, the orchestrator decides what runs next: skip this. Otherwise, once this step's work is done, read `.specify\u002Fextensions\u002Fcompanion\u002Fcommands\u002Freference\u002Fself-advance.md` and follow it.\n\u003C!-- \u002Fspeckit-companion:part self-advance -->\n\n**Pin the workflow identity in the same call that closes the step.** Record that this spec runs the **Companion** workflow, so the next dispatch is a Companion command and not a stock one. The shared writer defaults `workflow` to `speckit`, so without this the footer advance dispatches the stock successor. `--set` writes a plain field and appends no history, so it rides alongside `--advance`:\n\n```bash\npython3 .specify\u002Fextensions\u002Fcompanion\u002Fscripts\u002Fwrite-context.py --feature-dir \u003Cfeature_directory> --step \u003Cthis step> --advance --by ai --set workflow=companion\n```\n\nIdempotent, and a required deterministic write. Skip only if `python3` is genuinely unavailable. This replaces the bare `--advance` the timing rules describe; run one or the other, never both.\n\u003C!-- \u002Fspeckit-companion:node handoff -->\n\u003C!-- \u002Fspeckit-companion:phase wrap-up -->\n\n\u003C!-- speckit-companion:part orchestrator -->\n## Node hooks\n\nA project can attach its own work around this command's nodes in `.specify\u002Fcompanion.yml`. **Only if that file declares `commands.\u003Cthis-command>.hooks`**, read `.specify\u002Fextensions\u002Fcompanion\u002Fcommands\u002Freference\u002Fnode-hooks.md` and follow it. Otherwise there are no hooks: skip this and run the command as written.\n\u003C!-- \u002Fspeckit-companion:part orchestrator -->\n","## User Input\n\n```text\n$ARGUMENTS\n```\n\n\u003C!-- speckit-companion:part step-start -->\n## Record this step's start, before anything else runs\n\nLet `\u003Cstep>`\u002F`\u003Cstatus>` be this command's phase and in-progress status: `specify`\u002F`specifying`, `plan`\u002F`planning`, `tasks`\u002F`tasking`, `implement`\u002F`implementing`. A step that mints its own feature directory (`specify`, `auto`) resolves it first, because `.specify\u002Ffeature.json` still points at the previous spec; every other step stamps at once, before any hook or node:\n\n```bash\npython3 .specify\u002Fextensions\u002Fcompanion\u002Fscripts\u002Fwrite-context.py --feature-dir \u003Cfeature_directory> --step \u003Cstep> --status \u003Cstatus> --kind start --by extension\n```\n\nAdd `--at \"\u003Cdispatch time>\"` when the dispatcher printed one. Run it, never hand-write it. A second start is refused, so running it is always safe.\n\u003C!-- \u002Fspeckit-companion:part step-start -->\n\n\u003C!-- speckit-companion:part command-spelling -->\n## Name every command the way this project registers it\n\nCommands are named in dot form throughout this body, `speckit.companion.plan`, because that is their canonical id, and without a leading slash, because the spelling a host actually registers is not always this one. Claude Code installs `\u002Fspeckit-companion-plan`. Look at how the commands are installed in this project, under the agent's own commands or skills directory, and use that spelling every time you name one to the developer or dispatch one yourself. A dotted name typed into a host that registered dashes resolves to nothing at all.\n\u003C!-- \u002Fspeckit-companion:part command-spelling -->\n\n\u003C!-- speckit-companion:part speckit-hooks -->\n## Stock spec-kit extension hooks\n\nOnly if `.specify\u002Fextensions.yml` lists entries under `hooks.before_\u003Cstep>` or `hooks.after_\u003Cstep>`, where `\u003Cstep>` is this command's phase, read `.specify\u002Fextensions\u002Fcompanion\u002Fcommands\u002Freference\u002Fspeckit-hooks.md` and follow it: the `before_` pass now, before any work below, and the `after_` pass once this command's work is reported. Otherwise skip this.\n\u003C!-- \u002Fspeckit-companion:part speckit-hooks -->\n\n\u003C!-- speckit-companion:part concise -->\n## The smallest thing that works\n\n**Stop at the first rung that holds:** does it need to exist; does this codebase already have it; does the platform or an installed dependency do it; can it be one line; only then, the minimum code. Fix the cause where every caller passes through. No interface with one implementation, no factory for one product, no scaffolding for later. Lean governs what you build, not how work is split.\n\n**Write it the way you would say it.** One idea per sentence, no em-dashes, no \"shall be capable of\", no section that says \"N\u002FA\". Then reread and cut: the sentence that restates the one before, the example longer than its rule, the clause defending a choice nobody challenged.\n\n**Never simplify away** validation at a trust boundary, error handling that prevents data loss, security, accessibility, or anything the spec asks for. **A corner cut on purpose** carries `\u002F\u002F simplified: \u003Cceiling>, \u003Cwhat to do when it binds>` in the code and one `concerns` entry in this step's capture.\n\u003C!-- \u002Fspeckit-companion:part concise -->\n\n## Outline\n\nProduce an implementation plan and its design artifacts in phases: load context → write `plan.md` (Summary, Constitution Check, Project Structure) → Phase 0 research → Phase 1 design (data model, contracts).\n\u003C!-- speckit-companion:phase gather -->\n\u003C!-- speckit-companion:node size-budget -->\n**Right-size this plan to the change.** Before anything else, read the recorded size from the spec's context: `.spec-context.json` → the `size` field (a missing value means `normal`). That size sets the budget for the steps below. **Apply it to them, omitting anything it says to skip.**\n\n- **`normal`**: produce the full plan and every design artifact exactly as the step describes. No trimming.\n- **`oversized`**: produce the same full plan and every design artifact, and open it with a short **Scale note**: one or two sentences naming how many files and areas the change spans and what a reader should watch for. Size never trims here. An oversized change gets *more* signposting, not less.\n- **`simple`**: produce a **lean** plan:\n  - `plan.md`: keep the **Summary** only. **Skip the Project Structure section** (the task list already names every file) and **skip the Constitution Check** unless there is a real violation to flag.\n  - **Skip `data-model.md`**; fold the one or two types into the plan's prose.\n  - Write the design rationale as a short **Key Decisions** note folded into `plan.md` (a few Decision\u002Fwhy lines), not a separate `research.md`, unless a decision genuinely needs its own page.\n  - Skip the plan's blocks (calls, code, states, screens).\n  - Generate `contracts\u002F` only if the feature exposes an interface a consumer or test codes against.\n\nThis budget governs every step that follows. Where a later step would produce something the budget skips, omit it. Do not produce it and then delete it.\n\u003C!-- \u002Fspeckit-companion:node size-budget -->\n\u003C!-- speckit-companion:node gather-context -->\n1. Read `.specify\u002Ffeature.json` for the feature directory. The step's start is already stamped, above. Load the feature spec (`\u003Cfeature_directory>\u002Fspec.md`, or `\u003Cshort-name>.spec.md` in a project written before this) and `.specify\u002Fmemory\u002Fconstitution.md` if present. Those are the inputs the plan must satisfy. **Read what `specify` recorded before you open a file.** `specify` writes what it read onto `.spec-context.json` under `context`: the code areas it looked at and the constraints it found there. Read those entries first. They name where the feature attaches, so open the files they point at instead of rediscovering them. They carry locations, not content, so you still open the files that matter, filling gaps in a map you were handed. If no `context` entries were recorded, investigate from scratch as below. **Plan against the words the person used.** The record holds the request this run started from under `request`, word for word. Read it beside the spec, and where the two differ, the request is what was asked.\n\nThen **investigate the codebase** to understand where this feature attaches: the patterns it must follow (state\u002Fstore, routing, persistence, component and test conventions) and the exact files it will touch.\n\n**Before you open a source file, run this and do exactly what it prints:**\n\n```bash\npython3 .specify\u002Fextensions\u002Fcompanion\u002Fscripts\u002Fdispatch-briefs.py --feature-dir \u003Cfeature_directory>\n```\n\nWhen it prints reader briefs, dispatch every one of them in a single message, unedited. That is not a judgement call: it holds in an auto run, for short features, and when specify already sent readers, because those mapped where the feature lands and these find the pattern to copy. When it prints `Working inline`, read the code yourself. Hand each worker the slice the load above already resolved for its area, so it reads code to fill the gaps rather than to relearn what is written down. Each worker returns a **distilled finding**: the pattern to copy, the concrete file paths, the conventions to match, and anything the code does that its slice does not account for. Never file contents. One area, or no subagent tool: read it yourself. Collect the findings as the research basis for the plan.\n\u003C!-- \u002Fspeckit-companion:node gather-context -->\n\u003C!-- \u002Fspeckit-companion:phase gather -->\n\u003C!-- speckit-companion:phase author -->\n\u003C!-- speckit-companion:node plan-doc -->\n2. Create `\u003Cfeature_directory>\u002Fplan.md` with these sections, in order. This is the full `normal`\u002F`oversized` shape and the **size budget above governs**: at `simple` size it keeps only the Summary and skips the rest unless genuinely needed. Lead each section with prose. Reserve `inline code` for real identifiers (paths, types, packages), not ordinary nouns: a sentence that is mostly code spans is a rewrite.\n   - **Summary**: 2–4 plain-language sentences giving the primary requirement plus the technical approach. If a stack choice genuinely isn't obvious from the codebase (a new language, a newly-added dependency, a non-default storage or test setup), name it in a sentence here. Otherwise don't restate the project's known stack.\n   - **Project Structure**: the concrete source layout this feature touches, as a short tree of real directories\u002Ffiles, plus a one-line **Structure Decision**. Use the actual paths; do not leave placeholder option-trees in the output. *(Skipped at `simple` size per the budget.)*\n\u003C!-- \u002Fspeckit-companion:node plan-doc -->\n\u003C!-- speckit-companion:node pick-blocks -->\n   **Add a block to `plan.md` only where the change needs one.** Skip this at `simple` size. Decide each row, then run the command with the names that apply, or `none`, and write what it prints into `plan.md`.\n\n   | Block | Write it when |\n   |---|---|\n   | `calls` | the change crosses functions or files |\n   | `code` | one line needs a note to be understood |\n   | `states` | the change adds or alters a lifecycle |\n   | `screens` | the change alters what a person sees |\n\n   ```bash\n   python3 .specify\u002Fextensions\u002Fcompanion\u002Fscripts\u002Fplan-blocks.py --feature-dir \u003Cfeature_directory> \u003Cnames>\n   ```\n\u003C!-- \u002Fspeckit-companion:node pick-blocks -->\n\u003C!-- \u002Fspeckit-companion:phase author -->\n\u003C!-- speckit-companion:phase check -->\n\u003C!-- speckit-companion:node constitution-check -->\n3. **Constitution Check**: add a `## Constitution Check` section to `plan.md` as a table: one row per constitution principle with a PASS \u002F justified-violation assessment. This is a gate before Phase 0 research, re-checked after Phase 1 design. If a violation is genuinely necessary, justify it in a short **Complexity Tracking** table (violation | why needed | simpler alternative rejected). Omit Complexity Tracking when there are no violations; ERROR on an unjustified gate failure.\n\u003C!-- \u002Fspeckit-companion:node constitution-check -->\n\u003C!-- \u002Fspeckit-companion:phase check -->\n\u003C!-- speckit-companion:phase wrap-up -->\n\u003C!-- speckit-companion:node side-files -->\n4. **Phase 0, research first.** Write `\u003Cfeature_directory>\u002Fresearch.md` before the Phase 1 docs, which build on its decisions. *(The size budget above governs: at `simple` size, fold the rationale into a short Key Decisions note in `plan.md` instead of a separate `research.md`.)* For each genuine unknown the plan leaves open (a stack or dependency choice the codebase doesn't already settle, an integration, or a significant design choice) record a short entry as **Decision** (what you chose) \u002F **Rationale** (why) \u002F **Alternatives considered** (what else, and why not). Resolve every `NEEDS CLARIFICATION` here.\n\n5. **Phase 1, design and contracts.** With research settled, generate the design artifacts the size budget keeps. They share no evolving state, so once `research.md` is on disk run `python3 .specify\u002Fextensions\u002Fcompanion\u002Fscripts\u002Fdispatch-briefs.py --feature-dir \u003Cfeature_directory> --docs` and do exactly what it prints: writer briefs are dispatched in a single message, unedited, however short the documents look; `Working inline` means you write them yourself.\n   - `\u003Cfeature_directory>\u002Fdata-model.md`: the entities this feature introduces or reshapes, with fields, relationships, validation rules drawn from the requirements, and any state transitions.\n   - `\u003Cfeature_directory>\u002Fcontracts\u002F`: the interface the feature exposes (API \u002F CLI \u002F schema, or a UI contract listing routes and the identifiers a consumer\u002Ftest codes against). **Copy every identifier from the spec's Verbatim Constraints exactly. Never rename, recase, pluralize, or invent an identifier the spec already pinned: those exact strings *are* the contract.** Skip the directory only when the feature exposes no interface at all.\n   After the documents return, re-check the Constitution Check against the final design.\n\n   **`design` closes after `contracts\u002F`, not after the last document you happened to write.** Record the `design` substep finish only once every Phase 1 artifact this size budget keeps is on disk.\n\n6. **Capture the plan's reasoning** so the *why* survives the session (best-effort; JSON when you can produce it, bare text when not; skip silently if `python3` is unavailable):\n   ```bash\n   python3 .specify\u002Fextensions\u002Fcompanion\u002Fscripts\u002Fwrite-context.py --feature-dir \u003Cfeature_directory> --step plan --batch '{\n     \"decisions\": [{\"decision\": \"\u003Cwhat you chose>\", \"why\": \"\u003Cwhy>\", \"rejected\": \"\u003Cthe alternative not taken>\"}],\n     \"step_summary\": {\"summary\": \"\u003Cone-line rollup>\", \"key_finding\": \"\u003Cthe most load-bearing thing you learned>\"},\n     \"set\": {\"approach\": \"\u003C2-3 sentence how-summary>\"}\n   }'\n   ```\n   Record one `decisions` entry per genuine choice from Phase 0; skip trivia. These are additive and de-duped, so re-running them never duplicates. **One call, not one per item.** `--batch` takes the whole volley as a single JSON object and applies each writer additively, so the shared context file is read and rewritten once instead of once per entry. Emit one `--batch`.\n\n**Output**: `\u003Cfeature_directory>\u002Fplan.md` plus `research.md`, `data-model.md`, and `contracts\u002F` when applicable.\n\u003C!-- \u002Fspeckit-companion:node side-files -->\n\u003C!-- speckit-companion:node handoff -->\n\u003C!-- speckit-companion:part timing -->\n## Timing: keep `.spec-context.json` honest\n\nRecord every boundary by **running the writer script**, never by editing `.spec-context.json`. The model is **finish-only**: one finish per task and per substep, timed from the previous one; never a `start`+`complete` pair. **One shell call per moment**: writes that happen together go in one call chained with `&&`, because every separate call is a turn that re-reads the whole session. **In a single-quoted `--batch '{…}'`, write an apostrophe as `'`**, or pass `--batch -` with the JSON on stdin; never debug the quoting by reading the script.\n\n- **Close your own step** as your last action, after any mandatory after-hook block. Specify already closed itself in its wrap-up; clarify and analyze use `--finish` instead. Implement ends at `implemented`; converge completes the spec.\n\n  ```bash\n  python3 .specify\u002Fextensions\u002Fcompanion\u002Fscripts\u002Fwrite-context.py --feature-dir \u003Cfeature_dir> --step \u003Cthis step> --advance --by ai\n  ```\n\n- **One finish per substep, the moment it ends, when the step runs on its own**; inside an auto run, skip them. Plan records `research` and `design`, tasks `generate`.\n\n  ```bash\n  python3 .specify\u002Fextensions\u002Fcompanion\u002Fscripts\u002Fwrite-context.py --feature-dir \u003Cfeature_dir> --step \u003Cstep> --substep \u003Cname> --finish --by ai\n  ```\n\n- **Close each wave the moment its last task is done**, in one call listing its tasks. It checks their boxes and times the wave as one unit. Never hand-edit a box; closing several waves at once is a defect the doctor reports.\n\n  ```bash\n  python3 .specify\u002Fextensions\u002Fcompanion\u002Fscripts\u002Fwrite-context.py --feature-dir \u003Cfeature_dir> --close-task \u003CT001,T002,…> --by ai --did \"\u003Cone line>\" --files \"\u003Cfiles>\"\n  ```\n\n  **A fanned-out worker appends only**, because two folders contend; the main agent folds each returned result with `--materialize`, one at a time:\n\n  ```bash\n  python3 .specify\u002Fextensions\u002Fcompanion\u002Fscripts\u002Fwrite-context.py --feature-dir \u003Cfeature_dir> --task \u003CTaskID> --kind complete --by ai --did \"\u003Cone line>\" --files \"\u003Cfiles>\" --append\n  ```\n\n- **Never write the next step's start.** The next command owns it.\n\u003C!-- \u002Fspeckit-companion:part timing -->\n\n**The next step is `tasks`.** Dispatch `speckit.companion.tasks \u003Cfeature_dir>`.\n\n\u003C!-- speckit-companion:part self-advance -->\n## After this step\n\nInside a Companion auto run, or when the input says `workflow engine step`, the orchestrator decides what runs next: skip this. Otherwise, once this step's work is done, read `.specify\u002Fextensions\u002Fcompanion\u002Fcommands\u002Freference\u002Fself-advance.md` and follow it.\n\u003C!-- \u002Fspeckit-companion:part self-advance -->\n\n**Pin the workflow identity in the same call that closes the step.** Record that this spec runs the **Companion** workflow, so the next dispatch is a Companion command and not a stock one. The shared writer defaults `workflow` to `speckit`, so without this the footer advance dispatches the stock successor. `--set` writes a plain field and appends no history, so it rides alongside `--advance`:\n\n```bash\npython3 .specify\u002Fextensions\u002Fcompanion\u002Fscripts\u002Fwrite-context.py --feature-dir \u003Cfeature_directory> --step \u003Cthis step> --advance --by ai --set workflow=companion\n```\n\nIdempotent, and a required deterministic write. Skip only if `python3` is genuinely unavailable. This replaces the bare `--advance` the timing rules describe; run one or the other, never both.\n\u003C!-- \u002Fspeckit-companion:node handoff -->\n\u003C!-- \u002Fspeckit-companion:phase wrap-up -->\n\n\u003C!-- speckit-companion:part orchestrator -->\n## Node hooks\n\nA project can attach its own work around this command's nodes in `.specify\u002Fcompanion.yml`. **Only if that file declares `commands.\u003Cthis-command>.hooks`**, read `.specify\u002Fextensions\u002Fcompanion\u002Fcommands\u002Freference\u002Fnode-hooks.md` and follow it. Otherwise there are no hooks: skip this and run the command as written.\n\u003C!-- \u002Fspeckit-companion:part orchestrator -->\n",{"name":5,"metadata":24,"description":7,"compatibility":27},{"author":25,"source":26},"github-spec-kit","companion:commands\u002Fspeckit.companion.plan.md","Requires spec-kit project structure with .specify\u002F directory","main","76d33ff49e8de1e5f77412aeba2d7e5602e442ed",".claude\u002Fskills\u002Fspeckit-companion-plan","https:\u002F\u002Fgithub.com\u002Fmictlanix\u002Fmbe-ui","https:\u002F\u002Fgithub.com\u002Fmictlanix","https:\u002F\u002Fmictlanix.com","2026-11-15 04:02:27",{"source":8,"skillName":5,"commands":36,"prompt":46,"zipAvailable":47},[37,40,43],{"tool":38,"command":39},"npx","npx skills add mictlanix\u002Fmbe-ui --skill speckit-companion-plan",{"tool":41,"command":42},"bunx","bunx skills add mictlanix\u002Fmbe-ui --skill speckit-companion-plan",{"tool":44,"command":45},"pnpm","pnpm dlx skills add mictlanix\u002Fmbe-ui --skill speckit-companion-plan","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fmictlanix\u002Fmbe-ui\u002Fblob\u002Fmain\u002F.claude\u002Fskills\u002Fspeckit-companion-plan\u002FSKILL.md",true,[],[50,57,62,69,76,83],{"skillNo":51,"name":52,"nameZh":6,"description":53,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":54,"categories":55,"keywords":56,"publishedAt":19},"01M75QCZHHB42Q7KJTZHQZXZ77","speckit-wireframes-draft","Draw low-fi wireframes for every screen and state the spec describes","https:\u002F\u002Fgithub.com\u002Fmictlanix\u002Fmbe-ui\u002Fblob\u002Fmain\u002F.specify\u002Fextensions\u002Fwireframes\u002F.specify-dev\u002Fagent-commands\u002Fclaude\u002Fspeckit-wireframes-draft\u002FSKILL.md",[],[],{"skillNo":58,"name":52,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":59,"categories":60,"keywords":61,"publishedAt":19},"01M75QCXRSD7HM7AFZH4HA9E6S","https:\u002F\u002Fgithub.com\u002Fmictlanix\u002Fmbe-ui\u002Fblob\u002Fmain\u002F.claude\u002Fskills\u002Fspeckit-wireframes-draft\u002FSKILL.md",[],[],{"skillNo":63,"name":64,"nameZh":6,"description":65,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":66,"categories":67,"keywords":68,"publishedAt":19},"01M75QCVS17DXXBTQ8DE2SSXVR","speckit-taskstoissues","Convert existing tasks into actionable, dependency-ordered GitHub issues for the feature based on available design artifacts.","https:\u002F\u002Fgithub.com\u002Fmictlanix\u002Fmbe-ui\u002Fblob\u002Fmain\u002F.claude\u002Fskills\u002Fspeckit-taskstoissues\u002FSKILL.md",[],[],{"skillNo":70,"name":71,"nameZh":6,"description":72,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":73,"categories":74,"keywords":75,"publishedAt":19},"01M75QCS3M02XD4PW58EXS6458","speckit-tasks","Generate an actionable, dependency-ordered tasks.md for the feature based on available design artifacts.","https:\u002F\u002Fgithub.com\u002Fmictlanix\u002Fmbe-ui\u002Fblob\u002Fmain\u002F.claude\u002Fskills\u002Fspeckit-tasks\u002FSKILL.md",[],[],{"skillNo":77,"name":78,"nameZh":6,"description":79,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":80,"categories":81,"keywords":82,"publishedAt":19},"01M75QCP9NASXGDNYZF6XYJZBD","speckit-specify","Create or update the feature specification from a natural language feature description.","https:\u002F\u002Fgithub.com\u002Fmictlanix\u002Fmbe-ui\u002Fblob\u002Fmain\u002F.claude\u002Fskills\u002Fspeckit-specify\u002FSKILL.md",[],[],{"skillNo":84,"name":85,"nameZh":6,"description":86,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":87,"categories":88,"keywords":89,"publishedAt":19},"01M75QCKBPS4K60R4YPRQ8HBJ9","speckit-plan","Execute the implementation planning workflow using the plan template to generate design artifacts.","https:\u002F\u002Fgithub.com\u002Fmictlanix\u002Fmbe-ui\u002Fblob\u002Fmain\u002F.claude\u002Fskills\u002Fspeckit-plan\u002FSKILL.md",[],[]]