[P3] Make sprint number configurable in planning automation

[frankbria]

Summary

The planning automation currently hardcodes sprint_number=1 when calling LeadAgent.generate_issues(). This should be configurable or derived from project state.

Location

codeframe/ui/routers/discovery.py:193

issues = await asyncio.to_thread(agent.generate_issues, sprint_number=1)

Suggested Solutions

1. Derive from project state: Query the current/next sprint number from the database
2. Pass as parameter: Allow sprint number to be specified in the PRD generation request
3. Auto-increment: Track sprint count per project and auto-increment

Acceptance Criteria

• Sprint number is no longer hardcoded to 1
• Multi-sprint projects correctly generate issues for the appropriate sprint
• Tests cover sprint number selection logic

Context

This was identified during code review of PR #205 (planning phase automation).

[traycerai]

Plan

Observations

The codebase currently has a generate_issues(sprint_number) method in file:codeframe/agents/lead_agent.py that requires an explicit sprint number parameter. Issue numbers are formatted as {sprint}.{issue} (e.g., "1.1", "2.3"). The database schema in file:codeframe/persistence/repositories/project_repository.py does not track sprint information - there's no current_sprint or sprint_count field in the projects table. The issue references a hardcoded sprint_number=1 call in planning automation (PR #205), which needs to be made configurable to support multi-sprint projects.

Approach

The recommended approach is Solution 1: Derive from project state with auto-increment logic. This provides the best balance of automation and flexibility. Add a current_sprint field to the projects table to track the active sprint number, initialize it to 1 when a project is created, and auto-increment it when starting a new sprint. This approach requires minimal API changes, provides clear sprint progression, and maintains backward compatibility with existing code that explicitly passes sprint numbers.

Implementation Steps

1. Database Schema Changes

Add sprint tracking to projects table:

• Modify file:codeframe/persistence/schema_manager.py to add a current_sprint column to the projects table (INTEGER, DEFAULT 1, NOT NULL)
• Create a database migration to add this column to existing projects (set default value to 1 for backward compatibility)
• Update file:codeframe/core/models.py to add current_sprint: int = 1 field to the Project dataclass
• Update file:codeframe/persistence/repositories/project_repository.py:
  • Add current_sprint to the ALLOWED_PROJECT_FIELDS whitelist
  • Modify create_project() to initialize current_sprint=1
  • Update _row_to_project() to parse the current_sprint field from database rows
  • Update get_project() to include current_sprint in returned dictionary

2. Sprint Management Methods

Add sprint management logic to LeadAgent:

• In file:codeframe/agents/lead_agent.py, add new methods:
  • get_current_sprint() -> int: Query project's current_sprint from database
  • increment_sprint() -> int: Increment current_sprint in database and return new value
  • set_sprint(sprint_number: int) -> None: Manually set sprint number (for corrections)
• Modify generate_issues(sprint_number: Optional[int] = None):
  • If sprint_number is None, call get_current_sprint() to derive it
  • If sprint_number is provided, use it (maintains backward compatibility)
  • Log which sprint number is being used for transparency

3. Update Planning Automation

Make sprint number configurable in planning workflows:

• In file:codeframe/ui/routers/discovery.py (or wherever the hardcoded call exists):
  • Replace agent.generate_issues(sprint_number=1) with agent.generate_issues() (uses current sprint)
  • Or add optional sprint_number parameter to the PRD generation request body
• Update file:codeframe/core/models.py to add optional sprint_number field to any planning-related request models
• In background task generate_prd_background(), pass sprint number from request or use None to auto-derive

4. API Endpoints for Sprint Management

Add REST endpoints for sprint control:

• Create new router file:codeframe/ui/routers/sprints.py with endpoints:
  • GET /api/projects/{project_id}/sprint/current - Get current sprint number
  • POST /api/projects/{project_id}/sprint/next - Increment to next sprint
  • PUT /api/projects/{project_id}/sprint - Manually set sprint number (admin operation)
• Add authentication and authorization checks using get_current_user and user_has_project_access
• Include audit logging for sprint changes using file:codeframe/lib/audit_logger.py

5. CLI Commands

Add sprint management to CLI:

