Step: Align README, Style Guide, Docs, and historical entries with writer/reviewer naming

Author: apiad

.gemini/style-guide.md

@@ -1,6 +1,6 @@
 # Gemini CLI Style Guide
 
-This guide defines the authoritative technical and narrative style for all project documentation, articles, and reports. The `/review` command and the `reviewer` subagent use these rules to perform structured, multi-phase, non-destructive audits.
+This guide defines the authoritative technical and narrative style for all project documentation, articles, and reports. The `/draft` command and its `writer` subagent use these rules for original composition, while the `/review` command and the `reviewer` subagent use them to perform structured, multi-phase, non-destructive audits.
 
 ## General Context
 - **Tone:** Intellectual but accessible. Conversational academic style.

CHANGELOG.md

@@ -144,13 +144,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 - Implemented `/plan` command workflow and `planner` subagent for architectural planning.
-- Added `/draft` and `/revise` commands with `reporter` and `editor` subagents for structured content generation.
+- Added `/draft` and `/review` commands with `writer` and `reviewer` subagents for structured content generation.
 - Created an actionable project style guide in `.gemini/style-guide.md`.
 - Drafted the "The Architect in the Machine" Substack article showcasing the framework.
 
 ### Changed
 - Overhauled the `/research` command into an extensible, executive-style reporting workflow with iterative updates and asset linking.
-- Refactored `/draft` and `/revise` commands to integrate step-by-step, style-driven audits.
+- Refactored `/draft` and `/review` commands to integrate step-by-step, style-driven audits.
 - Refined `/plan` and `/task` workflows.
 
 ## [0.7.0] - 2026-03-02
@@ -198,7 +198,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [0.3.0] - 2026-02-28
 
 ### Added
-- Refactored the `/research` command into a robust 3-phase workflow using specialized `researcher` and `reporter` subagents.
+- Refactored the `/research` command into a robust 3-phase workflow using specialized `researcher` and `writer` subagents.
 - Rewrote the `README.md` to explain the opinionated framework, the agent's behavior, hooks, commands, journaling, and the project initialization workflow.
 
 ### Changed

README.md

@@ -73,7 +73,7 @@ The `.gemini/commands/` directory defines specialized workflows that automate ev
 *   **`/scaffold`**: Initializes new project structures from scratch using modern, standard tooling (Python/uv, TS/npm, Rust/cargo, etc.) and sets up a compatible `makefile`.
 
 ### 🧹 Phase 3: Content Generation, Maintenance & Documentation
-*   **`/draft`**: Multi-phase workflow to turn research and plans into detailed, high-quality technical documents or articles section-by-section.
+*   **`/draft`**: Multi-phase workflow to turn research and plans into detailed, high-quality technical documents or articles section-by-section using the `writer` subagent.
 *   **`/review`**: Uses the `reviewer` subagent to perform non-destructive, multi-phase structural and linguistic audits based on the project's style guide.
 *   **`/maintenance`**: Performs a deep scan of the codebase to identify technical debt, refactoring opportunities, and areas to improve test coverage.
 *   **`/document`**: Analyzes the codebase and journals to generate or update comprehensive project documentation in the `docs/` folder.

TASKS.md

@@ -55,7 +55,7 @@ Put done tasks into the Archive.
 - [x] Add the /issues command to manage project issues with GitHub CLI. (2026-02-28)
 - [x] Refactor the hook system: centralize shared logic into `.gemini/hooks/utils.py` and add PEP 257 docstrings. (2026-02-28)
 - [x] Rewrite the `README.md` to explain the opinionated framework and its key features. (2026-02-28)
-- [x] Refactor the `/research` command into a 3-phase workflow with researcher and reporter subagents. (2026-02-28)
+- [x] Refactor the `/research` command into a 3-phase workflow with researcher and writer subagents. (2026-02-28)
 - [x] Consolidate the `/task/*` commands into a single `/task` command. (2026-02-28)
 
 > Done tasks go here, in the order they where finished, with a finished date.

docs/design.md

