[Phase 1] PRD template system for customizable output formats

[frankbria]

Summary

Add support for PRD templates that allow users to customize the structure and format of generated PRDs. Currently, cf prd generate produces a fixed markdown format. This enhancement would allow projects to define their own PRD structure, sections, and formatting requirements.

Motivation

Different organizations and projects have varying PRD formats:

• Enterprise teams may require specific compliance sections
• Startups might prefer lean canvas-style PRDs
• Regulated industries need detailed requirements traceability
• Some teams prefer user story maps vs. feature lists

A template system would make CodeFRAME's PRD generation adaptable to these diverse needs while maintaining the Socratic discovery process.

Proposed Design

Template Definition Language

Templates would be defined in a YAML or Markdown-based DSL:

# .codeframe/prd-template.yaml
name: "Enterprise PRD Template"
version: 1

sections:
  - id: executive_summary
    title: "Executive Summary"
    required: true
    source: problem  # Maps to discovery category
    format: |
      ## Executive Summary
      
      ### Problem Statement
      {{ answers.problem_1 }}
      
      ### Business Justification
      {{ answers.problem_2 | default: "Not specified" }}

  - id: stakeholders
    title: "Stakeholders & Users"
    required: true
    source: users
    format: |
      ## Stakeholders
      
      ### Primary Users
      {{ extracted.users | bullet_list }}
      
      ### User Personas
      {% for user in extracted.users %}
      - **{{ user }}**: {{ generate_persona(user) }}
      {% endfor %}

  - id: requirements
    title: "Functional Requirements"
    required: true
    source: features
    format: |
      ## Functional Requirements
      
      | ID | Requirement | Priority | Source |
      |----|-------------|----------|--------|
      {% for feature in extracted.features %}
      | FR-{{ loop.index }} | {{ feature }} | P1 | Discovery |
      {% endfor %}

  - id: constraints
    title: "Technical Constraints"
    required: false
    source: constraints
    
  - id: acceptance
    title: "Acceptance Criteria"
    required: true
    auto_generate: true  # AI generates from features

Template Variables

Available variables in templates:

Variable	Description
answers.<question_id>	Raw answer text for a specific question
answers_by_category.<category>	All answers in a category
extracted.features	Features extracted by AnswerCapture
extracted.users	User types extracted
extracted.constraints	Constraints dict
metadata.project_name	From workspace config
metadata.generated_at	Timestamp
metadata.session_id	Discovery session ID

Template Functions

Function	Description
bullet_list(items)	Convert list to markdown bullets
numbered_list(items)	Convert list to numbered list
table(items, columns)	Generate markdown table
generate_persona(user)	AI-generate user persona
generate_acceptance(feature)	AI-generate acceptance criteria
summarize(text, max_words)	Summarize long text

CLI Integration

# Use project template
cf prd generate

# Use specific template
cf prd generate --template enterprise

# List available templates
cf prd templates list

# Import template from URL/file
cf prd templates import https://example.com/template.yaml
cf prd templates import ./my-template.yaml

# Export current format as template
cf prd templates export > my-template.yaml

Built-in Templates

Ship with several default templates:

1. standard (current default) - Balanced PRD for general use
2. lean - Minimal viable PRD (problem, users, MVP features)
3. enterprise - Full formal PRD with traceability
4. user-story-map - Organized around user journeys
5. technical-spec - Focused on technical requirements

Storage

• Global templates: ~/.codeframe/templates/
• Project templates: .codeframe/templates/
• Template registry: Optional remote template sharing

Implementation Considerations

Discovery Question Mapping

Templates may require additional discovery questions beyond the current 5 required + 5 optional. The template system should:

1. Define required discovery categories
2. Allow custom questions per template
3. Map questions to template sections

Backward Compatibility

• Default template matches current output format
• Existing PRDs remain valid
• Template field optional on PRD records

Validation

• Validate template syntax on import
• Ensure all required sections have data sources
• Warn about unmapped discovery answers

Tasks

• Design template DSL specification
• Implement template parser
• Add template storage (global + project)
• Modify _build_prd_content() to use templates
• Create built-in templates
• Add cf prd templates subcommands
• Update documentation
• Add template validation
• Tests for template rendering

Related

