{
  "markdown": "> [!WARNING]\n> **Demo/Illustrative Purpose Only**: This project is intended for inspiration and demonstration of AI-assisted development techniques. It should **not** be deployed to production environments without thorough testing, security audits, and validation. Use as a starting point for your own implementations.\n\n# ☕ Bean-to-Cup: The Autonomous Barista Swarm\n\n**Bean-to-Cup** is a comprehensive Gemini CLI extension designed to automate the entire Software Development Lifecycle (SDLC). It transforms the AI from a simple code generator into a structured **Autonomous Brewing Team** (Blueprint Forge) that follows a rigorous, multi-phase protocol to deliver high-quality, verified software.\n\n![The Brewing Swarm](docs/images/brewing-swarm.png)\n\nThis is a collection of AI-assisted development techniques, steps, and methods I have been experimenting with and building up over the last year. It is always evolving, and the space is evolving very quickly.\n\n---\n\n## 📖 Core Philosophy: \"The Perfect Brew\"\n\nJust as a master barista follows a precise recipe—from selecting the beans to the final pour—this extension treats software features as \"Brews.\" It enforces a strict **State Machine** based on the \"Document-as-Context\" architecture, where Markdown files act as the API for your AI agents.\n\n![The Control Funnel](docs/images/control-funnel.png)\n\nThis extension is a formal implementation of the **QRSPI method** (Questions, Research, Structure, Plan, Implement). This workflow combines the **RPI technique** (pioneered by **Dex Horthy** at HumanLayer) and the **Socratic Spec / AI-assisted product design** philosophies (pioneered by **Matt Pocock** at [AI Hero](https://www.aihero.dev/)). Together, these evolved into a state-of-the-art agentic pipeline protocol that ensures the human remains the \"director\" while the AI handles the \"execution.\" It is designed to prevent \"outsourcing thinking\" by creating high-fidelity checkpoints where you and the AI must align.\n\n### The AI-Native SDLC Stack\nThis extension implements emerging standards for AI-assisted development:\n\n![The Artifact Filter](docs/images/artifact-filter.png)\n\n| **Stage 0 (Optional)** | Product Discovery | `00_IDEATION.md`<br>`visual-dashboard.html` (Discovery Tab) | Formulate raw ideas, persona friction, and data schemas, publishing to visual Discovery tab. |\n| **Stage 1** | Socratic Alignment | `docs/glossary.md`<br>`visual-dashboard.html` (Glossary Tab) | Engage in Socratic interview, build global Ubiquitous Glossary and visual companion. |\n| **Stage 2** | Product Requirements | `02_PRD.md`<br>`visual-dashboard.html` (PRD Tab) | Establish requirements and Gherkin scenarios in markdown and visual HTML. |\n| **Stage 3** | Context Extraction | `03_EXTRACTION.md` | Factual codebase mapping (Blind Research). |\n| **Stage 4** | Technical Specification | `04_SPEC.md`<br>`visual-dashboard.html` (Spec Tab) | Design architecture and layout visual spec interface. |\n| **Stage 5** | Execution Planning | `05_PLAN.md`<br>`visual-dashboard.html` (Overview Tab) | Slices, TDD checklist, physical contracts, and interactive Kanban tracking. |\n| **Stage 6** | Human Review Gate | *None (Halt)* | STOP. Verify design contracts and visual specs before execution. |\n| **Stage 7** | Test-Driven Implementation | `07_VERIFICATION.md`<br>`visual-dashboard.html` (Overview Tab) | Incrementally execute code under TDD loop and track live progress on the Overview tab Kanban board. |\n| **Stage 8** | Automated Walkthrough | `08_WALKTHROUGH.md`<br>`visual-dashboard.html` (Recap Tab) | Visual/technical walkthroughs and visual recap report. |\n| **Stage 9** | PR Delivery & Maintenance | *PR Description* | Push branch, submit PR with walkthrough and recap reports. |\n\n---\n\n### 🛡️ Spec-Driven Development (SDD)\n\nTransitioning to SDD requires a shift in how you work with agents. If specifications are too long or vague, the agent will \"drift\" or experience context loss. This extension enforces these SDD tenets:\n\n#### A. Prioritize Human Reviewability\nThe \"fundamental test\" of a spec is whether a human can review it effectively. If a specification change is too long to review in 5 minutes, the feature is too large. We keep specifications concise and focused on intentionality.\n\n#### B. Solve the \"Lost in the Middle\" Problem\nLLMs often struggle with information buried in the middle of long documents. We keep `04_SPEC.md` and `05_PLAN.md` files modular and use **Plan Mode** guardrails to iterate in a read-only state before generating any code.\n\n#### C. Use \"Boundary Specs\" (What NOT to build)\nAgents are prone to \"over-implementing.\" Our artifacts explicitly list **Constraints** and **Non-Goals** (e.g., \"Do not upgrade existing dependencies\" or \"Do not add authentication logic\") to prevent scope drift.\n\n#### D. Agentic Validation (Evals)\nDon't just write tests; write Evals. In your `04_SPEC.md`, we define what \"Success\" looks like for the AI using measurable criteria (SLIs/SLOs), such as \"The generated API must have a response time < 100ms.\"\n\n#### E. Dual-Existence & Stage Handoff Protocol\nThe markdown files (`02_PRD.md`, `04_SPEC.md`, `05_PLAN.md`, `07_VERIFICATION.md`, and `08_WALKTHROUGH.md`) coexist perfectly with the consolidated `visual-dashboard.html` as the definitive, machine-parseable source of truth representing each stage. They are used directly by the test harness and model parsers as high-fidelity stage handoffs, ensuring full backward compatibility and automated parser interoperability.\n\n---\n\n### 📊 The Unified Master Visual Dashboard (`visual-dashboard.html`)\n\nA core innovation of Bean-to-Cup is the **Unified Master Visual Dashboard** (`visual-dashboard.html`). Created as a persistent visual artifact in your feature plan directory (`plans/<feature-slug>/<timestamp>/visual-dashboard.html`), it provides an interactive, rich UI dashboard that aggregates real-time insights across **all SDLC stages**:\n\n![Brew Overview & Interactive Kanban](docs/images/visual-dashboard-overview.png)\n\n*   **Discovery Tab (Stage 0)**: Displays raw ideation flows, target persona friction points, and mock data schemas.\n*   **Glossary & ADR Tab (Stage 1)**: Visualizes the global Ubiquitous Glossary terms and Architecture Decision Records (ADRs).\n*   **PRD Tab (Stage 2)**: Renders business requirements, Gherkin acceptance scenarios, and explicit non-goals.\n*   **Extraction Tab (Stage 3)**: Interactive codebase entrypoint maps, component trees, and architectural pattern findings.\n*   **Design Spec Tab (Stage 4)**: Renders Mermaid sequence diagrams, OpenAPI cards, ER schemas, and lo-fi wireframes.\n*   **Brew Overview / Interactive Kanban (Stages 5 & 7)**: Interactive Kanban board tracking vertical sprint slices and TDD task execution progress in real-time.\n*   **Recap Tab (Stage 8)**: Retrospective report, terminal recording playback, and walkthrough verification proof.\n\n![Technical Design Spec Tab](docs/images/visual-dashboard-spec.png)\n\n> [!TIP]\n> **Live Chat UI Panel Integration**:\n> Every stage update automatically mirrors `visual-dashboard.html` directly to the assistant's private system artifacts directory (`<appDataDir>/brain/<conversation-id>/00_visual-dashboard.html`), allowing you to view and inspect live feature progress in the side-panel artifact viewer without leaving the chat interface!\n>\n> 📖 **Deep Dive Documentation**:\n> Read our comprehensive **[Unified Master Visual Dashboard Guide](docs/VISUAL_DASHBOARD.md)** for a detailed technical discussion on how section markers, markdown-to-HTML rendering, dual-write brain artifact mirroring, and multi-stage lifecycle protocols operate under the hood.\n\n---\n\n## 🏗️ Architectural Overview\n\n### The 9-Phase Protocol (The State Machine)\nThe extension follows a rigorous 9-phase protocol to move from initial idea to a verified Pull Request.\n\n```mermaid\nflowchart TD\n    %% Style Classes Definition\n    classDef default fill:#f9f9f9,stroke:#333,stroke-width:2px,color:#333;\n    classDef stage fill:#ffffff,stroke:#4285F4,stroke-width:2.5px,color:#333,font-weight:bold;\n    classDef user fill:#eef2ff,stroke:#6366f1,stroke-width:2px,color:#312e81,font-weight:bold;\n    classDef component fill:#f0fdf4,stroke:#16a34a,stroke-width:2px,color:#14532d;\n    classDef artifact fill:#fffbeb,stroke:#d97706,stroke-width:2px,color:#78350f,font-style:italic;\n    classDef gate fill:#fef2f2,stroke:#dc2626,stroke-width:2.5px,color:#991b1b,font-weight:bold;\n\n    %% STAGE 0: PRODUCT DISCOVERY\n    subgraph S0 [\"Stage 0: Product Discovery (Optional)\"]\n        S0_Title[\"Stage 0: Discovery\"]:::stage\n        U0[\"User Types:<br>Brainstorm / request\"]:::user\n        I0[\"Input:<br>Initial Prompt\"]:::default\n        C0[\"Skill: ideator\"]:::component\n        A0[\"Output:<br>00_IDEATION.md\"]:::artifact\n        \n        U0 --> C0\n        I0 --> C0\n        C0 --> A0\n    end\n\n    %% STAGE 1: SOCRATIC ALIGNMENT\n    subgraph S1 [\"Stage 1: Socratic Alignment\"]\n        S1_Title[\"Stage 1: Socratic Alignment\"]:::stage\n        U1[\"User Types:<br>/feature goal<br>+ Answers Socratic Qs\"]:::user\n        I1[\"Input:<br>00_IDEATION.md (Optional)\"]:::artifact\n        C1[\"Skills: grill, grilling,<br>domain-modeling\"]:::component\n        A1[\"Output:<br>docs/glossary.md and<br>visual-dashboard.html (Glossary Tab)\"]:::artifact\n        \n        A0 -.-> I1\n        U1 --> C1\n        I1 --> C1\n        C1 --> A1\n    end\n\n    %% STAGE 2: PRODUCT REQUIREMENTS\n    subgraph S2 [\"Stage 2: Product Requirements\"]\n        S2_Title[\"Stage 2: Product Requirements\"]:::stage\n        U2[\"User Action:<br>Reviews PRD in chat UI\"]:::user\n        I2[\"Input:<br>docs/glossary.md and<br>visual-dashboard.html (Glossary Tab)\"]:::artifact\n        C2[\"Skill: write-prd\"]:::component\n        A2[\"Output:<br>02_PRD.md and<br>visual-dashboard.html (PRD Tab)\"]:::artifact\n        \n        A1 --> I2\n        U2 -.-> C2\n        I2 --> C2\n        C2 --> A2\n    end\n\n    %% STAGE 3: CONTEXT EXTRACTION\n    subgraph S3 [\"Stage 3: Context Extraction\"]\n        S3_Title[\"Stage 3: Context Extraction\"]:::stage\n        U3[\"User Action:<br>Approves PRD<br>(or types /research query)\"]:::user\n        I3[\"Input:<br>02_PRD.md / query\"]:::artifact\n        C3[\"Command: /research<br>- Skill: research<br>- Subagents: @scout,<br>@context-mapping,<br>@codebase-analyzer,<br>@pattern-recognition\"]:::component\n        A3[\"Output:<br>03_EXTRACTION.md<br>(Factual Code Map)\"]:::artifact\n        \n        A2 --> I3\n        U3 --> C3\n        I3 --> C3\n        C3 --> A3\n    end\n\n    %% STAGE 4 & 5: TECH SPEC & EXECUTION PLAN\n    subgraph S45 [\"Stages 4 and 5: Spec and Plan\"]\n        S45_Title[\"Stages 4 and 5: Spec and Plan\"]:::stage\n        U45[\"User Action:<br>None (Automated)\"]:::user\n        I45_1[\"Input 1:<br>02_PRD.md and<br>visual-dashboard.html (PRD Tab)\"]:::artifact\n        I45_2[\"Input 2:<br>03_EXTRACTION.md\"]:::artifact\n        C45[\"Subagent: @architect<br>(system-design.md)\"]:::component\n        A4[\"Output:<br>04_SPEC.md and<br>visual-dashboard.html (Spec Tab)\"]:::artifact\n        A5[\"Output:<br>05_PLAN.md (Checklist)\"]:::artifact\n        \n        A2 -.-> I45_1\n        A3 --> I45_2\n        I45_1 --> C45\n        I45_2 --> C45\n        C45 --> A4\n        C45 --> A5\n    end\n\n    %% STAGE 6: HUMAN GATE\n    subgraph S6 [\"Stage 6: Human Review Gate\"]\n        S6_Title[\"Stage 6: Human Gate\"]:::gate\n        U6[\"User Action:<br>Reviews 04_SPEC contracts<br>and types approve\"]:::user\n        I6_1[\"Input 1:<br>04_SPEC.md\"]:::artifact\n        I6_2[\"Input 2:<br>05_PLAN.md\"]:::artifact\n        \n        A4 --> I6_1\n        A5 --> I6_2\n        I6_1 --> U6\n        I6_2 --> U6\n    end\n\n    %% STAGE 7: TEST-DRIVEN IMPLEMENTATION\n    subgraph S7 [\"Stage 7: Test-Driven Implementation (TDD)\"]\n        S7_Title[\"Stage 7: TDD Loop\"]:::stage\n        U7[\"User Action:<br>Approves milestone commits<br>(Types yes / approve)\"]:::user\n        I7_1[\"Input 1:<br>04_SPEC.md (Contracts)\"]:::artifact\n        I7_2[\"Input 2:<br>05_PLAN.md (Checklist)\"]:::artifact\n        C7[\"Subagents: @engineer, @auditor,<br>@code-review<br>- Skills: generate-code, audit-code,<br>kanban, deploy-app<br>- Hook: lint-on-change.sh\"]:::component\n        A7[\"Outputs:<br>- Working verified code<br>- 07_VERIFICATION.md (Logs)<br>- visual-dashboard.html (Overview Tab)\"]:::artifact\n        \n        U6 -->|Approved| C7\n        A4 -.-> I7_1\n        A5 -.-> I7_2\n        I7_1 --> C7\n        I7_2 --> C7\n        U7 -.-> C7\n        C7 --> A7\n    end\n\n    %% STAGE 8: AUTOMATED WALKTHROUGH\n    subgraph S8 [\"Stage 8: Automated Walkthrough\"]\n        S8_Title[\"Stage 8: Walkthrough\"]:::stage\n        U8[\"User Types:<br>/record\"]:::user\n        I8_1[\"Input 1:<br>07_VERIFICATION.md\"]:::artifact\n        I8_2[\"Input 2:<br>walkthrough_scenario.json\"]:::default\n        C8[\"Command: /record<br>- Skill: asciinema\"]:::component\n        A8[\"Output:<br>08_WALKTHROUGH.md and<br>visual-dashboard.html (Recap Tab)\"]:::artifact\n        \n        A7 --> I8_1\n        U8 --> C8\n        I8_1 --> C8\n        I8_2 --> C8\n        C8 --> A8\n    end\n\n    %% STAGE 9: PR DELIVERY & MAINTENANCE\n    subgraph S9 [\"Stage 9: PR Delivery and Maintenance\"]\n        S9_Title[\"Stage 9: Delivery and PR\"]:::stage\n        U9[\"User Action:<br>Completes PR review<br>Optionally types:<br>/archive, /sync,<br>/worktree, /build:production\"]:::user\n        I9_1[\"Input 1:<br>Working code\"]:::artifact\n        I9_2[\"Input 2:<br>08_WALKTHROUGH.md and<br>visual-dashboard.html (Recap Tab)\"]:::artifact\n        C9[\"Skill: github-workflow<br>(creates PR via gh CLI)\"]:::component\n        A9[\"Output:<br>Active GitHub PR<br>and clean workspace\"]:::artifact\n        \n        A8 --> I9_2\n        U9 --> C9\n        I9_1 --> C9\n        I9_2 --> C9\n        C9 --> A9\n    end\n```\n\n### 1. The Head Barista (Supervisor) [CORE]\nThe heart of the extension is the `bean-to-cup.md` file. It acts as the **Head Barista** and **Guardian of the Protocol**. It ensures that \"Intent\" (PRD) is separated from \"Extraction\" (Research) to prevent bias.\n\n**Key Mandates:**\n*   **PRD over Specs:** Every feature starts with a machine-parsable `02_PRD.md` including **Non-Goals** and **SLIs/SLOs**.\n*   **UI/UX Alignment:** The Architect (@architect) explicitly searches for an existing `design.md` in your root to ensure UI/UX consistency.\n*   **SRE-Ready:** Requirements include initial telemetry and monitoring constraints for Day 2 operations.\n\n---\n\n## 🤖 The Brewing Swarm (Agents)\n\nThe Bean-to-Cup plugin manages an autonomous network of **9 active specialized sub-agents** in the `agents/` directory (plus **5 archived agents** in the holding pen). You can invoke active agents in your chat prompts using `@<name>`. For a detailed description of each agent's config file and target SDLC stage, see the [Swarm & Command Registry](docs/swarm-registry.md#-2-specialized-agents--swarm-13-total).\n\n| Agent | Role | Expertise & Focus | Status |\n| :--- | :--- | :--- | :--- |\n| **`@architect`** | The Planner | Strategic design patterns, `04_SPEC.md` specs, and `05_PLAN.md` roadmaps. | **CORE (Active)** |\n| **`@red-team-reviewer`** | The Red-Team Critic | Adversarial audits of PRDs, Specs, and Plans for missing edge cases & flaws. | **CORE (Active)** |\n| **`@engineer`** | The Builder | TDD implementation, Red-Green-Refactor, and production logic. | **CORE (Active)** |\n| **`@auditor`** | The Gatekeeper | Spec validation, regression checking, and QA cupping. | **CORE (Active)** |\n| **`@scout`** | The Investigator | Context-isolated codebase queries and raw context extraction. | **CORE (Active)** |\n| **`@browser_agent`** | The Browser | Automated browser walkthroughs and visual UI/UX verification. | **CORE (Active)** |\n| **`@codebase-analyzer`** | The Cartographer | Deep structural mapping and component tracing. | **CORE (Active)** |\n| **`@context-mapping`** | The Navigator | Entrypoint mapping and rapid workspace discovery. | **CORE (Active)** |\n| **`@pattern-recognition`** | The Librarian | Locating and mirroring existing architectural code patterns. | **CORE (Active)** |\n| **`@code-review`** | The Critic | Line-by-line quality reviews and static code smells analysis. | **CORE (Active)** |\n\n> [!NOTE]\n> **Archived Sentry & Tooling Agents (Holding Pen):**\n> The following agents have been safely moved to `holding-pen/agents/` to keep the active workspace clean and efficient:\n> - `@security-auditor`, `@security-remediator`, `@vulnerability-scanner` (Sentry group)\n> - `@msbuild` (Compiler)\n> - `@pipeline-stages` (CI/CD)\n\n---\n\n## ⌨️ Custom Commands\n\nThe plugin implements **12 active Custom Commands** mapped as flat namespace TOML declarations in the `commands/` directory.\n\n### Core Lifecycle\n*   **`/feature <goal>`** [CORE]: Initiates the 9-phase protocol starting with an AI-Ready PRD and versioned workspace setup.\n*   **`/rewrite <args>`** [CORE]: Initiates an application rewrite workflow (Stages 0-5) by analyzing assessments and coordinating specialized skills.\n*   **`/research <query>`** [CORE]: Spawns parallel agents for deep, factual context-isolated codebase extraction.\n\n### Workspace Management & Testing\n*   **`/push <args>`** [CORE]: Delivers code changes to Git following modern best practices, including linting, conventional commits, and rich PR descriptions.\n*   **`/init`** [CORE] *(Deprecated)*: Legacy command to bootstrap your project. This setup is now handled automatically.\n*   **`/archive`** [CORE]: Clears away 'spent grounds' (completed tasks) to keep context clean.\n*   **`/record`** [CORE]: Launches terminal recording and playback scenario capture.\n*   **`/sync`** [CORE]: Synchronizes active branch and plans with upstream repo states.\n*   **`/worktree`** [CORE]: Manages clean, isolated branch checkouts for development.\n*   **`/dev <task>`** [CORE]: General-purpose development helper for quick, minor inline requests.\n*   **`/test:api`** [CORE]: Specialized endpoint testing and compliance checks.\n*   **`/build:production`** [CORE]: Packages, compiles, and builds production release artifacts.\n\n> [!NOTE]\n> **Archived Pipeline & Loop Commands (Holding Pen):**\n> The following commands have been safely archived to the `holding-pen/commands/` directory to prevent workspace clutter:\n> - `/loop:start`, `/loop:cancel`, `/loop:help` (Legacy loop control)\n> - `/sql:analyze` (Legacy database schema extraction)\n> - `/ddd:*` commands: `/ddd:logical`, `/ddd:physical`, `/ddd:plan`, `/ddd:implement`, `/ddd:review`, `/ddd:fix`, `/ddd:create-user-stories` (Legacy refactoring pipeline)\n> - `/startcycle` (Legacy cycle manager)\n\n---\n\n## 🛠️ Reusable Skills & Hooks\n\nEach modular skill in the `skills/` directory complies with the open **Agent Skills specification**, enabling deep reuse. For the complete skill-to-stage mappings and execution scripts, see the [Swarm & Command Registry](docs/swarm-registry.md#-3-modular-skills-13-total).\n\n### Skills\n*   **`ideator`** [CORE]: **Stage 0 (Optional)**: Generates a product discovery and technical architecture draft from any raw product idea, feature request, or prompt, writing the results to `00_IDEATION.md`.\n*   **`grill`** [CORE]: **Stage 1**: Relentless interactive interview, requirements stress-testing, glossary update (`docs/glossary.md`), ADRs (`docs/adr/`), and `visual-dashboard.html` synchronization.\n*   **`grilling`** [DEPRECATED]: Replaced by the Stage 1 `grill` skill.\n*   **`domain-modeling`** [CORE]: **Stage 1, 4 & 5**: Builds, refines, and maintains the ubiquitous glossary and domain models.\n*   **`write-prd`** [CORE]: **Stage 2**: Standardizes requirements, non-goals, and KPIs into a machine-parsable `02_PRD.md`.\n*   **`rewrite`** [CORE]: **Stage 1 & 2**: Orchestrates a legacy application rewrite workflow by analyzing modernization assessments and coordinating specialized skills.\n*   **`research`** [CORE]: **Stage 3**: Guides context-isolated codebase extraction into factual `03_EXTRACTION.md`.\n*   **`audit-code`** [CORE]: **Stage 7**: Runs architectural compliance checks, QA gates, and executes minor commits.\n*   **`generate-code`** [CORE]: **Stage 7**: Generates boilerplate and components according to Spec contracts.\n*   **`kanban`** [CORE]: **Stage 7**: Progress tracking (HTML & Mermaid visualizer) for vertical sprint slices.\n*   **`chaos-mitigation`** [CORE]: **Stage 7**: Handles SRE log inspection and runs automated mitigation playbooks.\n*   **`visual-dashboard`** [CORE]: **Universal (Stages 0–8)**: Central authority to instantiate, preserve, update, and mirror `visual-dashboard.html` across all stages to the assistant's private system artifacts directory.\n*   **`github-workflow`** [CORE]: **Stage 9**: Automates branch pushes and PR compilation with the GitHub CLI (`gh`).\n*   **`git-delivery`** [CORE]: **Stage 9**: Provides an emoji-powered, best-practice delivery pipeline to verify, stage, commit, and raise high-quality \"What, Why, How\" PRs.\n\n### Automated Hooks\n*   **`lint-on-change`** [CORE]: Automatically runs your linter whenever a file is modified.\n*   **`coffee-and-git`** [CORE]: Provides a coffee tip and git history at session start.\n*   **`git-status`** [CORE]: Keeps your current branch and workspace state visible.\n\n---\n\n## 🧪 Testing & Verification\n\nDeveloping and maintaining an autonomous swarm requires a resilient testing protocol. We have established a comprehensive **5-layer isolation and behavioral testing suite** located in the [`tests/`](file:///home/robedwards/workspace/bean-to-cup/tests) directory that operates entirely locally and independently of external dependencies.\n\n### 📋 The Automated Test Suite (`tests/`)\n\n*   **[`test_skills_schema.py`](file:///home/robedwards/workspace/bean-to-cup/tests/test_skills_schema.py)**: Validates YAML frontmatter, name, and schema compliance across all 25 skills.\n*   **[`test_hooks_and_scripts.py`](file:///home/robedwards/workspace/bean-to-cup/tests/test_hooks_and_scripts.py)**: Verifies script execution and context injection for all lifecycle hooks (`hooks/*.sh`).\n*   **[`test_manage_dashboard.py`](file:///home/robedwards/workspace/bean-to-cup/tests/test_manage_dashboard.py)**: Tests deterministic `visual-dashboard.html` updates (`auto-sync`, `sync-glossary`, `sync-prd`, `sync-spec`, `sync-plan`, `sync-verification`, `sync-recap`).\n*   **[`test_sdlc_headless_e2e.py`](file:///home/robedwards/workspace/bean-to-cup/tests/test_sdlc_headless_e2e.py)**: Headless end-to-end simulation harness that populates stage markdown artifacts across Stages 0 through 8, invokes all stage skills, and verifies 100% full-fidelity content parity in `visual-dashboard.html`.\n\n### 🏃 Running the Test Suite locally\n\nRun all automated unit and E2E simulation tests in standard Python:\n\n```bash\npython3 -m unittest discover -s tests\n```\n\n*   **Isolated Testing Strategy Guide**: See our detailed **[Isolated Testing & Verification Strategy Guide](docs/testing_and_verification.md)** to learn how we isolate workspace states, mock stage inputs, execute deterministic validation gates, and run pseudo-terminal simulations.\n*   **End-to-End Audit Evidence**: View our live **[End-to-End Testing & Evaluation Report](docs/test_report.md)** which showcases real test execution traces, negative/positive gating checks, and a full behavior audit.\n\n### Why this is set up:\n*   **Deterministic Safety**: Catches AI-specific failures like bracket placeholder leaks (`[TODO]`), missing licenses, or broken markdown structures.\n*   **Behavioral Assurance**: Programmatic transcript checking ensures subagents (such as `@architect` or `@engineer`) are spawned with exact arguments and that tools execute error-free.\n*   **Extreme Velocity**: Input mocking allows testing late stages (like Stage 7 TDD or Stage 8 Walkthrough) in a lightweight sandbox in seconds without running full interactive sessions.\n\n---\n\n## 🚀 Installation & Quickstart\n\nThis repository is **multi-compatible**: it functions seamlessly as a modern **Antigravity Plugin**, a standard **Agent Skills Package** via the `skills` CLI, and a legacy **Gemini CLI Extension**. \n\nYou can use whichever harness or tool matches your workflow; they will coexist peacefully using their respective manifest files (`plugin.json` and `gemini-extension.json`) and standard layouts.\n\n---\n\n### Option A: Running as an Antigravity Plugin (Modern)\n\nAntigravity natively scans your active workspace or user home directory to discover plugins and registers all included subagents, skills, and rules automatically.\n\nWe provide an automated, dependency-free Bash installer script (`install.sh`) at the root of the repository to set up the plugin.\n\n#### 1. One-Line Installation (No local clone required)\nIf you are on a new machine and don't have the repository cloned locally, you can stream the installer directly via `curl` to clone and register the plugin in one step:\n\n*   **Global-Level Installation** (Active across all of your projects):\n    ```bash\n    curl -sSL https://raw.githubusercontent.com/sapientcoffee/bean-to-cup/main/install.sh | bash\n    ```\n*   **Workspace-Level Installation** (Active only in the current workspace directory):\n    ```bash\n    curl -sSL https://raw.githubusercontent.com/sapientcoffee/bean-to-cup/main/install.sh | bash -s -- --workspace\n    ```\n\n#### 2. Local Clone Installation (Symlinked for Active Development)\nIf you are actively developing the plugin, or already have a local clone of this repository, run the installer script from the root of your clone. This creates a **symlink** to your development directory:\n\n*   **Global Symlink** (Registers your local clone for all projects):\n    ```bash\n    ./install.sh\n    ```\n*   **Workspace-Level Symlink** (Registers your local clone inside the current project):\n    ```bash\n    ./install.sh --workspace\n    ```\n\n#### 3. How to Update the Plugin (`git pull`)\nUpdates are clean and simple depending on how the plugin was installed:\n\n*   **If installed via Local Symlink (Development)**:\n    Just run `git pull` inside your local clone. Since the plugin directory is symlinked, Antigravity picks up changes instantly.\n*   **If installed via One-Line Curl (Direct Clones)**:\n    The installer clones the real Git repository directly into the target location. You can fetch updates by navigating into that directory and pulling:\n    ```bash\n    cd ~/.gemini/skills/bean-to-cup\n    git pull\n    ```\n\n#### 4. Verify Discovery\nStart your Antigravity session. The platform automatically scans `plugin.json` and loads the custom skills and subagents:\n*   View your active agents by listing them in your developer panel (or using the `/agents` helper).\n*   Any skills inside the `skills/` directory (like `audit-code` or `github-workflow`) are instantly accessible to your active agent.\n\n---\n\n### Option B: Running as a Gemini CLI Extension (Legacy)\n\n#### 1. Install the Extension\nYou can install or link the extension directly using the Gemini CLI.\n\n**Via GitHub (Recommended):**\n```bash\ngemini extensions install https://github.com/sapientcoffee/bean-to-cup.git\n```\n\n**Via Local Path (For Development):**\n```bash\n# Clone the repository\ngit clone https://github.com/sapientcoffee/bean-to-cup.git\n\n# Link the extension\ngemini extensions link ./bean-to-cup\n```\n\n#### 2. Initialize your Workspace (Deprecated)\n> [!NOTE]\n> This step is deprecated under Antigravity 2.0. Workspace bootstrapping is now managed automatically upon plugin registration.\n>\n> If running on legacy Gemini CLI, you can still optionally run:\n> ```bash\n> /init\n> ```\n\n#### 3. Start your first Brew\nBegin the 9-phase protocol for a new feature:\n```bash\n/feature \"Add a search bar to the coffee bean catalog\"\n```\n\n---\n\n### Option C: Installing Individual Skills via the Open Skills CLI (Universal)\n\nEach capability inside our `skills/` directory complies with the open **Agent Skills specification** designed by Vercel Labs. This means you can install, manage, and use these skills across **over 40 supported local coding agents** (including Claude Code, Cursor, Windsurf, Roo Code, and more) using the universal `skills` CLI.\n\n#### 1. List Available Skills in this Repository\nYou can query this repository directly using the `skills` CLI to see all discovered modular capabilities:\n```bash\nnpx skills add sapientcoffee/bean-to-cup --list\n```\n\n#### 2. Install a Specific Skill\nTo add an individual skill (such as our high-performance code auditor) to your current project:\n```bash\nnpx skills add sapientcoffee/bean-to-cup --skill audit-code\n```\n\n#### 3. Install All Skills Globally\nTo make the entire suite of `bean-to-cup` skills available globally across all of your local AI coding agents:\n```bash\nnpx skills add sapientcoffee/bean-to-cup -g\n```\n\n---\n\n**Credits**: [@dandobrin](https://github.com/dandobrin), [@jjdelorme](https://github.com/jjdelorme), [@cedricyao](https://github.com/cedricyao), [Dex Horthy](https://x.com/dexhorthy), [Matt Pocock](https://www.aihero.dev/).\n\n*Created with ❤️ for demo/example purposes only.*\n",
  "bytes": 28844,
  "sha": "b048d12e4ca98aa9721ead8de4f714aabe4106e13c5090d4a3b75d1e6848eeda",
  "repo_slug": "sapientcoffee/bean-to-cup",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_sapientcoffee_bean_to_cup_dcec31a2/readme"
}