Implement AI-driven PRD generation system

[frankbria]

🎯 Overview

Implement interactive AI-driven PRD generation to replace basic codeframe prd add <file.md> functionality. This is identified as the single most critical gap that would impact 100% of users trying to use the enhanced MVP workflow.

🚨 Critical Blocker Details

Current State: Only codeframe prd add <file.md> exists for manual PRD upload
Problem: Enhanced MVP requires AI-driven discovery with:

• Interactive AI sessions asking contextual questions
• Requirement gathering and constraint identification
• Comprehensive PRD generation with technical specs and user stories
• Iterative refinement based on user feedback
• PRD versioning and change tracking

📋 Implementation Requirements

Phase 1: Discovery Session Framework

• Create `codeframe/core/prd_discovery.py` module
• Implement interactive AI questioning system
• Add contextual question generation based on project analysis
• Support for requirement clarification and scope validation

Phase 2: PRD Generation Engine

• LLM-based PRD generation from discovery responses
• Integration with existing task generation system
• Support for comprehensive PRD structure:
  • Executive summary and problem statement
  • Functional requirements with acceptance criteria
  • Technical specifications and architecture guidance
  • User stories with priority ranking
  • Success metrics and validation criteria

Phase 3: Iterative Refinement System

• Support for user feedback and iterative improvement
• PRD versioning and change tracking
• Difference tracking between PRD versions
• Rollback capability for PRD changes

Phase 4: CLI Integration

• Add `codeframe prd generate` command (primary over `prd add`)
• Integrate with existing `codeframe status` display
• Ensure backward compatibility with existing `prd add` command
• Update help system and documentation

🔗 Dependencies

• Requires `codeframe prd generate` to work with existing task generation
• Needs credential management system for AI access
• Should integrate with workspace state management
• Must maintain compatibility with current state machine

✅ Acceptance Criteria

• Users can run `codeframe prd generate` and get interactive AI session
• AI asks relevant contextual questions about project scope and requirements
• Generated PRD is comprehensive and includes all required sections
• Users can refine PRD iteratively with version tracking
• Command integrates seamlessly with existing CLI workflow
• Comprehensive test coverage for all discovery and generation scenarios
• Documentation updated with examples and usage patterns

🎯 Success Metrics

• Reduced friction for new projects starting with CodeFRAME
• Higher quality PRDs generated through AI-guided discovery
• Improved project understanding and requirement clarity
• Reduced need for manual PRD creation and editing

📚 References

• Enhanced MVP specification: `docs/GOLDEN_PATH.md`
• Gap analysis: `docs/GAP_ANALYSIS_SUMMARY.md`
• Implementation plan: `docs/CRITICAL_GAP_IMPLEMENTATION_PLAN.md`
• Current PRD system: `codeframe/core/prd.py`

This is the highest priority implementation as it enables the entire enhanced MVP workflow and removes the primary barrier to user adoption.

[traycerai]

Plan

Observations

The codebase already implements a sophisticated AI-driven PRD generation system through the discovery workflow (file:codeframe/agents/lead_agent.py and file:codeframe/cli/discovery_commands.py). The system uses Anthropic's Claude API for interactive questioning, generates comprehensive PRDs, and stores them in both database and filesystem. However, there's no dedicated codeframe prd command group for PRD management. The ticket appears based on outdated information, as the core AI-driven discovery and PRD generation already exists. What's needed is better CLI organization and enhanced PRD management capabilities.

Approach

Rather than rebuilding existing functionality, the implementation will create a new codeframe prd command group that provides a unified interface for PRD operations. This will wrap and enhance existing discovery/PRD functionality with commands for viewing, exporting, versioning, and managing PRDs. The approach maintains backward compatibility with the existing discovery workflow while providing a more intuitive PRD-centric interface. The implementation follows the established CLI patterns using Typer, integrates with the existing API client, and leverages the LeadAgent's PRD capabilities.

