docs: update documentation to reflect TCR protocol and task isolation principles

Author: apiad

docs/design.md

@@ -20,6 +20,10 @@ Commands define structured, multi-phase workflows that automate the development
 - **`/research`:** A deep-dive exploration that produces exhaustive reports in the `research/` directory.
 - **`/debug`:** Activates a forensic investigation mode for root-cause analysis.
 - **`/docs`:** Analyzes the codebase and project state to update the documentation suite.
+- **`/task`:** The primary execution engine, managing `TASKS.md` and enforcing the strict TCR (Test-Commit-Revert) loop and feature branch isolation.
+
+### 🔌 Synergistic Validation
+The `/task` command works in tandem with the `make.py` hook to ensure a "no-regression" policy. While `/task` enforces testing during the Red-Green-Verify cycle, the `make.py` hook provides a final, infrastructure-level check after every turn. If any turn (manual or automated) results in broken code, the framework immediately detects it, ensuring that the repository's "last known state" is always stable.
 
 ### 3. Specialized Agents (`.gemini/agents/`)
 Instead of a single "do-it-all" AI, the framework delegates tasks to specialized sub-agents with restricted toolsets and focused personas (e.g., `planner`, `debugger`, `editor`, `reporter`). This ensures higher reliability and more consistent results.

docs/develop.md

@@ -12,10 +12,25 @@ Before proposing a change, use the `/research` command to gather context, analyz
 ### 2. Strategic Planning
 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`.
 
-### 3. Execution & Validation
-- **Incremental Implementation:** Break features into small, testable commits.
-- **Continuous Validation:** After every implementation turn, the framework automatically runs the `makefile`. Do not attempt to bypass this process.
-- **Journaling:** A brief, one-line technical log must be added to the daily journal for every significant turn.
+### 3. Execution & Validation (TCR Protocol)
+The `/task work` command implements a strict **TCR (Test-Commit-Revert)** protocol to ensure high-velocity, high-quality code.
+
+#### **Phase 1: Pre-flight Verification**
+The agent verifies that the working tree is clean, the current branch is `main`, and `make test` passes as a baseline.
+
+#### **Phase 2: Task Isolation**
+A dedicated feature branch (e.g., `feature/task-name`) is auto-generated and checked out. All subsequent work for this task occurs here.
+
+#### **Phase 3: The Red-Green-Verify Loop**
+For every granular step of the implementation:
+1.  **Red:** Write a failing test and verify failure with `make test`.
+2.  **Green:** Implement the minimal code to pass.
+3.  **Verify:** Run `make test`.
+    - **Pass:** `git commit` the step.
+    - **Fail:** Attempt one quick fix; if it still fails, **revert** to the last green state (`git checkout .`).
+
+#### **Phase 4: Integration**
+Once all steps are complete, a final test run is performed. Upon user approval, the branch is merged back to `main` and the roadmap in `TASKS.md` is updated.
 
 ## ✅ Testing & Quality Standards
 

docs/index.md

@@ -12,11 +12,14 @@ The framework is built on the belief that AI is most effective when it is constr
 The agent is mandated to challenge ideas before implementing them. It identifies technical flaws, security risks, or redundant logic, acting as a "peer reviewer" in real-time.
 
 ### 2. Strategy-First (Research -> 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.
+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.
 
 ### 3. 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)
+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.
+
 ## 🚀 Quick Start
 
 The fastest way to bootstrap a new project or integrate the framework into an existing one is to run the following command in your terminal:

docs/user-guide.md

@@ -54,21 +54,33 @@ Brings order to your version history.
 Automates the deployment process.
 - **How it works:** Verifies workspace integrity (clean git tree, passing tests via `make`), analyzes commit history to propose the next version bump, drafts a `CHANGELOG.md` entry, and publishes the final tag to GitHub.
 
----
+## 🔄 A Full Feature Development Walkthrough
 
-## ✍️ The Content Creation Workflow
+A complete, principled development cycle follows the **Research -> Plan -> Execute** lifecycle.
 
-The framework is uniquely suited for writing high-quality documentation and long-form articles, built on the same cognitive foundation as the development path.
+### **Step 1: Research with `/research`**
+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`.
 
-### `/draft`
-Turns research into structured prose.
-- **How it works:** Performs a deep scan of `research/` and `plans/` to identify key themes. It collaboratively generates a Markdown outline. Once approved, the `reporter` subagent expands the outline section-by-section, drawing directly from your validated research to ensure evidence-based writing.
+### **Step 2: Strategy with `/plan`**
+Once you understand the requirements, you trigger the `/plan` command.
+- The `planner` subagent analyzes the codebase and generates `plans/implement-auth.md`, mapping out the specific architectural changes and testing strategy.
 
-### `/revise`
-Provides professional editing and polish.
-- **How it works:** Uses the `editor` subagent to perform a structural and linguistic audit based on your `.gemini/style-guide.md`. It identifies logical gaps and awkward phrasing, presenting specific improvements for you to review interactively.
+### **Step 3: Execute with `/task work`**
+The approved plan is linked to a task. You trigger the execution:
+- **Pre-flight:** The agent verifies the tree is clean on `main`.
+- **Isolation:** A `feature/auth-integration` branch is created.
+- **Loop (Red-Green-Verify):**
+    1.  Agent writes a failing `test_auth_logic.py`.
+    2.  Agent implements the minimal logic to pass.
+    3.  Agent runs `make test`. If successful, the step is committed.
+    4.  The loop repeats for every granular step.
 
----
+### **Step 4: Review & Integrate**
+After all steps pass, the agent presents the final work. Upon your approval, it merges back to `main` and cleans up the feature branch.
+
+### **Step 5: Document & Release with `/docs` & `/release`**
+Finally, use `/docs` to update the technical documentation and `/release` to publish the new version.
 
 ## ⚙️ Background Tasks & Maintenance