beads-workflow
A high-stakes engineering workflow powered by Beads (issue tracking) and Obsidian (planning).
Open source Open in the app JSON README (API)
About
A high-stakes engineering workflow powered by Beads (issue tracking) and Obsidian (planning).
Details
- Kind
- Plugins
- Topic
- Productivity
- Publisher
- thoreinstein
- Origin
- gemini
- Category
- ferramentas
- Version
- 1.9.0
- Stars
- 10
- Forks
- 1
- Last push
- 2026-03-21T21:27:43Z
- Repository state
- ativo
- Language
- Shell
- Added
- 2026-08-30 14:13:39
- Updated
- 2026-08-30 14:13:39
- Origin id
thoreinstein/beads-workflow
README
# Beads Workflow 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. ## Core Mandates 1. **Beads is Truth**: Never work without an active ticket. Synchronize your session with `bd ready` or `bd prime`. 2. **Obsidian is Memory**: Implementation plans and architectural records live in Obsidian. Use `/analyze` to generate them. 3. **Atomic Execution**: Follow the `/implement` phases strictly. Commit after every phase. 4. **Compound Knowledge**: Use `/compound` after every task to capture patterns and traps in your Obsidian vault. ## Slash Commands | Command | Description | | :--- | :--- | | `/idd` | Refines fuzzy ideas into Intent-Driven Development (IDD) artifacts and Intent-driven Beads. | | `/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. | ## Specialized Agents 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 `/analyze` output 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 `/refine` process. * **SRE Engineer**: Manages reliability, SLOs, and infrastructure. ## Prerequisites This extension requires the following tools to be installed and configured: 1. **Beads CLI**: The git-backed issue tracker used for state management. 2. **Obsidian MCP Server**: Required for architectural planning and knowledge compounding. 3. **Git**: For version control and atomic commits. ## Installation Install the extension directly via the Gemini CLI: ```bash gemini extensions install https://github.com/thoreinstein/beads-workflow.git ``` ## Workflow Lifecycle 1. **IDD Refinement**: Use `/idd` to transform a fuzzy "Idea" into a "Product" (Epic) and "Intentions" (Features). This establishes the **Chain of Context**. 2. **Plan**: Use `/analyze` to create the architectural record in Obsidian. Every plan must include **Expectations** and **Boundaries**. 3. **Execute**: Use `/implement` to build the feature, following the atomic commit cycle. 4. **Audit**: Use `/rams` for design quality and `/review` for logic gates. 5. **Compound**: Use `/compound` to ensure the team learns from the implementation. 6. **Release**: Use `/release` to prepare the artifacts for production. ## Configuration 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 to `working`. 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. ## Hooks 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`.