[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M6C7F05XGSEFED79NQHT2QBZ":3,"skill-same:01M6C7F05XGSEFED79NQHT2QBZ":52},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":9,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":15,"categories":16,"keywords":17,"publishedAt":26,"linkOnly":27,"markdownContent":28,"markdownBody":29,"frontMatter":30,"refName":31,"commitSha":32,"skillDirectory":33,"forksCount":34,"repositoryHtmlUrl":35,"repositoryHomepageUrl":6,"ownerHtmlUrl":36,"ownerBlogUrl":6,"ownerDescription":6,"updatedAt":37,"install":38,"resources":51},"01M6C7F05XGSEFED79NQHT2QBZ","kspec-plan",null,"Translate approved plans into specs and tasks. Import structured documents or create incrementally. Plans persist as durable artifacts with audit trail.","lepahc\u002Fkynetic-spec","lepahc","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F255431765?v=4","01M6C7E6Z0C8SE1X6PJ2F9Q1CX","01M6C7E744QKNYBVZ7KV7Z69GF",1,"MIT","https:\u002F\u002Fgithub.com\u002Flepahc\u002Fkynetic-spec\u002Fblob\u002Fmain\u002F.agents\u002Fskills\u002Fkspec-plan\u002FSKILL.md",[],[18,19,20,21,22,23,24,25],"plan","kspec plan","translate","documents","tasks","create","artifacts","audit","2026-11-10 10:12:30",false,"---\nname: kspec-plan\ndescription: Translate approved plans into specs and tasks. Import structured\n  documents or create incrementally. Plans persist as durable artifacts with\n  audit trail.\n---\n\u003C!-- kspec-managed -->\n# Plan to Spec Translation\n\nTranslate approved plans into specs and tasks. Plans are durable artifacts — they persist in the shadow branch, link to derived work, and provide auditable planning history across sessions.\n\n## When to Use\n\n- After plan mode approval — turning an approved plan into trackable specs and tasks\n- Creating specs for new features or multi-spec capabilities\n- Translating design documents into the spec hierarchy\n\n**Not for:** Raw ideas (use `kspec inbox add`), single spec creation (use `$kspec-writing-specs`), or triage (use `$kspec-triage`).\n\n## Two Paths\n\n### Import Path (Recommended for 3+ Specs)\n\nWrite a structured markdown document, import it as a durable plan record, iterate as needed, then derive specs\u002Ftasks when the plan is ready.\n\n```bash\nkspec plan import .\u002Fplan.md --dry-run                           # Preview plan record\nkspec plan import .\u002Fplan.md --module @target-module             # Store plan (+ optional module)\nkspec plan import .\u002Fedited.md --into @plan-ref                  # Re-import edits into existing plan\nkspec plan set @plan-ref --status approved                      # Approve when ready\nkspec plan derive @plan-ref --module @target-module             # Materialize specs\u002Ftasks\n```\n\n### Manual Path (1-2 Specs)\n\nCreate plan record and specs incrementally via CLI.\n\n```bash\nkspec plan add --title \"Plan Title\" --content \"Description\" --status approved\nkspec item add --under @parent --title \"Feature\" --type feature --slug slug\nkspec item ac add @slug --given \"...\" --when \"...\" --then \"...\"\nkspec derive @slug\n```\n\n### When to Use Which\n\n| Situation                                | Path              |\n| ---------------------------------------- | ----------------- |\n| Plan mode just approved, complex feature | Import            |\n| Adding a requirement to existing feature | Manual            |\n| Multiple related specs with parent\u002Fchild | Import            |\n| Quick bug fix that needs spec coverage   | Manual            |\n| Translating design doc with many specs   | Import            |\n| Iterating on previously imported plan    | Import (`--into`) |\n\n## Three-Phase Workflow\n\n### Phase 1: Design\n\nAlways start here — never skip research.\n\nIf the project defines a plan-design workflow (for example `@spec-plan-design`), start it now:\n\n```bash\nkspec workflow start @spec-plan-design\n```\n\nOtherwise follow these steps directly:\n\n1. **Explore** — Read relevant code, understand current state\n2. **Clarify** — Identify ambiguities, resolve with user\n3. **Design** — Spec structure, AC coverage, trait selection\n4. **Review** — Check for completeness and gaps\n\nDesign concludes by choosing import or manual path.\n\n### Phase 2: Execute\n\nIf the project defines plan-execution workflows, start the matching one:\n\n```bash\n# Import path\nkspec workflow start @spec-plan-import\n\n# Manual path\nkspec workflow start @spec-plan-manual\n```\n\nOtherwise run the import or manual path commands directly (see the path examples above).\n\nBefore deriving, ask the user: **should this plan use a shared branch\nfor task stacking?** If yes, run `kspec plan branch @ref` after approval\nand before derive. This is a planning decision — dispatch handles the\nrest automatically.\n\n### Phase 3: Validate\n\nAfter import and derive:\n\n```bash\nkspec validate              # Check spec quality\nkspec validate --alignment  # Verify spec-task links\n```\n\n## Plan Document Format\n\nThe import parser extracts specs, tasks, and notes from this markdown structure:\n\n````markdown\n# Plan Title\n\n## Specs\n\n```yaml\n- title: Example Feature\n  slug: example-feature\n  type: feature\n  parent: \"@parent-module\"\n  description: One-line description of the user-visible capability\n  traits:\n    - example-project-trait\n  acceptance_criteria:\n    - id: ac-1\n      given: A described precondition\n      when: A user-visible action happens\n      then: A specific observable outcome\n    - id: ac-2\n      given: A described error precondition\n      when: The error path is triggered\n      then: A specific recovery or guidance outcome\n  implementation_notes: |\n    Per-spec implementation notes. Attached to this spec's derived task.\n\n- title: Example Requirement\n  slug: example-requirement\n  type: requirement\n  parent: \"@example-feature\"\n  acceptance_criteria:\n    - id: ac-1\n      given: A described precondition\n      when: A user-visible action happens\n      then: A specific observable outcome\n```\n\n## Tasks\n\nderive_from_specs: true\n\n```yaml\n- title: Example task title\n  slug: example-task\n  description: |\n    Brief description of the task — what to do and why. Include scope\n    boundaries when they are not obvious from the spec.\n  priority: 2\n  tags:\n    - docs\n  spec_ref: \"@example-feature\"\n  depends_on:\n    - \"@example-requirement\"\n```\n\n## Implementation Notes\n\nGeneral architecture notes attached to the plan record.\nUse this section for cross-spec implementation context.\n````\n\n### Section Reference\n\n| Section                   | Content                                           | Notes                                                                                   |\n| ------------------------- | ------------------------------------------------- | --------------------------------------------------------------------------------------- |\n| `## Specs`                | YAML code block — array of spec objects           | **Must** use fenced code block (triple-backtick yaml)                                   |\n| `## Tasks`                | `derive_from_specs: true` + optional manual tasks | Manual tasks get `plan_ref`; can optionally set `spec_ref`, `depends_on`, `description` |\n| `## Implementation Notes` | Plain text                                        | Attached to plan record; per-spec notes use `implementation_notes` field                |\n\n### Spec Fields\n\n| Field                  | Required | Description                                                                |\n| ---------------------- | -------- | -------------------------------------------------------------------------- |\n| `title`                | Yes      | Spec title                                                                 |\n| `slug`                 | No       | Human-friendly ID (auto-generated if omitted)                              |\n| `type`                 | No       | `feature`, `requirement`, `constraint`, `decision` (default: `feature`)    |\n| `parent`               | No       | Parent ref (e.g., `\"@parent-slug\"`)                                        |\n| `description`          | No       | What and why                                                               |\n| `acceptance_criteria`  | No       | Array of `{id, given, when, then}`                                         |\n| `traits`               | No       | Array of trait slugs from the project's trait catalog (`kspec trait list`) |\n| `implementation_notes` | No       | Scoped to this spec's derived task                                         |\n\n### Spec Language Quality\n\nSpecs in plan documents must follow the same behavioral language rules as any spec. See `$kspec-writing-specs` for the full rules. Key points:\n\n- **ACs describe observable behavior** — not internal mechanisms. Use natural language a non-developer could follow, not code-level terms.\n- **ACs contain only assertions** — no rationale, design commentary, or backward compatibility notes. Those belong in descriptions or `implementation_notes`.\n- **Specs are standalone and timeless** — describe what the system does, not how it differs from a previous version. Use spec fields (`depends_on`, `relates_to`) for relationships.\n- **Implementation guidance goes in tasks** — task descriptions are the right place for file paths, class names, and technical approach.\n\n### Task Fields\n\n| Field         | Required | Description                                               |\n| ------------- | -------- | --------------------------------------------------------- |\n| `title`       | Yes      | Task title                                                |\n| `slug`        | No       | Human-friendly ID (auto-generated from title if omitted)  |\n| `description` | No       | Task context — what to do and why                         |\n| `priority`    | No       | 1 (highest) to 5 (lowest), default: 3                     |\n| `tags`        | No       | Array of tags (e.g., `docs`, `cli`)                       |\n| `spec_ref`    | No       | Link to a spec — local spec slug or existing `@ref`       |\n| `depends_on`  | No       | Array of refs — local task\u002Fspec slugs or existing `@ref`s |\n\n## Trait Selection\n\nTraits are not shipped by `kspec init` — each project defines its own trait catalog. Before writing specs, review what's available in this project and pick matching ones:\n\n```bash\nkspec trait list                       # See the project's trait catalog\nkspec trait get @\u003Ctrait-slug>          # See a trait's inherited ACs\n```\n\nFor each spec you write, scan the catalog for traits whose behavior the spec implements (for example: output formatting, destructive-operation prompts, list filtering, error guidance, batch refs, shadow-state mutation). If no matching trait exists and the cross-cutting behavior recurs across 3+ specs, consider defining a new trait. See [Creating New Traits](#creating-new-traits) — covered in `$kspec-writing-specs`.\n\n### Trait Naming in Plan Documents\n\nUse the **full trait slug** as it appears in `kspec trait list` — import only auto-prefixes `@`, not any specific trait namespace prefix:\n\n```yaml\n# Wrong — uses the un-prefixed name\ntraits:\n  - some-trait\n\n# Correct — full slug from the project trait catalog\ntraits:\n  - example-project-trait\n```\n\n## YAML Pitfalls\n\nPlan documents embed YAML that is parsed as structured data. Common issues:\n\n### Block Scalars for Complex Text\n\nUse `|` (literal block scalar) when AC text contains quotes, colons, or special characters:\n\n```yaml\n# Problem — mixed quoting breaks parser\nacceptance_criteria:\n  - id: ac-1\n    when: \"kspec foo\" is run\n\n# Solution — block scalar preserves content literally\nacceptance_criteria:\n  - id: ac-1\n    when: |\n      \"kspec foo\" is run\n```\n\n### Colons in Values\n\nYAML treats `: ` (colon-space) as a key-value separator:\n\n```yaml\n# Problem — parsed as nested key\nthen: output shows time: 10:30\n\n# Solution — quote the value\nthen: \"output shows time: 10:30\"\n```\n\n### Best Practice\n\nUse block scalars (`|`) for ALL given\u002Fwhen\u002Fthen text. This avoids every quoting issue:\n\n```yaml\nacceptance_criteria:\n  - id: ac-1\n    given: |\n      user has an existing session\n    when: |\n      user runs \"kspec session start\"\n    then: |\n      session context shows: active tasks, recent notes, inbox count\n```\n\n## Always Dry-Run First\n\n```bash\nkspec plan import .\u002Fplan.md --dry-run\n```\n\nImport dry-run confirms:\n\n- Title, status, and stored module look right\n- The file is readable and the full document will be stored as plan content\n- No plan state is changed while previewing\n\n## Post-Import Checklist\n\nAfter importing, verify the stored plan record:\n\n```bash\n# Review plan title\u002Fcontent\u002Fstatus\u002Fmodule\nkspec plan get @plan-slug\n\n# Iterate on the document if needed\nkspec plan export @plan-slug --output .\u002Fplan.md\nkspec plan import .\u002Fplan.md --into @plan-slug --reason \"Refined scope\"\n\n# Approve when ready to materialize work\nkspec plan set @plan-slug --status approved\n\n# Derive specs\u002Ftasks from the stored plan document\nkspec plan derive @plan-slug\n\n# Validate the resulting refs and coverage surface\nkspec validate\n```\n\nIf derived tasks are too generic to execute without chat history, add a structured task note immediately after derive:\n\n```bash\nkspec task note @task-slug \"Execution context:\n- Background: why this task exists\n- Scope: concrete boundaries for this task\n- Files: exact files\u002Fareas to touch\n- Verification: commands\u002Ftests to run\"\n```\n\n## Plan Lifecycle\n\n```\ndraft → approved → active → completed\n                     ↓\n                  rejected\n```\n\n- **Import** stores the full document as a plan record and defaults to `draft`\n- **Import** may optionally store `module_ref` for later derive\n- **Manual** creates plan as `approved`\n- **Branch** (optional) — after approval but before derive, ask the user\n  whether tasks should target a shared plan branch or the default\n  integration branch. If the user wants task stacking:\n\n```bash\nkspec plan branch @plan-ref          # Deterministic: plan\u002F\u003Cslug>\u002F\u003Cshort-ref>\nkspec plan branch @plan-ref --name feat\u002Fcustom-name  # Custom name\n```\n\nDispatch automatically targets the plan branch for all derived tasks.\nWithout a plan branch, tasks target the default integration branch as\nusual.\n\n- **Derive** materializes an approved plan into specs and tasks by default, then transitions it to `active`\n- Mark completed when all derived work is done:\n\n```bash\nkspec plan set @plan --status completed\n```\n\n> **Plan branch lifecycle:** When a plan has a branch, all derived tasks\n> fork from and merge back into that branch. Task work accumulates on the\n> plan branch as tasks are completed. Once all tasks are done and the plan\n> is marked completed, the plan branch requires manual merging into the\n> project's integration branch using the project-defined merge command.\n> A future `kspec plan merge` command may automate this, but for now it is\n> a manual step.\n\n## Programmatic Alternative: Batch\n\nFor fully programmatic creation (scripts, agent pipelines):\n\n```bash\nkspec batch --commands '[\n  {\"command\":\"item add\",\"args\":{\"under\":\"@parent\",\"title\":\"Feature X\",\"type\":\"feature\",\"slug\":\"feature-x\"}},\n  {\"command\":\"item ac add\",\"args\":{\"ref\":\"@feature-x\",\"given\":\"...\",\"when\":\"...\",\"then\":\"...\"}},\n  {\"command\":\"derive\",\"args\":{\"ref\":\"@feature-x\"}}\n]'\n```\n\nAtomic — all succeed or all roll back. Use `--dry-run` to preview.\n\n## Command Reference\n\n```bash\n# Design phase — start the project's plan-design workflow if it exists\nkspec workflow start @spec-plan-design\n\n# Import path\nkspec plan import \u003Cpath> [--module @module] --dry-run         # Preview plan record\nkspec plan import \u003Cpath> [--module @module] [--status approved]  # Create stored plan record\nkspec plan export \u003Cplan-ref> --output .\u002Fplan.md\nkspec plan import \u003Cpath> --into \u003Cplan-ref> [--reason \"...\"]  # Re-import edits\nkspec plan set \u003Cplan-ref> --status approved\nkspec plan derive \u003Cplan-ref> [--module @module] [--no-tasks]\n\n# Manual path\nkspec plan add --title \"...\" --content \"...\" --status approved\nkspec plan get \u003Cref>\nkspec plan set \u003Cref> --status \u003Cstatus>\nkspec plan note \u003Cref> \"...\"\nkspec plan list\n\n# Plan branch (opt-in task stacking)\nkspec plan branch \u003Cref>                              # Create\u002Fresume deterministic branch\nkspec plan branch \u003Cref> --name \u003Cbranch>              # Custom branch name\nkspec plan set \u003Cref> --branch \u003Cname>                 # Set branch manually\nkspec plan set \u003Cref> --branch \"\"                     # Clear branch (revert to default)\n\n# Validation\nkspec validate\nkspec validate --completeness\nkspec validate --alignment\n```\n\n## Integration\n\n- **`$kspec-writing-specs`** — Spec authoring details (types, AC format, traits)\n- **`$kspec-task-work`** — After specs are created, work on derived tasks\n- **`$kspec-triage`** — Inbox items may trigger plan creation\n- **`$kspec-observe`** — Friction during planning becomes observations\n","\u003C!-- kspec-managed -->\n# Plan to Spec Translation\n\nTranslate approved plans into specs and tasks. Plans are durable artifacts — they persist in the shadow branch, link to derived work, and provide auditable planning history across sessions.\n\n## When to Use\n\n- After plan mode approval — turning an approved plan into trackable specs and tasks\n- Creating specs for new features or multi-spec capabilities\n- Translating design documents into the spec hierarchy\n\n**Not for:** Raw ideas (use `kspec inbox add`), single spec creation (use `$kspec-writing-specs`), or triage (use `$kspec-triage`).\n\n## Two Paths\n\n### Import Path (Recommended for 3+ Specs)\n\nWrite a structured markdown document, import it as a durable plan record, iterate as needed, then derive specs\u002Ftasks when the plan is ready.\n\n```bash\nkspec plan import .\u002Fplan.md --dry-run                           # Preview plan record\nkspec plan import .\u002Fplan.md --module @target-module             # Store plan (+ optional module)\nkspec plan import .\u002Fedited.md --into @plan-ref                  # Re-import edits into existing plan\nkspec plan set @plan-ref --status approved                      # Approve when ready\nkspec plan derive @plan-ref --module @target-module             # Materialize specs\u002Ftasks\n```\n\n### Manual Path (1-2 Specs)\n\nCreate plan record and specs incrementally via CLI.\n\n```bash\nkspec plan add --title \"Plan Title\" --content \"Description\" --status approved\nkspec item add --under @parent --title \"Feature\" --type feature --slug slug\nkspec item ac add @slug --given \"...\" --when \"...\" --then \"...\"\nkspec derive @slug\n```\n\n### When to Use Which\n\n| Situation                                | Path              |\n| ---------------------------------------- | ----------------- |\n| Plan mode just approved, complex feature | Import            |\n| Adding a requirement to existing feature | Manual            |\n| Multiple related specs with parent\u002Fchild | Import            |\n| Quick bug fix that needs spec coverage   | Manual            |\n| Translating design doc with many specs   | Import            |\n| Iterating on previously imported plan    | Import (`--into`) |\n\n## Three-Phase Workflow\n\n### Phase 1: Design\n\nAlways start here — never skip research.\n\nIf the project defines a plan-design workflow (for example `@spec-plan-design`), start it now:\n\n```bash\nkspec workflow start @spec-plan-design\n```\n\nOtherwise follow these steps directly:\n\n1. **Explore** — Read relevant code, understand current state\n2. **Clarify** — Identify ambiguities, resolve with user\n3. **Design** — Spec structure, AC coverage, trait selection\n4. **Review** — Check for completeness and gaps\n\nDesign concludes by choosing import or manual path.\n\n### Phase 2: Execute\n\nIf the project defines plan-execution workflows, start the matching one:\n\n```bash\n# Import path\nkspec workflow start @spec-plan-import\n\n# Manual path\nkspec workflow start @spec-plan-manual\n```\n\nOtherwise run the import or manual path commands directly (see the path examples above).\n\nBefore deriving, ask the user: **should this plan use a shared branch\nfor task stacking?** If yes, run `kspec plan branch @ref` after approval\nand before derive. This is a planning decision — dispatch handles the\nrest automatically.\n\n### Phase 3: Validate\n\nAfter import and derive:\n\n```bash\nkspec validate              # Check spec quality\nkspec validate --alignment  # Verify spec-task links\n```\n\n## Plan Document Format\n\nThe import parser extracts specs, tasks, and notes from this markdown structure:\n\n````markdown\n# Plan Title\n\n## Specs\n\n```yaml\n- title: Example Feature\n  slug: example-feature\n  type: feature\n  parent: \"@parent-module\"\n  description: One-line description of the user-visible capability\n  traits:\n    - example-project-trait\n  acceptance_criteria:\n    - id: ac-1\n      given: A described precondition\n      when: A user-visible action happens\n      then: A specific observable outcome\n    - id: ac-2\n      given: A described error precondition\n      when: The error path is triggered\n      then: A specific recovery or guidance outcome\n  implementation_notes: |\n    Per-spec implementation notes. Attached to this spec's derived task.\n\n- title: Example Requirement\n  slug: example-requirement\n  type: requirement\n  parent: \"@example-feature\"\n  acceptance_criteria:\n    - id: ac-1\n      given: A described precondition\n      when: A user-visible action happens\n      then: A specific observable outcome\n```\n\n## Tasks\n\nderive_from_specs: true\n\n```yaml\n- title: Example task title\n  slug: example-task\n  description: |\n    Brief description of the task — what to do and why. Include scope\n    boundaries when they are not obvious from the spec.\n  priority: 2\n  tags:\n    - docs\n  spec_ref: \"@example-feature\"\n  depends_on:\n    - \"@example-requirement\"\n```\n\n## Implementation Notes\n\nGeneral architecture notes attached to the plan record.\nUse this section for cross-spec implementation context.\n````\n\n### Section Reference\n\n| Section                   | Content                                           | Notes                                                                                   |\n| ------------------------- | ------------------------------------------------- | --------------------------------------------------------------------------------------- |\n| `## Specs`                | YAML code block — array of spec objects           | **Must** use fenced code block (triple-backtick yaml)                                   |\n| `## Tasks`                | `derive_from_specs: true` + optional manual tasks | Manual tasks get `plan_ref`; can optionally set `spec_ref`, `depends_on`, `description` |\n| `## Implementation Notes` | Plain text                                        | Attached to plan record; per-spec notes use `implementation_notes` field                |\n\n### Spec Fields\n\n| Field                  | Required | Description                                                                |\n| ---------------------- | -------- | -------------------------------------------------------------------------- |\n| `title`                | Yes      | Spec title                                                                 |\n| `slug`                 | No       | Human-friendly ID (auto-generated if omitted)                              |\n| `type`                 | No       | `feature`, `requirement`, `constraint`, `decision` (default: `feature`)    |\n| `parent`               | No       | Parent ref (e.g., `\"@parent-slug\"`)                                        |\n| `description`          | No       | What and why                                                               |\n| `acceptance_criteria`  | No       | Array of `{id, given, when, then}`                                         |\n| `traits`               | No       | Array of trait slugs from the project's trait catalog (`kspec trait list`) |\n| `implementation_notes` | No       | Scoped to this spec's derived task                                         |\n\n### Spec Language Quality\n\nSpecs in plan documents must follow the same behavioral language rules as any spec. See `$kspec-writing-specs` for the full rules. Key points:\n\n- **ACs describe observable behavior** — not internal mechanisms. Use natural language a non-developer could follow, not code-level terms.\n- **ACs contain only assertions** — no rationale, design commentary, or backward compatibility notes. Those belong in descriptions or `implementation_notes`.\n- **Specs are standalone and timeless** — describe what the system does, not how it differs from a previous version. Use spec fields (`depends_on`, `relates_to`) for relationships.\n- **Implementation guidance goes in tasks** — task descriptions are the right place for file paths, class names, and technical approach.\n\n### Task Fields\n\n| Field         | Required | Description                                               |\n| ------------- | -------- | --------------------------------------------------------- |\n| `title`       | Yes      | Task title                                                |\n| `slug`        | No       | Human-friendly ID (auto-generated from title if omitted)  |\n| `description` | No       | Task context — what to do and why                         |\n| `priority`    | No       | 1 (highest) to 5 (lowest), default: 3                     |\n| `tags`        | No       | Array of tags (e.g., `docs`, `cli`)                       |\n| `spec_ref`    | No       | Link to a spec — local spec slug or existing `@ref`       |\n| `depends_on`  | No       | Array of refs — local task\u002Fspec slugs or existing `@ref`s |\n\n## Trait Selection\n\nTraits are not shipped by `kspec init` — each project defines its own trait catalog. Before writing specs, review what's available in this project and pick matching ones:\n\n```bash\nkspec trait list                       # See the project's trait catalog\nkspec trait get @\u003Ctrait-slug>          # See a trait's inherited ACs\n```\n\nFor each spec you write, scan the catalog for traits whose behavior the spec implements (for example: output formatting, destructive-operation prompts, list filtering, error guidance, batch refs, shadow-state mutation). If no matching trait exists and the cross-cutting behavior recurs across 3+ specs, consider defining a new trait. See [Creating New Traits](#creating-new-traits) — covered in `$kspec-writing-specs`.\n\n### Trait Naming in Plan Documents\n\nUse the **full trait slug** as it appears in `kspec trait list` — import only auto-prefixes `@`, not any specific trait namespace prefix:\n\n```yaml\n# Wrong — uses the un-prefixed name\ntraits:\n  - some-trait\n\n# Correct — full slug from the project trait catalog\ntraits:\n  - example-project-trait\n```\n\n## YAML Pitfalls\n\nPlan documents embed YAML that is parsed as structured data. Common issues:\n\n### Block Scalars for Complex Text\n\nUse `|` (literal block scalar) when AC text contains quotes, colons, or special characters:\n\n```yaml\n# Problem — mixed quoting breaks parser\nacceptance_criteria:\n  - id: ac-1\n    when: \"kspec foo\" is run\n\n# Solution — block scalar preserves content literally\nacceptance_criteria:\n  - id: ac-1\n    when: |\n      \"kspec foo\" is run\n```\n\n### Colons in Values\n\nYAML treats `: ` (colon-space) as a key-value separator:\n\n```yaml\n# Problem — parsed as nested key\nthen: output shows time: 10:30\n\n# Solution — quote the value\nthen: \"output shows time: 10:30\"\n```\n\n### Best Practice\n\nUse block scalars (`|`) for ALL given\u002Fwhen\u002Fthen text. This avoids every quoting issue:\n\n```yaml\nacceptance_criteria:\n  - id: ac-1\n    given: |\n      user has an existing session\n    when: |\n      user runs \"kspec session start\"\n    then: |\n      session context shows: active tasks, recent notes, inbox count\n```\n\n## Always Dry-Run First\n\n```bash\nkspec plan import .\u002Fplan.md --dry-run\n```\n\nImport dry-run confirms:\n\n- Title, status, and stored module look right\n- The file is readable and the full document will be stored as plan content\n- No plan state is changed while previewing\n\n## Post-Import Checklist\n\nAfter importing, verify the stored plan record:\n\n```bash\n# Review plan title\u002Fcontent\u002Fstatus\u002Fmodule\nkspec plan get @plan-slug\n\n# Iterate on the document if needed\nkspec plan export @plan-slug --output .\u002Fplan.md\nkspec plan import .\u002Fplan.md --into @plan-slug --reason \"Refined scope\"\n\n# Approve when ready to materialize work\nkspec plan set @plan-slug --status approved\n\n# Derive specs\u002Ftasks from the stored plan document\nkspec plan derive @plan-slug\n\n# Validate the resulting refs and coverage surface\nkspec validate\n```\n\nIf derived tasks are too generic to execute without chat history, add a structured task note immediately after derive:\n\n```bash\nkspec task note @task-slug \"Execution context:\n- Background: why this task exists\n- Scope: concrete boundaries for this task\n- Files: exact files\u002Fareas to touch\n- Verification: commands\u002Ftests to run\"\n```\n\n## Plan Lifecycle\n\n```\ndraft → approved → active → completed\n                     ↓\n                  rejected\n```\n\n- **Import** stores the full document as a plan record and defaults to `draft`\n- **Import** may optionally store `module_ref` for later derive\n- **Manual** creates plan as `approved`\n- **Branch** (optional) — after approval but before derive, ask the user\n  whether tasks should target a shared plan branch or the default\n  integration branch. If the user wants task stacking:\n\n```bash\nkspec plan branch @plan-ref          # Deterministic: plan\u002F\u003Cslug>\u002F\u003Cshort-ref>\nkspec plan branch @plan-ref --name feat\u002Fcustom-name  # Custom name\n```\n\nDispatch automatically targets the plan branch for all derived tasks.\nWithout a plan branch, tasks target the default integration branch as\nusual.\n\n- **Derive** materializes an approved plan into specs and tasks by default, then transitions it to `active`\n- Mark completed when all derived work is done:\n\n```bash\nkspec plan set @plan --status completed\n```\n\n> **Plan branch lifecycle:** When a plan has a branch, all derived tasks\n> fork from and merge back into that branch. Task work accumulates on the\n> plan branch as tasks are completed. Once all tasks are done and the plan\n> is marked completed, the plan branch requires manual merging into the\n> project's integration branch using the project-defined merge command.\n> A future `kspec plan merge` command may automate this, but for now it is\n> a manual step.\n\n## Programmatic Alternative: Batch\n\nFor fully programmatic creation (scripts, agent pipelines):\n\n```bash\nkspec batch --commands '[\n  {\"command\":\"item add\",\"args\":{\"under\":\"@parent\",\"title\":\"Feature X\",\"type\":\"feature\",\"slug\":\"feature-x\"}},\n  {\"command\":\"item ac add\",\"args\":{\"ref\":\"@feature-x\",\"given\":\"...\",\"when\":\"...\",\"then\":\"...\"}},\n  {\"command\":\"derive\",\"args\":{\"ref\":\"@feature-x\"}}\n]'\n```\n\nAtomic — all succeed or all roll back. Use `--dry-run` to preview.\n\n## Command Reference\n\n```bash\n# Design phase — start the project's plan-design workflow if it exists\nkspec workflow start @spec-plan-design\n\n# Import path\nkspec plan import \u003Cpath> [--module @module] --dry-run         # Preview plan record\nkspec plan import \u003Cpath> [--module @module] [--status approved]  # Create stored plan record\nkspec plan export \u003Cplan-ref> --output .\u002Fplan.md\nkspec plan import \u003Cpath> --into \u003Cplan-ref> [--reason \"...\"]  # Re-import edits\nkspec plan set \u003Cplan-ref> --status approved\nkspec plan derive \u003Cplan-ref> [--module @module] [--no-tasks]\n\n# Manual path\nkspec plan add --title \"...\" --content \"...\" --status approved\nkspec plan get \u003Cref>\nkspec plan set \u003Cref> --status \u003Cstatus>\nkspec plan note \u003Cref> \"...\"\nkspec plan list\n\n# Plan branch (opt-in task stacking)\nkspec plan branch \u003Cref>                              # Create\u002Fresume deterministic branch\nkspec plan branch \u003Cref> --name \u003Cbranch>              # Custom branch name\nkspec plan set \u003Cref> --branch \u003Cname>                 # Set branch manually\nkspec plan set \u003Cref> --branch \"\"                     # Clear branch (revert to default)\n\n# Validation\nkspec validate\nkspec validate --completeness\nkspec validate --alignment\n```\n\n## Integration\n\n- **`$kspec-writing-specs`** — Spec authoring details (types, AC format, traits)\n- **`$kspec-task-work`** — After specs are created, work on derived tasks\n- **`$kspec-triage`** — Inbox items may trigger plan creation\n- **`$kspec-observe`** — Friction during planning becomes observations\n",{"name":5,"description":7},"main","c4b0de3035f8512bba7eb0a9b4e39ea2fbd3f08e",".agents\u002Fskills\u002Fkspec-plan",2,"https:\u002F\u002Fgithub.com\u002Flepahc\u002Fkynetic-spec","https:\u002F\u002Fgithub.com\u002Flepahc","2026-07-22 18:57:40",{"source":8,"skillName":5,"commands":39,"prompt":49,"zipAvailable":50},[40,43,46],{"tool":41,"command":42},"npx","npx skills add lepahc\u002Fkynetic-spec --skill kspec-plan",{"tool":44,"command":45},"bunx","bunx skills add lepahc\u002Fkynetic-spec --skill kspec-plan",{"tool":47,"command":48},"pnpm","pnpm dlx skills add lepahc\u002Fkynetic-spec --skill kspec-plan","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Flepahc\u002Fkynetic-spec\u002Fblob\u002Fmain\u002F.agents\u002Fskills\u002Fkspec-plan\u002FSKILL.md",true,[],[53,71,77,85,96,104],{"skillNo":54,"name":55,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":9,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":56,"categories":57,"keywords":68,"publishedAt":26},"01M6C7KCZE43MDZ74FV3A5TDCQ","writing-specs","https:\u002F\u002Fgithub.com\u002Flepahc\u002Fkynetic-spec\u002Fblob\u002Fmain\u002Ftemplates\u002Fskills\u002Fwriting-specs\u002FSKILL.md",[58,63],{"categoryNo":59,"categoryName":60,"taxonomyType":61,"taxonomyTypeDesc":62},"01JBSEEDCAT000000000000018","写作与文案","SCENARIO","使用场景",{"categoryNo":64,"categoryName":65,"taxonomyType":66,"taxonomyTypeDesc":67},"01JBSEEDCAT000000000000036","内容创作者","PROFESSION","适用职业",[69,70],"writing","writing specs",{"skillNo":72,"name":73,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":9,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":74,"categories":75,"keywords":76,"publishedAt":26},"01M6C7KAK9CBJ87PX3BCW7B7YG","triage","https:\u002F\u002Fgithub.com\u002Flepahc\u002Fkynetic-spec\u002Fblob\u002Fmain\u002Ftemplates\u002Fskills\u002Ftriage\u002FSKILL.md",[],[73],{"skillNo":78,"name":79,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":9,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":80,"categories":81,"keywords":82,"publishedAt":26},"01M6C7K89VN6FJCT8M86K56EE8","triage-inbox","https:\u002F\u002Fgithub.com\u002Flepahc\u002Fkynetic-spec\u002Fblob\u002Fmain\u002Ftemplates\u002Fskills\u002Ftriage-inbox\u002FSKILL.md",[],[73,83,84],"inbox","triage inbox",{"skillNo":86,"name":87,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":9,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":88,"categories":89,"keywords":93,"publishedAt":26},"01M6C7K6F2342AC1TJCN9PM0ZB","triage-automation","https:\u002F\u002Fgithub.com\u002Flepahc\u002Fkynetic-spec\u002Fblob\u002Fmain\u002Ftemplates\u002Fskills\u002Ftriage-automation\u002FSKILL.md",[90],{"categoryNo":91,"categoryName":92,"taxonomyType":61,"taxonomyTypeDesc":62},"01JBSEEDCAT000000000000023","Skill与智能体开发",[73,94,95],"automation","triage automation",{"skillNo":97,"name":98,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":9,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":99,"categories":100,"keywords":101,"publishedAt":26},"01M6C7K3TFQ88QQBW3PXYDHQG2","task-work","https:\u002F\u002Fgithub.com\u002Flepahc\u002Fkynetic-spec\u002Fblob\u002Fmain\u002Ftemplates\u002Fskills\u002Ftask-work\u002FSKILL.md",[],[102,103],"work","task work",{"skillNo":105,"name":106,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":9,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":107,"categories":108,"keywords":109,"publishedAt":26},"01M6C7K168CH3XJCC3PDGA9H6C","review","https:\u002F\u002Fgithub.com\u002Flepahc\u002Fkynetic-spec\u002Fblob\u002Fmain\u002Ftemplates\u002Fskills\u002Freview\u002FSKILL.md",[],[106]]