Implementation Steps

1. Create PRD Commands Module

Create file:codeframe/cli/prd_commands.py with a new Typer app for PRD management:

Command Structure:

• codeframe prd generate <project_id> - Start interactive AI-driven PRD generation (wraps discovery workflow)
• codeframe prd view <project_id> - Display current PRD content
• codeframe prd export <project_id> - Export PRD to markdown file
• codeframe prd add <project_id> <file.md> - Upload PRD from file (backward compatibility)
• codeframe prd versions <project_id> - List PRD version history
• codeframe prd diff <project_id> <version1> <version2> - Show differences between versions
• codeframe prd status <project_id> - Show PRD generation status

Implementation Details:

• Follow the pattern established in file:codeframe/cli/discovery_commands.py and file:codeframe/cli/project_commands.py
• Use APIClient from file:codeframe/cli/api_client.py for backend communication
• Implement rich console output using rich.console.Console and rich.panel.Panel
• Add authentication checks using require_auth() helper
• Handle errors gracefully with appropriate HTTP status code handling

2. Extend Backend API Endpoints

Add new PRD-specific endpoints in file:codeframe/ui/routers/discovery.py or create new file:codeframe/ui/routers/prd.py:

New Endpoints:

• GET /api/projects/{project_id}/prd - Retrieve PRD content (may already exist)
• POST /api/projects/{project_id}/prd/upload - Upload PRD from file
• GET /api/projects/{project_id}/prd/versions - List PRD versions
• GET /api/projects/{project_id}/prd/versions/{version_id} - Get specific version
• POST /api/projects/{project_id}/prd/versions/{version_id}/restore - Restore previous version
• GET /api/projects/{project_id}/prd/diff - Compare two versions

Integration Points:

• Leverage existing LeadAgent.generate_prd() from file:codeframe/agents/lead_agent.py
• Use Database methods for PRD storage and retrieval
• Implement WebSocket broadcasts for real-time updates using file:codeframe/ui/websocket_broadcasts.py
• Add authentication/authorization checks using get_current_user dependency

3. Enhance PRD Versioning in Database

Extend file:codeframe/persistence/database.py with PRD versioning support:

New Database Methods:

• save_prd_version(project_id, content, version_number, change_summary) - Save PRD version
• get_prd_versions(project_id) - List all versions
• get_prd_version(project_id, version_id) - Retrieve specific version
• restore_prd_version(project_id, version_id) - Restore previous version
• get_prd_diff(project_id, version1, version2) - Generate diff between versions

Schema Considerations:

• Add prd_versions table with columns: id, project_id, version_number, content, change_summary, created_at, created_by
• Update existing PRD storage to track version numbers
• Implement automatic versioning on PRD updates

4. Implement PRD Upload Functionality

Add file upload capability in file:codeframe/agents/lead_agent.py:

New LeadAgent Method:

• upload_prd(file_path: str, skip_validation: bool = False) - Parse and validate uploaded PRD
• Validate PRD structure (sections, format, completeness)
• Extract metadata (title, description, requirements)
• Store in database with version tracking
• Optionally trigger task generation from uploaded PRD

Validation Logic:

• Check for required sections (Executive Summary, Requirements, User Stories, etc.)
• Validate markdown format
• Extract and validate acceptance criteria
• Warn about missing or incomplete sections

5. Add PRD Diff and Comparison

Implement diff functionality for PRD versions:

Diff Implementation:

• Use Python's difflib for text comparison
• Generate side-by-side or unified diff format
• Highlight structural changes (sections added/removed)
• Track requirement changes with semantic understanding
• Format output for CLI display using Rich tables

6. Register PRD Command Group

Update file:codeframe/cli/__init__.py:

Registration:

from codeframe.cli.prd_commands import prd_app  # noqa: E402
app.add_typer(prd_app, name="prd", help="PRD management (generate, view, export, versions)")