• Implements enhancement for [Phase 1] cf prd generate - Interactive AI PRD creation (Socratic Discovery) #307 (cf prd generate)
• Part of Phase 1: CLI Completion

Labels

enhancement, phase-1, prd

[traycerai]

Plan

Observations

The codebase has a well-established foundation for implementing PRD templates. The current PRD generation logic resides in file:codeframe/agents/lead_agent.py with a hardcoded template in the _build_prd_prompt() method. An existing task template system in file:codeframe/planning/task_templates.py provides a proven pattern for template management, storage, and application. The workspace uses .codeframe/ for project-level configuration with YAML support already in place via file:codeframe/core/config.py. The CLI uses Typer with a modular structure, and there's already a templates_app registered for task templates that can be extended.

Approach

The implementation will follow the existing task template pattern, creating a parallel PRD template system. Templates will be stored as YAML files in both global (~/.codeframe/templates/prd/) and project-level (.codeframe/templates/prd/) directories. A new PrdTemplateManager class will handle template loading, validation, and rendering using Jinja2 for variable substitution and template functions. The current hardcoded PRD generation in LeadAgent._build_prd_prompt() will be refactored to use the template system while maintaining backward compatibility through a default "standard" template. CLI commands will be added under a new cf prd templates subcommand group to manage templates.

Implementation Steps

1. Create PRD Template Data Structures

File: file:codeframe/planning/prd_templates.py (new)

Create dataclasses for PRD template structure:

• PrdTemplateSection: Represents a single section with id, title, required flag, source category, and format template
• PrdTemplate: Contains template metadata (id, name, version, description) and list of sections
• Define template variable schema and available functions (bullet_list, numbered_list, table, generate_persona, etc.)

2. Implement Template Manager

File: file:codeframe/planning/prd_templates.py

Create PrdTemplateManager class with methods:

• __init__(): Initialize with builtin templates
• load_template(template_id: str): Load from global or project directories
• list_templates(): List available templates with metadata
• get_template(template_id: str): Retrieve specific template
• validate_template(template: PrdTemplate): Validate structure and required fields
• render_template(template: PrdTemplate, discovery_data: dict): Render using Jinja2
• import_template(source_path: Path): Import from file or URL
• export_template(template_id: str, output_path: Path): Export template to file

3. Create Built-in Templates

File: file:codeframe/planning/prd_templates.py

Define 5 built-in templates as YAML structures:

• standard: Current default format (executive summary, problem statement, user personas, features, technical architecture, success metrics, timeline)
• lean: Minimal viable PRD (problem, users, MVP features only)
• enterprise: Full formal PRD with compliance sections, traceability matrix, stakeholder analysis, risk assessment
• user-story-map: Organized around user journeys with story mapping structure
• technical-spec: Focused on technical requirements, architecture diagrams, API specifications, data models

4. Implement Template Storage

Directories:

• Global: ~/.codeframe/templates/prd/
• Project: .codeframe/templates/prd/

Create helper functions in file:codeframe/planning/prd_templates.py:

• get_global_template_dir(): Return Path to global template directory
• get_project_template_dir(workspace: Workspace): Return Path to project template directory
• save_template_to_file(template: PrdTemplate, path: Path): Serialize template to YAML
• load_template_from_file(path: Path): Deserialize YAML to PrdTemplate
• Template discovery: Search both global and project directories, with project templates taking precedence

5. Integrate with Discovery System

File: file:codeframe/discovery/answers.py

Enhance AnswerCapture.get_structured_data() to return template-compatible data:

• Add answers_by_category mapping
• Include metadata dict with project_name, generated_at, session_id
• Ensure extracted dict contains features, users, constraints as expected by templates
• Add method get_template_context() that formats data specifically for template rendering

6. Refactor PRD Generation in LeadAgent

File: file:codeframe/agents/lead_agent.py

Modify generate_prd() method:

• Add optional template_id parameter (defaults to "standard")
• Initialize PrdTemplateManager instance
• Load specified template or fall back to default
• Replace _build_prd_prompt() call with template rendering

Update _build_prd_prompt() method:

• Rename to _render_prd_from_template(template: PrdTemplate, structured_data: dict)
• Use Jinja2 to render template sections
• Apply template functions (bullet_list, generate_persona, etc.)
• Return rendered markdown content

