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.

1. Add the Marketplace

/plugin marketplace add BrandCast-Signage/root

2. Install the Plugin

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

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.

/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.

/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.

/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

1. Parses your task (extracts issue number, description)
2. Fetches GitHub issue context (title, labels, body)
3. Classifies as Tier 1 (full process) or Tier 2 (light process)
4. Loads relevant docs via RAG semantic search
5. Recommends specialist agents based on config mappings
6. Tracks your session (files edited, docs read, board stream state)
7. Drives planning:
   • Tier 1: Guided PRD → Implementation Plan with Change Manifest, Dependency Graph, Execution Groups, and Verification Plan
   • Tier 2: Uses built-in plan mode for lightweight planning
8. Executes via /root:impl — parallel agents across Execution Groups, validation checkpoints, test generation, doc creation, and commit/PR
9. Orchestrates — every re-invocation of /root #<issue> advances the stream through its next gate. Tier 2 runs fully autonomously to PR. Tier 1 pauses once for plan approval, then runs autonomously.

For projects with incomplete or missing documentation:

/root:docs health     # See the current state
/root:docs fix        # Repair/add frontmatter on existing docs
/root:docs scan       # Discover undocumented code → triage → generate docs
/root:docs health     # See the improvement

The scan command runs as a single interactive pipeline: it discovers undocumented code components using heuristics (or docTargets config), presents them grouped by priority for triage, and generates first-draft docs with proper frontmatter for selected items.

Root workflows depend on frontmatter in .md files for health tracking, freshness detection, and validation. Required fields:

---
title: Authentication Service
type: service
status: active
created: 2025-08-15
updated: 2026-03-10
---

A write-time hook warns when .md files in doc directories are saved without valid frontmatter.

Root installs two templates during /root:init:

Implementation Plan (<plansDir>/TEMPLATE.md) — Used by Tier 1 planning. Includes Context, Scope, Requirements Traceability, Change Manifest (numbered files with req linkage), Dependency Graph (Mermaid), Execution Groups, Coding Standards Compliance, Risk Register, and Verification Plan.

PRD (<prdsDir>/TEMPLATE.md) — Product Requirements Document. Required before Tier 1 implementation. Includes Problem Statement, Goals/Non-Goals, Functional Requirements (P0/P1/P2 with REQ IDs), Technical Considerations, Risks, and Success Metrics.

Root includes 8 agent templates organized into team roles and specialist roles.

Specialist agents are templates — customize their expertise areas and key references per project.

root.config.json in your project root:

{
  "project": {
    "name": "my-project",
    "docsDir": "docs",
    "plansDir": "docs/plans",
    "prdsDir": "docs/prds"
  },
  "ingest": {
    "dbPath": ".root/rag-db",
    "docs": ["docs/"]
  },
  "docMappings": [
    { "pattern": "AUTH|OAUTH", "agents": ["specialist-backend"], "skills": [] }
  ],
  "labelMappings": [
    { "label": "area:frontend", "agents": ["specialist-frontend"] }
  ],
  "keywordMappings": [
    { "keywords": ["schema", "migration", "database"], "agents": ["specialist-database"] }
  ],
  "docTargets": [
    { "glob": "packages/*/src/index.ts", "type": "package", "docsDir": "docs/packages" },
    { "glob": "apps/*/src/services/*.ts", "type": "service", "docsDir": "docs/services" }
  ],
  "codingStandards": [
    "All exports have JSDoc",
    "No `any` types"
  ],
  "validation": {
    "lintCommand": "npm run lint && npm run type-check",
    "testCommand": "npm test -- <pattern>"
  },
  "board": {
    "gates": {
      "plan_approval": { "tier1": "human", "tier2": "auto" },
      "reviewer_pass": "auto",
      "validation": "auto",
      "pr_creation": "auto"
    },
    "maxParallel": 3
  }
}

Root uses three mapping types to recommend agents for a task:

• docMappings: Regex against loaded doc paths → agents/skills
• labelMappings: GitHub issue labels → agents
• keywordMappings: Keywords in task description → agents

Override default heuristics for /root:docs scan. Each entry maps a glob pattern to a doc type and output directory. When present, scan uses these instead of built-in heuristics.

The board.gates section controls which transitions require human approval:

Set any gate to "human" to always pause, "auto" to always advance, or use { "tier1": "human", "tier2": "auto" } for tier-specific behavior.

/plugin marketplace update root-plugins
/plugin update root@root-plugins --scope local
/reload-plugins

gemini extension update root

Root works with both Claude Code and Gemini CLI. The board orchestration layer enables them to work on the same project simultaneously:

• Each execution group within a feature can be assigned to a different harness
• Claude handles Group A in one worktree, Gemini handles Group B in another
• Both read/write the same board state (.root/board/) — no conflicts on different streams
• The model rubric (skills/root/MODEL_RUBRIC.md) guides when to use which model and harness

• gh CLI: Required for board GitHub features (labels, comments, PRs). Install: https://cli.github.com
• Run gh auth login before using board commands
• If gh is not authenticated, board still works locally — GitHub features are skipped gracefully

Board MCP required: The mcp-root-board MCP server must be available for session tracking. It is auto-installed by the ensure-mcp.sh session-start hook. Session state is stored per-issue at .root/board/<issue>.json.

MIT

Root is part of the BrandCast agent family:

• Chip — AI chat assistant
• Twig — AI styling assistant
• Bark — Infrastructure & environment management plugin
• Root — Development workflow framework