# Roadmap Lifecycle Guide

The `roadmap.yaml` file is the AI agent's living memory of your project's progress. It answers the question: *"Where are we, and what needs doing next?"*

> **v3.0.0 note (2026-05-22):** The 2026-05-22 surface-cut audit
> removed the `changesets` feature entirely. References below to
> `open_changesets` / `list_open_changesets()` /
> `add_open_changeset()` / `remove_open_changeset()` apply to v1.x
> through v2.x only; v3.0.0 has no changesets module. Roadmap mutation
> in v3.0.0 is also flock-guarded — all 6 mutation tools
> (`add_phase`, `update_phase_status`, `defer_phase`, `complete_phase`,
> `bulk_import_phases`, `update_next_action`) wrap their read-modify-
> write in `mcp_server.storage.atomic.file_lock` to survive
> concurrent IDE sessions. See [`docs/architecture.md`](architecture.md)
> § "Concurrent-write safety".
>
> **v1.6+ historical note:** As of v1.6, project data lives centrally
> at `~/.codevira/projects/<project-key>/` instead of inside the
> project repo at `<project>/.codevira/`. The code graph still lives
> at the centralized location in v3.0.0 (spec/impl drift documented
> in [ROADMAP.md § Known limitations](../ROADMAP.md)).

---

## Table of Contents