7. Add Template Field to PRD Storage

File: file:codeframe/core/prd.py

Update PrdRecord dataclass:

• Add template_id: Optional[str] = None field
• Update store() function to accept and save template_id in metadata
• Update get_latest(), get_by_id(), list_all() to include template_id

File: file:codeframe/core/workspace.py

Add database migration in _ensure_schema_upgrades():

• Check if template_id column exists in prds table
• Add column if missing: ALTER TABLE prds ADD COLUMN template_id TEXT

8. Implement CLI Commands

File: file:codeframe/cli/app.py

Create new command group under PRD commands:

cf prd templates list [--category CATEGORY]

• List available templates with name, description, category
• Show source (builtin/global/project)

cf prd templates show TEMPLATE_ID

• Display template details including sections and variables

cf prd templates import SOURCE [--name NAME]

• Import from file path or URL
• Validate and save to project templates directory

cf prd templates export TEMPLATE_ID [--output PATH]

• Export template to file (default: stdout)

cf prd generate [--template TEMPLATE_ID]

• Modify existing command to accept template parameter
• Default to "standard" template for backward compatibility

9. Add Template Validation

File: file:codeframe/planning/prd_templates.py

Implement validation in PrdTemplateManager.validate_template():

• Check required fields: id, name, version, sections
• Validate section structure: id, title, source, format
• Ensure all template variables reference valid discovery categories
• Verify Jinja2 syntax in format strings
• Check that required sections have valid data sources
• Return list of validation errors or empty list if valid

10. Implement Template Functions

File: file:codeframe/planning/prd_template_functions.py (new)

Create Jinja2 custom filters and functions:

• bullet_list(items: list): Convert list to markdown bullets
• numbered_list(items: list): Convert list to numbered list
• table(items: list, columns: list): Generate markdown table
• generate_persona(user: str): AI-generate user persona description
• generate_acceptance(feature: str): AI-generate acceptance criteria
• summarize(text: str, max_words: int): Summarize long text
• Register these functions with Jinja2 environment

11. Update Documentation

Files:

• file:README.md: Add section on PRD templates
• Create docs/prd-templates.md (new): Comprehensive template guide

Documentation should cover:

• Template structure and YAML format
• Available variables and their sources
• Template functions and usage examples
• Creating custom templates
• Built-in template descriptions
• CLI command reference
• Migration guide from hardcoded format

12. Add Tests

File: tests/planning/test_prd_templates.py (new)

Test coverage:

• Template loading from YAML files
• Template validation (valid and invalid cases)
• Template rendering with mock discovery data
• Built-in template completeness
• Template manager operations (list, get, import, export)
• Template function execution
• Integration with LeadAgent.generate_prd()

File: tests/cli/test_prd_commands.py

Add tests for new CLI commands:

• cf prd templates list
• cf prd templates show
• cf prd templates import
• cf prd templates export
• cf prd generate --template

13. Backward Compatibility

Ensure existing functionality continues to work:

• Default template matches current PRD output format exactly
• Existing PRDs without template_id continue to work
• cf prd generate without --template flag uses "standard" template
• Discovery process remains unchanged
• PRD storage and retrieval APIs maintain compatibility

Architecture Diagram

sequenceDiagram
    participant User
    participant CLI
    participant LeadAgent
    participant TemplateManager
    participant AnswerCapture
    participant Storage

    User->>CLI: cf prd generate --template enterprise
    CLI->>LeadAgent: generate_prd(template_id="enterprise")
    LeadAgent->>AnswerCapture: get_structured_data()
    AnswerCapture-->>LeadAgent: discovery_data
    LeadAgent->>TemplateManager: load_template("enterprise")
    TemplateManager->>Storage: Read from .codeframe/templates/prd/
    Storage-->>TemplateManager: template YAML
    TemplateManager-->>LeadAgent: PrdTemplate object
    LeadAgent->>TemplateManager: render_template(template, discovery_data)
    TemplateManager->>TemplateManager: Apply Jinja2 rendering
    TemplateManager->>TemplateManager: Execute template functions
    TemplateManager-->>LeadAgent: rendered PRD markdown
    LeadAgent->>Storage: store PRD with template_id
    Storage-->>LeadAgent: PrdRecord
    LeadAgent-->>CLI: PRD content
    CLI-->>User: Display success message

