embed-acs

Auto-embed Acceptance Criteria from living docs into increment spec.md for hook compatibility

majiayu000/claude-skill-registry·0installs660stars

SKILL.md

Full skill instructions

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

Extract increment ID:
- Parse from command: /sw:embed-acs 0050 → "0050"
- Normalize to 4-digit format: "0050"
- Support formats: "50", "0050", "0050-feature-name"
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

Check spec.md exists:

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

Check for structure: user-stories in frontmatter:
```
grep "structure: user-stories" spec.md
```

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

Extract feature_id from spec.md frontmatter:

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

Construct living docs path:

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

Validate living docs path exists:

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

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

Read user_stories from frontmatter:

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

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

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"

Extract ACs from each file:

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

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

Check if spec.md already has AC section:

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

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:

If user chooses "Replace": Remove old AC section, add new one
If user chooses "Merge": Smart merge (add only missing ACs)
If user chooses "Cancel": Exit without changes

Step 7: Format and Embed ACs

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"

...

Find insertion point in spec.md:
- After "## Implementation Summary" section, OR
- Before final line if no summary section

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

Count total ACs:

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

Update metadata.json:

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

Use Edit tool to update:

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

Step 9: Validate Embedding

Re-count ACs in spec.md:

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

Validate format:
- All ACs follow pattern: - [ ] **AC-US1-01**: Title
- No duplicate AC IDs
- All user stories represented

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:

/sw:validate: Suggests running /sw:embed-acs when ACs are missing
/sw:do: Pre-start hook suggests this command if validation fails
/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

Install skill

Copy and run in your terminal

npx -y skills add https://github.com/majiayu000/claude-skill-registry --skill embed-acs

View on GitHub

skills/data/embed-acs/SKILL.md

embed-acs

SKILL.md

Embed Acceptance Criteria from Living Docs

Context

Usage

Arguments

Workflow

Step 1: Parse and Validate Arguments

Step 2: Validate Increment Structure

Step 3: Find Living Docs Path

Step 4: Extract User Stories from spec.md

Step 5: Extract ACs from Living Docs

Step 6: Check for Existing ACs

Step 7: Format and Embed ACs

Step 8: Update metadata.json

Step 9: Validate Embedding

Flags (Optional)

--living-docs-path <path>

--dry-run

--force

Error Handling

Living Docs Not Found

No User Stories in spec.md

User Story File Not Found

No ACs Found in User Story

Integration with Other Commands

Examples

Example 1: Basic Usage

Example 2: Dry Run

Example 3: Manual Path

Related Commands

Related Documentation

`--living-docs-path <path>`

`--dry-run`

`--force`