docs: update documentation to reflect unified discovery-plan-execute lifecycle

Author: apiad

docs/deploy.md

@@ -40,8 +40,9 @@ To ensure full functionality, your environment should have:
 
 - **Git:** Required for state management and change detection hooks.
 - **Node.js:** Necessary for running the `gemini` CLI.
-- **Python 3.10+:** Required for executing the project's automation hooks (`.gemini/hooks/`).
-- **Make:** Used for project validation and health checks.
+- **Python 3.12+:** Required for executing the project's automation hooks (`.gemini/hooks/`).
+- **uv:** The required Python package and project manager.
+- **Make:** Used for project validation and health checks (runs `uv run pytest`).
 
 ### Installing Git Hooks
 

docs/design.md

@@ -32,14 +32,30 @@ Helper scripts that standardize framework operations across different environmen
 
 ### 3. The Command System (`.gemini/commands/`)
 
-Commands define structured, multi-phase workflows that automate the development lifecycle. Each command is a TOML file containing specific instructions and context for the agent.
+Commands define structured, multi-phase workflows that automate the development lifecycle. They are strictly categorized by their role in the Unified Lifecycle Flow.
 
-- **`/plan`:** An interactive workflow that transitions between clarification, analysis, and strategy generation.
-- **`/research`:** A deep-dive exploration that produces exhaustive reports in the `research/` directory.
-- **`/debug`:** Activates a **forensic investigation mode** using a scientific, hypothesis-driven workflow.
+#### Phase 1: Discovery & Audit (Read-Only)
+- **`/research`:** Deep-dive exploration producing exhaustive Markdown reports.
+- **`/maintenance`:** A non-destructive codebase audit generating a 'Maintenance Report Card'.
+- **`/review`:** A multi-phase linguistic and structural audit of a document, producing a sidecar `.review.md` file.
+- **`/debug`:** A scientific, hypothesis-driven forensic investigation ending in a Root Cause Analysis (RCA) report.
 - **`/learn`:** A grounded learning lifecycle for mastering new technologies and codifying them into project skills.
-- **`/document`:** Analyzes the codebase and project state to update the documentation suite.
+
+#### Phase 2: Strategy (The Bridge)
+- **`/plan`:** The mandatory bridge. An interactive workflow that transitions between clarification, analysis of discovery artifacts, and strategy generation. It produces a persistent Markdown plan in `plans/`.
+
+#### Phase 3: Execution (Side-Effects)
 - **`/task`:** The primary execution engine, managing `TASKS.md` and enforcing the **strict TCR (Test-Commit-Revert) loop** and feature branch isolation.
+- **`/draft`:** The content execution engine, transforming plans or `.review.md` reports into finished Markdown documents.
+- **`/document`:** Analyzes the codebase and project state to update the documentation suite.
+
+### 🔄 The Unified Lifecycle Flow
+
+The framework enforces a strict architectural boundary between discovering what to do and actually doing it. Data flows unidirectionally:
+
+1. **Artifact Generation:** Discovery commands (`/maintenance`, `/review`, `/debug`) create read-only artifacts (`research/`, `*.review.md`).
+2. **Strategy Synthesis:** The `planner` agent ingests these artifacts via the `/plan` command to generate an actionable, step-by-step roadmap.
+3. **Execution Routing:** The verified plan is handed off to the appropriate execution command (`/task` for logic, `/draft` for prose).
 
 ### 🔍 Deep Dive: Scientific Debugging
 

docs/develop.md

@@ -4,20 +4,33 @@ The **Gemini CLI Opinionated Framework** enforces a high-discipline development
 
 ## 🔄 The Mandatory Workflow Lifecycle
 
-Every non-trivial change must follow this strict four-phase process:
+Every non-trivial change must follow this strict three-phase process:
 
-### 1. Research & Analysis
+```text
+[Phase 1: Discovery] -> [Phase 2: Strategy] -> [Phase 3: Execution]
+(Audit/Research)        (Planning Bridge)      (Tasks/Drafting)
+```
+
+### 1. Discovery & Audit (Read-Only)
+
+Before proposing a change, you must gather context and identify risks. Use the specialized discovery commands:
+- **`/research`**: For domain knowledge and external libraries.
+- **`/maintenance`**: To audit the codebase for technical debt.
+- **`/debug`**: To perform a root-cause analysis (RCA) on a bug.
+- **`/review`**: To audit a document's structure and prose.
 
-Before proposing a change, use the `/research` command to gather context, analyze the current codebase, and identify potential risks.
+*Crucially, these commands are read-only; they produce artifacts (`research/`, `*.review.md`), not code changes.*
 
-### 2. Strategic Planning
+### 2. Strategic Planning (The Bridge)
 
-A feature is not considered "active" until a persistent Markdown plan has been created in the `plans/` directory. Use the `/plan` command to generate this strategy and synchronize it with `TASKS.md`.
+A feature or fix is not considered "active" until a persistent Markdown plan has been created in the `plans/` directory. Use the `/plan` command to synthesize the artifacts generated in Phase 1 into an actionable strategy, and synchronize it with `TASKS.md`.
 
-### 3. Execution & Validation (The TCR Protocol)
+### 3. Execution & Validation (Side-Effects)
 
-The `/task` command is the primary tool for repository execution. It supports multiple actions to manage the project roadmap:
+Once a plan is approved, you move to execution. This is the **only** phase where files are modified.
 
