{
  "markdown": "# Beads Workflow\n\nA high-stakes engineering workflow extension for the Gemini CLI, powered by **Beads** (issue tracking) and **Obsidian** (architectural planning).\n\nThis extension enforces a rigorous \"Planning First\" philosophy, ensuring that every line of code is backed by an architectural record and every lesson learned is compounded into permanent knowledge.\n\n## Core Mandates\n\n1.  **Beads is Truth**: Never work without an active ticket. Synchronize your session with `bd ready` or `bd prime`.\n2.  **Obsidian is Memory**: Implementation plans and architectural records live in Obsidian. Use `/analyze` to generate them.\n3.  **Atomic Execution**: Follow the `/implement` phases strictly. Commit after every phase.\n4.  **Compound Knowledge**: Use `/compound` after every task to capture patterns and traps in your Obsidian vault.\n\n## Slash Commands\n\n| Command | Description |\n| :--- | :--- |\n| `/idd` | Refines fuzzy ideas into Intent-Driven Development (IDD) artifacts and Intent-driven Beads. |\n| `/accessibility [target]` | Audits and improves web accessibility following WCAG 2.1 guidelines (full WCAG audit with remediation code). |\n| `/adr [title]` | Interactive session to write an Architectural Decision Record (ADR). |\n| `/analyze <id>` | Fetches a ticket from Beads and generates a detailed implementation plan in Obsidian. |\n| `/bugfix <id>` | Diagnoses and fixes bugs using hypothesis-driven debugging. |\n| `/review [target]` | Performs comprehensive code review with security, performance, and maintainability focus. |\n| `/commit [focus]` | Analyzes changes and creates atomic commits with conventional messages. |\n| `/compound <id>` | Transmutes implementation lessons into permanent knowledge artifacts. |\n| `/implement <id>` | Executes a plan from Obsidian, following phased gates and atomic commits. |\n| `/rams [file]` | Runs an expert accessibility and visual design review (quick design + a11y review with severity scoring). |\n| `/refactor [target]` | Analyzes code and suggests refactoring opportunities with blast radius assessment. |\n| `/refine <id>` | Refines an epic or story through cross-functional analysis and requirements gathering. |\n| `/release` | Authors release notes, changelogs, and creates signed release tags. |\n\n## Specialized Agents\n\nThe extension includes a library of specialized \"Specialist\" agents that handle high-stakes gates:\n\n*   **Principal Engineer**: For complex architectural decisions and deep debugging.\n*   **Software Architect**: Owns the `/analyze` output and architectural validation.\n*   **Security Engineer**: Performs OWASP-aligned security reviews.\n*   **SDET / QA Engineer**: Handles unit testing and exploratory browser testing.\n*   **Agile Delivery Lead**: Owns the `/refine` process.\n*   **SRE Engineer**: Manages reliability, SLOs, and infrastructure.\n\n## Prerequisites\n\nThis extension requires the following tools to be installed and configured:\n\n1.  **Beads CLI**: The git-backed issue tracker used for state management.\n2.  **Obsidian MCP Server**: Required for architectural planning and knowledge compounding.\n3.  **Git**: For version control and atomic commits.\n\n## Installation\n\nInstall the extension directly via the Gemini CLI:\n\n```bash\ngemini extensions install https://github.com/thoreinstein/beads-workflow.git\n```\n\n## Workflow Lifecycle\n\n1.  **IDD Refinement**: Use `/idd` to transform a fuzzy \"Idea\" into a \"Product\" (Epic) and \"Intentions\" (Features). This establishes the **Chain of Context**.\n2.  **Plan**: Use `/analyze` to create the architectural record in Obsidian. Every plan must include **Expectations** and **Boundaries**.\n3.  **Execute**: Use `/implement` to build the feature, following the atomic commit cycle.\n4.  **Audit**: Use `/rams` for design quality and `/review` for logic gates.\n5.  **Compound**: Use `/compound` to ensure the team learns from the implementation.\n6.  **Release**: Use `/release` to prepare the artifacts for production.\n\n## Configuration\n\nThe extension uses the following environment variables:\n\n*   `OBSIDIAN_VAULT_PATH`: (Required) The absolute path to your Obsidian vault.\n*   `BEADS_PLAN_DIR`: (Optional) The base directory within your Obsidian vault for project artifacts. Defaults to `working`. Plans are stored at `<BEADS_PLAN_DIR>/<project-name>/plans/`.\n*   `BEADS_PROJECT_NAME`: (Optional) The project name used for Obsidian vault paths. Defaults to the current directory name.\n\nEnsure these are set in your shell profile or provided to the Gemini CLI.\n\n## Hooks\n\nThe extension includes automated guardrail hooks that enforce workflow discipline:\n\n| Hook | Event | Purpose |\n| :--- | :--- | :--- |\n| `obsidian-guardrail` | BeforeTool | Blocks local writes to `.md` files (except `GEMINI.md`). Enforces the rule that planning and documentation artifacts must be stored in Obsidian. |\n| `session-context` | SessionStart | Provides workflow context at session start and reminds you to sync with Beads via `bd ready` or `bd prime`. |\n| `compound-reminder` | SessionEnd | Checks if tickets were marked done without running `/compound` and reminds you to capture lessons learned. |\n\nHook scripts are located in the `hooks/` directory and configured via `hooks/hooks.json`.\n",
  "bytes": 5201,
  "sha": "c4f4af3105d2c5b95b24478e1009340019810e2ce1623461aa95eafe78a4d290",
  "repo_slug": "thoreinstein/beads-workflow",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_thoreinstein_beads_workflow_cfca04a0/readme"
}