# CodeFRAME v2 — Golden Path Contract (CLI-first)

This document is the contract for CodeFRAME v2 development.

**Rule 0 (the only rule that matters):**
> If a change does not directly support the Golden Path flow below, do not implement it.

This applies to both humans and agentic coding assistants.

---

## Goals

### What "done" looks like (Enhanced MVP definition)
CodeFRAME can run a complete end-to-end AI-driven development workflow **from the CLI** on a target repo:

1) **Initialize workspace with project discovery**
   - Analyze codebase and detect tech stack
   - Configure environment and tooling automatically
   - Create durable state storage

2) **AI-driven PRD generation and refinement**
   - Interactive AI session gathers project requirements
   - AI asks follow-up questions about scope, users, constraints
   - Generates comprehensive PRD + technical specs + user stories
   - Iterative refinement based on user feedback

3) **Intelligent task generation with dependency analysis**
   - Decompose PRD into actionable tasks with dependencies
   - Prioritize tasks and group by functionality
   - Generate implementation strategies per task

4) **Batch task execution with orchestration**
   - Execute multiple tasks in sequence or parallel
   - Handle inter-task dependencies automatically
   - Main agent coordinates entire batch workflow
   - Real-time progress monitoring and event streaming

5) **Human-in-the-loop blocker resolution**
   - Interactive blocker handling with contextual AI suggestions
   - Resume execution after blocker resolution
   - Learning from blocker patterns

6) **Integrated Git workflow and PR management**
   - Automatic branch creation per task/batch
   - AI-generated commit messages and PR descriptions
   - Automated verification gate execution
   - PR creation, review, and merging workflows

7) **Comprehensive checkpointing and state management**
   - Snapshots of workspace state with git refs
   - Resume interrupted workflows from checkpoints
   - Multi-environment state isolation

**No UI is required.**
**A FastAPI server is not required for the Golden Path to work.**
**All Git operations are integrated into the CLI workflow.**

---

## Non-Goals (explicitly forbidden until Golden Path works)

Do not build or refactor:
- Web UI / dashboard features
- Settings pages, preferences, themes
- Multi-provider/model switching UI or complex provider management
- Advanced metrics dashboards or timeseries endpoints
- Auth / sessions for remote users
- Electron desktop app
- Plugin marketplace / extensibility frameworks
- “Perfect” project structure, monorepo tooling, or build system redesign
- Large migrations or renames that aren’t required by Golden Path

These may be revisited **only after** Golden Path is working and stable.

---

## Golden Path CLI Flow (the only flow that matters)

### 0) Preconditions
- A target repo exists (any small test repo is fine).
- CodeFRAME runs locally and can store durable state (SQLite or filesystem).
- The CLI can be run from anywhere.

### 1) Initialize a workspace
Command:
- `codeframe init <path-to-repo>`

Required behavior:
- Registers the repo as a workspace.
- Creates/updates durable state storage.
- Prints a short workspace summary (repo path, workspace id, state location).

Artifacts:
- Local state created (DB/file), e.g. `.codeframe/` and/or `codeframe.db`.

### 2) AI-driven PRD generation and refinement
Commands:
- `codeframe prd generate` (primary - interactive AI session)
- `codeframe prd add <file.md>` (secondary - existing file support)
- `codeframe prd refine` (iterative improvement)

Required behavior for `prd generate`:
- AI conducts interactive discovery session asking:
  - Project scope, objectives, and success criteria
  - Target users, use cases, and user stories
  - Technical constraints, preferences, and requirements
  - Timeline, priorities, and MVP boundaries
- Generates comprehensive PRD with:
  - 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
- Provides iterative refinement based on user feedback
- Stores PRD in durable state with versioning
- Supports multiple PRD versions with change tracking

### 3) Intelligent task generation with dependency analysis
Commands:
- `codeframe tasks generate` (enhanced with dependencies)
- `codeframe tasks analyze` (dependency graph analysis)

