root

Root

Development workflow framework for Claude Code and Gemini CLI.

Root provides tier-based planning, doc-aware context gathering, RAG-powered search, multi-feature orchestration, and autonomous issue-to-PR workflows.

Install

For Claude Code

1. Add the Marketplace

/plugin marketplace add BrandCast-Signage/root

2. Install the Plugin

/plugin install root@root-plugins --scope local
/reload-plugins

For Gemini CLI

1. Install the Extension

gemini extension install https://github.com/BrandCast-Signage/root

---

The extension auto-installs its RAG MCP server on first session start.

Initialize Your Project

/root:init

This interactively detects your project structure, asks which directories contain docs and source code, generates root.config.json, installs templates, and ingests your docs into RAG.

Commands

Command	Description
/root <task>	Start a development session, or continue one. Context gathering, planning, and phase-aware orchestration in a single command.
/root <verb>	Orchestration verbs: list, status, approve, run, sync, delete, clean, reset
/root:init	Interactive project setup
/root:prd [action]	PRD authoring: new, edit, review, list
/root:impl [action]	Execute a plan: run, resume, status, finalize
/root:explore [action]	RAG-powered codebase exploration: topic, flow, map
/root:rag [action]	Manage RAG database: status, ingest, refresh, clear, config, scan
/root:docs [action]	Documentation management: health, search, stale, scan, validate, fix, create

Usage

Orchestration (v2.2)

/root IS the orchestrator. Running /root #<issue> creates a stream on first invocation and advances it on every subsequent invocation — re-running is the universal "continue" gesture.

/root #42                         # Create stream, classify tier, plan. Stops at plan approval.
/root #42                         # (after approving) Dispatches /root:impl, drives to PR-ready.
/root #58                         # Start a second stream — each gets its own worktree

/root list                        # View all active streams
/root status #42                  # Detailed status for one stream
/root approve #42                 # Green-light a Tier 1 plan AND continue execution
/root run                         # If one active stream, resume it; else prompt
/root sync                        # Sync local state with GitHub labels
/root delete #42                  # Abandon a stream and tear down its worktree
/root clean                       # Tear down merged worktrees

How it works: Each stream progresses through a state machine (queued → planning → plan-ready → approved → implementing → validating → pr-ready → merged). Gates at each transition determine whether to auto-advance or pause for human approval. Tier 2 work (bug fixes) runs fully autonomously to PR. Tier 1 work pauses once for plan approval, then runs autonomously.

Streams are tracked locally in .root/board/ and reflected on GitHub issues via labels (root:planning, root:plan-ready, root:approved, root:implementing, root:pr-ready). Approve from anywhere — CLI, GitHub UI, or your phone.

Core Workflow

/root #1132                      # Start session from a GitHub issue
/root #1132 webhook flaky on retries  # Issue + in-the-moment color
/root 1234                       # Bare number also works
/root reset                      # Clear completed streams

/root:prd new #1234              # Guided PRD creation from an issue
/root:prd review auth-refresh    # Quality review of a PRD
/root:prd list                   # List all PRDs in the project

/root:impl                       # Execute the approved plan
/root:impl status                # Check implementation progress
/root:impl resume                # Pick up where you left off

/root:explore topic auth         # Explore a topic across the codebase
/root:explore flow login         # Trace a flow end-to-end
/root:explore map                # Map the codebase architecture

/root:rag status                # Check RAG database state
/root:rag refresh               # Re-ingest all docs after major changes
/root:rag scan                  # Discover new directories to index

/root:docs health               # Dashboard of doc coverage and freshness
/root:docs search oauth         # Find docs about a topic
/root:docs stale                # Find outdated documentation
/root:docs scan                 # Find undocumented code, triage, generate docs
/root:docs create src/services/auth.ts  # Generate a doc from source code
/root:docs validate             # Check frontmatter across all docs
/root:docs fix                  # Auto-add missing frontmatter

What Root Does