{
  "markdown": "# Scribe Commands Extension for Gemini CLI\n\n<p align=\"center\">\n  <img src=\"static/scribe-logo.png\" alt=\"Scribe Logo\" width=\"200\"/>\n</p>\n\nAn AI-powered extension for [Gemini CLI](https://github.com/google-gemini/gemini-cli) that facilitates a professional, multi-stage documentation workflow from research to final polish.\n\n> **Read the deep-dive blog post:** [Building Scribe: Spec-Driven Documentation in the Terminal](https://sapient.coffee/posts/2025/scribe-gemini-cli-extension/)\n\n## Workflow Diagram\n\n```mermaid\ngraph TD\n    subgraph \"Phase 1: Preparation\"\n        Research[/\"/scribe:research\"/] -->|Creates| ResearchDoc[(\"RESEARCH.md\")]\n        ResearchDoc --> Plan\n        Plan[/\"/scribe:plan\"/] -->|Creates| BlueprintDoc[(\"BLUEPRINT.md\")]\n    end\n\n    subgraph \"Phase 2: Production\"\n        BlueprintDoc --> Draft\n        ResearchDoc -.-> Draft\n        Draft[/\"/scribe:draft\"/] -->|Creates| DraftDoc[(\"DRAFT.md\")]\n    end\n\n    subgraph \"Phase 3: Refinement\"\n        DraftDoc --> Review\n        Review[/\"/scribe:review\"/] -->|Creates| CritiqueDoc[(\"CRITIQUE.md\")]\n        CritiqueDoc --> Iterate\n        Iterate[/\"/scribe:iterate\"/] -->|Updates| DraftDoc\n        DraftDoc --> Polish\n    end\n\n    subgraph \"Phase 4: Finalization\"\n        Polish[/\"/scribe:polish\"/] -->|Creates| FinalDoc[(\"FINAL.md\")]\n        FinalDoc --> Archive\n        Archive[/\"/scribe:archive\"/] -->|Moves to| ArchiveFolder[(\"scribe/_archive_/\")]\n    end\n\n    style Research fill:#e1f5fe,stroke:#01579b,stroke-width:2px\n    style Plan fill:#e1f5fe,stroke:#01579b,stroke-width:2px\n    style Draft fill:#fff9c4,stroke:#fbc02d,stroke-width:2px\n    style Review fill:#ffebee,stroke:#b71c1c,stroke-width:2px\n    style Iterate fill:#ffebee,stroke:#b71c1c,stroke-width:2px\n    style Polish fill:#e8f5e9,stroke:#2e7d32,stroke-width:2px\n    style Archive fill:#f5f5f5,stroke:#616161,stroke-width:2px\n```\n\n## The Scribe Workflow: A Quality Control Loop\n\nScribe operates on a structured, file-based workflow that mimics a professional editorial process. Each command performs a specific task and creates a specific file, allowing you to review and control every stage of document creation.\n\n1. **Research (`/scribe:research`):** Gathers foundational knowledge and creates `RESEARCH.md`.\n2. **Plan (`/scribe:plan`):** Creates a structured outline in `BLUEPRINT.md`.\n3. **Draft (`/scribe:draft`):** Writes the first version of the document into `DRAFT.md`.\n4. **Review (`/scribe:review`):** Critiques the draft from a specific perspective and creates `CRITIQUE.md`.\n5. **Iterate (`/scribe:iterate`):** Applies your chosen fixes from the critique to the `DRAFT.md`.\n6. **Polish (`/scribe:polish`):** Performs a final grammar and style check, creating `FINAL.md`.\n\n## Ideal Use Cases\n\nScribe is designed for high-stakes, long-form content where structure and accuracy are paramount.\n\n### 📖 Technical Books\n\n* **Why:** Maintains consistency across hundreds of pages.\n* **Strategy:** Treat each chapter as a separate Scribe project (e.g., `scribe/ch01-intro`). This keeps the context focused while a global `styleguide.md` ensures a unified voice across all chapters.\n* **Key Feature:** Use `/scribe:review --lens=tech` to specifically audit code snippets and technical claims separate from prose editing.\n\n### 📄 Whitepapers & RFCs\n\n* **Why:** Requires persuasive authority and bulletproof logic.\n* **Strategy:** Use the **Research** phase to ground arguments in data, preventing hallucinations.\n* **Key Feature:** Use `/scribe:review --lens=devil` to simulate a skeptical stakeholder, tearing down weak arguments before you publish.\n\n### 🎯 Product Requirement Documents (PRDs)\n\n* **Why:** PRDs are contracts between teams; ambiguity causes bugs.\n* **Strategy:** Use `/scribe:plan` to enforce standard sections (Non-Goals, Success Metrics) that are often skipped.\n* **Key Feature:** Use `/scribe:review --lens=devil` to hunt for edge cases and vague requirements before engineering sees the doc.\n\n### 📝 Complex Engineering Documentation\n\n* **Why:** \"Chatting\" a complex doc into existence often leads to structural mess.\n* **Strategy:** The **Plan** phase (`BLUEPRINT.md`) forces you to agree on the document's architecture before a single sentence is written.\n\n## Available Commands\n\n| Status             | Command          | Purpose                                                       | User Mental Model                                     |\n| :----------------- | :--------------- | :------------------------------------------------------------ | :---------------------------------------------------- |\n| :white_check_mark: | `/scribe:status`   | Checks the current workflow state and suggests the next step. | \"Where was I? What should I do next?\"                 |\n| :white_check_mark: | `/scribe:research` | Compiles a research dossier on a topic.                       | \"I need foundational knowledge on a new subject.\"     |\n| :white_check_mark: | `/scribe:plan`     | Creates a structured `BLUEPRINT.md` from a topic.             | \"Help me think. I need to structure my idea.\"         |\n| :white_check_mark: | `/scribe:draft`    | Writes the first `DRAFT.md` from the blueprint.               | \"I have an outline and I'm ready for the full text.\"      |\n| :white_check_mark: | `/scribe:review`   | Critiques the draft and creates a `CRITIQUE.md` report.       | \"Check my work for logical flaws or missed details.\"  |\n| :white_check_mark: | `/scribe:iterate`  | Applies specific feedback from the critique to the draft.     | \"Fix the specific issues I tell you to.\"               |\n| :construction:     | `/scribe:polish`   | Performs a final grammar and style check.                     | \"Make this text sound professional and read better.\" |\n\n## Enforcing Consistency with a Style Guide\n\nTo ensure all documents have a consistent voice, tone, and format, you can create a `styleguide.md` file in your project root.\n\nIf Scribe finds this file, it will strictly adhere to the rules defined within it during the `draft`, `iterate`, and `polish` phases. An example `styleguide.md` is included with the extension to get you started.\n\n## Prerequisites\n\nInstall the [Gemini CLI](https://geminicli.com/docs/getting-started/installation).\n\n**Learn more about** [Gemini CLI Extensions](https://geminicli.com/docs/extensions/)!\n\n## Extension Installation\n\nFrom your command line:\n\n```bash\ngemini extensions install https://github.com/sapientcoffee/scribe\n```\n\n## Extension Validation & Testing\n\nWe maintain high quality standards for this extension using automated linting and validation tests.\n\n```mermaid\ngraph LR\n    classDef external fill:#f9f9f9,stroke:#333,stroke-width:2px,stroke-dasharray: 5 5;\n    \n    Developer[Developer] -->|Run Locally| Script[\"./scripts/run-tests.sh\"]\n    Developer -->|Push / PR| GitHub[GitHub Actions]:::external\n\n    subgraph \"Automated Checks\"\n        Script --> Manifest[\"Manifest Validation\"]\n        Script --> Syntax[\"Syntax Linting<br/>(JSON, YAML, TOML, MD)\"]\n        Script --> Audit[\"Token Audit\"]\n        \n        GitHub --> Manifest\n        GitHub --> Syntax\n        Script --> Linting[\"Linter Checks<br/>(JSON, MD, TOML, YAML)\"]\n        Script --> Audit[Token Audit]\n        \n        GitHub --> Linting\n        GitHub --> Audit\n        GitHub --> Quality[\"Quality Assurance<br/>(Promptfoo)\"]\n        GitHub --> Validation[\"Extension Validation<br/>(Install & List)\"]\n        \n        GitHub --> EvalFlow[Evaluation Pipeline]\n    end\n\n    subgraph \"Evaluation Pipeline\"\n        EvalFlow --> CustomJudge[\"Custom Judge (Node.js)<br/>Run CLI -> Generate Content\"]\n        CustomJudge -->|Grading Prompt| Gemini[Gemini API]:::external\n        CustomJudge -->|Passes Artifact| VertexEval[\"Vertex AI Eval (Python)<br/>Compute Metrics\"]\n        VertexEval -->|Compute| VertexAPI[Vertex AI Service]:::external\n        VertexAPI -->|Logs to| VertexConsole[Vertex Experiments]:::external\n    end\n```\n\n### Running Tests Locally\n\nTo ensure your changes are valid before pushing, you can run the local test script:\n\n```bash\nnpm test\n```\n\nThis script checks for:\n1. **JSON Syntax:** Validates `gemini-extension.json` and other JSON files.\n2. **Markdown Style:** Checks all `.md` files against our style guide.\n3. **TOML Validity:** Ensures command definitions in `commands/` are valid TOML.\n4. **YAML Syntax:** Validates GitHub Actions workflow files.\n\n### Semantic & Matrix Testing\n\nWe use `promptfoo` to perform deep semantic testing of the extension's output.\n\n*   **Quality Check:** `npm run test:eval`\n    *   Tests if the \"Architect\" sounds like an architect.\n    *   Verifies formatting constraints (e.g., line length).\n*   **Model Matrix:** `npm run test:models`\n    *   Runs the same tests against multiple Gemini models (e.g., Gemini 3 Pro vs Gemini 2.0 Flash) side-by-side.\n    *   Useful for ensuring future-proofing and regression testing across model versions.\n\n### CI/CD Pipeline\n\n### CI/CD Pipeline\n\nEvery Pull Request is automatically tested via GitHub Actions to verify:\n*   **Linting:** All file formats (JSON, Markdown, YAML, TOML) are syntactically correct.\n*   **Installation:** The extension installs successfully in a fresh environment.\n*   **Validation:** The extension manifest is valid according to the Gemini CLI schema.\n*   **Token Audit:** Estimates token usage for each command to ensure prompts remain efficient (< 4500 tokens).\n\n### CI Configuration\n\nTo enable the Token Audit in your fork or repository, you must provide a Gemini API Key.\n\n1.  Get an API Key from [Google AI Studio](https://aistudio.google.com/).\n2.  Go to your GitHub Repository **Settings** > **Secrets and variables** > **Actions**.\n3.  Create a **New repository secret** named `GEMINI_API_KEY`.\n4.  Paste your API key value.\n\nWithout this key, the CI workflow will fail.\n\n## Evaluation & Quality Assurance\n\nTo ensure the quality of the Scribe extension's outputs, we have implemented multiple evaluation strategies.\n\n### 1. Custom Judge Script (Node.js)\nThis script runs an end-to-end test of the CLI commands and uses a \"Judge\" LLM (Gemini 3 Pro) to grade the generated content.\n\n*   **Usage:** `node scripts/eval-custom.js`\n*   **What it does:**\n    1.  Executes `/scribe:research` and `/scribe:plan` via the Gemini CLI (headless mode).\n    2.  Verifies the creation of `BLUEPRINT.md`.\n    3.  Sends the blueprint to Gemini 3 Pro with a grading rubric (Structure, Completeness, Formatting).\n    4.  Passes only if the score is high and the reasoning is positive.\n\n### 2. Vertex AI Evaluation (Enterprise)\nFor more robust, metrics-based evaluation, we support the Vertex AI Evaluation Service. This step runs automatically in CI/CD if Google Cloud credentials are provided.\n\n*   **Usage:** `source .venv/bin/activate && python scripts/eval_vertex.py`\n*   **Requirements:**\n    1.  Google Cloud Project with **Vertex AI API** enabled.\n    2.  Service Account with `Vertex AI User` role.\n    3.  Python dependencies installed from `requirements.txt`.\n*   **Metrics:**\n    *   **Coherence:** Auto-rated by a model (Score 1-5).\n    *   **Safety:** Checked against safety filters.\n    *   **ROUGE:** Structural similarity against a \"Golden Reference\" (from `eval_dataset.jsonl`).\n*   **CI Configuration:**\n    *   Add `GCP_CREDENTIALS` (Service Account JSON Key) to GitHub Secrets.\n    *   Add `GEMINI_API_KEY` to GitHub Secrets.\n\n### 3. Golden Dataset\nWe maintain a \"Golden Dataset\" in `eval_dataset.jsonl` containing high-quality prompt/response pairs. This can be uploaded to the Vertex AI Console to run large-scale batch evaluations and track quality trends over time.\n",
  "bytes": 11578,
  "sha": "952a25e246aba184f05114d5f54a2372c472990a6345a327d82c4f85601f1664",
  "repo_slug": "sapientcoffee/scribe",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_sapientcoffee_scribe_fba9234f/readme"
}