Loading

Template Structure Example

name: "Enterprise PRD Template"
version: 1
description: "Full formal PRD with compliance and traceability"

sections:
  - id: executive_summary
    title: "Executive Summary"
    required: true
    source: problem
    format: |
      ## Executive Summary
      
      ### Problem Statement
      {{ answers.problem_1 }}
      
      ### Business Justification
      {{ answers.problem_2 | default("Not specified") }}

  - id: stakeholders
    title: "Stakeholders & Users"
    required: true
    source: users
    format: |
      ## Stakeholders
      
      ### Primary Users
      {{ extracted.users | bullet_list }}
      
      ### User Personas
      {% for user in extracted.users %}
      - **{{ user }}**: {{ generate_persona(user) }}
      {% endfor %}

  - id: requirements
    title: "Functional Requirements"
    required: true
    source: features
    format: |
      ## Functional Requirements
      
      | ID | Requirement | Priority | Source |
      |----|-------------|----------|--------|
      {% for feature in extracted.features %}
      | FR-{{ loop.index }} | {{ feature }} | P1 | Discovery |
      {% endfor %}

Import In IDE

🤖 Prompt for AI Agents

## Observations

The codebase has a well-established foundation for implementing PRD templates. The current PRD generation logic resides in `file:codeframe/agents/lead_agent.py` with a hardcoded template in the `_build_prd_prompt()` method. An existing task template system in `file:codeframe/planning/task_templates.py` provides a proven pattern for template management, storage, and application. The workspace uses `.codeframe/` for project-level configuration with YAML support already in place via `file:codeframe/core/config.py`. The CLI uses Typer with a modular structure, and there's already a `templates_app` registered for task templates that can be extended.

## Approach

The implementation will follow the existing task template pattern, creating a parallel PRD template system. Templates will be stored as YAML files in both global (`~/.codeframe/templates/prd/`) and project-level (`.codeframe/templates/prd/`) directories. A new `PrdTemplateManager` class will handle template loading, validation, and rendering using Jinja2 for variable substitution and template functions. The current hardcoded PRD generation in `LeadAgent._build_prd_prompt()` will be refactored to use the template system while maintaining backward compatibility through a default "standard" template. CLI commands will be added under a new `cf prd templates` subcommand group to manage templates.

## Implementation Steps

### 1. Create PRD Template Data Structures

**File**: `file:codeframe/planning/prd_templates.py` (new)

Create dataclasses for PRD template structure:
- `PrdTemplateSection`: Represents a single section with id, title, required flag, source category, and format template
- `PrdTemplate`: Contains template metadata (id, name, version, description) and list of sections
- Define template variable schema and available functions (bullet_list, numbered_list, table, generate_persona, etc.)

### 2. Implement Template Manager

**File**: `file:codeframe/planning/prd_templates.py`

Create `PrdTemplateManager` class with methods:
- `__init__()`: Initialize with builtin templates
- `load_template(template_id: str)`: Load from global or project directories
- `list_templates()`: List available templates with metadata
- `get_template(template_id: str)`: Retrieve specific template
- `validate_template(template: PrdTemplate)`: Validate structure and required fields
- `render_template(template: PrdTemplate, discovery_data: dict)`: Render using Jinja2
- `import_template(source_path: Path)`: Import from file or URL
- `export_template(template_id: str, output_path: Path)`: Export template to file

### 3. Create Built-in Templates

**File**: `file:codeframe/planning/prd_templates.py`

Define 5 built-in templates as YAML structures:
- **standard**: Current default format (executive summary, problem statement, user personas, features, technical architecture, success metrics, timeline)
- **lean**: Minimal viable PRD (problem, users, MVP features only)
- **enterprise**: Full formal PRD with compliance sections, traceability matrix, stakeholder analysis, risk assessment
- **user-story-map**: Organized around user journeys with story mapping structure
- **technical-spec**: Focused on technical requirements, architecture diagrams, API specifications, data models

### 4. Implement Template Storage

**Directories**:
- Global: `~/.codeframe/templates/prd/`
- Project: `.codeframe/templates/prd/`

