[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M6RB4HJ3A9GWEK3WHT2KCWN5":3,"skill-same:01M6RB4HJ3A9GWEK3WHT2KCWN5":88},{"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":34,"publishedAt":55,"linkOnly":56,"markdownContent":57,"markdownBody":58,"frontMatter":59,"refName":66,"commitSha":67,"skillDirectory":68,"forksCount":69,"repositoryHtmlUrl":70,"repositoryHomepageUrl":6,"ownerHtmlUrl":71,"ownerBlogUrl":72,"ownerDescription":73,"updatedAt":74,"install":75,"resources":87},"01M6RB4HJ3A9GWEK3WHT2KCWN5","code-design",null,"Create a high-quality code design document through an iterative research\u002Fdesign\u002Faudit workflow","Nairon-AI\u002Fagentic-starter-pack","Nairon-AI","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F260662138?v=4","01M6R8PZ1Y8CSQGFN61VACZGTH","Nairon AI","01M6R8PZ6184VR3BA88YZFBC3N",4,"MIT","https:\u002F\u002Fgithub.com\u002FNairon-AI\u002Fagentic-starter-pack\u002Fblob\u002Fmain\u002Fplanning\u002Fcode-design\u002FSKILL.md",[18,23,26,31],{"categoryNo":19,"categoryName":20,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000015","视觉设计","SCENARIO","使用场景",{"categoryNo":24,"categoryName":25,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000021","资料检索与研究",{"categoryNo":27,"categoryName":28,"taxonomyType":29,"taxonomyTypeDesc":30},"01JBSEEDCAT000000000000030","开发工程师","PROFESSION","适用职业",{"categoryNo":32,"categoryName":33,"taxonomyType":29,"taxonomyTypeDesc":30},"01JBSEEDCAT000000000000032","设计师",[35,36,37,38,39,40,41,42,43,44,45,46,47,48,49,50,51,52,53,54],"code design","code","design","goal","describe","title","buffer","true","feature","files","issue","clipboard","outcome","command","doc","audit","transcript","create","architecture","workflow","2026-11-10 10:12:30",false,"---\nname: code-design\ndescription: Create a high-quality code design document through an iterative research\u002Fdesign\u002Faudit workflow\naliases: code-design,design-doc,iterative-design,architecture-design\nusage: \u002Fgoal code-design --doc .ai\u002Fdocs\u002Frealtime-voice\u002Fdesign-feature-name.md --title \"Feature name\" --minutes 7 -- Describe the issue, feature, constraints, known files, and desired outcome\nexamples: \u002Fgoal code-design --doc .ai\u002Fdocs\u002Frealtime-voice\u002Fdesign-copy-capture-command.md --title \"Copy capture command\" --minutes 7 -- Design a command that copies the current capture buffer to the clipboard; \u002Fgoal iterative-design --doc .ai\u002Fdocs\u002Frealtime-voice\u002Fdesign-utterance-aggregation-delay.md --title \"Utterance aggregation delay\" --minutes 10 -- Design configurable transcript aggregation before capture\u002Fbackend routing\nallow_commands: true\ncommand_timeout_ms: 10000\ncommand_output_limit: 30000\n---\n\nCreate a code design document for the requested issue, feature, improvement, or architectural change.\n\n\u003Cdesign_goal_request>\n  \u003Ctitle>{{title}}\u003C\u002Ftitle>\n  \u003Ctarget_design_doc>{{doc}}\u003C\u002Ftarget_design_doc>\n  \u003Cminimum_effort_floor_minutes>{{minutes}}\u003C\u002Fminimum_effort_floor_minutes>\n  \u003Ccontext>{{args}}\u003C\u002Fcontext>\n\u003C\u002Fdesign_goal_request>\n\nThis is a **design-document goal**, not an implementation goal. Do not edit runtime\u002Fsource code for the feature unless the user explicitly authorizes implementation in the goal context. Design artifacts, validation probes for the design document, and documentation edits directly needed for the design goal are allowed when appropriate.\n\n## Phase 1: Goal initialization and readiness\n\n1. Confirm that this goal is already initialized from the reusable `iterative-code-design` goal template.\n2. Confirm the target design document path: `{{doc}}`.\n3. Confirm the minimum effort floor: `{{minutes}}` minutes.\n   - Treat this as a hard minimum eligibility floor only.\n   - Do not use `sleep` to satisfy the floor.\n   - Take all time necessary for a clean, high-quality architectural design.\n   - Do not stop just because the floor is met.\n4. Read `AGENTS.md` and any project-local instructions relevant to the target files\u002Fworkstream.\n5. Read project design\u002Fstyle guides when present:\n   - `.ai\u002Fdocs\u002Farchitecture-and-system-design-style.md`\n   - `.ai\u002Fdocs\u002Fcode-style.md`\n6. If this template itself is being revised, read `.ai\u002Fdocs\u002Fprompt-template-authoring.md` first.\n7. Explicitly restate the design objectives, scope, constraints, and repository guidance before drafting.\n\nUse this initial read-only repository context, then inspect targeted files directly as needed:\n\n\u003Crepo_status>\n!`git status --short --untracked-files=all`\n\u003C\u002Frepo_status>\n\n\u003Cexisting_design_docs>\n!`find .ai\u002Fdocs -type f -name 'design-*.md' 2>\u002Fdev\u002Fnull | sort | tail -80`\n\u003C\u002Fexisting_design_docs>\n\n## Phase 2: Design scope and objectives\n\nDesign the cleanest, most robust implementation possible for `{{title}}`, grounded in the provided context and inspected code\u002Fdocs.\n\nThe design must keep the architecture:\n\n- **Encapsulated**: separate provider\u002Fmodel\u002Fplatform mechanics from core domain\u002Frouting logic or equivalent ownership boundaries.\n- **Provider-neutral where appropriate**: avoid vendor-locking behavior in core domain layers. Keep provider-specific behavior under provider-owned modules.\n- **Decoupled**: minimize scattered conditionals by relying on typed behavior\u002Fconfiguration boundaries.\n- **Testable**: define deterministic validation, live validation where required, and false-green risks.\n- **Maintainable**: keep file ownership clear, avoid vague managers\u002Fabstractions, and prefer small concrete modules.\n- **Design-compressed**: when later evidence shows an existing code shape is too narrow, prefer reshaping that existing decision over adding a second nearby path.\n\nThe design document must answer:\n\n- What user\u002Fproblem outcome is being designed?\n- What current code\u002Fdocs\u002Fevidence are relevant?\n- What architecture and file ownership should be used?\n- What existing code or design decisions constrain this work?\n- Which existing assumptions might become too narrow because of this work?\n- What state, replay, lifecycle, UI, provider, or OS boundaries are affected?\n- What edge cases and failure modes matter?\n- What validation proves the design and later implementation?\n- What is explicitly out of scope?\n\n## Phase 3: Baseline design inventory\n\nBefore drafting the proposed design, create a `Baseline design inventory` section in `{{doc}}`.\n\nThis is mandatory. Do not skip it. Do not treat it as optional background research.\n\nThe inventory must list the existing design decisions in the current repo that constrain, shape, or risk being invalidated by the requested design.\n\nA baseline decision can come from:\n\n- current code structure;\n- current file or module ownership;\n- existing types, commands, tools, events, state, lifecycle hooks, provider boundaries, UI boundaries, or persistence paths;\n- prior design docs;\n- issue docs or validation probes;\n- git history for the target files when useful;\n- earlier implementation choices visible in the current code.\n\nFor every relevant existing decision, write one row in this format:\n\n| id | source | decision | location | current assumption | why it matters now | pressure signal |\n| --- | --- | --- | --- | --- | --- | --- |\n| B1 | existing code | Realtime requests enter Pi through `pi-realtime.request` custom messages instead of normal user messages | `.pi\u002Fextensions\u002Fpi-realtime\u002Fruntime.ts`, `.pi\u002Fextensions\u002Fpi-realtime\u002Fservice.ts` | Realtime-originated work must remain visibly distinct from typed user turns | The new design must preserve backend routing semantics | If the design adds another request route or wraps this path, review whether the original route should be widened instead |\n\nRules:\n\n1. `id` must be stable within the document: `B1`, `B2`, `B3`.\n2. `source` must name where the decision came from, such as `existing code`, `design doc`, `issue doc`, `validation probe`, or `git history`.\n3. `decision` must describe the actual design choice, not a vague topic.\n4. `location` must name concrete files, symbols, docs, or probes.\n5. `current assumption` must state what the existing design appears to believe.\n6. `why it matters now` must connect the existing decision to this requested design.\n7. `pressure signal` must say what kind of future finding would force this decision to be reviewed.\n\nIf no baseline decision is found, the design document must include a `Baseline design inventory` section with:\n\n- files\u002Fdocs\u002Fprobes inspected;\n- why none of them constrain the requested design;\n- what evidence would change that conclusion.\n\nDo not proceed to the main proposed design until this baseline section exists.\n\n## Phase 4: Iterative design loop\n\nIterate continuously through this loop until the design is semantically complete.\n\nEach iteration must include all six steps below. Do not skip the design compression review.\n\n### 1. Interrogate\n\nFor each iteration, formulate and answer the 5 most critical technical questions about the design.\n\nCover:\n\n- functional requirements;\n- architecture;\n- code ownership;\n- baseline decisions from the `Baseline design inventory`;\n- edge cases;\n- maintainability;\n- extensibility;\n- project standards;\n- validation;\n- known risks.\n\nAt least one question in each iteration must explicitly reference one or more baseline decision ids, such as `B1` or `B3`.\n\n### 2. Research\n\nInspect the codebase, docs, examples, design guides, validation probes, prior issue\u002Fdesign docs, and external docs if needed.\n\nDo not rely on memory when concrete file evidence is available.\n\nRecord the important files\u002Fdocs inspected inside the design document.\n\nWhen research touches a file, symbol, behavior, state path, provider path, lifecycle hook, command, or tool already named in the `Baseline design inventory`, record that connection in the design document.\n\n### 3. Synthesize\n\nIntegrate findings directly into `{{doc}}`:\n\n- design choices;\n- rejected alternatives;\n- API\u002Ftype\u002Fstate sketches when useful;\n- file-by-file implementation shape;\n- validation plan;\n- live-validation requirements and caveats;\n- risks and mitigations;\n- unresolved questions or blockers.\n\nEvery new proposed design choice that constrains implementation must be recorded in a `Proposed design decision ledger`.\n\nUse this format:\n\n| id | decision | location | reason | assumption | related baseline ids |\n| --- | --- | --- | --- | --- | --- |\n| D1 | Add a provider-neutral capture buffer service instead of putting capture state in the command handler | `.pi\u002Fextensions\u002Fpi-realtime\u002Fservice.ts`, `.pi\u002Fextensions\u002Fpi-realtime\u002Fruntime.ts` | Keeps command wiring separate from capture state | Capture buffering is core realtime domain behavior | B2, B4 |\n\nRules:\n\n1. `id` must be stable within the document: `D1`, `D2`, `D3`.\n2. `decision` must name the actual implementation-shaping choice.\n3. `location` must name concrete files, symbols, docs, or probes.\n4. `reason` must explain why this shape is better than a local patch.\n5. `assumption` must state what the proposed design depends on.\n6. `related baseline ids` must list every baseline decision this proposed choice touches. Use `none` only when the choice truly does not touch an existing decision.\n\n### 4. Design compression review\n\nThis step is mandatory in every iteration after synthesis.\n\nReview every row in:\n\n- `Baseline design inventory`;\n- `Proposed design decision ledger`.\n\nFor each row, answer these exact checks:\n\n1. Does the current proposed design touch the same `location`?\n2. Does the current proposed design reuse the same behavior, state, event, tool, command, provider boundary, UI boundary, lifecycle hook, or persistence path?\n3. Does the current proposed design make the recorded `current assumption` or `assumption` too narrow?\n4. Would keeping this decision force the implementation plan to add a new branch, helper, adapter, mode, fallback, wrapper, or parallel path near the same `location`?\n5. Would rewriting, splitting, or merging this decision make the final implementation smaller, clearer, or more consistent?\n\nFor every `yes`, add or update a `Compression review` section in `{{doc}}`.\n\nUse this format:\n\n| review id | decision id | trigger | finding | action | design update required |\n| --- | --- | --- | --- | --- | --- |\n| C1 | B2 | New command also needs capture text | Existing command-local capture shape would create a second capture path | rewrite | Move capture ownership into provider-neutral service before designing the command |\n\nThe `action` must be exactly one of:\n\n- `keep`: the existing or proposed decision still fits the final design.\n- `rewrite`: replace the decision with a broader or simpler design.\n- `split`: separate two responsibilities that were combined too early.\n- `merge`: fold the new behavior into an existing path instead of adding another path.\n- `defer`: leave the pressure unresolved, with the exact reason and risk named.\n\nOperational rules:\n\n1. If action is `rewrite`, `split`, or `merge`, update the proposed design before continuing to the next iteration.\n2. If action is `keep`, the finding must explain why the current shape still fits.\n3. If action is `defer`, the design must name the exact risk left for implementation or future work.\n4. Do not write vague findings like `reviewed`, `looks fine`, or `no issue`.\n5. Do not call the design complete while a compression review says `rewrite`, `split`, or `merge` and the document has not been updated to match that action.\n\n### 5. Reformat\n\nReview the whole design document for coherence.\n\nRestructure unclear sections so the document becomes the best possible draft so far, not a chronological scratchpad.\n\nThe baseline inventory, proposed decision ledger, and compression review must remain readable as durable design evidence. They may be reorganized, but they must not be deleted unless their content is replaced by an equally explicit section.\n\n### 6. Repeat\n\nContinue iterating until all are true:\n\n- the `{{minutes}}` minute floor has been met;\n- the `Baseline design inventory` exists and is grounded in inspected files\u002Fdocs\u002Fprobes;\n- the `Proposed design decision ledger` covers every implementation-shaping proposed decision;\n- the `Compression review` has evaluated every baseline and proposed decision touched by the final design;\n- every `rewrite`, `split`, or `merge` action has been reflected in the final proposed design;\n- the design document is complete, internally coherent, and strong enough to guide implementation without major architecture decisions left to the implementer.\n\n## Phase 5: Design document requirements\n\nWrite the final design document to:\n\n`{{doc}}`\n\nRecommended structure:\n\n1. `# Design: {{title}}`\n2. Intent \u002F problem statement.\n3. Scope and non-goals.\n4. Current evidence and inspected files.\n5. Baseline design inventory.\n6. Proposed behavior.\n7. Architecture and file ownership.\n8. Proposed design decision ledger.\n9. Compression review.\n10. State\u002Freplay\u002Flifecycle considerations if relevant.\n11. UI\u002Fcommand\u002Ftool\u002Fprovider\u002Fplatform considerations if relevant.\n12. Edge cases and failure modes.\n13. Validation plan.\n14. Implementation sequence or patch-shape guidance.\n15. Open questions \u002F decisions needed, if any.\n16. Completion audit against project guides.\n\nDo not include placeholder sections like `TODO`, `TBD`, or empty headings. If a section is not applicable, explicitly say why or omit it.\n\nThe `Baseline design inventory`, `Proposed design decision ledger`, and `Compression review` sections are not optional. If one of them has no rows, the section must explain why, using inspected evidence.\n\n## Phase 6: Final validation and closeout\n\nBefore marking the goal complete:\n\n1. Audit `{{doc}}` against:\n   - `AGENTS.md`;\n   - `.ai\u002Fdocs\u002Farchitecture-and-system-design-style.md` when present;\n   - `.ai\u002Fdocs\u002Fcode-style.md` when present;\n   - any workstream-specific docs discovered during research.\n2. Verify the document exists and has no placeholders:\n   - `test -f {{doc}}`\n   - `rg -n \"TODO|TBD|FIXME|placeholder\" {{doc}}` should find nothing unless discussing those words as concepts.\n3. Verify the document is visible or intentionally ignored according to repo policy:\n   - `git status --short --untracked-files=all`\n   - `git check-ignore -v {{doc}} || true`\n4. Verify that the design-compression sections exist:\n   - `rg -n \"Baseline design inventory|Proposed design decision ledger|Compression review\" {{doc}}`\n5. Verify that compression actions are resolved:\n   - No `rewrite`, `split`, or `merge` action may remain without a matching design update described in the document.\n   - Every `defer` action must name the risk, reason, and owner of the future decision.\n6. If the design proposes code changes, specify the exact validation gates a future implementation must run.\n7. Mark the goal complete only after all completion gates are met:\n   - minimum floor met;\n   - design semantically complete;\n   - baseline design inventory completed;\n   - proposed design decision ledger completed;\n   - compression review completed;\n   - unresolved compression actions either applied or explicitly deferred with risk.\n\nFinal response must include:\n\n- design doc path;\n- key design decisions;\n- baseline decisions reviewed;\n- compression actions taken;\n- files\u002Fdocs inspected;\n- validation\u002Fcheck commands run;\n- unresolved decisions, if any;\n- whether the document is tracked or ignored by git policy.\n\n---\nIMPORTANT:\n----\nDo not treat the minimum minute mark as a completion gate, instead of treat it as only the earliest possible wrap-up point.\n 1. Iterate until the design is actually high-quality and complete.\n 2. Use the N-minute floor only as a minimum eligibility check, not as a completion gate.\n 3. If the floor is met but the design still has unresolved structure, weak sections, missing research, or insufficient audit, keep going.\n 4. Only mark the goal complete after both are true:\n     - floor met\n     - design semantically complete\n\n The instruction “take all the time necessary” should override any impulse to stop at the minimum.\n","Create a code design document for the requested issue, feature, improvement, or architectural change.\n\n\u003Cdesign_goal_request>\n  \u003Ctitle>{{title}}\u003C\u002Ftitle>\n  \u003Ctarget_design_doc>{{doc}}\u003C\u002Ftarget_design_doc>\n  \u003Cminimum_effort_floor_minutes>{{minutes}}\u003C\u002Fminimum_effort_floor_minutes>\n  \u003Ccontext>{{args}}\u003C\u002Fcontext>\n\u003C\u002Fdesign_goal_request>\n\nThis is a **design-document goal**, not an implementation goal. Do not edit runtime\u002Fsource code for the feature unless the user explicitly authorizes implementation in the goal context. Design artifacts, validation probes for the design document, and documentation edits directly needed for the design goal are allowed when appropriate.\n\n## Phase 1: Goal initialization and readiness\n\n1. Confirm that this goal is already initialized from the reusable `iterative-code-design` goal template.\n2. Confirm the target design document path: `{{doc}}`.\n3. Confirm the minimum effort floor: `{{minutes}}` minutes.\n   - Treat this as a hard minimum eligibility floor only.\n   - Do not use `sleep` to satisfy the floor.\n   - Take all time necessary for a clean, high-quality architectural design.\n   - Do not stop just because the floor is met.\n4. Read `AGENTS.md` and any project-local instructions relevant to the target files\u002Fworkstream.\n5. Read project design\u002Fstyle guides when present:\n   - `.ai\u002Fdocs\u002Farchitecture-and-system-design-style.md`\n   - `.ai\u002Fdocs\u002Fcode-style.md`\n6. If this template itself is being revised, read `.ai\u002Fdocs\u002Fprompt-template-authoring.md` first.\n7. Explicitly restate the design objectives, scope, constraints, and repository guidance before drafting.\n\nUse this initial read-only repository context, then inspect targeted files directly as needed:\n\n\u003Crepo_status>\n!`git status --short --untracked-files=all`\n\u003C\u002Frepo_status>\n\n\u003Cexisting_design_docs>\n!`find .ai\u002Fdocs -type f -name 'design-*.md' 2>\u002Fdev\u002Fnull | sort | tail -80`\n\u003C\u002Fexisting_design_docs>\n\n## Phase 2: Design scope and objectives\n\nDesign the cleanest, most robust implementation possible for `{{title}}`, grounded in the provided context and inspected code\u002Fdocs.\n\nThe design must keep the architecture:\n\n- **Encapsulated**: separate provider\u002Fmodel\u002Fplatform mechanics from core domain\u002Frouting logic or equivalent ownership boundaries.\n- **Provider-neutral where appropriate**: avoid vendor-locking behavior in core domain layers. Keep provider-specific behavior under provider-owned modules.\n- **Decoupled**: minimize scattered conditionals by relying on typed behavior\u002Fconfiguration boundaries.\n- **Testable**: define deterministic validation, live validation where required, and false-green risks.\n- **Maintainable**: keep file ownership clear, avoid vague managers\u002Fabstractions, and prefer small concrete modules.\n- **Design-compressed**: when later evidence shows an existing code shape is too narrow, prefer reshaping that existing decision over adding a second nearby path.\n\nThe design document must answer:\n\n- What user\u002Fproblem outcome is being designed?\n- What current code\u002Fdocs\u002Fevidence are relevant?\n- What architecture and file ownership should be used?\n- What existing code or design decisions constrain this work?\n- Which existing assumptions might become too narrow because of this work?\n- What state, replay, lifecycle, UI, provider, or OS boundaries are affected?\n- What edge cases and failure modes matter?\n- What validation proves the design and later implementation?\n- What is explicitly out of scope?\n\n## Phase 3: Baseline design inventory\n\nBefore drafting the proposed design, create a `Baseline design inventory` section in `{{doc}}`.\n\nThis is mandatory. Do not skip it. Do not treat it as optional background research.\n\nThe inventory must list the existing design decisions in the current repo that constrain, shape, or risk being invalidated by the requested design.\n\nA baseline decision can come from:\n\n- current code structure;\n- current file or module ownership;\n- existing types, commands, tools, events, state, lifecycle hooks, provider boundaries, UI boundaries, or persistence paths;\n- prior design docs;\n- issue docs or validation probes;\n- git history for the target files when useful;\n- earlier implementation choices visible in the current code.\n\nFor every relevant existing decision, write one row in this format:\n\n| id | source | decision | location | current assumption | why it matters now | pressure signal |\n| --- | --- | --- | --- | --- | --- | --- |\n| B1 | existing code | Realtime requests enter Pi through `pi-realtime.request` custom messages instead of normal user messages | `.pi\u002Fextensions\u002Fpi-realtime\u002Fruntime.ts`, `.pi\u002Fextensions\u002Fpi-realtime\u002Fservice.ts` | Realtime-originated work must remain visibly distinct from typed user turns | The new design must preserve backend routing semantics | If the design adds another request route or wraps this path, review whether the original route should be widened instead |\n\nRules:\n\n1. `id` must be stable within the document: `B1`, `B2`, `B3`.\n2. `source` must name where the decision came from, such as `existing code`, `design doc`, `issue doc`, `validation probe`, or `git history`.\n3. `decision` must describe the actual design choice, not a vague topic.\n4. `location` must name concrete files, symbols, docs, or probes.\n5. `current assumption` must state what the existing design appears to believe.\n6. `why it matters now` must connect the existing decision to this requested design.\n7. `pressure signal` must say what kind of future finding would force this decision to be reviewed.\n\nIf no baseline decision is found, the design document must include a `Baseline design inventory` section with:\n\n- files\u002Fdocs\u002Fprobes inspected;\n- why none of them constrain the requested design;\n- what evidence would change that conclusion.\n\nDo not proceed to the main proposed design until this baseline section exists.\n\n## Phase 4: Iterative design loop\n\nIterate continuously through this loop until the design is semantically complete.\n\nEach iteration must include all six steps below. Do not skip the design compression review.\n\n### 1. Interrogate\n\nFor each iteration, formulate and answer the 5 most critical technical questions about the design.\n\nCover:\n\n- functional requirements;\n- architecture;\n- code ownership;\n- baseline decisions from the `Baseline design inventory`;\n- edge cases;\n- maintainability;\n- extensibility;\n- project standards;\n- validation;\n- known risks.\n\nAt least one question in each iteration must explicitly reference one or more baseline decision ids, such as `B1` or `B3`.\n\n### 2. Research\n\nInspect the codebase, docs, examples, design guides, validation probes, prior issue\u002Fdesign docs, and external docs if needed.\n\nDo not rely on memory when concrete file evidence is available.\n\nRecord the important files\u002Fdocs inspected inside the design document.\n\nWhen research touches a file, symbol, behavior, state path, provider path, lifecycle hook, command, or tool already named in the `Baseline design inventory`, record that connection in the design document.\n\n### 3. Synthesize\n\nIntegrate findings directly into `{{doc}}`:\n\n- design choices;\n- rejected alternatives;\n- API\u002Ftype\u002Fstate sketches when useful;\n- file-by-file implementation shape;\n- validation plan;\n- live-validation requirements and caveats;\n- risks and mitigations;\n- unresolved questions or blockers.\n\nEvery new proposed design choice that constrains implementation must be recorded in a `Proposed design decision ledger`.\n\nUse this format:\n\n| id | decision | location | reason | assumption | related baseline ids |\n| --- | --- | --- | --- | --- | --- |\n| D1 | Add a provider-neutral capture buffer service instead of putting capture state in the command handler | `.pi\u002Fextensions\u002Fpi-realtime\u002Fservice.ts`, `.pi\u002Fextensions\u002Fpi-realtime\u002Fruntime.ts` | Keeps command wiring separate from capture state | Capture buffering is core realtime domain behavior | B2, B4 |\n\nRules:\n\n1. `id` must be stable within the document: `D1`, `D2`, `D3`.\n2. `decision` must name the actual implementation-shaping choice.\n3. `location` must name concrete files, symbols, docs, or probes.\n4. `reason` must explain why this shape is better than a local patch.\n5. `assumption` must state what the proposed design depends on.\n6. `related baseline ids` must list every baseline decision this proposed choice touches. Use `none` only when the choice truly does not touch an existing decision.\n\n### 4. Design compression review\n\nThis step is mandatory in every iteration after synthesis.\n\nReview every row in:\n\n- `Baseline design inventory`;\n- `Proposed design decision ledger`.\n\nFor each row, answer these exact checks:\n\n1. Does the current proposed design touch the same `location`?\n2. Does the current proposed design reuse the same behavior, state, event, tool, command, provider boundary, UI boundary, lifecycle hook, or persistence path?\n3. Does the current proposed design make the recorded `current assumption` or `assumption` too narrow?\n4. Would keeping this decision force the implementation plan to add a new branch, helper, adapter, mode, fallback, wrapper, or parallel path near the same `location`?\n5. Would rewriting, splitting, or merging this decision make the final implementation smaller, clearer, or more consistent?\n\nFor every `yes`, add or update a `Compression review` section in `{{doc}}`.\n\nUse this format:\n\n| review id | decision id | trigger | finding | action | design update required |\n| --- | --- | --- | --- | --- | --- |\n| C1 | B2 | New command also needs capture text | Existing command-local capture shape would create a second capture path | rewrite | Move capture ownership into provider-neutral service before designing the command |\n\nThe `action` must be exactly one of:\n\n- `keep`: the existing or proposed decision still fits the final design.\n- `rewrite`: replace the decision with a broader or simpler design.\n- `split`: separate two responsibilities that were combined too early.\n- `merge`: fold the new behavior into an existing path instead of adding another path.\n- `defer`: leave the pressure unresolved, with the exact reason and risk named.\n\nOperational rules:\n\n1. If action is `rewrite`, `split`, or `merge`, update the proposed design before continuing to the next iteration.\n2. If action is `keep`, the finding must explain why the current shape still fits.\n3. If action is `defer`, the design must name the exact risk left for implementation or future work.\n4. Do not write vague findings like `reviewed`, `looks fine`, or `no issue`.\n5. Do not call the design complete while a compression review says `rewrite`, `split`, or `merge` and the document has not been updated to match that action.\n\n### 5. Reformat\n\nReview the whole design document for coherence.\n\nRestructure unclear sections so the document becomes the best possible draft so far, not a chronological scratchpad.\n\nThe baseline inventory, proposed decision ledger, and compression review must remain readable as durable design evidence. They may be reorganized, but they must not be deleted unless their content is replaced by an equally explicit section.\n\n### 6. Repeat\n\nContinue iterating until all are true:\n\n- the `{{minutes}}` minute floor has been met;\n- the `Baseline design inventory` exists and is grounded in inspected files\u002Fdocs\u002Fprobes;\n- the `Proposed design decision ledger` covers every implementation-shaping proposed decision;\n- the `Compression review` has evaluated every baseline and proposed decision touched by the final design;\n- every `rewrite`, `split`, or `merge` action has been reflected in the final proposed design;\n- the design document is complete, internally coherent, and strong enough to guide implementation without major architecture decisions left to the implementer.\n\n## Phase 5: Design document requirements\n\nWrite the final design document to:\n\n`{{doc}}`\n\nRecommended structure:\n\n1. `# Design: {{title}}`\n2. Intent \u002F problem statement.\n3. Scope and non-goals.\n4. Current evidence and inspected files.\n5. Baseline design inventory.\n6. Proposed behavior.\n7. Architecture and file ownership.\n8. Proposed design decision ledger.\n9. Compression review.\n10. State\u002Freplay\u002Flifecycle considerations if relevant.\n11. UI\u002Fcommand\u002Ftool\u002Fprovider\u002Fplatform considerations if relevant.\n12. Edge cases and failure modes.\n13. Validation plan.\n14. Implementation sequence or patch-shape guidance.\n15. Open questions \u002F decisions needed, if any.\n16. Completion audit against project guides.\n\nDo not include placeholder sections like `TODO`, `TBD`, or empty headings. If a section is not applicable, explicitly say why or omit it.\n\nThe `Baseline design inventory`, `Proposed design decision ledger`, and `Compression review` sections are not optional. If one of them has no rows, the section must explain why, using inspected evidence.\n\n## Phase 6: Final validation and closeout\n\nBefore marking the goal complete:\n\n1. Audit `{{doc}}` against:\n   - `AGENTS.md`;\n   - `.ai\u002Fdocs\u002Farchitecture-and-system-design-style.md` when present;\n   - `.ai\u002Fdocs\u002Fcode-style.md` when present;\n   - any workstream-specific docs discovered during research.\n2. Verify the document exists and has no placeholders:\n   - `test -f {{doc}}`\n   - `rg -n \"TODO|TBD|FIXME|placeholder\" {{doc}}` should find nothing unless discussing those words as concepts.\n3. Verify the document is visible or intentionally ignored according to repo policy:\n   - `git status --short --untracked-files=all`\n   - `git check-ignore -v {{doc}} || true`\n4. Verify that the design-compression sections exist:\n   - `rg -n \"Baseline design inventory|Proposed design decision ledger|Compression review\" {{doc}}`\n5. Verify that compression actions are resolved:\n   - No `rewrite`, `split`, or `merge` action may remain without a matching design update described in the document.\n   - Every `defer` action must name the risk, reason, and owner of the future decision.\n6. If the design proposes code changes, specify the exact validation gates a future implementation must run.\n7. Mark the goal complete only after all completion gates are met:\n   - minimum floor met;\n   - design semantically complete;\n   - baseline design inventory completed;\n   - proposed design decision ledger completed;\n   - compression review completed;\n   - unresolved compression actions either applied or explicitly deferred with risk.\n\nFinal response must include:\n\n- design doc path;\n- key design decisions;\n- baseline decisions reviewed;\n- compression actions taken;\n- files\u002Fdocs inspected;\n- validation\u002Fcheck commands run;\n- unresolved decisions, if any;\n- whether the document is tracked or ignored by git policy.\n\n---\nIMPORTANT:\n----\nDo not treat the minimum minute mark as a completion gate, instead of treat it as only the earliest possible wrap-up point.\n 1. Iterate until the design is actually high-quality and complete.\n 2. Use the N-minute floor only as a minimum eligibility check, not as a completion gate.\n 3. If the floor is met but the design still has unresolved structure, weak sections, missing research, or insufficient audit, keep going.\n 4. Only mark the goal complete after both are true:\n     - floor met\n     - design semantically complete\n\n The instruction “take all the time necessary” should override any impulse to stop at the minimum.\n",{"name":5,"usage":60,"aliases":61,"examples":62,"description":7,"allow_commands":63,"command_timeout_ms":64,"command_output_limit":65},"\u002Fgoal code-design --doc .ai\u002Fdocs\u002Frealtime-voice\u002Fdesign-feature-name.md --title \"Feature name\" --minutes 7 -- Describe the issue, feature, constraints, known files, and desired outcome","code-design,design-doc,iterative-design,architecture-design","\u002Fgoal code-design --doc .ai\u002Fdocs\u002Frealtime-voice\u002Fdesign-copy-capture-command.md --title \"Copy capture command\" --minutes 7 -- Design a command that copies the current capture buffer to the clipboard; \u002Fgoal iterative-design --doc .ai\u002Fdocs\u002Frealtime-voice\u002Fdesign-utterance-aggregation-delay.md --title \"Utterance aggregation delay\" --minutes 10 -- Design configurable transcript aggregation before capture\u002Fbackend routing",true,10000,30000,"main","c9d0c408715983e993b2f9ebffdbfa7f10153bcb","planning\u002Fcode-design",0,"https:\u002F\u002Fgithub.com\u002FNairon-AI\u002Fagentic-starter-pack","https:\u002F\u002Fgithub.com\u002FNairon-AI","https:\u002F\u002Fwww.naironai.com\u002F","Building the future of Work","2026-09-20 17:40:05",{"source":8,"skillName":5,"commands":76,"prompt":86,"zipAvailable":63},[77,80,83],{"tool":78,"command":79},"npx","npx skills add Nairon-AI\u002Fagentic-starter-pack --skill code-design",{"tool":81,"command":82},"bunx","bunx skills add Nairon-AI\u002Fagentic-starter-pack --skill code-design",{"tool":84,"command":85},"pnpm","pnpm dlx skills add Nairon-AI\u002Fagentic-starter-pack --skill code-design","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002FNairon-AI\u002Fagentic-starter-pack\u002Fblob\u002Fmain\u002Fplanning\u002Fcode-design\u002FSKILL.md",[],[89,122,144,165,185,206],{"skillNo":90,"name":91,"nameZh":6,"description":92,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":93,"categories":94,"keywords":101,"publishedAt":55},"01M6RBCG630Y8X99XWR9Q4GYNY","writing-shape","Take a markdown file of raw material and shape it into an article through a conversational session — drafting candidate openings, growing the piece paragraph by paragraph, arguing about format (lists, tables, callouts, quotes) at each step. Use when the user has a pile of notes, fragments, or a rough draft and wants help turning it into something publishable.","https:\u002F\u002Fgithub.com\u002FNairon-AI\u002Fagentic-starter-pack\u002Fblob\u002Fmain\u002Fwriting\u002Fwriting-shape\u002FSKILL.md",[95,98],{"categoryNo":96,"categoryName":97,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000018","写作与文案",{"categoryNo":99,"categoryName":100,"taxonomyType":29,"taxonomyTypeDesc":30},"01JBSEEDCAT000000000000036","内容创作者",[102,103,104,105,106,107,108,109,110,111,112,113,114,115,116,117,118,119,120,121],"writing","writing shape","shape","notes","help","file","markdown","format","session","use","take","draft","article","material","it","about","quotes","at","candidate","when",{"skillNo":123,"name":124,"nameZh":6,"description":125,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":126,"categories":127,"keywords":130,"publishedAt":55},"01M6RBCCCB1KMF01P5SYGFWBSW","writing-fragments","Grilling session that mines the user for fragments — heterogeneous nuggets of writing (claims, vignettes, sharp sentences, half-thoughts) — and appends them to a single document as raw material for a future article. Use when the user wants to develop ideas before imposing structure, or mentions \"fragments\", \"ideate\", or \"raw material\" for writing.","https:\u002F\u002Fgithub.com\u002FNairon-AI\u002Fagentic-starter-pack\u002Fblob\u002Fmain\u002Fwriting\u002Fwriting-fragments\u002FSKILL.md",[128,129],{"categoryNo":96,"categoryName":97,"taxonomyType":21,"taxonomyTypeDesc":22},{"categoryNo":99,"categoryName":100,"taxonomyType":29,"taxonomyTypeDesc":30},[102,131,132,133,134,135,110,111,136,137,138,114,139,115,140,141,142,143,121],"writing fragments","grilling","ideate","develop","user","document","structure","ideas","as","sharp","claims","for","single",{"skillNo":145,"name":146,"nameZh":6,"description":147,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":148,"categories":149,"keywords":152,"publishedAt":55},"01M6RBC8V7NHHKMTAZB4BPXVYQ","writing-beats","Shape an article as a journey of beats, choose-your-own-adventure style. The user picks a starting beat from the raw material, you write only that beat, then offer options for where to pivot next, beat by beat, until the article reaches a natural end. Use when the user has raw material and wants to assemble it as a narrative rather than an argument.","https:\u002F\u002Fgithub.com\u002FNairon-AI\u002Fagentic-starter-pack\u002Fblob\u002Fmain\u002Fwriting\u002Fwriting-beats\u002FSKILL.md",[150,151],{"categoryNo":96,"categoryName":97,"taxonomyType":21,"taxonomyTypeDesc":22},{"categoryNo":99,"categoryName":100,"taxonomyType":29,"taxonomyTypeDesc":30},[102,153,154,155,111,156,157,104,158,159,160,114,161,139,162,115,163,164,142,121],"writing beats","choose","write","assemble","only","journey","next","options","end","style","narrative","argument",{"skillNo":166,"name":167,"nameZh":6,"description":168,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":169,"categories":170,"keywords":173,"publishedAt":55},"01M6RBC58SG5Y5SC4ZV4ZNEFHC","stop-slop","Remove AI writing patterns from prose. Use when drafting, editing, or reviewing text to eliminate predictable AI tells.","https:\u002F\u002Fgithub.com\u002FNairon-AI\u002Fagentic-starter-pack\u002Fblob\u002Fmain\u002Fwriting\u002Fstop-slop\u002FSKILL.md",[171,172],{"categoryNo":96,"categoryName":97,"taxonomyType":21,"taxonomyTypeDesc":22},{"categoryNo":99,"categoryName":100,"taxonomyType":29,"taxonomyTypeDesc":30},[174,175,176,102,177,178,179,180,181,111,182,183,184,142,121],"stop","stop slop","slop","content","https","text","editing","remove","prose","patterns","drafts",{"skillNo":186,"name":187,"nameZh":6,"description":188,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":189,"categories":190,"keywords":193,"publishedAt":55},"01M6RBBJTTCJ7KZCP16G9JDFZH","humanizer","Remove signs of AI-generated writing from text. Use when editing or reviewing\ntext to make it sound more natural and human-written. Based on Wikipedia's\ncomprehensive \"Signs of AI writing\" guide. Detects and fixes patterns including:\ninflated symbolism, promotional language, superficial -ing analyses, vague\nattributions, em dash overuse, rule of three, AI vocabulary words, passive\nvoice, negative parallelisms, and filler phrases.","https:\u002F\u002Fgithub.com\u002FNairon-AI\u002Fagentic-starter-pack\u002Fblob\u002Fmain\u002Fwriting\u002Fhumanizer\u002FSKILL.md",[191,192],{"categoryNo":96,"categoryName":97,"taxonomyType":21,"taxonomyTypeDesc":22},{"categoryNo":99,"categoryName":100,"taxonomyType":29,"taxonomyTypeDesc":30},[187,102,36,194,179,195,155,196,197,181,198,199,183,200,201,202,203,204,205,121],"em dash","read","edit","generated","guide","opencode","three","human","make","wikipedia","vague","dash",{"skillNo":207,"name":208,"nameZh":6,"description":209,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":210,"categories":211,"keywords":212,"publishedAt":55},"01M6RBBEQKJ5HRH8AV9J85QB1T","feedback","Prepare, deliver, and debrief timely interpersonal feedback using a question-first coaching flow, observable behavior, owned experience, and concrete impact. Use when drafting feedback, coaching managers, rehearsing a feedback conversation, praising specific behavior, or reviewing whether feedback landed.","https:\u002F\u002Fgithub.com\u002FNairon-AI\u002Fagentic-starter-pack\u002Fblob\u002Fmain\u002Fwriting\u002Ffeedback\u002FSKILL.md",[],[208,213,214,215,216,217,111,218,219,220,221,222,121,223],"prepare","flow","first","question","behavior","conversation","coaching","debrief","impact","managers","deliver"]