1. [What is the roadmap?](#what-is-the-roadmap)
2. [How init auto-generates it](#how-init-auto-generates-it)
3. [Roadmap YAML schema](#roadmap-yaml-schema)
4. [How the roadmap evolves during development](#how-the-roadmap-evolves-during-development)
5. [Manual editing guide](#manual-editing-guide)
6. [Troubleshooting](#troubleshooting)

---

## What is the roadmap?

The roadmap is a YAML file at `~/.codevira/projects/<project-key>/roadmap.yaml` that tracks:

- **What phase of development you're in** (e.g., "Phase 2 — Auth System")
- **What the agent should do next** (`next_action` field — updated at session end)
- **Active multi-file changes** (`open_changesets` — prevents agents from losing context across sessions)
- **Past phases** (so the agent understands project history)

The AI agent reads the roadmap at the start of every session via `get_roadmap()`. It's the first thing it calls.

---

## How init auto-generates it

When you run `codevira init`, the initializer:

1. **Reads your git history** — extracts tags (e.g., `v0.1`, `v1.0-auth`) as completed phase milestones
2. **Detects your framework** — looks for `pyproject.toml`, `package.json`, `Cargo.toml`, `go.mod` etc. to infer the project type
3. **Infers phase state** — if very few source files exist, creates a "Getting Started" phase; if the project is active, creates a "Feature Development" phase
4. **Creates a stub** at `~/.codevira/projects/<project-key>/roadmap.yaml` — only if the file doesn't already exist (never overwrites)

### Auto-generated stub example

```yaml
project: my-project
version: "1.0"
current_phase:
  number: 1
  name: Getting Started
  status: in_progress
  goal: Auto-generated stub — update this to reflect your project goals.
  next_action: >-
    Review and update this roadmap with your actual project phases.
    Use add_phase() to add upcoming work, or edit this file directly.
  open_changesets: []
  description: >-
    This phase was auto-generated by codevira init.
    Replace with a meaningful description of your current work.
upcoming_phases: []
completed_phases: []
deferred_phases: []
```

**What to do after init:**
- Open `~/.codevira/projects/<project-key>/roadmap.yaml` in your editor
- Replace "Getting Started" with your actual current phase name
- Update `goal` with what you're actually building
- Add `upcoming_phases` for future work

---

## Roadmap YAML schema

```yaml
project: <string>           # Project name (from directory name on init)
version: "1.0"              # Schema version

current_phase:
  number: <int>             # Phase number (1-based)
  name: <string>            # Short phase title (e.g. "Auth System")
  status: <string>          # in_progress | blocked | pending
  goal: <string>            # What this phase achieves
  next_action: <string>     # What the agent should do next (updated by agent at session end)
  open_changesets: [<id>]   # Active multi-file change IDs in progress
  description: <string>     # Longer description (optional)

upcoming_phases:            # Planned future phases (ordered)
  - number: <int>
    name: <string>
    goal: <string>
    status: pending

completed_phases:           # Finished phases (historical record)
  - number: <int>
    name: <string>
    goal: <string>
    status: done
    completed_date: <YYYY-MM-DD>

deferred_phases:            # Deprioritized phases (not abandoned, just postponed)
  - number: <int>
    name: <string>
    goal: <string>
    status: deferred
    reason: <string>
```

---

## How the roadmap evolves during development

The agent updates the roadmap automatically through MCP tool calls. You don't need to manually update it during normal development.

### Tool → roadmap change mapping

| MCP tool call | What the agent calls it for | What changes in roadmap.yaml |
|---|---|---|
| `get_roadmap()` | Session start — orient to current state | Read-only |
| `update_phase_status(phase, "in_progress")` | Starting work on a phase | `current_phase.status = in_progress` |
| `update_phase_status(phase, "blocked")` | Blocked on external dependency | `current_phase.status = blocked` |
| `update_next_action("...")` | Session end — record what to do next | `current_phase.next_action = ...` |
| `add_phase(title, goal)` | Planning a new upcoming feature | New entry appended to `upcoming_phases` |
| `complete_phase(number)` | Phase fully done | Phase moved to `completed_phases`, `current_phase.number` incremented |
| `defer_phase(number)` | Deprioritizing future work | Phase moved to `deferred_phases` |
| `add_open_changeset("fix-id")` | Starting multi-file change | `current_phase.open_changesets` += "fix-id" |
| `remove_open_changeset("fix-id")` | Changeset done | "fix-id" removed from `open_changesets` |

### Example: a typical session

```
Session start:
  agent calls get_roadmap()
  → sees: Phase 2 "Auth System", next_action: "Implement JWT refresh token endpoint"

During session:
  agent calls update_phase_status(2, "in_progress")
  agent calls start_changeset("jwt-refresh", "Add /auth/refresh endpoint", [...])
  agent calls add_open_changeset("jwt-refresh")
  ... (does the work) ...
  agent calls complete_changeset("jwt-refresh", decisions=[...])
  agent calls remove_open_changeset("jwt-refresh")

Session end:
  agent calls update_next_action("Write integration tests for /auth/refresh")
  → roadmap.yaml now has next_action: "Write integration tests for /auth/refresh"

Next session:
  agent calls get_roadmap()
  → immediately knows to write integration tests
```

---

## Manual editing guide

You can always edit `~/.codevira/projects/<project-key>/roadmap.yaml` directly. The agent will pick up changes on the next `get_roadmap()` call.

### When to edit manually

**Set your actual project phases:**
```yaml
# Replace the auto-generated stub with real phases
current_phase:
  number: 1
  name: "Core API — User Registration"
  status: in_progress
  goal: "Build /users/register and /users/login endpoints with JWT auth"
  next_action: "Start with the database schema (users table)"
  open_changesets: []

upcoming_phases:
  - number: 2
    name: "Core API — Post Management"
    goal: "CRUD endpoints for posts: create, list, update, delete"
    status: pending

  - number: 3
    name: "Frontend — Auth Flow"
    goal: "Login/register UI with token storage and refresh logic"
    status: pending
```

**Roll back a phase:**
```yaml
# Move phase 2 back to current if something went wrong
current_phase:
  number: 2     # Change this back from 3
  ...
```

**Add a hotfix phase:**
```yaml
# Insert emergency fix between phases
upcoming_phases:
  - number: 2
    name: "HOTFIX — Production crash fix"
    goal: "Fix NullPointerException in /payments/checkout"
    status: pending
  - number: 3      # renumber existing phases
    name: "..."
    ...
```

**Record a deferred decision:**
```yaml
deferred_phases:
  - number: 5
    name: "Performance Optimization"
    goal: "Profile and optimize query-heavy endpoints"
    status: deferred
    reason: "Deprioritized for MVP — revisit after launch"
```

### Editing rules

1. **YAML is whitespace-sensitive** — use 2-space indentation consistently
2. **Don't change** `version: "1.0"` — agents check this
3. **Keep `current_phase.number` in sync** — if you manually move phases, update the number
4. **Multi-line strings** — use `>-` for long values to avoid quoting issues:
   ```yaml
   next_action: >-
     Implement the retry logic in payment_service.py,
     then add circuit breaker tests.
   ```

---

## Troubleshooting

### "Roadmap not found" error

Run `codevira init` from your project root. The roadmap is created at `~/.codevira/projects/<project-key>/roadmap.yaml`.

### Roadmap is out of sync with actual progress

Edit `~/.codevira/projects/<project-key>/roadmap.yaml` directly to set the correct `current_phase.number` and `status`. The agent will read the updated file on the next tool call.

### Agent keeps doing work from a completed phase

The agent missed calling `complete_phase()`. Manually update the roadmap:
```yaml
completed_phases:
  - number: 1
    name: "..."
    status: done
    completed_date: "2025-01-15"

current_phase:
  number: 2
  ...
```

### Roadmap corrupted (YAML parse error)

Run the following to validate (replace `<project-key>` with your actual project key — find it via `codevira status` or by listing `~/.codevira/projects/`):
```bash
python -c "import yaml; yaml.safe_load(open('$HOME/.codevira/projects/<project-key>/roadmap.yaml'))"
```

If the file is corrupted beyond repair, delete it and restart:
```bash
rm ~/.codevira/projects/<project-key>/roadmap.yaml
codevira index --full  # Regenerates the roadmap stub on next get_roadmap() call
```

### Agent's `next_action` doesn't match what I want

Directly edit the `next_action` field in `~/.codevira/projects/<project-key>/roadmap.yaml`, or ask the agent:
> "Update next_action to say: [your intent]"

The agent will call `update_next_action()` and save it.

---

## FAQ

**Q: Is the roadmap committed to git?**

No. As of v1.6, the roadmap lives at `~/.codevira/projects/<key>/roadmap.yaml` — outside your project repo entirely. Each developer's roadmap is local to their machine.

If you want to share roadmap state across a team, you can manually copy the file into your repo (e.g. `docs/roadmap.yaml`) and commit it. But Codevira itself is local-first by design — team-shared memory is on the v2.0 roadmap.

**Q: Can multiple agents update the roadmap concurrently?**

The roadmap is a flat YAML file — concurrent writes could corrupt it. Codevira is designed for single-agent workflows. If using multiple parallel agents, have only one "orchestrator" agent manage roadmap state.

**Q: How detailed should phases be?**

Phases work best at the "1–2 day" granularity. Too coarse ("Build the whole auth system") and the agent loses focus. Too fine ("Add one field to the users table") and you'll be managing hundreds of phases. Aim for phases that represent a meaningful, testable milestone.
