[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M6C7FR7NSBAT2Z1MTSB7ARY1":3,"skill-same:01M6C7FR7NSBAT2Z1MTSB7ARY1":100},{"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":27,"publishedAt":34,"linkOnly":35,"markdownContent":36,"markdownBody":37,"frontMatter":38,"refName":39,"commitSha":40,"skillDirectory":41,"forksCount":42,"repositoryHtmlUrl":43,"repositoryHomepageUrl":6,"ownerHtmlUrl":44,"ownerBlogUrl":6,"ownerDescription":6,"updatedAt":45,"install":46,"resources":59},"01M6C7FR7NSBAT2Z1MTSB7ARY1","kspec-writing-specs",null,"Create and maintain specification items — modules, features, requirements, acceptance criteria, and traits. The source of truth for what to build.","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-writing-specs\u002FSKILL.md",[17,22],{"categoryNo":18,"categoryName":19,"taxonomyType":20,"taxonomyTypeDesc":21},"01JBSEEDCAT000000000000018","写作与文案","SCENARIO","使用场景",{"categoryNo":23,"categoryName":24,"taxonomyType":25,"taxonomyTypeDesc":26},"01JBSEEDCAT000000000000036","内容创作者","PROFESSION","适用职业",[28,29,30,31,32,33],"writing","writing specs","kspec writing specs","create","acceptance","modules","2026-11-10 10:12:30",false,"---\nname: kspec-writing-specs\ndescription: Create and maintain specification items — modules, features,\n  requirements, acceptance criteria, and traits. The source of truth for what to\n  build.\n---\n\u003C!-- kspec-managed -->\n# Writing Specs\n\nCreate and maintain specification items — the source of truth for what to build. This skill covers spec structure, writing good acceptance criteria, using traits, and organizing specs in the hierarchy.\n\n## When to Use\n\n- Creating a new feature, requirement, or constraint spec\n- Adding or refining acceptance criteria\n- Applying traits for cross-cutting behaviors\n- Organizing specs under the right module\u002Fparent\n- Reviewing spec quality before deriving tasks\n\n**Not for:** Task management (use `$kspec-task-work`), plan-to-spec translation (use `$kspec-plan`), or triage (use `$kspec-triage`).\n\n## Finding Things\n\nUse CLI commands to discover and inspect specs. **Do NOT search `.kspec\u002F` YAML files manually.**\n\n| Need                 | Command                           |\n| -------------------- | --------------------------------- |\n| View spec + all ACs  | `kspec item get @ref`             |\n| Search by keyword    | `kspec search \"keyword\"`          |\n| List by type         | `kspec item list --type feature`  |\n| All modules          | `kspec item list --type module`   |\n| All traits           | `kspec trait list`                |\n| Trait details + ACs  | `kspec item get @trait-slug`      |\n| Items under a parent | `kspec item list --under @parent` |\n\n## Core Principles\n\n1. **Spec defines WHAT, not HOW** — Describe the desired behavior, not the implementation\n2. **Every spec needs AC** — A spec without acceptance criteria is incomplete\n3. **Given\u002FWhen\u002FThen is testable** — Each AC should map to at least one test\n4. **Traits eliminate duplication** — Cross-cutting concerns belong in traits, not copied across specs\n5. **Use CLI, not YAML** — All changes through `kspec` commands for auto-commit\n\n## Spec Hierarchy\n\nSpecs live in modules and form a tree:\n\n```\nmodule (organizational grouping)\n├── feature (user-facing capability)\n│   ├── requirement (specific testable behavior)\n│   └── constraint (limitation or boundary)\n├── feature\n│   └── requirement\n└── decision (architectural choice, ADR-style)\n```\n\n### Choosing the Right Type\n\n| Type          | Use when                                       | Example                                                        |\n| ------------- | ---------------------------------------------- | -------------------------------------------------------------- |\n| `module`      | Grouping related features                      | \"CLI Commands\", \"Web UI\", \"Schema\"                             |\n| `feature`     | User-facing capability                         | \"JSON Export\", \"Inbox Triage\", \"Shadow Sync\"                   |\n| `requirement` | Specific testable behavior within a feature    | \"Export validates output format\", \"Triage records audit trail\" |\n| `constraint`  | Non-functional limit or boundary               | \"Response time \u003C 200ms\", \"Max 1000 items per module\"           |\n| `decision`    | Architectural choice with rationale            | \"Use YAML over JSON for spec files\"                            |\n| `trait`       | Reusable AC bundle for cross-cutting behaviors | \"JSON output mode\", \"Confirmation prompts\"                     |\n\n**Rule of thumb:** If it has acceptance criteria that a user could verify, it's a feature or requirement. If it constrains how something works, it's a constraint. If multiple specs need the same behavior, extract a trait.\n\n## Writing Acceptance Criteria\n\nAC are the heart of a spec. They define what \"done\" means.\n\n### Format\n\n```\nGiven: precondition (state before the action)\nWhen:  action (what triggers the behavior)\nThen:  outcome (observable, verifiable result)\n```\n\n### Good AC Patterns\n\n**Specific and testable:**\n\n```bash\nkspec item ac add @json-export \\\n  --given \"user has 3 tasks in project\" \\\n  --when \"user runs 'kspec tasks list --json'\" \\\n  --then \"stdout contains valid JSON array with 3 task objects\"\n```\n\n**Covers error cases:**\n\n```bash\nkspec item ac add @json-export \\\n  --given \"project has no tasks\" \\\n  --when \"user runs 'kspec tasks list --json'\" \\\n  --then \"stdout contains empty JSON array []\"\n```\n\n**Boundary behavior:**\n\n```bash\nkspec item ac add @bulk-delete \\\n  --given \"user passes 50 refs (maximum supported)\" \\\n  --when \"user runs bulk delete\" \\\n  --then \"all 50 items deleted in single operation\"\n```\n\n### AC Anti-patterns\n\n| Anti-pattern             | Problem            | Better                                              |\n| ------------------------ | ------------------ | --------------------------------------------------- |\n| \"System works correctly\" | Not testable       | Describe specific observable outcome                |\n| \"User is happy\"          | Subjective         | Describe what they can do or see                    |\n| \"Fast performance\"       | Not measurable     | \"Response returns within 200ms\"                     |\n| \"Handles errors\"         | Vague              | Specific error scenario + expected behavior         |\n| Duplicating trait AC     | Maintenance burden | Apply the trait instead                             |\n| Implementation details   | Not behavioral     | Describe observable outcome, not internal mechanism |\n| Rationale or commentary  | Not testable       | Move to description or implementation notes         |\n\n### Behavioral Language Rules\n\nSpecs are standalone behavioral contracts. They must read as timeless descriptions of what the system does, not how it's built. A spec should make sense to someone who has never seen the codebase.\n\n**ACs describe observable behavior, not implementation:**\nACs should describe what happens from the outside — what a user or consumer observes. They should not reveal how the system achieves the behavior internally. This includes internal field\u002Fvariable names, protocol details, internal function calls, file formats, library names, and architectural terms. Use natural language to describe the same concept.\n\nExamples of implementation leaking into ACs:\n\n- Internal field names (e.g. `record_id`, `event_count`) → \"record identifier\", \"event count\"\n- Protocol or transport names (e.g. specific RPC, message-bus, or socket protocol names) → describe the behavior they enable\n- Internal function or method calls (e.g. `client.action()`, `session.close()`) → \"the action is delivered\", \"the session closes\"\n- Internal file paths (e.g. `events.jsonl`) → \"the recorded event history\"\n\n**ACs contain only assertions, not rationale:**\nEach AC should state what happens, not why it happens or how it relates to other concerns. Rationale, design context, backward compatibility notes, and cross-references to other specs belong in the description or implementation notes — not in the given\u002Fwhen\u002Fthen.\n\nExamples of commentary leaking into ACs:\n\n- \"the request completes; this preserves backward compatibility\" → \"the request completes\"\n- \"per @other-spec\" → use `depends_on` or `relates_to` fields\n- \"unlike the previous behavior\" → just state the current behavior\n\n**Descriptions follow the same principles** — describe behavior and purpose, not implementation approach. Implementation guidance belongs in task descriptions or implementation notes.\n\n**Good:**\n\n```\nGiven: A user has an existing record\nWhen: The user runs the delete command\nThen: The record is removed and the deletion is confirmed\n```\n\n**Bad:**\n\n```\nGiven: store.records[id].state === \"active\" and no pending writes target it\nWhen: deleteRecord() resolves\nThen: store.records[id] is removed via the standard teardown sequence; this preserves backward compatibility\n```\n\n### AC Naming Convention\n\nAC IDs are auto-generated (`ac-1`, `ac-2`, ...) or can be explicit:\n\n```bash\n# Auto-generated\nkspec item ac add @feature --given \"...\" --when \"...\" --then \"...\"\n\n# Explicit ID for clarity\nkspec item ac add @feature --id ac-json-valid --given \"...\" --when \"...\" --then \"...\"\n```\n\n### How Many ACs?\n\n- **Minimum 1** — Every spec needs at least one\n- **Typical: 2-5** — Happy path + key error cases\n- **If 8+** — Consider splitting the spec into smaller requirements\n- **Each AC = one behavior** — Don't combine multiple verifiable outcomes\n\n## Working with Traits\n\nTraits are reusable bundles of acceptance criteria. When a spec implements a trait, it inherits all the trait's ACs.\n\nTraits are not shipped by `kspec init` — each project defines its own trait catalog. Always start by listing the project's traits before applying or extracting one.\n\n### When to Use Traits\n\nApply a trait when a spec needs a cross-cutting behavior that is already represented in the project's catalog:\n\n```bash\n# Discover the project's trait catalog\nkspec trait list\n\n# View trait details (shows ACs that will be inherited)\nkspec trait get @\u003Ctrait-slug>\n\n# Apply trait to spec\nkspec item trait add @my-spec @\u003Ctrait-slug>\n\n# Apply multiple traits\nkspec item trait add @my-spec @\u003Ctrait-slug-a> @\u003Ctrait-slug-b>\n```\n\n### Picking Traits\n\nScan the catalog returned by `kspec trait list` and look for traits whose cross-cutting behavior the spec implements. Typical categories you might see in a project's catalog include things like output formatting, destructive-operation prompts, filterable lists, error guidance, batch references, or shadow-state mutation. Use whatever traits the project defines — the catalog is project-specific.\n\n### Creating New Traits\n\nIf 3+ specs need the same cross-cutting behavior and no existing trait covers it, consider extracting a trait:\n\n```bash\n# Create the trait\nkspec trait add \"Trait Name\" --description \"Brief description of the cross-cutting behavior\" --slug \u003Ctrait-slug>\n\n# Add ACs to the trait\nkspec item ac add @\u003Ctrait-slug> --given \"...\" --when \"...\" --then \"...\"\n```\n\n### Trait AC Coverage\n\nWhen implementing specs with traits, all inherited ACs must be covered by tests:\n\n```javascript\n\u002F\u002F AC: @\u003Ctrait-slug> ac-1\nit('exhibits the trait-defined behavior', () => { ... });\n```\n\nRun `kspec validate` to check for uncovered trait ACs.\n\n## Creating Specs\n\n### New Feature Under a Module\n\n```bash\n# 1. Find the right parent module\nkspec item list --type module\n\n# 2. Create the feature\nkspec item add --under @cli-module --title \"Bulk Operations\" --type feature --slug bulk-ops\n\n# 3. Add description\nkspec item set @bulk-ops --description \"Support batch operations on multiple items in a single command\"\n\n# 4. Add acceptance criteria\nkspec item ac add @bulk-ops \\\n  --given \"user provides 3 item refs\" \\\n  --when \"user runs bulk delete\" \\\n  --then \"all 3 items deleted and confirmation shown\"\n\nkspec item ac add @bulk-ops \\\n  --given \"one of 3 refs is invalid\" \\\n  --when \"user runs bulk delete\" \\\n  --then \"error reported for invalid ref, valid refs still processed\"\n\n# 5. Apply relevant traits from the project's catalog (kspec trait list)\nkspec item trait add @bulk-ops @\u003Ctrait-slug-a> @\u003Ctrait-slug-b>\n\n# 6. Validate\nkspec validate\n```\n\n### Requirement Under a Feature\n\n```bash\nkspec item add --under @bulk-ops --title \"Ref validation in batch mode\" --type requirement --slug bulk-ref-validation\nkspec item ac add @bulk-ref-validation \\\n  --given \"batch contains mix of valid and invalid refs\" \\\n  --when \"batch executes\" \\\n  --then \"report lists each ref with success\u002Ffailure status\"\n```\n\n### Updating Existing Specs\n\n```bash\n# View current state\nkspec item get @feature-slug\n\n# Update description\nkspec item set @feature-slug --description \"Updated description\"\n\n# Add missing AC\nkspec item ac add @feature-slug --given \"...\" --when \"...\" --then \"...\"\n\n# Update existing AC\nkspec item ac set @feature-slug ac-2 --then \"updated expected outcome\"\n\n# Mark implementation status\nkspec item set @feature-slug --status implemented\n\n# Add relationships\nkspec item set @feature-slug --depends-on @other-feature\nkspec item set @feature-slug --relates-to @related-item\n```\n\n## Spec Quality Checklist\n\nBefore deriving a task from a spec, verify:\n\n- [ ] **Description** — Explains what and why (not how)\n- [ ] **AC coverage** — At least happy path + primary error case\n- [ ] **AC testability** — Each AC maps to a concrete test\n- [ ] **Traits applied** — Cross-cutting behaviors use traits, not duplicated AC\n- [ ] **Correct parent** — Placed under the right module\u002Ffeature\n- [ ] **No implementation details** — AC describes behavior, not code structure\n- [ ] **Validation passes** — `kspec validate` reports no errors for this item\n\n## Validation\n\n```bash\n# Full validation\nkspec validate\n\n# Completeness check\nkspec validate --completeness\n\n# Spec-task alignment\nkspec validate --alignment\n\n# Strict mode (warnings → errors)\nkspec validate --strict\n```\n\n**Exit codes:** `0` = success, `4` = errors, `6` = warnings only.\n\nValidation catches:\n\n- Missing acceptance criteria\n- Broken references (`@slug` pointing to nonexistent items)\n- Missing descriptions\n- Orphaned specs (no linked tasks)\n- Uncovered trait ACs\n\n## Command Reference\n\n### Item Management\n\n```bash\nkspec item list [--type \u003Ctype>]        # List items\nkspec item get \u003Cref>                   # Get item details with ACs and traits\nkspec item add --under \u003Cparent> --title \"...\" --type \u003Ctype> [--slug \u003Cslug>]\nkspec item set \u003Cref> --title \"...\"     # Update fields\nkspec item set \u003Cref> --description \"...\"\nkspec item set \u003Cref> --status \u003Cstatus> # implementation status\nkspec item set \u003Cref> --depends-on \u003Cref>\nkspec item set \u003Cref> --relates-to \u003Cref>\nkspec item patch \u003Cref> --data '{...}'  # Complex updates\nkspec item delete \u003Cref> [--force]\n```\n\n### Acceptance Criteria\n\n```bash\nkspec item ac list \u003Cref>               # List ACs for item\nkspec item ac add \u003Cref> --given \"...\" --when \"...\" --then \"...\"\nkspec item ac add \u003Cref> --id \u003Cid> --given \"...\" --when \"...\" --then \"...\"\nkspec item ac set \u003Cref> \u003Cac-id> --then \"updated\"\nkspec item ac remove \u003Cref> \u003Cid> [--force]\n```\n\n### Traits\n\n```bash\nkspec trait list                       # All traits with AC counts\nkspec trait get \u003Cref>                  # Trait details\nkspec trait add \"Name\" --description \"...\" [--slug \u003Cslug>]\nkspec item trait add \u003Cspec> \u003Ctrait> [\u003Ctrait2> ...]\nkspec item trait remove \u003Cspec> \u003Ctrait> [\u003Ctrait2> ...]\n```\n\n### Deriving Tasks\n\nOnce a spec is ready, derive a task to track implementation:\n\n```bash\nkspec derive @feature-slug             # Create task linked to spec\nkspec derive @feature-slug --priority 2\n```\n\nThe derived task gets `spec_ref: @feature-slug` automatically.\n\n## Integration\n\n- **`$kspec-plan`** — Plans create specs via import or manual creation\n- **`$kspec-task-work`** — Tasks reference specs; AC guides implementation\n- **`$kspec-triage`** — Inbox items may reveal spec gaps\n- **`$kspec-observe`** — Friction may indicate missing specs\n- **`$kspec-review`** — Reviews check AC coverage\n","\u003C!-- kspec-managed -->\n# Writing Specs\n\nCreate and maintain specification items — the source of truth for what to build. This skill covers spec structure, writing good acceptance criteria, using traits, and organizing specs in the hierarchy.\n\n## When to Use\n\n- Creating a new feature, requirement, or constraint spec\n- Adding or refining acceptance criteria\n- Applying traits for cross-cutting behaviors\n- Organizing specs under the right module\u002Fparent\n- Reviewing spec quality before deriving tasks\n\n**Not for:** Task management (use `$kspec-task-work`), plan-to-spec translation (use `$kspec-plan`), or triage (use `$kspec-triage`).\n\n## Finding Things\n\nUse CLI commands to discover and inspect specs. **Do NOT search `.kspec\u002F` YAML files manually.**\n\n| Need                 | Command                           |\n| -------------------- | --------------------------------- |\n| View spec + all ACs  | `kspec item get @ref`             |\n| Search by keyword    | `kspec search \"keyword\"`          |\n| List by type         | `kspec item list --type feature`  |\n| All modules          | `kspec item list --type module`   |\n| All traits           | `kspec trait list`                |\n| Trait details + ACs  | `kspec item get @trait-slug`      |\n| Items under a parent | `kspec item list --under @parent` |\n\n## Core Principles\n\n1. **Spec defines WHAT, not HOW** — Describe the desired behavior, not the implementation\n2. **Every spec needs AC** — A spec without acceptance criteria is incomplete\n3. **Given\u002FWhen\u002FThen is testable** — Each AC should map to at least one test\n4. **Traits eliminate duplication** — Cross-cutting concerns belong in traits, not copied across specs\n5. **Use CLI, not YAML** — All changes through `kspec` commands for auto-commit\n\n## Spec Hierarchy\n\nSpecs live in modules and form a tree:\n\n```\nmodule (organizational grouping)\n├── feature (user-facing capability)\n│   ├── requirement (specific testable behavior)\n│   └── constraint (limitation or boundary)\n├── feature\n│   └── requirement\n└── decision (architectural choice, ADR-style)\n```\n\n### Choosing the Right Type\n\n| Type          | Use when                                       | Example                                                        |\n| ------------- | ---------------------------------------------- | -------------------------------------------------------------- |\n| `module`      | Grouping related features                      | \"CLI Commands\", \"Web UI\", \"Schema\"                             |\n| `feature`     | User-facing capability                         | \"JSON Export\", \"Inbox Triage\", \"Shadow Sync\"                   |\n| `requirement` | Specific testable behavior within a feature    | \"Export validates output format\", \"Triage records audit trail\" |\n| `constraint`  | Non-functional limit or boundary               | \"Response time \u003C 200ms\", \"Max 1000 items per module\"           |\n| `decision`    | Architectural choice with rationale            | \"Use YAML over JSON for spec files\"                            |\n| `trait`       | Reusable AC bundle for cross-cutting behaviors | \"JSON output mode\", \"Confirmation prompts\"                     |\n\n**Rule of thumb:** If it has acceptance criteria that a user could verify, it's a feature or requirement. If it constrains how something works, it's a constraint. If multiple specs need the same behavior, extract a trait.\n\n## Writing Acceptance Criteria\n\nAC are the heart of a spec. They define what \"done\" means.\n\n### Format\n\n```\nGiven: precondition (state before the action)\nWhen:  action (what triggers the behavior)\nThen:  outcome (observable, verifiable result)\n```\n\n### Good AC Patterns\n\n**Specific and testable:**\n\n```bash\nkspec item ac add @json-export \\\n  --given \"user has 3 tasks in project\" \\\n  --when \"user runs 'kspec tasks list --json'\" \\\n  --then \"stdout contains valid JSON array with 3 task objects\"\n```\n\n**Covers error cases:**\n\n```bash\nkspec item ac add @json-export \\\n  --given \"project has no tasks\" \\\n  --when \"user runs 'kspec tasks list --json'\" \\\n  --then \"stdout contains empty JSON array []\"\n```\n\n**Boundary behavior:**\n\n```bash\nkspec item ac add @bulk-delete \\\n  --given \"user passes 50 refs (maximum supported)\" \\\n  --when \"user runs bulk delete\" \\\n  --then \"all 50 items deleted in single operation\"\n```\n\n### AC Anti-patterns\n\n| Anti-pattern             | Problem            | Better                                              |\n| ------------------------ | ------------------ | --------------------------------------------------- |\n| \"System works correctly\" | Not testable       | Describe specific observable outcome                |\n| \"User is happy\"          | Subjective         | Describe what they can do or see                    |\n| \"Fast performance\"       | Not measurable     | \"Response returns within 200ms\"                     |\n| \"Handles errors\"         | Vague              | Specific error scenario + expected behavior         |\n| Duplicating trait AC     | Maintenance burden | Apply the trait instead                             |\n| Implementation details   | Not behavioral     | Describe observable outcome, not internal mechanism |\n| Rationale or commentary  | Not testable       | Move to description or implementation notes         |\n\n### Behavioral Language Rules\n\nSpecs are standalone behavioral contracts. They must read as timeless descriptions of what the system does, not how it's built. A spec should make sense to someone who has never seen the codebase.\n\n**ACs describe observable behavior, not implementation:**\nACs should describe what happens from the outside — what a user or consumer observes. They should not reveal how the system achieves the behavior internally. This includes internal field\u002Fvariable names, protocol details, internal function calls, file formats, library names, and architectural terms. Use natural language to describe the same concept.\n\nExamples of implementation leaking into ACs:\n\n- Internal field names (e.g. `record_id`, `event_count`) → \"record identifier\", \"event count\"\n- Protocol or transport names (e.g. specific RPC, message-bus, or socket protocol names) → describe the behavior they enable\n- Internal function or method calls (e.g. `client.action()`, `session.close()`) → \"the action is delivered\", \"the session closes\"\n- Internal file paths (e.g. `events.jsonl`) → \"the recorded event history\"\n\n**ACs contain only assertions, not rationale:**\nEach AC should state what happens, not why it happens or how it relates to other concerns. Rationale, design context, backward compatibility notes, and cross-references to other specs belong in the description or implementation notes — not in the given\u002Fwhen\u002Fthen.\n\nExamples of commentary leaking into ACs:\n\n- \"the request completes; this preserves backward compatibility\" → \"the request completes\"\n- \"per @other-spec\" → use `depends_on` or `relates_to` fields\n- \"unlike the previous behavior\" → just state the current behavior\n\n**Descriptions follow the same principles** — describe behavior and purpose, not implementation approach. Implementation guidance belongs in task descriptions or implementation notes.\n\n**Good:**\n\n```\nGiven: A user has an existing record\nWhen: The user runs the delete command\nThen: The record is removed and the deletion is confirmed\n```\n\n**Bad:**\n\n```\nGiven: store.records[id].state === \"active\" and no pending writes target it\nWhen: deleteRecord() resolves\nThen: store.records[id] is removed via the standard teardown sequence; this preserves backward compatibility\n```\n\n### AC Naming Convention\n\nAC IDs are auto-generated (`ac-1`, `ac-2`, ...) or can be explicit:\n\n```bash\n# Auto-generated\nkspec item ac add @feature --given \"...\" --when \"...\" --then \"...\"\n\n# Explicit ID for clarity\nkspec item ac add @feature --id ac-json-valid --given \"...\" --when \"...\" --then \"...\"\n```\n\n### How Many ACs?\n\n- **Minimum 1** — Every spec needs at least one\n- **Typical: 2-5** — Happy path + key error cases\n- **If 8+** — Consider splitting the spec into smaller requirements\n- **Each AC = one behavior** — Don't combine multiple verifiable outcomes\n\n## Working with Traits\n\nTraits are reusable bundles of acceptance criteria. When a spec implements a trait, it inherits all the trait's ACs.\n\nTraits are not shipped by `kspec init` — each project defines its own trait catalog. Always start by listing the project's traits before applying or extracting one.\n\n### When to Use Traits\n\nApply a trait when a spec needs a cross-cutting behavior that is already represented in the project's catalog:\n\n```bash\n# Discover the project's trait catalog\nkspec trait list\n\n# View trait details (shows ACs that will be inherited)\nkspec trait get @\u003Ctrait-slug>\n\n# Apply trait to spec\nkspec item trait add @my-spec @\u003Ctrait-slug>\n\n# Apply multiple traits\nkspec item trait add @my-spec @\u003Ctrait-slug-a> @\u003Ctrait-slug-b>\n```\n\n### Picking Traits\n\nScan the catalog returned by `kspec trait list` and look for traits whose cross-cutting behavior the spec implements. Typical categories you might see in a project's catalog include things like output formatting, destructive-operation prompts, filterable lists, error guidance, batch references, or shadow-state mutation. Use whatever traits the project defines — the catalog is project-specific.\n\n### Creating New Traits\n\nIf 3+ specs need the same cross-cutting behavior and no existing trait covers it, consider extracting a trait:\n\n```bash\n# Create the trait\nkspec trait add \"Trait Name\" --description \"Brief description of the cross-cutting behavior\" --slug \u003Ctrait-slug>\n\n# Add ACs to the trait\nkspec item ac add @\u003Ctrait-slug> --given \"...\" --when \"...\" --then \"...\"\n```\n\n### Trait AC Coverage\n\nWhen implementing specs with traits, all inherited ACs must be covered by tests:\n\n```javascript\n\u002F\u002F AC: @\u003Ctrait-slug> ac-1\nit('exhibits the trait-defined behavior', () => { ... });\n```\n\nRun `kspec validate` to check for uncovered trait ACs.\n\n## Creating Specs\n\n### New Feature Under a Module\n\n```bash\n# 1. Find the right parent module\nkspec item list --type module\n\n# 2. Create the feature\nkspec item add --under @cli-module --title \"Bulk Operations\" --type feature --slug bulk-ops\n\n# 3. Add description\nkspec item set @bulk-ops --description \"Support batch operations on multiple items in a single command\"\n\n# 4. Add acceptance criteria\nkspec item ac add @bulk-ops \\\n  --given \"user provides 3 item refs\" \\\n  --when \"user runs bulk delete\" \\\n  --then \"all 3 items deleted and confirmation shown\"\n\nkspec item ac add @bulk-ops \\\n  --given \"one of 3 refs is invalid\" \\\n  --when \"user runs bulk delete\" \\\n  --then \"error reported for invalid ref, valid refs still processed\"\n\n# 5. Apply relevant traits from the project's catalog (kspec trait list)\nkspec item trait add @bulk-ops @\u003Ctrait-slug-a> @\u003Ctrait-slug-b>\n\n# 6. Validate\nkspec validate\n```\n\n### Requirement Under a Feature\n\n```bash\nkspec item add --under @bulk-ops --title \"Ref validation in batch mode\" --type requirement --slug bulk-ref-validation\nkspec item ac add @bulk-ref-validation \\\n  --given \"batch contains mix of valid and invalid refs\" \\\n  --when \"batch executes\" \\\n  --then \"report lists each ref with success\u002Ffailure status\"\n```\n\n### Updating Existing Specs\n\n```bash\n# View current state\nkspec item get @feature-slug\n\n# Update description\nkspec item set @feature-slug --description \"Updated description\"\n\n# Add missing AC\nkspec item ac add @feature-slug --given \"...\" --when \"...\" --then \"...\"\n\n# Update existing AC\nkspec item ac set @feature-slug ac-2 --then \"updated expected outcome\"\n\n# Mark implementation status\nkspec item set @feature-slug --status implemented\n\n# Add relationships\nkspec item set @feature-slug --depends-on @other-feature\nkspec item set @feature-slug --relates-to @related-item\n```\n\n## Spec Quality Checklist\n\nBefore deriving a task from a spec, verify:\n\n- [ ] **Description** — Explains what and why (not how)\n- [ ] **AC coverage** — At least happy path + primary error case\n- [ ] **AC testability** — Each AC maps to a concrete test\n- [ ] **Traits applied** — Cross-cutting behaviors use traits, not duplicated AC\n- [ ] **Correct parent** — Placed under the right module\u002Ffeature\n- [ ] **No implementation details** — AC describes behavior, not code structure\n- [ ] **Validation passes** — `kspec validate` reports no errors for this item\n\n## Validation\n\n```bash\n# Full validation\nkspec validate\n\n# Completeness check\nkspec validate --completeness\n\n# Spec-task alignment\nkspec validate --alignment\n\n# Strict mode (warnings → errors)\nkspec validate --strict\n```\n\n**Exit codes:** `0` = success, `4` = errors, `6` = warnings only.\n\nValidation catches:\n\n- Missing acceptance criteria\n- Broken references (`@slug` pointing to nonexistent items)\n- Missing descriptions\n- Orphaned specs (no linked tasks)\n- Uncovered trait ACs\n\n## Command Reference\n\n### Item Management\n\n```bash\nkspec item list [--type \u003Ctype>]        # List items\nkspec item get \u003Cref>                   # Get item details with ACs and traits\nkspec item add --under \u003Cparent> --title \"...\" --type \u003Ctype> [--slug \u003Cslug>]\nkspec item set \u003Cref> --title \"...\"     # Update fields\nkspec item set \u003Cref> --description \"...\"\nkspec item set \u003Cref> --status \u003Cstatus> # implementation status\nkspec item set \u003Cref> --depends-on \u003Cref>\nkspec item set \u003Cref> --relates-to \u003Cref>\nkspec item patch \u003Cref> --data '{...}'  # Complex updates\nkspec item delete \u003Cref> [--force]\n```\n\n### Acceptance Criteria\n\n```bash\nkspec item ac list \u003Cref>               # List ACs for item\nkspec item ac add \u003Cref> --given \"...\" --when \"...\" --then \"...\"\nkspec item ac add \u003Cref> --id \u003Cid> --given \"...\" --when \"...\" --then \"...\"\nkspec item ac set \u003Cref> \u003Cac-id> --then \"updated\"\nkspec item ac remove \u003Cref> \u003Cid> [--force]\n```\n\n### Traits\n\n```bash\nkspec trait list                       # All traits with AC counts\nkspec trait get \u003Cref>                  # Trait details\nkspec trait add \"Name\" --description \"...\" [--slug \u003Cslug>]\nkspec item trait add \u003Cspec> \u003Ctrait> [\u003Ctrait2> ...]\nkspec item trait remove \u003Cspec> \u003Ctrait> [\u003Ctrait2> ...]\n```\n\n### Deriving Tasks\n\nOnce a spec is ready, derive a task to track implementation:\n\n```bash\nkspec derive @feature-slug             # Create task linked to spec\nkspec derive @feature-slug --priority 2\n```\n\nThe derived task gets `spec_ref: @feature-slug` automatically.\n\n## Integration\n\n- **`$kspec-plan`** — Plans create specs via import or manual creation\n- **`$kspec-task-work`** — Tasks reference specs; AC guides implementation\n- **`$kspec-triage`** — Inbox items may reveal spec gaps\n- **`$kspec-observe`** — Friction may indicate missing specs\n- **`$kspec-review`** — Reviews check AC coverage\n",{"name":5,"description":7},"main","c4b0de3035f8512bba7eb0a9b4e39ea2fbd3f08e",".agents\u002Fskills\u002Fkspec-writing-specs",2,"https:\u002F\u002Fgithub.com\u002Flepahc\u002Fkynetic-spec","https:\u002F\u002Fgithub.com\u002Flepahc","2026-07-22 18:57:40",{"source":8,"skillName":5,"commands":47,"prompt":57,"zipAvailable":58},[48,51,54],{"tool":49,"command":50},"npx","npx skills add lepahc\u002Fkynetic-spec --skill kspec-writing-specs",{"tool":52,"command":53},"bunx","bunx skills add lepahc\u002Fkynetic-spec --skill kspec-writing-specs",{"tool":55,"command":56},"pnpm","pnpm dlx skills add lepahc\u002Fkynetic-spec --skill kspec-writing-specs","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Flepahc\u002Fkynetic-spec\u002Fblob\u002Fmain\u002F.agents\u002Fskills\u002Fkspec-writing-specs\u002FSKILL.md",true,[60,66,70,74,80,84,88,92,96],{"path":61,"resourceType":62,"resourceTypeDesc":63,"sizeBytes":64,"sourceHtmlUrl":65},"references\u002Fhelius-api.md","REFERENCE","参考文档",5038,"https:\u002F\u002Fgithub.com\u002Fjiayaoqijia\u002Fcryptoskill\u002Fblob\u002Fmain\u002Fskills\u002Fai-crypto\u002Fxspoonai-official-solana-toolkit\u002Freferences\u002Fhelius-api.md",{"path":67,"resourceType":62,"resourceTypeDesc":63,"sizeBytes":68,"sourceHtmlUrl":69},"references\u002Fjupiter.md",5796,"https:\u002F\u002Fgithub.com\u002Fjiayaoqijia\u002Fcryptoskill\u002Fblob\u002Fmain\u002Fskills\u002Fai-crypto\u002Fxspoonai-official-solana-toolkit\u002Freferences\u002Fjupiter.md",{"path":71,"resourceType":62,"resourceTypeDesc":63,"sizeBytes":72,"sourceHtmlUrl":73},"references\u002Fsecurity.md",5566,"https:\u002F\u002Fgithub.com\u002Fjiayaoqijia\u002Fcryptoskill\u002Fblob\u002Fmain\u002Fskills\u002Fai-crypto\u002Fxspoonai-official-solana-toolkit\u002Freferences\u002Fsecurity.md",{"path":75,"resourceType":76,"resourceTypeDesc":77,"sizeBytes":78,"sourceHtmlUrl":79},"scripts\u002Fconfig.ts","SCRIPT","脚本",1654,"https:\u002F\u002Fgithub.com\u002Fjiayaoqijia\u002Fcryptoskill\u002Fblob\u002Fmain\u002Fskills\u002Fai-crypto\u002Fxspoonai-official-solana-toolkit\u002Fscripts\u002Fconfig.ts",{"path":81,"resourceType":76,"resourceTypeDesc":77,"sizeBytes":82,"sourceHtmlUrl":83},"scripts\u002Fsend.ts",6962,"https:\u002F\u002Fgithub.com\u002Fjiayaoqijia\u002Fcryptoskill\u002Fblob\u002Fmain\u002Fskills\u002Fai-crypto\u002Fxspoonai-official-solana-toolkit\u002Fscripts\u002Fsend.ts",{"path":85,"resourceType":76,"resourceTypeDesc":77,"sizeBytes":86,"sourceHtmlUrl":87},"scripts\u002Fswap.ts",8788,"https:\u002F\u002Fgithub.com\u002Fjiayaoqijia\u002Fcryptoskill\u002Fblob\u002Fmain\u002Fskills\u002Fai-crypto\u002Fxspoonai-official-solana-toolkit\u002Fscripts\u002Fswap.ts",{"path":89,"resourceType":76,"resourceTypeDesc":77,"sizeBytes":90,"sourceHtmlUrl":91},"scripts\u002Fwallet.ts",8655,"https:\u002F\u002Fgithub.com\u002Fjiayaoqijia\u002Fcryptoskill\u002Fblob\u002Fmain\u002Fskills\u002Fai-crypto\u002Fxspoonai-official-solana-toolkit\u002Fscripts\u002Fwallet.ts",{"path":93,"resourceType":62,"resourceTypeDesc":63,"sizeBytes":94,"sourceHtmlUrl":95},"SOURCE.md",371,"https:\u002F\u002Fgithub.com\u002Fjiayaoqijia\u002Fcryptoskill\u002Fblob\u002Fmain\u002Fskills\u002Fai-crypto\u002Fxspoonai-official-solana-toolkit\u002FSOURCE.md",{"path":97,"resourceType":62,"resourceTypeDesc":63,"sizeBytes":98,"sourceHtmlUrl":99},"TRUST.auto.yaml",2320,"https:\u002F\u002Fgithub.com\u002Fjiayaoqijia\u002Fcryptoskill\u002Fblob\u002Fmain\u002Fskills\u002Fai-crypto\u002Fxspoonai-official-solana-toolkit\u002FTRUST.auto.yaml",[101,109,115,123,134,142],{"skillNo":102,"name":103,"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":104,"categories":105,"keywords":108,"publishedAt":34},"01M6C7KCZE43MDZ74FV3A5TDCQ","writing-specs","https:\u002F\u002Fgithub.com\u002Flepahc\u002Fkynetic-spec\u002Fblob\u002Fmain\u002Ftemplates\u002Fskills\u002Fwriting-specs\u002FSKILL.md",[106,107],{"categoryNo":18,"categoryName":19,"taxonomyType":20,"taxonomyTypeDesc":21},{"categoryNo":23,"categoryName":24,"taxonomyType":25,"taxonomyTypeDesc":26},[28,29],{"skillNo":110,"name":111,"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":112,"categories":113,"keywords":114,"publishedAt":34},"01M6C7KAK9CBJ87PX3BCW7B7YG","triage","https:\u002F\u002Fgithub.com\u002Flepahc\u002Fkynetic-spec\u002Fblob\u002Fmain\u002Ftemplates\u002Fskills\u002Ftriage\u002FSKILL.md",[],[111],{"skillNo":116,"name":117,"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":118,"categories":119,"keywords":120,"publishedAt":34},"01M6C7K89VN6FJCT8M86K56EE8","triage-inbox","https:\u002F\u002Fgithub.com\u002Flepahc\u002Fkynetic-spec\u002Fblob\u002Fmain\u002Ftemplates\u002Fskills\u002Ftriage-inbox\u002FSKILL.md",[],[111,121,122],"inbox","triage inbox",{"skillNo":124,"name":125,"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":126,"categories":127,"keywords":131,"publishedAt":34},"01M6C7K6F2342AC1TJCN9PM0ZB","triage-automation","https:\u002F\u002Fgithub.com\u002Flepahc\u002Fkynetic-spec\u002Fblob\u002Fmain\u002Ftemplates\u002Fskills\u002Ftriage-automation\u002FSKILL.md",[128],{"categoryNo":129,"categoryName":130,"taxonomyType":20,"taxonomyTypeDesc":21},"01JBSEEDCAT000000000000023","Skill与智能体开发",[111,132,133],"automation","triage automation",{"skillNo":135,"name":136,"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":137,"categories":138,"keywords":139,"publishedAt":34},"01M6C7K3TFQ88QQBW3PXYDHQG2","task-work","https:\u002F\u002Fgithub.com\u002Flepahc\u002Fkynetic-spec\u002Fblob\u002Fmain\u002Ftemplates\u002Fskills\u002Ftask-work\u002FSKILL.md",[],[140,141],"work","task work",{"skillNo":143,"name":144,"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":145,"categories":146,"keywords":147,"publishedAt":34},"01M6C7K168CH3XJCC3PDGA9H6C","review","https:\u002F\u002Fgithub.com\u002Flepahc\u002Fkynetic-spec\u002Fblob\u002Fmain\u002Ftemplates\u002Fskills\u002Freview\u002FSKILL.md",[],[144]]