@@ -79,7 +79,7 @@ Instead of a single "do-it-all" AI, the framework delegates tasks to specialized
 - **`debugger`:** A forensic investigation specialist using a scientific, hypothesis-driven workflow.
 - **`learner`:** A "Grounded Learning Specialist" who masters new technologies by writing, executing, and documenting code experiments.
 - **`researcher`:** Optimized for deep information gathering and multi-source synthesis.
-- **`reporter` / `editor`:** Content generation and refinement specialists.
+- **`writer` / `reviewer`:** Content generation and refinement specialists.
 
 ### 5. The Skill System (`.gemini/skills/`)
 

docs/user-guide.md

@@ -14,7 +14,7 @@ This framework solves this problem by enforcing three core principles:
 
 1.  **The important things should be made explicit:** We keep track of everything important in Markdown files. Ideas are committed to `plans/`, research is summarized in `research/`, and all changes are logged in the `journal/`. This physical "long-term memory" prevents the agent from forgetting context.
 2.  **Resist the urge to guess:** We favor explicit commands over implicit actions. If you want the model to make a plan, you use the `/plan` command, which invokes a carefully crafted workflow rather than relying on the agent's default behavior.
-3.  **Delegate, delegate, delegate:** We use specialized sub-agents (`planner`, `researcher`, `reporter`, `editor`). These agents run complex, multi-step tasks in private contexts, preventing their internal reasoning (e.g., browsing 20 web pages) from polluting the main session's context window.
+3.  **Delegate, delegate, delegate:** We use specialized sub-agents (`planner`, `researcher`, `writer`, `reviewer`). These agents run complex, multi-step tasks in private contexts, preventing their internal reasoning (e.g., browsing 20 web pages) from polluting the main session's context window.
 
 ---
 
@@ -168,7 +168,7 @@ Beyond code, this framework excels at generating high-quality technical content
 
 Your primary tool for long-form technical writing.
 
-- **How it works:** Instead of generating a single large blob of text, the `/draft` command follows a strict 6-phase workflow: Context Gathering (from `research/` or `plans/`), Title & Metadata Selection, Outline Creation (aligned with the Style Guide), Initialization of the file, Section-by-Section Drafting (using the `reporter` subagent), and finally, a Conclusion with next steps.
+- **How it works:** Instead of generating a single large blob of text, the `/draft` command follows a strict 6-phase workflow: Context Gathering (from `research/` or `plans/`), Title & Metadata Selection, Outline Creation (aligned with the Style Guide), Initialization of the file, Section-by-Section Drafting (using the `writer` subagent), and finally, a Conclusion with next steps.
 - **Why it works:** It forces structural integrity and prevents the "AI-ish" monotone by building the document incrementally based on project-specific research.
 
 ### `/review`

drafts/architect-in-the-machine.md

@@ -44,9 +44,9 @@ I use four sub-agents in different commands. The `planner` is the lead architect
 
 When I need external knowledge---like a library’s latest API or a specific technical specification---the `researcher` agent takes over. It scours the web to fetch relevant documentation, which it then synthesizes into granular summaries in the `research/` directory. This raw data is then handed off to the main agent to build an executive report annotated and linked to all relevant sources, again all stored already in your repository.
 
-And there are two more agents, specifically designed for technical writing. The `reporter` agent takes an outline, and a folder of content, and it will write section by section, a detailed account of what the outline requested.
+And there are two more agents, specifically designed for technical writing. The `writer` agent takes an outline, and a folder of content, and it will write section by section, a detailed account of what the outline requested.
 
