{
  "markdown": "# Root\n\nDevelopment workflow framework for Claude Code and Gemini CLI.\n\nRoot provides **tier-based planning**, **doc-aware context gathering**, **RAG-powered search**, **multi-feature orchestration**, and **autonomous issue-to-PR workflows**.\n\n## Install\n\n### For Claude Code\n\n**1. Add the Marketplace**\n\n```\n/plugin marketplace add BrandCast-Signage/root\n```\n\n**2. Install the Plugin**\n\n```\n/plugin install root@root-plugins --scope local\n/reload-plugins\n```\n\n### For Gemini CLI\n\n**1. Install the Extension**\n\n```bash\ngemini extension install https://github.com/BrandCast-Signage/root\n```\n\n---\n\nThe extension auto-installs its RAG MCP server on first session start.\n\n### Initialize Your Project\n\n```\n/root:init\n```\n\nThis 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.\n\n## Commands\n\n| Command | Description |\n|---------|-------------|\n| `/root <task>` | Start a development session, or continue one. Context gathering, planning, and phase-aware orchestration in a single command. |\n| `/root <verb>` | Orchestration verbs: `list`, `status`, `approve`, `run`, `sync`, `delete`, `clean`, `reset` |\n| `/root:init` | Interactive project setup |\n| `/root:prd [action]` | PRD authoring: `new`, `edit`, `review`, `list` |\n| `/root:impl [action]` | Execute a plan: `run`, `resume`, `status`, `finalize` |\n| `/root:explore [action]` | RAG-powered codebase exploration: `topic`, `flow`, `map` |\n| `/root:rag [action]` | Manage RAG database: `status`, `ingest`, `refresh`, `clear`, `config`, `scan` |\n| `/root:docs [action]` | Documentation management: `health`, `search`, `stale`, `scan`, `validate`, `fix`, `create` |\n\n## Usage\n\n### Orchestration (v2.2)\n\n`/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.\n\n```\n/root #42                         # Create stream, classify tier, plan. Stops at plan approval.\n/root #42                         # (after approving) Dispatches /root:impl, drives to PR-ready.\n/root #58                         # Start a second stream — each gets its own worktree\n\n/root list                        # View all active streams\n/root status #42                  # Detailed status for one stream\n/root approve #42                 # Green-light a Tier 1 plan AND continue execution\n/root run                         # If one active stream, resume it; else prompt\n/root sync                        # Sync local state with GitHub labels\n/root delete #42                  # Abandon a stream and tear down its worktree\n/root clean                       # Tear down merged worktrees\n```\n\n**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.\n\nStreams 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.\n\n### Core Workflow\n\n```\n/root #1132                      # Start session from a GitHub issue\n/root #1132 webhook flaky on retries  # Issue + in-the-moment color\n/root 1234                       # Bare number also works\n/root reset                      # Clear completed streams\n\n/root:prd new #1234              # Guided PRD creation from an issue\n/root:prd review auth-refresh    # Quality review of a PRD\n/root:prd list                   # List all PRDs in the project\n\n/root:impl                       # Execute the approved plan\n/root:impl status                # Check implementation progress\n/root:impl resume                # Pick up where you left off\n\n/root:explore topic auth         # Explore a topic across the codebase\n/root:explore flow login         # Trace a flow end-to-end\n/root:explore map                # Map the codebase architecture\n\n/root:rag status                # Check RAG database state\n/root:rag refresh               # Re-ingest all docs after major changes\n/root:rag scan                  # Discover new directories to index\n\n/root:docs health               # Dashboard of doc coverage and freshness\n/root:docs search oauth         # Find docs about a topic\n/root:docs stale                # Find outdated documentation\n/root:docs scan                 # Find undocumented code, triage, generate docs\n/root:docs create src/services/auth.ts  # Generate a doc from source code\n/root:docs validate             # Check frontmatter across all docs\n/root:docs fix                  # Auto-add missing frontmatter\n```\n\n### What Root Does\n\n1. **Parses** your task (extracts issue number, description)\n2. **Fetches** GitHub issue context (title, labels, body)\n3. **Classifies** as Tier 1 (full process) or Tier 2 (light process)\n4. **Loads** relevant docs via RAG semantic search\n5. **Recommends** specialist agents based on config mappings\n6. **Tracks** your session (files edited, docs read, board stream state)\n7. **Drives planning**:\n   - **Tier 1**: Guided PRD → Implementation Plan with Change Manifest, Dependency Graph, Execution Groups, and Verification Plan\n   - **Tier 2**: Uses built-in plan mode for lightweight planning\n8. **Executes** via `/root:impl` — parallel agents across Execution Groups, validation checkpoints, test generation, doc creation, and commit/PR\n9. **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.\n\n### Two-Tier Workflow\n\n| | Tier 1 (Full Process) | Tier 2 (Light Process) |\n|---|---|---|\n| **When** | New features, large refactors, multi-package changes | Bug fixes, small changes, config updates |\n| **Planning** | Guided PRD → Implementation Plan → Human review | Built-in plan mode (ephemeral) |\n| **Artifacts** | Persistent plan in `<plansDir>/` | Commit message + PR |\n| **Traceability** | Change Manifest → PRD requirements | GitHub issue/PR linkage |\n\n### Autonomous Multi-Issue Mode (2.4+)\n\nBeyond single-issue autonomy, Root can drive an entire **epic** or a **batch** of unrelated tier-2 issues to a single PR:\n\n```\n/root #<epic-issue> --auto              # Run every linked sub-issue under an epic\n/root #x #y #z --auto --batch           # Run an explicit list of unrelated issues\n```\n\n**Epic mode** resolves children via GitHub's sub-issues link, runs them in declared order on a `feat/epic-<n>-<slug>` branch, and assembles a single PR with `Closes #x` for each child.\n\n**Batch mode** takes an explicit issue list, requires every member to classify as tier-2, runs them on a `chore/batch-<n>-<slug>` branch, and produces one PR. Any tier-1 sneak-in is a hard stop.\n\nBoth modes share a per-run **shared-context** file at `.root/streams/<parent>/shared-context.md` that subagents append to as they work — this is what protects the run against the orchestrator's auto-compaction.\n\n#### Readiness gate\n\nBefore any autonomous run starts, every involved issue is graded by the `issue-readiness-grader` agent against a strict rubric (goal stated, scope bounded, solvability, touchpoints clear, no blocking deps, tier-honest). Any `needs-clarification` verdict triggers an **interactive interview**: Root asks the human concrete questions, applies the answers to the issue body via `gh issue edit`, and re-grades. There is no `--force` to bypass this — closing the readiness gap IS the work, not an obstacle to skip. The interview caps at 3 rounds; round 4 is a hard stop.\n\n#### Partial PRs\n\nIf a child fails mid-run, completed children stay on the branch and ship in a partial PR (kept draft). The PR body marks the partial completion clearly. The user can re-run the unfinished children later with a fresh `/root #<remaining> --auto` invocation.\n\n#### Notifications\n\nConfigure a Discord webhook to get pinged when the autonomous run hits a human gate, blocker, or completion (see *Notifications* below). Without a webhook configured, autonomous mode still works — you just have to watch the shell.\n\n### Documentation Onboarding\n\nFor projects with incomplete or missing documentation:\n\n```\n/root:docs health     # See the current state\n/root:docs fix        # Repair/add frontmatter on existing docs\n/root:docs scan       # Discover undocumented code → triage → generate docs\n/root:docs health     # See the improvement\n```\n\nThe `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.\n\n### Frontmatter\n\nRoot workflows depend on frontmatter in `.md` files for health tracking, freshness detection, and validation. Required fields:\n\n```yaml\n---\ntitle: Authentication Service\ntype: service\nstatus: active\ncreated: 2025-08-15\nupdated: 2026-03-10\n---\n```\n\n| Field | Values |\n|-------|--------|\n| `title` | Non-empty string |\n| `type` | `doc`, `plan`, `prd`, `adr`, `pattern`, `guide`, `spec`, `research`, `service`, `api`, `package`, `module` |\n| `status` | Type-scoped — see table below |\n| `created` | `YYYY-MM-DD` |\n| `updated` | `YYYY-MM-DD` (must be >= `created`, no future dates) |\n\nValid `status:` values depend on the doc's `type:`, so ADRs, patterns, and research notes can keep their conventional vocabularies instead of being forced onto the lifecycle set:\n\n| Type(s) | Valid `status:` values |\n|---------|------------------------|\n| `plan`, `prd` | `draft`, `active`, `completed`, `deferred`, `cancelled`, `superseded`, `archived` |\n| `adr` | `proposed`, `accepted`, `rejected`, `deprecated`, `superseded` |\n| `pattern` | `investigating`, `draft`, `decided`, `active`, `deprecated`, `superseded`, `archived` |\n| `research` | `draft`, `active`, `archived` |\n| `doc`, `guide`, `spec`, `service`, `api`, `package`, `module` | `draft`, `active`, `deprecated`, `archived` |\n| _unknown / missing type_ | default: `draft`, `active`, `completed`, `deferred`, `cancelled`, `superseded`, `archived` |\n\nA write-time hook warns when `.md` files in doc directories are saved without valid frontmatter.\n\n## Templates\n\nRoot installs two templates during `/root:init`:\n\n**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.\n\n**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.\n\n## Agents\n\nRoot includes 8 agent templates organized into team roles and specialist roles.\n\n### Team Roles\n\n| Agent | Model | Mode | Purpose |\n|-------|-------|------|---------|\n| `team-architect` | Opus | Read-only, plan mode | Designs implementation plans with change manifests and dependency graphs |\n| `team-implementer` | Sonnet | Full read/write | Executes plan tasks, follows patterns, validates before completing |\n| `team-reviewer` | Sonnet | Read + checks | Reviews code against plan and coding standards |\n| `team-tester` | Sonnet | Test creation | Writes and validates tests, ensures coverage |\n\n### Specialist Roles\n\n| Agent | Focus Areas |\n|-------|-------------|\n| `specialist-backend` | API routing, auth, middleware, database queries, integrations |\n| `specialist-frontend` | Components, state management, design system, forms, client routing |\n| `specialist-database` | Schema design, ORM, migrations, indexes, data integrity |\n| `specialist-devops` | CI/CD, containers, environments, secrets, monitoring, deployments |\n\nSpecialist agents are templates — customize their expertise areas and key references per project.\n\n## Hooks\n\n| Hook | Event | Purpose |\n|------|-------|---------|\n| `ensure-mcp.sh` | Session start | Auto-installs RAG + board MCP servers, checks `gh` auth, auto-ingests if DB is empty |\n| `track-edits.sh` | After file write/edit | Tracks edited files in session state, warns on missing frontmatter |\n| `track-doc-reads.sh` | After file read | Tracks doc reads in session state |\n| `context-receipt.sh` | Session end | Outputs session summary (tier, issue, files, docs) |\n| `doc-update-check.sh` | Session end | Reminds to update docs when Tier 1 source was edited |\n\n## Configuration\n\n`root.config.json` in your project root:\n\n```json\n{\n  \"project\": {\n    \"name\": \"my-project\",\n    \"docsDir\": \"docs\",\n    \"plansDir\": \"docs/plans\",\n    \"prdsDir\": \"docs/prds\"\n  },\n  \"ingest\": {\n    \"dbPath\": \".root/rag-db\",\n    \"docs\": [\"docs/\"]\n  },\n  \"docMappings\": [\n    { \"pattern\": \"AUTH|OAUTH\", \"agents\": [\"specialist-backend\"], \"skills\": [] }\n  ],\n  \"labelMappings\": [\n    { \"label\": \"area:frontend\", \"agents\": [\"specialist-frontend\"] }\n  ],\n  \"keywordMappings\": [\n    { \"keywords\": [\"schema\", \"migration\", \"database\"], \"agents\": [\"specialist-database\"] }\n  ],\n  \"docTargets\": [\n    { \"glob\": \"packages/*/src/index.ts\", \"type\": \"package\", \"docsDir\": \"docs/packages\" },\n    { \"glob\": \"apps/*/src/services/*.ts\", \"type\": \"service\", \"docsDir\": \"docs/services\" }\n  ],\n  \"codingStandards\": [\n    \"All exports have JSDoc\",\n    \"No `any` types\"\n  ],\n  \"validation\": {\n    \"lintCommand\": \"npm run lint && npm run type-check\",\n    \"testCommand\": \"npm test -- <pattern>\"\n  },\n  \"board\": {\n    \"gates\": {\n      \"plan_approval\": { \"tier1\": \"human\", \"tier2\": \"auto\" },\n      \"reviewer_pass\": \"auto\",\n      \"validation\": \"auto\",\n      \"pr_creation\": \"auto\"\n    },\n    \"maxParallel\": 3\n  }\n}\n```\n\n### Mapping Types\n\nRoot uses three mapping types to recommend agents for a task:\n\n- **docMappings**: Regex against loaded doc paths → agents/skills\n- **labelMappings**: GitHub issue labels → agents\n- **keywordMappings**: Keywords in task description → agents\n\n### docTargets (optional)\n\nOverride 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.\n\n### Board Gates\n\nThe `board.gates` section controls which transitions require human approval:\n\n| Gate | Default | Purpose |\n|------|---------|---------|\n| `plan_approval` | `tier1: human, tier2: auto` | Whether plans need human review before implementation |\n| `reviewer_pass` | `auto` | Whether code review gates auto-advance |\n| `validation` | `auto` | Whether lint/type/test validation auto-advances |\n| `pr_creation` | `auto` | Whether PR creation is automatic |\n\nSet any gate to `\"human\"` to always pause, `\"auto\"` to always advance, or use `{ \"tier1\": \"human\", \"tier2\": \"auto\" }` for tier-specific behavior.\n\n### Notifications\n\nWhen `notifications.discord` is configured AND the `ROOT_DISCORD_WEBHOOK_URL` environment variable is set, Root posts color-coded Discord embeds for autonomous-mode signaling.\n\n```json\n\"notifications\": {\n  \"discord\": {\n    \"enabled\": true,\n    \"events\": [\"blocker\", \"human_gate\", \"pr_ready\", \"epic_complete\"],\n    \"mention\": null\n  }\n}\n```\n\n**Webhook URL is never stored in any committed file.** Set it via environment:\n\n```bash\nexport ROOT_DISCORD_WEBHOOK_URL=\"https://discord.com/api/webhooks/...\"\n```\n\nThe four events:\n\n| Event | Color | When |\n|---|---|---|\n| `blocker` | red | A run is parked on a hard failure (failed readiness after 3 rounds, classifier disagreement, repeated test failure, shared-context overflow) |\n| `human_gate` | amber | Waiting for explicit human approval (Tier 1 plan, etc.) |\n| `pr_ready` | blue | A PR has been opened/updated; review needed |\n| `epic_complete` | green | Every child of an epic / batch run completed; PR is ready to flip to non-draft |\n\nSet `mention` to a role/user mention string (`<@&role-id>` or `<@user-id>`) to ping on `blocker` events. Other events never @-mention regardless of config.\n\nIf the section is absent, `enabled: false`, or the env var is unset, notifications are silently off — Root works as if the feature didn't exist.\n\n**Verify the webhook works:**\n```bash\ncurl -X POST -H 'Content-Type: application/json' \\\n  -d '{\"content\":\"root webhook smoke test\"}' \\\n  \"$ROOT_DISCORD_WEBHOOK_URL\"\n```\n\n### GitHub Project sync\n\nWhen `board.githubProject` is set, `board_start` flips the linked Project v2 item's Status field to \"In Progress\" and applies the configured mirror label on the issue. Other Project transitions (auto-add to Backlog, PR-linked → Review, item-closed → Done) are handled by Project v2's native workflows; only Backlog/Ready → In Progress requires Root to write.\n\n```json\n\"board\": {\n  \"githubProject\": {\n    \"projectId\": \"PVT_…\",\n    \"statusFieldId\": \"PVTSSF_…\",\n    \"statusOptions\": { \"inProgress\": \"<option-id>\" },\n    \"mirrorLabel\": \"status:in-progress\"\n  }\n}\n```\n\nIf the section is absent, the feature is off — `board_start` works exactly as before. Failures (gh not authenticated, stale field IDs, GraphQL errors) are non-fatal: the work stream is real, the Project mirror is a nice-to-have.\n\n**Looking up the node IDs** — run once per project, paste into config:\n\n```bash\n# Project ID + status field ID + option IDs\ngh api graphql -f query='\n  query($org:String!,$num:Int!){\n    organization(login:$org){\n      projectV2(number:$num){\n        id\n        field(name:\"Status\"){\n          ... on ProjectV2SingleSelectField {\n            id\n            options { id name }\n          }\n        }\n      }\n    }\n  }' -f org=<org> -F num=<project-number>\n```\n\n## Components\n\n| Component | Type | Purpose |\n|-----------|------|---------|\n| `root` | Skill | Workflow entry point — context + planning |\n| `mcp-local-rag` | Skill | RAG query/ingest guidance |\n| `mcp-root-board` | MCP Server | Stream orchestration backend — state machine, worktree lifecycle, GitHub integration, gates. Driven directly by `/root`. |\n| `root:init` | Command | Interactive project setup |\n| `root:prd` | Command | Guided PRD authoring (4 subcommands) |\n| `root:impl` | Command | Plan execution with parallel agents (4 subcommands) |\n| `root:explore` | Command | RAG-powered codebase exploration (3 subcommands) |\n| `root:rag` | Command | RAG database management (6 subcommands) |\n| `root:docs` | Command | Documentation management (7 subcommands) |\n| Session hooks | Hooks | Track edits, doc reads, frontmatter enforcement, context receipts |\n| Agent templates | Agents | Team (architect/implementer/reviewer/tester) + specialist (backend/frontend/database/devops) |\n| Model rubric | Reference | When to use Opus vs Sonnet, Claude vs Gemini per workflow phase |\n| Plan template | Template | Tier 1 implementation plan structure |\n| PRD template | Template | Product requirements document structure |\n\n## Updating\n\n### Claude Code\n\n```\n/plugin marketplace update root-plugins\n/plugin update root@root-plugins --scope local\n/reload-plugins\n```\n\n### Gemini CLI\n\n```bash\ngemini extension update root\n```\n\n## Cross-Harness Support\n\nRoot works with both Claude Code and Gemini CLI. The board orchestration layer enables them to work on the same project simultaneously:\n\n- Each execution group within a feature can be assigned to a different harness\n- Claude handles Group A in one worktree, Gemini handles Group B in another\n- Both read/write the same board state (`.root/board/`) — no conflicts on different streams\n- The model rubric (`skills/root/MODEL_RUBRIC.md`) guides when to use which model and harness\n\n### Prerequisites\n\n- **`gh` CLI**: Required for board GitHub features (labels, comments, PRs). Install: https://cli.github.com\n- Run `gh auth login` before using board commands\n- If `gh` is not authenticated, board still works locally — GitHub features are skipped gracefully\n\n## Known Limitations\n\n**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`.\n\n## License\n\n[MIT](LICENSE)\n\n## Family\n\nRoot is part of the BrandCast agent family:\n- **Chip** — AI chat assistant\n- **Twig** — AI styling assistant\n- **Bark** — Infrastructure & environment management plugin\n- **Root** — Development workflow framework\n",
  "bytes": 20557,
  "sha": "e4cf5ad6dbea4d6c8d98c7aa51be306da4fcd71eb03439519bb460f24688612c",
  "repo_slug": "brandcast-signage/root",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_brandcast_signage_root_c9fd452c/readme"
}