Place in Phase 1 imports section alongside discovery commands for logical grouping.

7. Update Discovery Integration

Modify file:codeframe/cli/discovery_commands.py to reference new PRD commands:

Cross-references:

• Update help text to mention codeframe prd view after PRD generation
• Add suggestions to use codeframe prd export for saving PRD
• Maintain backward compatibility with existing discovery generate-prd command

8. Implement Iterative Refinement

Add PRD refinement capability in file:codeframe/agents/lead_agent.py:

New Methods:

• refine_prd(feedback: str) - Accept user feedback and regenerate sections
• update_prd_section(section_name: str, new_content: str) - Update specific section
• Track refinement history as versions
• Broadcast refinement progress via WebSocket

CLI Command:

• codeframe prd refine <project_id> - Interactive refinement session
• Prompt for feedback on specific sections
• Show before/after comparison
• Confirm changes before saving

9. Add PRD Templates and Validation

Create PRD template system:

Template Structure:

• Define standard PRD sections in file:codeframe/core/prd_template.py
• Include section descriptions and examples
• Provide validation rules for each section
• Support custom templates per project type

Validation Rules:

• Minimum content length per section
• Required vs optional sections
• Format validation (markdown structure)
• Completeness scoring

10. Implement Comprehensive Testing

Create test suite following existing patterns:

Test Files:

• file:tests/cli/test_prd_commands.py - CLI command tests
• file:tests/api/test_prd_endpoints.py - API endpoint tests
• file:tests/agents/test_lead_agent_prd.py - PRD generation tests
• file:tests/persistence/test_prd_versioning.py - Database versioning tests

Test Coverage:

• PRD generation workflow
• File upload and validation
• Version management (create, list, restore)
• Diff generation
• Error handling and edge cases
• Authentication and authorization

11. Update Documentation

Update relevant documentation files:

Documentation Updates:

• Add PRD command examples to file:README.md
• Update file:docs/GOLDEN_PATH.md to reference new codeframe prd generate command
• Create file:docs/PRD_WORKFLOW.md with detailed PRD management guide
• Update CLI help text and command descriptions
• Add PRD versioning examples and best practices

12. Backward Compatibility

Ensure existing workflows continue to function:

Compatibility Measures:

• Keep codeframe discovery generate-prd command functional
• Maintain existing API endpoints
• Support both discovery-driven and direct PRD generation
• Preserve existing PRD storage format
• Add migration path for existing PRDs to versioned system

Architecture Diagram

sequenceDiagram
    participant User
    participant CLI as codeframe prd
    participant API as FastAPI Backend
    participant Agent as LeadAgent
    participant DB as Database
    participant FS as Filesystem

    User->>CLI: codeframe prd generate <project_id>
    CLI->>API: POST /api/projects/{id}/discovery/start
    API->>Agent: start_discovery()
    Agent->>User: Interactive questions
    User->>CLI: Answer questions
    CLI->>API: POST /api/projects/{id}/discovery/answer
    API->>Agent: process_discovery_answer()
    Agent->>Agent: generate_prd()
    Agent->>DB: save_prd_version()
    Agent->>FS: Write .codeframe/memory/prd.md
    Agent->>API: PRD complete
    API-->>User: WebSocket: prd_generation_completed
    
    User->>CLI: codeframe prd view <project_id>
    CLI->>API: GET /api/projects/{id}/prd
    API->>DB: get_prd()
    DB-->>CLI: PRD content
    CLI-->>User: Display PRD
    
    User->>CLI: codeframe prd refine <project_id>
    CLI->>API: POST /api/projects/{id}/prd/refine
    API->>Agent: refine_prd(feedback)
    Agent->>DB: save_prd_version()
    DB-->>User: Updated PRD

Loading

Key Integration Points