Required behavior:
- Decomposes PRD into granular, actionable tasks
- Automatically detects and assigns task dependencies
- Estimates effort and complexity for each task
- Groups related tasks into logical workstreams
- Prioritizes tasks based on dependencies and value delivery
- Supports task templates for common patterns (setup, implementation, testing, deployment)
- Generates implementation strategy per task (files to modify, approaches to consider)
- Creates task dependency graph with critical path identification

### 4) Batch task execution with orchestration
Commands:
- `codeframe work batch run` (primary - main execution pathway)
- `codeframe work start <task-id>` (secondary - single task fallback)
- `codeframe work batch status <batch-id>` (monitoring)
- `codeframe work batch follow <batch-id>` (real-time streaming)

Required behavior for batch execution:
- Executes multiple tasks with intelligent scheduling:
  - Serial execution for dependent tasks
  - Parallel execution for independent tasks
  - Auto-strategy using dependency graph analysis
- Main orchestrator agent coordinates entire batch:
  - Resource allocation and task scheduling
  - Inter-task communication and data sharing
  - Failure handling and retry logic
  - Progress tracking and milestone reporting
- Real-time event streaming with:
  - Task start/completion events
  - Progress indicators and ETAs
  - Blocker detection and notification
  - Dependency resolution updates
- Supports execution strategies:
  - `--strategy serial`: Linear execution
  - `--strategy parallel`: Max parallelization
  - `--strategy auto`: AI-optimized based on dependencies

### 5) Enhanced human-in-loop blocker resolution
Commands:
- `codeframe blockers list` (enhanced with context)
- `codeframe blocker answer <blocker-id> "<text>"` (with AI suggestions)
- `codeframe blocker resolve <blocker-id>` (automated resolution options)

Required behavior:
- AI provides contextual blocker resolution suggestions:
  - Similar past blockers and their solutions
  - Multiple solution approaches with trade-offs
  - Impact analysis of resolution choices
- Interactive blocker handling with:
  - Rich context display (related code, PRD sections, task dependencies)
  - Suggested responses ranked by confidence
  - Impact on task timeline and dependencies
- Learning system that:
  - Records blocker patterns and resolutions
  - Improves future blocker handling suggestions
  - Reduces human intervention over time

### 6) Integrated Git workflow and PR management
Commands:
- `codeframe work start <task-id> --create-branch` (branch management)
- `codeframe pr create` (PR creation with AI descriptions)
- `codeframe pr list` (PR status monitoring)
- `codeframe pr merge <pr-id>` (PR merging with verification)

Required behavior:
- **Branch Management**:
  - Automatic feature branch creation per task/batch
  - Branch naming conventions with task/batch IDs
  - Branch cleanup and organization utilities
  - Conflict detection and resolution assistance
- **PR Creation**:
  - AI generates comprehensive PR descriptions:
    - Summary of changes and business impact
    - Technical implementation details
    - Testing performed and results
    - Breaking changes and migration notes
  - Automated PR labeling and categorization
  - Reviewer assignment based on code expertise
- **PR Workflow**:
  - Automated gate execution before merge (tests, lint, security scans)
  - Integration with CI/CD pipelines
  - Merge strategies (squash, merge, rebase) based on team preferences
  - Post-merge cleanup and notification

### 7) Enhanced verification and quality gates
Commands:
- `codeframe review` (comprehensive code review)
- `codeframe gates run` (automated quality checks)
- `codeframe quality report` (quality metrics and trends)

Required behavior:
- **Comprehensive Gate Suite**:
  - Unit tests with coverage reporting
  - Integration and end-to-end tests
  - Static code analysis (lint, security, complexity)
  - Performance regression tests
  - Documentation and API specification validation
- **AI-Assisted Code Review**:
  - Automated code quality assessment
  - Best practices compliance checking
  - Potential bug detection and suggestions
  - Code style and maintainability analysis
- **Quality Tracking**:
  - Trend analysis of code quality metrics
  - Technical debt accumulation tracking
  - Gate failure pattern identification

