Embed Acceptance Criteria from Living Docs

You are helping the user embed Acceptance Criteria from living documentation into increment spec.md.

Context

Problem: The AC sync hook requires ACs to be in spec.md, but some increments use

structure: user-stories

which references external living docs without embedding ACs inline.

Solution: This command auto-embeds ACs from living docs into spec.md, ensuring sync hooks work correctly.

Architecture: spec.md is ALWAYS the source of truth for ACs, even when living docs exist as a documentation layer. (See ADR-0062)

Usage

/sw:embed-acs <increment-id>

Arguments

• <increment-id>

  : Required. Increment ID (e.g., "0050", "50", "0050-feature-name")

Workflow

Step 1: Parse and Validate Arguments

1. Extract increment ID:

   • Parse from command:

     /sw:embed-acs 0050

     → "0050"
   • Normalize to 4-digit format: "0050"
   • Support formats: "50", "0050", "0050-feature-name"

2. Validate increment exists:

   • List directories in

     .specweave/increments/

   • Find matching increment (e.g.,

     0050-external-tool-import-phase-1b-7

     )
   • If not found: Show error with available increments

Example output if not found:

❌ Error: Increment 0050 not found

Available increments:
  • 0048-external-tool-import-enhancement
  • 0049-cli-first-init-flow

Usage: /sw:embed-acs <increment-id>

Step 2: Validate Increment Structure

1. Check spec.md exists:

   ls .specweave/increments/0050-*/spec.md
   

2. Check for

   structure: user-stories

   in frontmatter:

   grep "structure: user-stories" spec.md
   

3. If NOT using living docs structure:

   ℹ️  Info: Increment 0050 does not use 'structure: user-stories'
   
   This command is intended for increments that reference external living docs.
   For standard increments, ACs should already be in spec.md.
   
   Do you want to proceed anyway? [Y/n]:
   

Step 3: Find Living Docs Path

1. Extract feature_id from spec.md frontmatter:

   grep "feature_id:" spec.md | cut -d: -f2 | tr -d ' '
   

2. Construct living docs path:

   .specweave/docs/internal/specs/specweave/{feature_id}/
   

3. Validate living docs path exists:

   ls .specweave/docs/internal/specs/specweave/FS-048/
   

4. If living docs not found:

   ❌ Error: Living docs not found for feature FS-048
   
   Expected path: .specweave/docs/internal/specs/specweave/FS-048/
   Actual path: Not found
   
   This increment may not have living docs, or they're in a different location.
   
   Please specify living docs path manually:
     /sw:embed-acs 0050 --living-docs-path <path>
   

Step 4: Extract User Stories from spec.md

1. Read user_stories from frontmatter:

   user_stories:
     - US-001
     - US-002
     - US-004
   

2. Display user stories to embed:

   Found 7 user stories in spec.md frontmatter:
     • US-001: Smart Pagination During Init
     • US-002: CLI-First Defaults
     • US-004: Smart Caching with TTL
     • US-005: Dedicated Import Commands
     • US-006: ADO Area Path Mapping
     • US-007: Progress Tracking
     • US-008: Smart Filtering
   

Step 5: Extract ACs from Living Docs

1. For each user story, find corresponding file:

   # Try multiple file naming patterns
   find .specweave/docs/internal/specs/specweave/FS-048/ -name "us-001-*.md"
   find .specweave/docs/internal/specs/specweave/FS-048/ -name "US-001.md"
   

2. Extract ACs from each file:

   grep -E "^### AC-US[0-9]+-[0-9]+:" us-001-smart-pagination-during-init.md
   

