[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M6M9G1RE28Z9SBFQS1755DEP":3,"skill-same:01M6M9G1RE28Z9SBFQS1755DEP":81},{"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":31,"publishedAt":52,"linkOnly":53,"markdownContent":54,"markdownBody":55,"frontMatter":56,"refName":57,"commitSha":58,"skillDirectory":59,"forksCount":60,"repositoryHtmlUrl":61,"repositoryHomepageUrl":62,"ownerHtmlUrl":63,"ownerBlogUrl":64,"ownerDescription":65,"updatedAt":66,"install":67,"resources":80},"01M6M9G1RE28Z9SBFQS1755DEP","blueprint-writing",null,"How to write Blueprint-quality blueprints that AI agents can consume effectively. Covers\nimplementation-agnostic blueprint design, testable acceptance criteria, hierarchical structure,\ncross-referencing, blueprint templates, greenfield and rewrite patterns, blueprint compaction, and gap analysis.\nTrigger phrases: \"write blueprints\", \"create blueprints\", \"blueprint this out\",\n\"define requirements for agents\", \"how to write blueprints for AI\"","hashgraph-online\u002Fawesome-codex-plugins","hashgraph-online","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F160371962?v=4","01M6CNB6NRJVNNGN14TR01Q6D3","HOL (Hashgraph Online)","01M6JT1HSKKG9V68KQAQGBA7XP",1575,"Apache-2.0","https:\u002F\u002Fgithub.com\u002Fhashgraph-online\u002Fawesome-codex-plugins\u002Fblob\u002Fmain\u002Fplugins\u002FJuliusBrussee\u002Fblueprint\u002Fskills\u002Fblueprint-writing\u002FSKILL.md",[18,23,26],{"categoryNo":19,"categoryName":20,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000015","视觉设计","SCENARIO","使用场景",{"categoryNo":24,"categoryName":25,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000018","写作与文案",{"categoryNo":27,"categoryName":28,"taxonomyType":29,"taxonomyTypeDesc":30},"01JBSEEDCAT000000000000036","内容创作者","PROFESSION","适用职业",[32,33,34,35,36,37,38,39,40,41,42,43,44,45,46,47,48,49,50,51],"writing","blueprint writing","Blueprint","requirements","design","for","compaction","how to","rewrite","gap analysis","trigger","define","create","structure","patterns","ai agents","write","how","analysis","acceptance","2026-11-10 10:12:30",false,"---\nname: blueprint-writing\ndescription: |\n  How to write Blueprint-quality blueprints that AI agents can consume effectively. Covers\n  implementation-agnostic blueprint design, testable acceptance criteria, hierarchical structure,\n  cross-referencing, blueprint templates, greenfield and rewrite patterns, blueprint compaction, and gap analysis.\n  Trigger phrases: \"write blueprints\", \"create blueprints\", \"blueprint this out\",\n  \"define requirements for agents\", \"how to write blueprints for AI\"\n---\n\n# Blueprint Writing\n\n## Core Principle: Blueprints Describe WHAT, Not HOW\n\nBlueprints are **implementation-agnostic**. They define what the system must do and how to verify it, but never prescribe a specific framework, language, or architecture.\n\nThis is the fundamental distinction in Blueprint:\n- **Blueprints** = WHAT must be true (framework-agnostic, durable, portable)\n- **Plans** = HOW to build it (framework-specific, derived from blueprints)\n- **Code** = the implementation (generated from plans, validated against blueprints)\n\n### Why Implementation-Agnostic?\n\nWhen blueprints avoid prescribing HOW, they become:\n- **Portable** — the same blueprints can drive implementations in different frameworks\n- **Durable** — blueprints survive technology migrations\n- **Testable** — acceptance criteria are about behavior, not implementation details\n- **Reusable** — the same blueprints work for greenfield, rewrites, and cross-framework evaluation\n\n**Bad blueprint requirement:** \"Use React useState hook to manage form state\"\n**Good blueprint requirement:** \"Form state persists across user interactions within a session. Acceptance: entering values, navigating away, and returning preserves all entered values.\"\n\n---\n\n## Every Requirement Needs Testable Acceptance Criteria\n\nThis is the single most important rule in Blueprint writing. If an agent cannot automatically validate a requirement, that requirement will not be met.\n\n### The Validation-First Rule\n\nEvery requirement must answer: **\"How would an automated test verify this?\"**\n\n| Weak Criterion | Strong Criterion |\n|----------------|-----------------|\n| \"UI should look good\" | \"All interactive elements have minimum 44x44px touch targets\" |\n| \"System should be fast\" | \"API responses return within 200ms at p95 under 100 concurrent users\" |\n| \"Handle errors gracefully\" | \"Network failures display a retry prompt with exponential backoff (1s, 2s, 4s)\" |\n| \"Support authentication\" | \"Valid credentials return a session token; invalid credentials return 401 with error message\" |\n\n### Acceptance Criteria Format\n\nEach criterion should be:\n- **Observable** — can be checked by reading output, UI state, or logs\n- **Deterministic** — same input always produces same pass\u002Ffail result\n- **Automatable** — an agent can write a test that checks this\n- **Independent** — does not depend on subjective judgment\n\n```markdown\n**Acceptance Criteria:**\n- [ ] {Action} results in {observable outcome}\n- [ ] Given {precondition}, when {action}, then {result}\n- [ ] {Metric} meets {threshold} under {conditions}\n```\n\n---\n\n## Hierarchical Structure with Index\n\nBlueprints must be organized as a hierarchy — one index file linking to domain-specific sub-blueprints. This enables progressive disclosure: agents read the index first, then only the sub-blueprints relevant to their task.\n\n### The Blueprint Index Pattern\n\nCreate a `blueprint-overview.md` as the entry point:\n\n```markdown\n# Blueprint Overview\n\n## Domains\n\n| Domain | Blueprint File | Summary |\n|--------|-----------|---------|\n| Authentication | blueprint-auth.md | User registration, login, session management, OAuth |\n| Data Models | blueprint-data-models.md | Core entities, relationships, validation rules |\n| API | blueprint-api.md | REST endpoints, request\u002Fresponse formats, error handling |\n| UI Components | blueprint-ui-components.md | Shared components, accessibility, responsive behavior |\n| Notifications | blueprint-notifications.md | Email, push, in-app notification delivery |\n\n## Cross-Cutting Concerns\n- Security requirements: see blueprint-auth.md R3, blueprint-api.md R7\n- Performance budgets: see blueprint-api.md R12, blueprint-ui-components.md R5\n- Accessibility: see blueprint-ui-components.md R8-R10\n```\n\n### Why Hierarchical?\n\n1. **Context window efficiency** — agents load only the domains they need\n2. **Parallel work** — different agents can own different spec domains\n3. **Review efficiency** — humans can review domain-by-domain\n4. **Cross-referencing** — domains link to each other explicitly\n\n---\n\n## Cross-Referencing Between Blueprints\n\nRelated blueprints must link to each other. Cross-references prevent requirements from being lost at domain boundaries.\n\n### Cross-Reference Patterns\n\n```markdown\n## Cross-References\n- **Depends on:** blueprint-auth.md R1 (session tokens required for API access)\n- **Depended on by:** blueprint-notifications.md R4 (uses user preferences from this blueprint)\n- **Related:** blueprint-ui-components.md R6 (error display components used by this domain)\n```\n\n### When to Cross-Reference\n\n- When one domain's requirement depends on another domain's output\n- When shared entities are defined in one blueprint but used in many\n- When validation criteria span multiple domains\n- When out-of-scope items are in-scope for another blueprint\n\n---\n\n## Full Blueprint Format Template\n\nUse this template for every domain blueprint:\n\n```markdown\n# Blueprint: {Domain Name}\n\n## Scope\n{One paragraph describing what this spec covers and its boundaries.}\n\n## Requirements\n\n### R1: {Requirement Name}\n**Description:** {What must be true — stated in terms of behavior, not implementation.}\n**Acceptance Criteria:**\n- [ ] {Testable criterion 1}\n- [ ] {Testable criterion 2}\n- [ ] {Testable criterion 3}\n**Dependencies:** {Other specs\u002Frequirements this depends on, or \"None\"}\n\n### R2: {Requirement Name}\n**Description:** {What must be true}\n**Acceptance Criteria:**\n- [ ] {Testable criterion 1}\n- [ ] {Testable criterion 2}\n**Dependencies:** {Dependencies}\n\n### R3: ...\n\n## Out of Scope\n{Explicit list of things this blueprint does NOT cover. This is critical — it prevents\nagents from over-building and clarifies domain boundaries.}\n- {Thing explicitly excluded and why}\n- {Another exclusion}\n\n## Cross-References\n- See also: blueprint-{related-domain}.md — {why it is related}\n- Depends on: blueprint-{dependency}.md R{N} — {what is needed}\n- Depended on by: blueprint-{dependent}.md R{N} — {what depends on this}\n```\n\n### Template Rules\n\n1. **Number requirements sequentially** (R1, R2, R3...) — agents reference them by ID\n2. **Every requirement gets acceptance criteria** — no exceptions\n3. **Out of Scope is mandatory** — explicit exclusions prevent scope creep\n4. **Cross-References section is mandatory** — even if it says \"None\"\n5. **Scope section is one paragraph** — concise boundary description\n\n---\n\n## Greenfield Pattern: Reference Material → Blueprints\n\nWhen building from scratch, you start with reference materials and derive blueprints from them.\n\n### Flow\n\n```\ncontext\u002Frefs\u002F              context\u002Fblueprints\u002F\n├── prd.md          →      ├── blueprint-overview.md\n├── design-doc.md   →      ├── blueprint-auth.md\n├── api-draft.md    →      ├── blueprint-api.md\n└── research\u002F       →      ├── blueprint-data-models.md\n    └── ...         →      └── blueprint-ui.md\n```\n\n### Process\n\n1. **Place all reference materials** in `context\u002Frefs\u002F`\n2. **Run blueprint generation** — agent reads all refs, decomposes into domains\n3. **Agent produces:**\n   - `blueprint-overview.md` — index with domain summaries\n   - One `blueprint-{domain}.md` per identified domain\n   - Cross-references between related domains\n4. **Human reviews** blueprints for completeness and correctness\n5. **Iterate** — refine blueprints based on review feedback\n\n### Greenfield Prompt Pattern\n\nThe first prompt in a greenfield pipeline (typically `001-generate-blueprints-from-refs.md`) should:\n- Read all files in `context\u002Frefs\u002F`\n- Decompose reference material into domains\n- Generate blueprints following the template above\n- Create `blueprint-overview.md` as the index\n- Cross-reference related blueprints\n\n---\n\n## Rewrite Pattern: Old Code → Reference Docs → Blueprints\n\nWhen rewriting an existing system, the existing code becomes your reference material. But you never go directly from old code to new code — you always extract blueprints first.\n\n### Flow\n\n```\nExisting codebase          context\u002Frefs\u002F              context\u002Fblueprints\u002F\n├── src\u002F            →      ├── ref-apis.md      →     ├── blueprint-overview.md\n├── tests\u002F          →      ├── ref-data-models.md →   ├── blueprint-auth.md\n└── docs\u002F           →      ├── ref-ui-components.md →  ├── blueprint-api.md\n                           └── ref-architecture.md →   └── blueprint-data.md\n```\n\n### Process\n\n1. **Agent explores the existing codebase** and generates reference documents\n2. **Reference docs capture** the current system's behavior, APIs, data models, and UI patterns\n3. **Agent generates blueprints** from reference docs — implementation-agnostic requirements\n4. **Validate blueprints against existing code** — verify acceptance criteria match current behavior\n5. **Proceed with normal DABI** — blueprints drive the new implementation\n\n### Rewrite Prompt Pattern\n\nRewrites typically use more prompts because of the reverse-engineering step:\n- `001`: Generate reference materials from old code\n- `002`: Generate blueprints from references + feature scope\n- `003`: Validate blueprints against existing codebase\n- `004+`: Plans and implementation\n\nThe key difference from greenfield: step 003 validates that your blueprints actually describe what the old system does, before you start building the new one.\n\n---\n\n## Blueprint Compaction\n\nWhen implementation tracking or blueprint files grow beyond approximately 500 lines, they become unwieldy for agents to process efficiently. Spec compaction compresses large files while preserving active context.\n\n### When to Compact\n\n- Implementation tracking file exceeds 500 lines\n- Blueprint file has many resolved\u002Fcompleted requirements mixed with active ones\n- Agent is spending too much context window on historical information\n\n### How to Compact\n\n1. **Identify resolved content:** completed tasks, resolved issues, archived dead ends\n2. **Archive removed content** to a separate file (e.g., `impl\u002Farchive\u002Fimpl-domain-v1.md`)\n3. **Preserve in the compacted file:**\n   - All active\u002Fin-progress tasks\n   - All open issues\n   - Recent dead ends (last 2-3 sessions)\n   - Current test health status\n   - Active cross-references\n4. **Target:** under 500 lines in the active file\n\n### Compaction Rule\n\nNever delete information — move it to an archive. Agents can still find archived context if needed, but it will not consume context window during normal operations.\n\n---\n\n## Gap Analysis\n\nGap analysis compares what was built against what was intended, identifying where blueprints, plans, or validation fell short.\n\n### How to Perform Gap Analysis\n\n1. **Read blueprints** (intended behavior) and **implementation tracking** (what was built)\n2. **For each blueprint requirement,** check if acceptance criteria are satisfied\n3. **Classify each requirement:**\n\n| Status | Meaning |\n|--------|---------|\n| **Complete** | All acceptance criteria pass |\n| **Partial** | Some criteria pass, others do not |\n| **Missing** | Requirement not implemented at all |\n| **Over-built** | Implementation exceeds blueprint (may indicate blueprint gap) |\n\n4. **Report gaps** with: which blueprint, which criterion, what is missing\n5. **Feed gaps into revision** — update blueprints if needed, then re-implement\n\n### Gap Analysis as Feedback\n\nGap analysis is not a one-time activity. Run it:\n- After each implementation iteration\n- Before starting a new session (to prioritize work)\n- When convergence stalls (to identify what is blocking progress)\n\n---\n\n## Integration with Other Skills\n\n### Collaborative Design in the Draft Phase\n\nThe Draft phase (`\u002Fbp:draft`) now embeds brainstorming principles directly. When running in interactive mode (no arguments), the drafter follows a collaborative design process before generating any files:\n\n1. **Explore project context** — check existing files, docs, commits before asking questions\n2. **Ask clarifying questions one at a time** — understand purpose, constraints, success criteria\n3. **Propose 2-3 domain decomposition approaches** — with tradeoffs and a recommendation\n4. **Present the design incrementally** — section by section, get approval per domain\n5. **Generate blueprints only after design approval** — formalize with acceptance criteria\n6. **Blueprint review loop** — automated reviewer checks quality, up to 3 iterations\n7. **User review gate** — explicit approval before transitioning to Architect phase\n\nThis process applies to EVERY project regardless of perceived simplicity. The design can be short for simple projects, but it must happen.\n\n**Visual companion:** For projects involving visual elements (UI, architecture diagrams), the Draft phase can use a browser-based visual companion to show mockups and diagrams during the design conversation. See `references\u002Fvisual-companion.md`.\n\n**YAGNI enforcement:** During the design conversation and blueprint generation, actively strip requirements the user did not ask for. Smaller blueprints are better blueprints.\n\n### With `bp:design-system`\n\nWhen DESIGN.md exists at the project root, blueprints for UI domains should reference design tokens in acceptance criteria. This creates a traceable chain: DESIGN.md -> blueprint acceptance criterion -> plan task -> implementation.\n\n| Acceptance Criterion Type | Design Reference |\n|--------------------------|-----------------|\n| \"Button has primary CTA appearance\" | DESIGN.md Section 4, primary button variant |\n| \"Text follows heading hierarchy\" | DESIGN.md Section 3, type scale |\n| \"Card has subtle elevation\" | DESIGN.md Section 6, elevation level 1 |\n| \"Layout uses 12-column grid\" | DESIGN.md Section 5, grid system |\n| \"Colors adapt for dark mode\" | DESIGN.md Section 2, dark mode mapping |\n\n**Do NOT duplicate DESIGN.md content into blueprints.** Reference by section\u002Ftoken name only. If a color changes in DESIGN.md, blueprints should not need updating.\n\nWhen a blueprint needs a visual pattern not yet defined in DESIGN.md, note it in the acceptance criterion:\n```markdown\n- [ ] Component uses card-like container [DESIGN.md: pattern not yet defined — flag for design update]\n```\n\n### With `bp:validation-first`\n\nEvery acceptance criterion in a blueprint must map to at least one validation gate. When writing blueprints, think about which gate will verify each requirement:\n\n| Acceptance Criterion Type | Likely Gate |\n|--------------------------|-------------|\n| \"Code compiles without errors\" | Gate 1: Build |\n| \"Function returns correct output for input X\" | Gate 2: Unit Tests |\n| \"User can complete workflow end-to-end\" | Gate 3: E2E\u002FIntegration |\n| \"Response time under N ms\" | Gate 4: Performance |\n| \"Application starts and displays main screen\" | Gate 5: Launch Verification |\n| \"UI matches design intent\" | Gate 6: Human Review |\n\n### With `bp:context-architecture`\n\nBlueprints live in the `context\u002Fblueprints\u002F` directory. See `bp:context-architecture` for the full context directory structure, CLAUDE.md conventions, and multi-repo strategies.\n\n### With `bp:impl-tracking`\n\nAs blueprints are implemented, progress is tracked in `context\u002Fimpl\u002F` documents. Dead ends discovered during implementation should be recorded to prevent future agents from retrying failed approaches.\n\n---\n\n## Common Mistakes\n\n### 1. Writing Implementation-Specific Blueprints\n\n**Wrong:** \"Use PostgreSQL with a users table containing columns: id (UUID), email (VARCHAR), ...\"\n**Right:** \"User accounts have a unique identifier and email. Email must be unique across all accounts. Acceptance: creating two accounts with the same email fails with a duplicate error.\"\n\n### 2. Vague Acceptance Criteria\n\n**Wrong:** \"System handles errors properly\"\n**Right:** \"When a network request fails, the UI displays an error message within 2 seconds and offers a retry action. Acceptance: simulating network failure shows error banner with retry button.\"\n\n### 3. Missing Out of Scope\n\nEvery blueprint needs explicit exclusions. Without them, agents will over-build or make assumptions.\n\n### 4. No Cross-References\n\nDomains do not exist in isolation. If blueprint-auth defines session tokens that blueprint-api uses, both blueprints must cross-reference each other.\n\n### 5. Monolithic Blueprints\n\nA single 1000-line blueprint file defeats progressive disclosure. Decompose into domains with a clear index.\n\n---\n\n## Summary\n\nWriting blueprints for AI agents follows these rules:\n\n1. **WHAT, not HOW** — describe behavior, not implementation\n2. **Every requirement gets testable acceptance criteria** — if agents cannot validate it, it will not be met\n3. **Hierarchical with an index** — progressive disclosure for context efficiency\n4. **Cross-referenced** — related domains link to each other\n5. **Explicitly scoped** — out-of-scope section prevents over-building\n6. **Compact when large** — archive resolved content, keep active files under 500 lines\n7. **Living documents** — blueprints evolve through revision as gaps are discovered\n","# Blueprint Writing\n\n## Core Principle: Blueprints Describe WHAT, Not HOW\n\nBlueprints are **implementation-agnostic**. They define what the system must do and how to verify it, but never prescribe a specific framework, language, or architecture.\n\nThis is the fundamental distinction in Blueprint:\n- **Blueprints** = WHAT must be true (framework-agnostic, durable, portable)\n- **Plans** = HOW to build it (framework-specific, derived from blueprints)\n- **Code** = the implementation (generated from plans, validated against blueprints)\n\n### Why Implementation-Agnostic?\n\nWhen blueprints avoid prescribing HOW, they become:\n- **Portable** — the same blueprints can drive implementations in different frameworks\n- **Durable** — blueprints survive technology migrations\n- **Testable** — acceptance criteria are about behavior, not implementation details\n- **Reusable** — the same blueprints work for greenfield, rewrites, and cross-framework evaluation\n\n**Bad blueprint requirement:** \"Use React useState hook to manage form state\"\n**Good blueprint requirement:** \"Form state persists across user interactions within a session. Acceptance: entering values, navigating away, and returning preserves all entered values.\"\n\n---\n\n## Every Requirement Needs Testable Acceptance Criteria\n\nThis is the single most important rule in Blueprint writing. If an agent cannot automatically validate a requirement, that requirement will not be met.\n\n### The Validation-First Rule\n\nEvery requirement must answer: **\"How would an automated test verify this?\"**\n\n| Weak Criterion | Strong Criterion |\n|----------------|-----------------|\n| \"UI should look good\" | \"All interactive elements have minimum 44x44px touch targets\" |\n| \"System should be fast\" | \"API responses return within 200ms at p95 under 100 concurrent users\" |\n| \"Handle errors gracefully\" | \"Network failures display a retry prompt with exponential backoff (1s, 2s, 4s)\" |\n| \"Support authentication\" | \"Valid credentials return a session token; invalid credentials return 401 with error message\" |\n\n### Acceptance Criteria Format\n\nEach criterion should be:\n- **Observable** — can be checked by reading output, UI state, or logs\n- **Deterministic** — same input always produces same pass\u002Ffail result\n- **Automatable** — an agent can write a test that checks this\n- **Independent** — does not depend on subjective judgment\n\n```markdown\n**Acceptance Criteria:**\n- [ ] {Action} results in {observable outcome}\n- [ ] Given {precondition}, when {action}, then {result}\n- [ ] {Metric} meets {threshold} under {conditions}\n```\n\n---\n\n## Hierarchical Structure with Index\n\nBlueprints must be organized as a hierarchy — one index file linking to domain-specific sub-blueprints. This enables progressive disclosure: agents read the index first, then only the sub-blueprints relevant to their task.\n\n### The Blueprint Index Pattern\n\nCreate a `blueprint-overview.md` as the entry point:\n\n```markdown\n# Blueprint Overview\n\n## Domains\n\n| Domain | Blueprint File | Summary |\n|--------|-----------|---------|\n| Authentication | blueprint-auth.md | User registration, login, session management, OAuth |\n| Data Models | blueprint-data-models.md | Core entities, relationships, validation rules |\n| API | blueprint-api.md | REST endpoints, request\u002Fresponse formats, error handling |\n| UI Components | blueprint-ui-components.md | Shared components, accessibility, responsive behavior |\n| Notifications | blueprint-notifications.md | Email, push, in-app notification delivery |\n\n## Cross-Cutting Concerns\n- Security requirements: see blueprint-auth.md R3, blueprint-api.md R7\n- Performance budgets: see blueprint-api.md R12, blueprint-ui-components.md R5\n- Accessibility: see blueprint-ui-components.md R8-R10\n```\n\n### Why Hierarchical?\n\n1. **Context window efficiency** — agents load only the domains they need\n2. **Parallel work** — different agents can own different spec domains\n3. **Review efficiency** — humans can review domain-by-domain\n4. **Cross-referencing** — domains link to each other explicitly\n\n---\n\n## Cross-Referencing Between Blueprints\n\nRelated blueprints must link to each other. Cross-references prevent requirements from being lost at domain boundaries.\n\n### Cross-Reference Patterns\n\n```markdown\n## Cross-References\n- **Depends on:** blueprint-auth.md R1 (session tokens required for API access)\n- **Depended on by:** blueprint-notifications.md R4 (uses user preferences from this blueprint)\n- **Related:** blueprint-ui-components.md R6 (error display components used by this domain)\n```\n\n### When to Cross-Reference\n\n- When one domain's requirement depends on another domain's output\n- When shared entities are defined in one blueprint but used in many\n- When validation criteria span multiple domains\n- When out-of-scope items are in-scope for another blueprint\n\n---\n\n## Full Blueprint Format Template\n\nUse this template for every domain blueprint:\n\n```markdown\n# Blueprint: {Domain Name}\n\n## Scope\n{One paragraph describing what this spec covers and its boundaries.}\n\n## Requirements\n\n### R1: {Requirement Name}\n**Description:** {What must be true — stated in terms of behavior, not implementation.}\n**Acceptance Criteria:**\n- [ ] {Testable criterion 1}\n- [ ] {Testable criterion 2}\n- [ ] {Testable criterion 3}\n**Dependencies:** {Other specs\u002Frequirements this depends on, or \"None\"}\n\n### R2: {Requirement Name}\n**Description:** {What must be true}\n**Acceptance Criteria:**\n- [ ] {Testable criterion 1}\n- [ ] {Testable criterion 2}\n**Dependencies:** {Dependencies}\n\n### R3: ...\n\n## Out of Scope\n{Explicit list of things this blueprint does NOT cover. This is critical — it prevents\nagents from over-building and clarifies domain boundaries.}\n- {Thing explicitly excluded and why}\n- {Another exclusion}\n\n## Cross-References\n- See also: blueprint-{related-domain}.md — {why it is related}\n- Depends on: blueprint-{dependency}.md R{N} — {what is needed}\n- Depended on by: blueprint-{dependent}.md R{N} — {what depends on this}\n```\n\n### Template Rules\n\n1. **Number requirements sequentially** (R1, R2, R3...) — agents reference them by ID\n2. **Every requirement gets acceptance criteria** — no exceptions\n3. **Out of Scope is mandatory** — explicit exclusions prevent scope creep\n4. **Cross-References section is mandatory** — even if it says \"None\"\n5. **Scope section is one paragraph** — concise boundary description\n\n---\n\n## Greenfield Pattern: Reference Material → Blueprints\n\nWhen building from scratch, you start with reference materials and derive blueprints from them.\n\n### Flow\n\n```\ncontext\u002Frefs\u002F              context\u002Fblueprints\u002F\n├── prd.md          →      ├── blueprint-overview.md\n├── design-doc.md   →      ├── blueprint-auth.md\n├── api-draft.md    →      ├── blueprint-api.md\n└── research\u002F       →      ├── blueprint-data-models.md\n    └── ...         →      └── blueprint-ui.md\n```\n\n### Process\n\n1. **Place all reference materials** in `context\u002Frefs\u002F`\n2. **Run blueprint generation** — agent reads all refs, decomposes into domains\n3. **Agent produces:**\n   - `blueprint-overview.md` — index with domain summaries\n   - One `blueprint-{domain}.md` per identified domain\n   - Cross-references between related domains\n4. **Human reviews** blueprints for completeness and correctness\n5. **Iterate** — refine blueprints based on review feedback\n\n### Greenfield Prompt Pattern\n\nThe first prompt in a greenfield pipeline (typically `001-generate-blueprints-from-refs.md`) should:\n- Read all files in `context\u002Frefs\u002F`\n- Decompose reference material into domains\n- Generate blueprints following the template above\n- Create `blueprint-overview.md` as the index\n- Cross-reference related blueprints\n\n---\n\n## Rewrite Pattern: Old Code → Reference Docs → Blueprints\n\nWhen rewriting an existing system, the existing code becomes your reference material. But you never go directly from old code to new code — you always extract blueprints first.\n\n### Flow\n\n```\nExisting codebase          context\u002Frefs\u002F              context\u002Fblueprints\u002F\n├── src\u002F            →      ├── ref-apis.md      →     ├── blueprint-overview.md\n├── tests\u002F          →      ├── ref-data-models.md →   ├── blueprint-auth.md\n└── docs\u002F           →      ├── ref-ui-components.md →  ├── blueprint-api.md\n                           └── ref-architecture.md →   └── blueprint-data.md\n```\n\n### Process\n\n1. **Agent explores the existing codebase** and generates reference documents\n2. **Reference docs capture** the current system's behavior, APIs, data models, and UI patterns\n3. **Agent generates blueprints** from reference docs — implementation-agnostic requirements\n4. **Validate blueprints against existing code** — verify acceptance criteria match current behavior\n5. **Proceed with normal DABI** — blueprints drive the new implementation\n\n### Rewrite Prompt Pattern\n\nRewrites typically use more prompts because of the reverse-engineering step:\n- `001`: Generate reference materials from old code\n- `002`: Generate blueprints from references + feature scope\n- `003`: Validate blueprints against existing codebase\n- `004+`: Plans and implementation\n\nThe key difference from greenfield: step 003 validates that your blueprints actually describe what the old system does, before you start building the new one.\n\n---\n\n## Blueprint Compaction\n\nWhen implementation tracking or blueprint files grow beyond approximately 500 lines, they become unwieldy for agents to process efficiently. Spec compaction compresses large files while preserving active context.\n\n### When to Compact\n\n- Implementation tracking file exceeds 500 lines\n- Blueprint file has many resolved\u002Fcompleted requirements mixed with active ones\n- Agent is spending too much context window on historical information\n\n### How to Compact\n\n1. **Identify resolved content:** completed tasks, resolved issues, archived dead ends\n2. **Archive removed content** to a separate file (e.g., `impl\u002Farchive\u002Fimpl-domain-v1.md`)\n3. **Preserve in the compacted file:**\n   - All active\u002Fin-progress tasks\n   - All open issues\n   - Recent dead ends (last 2-3 sessions)\n   - Current test health status\n   - Active cross-references\n4. **Target:** under 500 lines in the active file\n\n### Compaction Rule\n\nNever delete information — move it to an archive. Agents can still find archived context if needed, but it will not consume context window during normal operations.\n\n---\n\n## Gap Analysis\n\nGap analysis compares what was built against what was intended, identifying where blueprints, plans, or validation fell short.\n\n### How to Perform Gap Analysis\n\n1. **Read blueprints** (intended behavior) and **implementation tracking** (what was built)\n2. **For each blueprint requirement,** check if acceptance criteria are satisfied\n3. **Classify each requirement:**\n\n| Status | Meaning |\n|--------|---------|\n| **Complete** | All acceptance criteria pass |\n| **Partial** | Some criteria pass, others do not |\n| **Missing** | Requirement not implemented at all |\n| **Over-built** | Implementation exceeds blueprint (may indicate blueprint gap) |\n\n4. **Report gaps** with: which blueprint, which criterion, what is missing\n5. **Feed gaps into revision** — update blueprints if needed, then re-implement\n\n### Gap Analysis as Feedback\n\nGap analysis is not a one-time activity. Run it:\n- After each implementation iteration\n- Before starting a new session (to prioritize work)\n- When convergence stalls (to identify what is blocking progress)\n\n---\n\n## Integration with Other Skills\n\n### Collaborative Design in the Draft Phase\n\nThe Draft phase (`\u002Fbp:draft`) now embeds brainstorming principles directly. When running in interactive mode (no arguments), the drafter follows a collaborative design process before generating any files:\n\n1. **Explore project context** — check existing files, docs, commits before asking questions\n2. **Ask clarifying questions one at a time** — understand purpose, constraints, success criteria\n3. **Propose 2-3 domain decomposition approaches** — with tradeoffs and a recommendation\n4. **Present the design incrementally** — section by section, get approval per domain\n5. **Generate blueprints only after design approval** — formalize with acceptance criteria\n6. **Blueprint review loop** — automated reviewer checks quality, up to 3 iterations\n7. **User review gate** — explicit approval before transitioning to Architect phase\n\nThis process applies to EVERY project regardless of perceived simplicity. The design can be short for simple projects, but it must happen.\n\n**Visual companion:** For projects involving visual elements (UI, architecture diagrams), the Draft phase can use a browser-based visual companion to show mockups and diagrams during the design conversation. See `references\u002Fvisual-companion.md`.\n\n**YAGNI enforcement:** During the design conversation and blueprint generation, actively strip requirements the user did not ask for. Smaller blueprints are better blueprints.\n\n### With `bp:design-system`\n\nWhen DESIGN.md exists at the project root, blueprints for UI domains should reference design tokens in acceptance criteria. This creates a traceable chain: DESIGN.md -> blueprint acceptance criterion -> plan task -> implementation.\n\n| Acceptance Criterion Type | Design Reference |\n|--------------------------|-----------------|\n| \"Button has primary CTA appearance\" | DESIGN.md Section 4, primary button variant |\n| \"Text follows heading hierarchy\" | DESIGN.md Section 3, type scale |\n| \"Card has subtle elevation\" | DESIGN.md Section 6, elevation level 1 |\n| \"Layout uses 12-column grid\" | DESIGN.md Section 5, grid system |\n| \"Colors adapt for dark mode\" | DESIGN.md Section 2, dark mode mapping |\n\n**Do NOT duplicate DESIGN.md content into blueprints.** Reference by section\u002Ftoken name only. If a color changes in DESIGN.md, blueprints should not need updating.\n\nWhen a blueprint needs a visual pattern not yet defined in DESIGN.md, note it in the acceptance criterion:\n```markdown\n- [ ] Component uses card-like container [DESIGN.md: pattern not yet defined — flag for design update]\n```\n\n### With `bp:validation-first`\n\nEvery acceptance criterion in a blueprint must map to at least one validation gate. When writing blueprints, think about which gate will verify each requirement:\n\n| Acceptance Criterion Type | Likely Gate |\n|--------------------------|-------------|\n| \"Code compiles without errors\" | Gate 1: Build |\n| \"Function returns correct output for input X\" | Gate 2: Unit Tests |\n| \"User can complete workflow end-to-end\" | Gate 3: E2E\u002FIntegration |\n| \"Response time under N ms\" | Gate 4: Performance |\n| \"Application starts and displays main screen\" | Gate 5: Launch Verification |\n| \"UI matches design intent\" | Gate 6: Human Review |\n\n### With `bp:context-architecture`\n\nBlueprints live in the `context\u002Fblueprints\u002F` directory. See `bp:context-architecture` for the full context directory structure, CLAUDE.md conventions, and multi-repo strategies.\n\n### With `bp:impl-tracking`\n\nAs blueprints are implemented, progress is tracked in `context\u002Fimpl\u002F` documents. Dead ends discovered during implementation should be recorded to prevent future agents from retrying failed approaches.\n\n---\n\n## Common Mistakes\n\n### 1. Writing Implementation-Specific Blueprints\n\n**Wrong:** \"Use PostgreSQL with a users table containing columns: id (UUID), email (VARCHAR), ...\"\n**Right:** \"User accounts have a unique identifier and email. Email must be unique across all accounts. Acceptance: creating two accounts with the same email fails with a duplicate error.\"\n\n### 2. Vague Acceptance Criteria\n\n**Wrong:** \"System handles errors properly\"\n**Right:** \"When a network request fails, the UI displays an error message within 2 seconds and offers a retry action. Acceptance: simulating network failure shows error banner with retry button.\"\n\n### 3. Missing Out of Scope\n\nEvery blueprint needs explicit exclusions. Without them, agents will over-build or make assumptions.\n\n### 4. No Cross-References\n\nDomains do not exist in isolation. If blueprint-auth defines session tokens that blueprint-api uses, both blueprints must cross-reference each other.\n\n### 5. Monolithic Blueprints\n\nA single 1000-line blueprint file defeats progressive disclosure. Decompose into domains with a clear index.\n\n---\n\n## Summary\n\nWriting blueprints for AI agents follows these rules:\n\n1. **WHAT, not HOW** — describe behavior, not implementation\n2. **Every requirement gets testable acceptance criteria** — if agents cannot validate it, it will not be met\n3. **Hierarchical with an index** — progressive disclosure for context efficiency\n4. **Cross-referenced** — related domains link to each other\n5. **Explicitly scoped** — out-of-scope section prevents over-building\n6. **Compact when large** — archive resolved content, keep active files under 500 lines\n7. **Living documents** — blueprints evolve through revision as gaps are discovered\n",{"name":5,"description":7},"main","2b63f856ce19c2a797929cacabd9e0fc936812fa","plugins\u002FJuliusBrussee\u002Fblueprint\u002Fskills\u002Fblueprint-writing",491,"https:\u002F\u002Fgithub.com\u002Fhashgraph-online\u002Fawesome-codex-plugins","https:\u002F\u002Fhol.org\u002Fplugins\u002Fbest-codex-plugins","https:\u002F\u002Fgithub.com\u002Fhashgraph-online","https:\u002F\u002Fhol.org","Open-source standards and developer tools for interoperable AI agents: discovery, identity, communication, payments, privacy and security.","2026-11-14 14:06:13",{"source":8,"skillName":5,"commands":68,"prompt":78,"zipAvailable":79},[69,72,75],{"tool":70,"command":71},"npx","npx skills add hashgraph-online\u002Fawesome-codex-plugins --skill blueprint-writing",{"tool":73,"command":74},"bunx","bunx skills add hashgraph-online\u002Fawesome-codex-plugins --skill blueprint-writing",{"tool":76,"command":77},"pnpm","pnpm dlx skills add hashgraph-online\u002Fawesome-codex-plugins --skill blueprint-writing","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fhashgraph-online\u002Fawesome-codex-plugins\u002Fblob\u002Fmain\u002Fplugins\u002FJuliusBrussee\u002Fblueprint\u002Fskills\u002Fblueprint-writing\u002FSKILL.md",true,[],[82,92,100,108,116,124],{"skillNo":83,"name":84,"nameZh":6,"description":85,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":86,"licenseFileUrl":87,"sourceHtmlUrl":88,"categories":89,"keywords":90,"publishedAt":91},"01M7DV332YQMGD8WTRJ9DZQXTB","worktable-review-with-annotations","Create, inspect, reply to, update, or resolve situated Worktable annotations. Use when feedback belongs to a Doc section, block, text range, or HTML Doc, or when the user asks to address existing review feedback and coordinate a requested artifact edit.","MIT","https:\u002F\u002Fgithub.com\u002Fhashgraph-online\u002Fawesome-codex-plugins\u002Fblob\u002Fmain\u002Fplugins\u002Fworktable\u002Fworktable-plugin\u002Fskills\u002Fworktable-review-with-annotations\u002FLICENSE","https:\u002F\u002Fgithub.com\u002Fhashgraph-online\u002Fawesome-codex-plugins\u002Fblob\u002Fmain\u002Fplugins\u002Fworktable\u002Fworktable-plugin\u002Fskills\u002Fworktable-review-with-annotations\u002FSKILL.md",[],[],"2026-11-15 14:19:17",{"skillNo":93,"name":94,"nameZh":6,"description":95,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":86,"licenseFileUrl":96,"sourceHtmlUrl":97,"categories":98,"keywords":99,"publishedAt":91},"01M7DV2YGHCZVBEB1AHYB6CGHE","worktable-find-and-synthesize-context","Find, assess, and synthesize context from Worktable Docs and Records. Use when the user asks what a workspace contains, wants workspace-backed research, needs current facts reconciled across artifacts, or requests a cited synthesis without changing workspace state.","https:\u002F\u002Fgithub.com\u002Fhashgraph-online\u002Fawesome-codex-plugins\u002Fblob\u002Fmain\u002Fplugins\u002Fworktable\u002Fworktable-plugin\u002Fskills\u002Fworktable-find-and-synthesize-context\u002FLICENSE","https:\u002F\u002Fgithub.com\u002Fhashgraph-online\u002Fawesome-codex-plugins\u002Fblob\u002Fmain\u002Fplugins\u002Fworktable\u002Fworktable-plugin\u002Fskills\u002Fworktable-find-and-synthesize-context\u002FSKILL.md",[],[],{"skillNo":101,"name":102,"nameZh":6,"description":103,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":86,"licenseFileUrl":104,"sourceHtmlUrl":105,"categories":106,"keywords":107,"publishedAt":91},"01M7DV2TQN1H11ME2SAF9MXN7V","worktable-create-or-update-docs","Create, edit, rename, or maintain narrative Worktable Docs. Use for plans, decisions, briefs, notes, research syntheses, and other durable prose when the user requests a new artifact or a safe update to an existing one.","https:\u002F\u002Fgithub.com\u002Fhashgraph-online\u002Fawesome-codex-plugins\u002Fblob\u002Fmain\u002Fplugins\u002Fworktable\u002Fworktable-plugin\u002Fskills\u002Fworktable-create-or-update-docs\u002FLICENSE","https:\u002F\u002Fgithub.com\u002Fhashgraph-online\u002Fawesome-codex-plugins\u002Fblob\u002Fmain\u002Fplugins\u002Fworktable\u002Fworktable-plugin\u002Fskills\u002Fworktable-create-or-update-docs\u002FSKILL.md",[],[],{"skillNo":109,"name":110,"nameZh":6,"description":111,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":86,"licenseFileUrl":112,"sourceHtmlUrl":113,"categories":114,"keywords":115,"publishedAt":91},"01M7DV2NE452NEA8TXATKSNAJH","worktable-create-or-manage-records","Organize repeated structured information as durable Worktable Records. Use for research datasets, inventories, directories, pipelines, trackers, and other collections whose items need identity, fields, filtering, links, validation, or individual updates.","https:\u002F\u002Fgithub.com\u002Fhashgraph-online\u002Fawesome-codex-plugins\u002Fblob\u002Fmain\u002Fplugins\u002Fworktable\u002Fworktable-plugin\u002Fskills\u002Fworktable-create-or-manage-records\u002FLICENSE","https:\u002F\u002Fgithub.com\u002Fhashgraph-online\u002Fawesome-codex-plugins\u002Fblob\u002Fmain\u002Fplugins\u002Fworktable\u002Fworktable-plugin\u002Fskills\u002Fworktable-create-or-manage-records\u002FSKILL.md",[],[],{"skillNo":117,"name":118,"nameZh":6,"description":119,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":86,"licenseFileUrl":120,"sourceHtmlUrl":121,"categories":122,"keywords":123,"publishedAt":91},"01M7DV2HENRBR2KSCVM064WH0Y","worktable-create-or-manage-interactive-html","Create or improve durable visual and interactive artifacts in Worktable. Use for dashboards, trackers, calculators, mini apps, slide presentations, and other requests that benefit from a polished HTML Doc.","https:\u002F\u002Fgithub.com\u002Fhashgraph-online\u002Fawesome-codex-plugins\u002Fblob\u002Fmain\u002Fplugins\u002Fworktable\u002Fworktable-plugin\u002Fskills\u002Fworktable-create-or-manage-interactive-html\u002FLICENSE","https:\u002F\u002Fgithub.com\u002Fhashgraph-online\u002Fawesome-codex-plugins\u002Fblob\u002Fmain\u002Fplugins\u002Fworktable\u002Fworktable-plugin\u002Fskills\u002Fworktable-create-or-manage-interactive-html\u002FSKILL.md",[],[],{"skillNo":125,"name":126,"nameZh":6,"description":127,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":86,"licenseFileUrl":128,"sourceHtmlUrl":129,"categories":130,"keywords":131,"publishedAt":91},"01M7DV2CADR5R7RQFFYPNAGR9Y","worktable-collaborate-threads","Read, answer, and hand off messages through durable Worktable threads with users or other authenticated participants. Use when the user asks to check addressed messages, reply to a participant, continue a thread, request another agent's help, wait briefly for a response, or watch for comments and messages sent to the agent.","https:\u002F\u002Fgithub.com\u002Fhashgraph-online\u002Fawesome-codex-plugins\u002Fblob\u002Fmain\u002Fplugins\u002Fworktable\u002Fworktable-plugin\u002Fskills\u002Fworktable-collaborate-threads\u002FLICENSE","https:\u002F\u002Fgithub.com\u002Fhashgraph-online\u002Fawesome-codex-plugins\u002Fblob\u002Fmain\u002Fplugins\u002Fworktable\u002Fworktable-plugin\u002Fskills\u002Fworktable-collaborate-threads\u002FSKILL.md",[],[]]