### 8) Integrated artifact and commit management
Commands:
- `codeframe commit create -m "<message>"` (AI-generated commits)
- `codeframe patch export` (safe patch generation)
- `codeframe artifacts list` (artifact tracking)

Required behavior:
- **Smart Commits**:
  - AI generates meaningful commit messages:
    - Conventional commit format compliance
    - Contextual change descriptions
    - References to tasks/PRDs/issues
    - Breaking change highlights
  - Atomic commit boundaries and logical grouping
- **Artifact Management**:
  - Automatic patch generation for safety
  - Commit linking to tasks and batches
  - Rollback points and recovery procedures
  - Integration with external artifact repositories

### 9) Comprehensive checkpointing and state management
Commands:
- `codeframe checkpoint create "<name>"` (enhanced snapshots)
- `codeframe checkpoint restore <checkpoint-id>` (workflow resume)
- `codeframe summary` (comprehensive reporting)

Required behavior:
- **Rich Checkpoints**:
  - Complete workspace state capture:
    - Task statuses and progress
    - Git refs and working directory state
    - PRD versions and requirements
    - Configuration and environment settings
  - Incremental checkpoint optimization
  - Cross-environment checkpoint portability
- **Workflow Resume**:
  - Seamless resumption from any checkpoint
  - Context restoration for active agents
  - Branch and working directory restoration
  - Event log continuity and replay
- **Comprehensive Reporting**:
  - Executive summaries with progress metrics
  - Detailed task completion reports
  - Quality gate performance tracking
  - Resource utilization and timing analysis
  - Risk assessment and mitigation recommendations

---

## State Machine (authoritative)

Statuses:
- `BACKLOG` - Task identified but not ready for execution
- `READY` - Task prepared and ready to start
- `IN_PROGRESS` - Task actively being worked on
- `BLOCKED` - Task waiting for human input or external dependency
- `DONE` - Task completed locally, ready for review/integration
- `IN_REVIEW` - Task changes in PR review process
- `MERGED` - Task changes integrated into main branch
- `FAILED` - Task execution failed (can be retried)

Allowed transitions (comprehensive):
- BACKLOG -> READY (task preparation complete)
- READY -> IN_PROGRESS (work started)
- IN_PROGRESS -> BLOCKED (awaiting input/dependency)
- BLOCKED -> IN_PROGRESS (blocker resolved)
- BLOCKED -> READY (returned to queue)
- IN_PROGRESS -> DONE (local completion)
- IN_PROGRESS -> FAILED (execution failure)
- DONE -> IN_REVIEW (PR created/under review)
- IN_REVIEW -> DONE (PR rejected, needs work)
- IN_REVIEW -> MERGED (PR approved and merged)
- DONE -> READY (reopened for additional work)
- FAILED -> READY (retry after failure)
- MERGED -> BACKLOG (reopened for enhancement)

The CLI is the authority for transitions.
UIs (web/electron) are views over this state machine, not the source of truth.

**PR Workflow Integration:**
- Tasks automatically transition to IN_REVIEW when `codeframe pr create` is run
- PR status changes trigger corresponding task state updates
- Merge actions transition tasks to MERGED status
- Failed or rejected PRs return tasks to DONE for additional work

---

## Implementation Principles

### Core-first (no FastAPI in the core)
- Domain logic must live in a reusable core module/package.
- Core must not import FastAPI, websockets, or HTTP request objects.
- FastAPI server (if used) must be a thin adapter over core.

### CLI-first (server optional)
- Golden Path commands must work without any running backend server.
- If a server exists, it may be started separately (`codeframe serve`) and must wrap core.

### Salvage safely
- Legacy code can be read and copied from.
- Core must not take dependencies on legacy UI-driven modules.
- Prefer copying useful functions into core and simplifying interfaces.

### Keep it runnable
- Every commit should keep `codeframe --help` working.
- The Golden Path commands should remain executable even if stubs at first.

---

