Save PRD Skill

ROOT AGENT ONLY - Runs only from root Claude Code agent after HITL approval.

Purpose: Persist approved PRD artifacts to project directory Trigger: After hitl-approval phase completes in /architect workflow Input: PRD content, user stories, execution plan, innovations, architecture notes Output: Complete project directory ready for /build execution

Workflow

1. Detect project prefix

• Check git remote origin URL: git remote get-url origin
• Apply prefix mapping:

• Fallback: Check folder name for matches
• Final fallback: Ask user for 3-letter prefix

2. Auto-increment epic number

• Scan both directories for existing epics:
  • docs/projects/
  • docs/projects/completed/
• Extract folders matching {prefix}NNN-* pattern
• Find highest number for the detected prefix
• Increment by 1
• Format: Zero-padded 3 digits (e.g., 007)
• First epic for prefix starts at 001

3. Create project directory

• Generate directory name: docs/projects/{prefix}{NNN}-{kebab-case-name}/
• Example: docs/projects/msm007-user-authentication-api/
• Name derived from PRD title (lowercase, hyphens)
• Ensure docs/projects/ parent exists
• Create directory structure:

  {project-dir}/
  ├── prd.md
  ├── user-stories/
  ├── execution-plan.md
  ├── innovations-selected.md  # Optional - only if innovations selected
  └── architecture-notes.md
  

4. Save prd.md

• Write PRD content to {project-dir}/prd.md
• Include all sections:
  • Title, Overview, Goals
  • User Stories (summary list)
  • Success Criteria
  • Technical Requirements
  • Out of Scope
• Format: Markdown with proper headings

5. Save user-stories/ directory

• Create {project-dir}/user-stories/ subdirectory
• For each story, write individual file:
  • Filename: US-{NNN}-{slug}.md (e.g., US-001-user-auth.md)
  • Number: Zero-padded 3 digits
  • Slug: Derived from story title (kebab-case)
• Include in each story file:
  • Story ID, Title
  • Acceptance Criteria
  • Architecture annotations (files, imports, patterns)
  • Dependencies (if any)

6. Save execution-plan.md

• Write execution plan to {project-dir}/execution-plan.md
• Include:
  • Total stories, total waves
  • Wave breakdown with dependencies
  • Agent assignments
  • Parallel execution pairs
  • Gantt-style task schedule
• Format: Markdown with tables and lists

7. Save innovations-selected.md (conditional)

• Create only when: User selected one or more innovations
• Omit when: No innovations selected by user
• File: {project-dir}/innovations-selected.md
• Include:
  • List of selected innovations
  • Brief description of each
  • Impact on PRD (what changed)
• Format: Markdown with bullet lists

8. Save architecture-notes.md

• Write architecture validation notes to {project-dir}/architecture-notes.md
• Include:
  • Multi-mono repo findings (existing solutions referenced)
  • Example files discovered
  • Context7 validation results
  • Patterns to follow
  • Files to create/modify
• Format: Markdown with code blocks and file paths

9. Output final instruction

• Return absolute path to PRD
• Tell user: Run /build {absolute-path}/prd.md
• Example: Run /build /home/user/repo/docs/projects/msm007-user-auth/prd.md

Epic Number Detection Logic

function getNextEpicNumber(prefix):
  folders = listDirectories("docs/projects/")
  folders += listDirectories("docs/projects/completed/")

  existingNumbers = []
  for folder in folders:
    if folder matches pattern "{prefix}(\d{3})-.*":
      existingNumbers.append(extractNumber(folder))

  if existingNumbers is empty:
    return "001"

  maxNumber = max(existingNumbers)
  return zeroPad(maxNumber + 1, 3)

File Creation Order

1. Detect project prefix from git remote
2. Scan for existing epic numbers
3. Create parent directory (docs/projects/{prefix}{NNN}-{name}/)
4. Create user-stories/ subdirectory
5. Write prd.md
6. Write each US-{NNN}-{slug}.md file
7. Write execution-plan.md
8. Write innovations-selected.md (if applicable)
9. Write architecture-notes.md
10. Output instruction to user

Directory Naming Rules

Rules:

• Prefix: 3-letter project code (msm, mum, chc, msc)
• Number: Auto-incremented, zero-padded to 3 digits
• Name: Lowercase, words separated by hyphens
• Max name length: 50 characters (truncate if needed)
• Remove special characters except hyphens

User Story Filename Examples

Rules:

• Story ID: Zero-padded to 3 digits
• Slug: Derived from title (kebab-case)
• Max slug length: 40 characters

Error Handling

If directory with epic number exists:

• This indicates a race condition or manual creation
• Increment to next available number
• Log warning about skipped number

If prefix detection fails:

• Prompt user: "Enter 3-letter project prefix (e.g., msm, mum, chc):"
• Validate: Exactly 3 lowercase letters
• Proceed with user-provided prefix

If parent doesn't exist:

• Create docs/projects/ directory first
• Then create project directory

If write fails:

• Halt workflow
• Report error with file path
• Stop execution and wait for user intervention

Integration

Called by:

• /architect command (Phase 7: Output)

Calls:

• File system operations (Write tool)
• Git operations (remote detection)
• No agent spawning required

Next step: User executes /build {prd-path}

Example

Input:
  PRD Title: "User Authentication API"
  Project: metasaver-marketplace (detected from git remote)
  Existing epics: msm001, msm002, msm003, msm005, msm006
  Stories: 5 enriched stories with architecture notes
  Execution Plan: 3 waves, 5 TDD pairs
  Innovations: 2 selected (passwordless auth, MFA)
  Architecture Notes: Multi-mono findings, Context7 validation

Save PRD Phase (this skill):
  1. Detect prefix: "msm" (from git remote containing "metasaver-marketplace")
  2. Scan docs/projects/ and docs/projects/completed/
  3. Find highest: msm006 -> next is msm007
  4. Create directory: docs/projects/msm007-user-authentication-api/
  5. Write prd.md (all sections)
  6. Write user-stories/:
     - US-001-auth-schema.md
     - US-002-auth-service.md
     - US-003-token-service.md
     - US-004-login-endpoint.md
     - US-005-logout-endpoint.md
  7. Write execution-plan.md (3 waves, dependencies)
  8. Write innovations-selected.md (passwordless, MFA)
  9. Write architecture-notes.md (multi-mono, patterns)
  10. Output: "Run /build /home/user/repo/docs/projects/msm007-user-authentication-api/prd.md"

Result:
  docs/projects/msm007-user-authentication-api/
  ├── prd.md
  ├── user-stories/
  │   ├── US-001-auth-schema.md
  │   ├── US-002-auth-service.md
  │   ├── US-003-token-service.md
  │   ├── US-004-login-endpoint.md
  │   └── US-005-logout-endpoint.md
  ├── execution-plan.md
  ├── innovations-selected.md
  └── architecture-notes.md

Notes

• This is a WRITE skill - creates files, does not modify existing ones
• Always run AFTER hitl-approval (user must approve before saving)
• Output structure matches PRD specification from architect-command-target-state.md
• NO EXECUTION - /architect is planning only, /build executes the PRD
• Epic numbers provide traceable project identifiers across repositories