3. Display extraction progress:

   Extracting ACs from living docs...
     ✓ US-001: Found 5 ACs (AC-US1-01 to AC-US1-05)
     ✓ US-002: Found 4 ACs (AC-US2-01 to AC-US2-04)
     ✓ US-004: Found 5 ACs (AC-US4-01 to AC-US4-05)
     ✓ US-005: Found 7 ACs (AC-US5-01 to AC-US5-07)
     ✓ US-006: Found 6 ACs (AC-US6-01 to AC-US6-06)
     ✓ US-007: Found 6 ACs (AC-US7-01 to AC-US7-06)
     ✓ US-008: Found 6 ACs (AC-US8-01 to AC-US8-06)
   
   Total: 39 Acceptance Criteria extracted
   

Step 6: Check for Existing ACs

1. Check if spec.md already has AC section:

   grep -q "## Acceptance Criteria" spec.md
   

2. If ACs already exist:

   ⚠️  Warning: spec.md already contains Acceptance Criteria section
   
   Found 39 existing ACs in spec.md.
   
   What would you like to do?
     [R] Replace existing ACs with freshly embedded ones
     [M] Merge (keep existing + add missing)
     [C] Cancel
   
   Choice:
   

3. If user chooses "Replace": Remove old AC section, add new one

4. If user chooses "Merge": Smart merge (add only missing ACs)

5. If user chooses "Cancel": Exit without changes

Step 7: Format and Embed ACs

1. Format ACs as markdown:

   ## Acceptance Criteria
   
   <!-- Auto-synced from living docs -->
   
   ### US-001: Smart Pagination During Init
   
   - [ ] **AC-US1-01**: 50-Project Limit During Init
   - [ ] **AC-US1-02**: Explicit Choice Prompt
   - [ ] **AC-US1-03**: Async Fetch for "Import All"
   - [ ] **AC-US1-04**: Init Completes < 30 Seconds
   - [ ] **AC-US1-05**: No Timeout Errors
   
   ### US-002: CLI-First Defaults
   
   - [ ] **AC-US2-01**: "Import All" as Default Choice
   - [ ] **AC-US2-02**: All Projects Checked in Checkbox Mode
   - [ ] **AC-US2-03**: Clear Deselection Instructions
   - [ ] **AC-US2-04**: Easy Override for "Select None"
   
   ...
   

2. Find insertion point in spec.md:

   • After "## Implementation Summary" section, OR
   • Before final line if no summary section

3. Use Edit tool to insert ACs:

   Edit({
     file_path: "spec.md",
     old_string: "**See**: [plan.md](./plan.md)...",
     new_string: "**See**: [plan.md](./plan.md)...\n\n---\n\n" + acMarkdown
   });
   

Step 8: Update metadata.json

1. Count total ACs:

   grep -cE "^- \[ \] \*\*AC-US[0-9]+-[0-9]+\*\*:" spec.md
   

2. Update metadata.json:

   {
     "total_acs": 39,
     "completed_acs": 0
   }
   

3. Use Edit tool to update:

   Edit({
     file_path: "metadata.json",
     old_string: '"total_acs": 32,',
     new_string: '"total_acs": 39,'
   });
   

Step 9: Validate Embedding

1. Re-count ACs in spec.md:

   grep -cE "^- \[[x ]\] \*\*AC-US[0-9]+-[0-9]+\*\*:" spec.md
   

2. Validate format:

   • All ACs follow pattern:

     - [ ] **AC-US1-01**: Title

   • No duplicate AC IDs
   • All user stories represented

3. Display validation results:

   ✅ Validation: PASSED
   
   Embedded 39 Acceptance Criteria into spec.md:
     • US-001: 5 ACs
     • US-002: 4 ACs
     • US-004: 5 ACs
     • US-005: 7 ACs
     • US-006: 6 ACs
     • US-007: 6 ACs
     • US-008: 6 ACs
   
   metadata.json updated: total_acs = 39
   
   Next steps:
     1. Review embedded ACs in spec.md
     2. Run: /sw:validate 0050
     3. Start work: /sw:do
   

Flags (Optional)

--living-docs-path <path>

Manually specify living docs path if auto-detection fails:

/sw:embed-acs 0050 --living-docs-path .specweave/docs/internal/specs/specweave/FS-048

--dry-run

Preview what would be embedded without modifying files:

/sw:embed-acs 0050 --dry-run

Output:

[DRY RUN] Would embed 39 ACs into spec.md

Preview:
  • US-001: 5 ACs (AC-US1-01 to AC-US1-05)
  • US-002: 4 ACs (AC-US2-01 to AC-US2-04)
  ...

No files modified.

--force

Skip confirmation prompts:

/sw:embed-acs 0050 --force

Error Handling

Living Docs Not Found

❌ Error: Living docs not found for feature FS-048

Expected: .specweave/docs/internal/specs/specweave/FS-048/
Found: Directory does not exist

Possible solutions:
  1. Check if feature_id in spec.md is correct
  2. Manually specify path: --living-docs-path <path>
  3. Create living docs first: /sw:sync-docs

No User Stories in spec.md

❌ Error: No user_stories field in spec.md frontmatter

This command requires user_stories to be listed in spec.md.

Add to spec.md frontmatter:
  user_stories:
    - US-001
    - US-002
    ...

User Story File Not Found

⚠️  Warning: User story file not found for US-003

Expected paths tried:
  • .specweave/docs/internal/specs/specweave/FS-048/us-003.md
  • .specweave/docs/internal/specs/specweave/FS-048/US-003.md
  • .specweave/docs/internal/specs/specweave/FS-048/us-003-*.md

Continuing with remaining user stories...

No ACs Found in User Story

⚠️  Warning: No ACs found in US-005 file

File: .specweave/docs/internal/specs/specweave/FS-048/us-005-dedicated-import-commands.md

This file may be incomplete or use a different AC format.
Skipping US-005 for now.

Integration with Other Commands

This command is referenced by:

1. /sw:validate

   : Suggests running

   /sw:embed-acs

   when ACs are missing

2. /sw:do

   : Pre-start hook suggests this command if validation fails

3. /sw:increment

   : Should auto-call this when creating

   structure: user-stories

   increments

Examples

Example 1: Basic Usage

/sw:embed-acs 0050

Output:

Embedding ACs from living docs for increment 0050-external-tool-import-phase-1b-7...

Living docs path: .specweave/docs/internal/specs/specweave/FS-048/

Extracting ACs...
  ✓ US-001: 5 ACs
  ✓ US-002: 4 ACs
  ✓ US-004: 5 ACs
  ✓ US-005: 7 ACs
  ✓ US-006: 6 ACs
  ✓ US-007: 6 ACs
  ✓ US-008: 6 ACs

✅ Embedded 39 ACs into spec.md
✅ Updated metadata.json (total_acs: 39)

Example 2: Dry Run

/sw:embed-acs 0050 --dry-run

Output:

[DRY RUN] Embedding ACs for increment 0050...

Would extract 39 ACs from 7 user stories.
No files would be modified.

To apply changes, run without --dry-run flag.

Example 3: Manual Path

/sw:embed-acs 0050 --living-docs-path .specweave/docs/internal/specs/custom/FS-048

Output:

Using custom living docs path: .specweave/docs/internal/specs/custom/FS-048

Extracting ACs...
  ✓ US-001: 5 ACs
  ...

Related Commands

• /sw:increment

  : Create new increment (should auto-embed ACs)

• /sw:validate

  : Validate increment (checks AC presence)

• /sw:do

  : Start increment (pre-start hook validates ACs)

• /sw:sync-docs

  : Sync living documentation

Related Documentation

• ADR-0062: AC Embedding Architecture
• CLAUDE.md: Rule #X (spec.md AC presence requirement)
• src/utils/ac-embedder.ts: AC embedding utility (implementation)
• src/core/validators/ac-presence-validator.ts: AC presence validation

---

Important: This command should NOT be needed in the future if spec generators are updated to auto-embed ACs during increment creation. Consider this a migration/fix utility for existing increments.