Component	File	Purpose
CLI Commands	file:codeframe/cli/prd_commands.py	User-facing PRD management interface
API Router	file:codeframe/ui/routers/prd.py	HTTP endpoints for PRD operations
Lead Agent	file:codeframe/agents/lead_agent.py	AI-driven PRD generation and refinement
Database	file:codeframe/persistence/database.py	PRD storage and versioning
Models	file:codeframe/core/models.py	PRD data structures and validation
WebSocket	file:codeframe/ui/websocket_broadcasts.py	Real-time progress updates

Success Criteria Mapping

Requirement	Implementation
Interactive AI session	Leverage existing LeadAgent.start_discovery()
Contextual questions	Already implemented in discovery workflow
Comprehensive PRD	Use existing generate_prd() with enhanced templates
Iterative refinement	New refine_prd() method with version tracking
Version tracking	New database schema and API endpoints
CLI integration	New codeframe prd command group
Backward compatibility	Maintain prd add and discovery commands

Import In IDE

🤖 Prompt for AI Agents

## Observations

The codebase already implements a sophisticated AI-driven PRD generation system through the discovery workflow (`file:codeframe/agents/lead_agent.py` and `file:codeframe/cli/discovery_commands.py`). The system uses Anthropic's Claude API for interactive questioning, generates comprehensive PRDs, and stores them in both database and filesystem. However, there's no dedicated `codeframe prd` command group for PRD management. The ticket appears based on outdated information, as the core AI-driven discovery and PRD generation already exists. What's needed is better CLI organization and enhanced PRD management capabilities.

## Approach

Rather than rebuilding existing functionality, the implementation will create a new `codeframe prd` command group that provides a unified interface for PRD operations. This will wrap and enhance existing discovery/PRD functionality with commands for viewing, exporting, versioning, and managing PRDs. The approach maintains backward compatibility with the existing discovery workflow while providing a more intuitive PRD-centric interface. The implementation follows the established CLI patterns using Typer, integrates with the existing API client, and leverages the LeadAgent's PRD capabilities.

## Implementation Steps

### 1. Create PRD Commands Module

Create `file:codeframe/cli/prd_commands.py` with a new Typer app for PRD management:

**Command Structure:**
- `codeframe prd generate <project_id>` - Start interactive AI-driven PRD generation (wraps discovery workflow)
- `codeframe prd view <project_id>` - Display current PRD content
- `codeframe prd export <project_id>` - Export PRD to markdown file
- `codeframe prd add <project_id> <file.md>` - Upload PRD from file (backward compatibility)
- `codeframe prd versions <project_id>` - List PRD version history
- `codeframe prd diff <project_id> <version1> <version2>` - Show differences between versions
- `codeframe prd status <project_id>` - Show PRD generation status

**Implementation Details:**
- Follow the pattern established in `file:codeframe/cli/discovery_commands.py` and `file:codeframe/cli/project_commands.py`
- Use `APIClient` from `file:codeframe/cli/api_client.py` for backend communication
- Implement rich console output using `rich.console.Console` and `rich.panel.Panel`
- Add authentication checks using `require_auth()` helper
- Handle errors gracefully with appropriate HTTP status code handling

### 2. Extend Backend API Endpoints

Add new PRD-specific endpoints in `file:codeframe/ui/routers/discovery.py` or create new `file:codeframe/ui/routers/prd.py`:

**New Endpoints:**
- `GET /api/projects/{project_id}/prd` - Retrieve PRD content (may already exist)
- `POST /api/projects/{project_id}/prd/upload` - Upload PRD from file
- `GET /api/projects/{project_id}/prd/versions` - List PRD versions
- `GET /api/projects/{project_id}/prd/versions/{version_id}` - Get specific version
- `POST /api/projects/{project_id}/prd/versions/{version_id}/restore` - Restore previous version
- `GET /api/projects/{project_id}/prd/diff` - Compare two versions

