managing-spx

<quick_start> Different use cases read different sections:

• •Template access → Read <accessing_templates> FIRST to understand where templates are located
• •Structure definition → Read <structure_definition> for spx/ directory hierarchy, BSP numbering, test co-location
• •ADR templates → Read <adr_templates> for Architectural Decision Record patterns
• •PRD templates → Read <requirement_templates> for Product Requirements
• •Work item templates → Read <work_item_templates> for capability, feature, and story patterns

Use 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, you are provided 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>

<template_organization>

All templates are under ${SKILL_DIR}/templates/:

${SKILL_DIR}/
├── SKILL.md                                    # This file
└── templates/
    ├── product/
    │   └── product.prd.md
    ├── decisions/
    │   └── architectural-decision.adr.md
    └── outcomes/
        ├── capability-name.capability.md
        ├── feature-name.feature.md
        └── story-name.story.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/outcomes/feature-name.feature.md

</how_to_read_templates>

</accessing_templates>

<structure_definition>

<three_phase_transformation>

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

</three_phase_transformation>

<directory_structure>

spx/
├── {product-name}.prd.md             # Product requirements
├── NN-{slug}.adr.md                  # Product-wide ADRs (interleaved)
└── NN-{slug}.capability/
    ├── {slug}.capability.md
    ├── outcomes.yaml                       # Test verification ledger
    ├── tests/
    ├── NN-{slug}.adr.md              # Capability-scoped ADRs (interleaved)
    └── NN-{slug}.feature/
        ├── {slug}.feature.md
        ├── outcomes.yaml
        ├── tests/
        ├── NN-{slug}.adr.md          # Feature-scoped ADRs (interleaved)
        └── NN-{slug}.story/
            ├── {slug}.story.md
            ├── outcomes.yaml
            └── tests/

</directory_structure>

<work_item_hierarchy>

• •

  Capability: E2E scenario with product-wide impact

  • •Tests co-located in spx/NN-{slug}.capability/tests/ with .e2e.test.* suffix
  • •May have optional PRD as catalyst/enrichment
  • •Contains features
• •

  Feature: Integration scenario with specific functionality

  • •Tests co-located in spx/.../NN-{slug}.feature/tests/ with .integration.test.* suffix
  • •Technical details documented in feature.md (no separate TRD)
  • •Contains stories
• •

  Story: Unit-tested atomic implementation

  • •Tests co-located in spx/.../NN-{slug}.story/tests/ with .unit.test.* suffix
  • •No children
  • •Atomic implementation unit

</work_item_hierarchy>

<key_principles>

• •Requirements immutable - code adapts to requirements, not vice versa
• •BSP numbering: Binary Space Partitioning encodes dependency order—lower BSP items are dependencies that higher-BSP items may rely on; same BSP means independent
• •Full paths required: BSP numbers repeat at different levels (see <bsp_full_paths> below)
• •Test co-location: Tests stay in spx/.../tests/ permanently (no graduation)
• •Status rules (use CLI, do NOT check manually):
  • •spx spec status --format table - View project status
  • •spx spec next - Get next work item (respects BSP ordering)

</key_principles>

<bsp_full_paths>

🚨 CRITICAL: BSP numbers repeat at different levels—always use full paths.

21-foo.capability/21-bar.feature/54-baz.story/  ← One story-54
21-foo.capability/37-qux.feature/54-baz.story/  ← DIFFERENT story-54
37-other.capability/21-bar.feature/54-baz.story/  ← DIFFERENT story-54

ALWAYS use the FULL PATH when referencing work items:

Why this matters:

• •BSP numbers encode dependency order within each level, not global uniqueness
• •Different capabilities can have identically-numbered features
• •Different features can have identically-numbered stories
• •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 spx/

</bsp_full_paths>

</structure_definition>

<reading_status>

<understanding_work_items>

<three_states> Use CLI commands to check status (do NOT manually inspect directories):

# View project status
spx spec status --format table

# Get next work item (respects BSP ordering)
spx spec next

Status values:

</three_states>

<bsp_dependency_order>

Lower BSP = dependency. Higher-BSP items may rely on lower-BSP items.

Check dependencies before working on an item—lower-numbered items in the same scope may need to be done first.

This applies at every level:

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

48-test-harness.feature/ [OPEN]        ← Was added after 87 but blocks it
87-e2e-workflow.feature/ [IN_PROGRESS] ← Was already started, then dependency discovered

Next work item: 48-test-harness.feature/ → 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
21-foo.capability/
└── 21-first-feature.feature/

</case_1_first_item>

<case_2_insert_between>

Use midpoint: new = floor((left + right) / 2)

# Insert between 21 and 54
new = floor((21 + 54) / 2) = 37

21-first.feature/
37-inserted.feature/    ← NEW
54-second.feature/

</case_2_insert_between>

<case_3_append_after>

Use midpoint to upper bound: new = floor((last + 99) / 2)

# Append after 54
new = floor((54 + 99) / 2) = 76

21-first.feature/
54-second.feature/
76-appended.feature/    ← NEW

</case_3_append_after>

</creating_new_items>

</numbering_work_items>

<creating_work_items> Every work item needs:

1. •Directory: NN-{slug}.{type}/ (e.g., 21-auth.capability/)
2. •Spec file: {slug}.{type}.md (e.g., auth.capability.md)
3. •Tests directory: tests/ (create when starting work)

Optional:

• •Decision Records: NN-{slug}.adr.md (interleaved with work items)

</creating_work_items>

</managing_work_items>

</managing_items>

<adr_templates>

<template_location>

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

</template_location>

Read the template and adapt:

# Read ADR template
Read: ${SKILL_DIR}/templates/decisions/architectural-decision.adr.md

# Adapt for your decision
- Document decision context and problem
- List options considered with pros/cons
- Document chosen option and rationale
- Specify consequences and trade-offs

<scope_levels>

ADRs are interleaved with work items at any level:

• •Product: spx/NN-{slug}.adr.md
• •Capability: spx/NN-{slug}.capability/NN-{slug}.adr.md
• •Feature: spx/.../NN-{slug}.feature/NN-{slug}.adr.md

Stories inherit decisions from parent feature/capability.

</scope_levels>

<naming_convention>

Format: NN-{slug}.adr.md

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

</naming_convention>

<bsp_numbering_for_adrs>

Lower BSP = dependency. Higher-BSP ADRs may rely on lower-BSP decisions.

ADRs follow the same BSP numbering as work items:

<creating_first_adr>

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

21-first-decision.adr.md

</creating_first_adr>

<inserting_between_adrs>

Use midpoint: new = floor((left + right) / 2)

# Insert between 21 and 54
new = floor((21 + 54) / 2) = 37

21-type-safety.adr.md
37-inserted-decision.adr.md    ← NEW
54-cli-framework.adr.md

</inserting_between_adrs>

<appending_after_last>

Use midpoint to upper bound: new = floor((last + 99) / 2)

# Append after 54
new = floor((54 + 99) / 2) = 76

21-type-safety.adr.md
54-cli-framework.adr.md
76-appended-decision.adr.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 = dependency that higher-BSP items may rely on.

Cross-scope dependencies: Must be documented explicitly in the ADR content.

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

• •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](37-foo.adr.md) (markdown link with path)
• •Filenames can be renamed, slugs stay stable, markdown links update automatically

</why_no_numbers_in_content>

<why_markdown_links_only>

Problem: Plain text references like "ADR-23" or even `23-foo.adr.md` break when files are renumbered.

Solution: Markdown links [Decision Title](NN-slug.adr.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

</why_markdown_links_only>

</adr_templates>

<referencing_adrs>

<in_markdown_documents>

<within_same_directory>

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

</within_same_directory>

<from_child_to_parent_scope>

<!-- Feature ADR referencing capability ADR -->

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

<!-- Story referencing feature ADR -->

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

</from_child_to_parent_scope>

<from_work_item_to_adr>

<!-- From story to capability ADR -->

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

<!-- From feature to product ADR -->

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

</from_work_item_to_adr>

</in_markdown_documents>

<never_use_these_formats>

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

</never_use_these_formats>

<why_markdown_links>

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

</why_markdown_links>

</referencing_adrs>

<requirement_templates>

<prd_template>

Location: ${SKILL_DIR}/templates/product/product.prd.md

Purpose: Product requirements - user value, customer journey, measurable outcomes

Usage:

# Read PRD template
Read: ${SKILL_DIR}/templates/product/product.prd.md

# Adapt for product change
- Define user value proposition
- Document measurable outcomes with targets
- Specify acceptance criteria
- Avoid implementation details

Placement:

• •Product-wide: spx/{product-name}.prd.md
• •Capability catalyst: spx/NN-{slug}.capability/{topic}.prd.md

</prd_template>

<requirements_rules>

• •Immutable: Code adapts to requirements, not vice versa
• •Optional catalyst: PRD may exist as enrichment; spec file is always required
• •No TRDs: Technical details belong in feature.md, not separate documents

</requirements_rules>

</requirement_templates>

<work_item_templates>

<template_locations>

${SKILL_DIR}/templates/outcomes/capability-name.capability.md
${SKILL_DIR}/templates/outcomes/feature-name.feature.md
${SKILL_DIR}/templates/outcomes/story-name.story.md

</template_locations>

<usage_pattern>

# For capability
Read: ${SKILL_DIR}/templates/outcomes/capability-name.capability.md
Adapt: Replace {slug} with kebab-case name
       Fill functional requirements
       Add user value context

# For feature
Read: ${SKILL_DIR}/templates/outcomes/feature-name.feature.md
Adapt: Replace {slug} with kebab-case name
       Specify integration scope
       Define component interactions

# For story
Read: ${SKILL_DIR}/templates/outcomes/story-name.story.md
Adapt: Replace {slug} with kebab-case name
       Detail atomic implementation
       List specific functions/classes

</usage_pattern>

<file_placement>

Work items follow this pattern:

spx/{BSP}-{slug}.{type}/{slug}.{type}.md

Examples:

• •spx/21-core-cli.capability/core-cli.capability.md
• •spx/21-core-cli.capability/10-init.feature/init.feature.md
• •spx/21-core-cli.capability/15-init.feature/87-parse-flags.story/parse-flags.story.md

</file_placement>

<test_verification>

Tests stay co-located with their specs permanently. Test level is indicated by filename suffix:

• •Capability tests: spx/NN-{slug}.capability/tests/*.e2e.test.*
• •Feature tests: spx/.../NN-{slug}.feature/tests/*.integration.test.*
• •Story tests: spx/.../NN-{slug}.story/tests/*.unit.test.*

The outcomes.yaml ledger documents test verification and provides completion evidence.

</test_verification>

</work_item_templates>

<success_criteria> Skill is working correctly when:

• • Templates exist and are readable in templates/ subdirectories
• • Other skills can successfully read templates from appropriate sections
• • Progressive disclosure guides readers to relevant sections
• • ADR, requirement, and work item patterns are clearly documented
• • Test co-location paths are correctly specified for each level
• • BSP numbering uses consistent two-digit format (10-99)

</success_criteria>