prd-converter

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