## Acceptance Checklist (Enhanced MVP - must pass)

**Status: 🔄 Enhanced MVP Partially Complete**

## 📊 Current Implementation Status

**Overall Assessment**: Enhanced MVP is **~60% complete** with solid foundation but critical gaps remaining.

### ✅ Fully Implemented Phases:
- **Phase 1**: Basic PRD functionality (`prd add`) - **Enhanced PRD generation missing**
- **Phase 2**: Core task generation with LLM support - **Advanced dependency analysis incomplete**
- **Phase 3**: Complete batch execution framework - **Orchestrator integration complete**
- **Phase 4**: Basic blocker management system - **AI-powered suggestions missing**
- **Phase 6**: Basic verification gates (`codeframe review`) - **AI-assisted review missing**
- **Phase 7**: Comprehensive checkpointing system - **Incremental/batch features missing**

### ⚠️ Critical Missing Components:
- **AI-driven PRD generation**: No `codeframe prd generate` command
- **Credential management**: No `codeframe auth` system - **CRITICAL BLOCKER**
- **Git/PR workflow**: GitHub integration exists but no CLI commands
- **Environment validation**: No pre-flight validation system
- **Advanced recovery**: Limited rollback beyond full checkpoints
- **Enhanced monitoring**: Basic event streaming, no rich debugging

### 🎯 Key Finding:
**The single most critical issue is missing credential management** - users cannot reliably use the enhanced workflow without it.

**Foundation is solid** - Core CLI functionality, batch execution, and basic Git integration work reliably.

**Next priority**: Implement credential management system as outlined in gap analysis documents.

### Phase 1: AI-Driven Project Discovery & PRD Generation
- [x] `codeframe init` with auto tech stack detection and environment setup
  - ✅ **Implementation**: Auto tech stack detection with `--detect` flag
  - ✅ **Implementation**: Interactive tech stack configuration with `--tech-stack-interactive` 
  - ✅ **Note**: Basic init works, enhanced features not yet integrated
- [ ] `codeframe prd generate` conducts interactive AI discovery session
  - ⚠️ **Status**: Command not implemented - only `codeframe prd add <file.md>` exists
  - **Note**: Discovery exists in legacy codebase but not integrated into CLI
- [ ] AI asks contextual follow-up questions about requirements and constraints
- [ ] Generates comprehensive PRD with technical specs and user stories
- [ ] Supports iterative PRD refinement based on user feedback
- [ ] PRD versioning and change tracking

### Phase 2: Intelligent Task Generation & Dependency Management
- [x] `codeframe tasks generate` creates dependency-aware task graphs
  - ✅ **Implementation**: Uses LLM for task generation with dependency analysis
  - ✅ **Implementation**: Supports both LLM and simple extraction modes
  - ⚠️ **Status**: Limited dependency graph functionality
  - **Note**: Basic task generation works, advanced dependency analysis incomplete
- [ ] Automatic task prioritization and workstream grouping
- [ ] Effort estimation and complexity analysis
- [ ] Critical path identification and scheduling
- [ ] Task template system for common implementation patterns

### Phase 3: Batch Execution & Orchestration
- [x] `codeframe work batch run` as primary execution pathway
  - ✅ **Implementation**: Comprehensive batch execution with multiple strategies
  - ✅ **Implementation**: Serial, parallel, and auto-strategy execution modes
  - ✅ **Implementation**: Event streaming and progress monitoring
  - ✅ **Implementation**: Failure handling and retry logic
  - ✅ **Implementation**: Real-time status and batch monitoring commands
  - **Note**: Main batch functionality works, orchestrator integration complete
- [ ] Serial, parallel, and auto-strategy execution modes
- [ ] Real-time progress monitoring with event streaming
- [ ] Inter-task dependency management and coordination
- [ ] Main orchestrator agent manages entire batch workflow
- [ ] Failure handling and automatic retry logic

