root-plugins

Root

Development workflow framework for Claude Code and Gemini CLI.

Root provides tier-based planning, doc-aware context gathering, RAG-powered search, session tracking, and implementation plan generation.

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 — context gathering + planning
/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:rag [action]	Manage RAG database: status, ingest, refresh, clear, config, scan
/root:docs [action]	Documentation management: health, search, stale, scan, validate, fix, create

Usage

/root fix issue 1132      # Start session from a GitHub issue
/root new auth system      # Start session from a description
/root #1234                # Shorthand for issue number
/root reset                # Clear current session

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

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)
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. Or creates issues — one GitHub issue per Execution Group with linked requirements and cross-references

Two-Tier Workflow

	Tier 1 (Full Process)	Tier 2 (Light Process)
When	New features, large refactors, multi-package changes	Bug fixes, small changes, config updates
Planning	Guided PRD → Implementation Plan → Human review	Built-in plan mode (ephemeral)
Artifacts	Persistent plan in <plansDir>/	Commit message + PR
Traceability	Change Manifest → PRD requirements	GitHub issue/PR linkage

Documentation Onboarding

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.

Frontmatter

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