Create helper functions in `file:codeframe/planning/prd_templates.py`:
- `get_global_template_dir()`: Return Path to global template directory
- `get_project_template_dir(workspace: Workspace)`: Return Path to project template directory
- `save_template_to_file(template: PrdTemplate, path: Path)`: Serialize template to YAML
- `load_template_from_file(path: Path)`: Deserialize YAML to PrdTemplate
- Template discovery: Search both global and project directories, with project templates taking precedence

### 5. Integrate with Discovery System

**File**: `file:codeframe/discovery/answers.py`

Enhance `AnswerCapture.get_structured_data()` to return template-compatible data:
- Add `answers_by_category` mapping
- Include `metadata` dict with project_name, generated_at, session_id
- Ensure `extracted` dict contains features, users, constraints as expected by templates
- Add method `get_template_context()` that formats data specifically for template rendering

### 6. Refactor PRD Generation in LeadAgent

**File**: `file:codeframe/agents/lead_agent.py`

Modify `generate_prd()` method:
- Add optional `template_id` parameter (defaults to "standard")
- Initialize `PrdTemplateManager` instance
- Load specified template or fall back to default
- Replace `_build_prd_prompt()` call with template rendering

Update `_build_prd_prompt()` method:
- Rename to `_render_prd_from_template(template: PrdTemplate, structured_data: dict)`
- Use Jinja2 to render template sections
- Apply template functions (bullet_list, generate_persona, etc.)
- Return rendered markdown content

### 7. Add Template Field to PRD Storage

**File**: `file:codeframe/core/prd.py`

Update `PrdRecord` dataclass:
- Add `template_id: Optional[str] = None` field
- Update `store()` function to accept and save template_id in metadata
- Update `get_latest()`, `get_by_id()`, `list_all()` to include template_id

**File**: `file:codeframe/core/workspace.py`

Add database migration in `_ensure_schema_upgrades()`:
- Check if `template_id` column exists in prds table
- Add column if missing: `ALTER TABLE prds ADD COLUMN template_id TEXT`

### 8. Implement CLI Commands

**File**: `file:codeframe/cli/app.py`

Create new command group under PRD commands:

```
cf prd templates list [--category CATEGORY]
```
- List available templates with name, description, category
- Show source (builtin/global/project)

```
cf prd templates show TEMPLATE_ID
```
- Display template details including sections and variables

```
cf prd templates import SOURCE [--name NAME]
```
- Import from file path or URL
- Validate and save to project templates directory

```
cf prd templates export TEMPLATE_ID [--output PATH]
```
- Export template to file (default: stdout)

```
cf prd generate [--template TEMPLATE_ID]
```
- Modify existing command to accept template parameter
- Default to "standard" template for backward compatibility

### 9. Add Template Validation

**File**: `file:codeframe/planning/prd_templates.py`

Implement validation in `PrdTemplateManager.validate_template()`:
- Check required fields: id, name, version, sections
- Validate section structure: id, title, source, format
- Ensure all template variables reference valid discovery categories
- Verify Jinja2 syntax in format strings
- Check that required sections have valid data sources
- Return list of validation errors or empty list if valid

### 10. Implement Template Functions

**File**: `file:codeframe/planning/prd_template_functions.py` (new)

Create Jinja2 custom filters and functions:
- `bullet_list(items: list)`: Convert list to markdown bullets
- `numbered_list(items: list)`: Convert list to numbered list
- `table(items: list, columns: list)`: Generate markdown table
- `generate_persona(user: str)`: AI-generate user persona description
- `generate_acceptance(feature: str)`: AI-generate acceptance criteria
- `summarize(text: str, max_words: int)`: Summarize long text
- Register these functions with Jinja2 environment

### 11. Update Documentation

**Files**: 
- `file:README.md`: Add section on PRD templates
- Create `docs/prd-templates.md` (new): Comprehensive template guide

Documentation should cover:
- Template structure and YAML format
- Available variables and their sources
- Template functions and usage examples
- Creating custom templates
- Built-in template descriptions
- CLI command reference
- Migration guide from hardcoded format

### 12. Add Tests

**File**: `tests/planning/test_prd_templates.py` (new)