### Phase 4: Enhanced Human-in-the-Loop Blocker Resolution
- [x] Contextual blocker display with rich background information
  - ✅ **Implementation**: Comprehensive blocker management system
  - ✅ **Implementation**: Rich context display with codebase references
  - ⚠️ **Status**: AI-powered suggestions not yet implemented
  - **Note**: Basic blocker listing and answering works, AI suggestions missing
- [ ] AI-powered blocker resolution suggestions
- [ ] Learning system for blocker pattern recognition
- [ ] Similar past blocker solutions and recommendations
- [ ] Impact analysis for different resolution approaches

### Phase 5: Integrated Git Workflow & PR Management
- [ ] Automatic branch creation per task/batch with naming conventions
- [ ] AI-generated comprehensive PR descriptions with business impact
- [ ] Automated PR labeling and reviewer assignment
- [ ] Integration with CI/CD pipelines and gate execution
- [ ] Multiple merge strategies (squash, merge, rebase) support
- [ ] Post-merge cleanup and notification automation
  - ⚠️ **Status**: Basic Git integration exists, PR creation incomplete
  - **Note**: GitHub integration module exists (`codeframe/git/github_integration.py`)
  - **Note**: Auth commands exist but credential management missing
  - **Note**: No CLI commands for PR creation/management yet implemented

### Phase 6: Comprehensive Quality Gates & Verification
- [x] Expanded gate suite: unit tests, integration tests, security scans
  - ✅ **Implementation**: Basic `codeframe review` command exists
  - ✅ **Implementation**: Supports multiple gate types (pytest, ruff, mypy, npm)
  - ⚠️ **Status**: Limited gate functionality - stub implementation
  - **Note**: Only basic verification works, AI-assisted review not implemented
- [ ] AI-assisted code review with best practices checking
- [ ] Quality metrics tracking and trend analysis
- [ ] Technical debt accumulation monitoring
- [ ] Automated regression detection and prevention

### Phase 7: Advanced Checkpointing & State Management
- [x] Rich checkpoint snapshots with complete workspace state
  - ✅ **Implementation**: Comprehensive checkpoint management system
  - ✅ **Implementation**: Checkpoint create, list, show, and restore commands
  - ✅ **Implementation**: Git reference integration for state tracking
  - ⚠️ **Status**: Basic checkpointing works, advanced features missing
  - **Note**: No incremental checkpointing during batch execution
- [ ] Cross-environment checkpoint portability
- [ ] Seamless workflow resumption from any checkpoint
- [ ] Incremental checkpoint optimization
- [ ] Executive reporting with progress and risk metrics

### Cross-Cutting Requirements
- [x] All functionality works without FastAPI server running
  - ✅ **Implementation**: Core functionality works independently of server
  - ✅ **Verification**: CLI commands work without FastAPI dependency
  - ⚠️ **Status**: Server wrapper incomplete but not required for CLI workflow
- [ ] No UI required at any point in workflow
  - [x] Event logging and streaming for observability
  - ✅ **Implementation**: Comprehensive event system with rich logging
  - ✅ **Implementation**: Real-time event streaming during batch execution
  - ⚠️ **Status**: Advanced monitoring features missing
- [ ] Comprehensive error handling and recovery procedures
  - ⚠️ **Status**: Basic error handling exists, advanced recovery missing
  - **Note**: No rollback capability beyond full checkpoints
- [ ] Performance optimization for large repositories
  - [ ] Security best practices and credential management
  - [ ] Documentation and help commands for all new features
  - ⚠️ **Status**: No credential management system implemented
  - ⚠️ **Critical Gap**: Authentication failures would block entire workflow
  - **Note**: See gap analysis documents for detailed credential management plan

**Definition of Done:**
- All acceptance criteria must be satisfied
- End-to-end workflow tested on real project repositories
- Performance benchmarks meet minimum standards
- Security audit passes all compliance checks
- Documentation is complete and accurate
- User feedback collected from beta testing validates approach

Next phase: Production Readiness & Advanced Features (see roadmap planning).