**Integration Points:**
- Leverage existing `LeadAgent.generate_prd()` from `file:codeframe/agents/lead_agent.py`
- Use `Database` methods for PRD storage and retrieval
- Implement WebSocket broadcasts for real-time updates using `file:codeframe/ui/websocket_broadcasts.py`
- Add authentication/authorization checks using `get_current_user` dependency

### 3. Enhance PRD Versioning in Database

Extend `file:codeframe/persistence/database.py` with PRD versioning support:

**New Database Methods:**
- `save_prd_version(project_id, content, version_number, change_summary)` - Save PRD version
- `get_prd_versions(project_id)` - List all versions
- `get_prd_version(project_id, version_id)` - Retrieve specific version
- `restore_prd_version(project_id, version_id)` - Restore previous version
- `get_prd_diff(project_id, version1, version2)` - Generate diff between versions

**Schema Considerations:**
- Add `prd_versions` table with columns: `id`, `project_id`, `version_number`, `content`, `change_summary`, `created_at`, `created_by`
- Update existing PRD storage to track version numbers
- Implement automatic versioning on PRD updates

### 4. Implement PRD Upload Functionality

Add file upload capability in `file:codeframe/agents/lead_agent.py`:

**New LeadAgent Method:**
- `upload_prd(file_path: str, skip_validation: bool = False)` - Parse and validate uploaded PRD
- Validate PRD structure (sections, format, completeness)
- Extract metadata (title, description, requirements)
- Store in database with version tracking
- Optionally trigger task generation from uploaded PRD

**Validation Logic:**
- Check for required sections (Executive Summary, Requirements, User Stories, etc.)
- Validate markdown format
- Extract and validate acceptance criteria
- Warn about missing or incomplete sections

### 5. Add PRD Diff and Comparison

Implement diff functionality for PRD versions:

**Diff Implementation:**
- Use Python's `difflib` for text comparison
- Generate side-by-side or unified diff format
- Highlight structural changes (sections added/removed)
- Track requirement changes with semantic understanding
- Format output for CLI display using Rich tables

### 6. Register PRD Command Group

Update `file:codeframe/cli/__init__.py`:

**Registration:**
```python
from codeframe.cli.prd_commands import prd_app  # noqa: E402
app.add_typer(prd_app, name="prd", help="PRD management (generate, view, export, versions)")
```

Place in Phase 1 imports section alongside discovery commands for logical grouping.

### 7. Update Discovery Integration

Modify `file:codeframe/cli/discovery_commands.py` to reference new PRD commands:

**Cross-references:**
- Update help text to mention `codeframe prd view` after PRD generation
- Add suggestions to use `codeframe prd export` for saving PRD
- Maintain backward compatibility with existing `discovery generate-prd` command

### 8. Implement Iterative Refinement

Add PRD refinement capability in `file:codeframe/agents/lead_agent.py`:

**New Methods:**
- `refine_prd(feedback: str)` - Accept user feedback and regenerate sections
- `update_prd_section(section_name: str, new_content: str)` - Update specific section
- Track refinement history as versions
- Broadcast refinement progress via WebSocket

**CLI Command:**
- `codeframe prd refine <project_id>` - Interactive refinement session
- Prompt for feedback on specific sections
- Show before/after comparison
- Confirm changes before saving

### 9. Add PRD Templates and Validation

Create PRD template system:

**Template Structure:**
- Define standard PRD sections in `file:codeframe/core/prd_template.py`
- Include section descriptions and examples
- Provide validation rules for each section
- Support custom templates per project type

**Validation Rules:**
- Minimum content length per section
- Required vs optional sections
- Format validation (markdown structure)
- Completeness scoring

### 10. Implement Comprehensive Testing

Create test suite following existing patterns:

**Test Files:**
- `file:tests/cli/test_prd_commands.py` - CLI command tests
- `file:tests/api/test_prd_endpoints.py` - API endpoint tests
- `file:tests/agents/test_lead_agent_prd.py` - PRD generation tests
- `file:tests/persistence/test_prd_versioning.py` - Database versioning tests

