prd-converter

name

prd-converter

description

Convert markdown PRDs into prd.json execution format for SDK Bridge autonomous agents. Use when a PRD document exists and needs to be converted to SDK Bridge's JSON format. Trigger on 'convert prd', 'convert to prd.json', 'turn this PRD into sdk-bridge format', 'create prd.json from this PRD'. Also used internally by /sdk-bridge:start at the conversion checkpoint. Do NOT trigger on general JSON conversion or plan execution requests.

SDK Bridge PRD Converter

Converts existing PRDs to the prd.json format that SDK Bridge uses for Agent Teams execution.

---

The Job

Take a PRD (markdown file or text) and convert it to prd.json in your project directory.

---

Output Format (Enhanced Schema)

{
  "project": "[Project Name]",
  "branchName": "sdk-bridge/[feature-name-kebab-case]",
  "description": "[Feature description from PRD title/intro]",
  "userStories": [
    {
      "id": "US-001",
      "title": "[Story title]",
      "description": "As a [user], I want [feature] so that [benefit]",
      "acceptanceCriteria": [
        "Criterion 1",
        "Criterion 2 with verification",
        "Typecheck passes"
      ],
      "priority": 1,
      "passes": false,
      "notes": "",
      "depends_on": [],
      "related_to": [],
      "implementation_hint": "",
      "check_before_implementing": []
    }
  ]
}

New Schema Fields (Phase 3 Enhancements)

• depends_on (array): IDs of stories that MUST complete before this one (e.g., ["US-001", "US-005"])
• related_to (array): IDs of stories that may contain related work to check (e.g., ["US-002"])
• implementation_hint (string): Guidance like "Check if US-005 already implemented this" or "Reuse existing badge component"
• check_before_implementing (array): Commands to run to verify existing implementation (e.g., ["grep cabin_class api.py"])

When to use each:

• depends_on: Hard dependency - this story CANNOT be done until dependency completes
• related_to: Soft dependency - check this story for similar code or patterns
• implementation_hint: Free-form text guidance for the agent
• check_before_implementing: Specific search commands to detect existing implementation

---

Story Size: The Number One Rule

Each story should be independently implementable by one teammate in a single session.

SDK Bridge uses Agent Teams — multiple teammates run in parallel, each claiming and implementing one story at a time. Stories must be self-contained: a teammate implementing US-003 cannot rely on in-progress work from another teammate implementing US-002.

Right-sized stories (3-5 criteria):

Data Layer:

• Add new field to data model with validation
• Create migration for schema change
• Implement data access method for new query

Logic Layer:

• Add business rule validation
• Implement calculation or transformation logic
• Add error handling for specific failure case

Presentation Layer:

• Create reusable component with basic functionality
• Add interaction handler (click, submit, etc.)
• Implement visual state (loading, error, success)

Too big (8+ criteria - must split):

Pattern: "Build entire [subsystem]"

• ❌ Single story: All layers combined
• ✅ Split into: Data → Logic → Presentation → Integration

Pattern: "Add complex [feature]"

• ❌ Single story: All configuration + functionality + edge cases
• ✅ Split into: Core behavior → Options → Error handling

Pattern: "Refactor [large module]"

• ❌ Single story: Entire module at once
• ✅ Split into: One story per file/function/component

Rule of thumb: If you cannot describe the change in 2-3 sentences, it is too big.

Validation Rules:

• ✅ Ideal: 3-5 acceptance criteria (including typecheck/browser verification)
• ⚠️ Warning: 6-7 criteria - consider splitting if possible
• ❌ Too large: 8+ criteria - MUST split into multiple stories
• Time target: Each story should complete in 10-20 minutes

After converting, check for oversized stories:

jq '.userStories[] | select((.acceptanceCriteria | length) > 7) | "\(.id): \(.title) - \(.acceptanceCriteria | length) criteria (TOO LARGE)"'

If you find stories with 8+ criteria, recommend splitting them in your output.

---

Story Ordering: Dependencies First

Stories execute in priority order. Earlier stories must not depend on later ones.

Correct order:

1. Schema/database changes (migrations)
2. Server actions / backend logic
3. UI components that use the backend
4. Dashboard/summary views that aggregate data

Wrong order:

1. UI component (depends on schema that does not exist yet)
2. Schema change

---

Acceptance Criteria: Must Be Verifiable

Each criterion must be something SDK Bridge can CHECK, not something vague.

Good criteria (verifiable):

