A high-stakes engineering workflow extension for the Gemini CLI, powered by Beads (issue tracking) and Obsidian (architectural planning).
This 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.
- Beads is Truth: Never work without an active ticket. Synchronize your session with
bd readyorbd prime. - Obsidian is Memory: Implementation plans and architectural records live in Obsidian. Use
/analyzeto generate them. - Atomic Execution: Follow the
/implementphases strictly. Commit after every phase. - Compound Knowledge: Use
/compoundafter every task to capture patterns and traps in your Obsidian vault.
| Command | Description |
|---|---|
/accessibility [target] |
Audits and improves web accessibility following WCAG 2.1 guidelines (full WCAG audit with remediation code). |
/adr [title] |
Interactive session to write an Architectural Decision Record (ADR). |
/analyze <id> |
Fetches a ticket from Beads and generates a detailed implementation plan in Obsidian. |
/bugfix <id> |
Diagnoses and fixes bugs using hypothesis-driven debugging. |
/review [target] |
Performs comprehensive code review with security, performance, and maintainability focus. |
/commit [focus] |
Analyzes changes and creates atomic commits with conventional messages. |
/compound <id> |
Transmutes implementation lessons into permanent knowledge artifacts. |
/implement <id> |
Executes a plan from Obsidian, following phased gates and atomic commits. |
/rams [file] |
Runs an expert accessibility and visual design review (quick design + a11y review with severity scoring). |
/refactor [target] |
Analyzes code and suggests refactoring opportunities with blast radius assessment. |
/refine <id> |
Refines an epic or story through cross-functional analysis and requirements gathering. |
/release |
Authors release notes, changelogs, and creates signed release tags. |
The extension includes a library of specialized "Specialist" agents that handle high-stakes gates:
- Principal Engineer: For complex architectural decisions and deep debugging.
- Software Architect: Owns the
/analyzeoutput and architectural validation. - Security Engineer: Performs OWASP-aligned security reviews.
- SDET / QA Engineer: Handles unit testing and exploratory browser testing.
- Agile Delivery Lead: Owns the
/refineprocess. - SRE Engineer: Manages reliability, SLOs, and infrastructure.
This extension requires the following tools to be installed and configured:
- Beads CLI: The git-backed issue tracker used for state management.
- Obsidian MCP Server: Required for architectural planning and knowledge compounding.
- Git: For version control and atomic commits.
Install the extension directly via the Gemini CLI:
gemini extensions install https://github.com/thoreinstein/beads-workflow.git- Refine: Use
/refineto establish the scope in Beads. - Plan: Use
/analyzeto create the architectural record in Obsidian. - Execute: Use
/implementto build the feature, following the atomic commit cycle. - Audit: Use
/ramsfor design quality and/reviewfor logic gates. - Compound: Use
/compoundto ensure the team learns from the implementation. - Release: Use
/releaseto prepare the artifacts for production.
The extension uses the following environment variables:
OBSIDIAN_VAULT_PATH: (Required) The absolute path to your Obsidian vault.BEADS_PLAN_DIR: (Optional) The base directory within your Obsidian vault for project artifacts. Defaults toworking. Plans are stored at<BEADS_PLAN_DIR>/<project-name>/plans/.BEADS_PROJECT_NAME: (Optional) The project name used for Obsidian vault paths. Defaults to the current directory name.
Ensure these are set in your shell profile or provided to the Gemini CLI.
The extension includes automated guardrail hooks that enforce workflow discipline:
| Hook | Event | Purpose |
|---|---|---|
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. |
session-context |
SessionStart | Provides workflow context at session start and reminds you to sync with Beads via bd ready or bd prime. |
compound-reminder |
SessionEnd | Checks if tickets were marked done without running /compound and reminds you to capture lessons learned. |
Hook scripts are located in the hooks/ directory and configured via hooks/hooks.json.