Test coverage:
- Template loading from YAML files
- Template validation (valid and invalid cases)
- Template rendering with mock discovery data
- Built-in template completeness
- Template manager operations (list, get, import, export)
- Template function execution
- Integration with LeadAgent.generate_prd()

**File**: `tests/cli/test_prd_commands.py`

Add tests for new CLI commands:
- `cf prd templates list`
- `cf prd templates show`
- `cf prd templates import`
- `cf prd templates export`
- `cf prd generate --template`

### 13. Backward Compatibility

Ensure existing functionality continues to work:
- Default template matches current PRD output format exactly
- Existing PRDs without template_id continue to work
- `cf prd generate` without `--template` flag uses "standard" template
- Discovery process remains unchanged
- PRD storage and retrieval APIs maintain compatibility

## Architecture Diagram

```mermaid
sequenceDiagram
    participant User
    participant CLI
    participant LeadAgent
    participant TemplateManager
    participant AnswerCapture
    participant Storage

    User->>CLI: cf prd generate --template enterprise
    CLI->>LeadAgent: generate_prd(template_id="enterprise")
    LeadAgent->>AnswerCapture: get_structured_data()
    AnswerCapture-->>LeadAgent: discovery_data
    LeadAgent->>TemplateManager: load_template("enterprise")
    TemplateManager->>Storage: Read from .codeframe/templates/prd/
    Storage-->>TemplateManager: template YAML
    TemplateManager-->>LeadAgent: PrdTemplate object
    LeadAgent->>TemplateManager: render_template(template, discovery_data)
    TemplateManager->>TemplateManager: Apply Jinja2 rendering
    TemplateManager->>TemplateManager: Execute template functions
    TemplateManager-->>LeadAgent: rendered PRD markdown
    LeadAgent->>Storage: store PRD with template_id
    Storage-->>LeadAgent: PrdRecord
    LeadAgent-->>CLI: PRD content
    CLI-->>User: Display success message
```

## Template Structure Example

```yaml
name: "Enterprise PRD Template"
version: 1
description: "Full formal PRD with compliance and traceability"

sections:
  - id: executive_summary
    title: "Executive Summary"
    required: true
    source: problem
    format: |
      ## Executive Summary
      
      ### Problem Statement
      {{ answers.problem_1 }}
      
      ### Business Justification
      {{ answers.problem_2 | default("Not specified") }}

  - id: stakeholders
    title: "Stakeholders & Users"
    required: true
    source: users
    format: |
      ## Stakeholders
      
      ### Primary Users
      {{ extracted.users | bullet_list }}
      
      ### User Personas
      {% for user in extracted.users %}
      - **{{ user }}**: {{ generate_persona(user) }}
      {% endfor %}

  - id: requirements
    title: "Functional Requirements"
    required: true
    source: features
    format: |
      ## Functional Requirements
      
      | ID | Requirement | Priority | Source |
      |----|-------------|----------|--------|
      {% for feature in extracted.features %}
      | FR-{{ loop.index }} | {{ feature }} | P1 | Discovery |
      {% endfor %}
```

---

Execution Information

Branch: main
Commit: 1914267

---

💡 Tips

Supported Commands (Inside Comments)

• Use @traycerai generate to iterate on the previous version of the implementation plan.

Supported Commands (Inside Description)

• Add @traycerai ignore anywhere in the ticket description to prevent this ticket from being processed.
• Add @traycerai branch:<branch-name> anywhere in the ticket description to specify the target branch for the implementation plan.

Community

• Join our Discord Community to get help, request features, and share feedback.
• Follow us on X/Twitter for updates and announcements.

[coderabbitai]

📝 CodeRabbit Plan Mode

Generate an implementation plan and prompts that you can use with your favorite coding agent.

• Create Plan

Examples

• Example 1
• Example 2

---

🔗 Related PRs

#194 - Fix PRD generation progress tracking UI [merged]
#213 - feat(planning): Add Generate Task Breakdown button to DiscoveryProgress [merged]

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!

[frankbria]

MVP Iteration Note (from #318): A simpler first iteration could use pure markdown templates with section headers (no DSL), 2-3 built-in templates (SaaS, Library, CLI tool), and project-level storage only. This covers 80%+ of use cases before adding variables/functions.