• "Add status column to tasks table with default 'pending'"
• "Filter dropdown has options: All, Active, Completed"
• "Clicking delete shows confirmation dialog"
• "Typecheck passes"
• "Tests pass"

Bad criteria (vague):

• "Works correctly"
• "User can do X easily"
• "Good UX"
• "Handles edge cases"

Always include as final criterion:

"Typecheck passes"

For stories with testable logic, also include:

"Tests pass"

For stories that change UI, also include:

"Verify in browser using dev-browser skill"

Frontend stories are NOT complete until visually verified. SDK Bridge will use the dev-browser skill to navigate to the page, interact with the UI, and confirm changes work.

---

Conversion Rules

1. Each user story becomes one JSON entry
2. IDs: Sequential (US-001, US-002, etc.)
3. Priority: Based on dependency order, then document order
4. All stories: passes: false and empty notes
5. branchName: Derive from feature name, kebab-case, prefixed with sdk-bridge/
6. Always add: "Typecheck passes" to every story's acceptance criteria
7. Infer dependencies: Detect depends_on, related_to, and add hints (see below)

Dependency Inference Rules

Auto-detect depends_on:

• Backend stories depend on schema/database stories
• UI stories depend on backend API/service stories
• Integration stories depend on component stories
• Look for explicit "Depends on: US-XXX" in PRD

⚠️ Avoid False Dependencies:

• NOT all stories need to depend on the previous story
• Stories can run in parallel if they work on different files/modules
• Only add depends_on for TRUE blocking dependencies
• Test: Can this story be implemented without the previous story being complete? If yes, don't add dependency

True Dependencies (add depends_on):

• Data model required before business logic using it
• API endpoint required before UI consuming it
• Authentication required before protected features
• Base component required before extensions/variants
• Configuration required before features using it

False Dependencies (NO depends_on, use related_to):

• Two UI components in different parts of the app
• Two API endpoints serving different purposes
• Two database tables with no foreign key relationship
• Parallel implementation tracks (e.g., UI theme + API layer)
• Sequential numbering doesn't imply dependency

Auto-detect related_to:

• Stories working on the same file/module
• Stories in the same feature area (e.g., all "priority" stories)
• Frontend and backend halves of the same feature
• Later stories in a sequence (US-007 related to US-005, US-006)

Generate implementation_hint:

• If related_to is not empty: "Check US-XXX for similar implementation patterns"
• If UI story follows data/API story: "US-XXX may have already implemented the data layer for this"
• If splitting a feature: "This is part of [feature area], coordinate with US-XXX for consistency"
• If extending existing work: "Builds on US-XXX, review that implementation before starting"

Generate check_before_implementing: Extract key identifiers from acceptance criteria and create search commands:

For data models: grep -rn "[ModelName]\|[field_name]" src/models/ For API/services: grep -rn "[endpoint_name]\|[function_name]" src/api/ src/services/ For UI components: grep -rn "[ComponentName]" src/components/ src/pages/ For configuration: grep -rn "[config_key]" config/ .env

Use actual identifiers from the story (class names, function names, field names), not generic terms.

Example: Dependency Detection

Scenario: Feature requiring data model, API endpoint, and UI

PRD Stories:

### US-010: Add status field to data model
### US-011: Create filtering API endpoint
### US-012: Build filter UI component

Dependency Analysis:

• US-011 needs US-010 (can't filter by status field that doesn't exist) → depends_on: ["US-010"]
• US-012 needs US-011 (UI needs API to call) → depends_on: ["US-011"]
• US-012 related to US-010 (both involve "status" concept) → related_to: ["US-010"]

Converted to JSON:

{
  "id": "US-012",
  "title": "Build filter UI component",
  "depends_on": ["US-011"],
  "related_to": ["US-010"],
  "implementation_hint": "US-010 added the status field to the data model. US-011 implemented the filtering endpoint. Review both for field names and API contract.",
  "check_before_implementing": [
    "grep -rn 'status' src/models/",
    "grep -rn 'filter.*status' src/api/"
  ]
}

---

Splitting Large Features

Apply systematic decomposition when features have 8+ acceptance criteria:

Pattern 1: Layer-Based Split

Monolithic: "Add [feature] system"
↓
Decomposed:
1. "Implement [feature] data model"
2. "Create [feature] business logic"
3. "Build [feature] API endpoints"
4. "Design [feature] UI components"
5. "Add [feature] user workflows"

Pattern 2: Capability-Based Split