-Unlike a standard LLM that might provide a high-level summary, the `reporter` is trained to expand specific placeholders with deep, evidence-based paragraphs. It draws directly from your `research/` files and the project `journal/` to ensure every sentence is grounded in the project's actual state. Finally, the `editor` provides the final polish, auditing the draft for structural gaps and linguistic tics. It is grounded in a customizable style guide to make sure it always respects your style.
+Unlike a standard LLM that might provide a high-level summary, the `writer` is trained to expand specific placeholders with deep, evidence-based paragraphs. It draws directly from your `research/` files and the project `journal/` to ensure every sentence is grounded in the project's actual state. Finally, the `reviewer` provides the final polish, auditing the draft for structural gaps and linguistic tics. It is grounded in a customizable style guide to make sure it always respects your style.
 
 This distributed intelligence is held together by a central nervous system of context files, as per principle one. A `journal/` directory provides a chronological record of decisions and progress, acting as a long-term memory for the project. The `plans/` directory stores the strategic intent, while a `TASKS.md` file provides a high-level overview of the project's current status. This structured environment allows the subagents to maintain a high degree of situational awareness without needing to ingest the entire repository in every turn.
 
@@ -88,17 +88,17 @@ Anyway, the approach is built on the same cognitive foundation as the developmen
 
 It starts with the `/draft` command. In its initial phase, the system performs a deep scan of the `research/` and `plans/` directories to identify the key themes relevant to the requested topic. If the foundation is too thin, the system will pause and suggest a `/research` or `/plan` cycle to ensure the draft has sufficient substance. Once the context is validated, the workflow enters an interactive "Outline Creation" phase. Rather than guessing at a structure, the system proposes a detailed Markdown outline. This collaborative step allows me to set the narrative arc and logical flow that I want, iterating on the high-level structure of, say, a technical article, before committing on the details.
 
-Once the outline is locked, the `/draft` process initializes a skeleton file---complete with section headers and strategic placeholders---and then moves into an iterative, section-by-section expansion. Here, the `reporter` subagent takes the lead. Guided by the specific context of each section, the `reporter` weaves together research summaries and technical specifications into professional prose, all grounded on a style guide document.
+Once the outline is locked, the `/draft` process initializes a skeleton file---complete with section headers and strategic placeholders---and then moves into an iterative, section-by-section expansion. Here, the `writer` subagent takes the lead. Guided by the specific context of each section, the `writer` weaves together research summaries and technical specifications into professional prose, all grounded on a style guide document.
 
 Because the expansion happens in granular steps, the system maintains a high level of detail that a single-shot generation would inevitably lose. The result is a first draft that is structurally sound and rich with technical depth.
 
-However, a first draft is rarely the final word. It will always sound AI-ish, and for many other reasons, it is rarely good enough. To achieve professional quality, I use the `/revise` command, which runs a structural and linguistic audit powered by the `editor` subagent following the same style guide.
+However, a first draft is rarely the final word. It will always sound AI-ish, and for many other reasons, it is rarely good enough. To achieve professional quality, I use the `/review` command, which runs a non-destructive, multi-phase audit powered by the `reviewer` subagent following the same style guide. This process produces a dedicated review report, identifying structural gaps and linguistic tics, which I then apply back to the draft using the `/draft` command's refinement mode.
 
-Unlike a simple "check my writing" prompt, the `editor` performs a deep analysis of the document's flow and tone. It identifies logical gaps where more evidence might be needed and highlights awkward phrasing that could obscure my intent. And crucially, this isn't an automated "fix-all" tool; it's an interactive process. The system presents its findings and proposes specific improvements, which I can then review or approve.
+Unlike a simple "check my writing" prompt, the `reviewer` performs a deep analysis of the document's flow and tone. It identifies logical gaps where more evidence might be needed and highlights awkward phrasing that could obscure my intent. And crucially, this isn't an automated "fix-all" tool; it's an interactive process. The system presents its findings and proposes specific improvements, which I can then review or approve.
 
-This collaborative refinement process ensures the final output maintains a consistent, professional voice while benefiting from the speed of the AI. By using `/revise`, I can surgically improve the text to enhance clarity and impact without losing control over the narrative.
+This collaborative refinement process ensures the final output maintains a consistent, professional voice while benefiting from the speed of the AI. By using `/review` and `/draft` refinement, I can surgically improve the text to enhance clarity and impact without losing control over the narrative.
 