• In file:codeframe/cli/discovery_commands.py or create new file:codeframe/cli/sprint_commands.py:
  • codeframe sprint current <project_id> - Show current sprint
  • codeframe sprint next <project_id> - Move to next sprint
  • codeframe sprint set <project_id> <number> - Set specific sprint number
• Use file:codeframe/cli/api_client.py to call the new API endpoints

6. Update Issue Generation Flow

Modify decompose_prd to use current sprint:

• In file:codeframe/agents/lead_agent.py, update decompose_prd(sprint_number: Optional[int] = None):
  • If sprint_number is None, derive from get_current_sprint()
  • Pass the resolved sprint number to generate_issues()
• Update any callers of decompose_prd() to pass None for automatic sprint detection

7. Testing

Add comprehensive test coverage:

• In file:tests/planning/test_issue_generator.py:
  • Test that issues are generated with correct sprint numbers (1.1, 2.1, etc.)
  • Test sprint auto-increment logic
• Create new test file file:tests/agents/test_lead_agent_sprint_management.py:
  • Test get_current_sprint() returns correct value
  • Test increment_sprint() updates database and returns new value
  • Test generate_issues() with None uses current sprint
  • Test generate_issues(sprint_number=2) overrides current sprint
• Add integration tests in file:tests/ui/test_sprint_endpoints.py for API endpoints
• Test database migration adds current_sprint column correctly

8. Documentation

Update documentation and examples:

• Update file:PRD.md or relevant planning documentation to explain sprint management
• Add examples showing how to start a new sprint
• Document the auto-increment behavior and manual override options
• Update API documentation to include new sprint endpoints

Architecture Diagram

sequenceDiagram
    participant UI as UI/CLI
    participant Router as Sprint Router
    participant LeadAgent as Lead Agent
    participant DB as Database
    participant IssueGen as Issue Generator

    Note over UI,IssueGen: Scenario 1: Auto-derive sprint (recommended)
    UI->>Router: POST /projects/1/discovery/generate-prd
    Router->>LeadAgent: generate_issues(sprint_number=None)
    LeadAgent->>DB: SELECT current_sprint FROM projects WHERE id=1
    DB-->>LeadAgent: current_sprint=2
    LeadAgent->>IssueGen: generate_issues_from_prd(prd, sprint_number=2)
    IssueGen-->>LeadAgent: [Issue(2.1), Issue(2.2), ...]
    LeadAgent->>DB: INSERT issues
    LeadAgent-->>Router: issues created
    Router-->>UI: Success

    Note over UI,IssueGen: Scenario 2: Manual sprint increment
    UI->>Router: POST /projects/1/sprint/next
    Router->>LeadAgent: increment_sprint()
    LeadAgent->>DB: UPDATE projects SET current_sprint=3 WHERE id=1
    DB-->>LeadAgent: success
    LeadAgent-->>Router: new_sprint=3
    Router-->>UI: Sprint incremented to 3

    Note over UI,IssueGen: Scenario 3: Override sprint (backward compat)
    UI->>Router: POST /projects/1/issues/generate {sprint_number: 5}
    Router->>LeadAgent: generate_issues(sprint_number=5)
    LeadAgent->>IssueGen: generate_issues_from_prd(prd, sprint_number=5)
    IssueGen-->>LeadAgent: [Issue(5.1), Issue(5.2), ...]
    LeadAgent-->>Router: issues created
    Router-->>UI: Success

Loading

Database Schema Addition

Column	Type	Constraints	Description
current_sprint	INTEGER	NOT NULL, DEFAULT 1	Current active sprint number for the project

Migration Strategy

1. Phase 1 (Backward Compatible): Add current_sprint column with default value 1, make sprint_number parameter optional in generate_issues()
2. Phase 2 (Transition): Update all callers to use auto-derived sprint numbers
3. Phase 3 (Cleanup): Remove hardcoded sprint_number=1 calls from codebase

Acceptance Criteria Validation

• ✅ Sprint number is no longer hardcoded to 1 (derived from projects.current_sprint)
• ✅ Multi-sprint projects correctly generate issues for appropriate sprint (auto-increment or manual control)
• ✅ Tests cover sprint number selection logic (unit tests for get_current_sprint(), increment_sprint(), and generate_issues())

Import In IDE

🤖 Prompt for AI Agents

## Observations