Monolithic: "Build advanced [feature]"
↓
Decomposed:
1. "Implement basic [feature] functionality"
2. "Add [feature] configuration options"
3. "Implement [feature] batch operations"
4. "Add [feature] export capability"

Pattern 3: Journey-Based Split

Monolithic: "Implement [workflow]"
↓
Decomposed:
1. "Implement [workflow] step 1: [action]"
2. "Implement [workflow] step 2: [action]"
3. "Implement [workflow] step 3: [action]"
4. "Add [workflow] error recovery"

Each story focuses on one responsibility and can be verified independently.

---

Example

Input PRD:

# Task Status Feature

Add ability to mark tasks with different statuses.

## Requirements
- Toggle between pending/in-progress/done on task list
- Filter list by status
- Show status badge on each task
- Persist status in database

Output prd.json:

{
  "project": "TaskApp",
  "branchName": "sdk-bridge/task-status",
  "description": "Task Status Feature - Track task progress with status indicators",
  "userStories": [
    {
      "id": "US-001",
      "title": "Add status field to tasks table",
      "description": "As a developer, I need to store task status in the database.",
      "acceptanceCriteria": [
        "Add status column: 'pending' | 'in_progress' | 'done' (default 'pending')",
        "Generate and run migration successfully",
        "Typecheck passes"
      ],
      "priority": 1,
      "passes": false,
      "notes": ""
    },
    {
      "id": "US-002",
      "title": "Display status badge on task cards",
      "description": "As a user, I want to see task status at a glance.",
      "acceptanceCriteria": [
        "Each task card shows colored status badge",
        "Badge colors: gray=pending, blue=in_progress, green=done",
        "Typecheck passes",
        "Verify in browser using dev-browser skill"
      ],
      "priority": 2,
      "passes": false,
      "notes": "",
      "depends_on": ["US-001"],
      "related_to": [],
      "implementation_hint": "Reuse existing badge component if available, just add status color variants.",
      "check_before_implementing": [
        "grep -r 'Badge' components/",
        "grep status tasks/"
      ]
    },
    {
      "id": "US-003",
      "title": "Add status toggle to task list rows",
      "description": "As a user, I want to change task status directly from the list.",
      "acceptanceCriteria": [
        "Each row has status dropdown or toggle",
        "Changing status saves immediately",
        "UI updates without page refresh",
        "Typecheck passes",
        "Verify in browser using dev-browser skill"
      ],
      "priority": 3,
      "passes": false,
      "notes": ""
    },
    {
      "id": "US-004",
      "title": "Filter tasks by status",
      "description": "As a user, I want to filter the list to see only certain statuses.",
      "acceptanceCriteria": [
        "Filter dropdown: All | Pending | In Progress | Done",
        "Filter persists in URL params",
        "Typecheck passes",
        "Verify in browser using dev-browser skill"
      ],
      "priority": 4,
      "passes": false,
      "notes": ""
    }
  ]
}

---

Archiving Previous Runs

Before writing a new prd.json, check if there is an existing one from a different feature:

1. Read the current prd.json if it exists
2. Check if branchName differs from the new feature's branch name
3. If different AND progress.jsonl exists and is non-empty:
   • Create archive folder: archive/YYYY-MM-DD-feature-name/
   • Copy current prd.json and progress.jsonl to archive
   • Remove progress.jsonl (it will be recreated fresh by implementer teammates)

If you are manually updating prd.json between runs, archive first.

---

Dependency Graph Output

After writing prd.json, output a dependency analysis to help the team lead decide how many teammates to spawn:

## Dependency Graph

Parallel groups (can run simultaneously):
- Group 1: US-001 (no deps)
- Group 2: US-002, US-003 (depend on US-001, independent of each other)
- Group 3: US-004 (depends on US-002, US-003)

Suggested teammate count: 2 (max parallelism in Group 2)

Total stories: 4 | Parallelizable: 2 | Sequential: 2

This helps the start command calculate min(max_teammates, max_parallel_group_size).

---

Checklist Before Saving

Before writing prd.json, verify:

• Previous run archived (if prd.json exists with different branchName, archive it first)
• Each story is independently implementable by one teammate (self-contained)
• Stories are ordered by dependency (schema to backend to UI)
• Every story has "Typecheck passes" as criterion
• UI stories have "Verify in browser using dev-browser skill" as criterion
• Acceptance criteria are verifiable (not vague)
• No story depends on a later story
• Output dependency graph analysis after saving