-But, in any case, I always find necessary a manual review and editing after all the AI enhancements. It shouldn't be a surprise to you that this article is written in this way, but what you're reading now is probably 80% different to what the final `/revise` iteration gave me. There is only so much you can prompt an AI, and that final human touch is not part of it.
+But, in any case, I always find necessary a manual review and editing after all the AI enhancements. It shouldn't be a surprise to you that this article is written in this way, but what you're reading now is probably 80% different to what the final `/review` iteration gave me. There is only so much you can prompt an AI, and that final human touch is not part of it.
 
 But that's good. This automates the first 80% or so of compiling a gazillion sources into a coherent narrative, and leaves the remaining 80% of polishing for me, which is the part I actually enjoy about writing.
 

journal/2026-02-28.md

@@ -1,6 +1,6 @@
 - Consolidated `/task/*` commands (`create`, `work`, `report`, `update`) into a single `/task` command in `.gemini/commands/task.toml`.
 - Added a new `/scaffold` command to initialize new projects with modern standard practices and tooling.
-- Refactored the `/research` command into a robust 3-phase workflow using specialized `researcher` and `reporter` subagents.
+- Refactored the `/research` command into a robust 3-phase workflow using specialized `researcher` and `writer` subagents.
 - Rewrote the `README.md` to explain the opinionated framework, the agent's behavior, hooks, commands, journaling, and the project initialization workflow.
 - Refactored the hook system: centralized shared logic into `.gemini/hooks/utils.py` and added PEP 257 docstrings to all hooks.
 - Released version 0.4.0, documenting the hook system refactor and internal improvements.

journal/2026-03-02.md

@@ -3,11 +3,11 @@
 - Beautified `README.md` with project badges, emoji headers, and improved formatting.
 - Restored and updated `CHANGELOG.md` for the v0.7.0 release.
 - Implemented a custom `/plan` command workflow and a `planner` sub-agent to generate execution plans in `plans/` and synchronize with `TASKS.md`.
-- Initiated the planning process for drafting and editing capabilities, including the design of `/draft` and `/revise` commands and subagent integration.
+- Initiated the planning process for drafting and editing capabilities, including the design of `/draft` and `/review` commands and subagent integration.
 - Reorganized `README.md` to reflect a structured project lifecycle (Planning, Development, Maintenance, Shipping) and documented the `/plan` command's interactive phases.
-- Implemented `/draft` and `/revise` commands, refactored the `reporter` agent, and created the `editor` subagent to enable structured drafting and editing workflows.
-- Drafted a comprehensive Substack article "The Architect in the Machine" using the new `/draft` command and `reporter` subagent, showcasing the repository's AI-assisted development workflow.
-- Created an actionable project style guide in `.gemini/style-guide.md` and refactored `/draft` and `/revise` commands to integrate step-by-step, style-driven audits.
+- Implemented `/draft` and `/review` commands, refactored the `writer` agent, and created the `reviewer` subagent to enable structured drafting and editing workflows.
+- Drafted a comprehensive Substack article "The Architect in the Machine" using the new `/draft` command and `writer` subagent, showcasing the repository's AI-assisted development workflow.
+- Created an actionable project style guide in `.gemini/style-guide.md` and refactored `/draft` and `/review` commands to integrate step-by-step, style-driven audits.
 - Refactored the `/research` command into an extensible, executive-style reporting workflow with iterative report updates, detailed asset linking, and conclusion/recommendation synthesis.
 - Released v0.8.0 with planning, drafting, and editing capabilities, refactored research workflow, and updated README/CHANGELOG.
 - Refined the Substack draft "The Architect in the Machine" by fixing typos, spelling, and grammar errors while preserving the original style.

journal/2026-03-23.md

@@ -8,3 +8,4 @@
 [2026-03-23T06:00:12] - Plan and task for improving /draft command and evolve writer agent.
 [2026-03-23T06:00:52] - Rename reporter agent to writer and update its definition for composition and refinement.
 [2026-03-23T06:01:22] - Update /draft command with branching logic for initial drafting and review-driven refinement.
+[2026-03-23T06:07:18] - Align README, Style Guide, Docs, and historical entries with writer/reviewer naming.