# Product Requirement Documents — Trigger Rubric and Policy
Lightweight product scope log. Captures **what** to build, **who** it's for, and **when it's done** — before implementation starts.
PRDs complement ADRs: a PRD defines product scope and acceptance criteria, an ADR captures significant technical decisions made during that build.
## Location
All PRDs live in `docs/prd/` as numbered markdown files: `NNNN-short-slug.md`.
## Numbering
Sequential four-digit prefix: `0001`, `0002`, etc. The template lives at `0000-template.md`.
## Trigger Rubric
Write a PRD when a change does **any** of the following:
| New user-facing feature or surface | Skills management page, prompt editor, session rename |
| New domain or subsystem with product behavior | Projects domain, Tasks domain, Agent orchestration |
| Significant behavior change to existing feature | Changing session streaming model, adding multi-model support |
| Cross-domain feature spanning API + Web | Tool config system (schemas + API + settings + assistant UI) |
| Feature with non-obvious scope boundaries | "What does v1 of Projects actually include?" |
### Skip PRD when
- Bugfix restoring existing behavior (no new scope).
- Refactor or extraction (no user-facing change).
- Polish, styling, or copy changes.
- Dependency updates.
- Infrastructure-only changes (those get ADRs if significant, not PRDs).
**Rule of thumb:** If you'd start building and realize mid-way "wait, what exactly am I building?" — write a PRD first.
## Lifecycle
| `Draft` | Requirements being defined, not yet committed to |
| `Active` | Committed scope, implementation underway or planned |
| `Completed` | All acceptance criteria met, feature shipped |
| `Deferred` | Intentionally postponed with reason |
| `Cancelled` | Will not be built, with reason |
| `Superseded by PRD-XXXX` | Scope replaced by a new PRD; old PRD preserved as-is |
PRDs start as `Draft` during scope definition. Move to `Active` when implementation begins.
## Revision Policy
| Scope materially changes mid-build | New PRD; mark old one `Superseded by PRD-XXXX` |
| Scope refined/narrowed (same intent) | Update existing PRD in place, note in Revision History |
| Feature shipped | Mark `Completed` with date |
| Feature abandoned | Mark `Cancelled` with reason |
| Feature postponed | Mark `Deferred` with reason and revisit trigger |
## Cross-Linking with ADRs
PRDs and ADRs reference each other:
- PRD links related ADRs in its **Technical Surface** section.
- ADR links related PRDs in its **Related** metadata or **Context** section.
```md
## Technical Surface
- **Related ADRs:** ADR-0003 (plugin registry architecture)
```
## Linking in Changelog
Reference PRD IDs in changelog entries for feature work:
```md
- **Skills Management System** (PRD-0002): Discovering, creating, and managing AI assistant skills...
```
## Index
Maintain in `docs/prd/README.md`:
| 0000 | Template | Active | 2026-05-13 | — |
| 0001 | magi-code CLI Coding Agent MVP | Completed | 2026-05-13 | Provider auth/transport amendment active 2026-05-13 |
| 0002 | Immediate Assistant Token Streaming | Completed | 2026-05-14 | User-visible assistant text streams as provider deltas arrive |
| 0003 | Visible Tool Call Output | Completed | 2026-05-15 | Legible per-tool-call blocks with tool-specific metadata and output |
| 0004 | Opt-in Mission Control TUI | Completed | 2026-05-15 | Phase 4 MVP implemented and reviewed PASS; live bash stdout/stderr streaming remains immediate follow-up |
| 0005 | Live TUI Streaming for Assistant and Tool Events | Completed | 2026-05-15 | Implementation/review PASS; live assistant/tool updates delivered, manual real-TTY validation caveat preserved |
| 0006 | Prompt Editor Navigation and Scroll Control | Completed | 2026-05-15 | Implementation/review PASS; prompt cursor navigation, manual prompt scroll, cursor auto-reveal delivered; manual live TTY checklist not exercised in this agent run |
| 0007 | Mission Control TUI Slash-Command Autocomplete | Completed | 2026-05-16 | Implemented and verified custom ratatui/crossterm popup autocomplete sourced from CommandRegistry::list(); TUI execution limitation documented |
| 0008 | Mission Control TUI /new Command Execution | Completed | 2026-05-16 | Implemented and verified first real TUI slash-command execution: /new creates a session and clears transcript/activity UI without provider submission |
| 0009 | Mission Control TUI Matrix Theme | Completed | 2026-05-16 | Implemented and execution-review PASS; display-only built-in Matrix-green TUI theming with manual real-TTY visual validation caveat preserved |
| 0010 | Settings JSON Parity for Environment Configuration | Completed | 2026-05-16 | Implemented and verified settings.json parity for non-secret runtime configuration; credentials/auth and MC_HOME remain excluded |
| 0011 | Assistant Markdown and Code Rendering in Mission Control TUI | Completed | 2026-05-17 | Implemented and execution-review PASS; reusable Markdown/code rendering with Selected Activity Detail diff heuristic and future diff roles delivered; manual real-TTY visual smoke not exercised in this harness |
| 0012 | Alt-Up/Down Transcript Scrolling While Prompt Focused | Completed | 2026-05-18 | Implementation/review PASS; prompt-focused Alt-Up/Alt-Down scroll transcript without prompt focus regression; manual real-TTY smoke not exercised |
| 0013 | Slash-Command Parity Clean Slate | Completed | 2026-05-18 | Implementation/review PASS; only /new and /quit remain supported in both interactive surfaces; removed commands now use unknown-command diagnostics |
| 0014 | Mission Control TUI Mouse Selection Copy and Cursor Placement | Completed | 2026-05-18 | Implementation/review PASS; prompt/transcript mouse selection auto-copy, OSC 52 clipboard adapter, success/failure toasts, highlight clearing, and prompt click cursor placement delivered; manual real-TTY validation caveat preserved |
| 0015 | OpenAI Codex Dynamic Model Discovery and /model Selection | Completed | 2026-05-18 | Implementation/review PASS; dynamic discovery/cache and cross-surface `/model` selection delivered; live credential/network smoke not exercised |
| 0016 | /login Command and OpenAI Codex ChatGPT OAuth | Completed | 2026-05-18 | Implementation/review PASS; `/login` provider list, TUI modal, OpenAI Codex PKCE loopback/manual OAuth, provider-keyed persistence, refresh-before-use, and docs delivered; live OAuth smoke not exercised |
| 0017 | Logout Provider Auth Command | Completed | 2026-05-19 | Implementation/review PASS; `/logout` provider-selection and confirmed local auth removal delivered with no secret leakage |
| 0018 | Runtime Prompt Template Files | Completed | 2026-05-19 | Implementation/review PASS; runtime markdown prompt fragments, user override precedence, template variables, docs, and tests delivered |
| 0019 | /system-prompt Command | Completed | 2026-05-19 | Implementation/review PASS; TUI-only read-only current system prompt inspection modal delivered with command discovery/docs and tests |
| 0020 | Remove Fixed Provider Tool-Continuation Cap | Completed | 2026-05-19 | Implementation/review PASS; removed local 32-iteration continuation cutoff with 40-cycle regression coverage; clippy caveat unrelated existing warning in `src/tools/mod.rs` |
| 0021 | Custom Provider Login and Multi-Provider Model Selection | Completed | 2026-05-19 | Implementation/review PASS; custom provider login, env-var auth, multi-provider `/model`, stale-cache guard, duplicate confirmation, docs/tests delivered |
| 0022 | Custom Provider TUI Setup UX Refinement | Completed | 2026-05-19 | Implementation/review PASS; multi-step TUI setup, label-derived provider ID, readable modal formatting, optional blank/no-auth API-key env var, no Authorization fallback, docs/tests delivered |
| 0023 | Built-in Skill Tool | Completed | 2026-05-19 | Implementation/review PASS; built-in on-demand skill/reference loader delivered with safety tests |
| 0024 | /skills Command Enable/Disable | Completed | 2026-05-20 | Implementation/review PASS; `/skills` TUI modal, disabled-skill settings persistence, assistant/tool/subagent filtering, classic-shell diagnostic, and docs delivered |
| 0025 | /sessions Session Switching Modal | Completed | 2026-05-20 | Implementation/review PASS; `/sessions` TUI modal, newest-first persisted session selection, active marker, keyboard/mouse controls, stale-selection revalidation, active-session switching, classic-shell diagnostic, and docs delivered |
| 0026 | Discoverable Subagent Identity Profiles | Completed | 2026-05-20 | Implementation/review PASS; config-backed subagent identity profiles, optional `identity`, prompt composition, metadata-only parent exposure, sanitized diagnostics, docs/tests delivered |
| 0027 | Primary Agents | Completed | 2026-05-20 | Implementation/review PASS; `$MC_HOME/primary-agents` profiles, TUI Agent display and Shift-Tab cycling, main-assistant-only prompt append, sanitized diagnostics, docs/tests delivered |
| 0028 | Persist Selected Primary Agent | Completed | 2026-05-20 | Implementation/review PASS; `selected_primary_agent` settings persistence, valid restore, None fallback, sanitized diagnostics, docs/tests delivered |
| 0029 | Normalize Tool Absolute-Path Settings | Completed | 2026-05-20 | Implementation/review PASS; normalized `tools.<tool>.absolute_paths` for read/edit/write/ffgrep/bash/parallel_subagents, default true with JSON false opt-out; linked ADR-0020 |
| 0030 | Pending Write/Edit Tool Visibility | Completed | 2026-05-21 | Implementation/review PASS; pending/running transcript and activity-tree visibility for mutating write/edit calls delivered with provider/session/tool safety unchanged; manual real-TTY Mission Control smoke not exercised |
| 0031 | Alt-C Running Prompt Cancellation | Completed | 2026-05-21 | Implementation/review PASS; Mission Control Alt-C active prompt cancellation, running prompt border text, dim green non-bold cancel hint, provider cancellation propagation, and docs delivered; manual real-TTY smoke not exercised |
| 0032 | Configurable Tool-Call Bash Hooks | Completed | 2026-05-21 | Implementation/review PASS; typed settings, dedicated hook runtime, redacted/full payload modes, local-only diagnostics, bounded execution, and ignore/warn/block/fail policies delivered; manual isolated `MC_HOME` smoke not exercised |
| 0033 | AI-Generated Friendly Session Titles | Completed | 2026-05-21 | Implementation/review PASS; explicit title provider/model, no fallback, append-only sanitized `session_title` metadata, TUI stale-session guard, README/config examples/tests delivered; linked ADR-0022 remains aligned |
| 0034 | Mission Control Version Display and Update Notification | Superseded by ADR-0053 | 2026-05-22 | Historical update-notification scope retired by crates.io-first distribution policy |
| 0035 | Authenticated CLI Self-Update | Superseded by ADR-0053 | 2026-05-22 | Self-update command retired; Cargo reinstall is distribution update path |
| 0036 | Edit Tool Diffs in Activity Detail | Completed | 2026-05-22 | Implementation/review PASS; readable actual `edit` diffs in Mission Control Selected Activity Detail delivered with provider/session/plain-output boundaries preserved; manual real-TTY smoke not exercised |
| 0037 | Mission Control TUI Layout Shortcuts | Completed | 2026-05-22 | Primary Ctrl-Shift-Right activity-focused and Ctrl-Shift-Left transcript-focused Mission Control body layouts delivered with Alt aliases retained; automated verification passed; manual real-TTY shortcut smoke not exercised |
| 0038 | @filename File Tag Autocomplete | Completed | 2026-05-22 | Implementation/review PASS; cwd-scoped fuzzy `@filename` autocomplete reuses Mission Control popup, inserts `@relative/path` tags anywhere in prompt, docs/tests delivered; manual real-TTY smoke not exercised |
| 0039 | $skillname Skill Tag Autocomplete | Completed | 2026-05-22 | Implementation/review PASS; enabled-skill fuzzy `$skillname` autocomplete reuses Mission Control popup, inserts literal prompt tags anywhere in prompt, docs/tests delivered; manual real-TTY smoke not exercised |
| 0040 | Model Thinking Level Control | Completed | 2026-05-23 | Implementation/review PASS; non-secret thinking-level settings, OpenAI Codex reasoning-effort serialization, Mission Control Thinking display and Alt-T cycling, docs/tests delivered; manual real-TTY smoke not exercised |
| 0041 | Full Structured Conversation History Replay | Completed | 2026-05-23 | Implementation/review PASS; full structured history replay, hard over-window failure, ordered provider items, cache-stable input, docs/tests delivered |
| 0042 | EXA-Backed Search Tools | Completed | 2026-05-26 | Implementation/review PASS; provider-visible `web_search` and `code_search`, direct EXA REST `/search`, env-only `EXA_API_KEY`, bounded outputs, README/prompt guidance, display/redaction support, and fake-server tests delivered; live EXA smoke intentionally not run; `web_search` requires `queries` (1–5 items), with one item for a single search |
| 0043 | TUI Hook Visibility | Completed | 2026-05-26 | Implemented `hooks.show_in_tui` default-off Mission Control hook activity rows plus shell/Python hook command docs; automated config, hook runtime, agent lifecycle, session isolation, and TUI reducer tests added |
| 0044 | Session Logged Hook Activity | Completed | 2026-05-26 | Local-only session logging and replay for hook lifecycle events plus explicit subagent hook behavior/documentation |
| 0045 | Subagent Hook Inheritance | Completed | 2026-05-26 | Implementation/review PASS; child subagent tool calls inherit parent hooks with child-local hook lifecycle logs, cwd/session isolation, provider isolation, and parent `parallel_subagents` hook preservation |
| 0046 | TUI Header and Focus Hotkey Revamp | Completed | 2026-05-26 | Implementation/review PASS; borderless header, header-owned update notice, pane-level Alt focus shortcuts, double-Alt prompt focus, pane title shortcut labels, docs/tests delivered; manual real-TTY Alt delivery not exercised in API harness |
| 0047 | Hook Context Metadata and Payload Capture | Completed | 2026-05-26 | Implementation/review PASS; schema-versioned hook context metadata, bounded affected paths, safe large full-payload `payload_ref` overflow/omission behavior, docs/tests, and verification delivered |
| 0048 | Configurable Mission Control TUI Effects | Completed | 2026-05-27 | Historical: TachyonFX dependency, active effects, and `tui.effects` setting removed by issue #128 / ADR-0040 |
| 0049 | Mission Control Advanced TUI Effects | Completed | 2026-05-27 | Historical: TachyonFX activity/assistant effects removed by issue #128 / ADR-0040; no active `tui.effects` behavior remains |
| 0050 | Session Compaction Slash Command | Completed | 2026-05-27 | Implementation/review PASS; `/compact`, AI-generated compaction summary, and hard provider-replay cutoff delivered and verified |
| 0051 | Custom Provider Responses Endpoint Override | Completed | 2026-05-29 | Implementation/review PASS; provider-level `use_responses_endpoint` keeps custom providers on Chat Completions by default and opts selected providers into Responses |
| 0052 | Opt-in Session Pruning via /prune-sessions | Completed | 2026-05-29 | Implementation/review PASS; `/prune-sessions [days]` delivered with default 30-day stale session pruning, active-session protection, validation no-op safety, shell/TUI integration, docs/tests/changelog |
| 0052 | Multi-File Read Tool | Completed | 2026-05-29 | Implementation/review PASS; bounded multi-file `read` support with single-file compatibility, strict validation, grouped mixed-result output, aggregate cap, docs/tests delivered |
| 0053 | Two-Column Session Switcher Preview Modal | Completed | 2026-05-30 | Implementation/review PASS; expanded `/sessions` modal with session list plus redacted selected-session first/recent message preview, modal-local scrolling/focus controls, small-terminal fallback, docs/help/tests delivered; manual real-TTY smoke not exercised |
| 0054 | Hash Context Injection Tags | Completed | 2026-05-30 | Implementation/review PASS via PR #42 (`Closes #40`); standalone `#tree` and `#git-status` top-level prompt context injection with Mission Control autocomplete delivered; manual real-TTY smoke not exercised |
| 0055 | Prompt Template Interpolation Variables | Completed | 2026-05-31 | Implementation/review PASS; strict runtime prompt-template variables for `{{has_ripgrep}}`, `{{operating_system}}`, and `{{terminal_environment}}` delivered with docs/tests; ADR-0013 unchanged |
| 0056 | CPU Hotspot Profiling Workflow | Completed; TachyonFX effects scope removed by ADR-0040 | 2026-05-31 | Implementation/review PASS; crate-private harness, credential-free script, fixtures, docs, macOS synthetic samples, and PTY idle TUI baseline delivered; physical-terminal/Linux perf not run |
| 0056 | Edit Tool Multiple Match Replacement | Completed | 2026-05-31 | Issue #59 delivered optional `allow_multiple_matches` for explicit repeated `edit` replacements while default ambiguity error remains |
| 0056 | Expose Codex Reasoning Summaries and Thinking Usage by Default | Completed | 2026-05-31 | Implementation/review PASS; default Codex reasoning summaries, live CLI/TUI rendering, session replay, encrypted-content non-rendering, reasoning-token usage parsing, README/CHANGELOG/tests delivered; live Codex/TUI smoke skipped due credentials/interactive terminal |
| 0057 | Add tabbed right-column panes to Mission Control TUI | Completed | 2026-05-31 | Implementation/review PASS; Activity/Git right-column tabs, tab/mouse switching, bounded redacted Git status/diff pane, docs/tests/changelog delivered |
| 0058 | Mission Control Transcript Card Timeline | Completed | 2026-05-31 | Implementation/review PASS; wide/compact card timeline, prompt/reasoning/tool/parallel_subagents/assistant/session/diagnostic/cancel/error cards, selection/copy integrity, and static display-only rendering delivered; historical TachyonFX card polish removed by issue #128 / ADR-0040 |
| 0059 | Live Tokenizer-Backed TUI Context Usage Projection | Completed | 2026-06-01 | Implementation/review PASS; `tiktoken-rs` OpenAI/Codex estimates, fallback projection, live streaming updates, provider-exact reconciliation, partial-usage zero-safety, README/docs, and focused/full verification delivered |
| 0060 | Additional Configured Markdown Prompt Files | Completed | 2026-06-11 | Settings-backed ordered absolute `.md` instruction files appended after `AGENTS.md` and inherited by subagents |
| 0061 | Opt-in Hook Provider Context Injection | Completed | 2026-06-17 | Implementation/review PASS; opt-in provider-visible after_tool context injection delivered with local-only audit, provider replay/cache exclusion, subagent isolation, and linked ADR-0041 |
| 0062 | Real-Time Message Steering in Mission Control TUI | Completed | 2026-06-19 | Implementation/review PASS; TUI-only active-run steering queue, collapsed post-tool/text-action injection, replay-safe persistence, pending/injected feedback, CLI exclusion; manual real-TTY smoke not exercised |
| 0063 | Built-in view_image Tool | Completed | 2026-06-20 | Implementation/review PASS; provider-visible image-analysis tool delivered with settings-configured vision model, bounded sanitized results, docs/tests; live provider smoke not exercised |
| 0064 | Mission Control Immediate Render Speed | Completed | 2026-06-20 | Implementation/review PASS after fix loop 1; no-artificial-delay redraw behavior delivered, automated suite reported 1690 passing tests; manual real-TTY paint validation remains unexercised |
| 0065 | Prompt-Guidance Eval Harness | Active | 2026-06-20 | Active after accepted implementation plan; scope covers `--dump-prompt`, separate `magi-code-evals` crate, eval-core integration, provider/model matrix, and prompt/tool-call scoring; linked ADR-0043 |
| 0066 | MCP Stdio Tools Client Support | Completed | 2026-06-21 | Phase 1 stdio, tools-only MCP client support implemented and verified: `mcp_servers`, namespaced dynamic tools, CLI diagnostics, filtered env, bounded results; linked plan and ADR-0045 |
| 0067 | MCP Streamable HTTP Client Support | Completed | 2026-06-21 | Phase 2 remote HTTP MCP support implemented and verified: `reqwest::blocking` Streamable HTTP, sessions, SSE parsing, env-indirected headers, redaction, CLI diagnostics; linked plan, PRD-0066, and ADR-0045 |
| 0068 | MCP OAuth HTTP Client Support | Completed | 2026-06-21 | Phase 3 OAuth 2.1 authentication implemented and verified: Authorization Code + PKCE, metadata discovery, dynamic registration, locked token storage/refresh, 401 retry, login/logout/list/test CLI; links PRD-0066, PRD-0067, ADR-0045, and ADR-0046 |
| 0069 | Cascading AGENTS.md Subdirectory Discovery | Active | 2026-06-27 | Opt-in `instructions.subdir_discovery` loads nearest-first subdirectory `AGENTS.md` files from tool-touched paths, bounded by cwd/root and deduped per session |
| 0070 | Project Settings Scopes in Mission Control Modals | Active | 2026-06-30 | `/tools`, `/skills`, and `/subagents` modals can target global or exact-cwd project `settings.json` with Tab scope toggle |
| 0071 | LSP-Backed Live Diagnostics | Completed | 2026-07-08 | Opt-in post-edit LSP diagnostics injection plus diagnostics/references tools; linked ADR-0047 |
| 0072 | Custom Provider Reasoning Protocol | Completed | 2026-07-08 | Capability criteria revised by PRD-0073; protocol-specific request serialization record retained |
| 0073 | Provider-Wide GPT-Like Reasoning Capability | Superseded by PRD-0074 | 2026-07-11 | Historical provider-wide capability assertion; replaced by metadata-gated policy |
| 0074 | Metadata-Gated Custom GPT-Like Reasoning Capability | Completed | 2026-07-11 | Catalog/boolean evidence gates custom GPT-like capability; Codex cache-key contract remains unverified |
| 0075 | Opt-in Automatic Session Compaction | Completed | 2026-08-09 | Implementation/review PASS; exact schema-inclusive projection, durable labeled continuation, steering precedence, and checkpoint-authority failure handling delivered; linked ADR-0055 |