Managing Specs

Single source of truth for specs/ directory structure and all document templates. Enables creation of requirements (PRD/TRD), decisions (ADR for architecture, PDR for product), and work items (capability/feature/story) with consistent structure across all products using the SPX framework.

Different use cases read different sections:

• Template access → Read `` FIRST to understand where templates are located
• Structure definition → Read `` for specs/ directory hierarchy, BSP numbering, co-located tests
• ADR templates → Read `` for Architectural Decision Record patterns
• PDR templates → Read `` for Product Decision Record patterns
• PRD/TRD templates → Read `` for Product and Technical Requirements
• Work item templates → Read `` for capability, feature, story, and DONE.md patterns

Use progressive disclosure - read only what you need.

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.

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/

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

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

If you cannot find a template:

1. ✅ Verify you're using the skill's base directory, NOT the project directory
2. ✅ Ensure path starts with ${SKILL_DIR}/templates/... or .claude/plugins/cache/...
3. ✅ Use Glob to discover: Glob: .claude/plugins/cache/**/managing-specs/templates/**/*.md
4. ❌ Do NOT look for templates in the user's project (e.g., specs/templates/)

The specs/ directory follows the SPX framework structure.

1. Requirements (PRD/TRD) - Capture vision without implementation constraints
2. Decisions (ADR/PDR) - Constrain architecture (ADR) or product behavior (PDR) with explicit trade-offs
3. Work Items (Capability/Feature/Story) - Sized, testable implementation containers

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/

• Capability: E2E scenario with product-wide impact
• Tests co-located in specs/.../capability-NN/tests/ (E2E level)
• May have optional PRD as catalyst/enrichment
• Contains features

• Feature: Integration scenario with specific functionality
• Tests co-located in specs/.../feature-NN/tests/ (Integration level)
• May have optional TRD as catalyst/enrichment
• Contains stories

• Story: Unit-tested atomic implementation
• Tests co-located in specs/.../story-NN/tests/ (Unit level)
• No children
• Atomic implementation unit

• PRD OR TRD at same scope, never both
• Requirements immutable - code adapts to requirements, not vice versa
• BSP numbering: Two-digit (10-99), lower number = must complete first
• BSP numbers are SIBLING-UNIQUE: Numbers are only unique among siblings, not globally (see `` below)
• Tests co-located: Tests stay in specs/.../tests/ permanently (no graduation)

🚨 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:

• Different capabilities can have identically-numbered features
• Different features can have identically-numbered stories
• "story-54" could refer to dozens of different stories across the codebase
• Without the full path, agents will access the WRONG work item

When communicating about work items:

1. Always include the full hierarchy path
2. Never use bare numbers like "story-54" without context
3. When in doubt, use the absolute path from specs/work/

Status values:

| State | Meaning | | --------------- | ---------------- | | OPEN | Work not started | | IN_PROGRESS | Work underway | | DONE | Complete |

> Lower BSP number = must complete FIRST. > > You CANNOT work on item N until ALL items with numbers

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.

Two-digit prefixes in range [10, 99] encode dependency order.

Use position 21 (leaves room for ~10 items before/after):

# First feature in a new capability
capability-21_foo/
└── feature-21_first-feature/

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/

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

Every work item needs:

1. Directory: NN_{slug}/
2. Definition file: {slug}.{capability|feature|story}.md
3. Tests directory: tests/ (create when starting work)

Optional:

• Requirements document: {topic}.prd.md or {topic}.trd.md
• Decision Records: decisions/adr-NNN_{slug}.md

ADRs document technical choices with trade-offs and consequences.

${SKILL_DIR}/templates/decisions/architectural-decision.adr.md

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

ADRs can exist at three levels:

• Project: specs/decisions/adr-NN_{slug}.md
• Capability: specs/work/doing/capability-NN/decisions/adr-NN_{slug}.md
• Feature: specs/work/doing/.../feature-NN/decisions/adr-NN_{slug}.md

Stories inherit decisions from parent feature/capability.

Format: adr-{NN}_{slug}.md

• NN: BSP number in range [10, 99]
• slug: Kebab-case description (e.g., use-postgresql-for-persistence)

Lower BSP number = must decide first (within scope).

ADRs follow the same BSP numbering as work items:

Use position 21 (leaves room for ~10 items before/after):

decisions/adr-21_first-decision.md

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

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

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 |

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.

Problem: If ADR file is renumbered (e.g., adr-23 → adr-37), content with embedded numbers becomes stale.

Examples:

• Header # ADR 23: Foo - wrong after renumbering
• Reference "See ADR-23" - wrong after renumbering

Solution:

• Header: # ADR: Foo (document type prefix, no number)
• References: [Foo](decisions/adr-37_foo.md) (markdown link with path)
• Filenames can be renamed, slugs stay stable, markdown links update automatically

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):

• Modern editors update links automatically on file rename
• Links are clickable for navigation
• Slug provides stability even if number changes
• Can search by slug if link breaks

PDRs document product behavior decisions with trade-offs and user impact. Unlike ADRs (which govern code architecture), PDRs govern observable product behavior.

${SKILL_DIR}/templates/decisions/product-decision.pdr.md

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

PDRs can exist at three levels:

• Project: specs/decisions/pdr-NN_{slug}.md
• Capability: specs/work/doing/capability-NN/decisions/pdr-NN_{slug}.md
• Feature: specs/work/doing/.../feature-NN/decisions/pdr-NN_{slug}.md

Stories inherit product decisions from parent feature/capability.

Format: pdr-{NN}_{slug}.md

• NN: BSP number in range [10, 99]
• slug: Kebab-case description (e.g., simulation-lifecycle-phases)

| 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:

• Technical implementation choice → ADR
• User-facing behavior choice → PDR
• If unsure, ask: "Is this about HOW we build it (ADR) or WHAT users experience (PDR)?"

Always use markdown links with descriptive titles for both ADRs and PDRs.

See [Type Safety](adr-21_type-safety.md) for validation approach.

This decision builds on [Config Loading](../../decisions/adr-21_config-loading.md).

Implementation follows [CLI Structure](../../decisions/adr-21_cli-structure.md).

Architectural constraints: [Commander Pattern](../../decisions/adr-21_commander-pattern.md)

Type system: [Type Safety](../../../../decisions/adr-21_type-safety.md)

❌ Plain text reference: "See ADR-21" ❌ Code-only reference: ` adr-21_type-safety.md ` ❌ Number-only reference: "ADR 21 specifies..."

• Clickable: Navigate directly in editors/viewers
• Stable: Slug provides stability even if number changes
• Updatable: Modern editors can update links on file rename
• Descriptive: Title provides context without opening file

Templates for Product Requirements (PRD) and Technical Requirements (TRD).

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:

• Product-wide: specs/{product-name}.prd.md
• Capability catalyst: specs/work/doing/capability-NN/{topic}.prd.md

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:

• Feature catalyst: specs/work/doing/.../feature-NN/{topic}.trd.md

• PRD OR TRD at same scope, never both
• Immutable: Code adapts to requirements, not vice versa
• Optional catalyst: PRD/TRD may exist as enrichment; spec file is always required

Templates for capabilities, fe

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: outcomeeng
• Source: outcomeeng/claude
• License: MIT

Install and usage instructions live in the source repository linked above.