The codebase currently has a `generate_issues(sprint_number)` method in `file:codeframe/agents/lead_agent.py` that requires an explicit sprint number parameter. Issue numbers are formatted as `{sprint}.{issue}` (e.g., "1.1", "2.3"). The database schema in `file:codeframe/persistence/repositories/project_repository.py` does not track sprint information - there's no `current_sprint` or `sprint_count` field in the projects table. The issue references a hardcoded `sprint_number=1` call in planning automation (PR #205), which needs to be made configurable to support multi-sprint projects.

## Approach

The recommended approach is **Solution 1: Derive from project state** with auto-increment logic. This provides the best balance of automation and flexibility. Add a `current_sprint` field to the projects table to track the active sprint number, initialize it to 1 when a project is created, and auto-increment it when starting a new sprint. This approach requires minimal API changes, provides clear sprint progression, and maintains backward compatibility with existing code that explicitly passes sprint numbers.

## Implementation Steps

### 1. Database Schema Changes

**Add sprint tracking to projects table:**

- Modify `file:codeframe/persistence/schema_manager.py` to add a `current_sprint` column to the `projects` table (INTEGER, DEFAULT 1, NOT NULL)
- Create a database migration to add this column to existing projects (set default value to 1 for backward compatibility)
- Update `file:codeframe/core/models.py` to add `current_sprint: int = 1` field to the `Project` dataclass
- Update `file:codeframe/persistence/repositories/project_repository.py`:
  - Add `current_sprint` to the `ALLOWED_PROJECT_FIELDS` whitelist
  - Modify `create_project()` to initialize `current_sprint=1`
  - Update `_row_to_project()` to parse the `current_sprint` field from database rows
  - Update `get_project()` to include `current_sprint` in returned dictionary

### 2. Sprint Management Methods

**Add sprint management logic to LeadAgent:**

- In `file:codeframe/agents/lead_agent.py`, add new methods:
  - `get_current_sprint() -> int`: Query project's `current_sprint` from database
  - `increment_sprint() -> int`: Increment `current_sprint` in database and return new value
  - `set_sprint(sprint_number: int) -> None`: Manually set sprint number (for corrections)
- Modify `generate_issues(sprint_number: Optional[int] = None)`:
  - If `sprint_number` is None, call `get_current_sprint()` to derive it
  - If `sprint_number` is provided, use it (maintains backward compatibility)
  - Log which sprint number is being used for transparency

### 3. Update Planning Automation

**Make sprint number configurable in planning workflows:**

- In `file:codeframe/ui/routers/discovery.py` (or wherever the hardcoded call exists):
  - Replace `agent.generate_issues(sprint_number=1)` with `agent.generate_issues()` (uses current sprint)
  - Or add optional `sprint_number` parameter to the PRD generation request body
- Update `file:codeframe/core/models.py` to add optional `sprint_number` field to any planning-related request models
- In background task `generate_prd_background()`, pass sprint number from request or use None to auto-derive

### 4. API Endpoints for Sprint Management

**Add REST endpoints for sprint control:**

- Create new router `file:codeframe/ui/routers/sprints.py` with endpoints:
  - `GET /api/projects/{project_id}/sprint/current` - Get current sprint number
  - `POST /api/projects/{project_id}/sprint/next` - Increment to next sprint
  - `PUT /api/projects/{project_id}/sprint` - Manually set sprint number (admin operation)
- Add authentication and authorization checks using `get_current_user` and `user_has_project_access`
- Include audit logging for sprint changes using `file:codeframe/lib/audit_logger.py`

### 5. CLI Commands

**Add sprint management to CLI:**

- In `file:codeframe/cli/discovery_commands.py` or create new `file:codeframe/cli/sprint_commands.py`:
  - `codeframe sprint current <project_id>` - Show current sprint
  - `codeframe sprint next <project_id>` - Move to next sprint
  - `codeframe sprint set <project_id> <number>` - Set specific sprint number
- Use `file:codeframe/cli/api_client.py` to call the new API endpoints

### 6. Update Issue Generation Flow

**Modify decompose_prd to use current sprint:**

- In `file:codeframe/agents/lead_agent.py`, update `decompose_prd(sprint_number: Optional[int] = None)`:
  - If `sprint_number` is None, derive from `get_current_sprint()`
  - Pass the resolved sprint number to `generate_issues()`
