ALWAYS invoke this skill when creating or organizing specs, capabilities, features, stories, or ADRs. NEVER create, read, or modify any files in the specs/ directory without this skill.
From specsnpx claudepluginhub outcomeeng/claude --plugin specsThis skill uses the workspace's default tool permissions.
templates/decisions/architectural-decision.adr.mdtemplates/decisions/product-decision.pdr.mdtemplates/requirements/product-change.prd.mdtemplates/requirements/technical-change.trd.mdtemplates/work-items/DONE.mdtemplates/work-items/capability-name.capability.mdtemplates/work-items/feature-name.feature.mdtemplates/work-items/story-name.story.mdProvides UI/UX resources: 50+ styles, color palettes, font pairings, guidelines, charts for web/mobile across React, Next.js, Vue, Svelte, Tailwind, React Native, Flutter. Aids planning, building, reviewing interfaces.
Fetches up-to-date documentation from Context7 for libraries and frameworks like React, Next.js, Prisma. Use for setup questions, API references, and code examples.
Fetches up-to-date documentation from Context7 for libraries and frameworks like React, Next.js, Prisma. Use for setup questions, API references, and code examples.
<quick_start> Different use cases read different sections:
<accessing_templates> FIRST to understand where templates are located<structure_definition> for specs/ directory hierarchy, BSP numbering, co-located tests<adr_templates> for Architectural Decision Record patterns<pdr_templates> for Product Decision Record patterns<requirement_templates> for Product and Technical Requirements<work_item_templates> for capability, feature, story, and DONE.md patternsUse progressive disclosure - read only what you need. </quick_start>
<accessing_templates>
<how_to_access> All templates are stored within this skill's base directory.
When this skill is invoked, Claude Code provides the base directory in the loading message:
Base directory for this skill: {skill_dir}
Use this exact path for all file access. Throughout this documentation, ${SKILL_DIR} is a placeholder—Claude must substitute it manually from the loading message.
IMPORTANT: Do NOT search the project directory for skill files. </how_to_access>
<skill_directory_structure>
The skill's base directory path pattern:
.claude/plugins/cache/{marketplace-name}/{plugin-name}/{version}/skills/managing-specs/
Example: For outcomeeng marketplace, specs plugin version 0.3.3:
${SKILL_DIR} = .claude/plugins/cache/outcomeeng/specs/0.3.3/skills/managing-specs/
</skill_directory_structure>
<template_organization>
All templates are under ${SKILL_DIR}/templates/:
${SKILL_DIR}/
├── SKILL.md # This file
└── templates/
├── decisions/
│ ├── architectural-decision.adr.md
│ └── product-decision.pdr.md
├── requirements/
│ ├── product-change.prd.md
│ └── technical-change.trd.md
└── work-items/
├── capability-name.capability.md
├── feature-name.feature.md
├── story-name.story.md
└── DONE.md
</template_organization>
<how_to_read_templates>
Always use the skill's base directory, not the user's project directory.
# Pattern
Read: ${SKILL_DIR}/templates/{category}/{template-name}
# Example: Read feature template
Read: ${SKILL_DIR}/templates/work-items/feature-name.feature.md
# With actual path (example for outcomeeng marketplace, version 0.3.3)
Read: .claude/plugins/cache/outcomeeng/specs/0.3.3/skills/managing-specs/templates/work-items/feature-name.feature.md
</how_to_read_templates>
<troubleshooting>If you cannot find a template:
${SKILL_DIR}/templates/... or .claude/plugins/cache/...Glob: .claude/plugins/cache/**/managing-specs/templates/**/*.mdspecs/templates/)</accessing_templates>
<structure_definition>
<overview> The specs/ directory follows the SPX framework structure. </overview><three_phase_transformation>
</three_phase_transformation>
<directory_structure>
specs/
├── [product-name].prd.md # Product-wide PRD
├── decisions/ # Product-wide ADRs (optional)
│ └── adr-NN_{slug}.md
└── work/
├── backlog/
├── doing/
│ └── capability-NN_{slug}/
│ ├── {slug}.capability.md
│ ├── {slug}.prd.md # Optional capability-scoped PRD from which the capability work item (`{slug}.capability.md`) is derived
│ ├── {slug}.prd.md # Optional capability-scoped TRD from which capability-scoped ADRs are derived
│ ├── decisions/ # Capability-scoped ADRs
│ ├── tests/
│ └── feature-NN_{slug}/
│ ├── {slug}.prd.md # Optional capability-scoped PRD from which the feature spec in `{slug}.feature.md` is derived
│ ├── {slug}.trd.md # Optional capability-scoped TRD from which the feature-scoped ADRs are derived
│ ├── {slug}.feature.md
│ ├── decisions/ # Feature-scoped ADRs
│ ├── tests/
│ └── story-NN_{slug}/
│ ├── {slug}.story.md
│ └── tests/
└── done/
</directory_structure>
<work_item_hierarchy>
Capability: E2E scenario with product-wide impact
specs/.../capability-NN/tests/ (E2E level)Feature: Integration scenario with specific functionality
specs/.../feature-NN/tests/ (Integration level)Story: Unit-tested atomic implementation
specs/.../story-NN/tests/ (Unit level)</work_item_hierarchy>
<key_principles>
<bsp_sibling_uniqueness> below)specs/.../tests/ permanently (no graduation)</key_principles>
<bsp_sibling_uniqueness>
🚨 CRITICAL: BSP numbers are ONLY unique among siblings at the same level.
capability-21/feature-01/story-54 ← One story-54
capability-22/feature-01/story-54 ← DIFFERENT story-54
capability-21/feature-02/story-54 ← DIFFERENT story-54
ALWAYS use the FULL PATH when referencing work items:
| ❌ WRONG (Ambiguous) | ✅ CORRECT (Unambiguous) |
|---|---|
| "story-54" | "capability-21/feature-54/story-54" |
| "implement feature-01" | "implement capability-21/feature-01" |
| "Continue with story-54" | "Continue capability-21/feature-54/story-54" |
Why this matters:
When communicating about work items:
specs/work/</bsp_sibling_uniqueness>
</structure_definition>
<workflow><reading_status>
<understanding_work_items>
<three_states> Status values:
| State | Meaning |
|---|---|
| OPEN | Work not started |
| IN_PROGRESS | Work underway |
| DONE | Complete |
</three_states>
<bsp_dependency_order>
Lower BSP number = must complete FIRST.
You CANNOT work on item N until ALL items with numbers < N are DONE.
This applies at every level:
| If you see... | It means... |
|---|---|
feature-48 before feature-87 | feature-48 MUST be DONE before feature-87 starts |
story-21 before story-32 | story-21 MUST be DONE before story-32 starts |
feature-48 [OPEN], feature-87 [IN_PROGRESS] | BUG: Dependency violation |
</bsp_dependency_order>
<finding_next_work_item>
1. List all work items in BSP order (capability → feature → story)
2. Return the FIRST item where status ≠ DONE
3. That item blocks everything after it
Example:
feature-48_test-harness [OPEN] ← Was added after feature-87 but blocks it
feature-87_e2e-workflow [IN_PROGRESS] ← Was already started, then dependency discovered
Next work item: feature-48_test-harness → its first OPEN story.
</finding_next_work_item>
</understanding_work_items>
</reading_status>
<managing_items>
<managing_work_items>
<numbering_work_items>
<bsp_numbering> Two-digit prefixes in range [10, 99] encode dependency order. </bsp_numbering>
<creating_new_items>
<case_1_first_item>
Use position 21 (leaves room for ~10 items before/after):
# First feature in a new capability
capability-21_foo/
└── feature-21_first-feature/
</case_1_first_item>
<case_2_insert_between>
Use midpoint: new = floor((left + right) / 2)
# Insert between feature-21 and feature-54
new = floor((21 + 54) / 2) = 37
feature-21_first/
feature-37_inserted/ ← NEW
feature-54_second/
</case_2_insert_between>
<case_3_append_after>
Use midpoint to upper bound: new = floor((last + 99) / 2)
# Append after feature-54
new = floor((54 + 99) / 2) = 76
feature-21_first/
feature-54_second/
feature-76_appended/ ← NEW
</case_3_append_after>
</creating_new_items>
</numbering_work_items>
<creating_work_items> Every work item needs:
NN_{slug}/{slug}.{capability|feature|story}.mdtests/ (create when starting work)Optional:
{topic}.prd.md or {topic}.trd.mddecisions/adr-NNN_{slug}.md</creating_work_items>
</managing_work_items>
</managing_items>
</workflow><adr_templates>
<overview> ADRs document technical choices with trade-offs and consequences. </overview><template_location>
${SKILL_DIR}/templates/decisions/architectural-decision.adr.md
</template_location>
<usage>Read the template and adapt:
# Read ADR template
Read: ${SKILL_DIR}/templates/decisions/architectural-decision.adr.md
# Adapt for your decision
- State the architectural concern this decision governs (atemporal voice — no history)
- Document the chosen option and rationale
- Specify consequences and trade-offs
- Define compliance criteria
</usage>
<scope_levels>
ADRs can exist at three levels:
specs/decisions/adr-NN_{slug}.mdspecs/work/doing/capability-NN/decisions/adr-NN_{slug}.mdspecs/work/doing/.../feature-NN/decisions/adr-NN_{slug}.mdStories inherit decisions from parent feature/capability.
</scope_levels>
<naming_convention>
Format: adr-{NN}_{slug}.md
use-postgresql-for-persistence)</naming_convention>
<bsp_numbering_for_adrs>
Lower BSP number = must decide first (within scope).
ADRs follow the same BSP numbering as work items:
<creating_first_adr>
Use position 21 (leaves room for ~10 items before/after):
decisions/adr-21_first-decision.md
</creating_first_adr>
<inserting_between_adrs>
Use midpoint: new = floor((left + right) / 2)
# Insert between adr-21 and adr-54
new = floor((21 + 54) / 2) = 37
decisions/adr-21_type-safety.md
decisions/adr-37_inserted-decision.md ← NEW
decisions/adr-54_cli-framework.md
</inserting_between_adrs>
<appending_after_last>
Use midpoint to upper bound: new = floor((last + 99) / 2)
# Append after adr-54
new = floor((54 + 99) / 2) = 76
decisions/adr-21_type-safety.md
decisions/adr-54_cli-framework.md
decisions/adr-76_appended-decision.md ← NEW
</appending_after_last>
</bsp_numbering_for_adrs>
<dependency_order_within_scope>
Scope boundaries: ADRs are scoped to product/capability/feature.
Within scope: Lower BSP = must decide first.
| If you see... | It means... |
|---|---|
adr-21_type-safety.md | Foundational decision, must decide first |
adr-37_validation.md | Depends on adr-21, must come after |
adr-54_cli-framework.md | May depend on both adr-21 and adr-37 |
Cross-scope dependencies: Must be documented explicitly in the ADR content.
| Dependency | How to Express |
|---|---|
| Feature ADR depends on capability ADR | Reference in "Context" section with link |
| Capability ADR depends on product ADR | Reference in "Context" section with link |
</dependency_order_within_scope>
<why_bsp_numbering>
Problem: Sequential numbering (01, 02, 03) cannot accommodate discovered dependencies.
Example: You have decisions adr-01, adr-02, adr-03. You discover adr-02 needs a prior decision about type safety. With sequential numbering, you must renumber all subsequent ADRs.
Solution: BSP numbering allows insertion at any point using midpoint calculation.
</why_bsp_numbering>
<why_no_numbers_in_content>
Problem: If ADR file is renumbered (e.g., adr-23 → adr-37), content with embedded numbers becomes stale.
Examples:
# ADR 23: Foo - wrong after renumberingSolution:
# ADR: Foo (document type prefix, no number)[Foo](decisions/adr-37_foo.md) (markdown link with path)</why_no_numbers_in_content>
<why_markdown_links_only>
Problem: Plain text references like "ADR-23" or even `adr-23_foo.md` break when files are renumbered.
Solution: Markdown links [Decision Title](relative/path/to/adr-NN_slug.md):
</why_markdown_links_only>
</adr_templates>
<pdr_templates>
<overview> PDRs document product behavior decisions with trade-offs and user impact. Unlike ADRs (which govern code architecture), PDRs govern observable product behavior. </overview><template_location>
${SKILL_DIR}/templates/decisions/product-decision.pdr.md
</template_location>
<usage>Read the template and adapt:
# Read PDR template
Read: ${SKILL_DIR}/templates/decisions/product-decision.pdr.md
# Adapt for your decision
- State the product behavior this decision governs (atemporal voice — no history)
- Describe the chosen product behavior
- List product invariants users can rely on
- Specify compliance criteria for product behavior
</usage>
<scope_levels>
PDRs can exist at three levels:
specs/decisions/pdr-NN_{slug}.mdspecs/work/doing/capability-NN/decisions/pdr-NN_{slug}.mdspecs/work/doing/.../feature-NN/decisions/pdr-NN_{slug}.mdStories inherit product decisions from parent feature/capability.
</scope_levels>
<naming_convention>
Format: pdr-{NN}_{slug}.md
simulation-lifecycle-phases)</naming_convention>
<adr_vs_pdr>
| Aspect | ADR | PDR |
|---|---|---|
| Governs | Code architecture | Product behavior |
| Invariants | Algebraic code properties | Observable user guarantees |
| Compliance | Code review criteria | Product behavior validation |
| Example | "Use PostgreSQL for persistence" | "Simulation has three phases" |
When to use which:
</adr_vs_pdr>
</pdr_templates>
<referencing_decisions>
<overview> **Always use markdown links with descriptive titles for both ADRs and PDRs.** </overview><in_markdown_documents>
<within_same_directory>
See [Type Safety](adr-21_type-safety.md) for validation approach.
</within_same_directory>
<from_child_to_parent_scope>
<!-- Feature ADR referencing capability ADR -->
This decision builds on [Config Loading](../../decisions/adr-21_config-loading.md).
<!-- Story referencing feature ADR -->
Implementation follows [CLI Structure](../../decisions/adr-21_cli-structure.md).
</from_child_to_parent_scope>
<from_work_item_to_adr>
<!-- From story to capability ADR -->
Architectural constraints: [Commander Pattern](../../decisions/adr-21_commander-pattern.md)
<!-- From feature to product ADR -->
Type system: [Type Safety](../../../../decisions/adr-21_type-safety.md)
</from_work_item_to_adr>
</in_markdown_documents>
<never_use_these_formats>
❌ Plain text reference: "See ADR-21"
❌ Code-only reference: `adr-21_type-safety.md`
❌ Number-only reference: "ADR 21 specifies..."
</never_use_these_formats>
<why_markdown_links>
</why_markdown_links>
</referencing_decisions>
<requirement_templates>
<overview> Templates for Product Requirements (PRD) and Technical Requirements (TRD). </overview><prd_template>
Location: ${SKILL_DIR}/templates/requirements/product-change.prd.md
Purpose: Product requirements - user value, customer journey, measurable outcomes
Usage:
# Read PRD template
Read: ${SKILL_DIR}/templates/requirements/product-change.prd.md
# Adapt for product change
- Define user value proposition
- Document measurable outcomes with targets
- Specify acceptance criteria
- Avoid implementation details
Placement:
specs/{product-name}.prd.mdspecs/work/doing/capability-NN/{topic}.prd.md</prd_template>
<trd_template>
Location: ${SKILL_DIR}/templates/requirements/technical-change.trd.md
Purpose: Technical requirements - system architecture, validation strategy, test infrastructure
Usage:
# Read TRD template
Read: ${SKILL_DIR}/templates/requirements/technical-change.trd.md
# Adapt for technical change
- Specify technical architecture
- Define testing strategy (Level 1/2/3)
- Document validation approach
- Identify infrastructure needs
Placement:
specs/work/doing/.../feature-NN/{topic}.trd.md</trd_template>
<requirements_rules>
</requirements_rules>
</requirement_templates>
<work_item_templates>
<overview> Templates for capabilities, features, stories, and completion evidence. </overview><template_locations>
${SKILL_DIR}/templates/work-items/capability-name.capability.md
${SKILL_DIR}/templates/work-items/feature-name.feature.md
${SKILL_DIR}/templates/work-items/story-name.story.md
${SKILL_DIR}/templates/work-items/DONE.md
</template_locations>
<usage_pattern>
# For capability
Read: ${SKILL_DIR}/templates/work-items/capability-name.capability.md
Adapt: Replace {slug} with kebab-case name
Fill functional requirements
Add user value context
# For feature
Read: ${SKILL_DIR}/templates/work-items/feature-name.feature.md
Adapt: Replace {slug} with kebab-case name
Specify integration scope
Define component interactions
# For story
Read: ${SKILL_DIR}/templates/work-items/story-name.story.md
Adapt: Replace {slug} with kebab-case name
Detail atomic implementation
List specific functions/classes
# For completion
Read: ${SKILL_DIR}/templates/work-items/DONE.md
Adapt: List co-located tests by level
Document verification steps
Include evidence of completion
</usage_pattern>
<file_placement>
Work items follow this pattern:
specs/work/{backlog|doing|done}/{level}-{bsp}_{slug}/{slug}.{level}.md
Examples:
specs/work/doing/capability-21_core-cli/core-cli.capability.mdspecs/work/doing/capability-21_core-cli/feature-10_init/init.feature.mdspecs/work/doing/capability-21_core-cli/feature-15_init/story-87_parse-flags/parse-flags.story.md</file_placement>
<test_co_location>
Tests stay co-located with their work item permanently:
specs/.../capability-NN/tests/*.e2e.test.tsspecs/.../feature-NN/tests/*.integration.test.tsspecs/.../story-NN/tests/*.unit.test.tsDONE.md documents test verification and provides completion evidence.
</test_co_location>
</work_item_templates>
<success_criteria> Skill is working correctly when:
templates/ subdirectories</success_criteria>