**Test Coverage:**
- PRD generation workflow
- File upload and validation
- Version management (create, list, restore)
- Diff generation
- Error handling and edge cases
- Authentication and authorization

### 11. Update Documentation

Update relevant documentation files:

**Documentation Updates:**
- Add PRD command examples to `file:README.md`
- Update `file:docs/GOLDEN_PATH.md` to reference new `codeframe prd generate` command
- Create `file:docs/PRD_WORKFLOW.md` with detailed PRD management guide
- Update CLI help text and command descriptions
- Add PRD versioning examples and best practices

### 12. Backward Compatibility

Ensure existing workflows continue to function:

**Compatibility Measures:**
- Keep `codeframe discovery generate-prd` command functional
- Maintain existing API endpoints
- Support both discovery-driven and direct PRD generation
- Preserve existing PRD storage format
- Add migration path for existing PRDs to versioned system

## Architecture Diagram

```mermaid
sequenceDiagram
    participant User
    participant CLI as codeframe prd
    participant API as FastAPI Backend
    participant Agent as LeadAgent
    participant DB as Database
    participant FS as Filesystem

    User->>CLI: codeframe prd generate <project_id>
    CLI->>API: POST /api/projects/{id}/discovery/start
    API->>Agent: start_discovery()
    Agent->>User: Interactive questions
    User->>CLI: Answer questions
    CLI->>API: POST /api/projects/{id}/discovery/answer
    API->>Agent: process_discovery_answer()
    Agent->>Agent: generate_prd()
    Agent->>DB: save_prd_version()
    Agent->>FS: Write .codeframe/memory/prd.md
    Agent->>API: PRD complete
    API-->>User: WebSocket: prd_generation_completed
    
    User->>CLI: codeframe prd view <project_id>
    CLI->>API: GET /api/projects/{id}/prd
    API->>DB: get_prd()
    DB-->>CLI: PRD content
    CLI-->>User: Display PRD
    
    User->>CLI: codeframe prd refine <project_id>
    CLI->>API: POST /api/projects/{id}/prd/refine
    API->>Agent: refine_prd(feedback)
    Agent->>DB: save_prd_version()
    DB-->>User: Updated PRD
```

## Key Integration Points

| Component | File | Purpose |
|-----------|------|---------|
| CLI Commands | `file:codeframe/cli/prd_commands.py` | User-facing PRD management interface |
| API Router | `file:codeframe/ui/routers/prd.py` | HTTP endpoints for PRD operations |
| Lead Agent | `file:codeframe/agents/lead_agent.py` | AI-driven PRD generation and refinement |
| Database | `file:codeframe/persistence/database.py` | PRD storage and versioning |
| Models | `file:codeframe/core/models.py` | PRD data structures and validation |
| WebSocket | `file:codeframe/ui/websocket_broadcasts.py` | Real-time progress updates |

## Success Criteria Mapping

| Requirement | Implementation |
|-------------|----------------|
| Interactive AI session | Leverage existing `LeadAgent.start_discovery()` |
| Contextual questions | Already implemented in discovery workflow |
| Comprehensive PRD | Use existing `generate_prd()` with enhanced templates |
| Iterative refinement | New `refine_prd()` method with version tracking |
| Version tracking | New database schema and API endpoints |
| CLI integration | New `codeframe prd` command group |
| Backward compatibility | Maintain `prd add` and discovery commands |

---

Execution Information

Branch: main
Commit: 81fdeee

---

💡 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

#31 - Create SDK migration implementation plan [merged]
#194 - Fix PRD generation progress tracking UI [merged]
#196 - fix(discovery): Synchronize PRD buttons and fix state persistence on tab revisit [merged]
#205 - feat(planning): Add planning phase automation and task approval [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]

Closed with PR #293