+#### For Code: The TCR Protocol
+The `/task` command is the primary tool for repository execution:
 - **`/task create`**: Adds a new task to `TASKS.md`.
 - **`/task work on ...`**: Implements a strict **TCR (Test-Commit-Revert)** protocol to ensure high-velocity, high-quality code.
 - **`/task report`**: Provides a summary of the roadmap and current priorities.

docs/index.md

@@ -16,15 +16,18 @@ The agent is mandated to challenge ideas before implementing them. It identifies
 
 All significant work must be preceded or accompanied by a structured journal entry. The framework enforces this via a **timestamp-based pre-commit hook**, ensuring that the project's history is an accurate, human-and-AI-readable audit trail of intent and execution.
 
-### 3. Strategy-First (Research -> Plan -> Execute)
+### 3. Strategy-First (Discovery -> Plan -> Execute)
 
-Every non-trivial change follows a strict, non-negotiable lifecycle. The agent first researches the domain, proposes a detailed implementation plan, obtains user approval, and only then begins writing code. This is enforced by the **TCR (Test-Commit-Revert)** protocol, ensuring a "Green-only" development path.
+Every non-trivial change follows a strict, non-negotiable lifecycle. 
+1. **Discovery & Audit:** The agent first researches the domain (`/research`), audits the codebase (`/maintenance`, `/review`), or investigates bugs (`/debug`) without modifying anything.
+2. **Strategy:** A detailed implementation plan is proposed (`/plan`) based on discovery artifacts and requires user approval.
+3. **Execution:** Only then does the agent begin writing code (`/task`) or content (`/draft`). This is enforced by the **TCR (Test-Commit-Revert)** protocol, ensuring a "Green-only" development path.
 
-### 3. Validation-as-Truth
+### 4. Validation-as-Truth
 
 The `makefile` is the ultimate source of truth for project health. Automated hooks ensure that every agent action is followed by a validation run (linting, testing, formatting) to prevent regressions.
 
-### 4. Task Isolation (Feature Branching)
+### 5. Task Isolation (Feature Branching)
 
 All development work is strictly performed on dedicated, auto-generated feature branches. This keeps the `main` branch protected and always in a deployable state, while providing a clean, granular history for every task.
 
@@ -52,7 +55,7 @@ curl -fsSL https://apiad.github.io/starter/install.sh | bash
 
 1.  **Onboarding:** Run `/onboard` to get a high-signal overview of the repository.
 2.  **Scaffolding:** Use `/scaffold` to initialize new project components with modern tooling.
-3.  **Iterative Development:** Follow the Research-Plan-Execute cycle for every feature.
+3.  **Iterative Development:** Follow the Discovery -> Plan -> Execute cycle for every feature.
 4.  **Quality Control:** Rely on the `make.py` hook to maintain codebase integrity.
 5.  **Releasing:** Use `/release` to automate versioning, changelog updates, and git tagging.
 

docs/user-guide.md

@@ -18,9 +18,14 @@ This framework solves this problem by enforcing three core principles:
 
 ---
 
-## 🔍 The Discovery & Strategy Workflow
+## 🔍 Phase 1: Discovery & Audit
 
-The most critical phase of any project occurs before you write a single line of code. This framework moves away from impulsive execution toward a deliberate, architected approach.
+The most critical phase of any project occurs before you write a single line of code. This phase uses read-only commands to gather information safely.
+
+### `/research`
+
+Your tool for deep domain exploration.
+- **How it works:** Gathers documentation and synthesizes it into `research/` reports.
 
 ### `/debug`
 
@@ -29,6 +34,12 @@ Your primary tool for forensic, scientific investigation.
 - **How it works:** When a bug is detected, the `/debug` command implements a principled approach to problem-solving using the specialized `debugger` subagent. It moves through four distinct phases: Context Analysis, Hypothesis Formulation, Isolated Testing on a temporary branch (`debug/hyp-*`), and finally a Synthesis of the findings into a **Root Cause Analysis (RCA)** report.
 - **Why it works:** It forces the agent to identify the root cause *before* attempting a fix, preventing "guess-and-check" coding that can lead to regressions.
 
+---
+
+## 🌉 Phase 2: Strategy & Planning
+
+Once you have gathered discovery artifacts, you must synthesize them into an actionable strategy.
+
 ### `/plan`
 
 Your tool for internal strategy and architectural design.
@@ -54,7 +65,7 @@ Your tool for rapid project orientation.
 
 ---
 
-## 💻 The Software Development Workflow
+## 🚀 Phase 3: Execution & Implementation
 
 Once you have a solid strategy in `plans/`, you can move into execution. These commands eliminate the friction of context-switching between your IDE and terminal.
 
@@ -91,13 +102,14 @@ Automates the deployment process.
 
 ## 🔄 A Full Feature Development Walkthrough
 
-A complete, principled development cycle follows the **Research -> Plan -> Execute** lifecycle.
+A complete, principled development cycle follows the **Discovery -> Plan -> Execute** lifecycle.
 
-### **Step 1: Research with `/research`**
+### **Step 1: Discovery with `/research`, `/maintenance`, or `/review`**
 
-You are integrating a new authentication library. You start by researching the technical requirements.
+Before acting, you must gather context. For example, if you are integrating a new authentication library, you start by researching the technical requirements.
 
 - The `researcher` subagent gathers documentation and synthesizes it into `research/auth-library-deep-dive.md`.
+- Alternatively, you might run `/maintenance` to audit the codebase or `/review` to audit a document. In all cases, a read-only artifact is produced.
 
 ### **Step 2: Strategy with `/plan`**