- Update any callers of `decompose_prd()` to pass None for automatic sprint detection

### 7. Testing

**Add comprehensive test coverage:**

- In `file:tests/planning/test_issue_generator.py`:
  - Test that issues are generated with correct sprint numbers (1.1, 2.1, etc.)
  - Test sprint auto-increment logic
- Create new test file `file:tests/agents/test_lead_agent_sprint_management.py`:
  - Test `get_current_sprint()` returns correct value
  - Test `increment_sprint()` updates database and returns new value
  - Test `generate_issues()` with None uses current sprint
  - Test `generate_issues(sprint_number=2)` overrides current sprint
- Add integration tests in `file:tests/ui/test_sprint_endpoints.py` for API endpoints
- Test database migration adds `current_sprint` column correctly

### 8. Documentation

**Update documentation and examples:**

- Update `file:PRD.md` or relevant planning documentation to explain sprint management
- Add examples showing how to start a new sprint
- Document the auto-increment behavior and manual override options
- Update API documentation to include new sprint endpoints

## Architecture Diagram

```mermaid
sequenceDiagram
    participant UI as UI/CLI
    participant Router as Sprint Router
    participant LeadAgent as Lead Agent
    participant DB as Database
    participant IssueGen as Issue Generator

    Note over UI,IssueGen: Scenario 1: Auto-derive sprint (recommended)
    UI->>Router: POST /projects/1/discovery/generate-prd
    Router->>LeadAgent: generate_issues(sprint_number=None)
    LeadAgent->>DB: SELECT current_sprint FROM projects WHERE id=1
    DB-->>LeadAgent: current_sprint=2
    LeadAgent->>IssueGen: generate_issues_from_prd(prd, sprint_number=2)
    IssueGen-->>LeadAgent: [Issue(2.1), Issue(2.2), ...]
    LeadAgent->>DB: INSERT issues
    LeadAgent-->>Router: issues created
    Router-->>UI: Success

    Note over UI,IssueGen: Scenario 2: Manual sprint increment
    UI->>Router: POST /projects/1/sprint/next
    Router->>LeadAgent: increment_sprint()
    LeadAgent->>DB: UPDATE projects SET current_sprint=3 WHERE id=1
    DB-->>LeadAgent: success
    LeadAgent-->>Router: new_sprint=3
    Router-->>UI: Sprint incremented to 3

    Note over UI,IssueGen: Scenario 3: Override sprint (backward compat)
    UI->>Router: POST /projects/1/issues/generate {sprint_number: 5}
    Router->>LeadAgent: generate_issues(sprint_number=5)
    LeadAgent->>IssueGen: generate_issues_from_prd(prd, sprint_number=5)
    IssueGen-->>LeadAgent: [Issue(5.1), Issue(5.2), ...]
    LeadAgent-->>Router: issues created
    Router-->>UI: Success
```

## Database Schema Addition

| Column | Type | Constraints | Description |
|--------|------|-------------|-------------|
| `current_sprint` | INTEGER | NOT NULL, DEFAULT 1 | Current active sprint number for the project |

## Migration Strategy

1. **Phase 1 (Backward Compatible)**: Add `current_sprint` column with default value 1, make `sprint_number` parameter optional in `generate_issues()`
2. **Phase 2 (Transition)**: Update all callers to use auto-derived sprint numbers
3. **Phase 3 (Cleanup)**: Remove hardcoded `sprint_number=1` calls from codebase

## Acceptance Criteria Validation

- ✅ Sprint number is no longer hardcoded to 1 (derived from `projects.current_sprint`)
- ✅ Multi-sprint projects correctly generate issues for appropriate sprint (auto-increment or manual control)
- ✅ Tests cover sprint number selection logic (unit tests for `get_current_sprint()`, `increment_sprint()`, and `generate_issues()`)

---

Execution Information

Branch: main
Commit: c863ec5

---

💡 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

#205 - feat(planning): Add planning phase automation and task approval [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]

Closing as part of v2 roadmap cleanup. This v1-specific issue is retained with the v1-legacy label as reference material for Phase 3 (Web UI rebuild). See the v2 strategic roadmap for current priorities.