beth-copilot 1.1.0 → 2.1.0

package/CHANGELOG.md

@@ -6,6 +6,56 @@ All notable changes to Beth are documented here. Format based on [Keep a Changel
 
 ---
 
+## [Unreleased]
+
+## [2.1.0] - 2026-03-16
+
+### Added
+- **`npx beth-copilot uninstall` command** — Cleanly removes all Beth-installed files from a project: `.github/agents/`, `.github/skills/`, `.github/hooks/`, `AGENTS.md`, `Backlog.md`, `.github/copilot-instructions.md`, `.vscode/settings.json`, `mcp.json.example`, and `backlog/` directory. Removes Beth guard block from pre-push hook (preserving non-Beth content). Cleans up empty `.github/` and `.vscode/` directories. 17 tests covering all removal paths.
+- **Auto-derived backlog prefix** — `backlog init` during `beth-copilot init` now automatically derives a 6-letter prefix from the project name (e.g., `my-app` → `MYAPP`), eliminating the interactive prompt that blocked agent workflows.
+
+### Fixed
+- **Shell command injection in backlog init** — Fixed GHAS-flagged command injection vulnerability where unsanitized project directory names were interpolated into shell commands. Now validates input against a strict allowlist pattern before use.
+
+### Changed
+- **885 tests** — Up from 860 in v2.0.0. Added uninstall command tests and init prefix derivation coverage.
+
+## [2.0.0] - 2026-03-16
+
+### Breaking Changes
+- **Beads removed — Backlog.md is the sole task tracker.** The entire beads/Dolt database layer has been removed. All agent instructions, hooks, and CLI commands now use `backlog` CLI exclusively. If you were using `bd` commands in scripts, they will no longer be referenced by Beth agents.
+- **`npx beth-copilot close` command removed** (~560 lines deleted). This command enforced beads-specific close logic (blocker deps, child issues, mandatory test subtasks via `bd`). The workflow is now handled by `backlog task edit BETH-X -s "Done" --plain`.
+
+### Added
+- **Backlog.md CLI integration** — All agent instructions now reference `backlog task create`, `backlog task edit`, `backlog task list`, `backlog board`, and `backlog overview` commands. The `--plain` flag is enforced everywhere to prevent TUI mode in agent contexts.
+- **`npx beth-copilot update` command** — Updates project files to latest templates without full re-init. Supports `--check-only` for dry-run inspection.
+- **Behavioral skill tests** — 302 E2E skill routing tests across 3 files validating deterministic hook injection, trigger coverage, and mapping completeness.
+- **SubagentStart/SubagentStop hook enforcement** — `inject-skills.mjs` deterministically maps agent types to required skills. `verify-skills.mjs` gates subagent completion on both skill compliance and task tracking.
+- **Hub-and-spoke agent coordination** — Replaced 15 lateral handoffs across 6 agents with single "Escalate to Beth" handoff per agent. All agents now report to Beth.
+- **Community skills** — Added brainstorming, framer-components, frontend-design, proof, rclone, feature-video, and other community-contributed skill modules.
+- **27+ Azure skills** — Full Azure skill suite: compute, storage, AI, messaging, diagnostics, compliance, RBAC, cost optimization, cloud migration, resource lookup/visualizer, Entra ID, Copilot SDK, Foundry, and more.
+- **860 tests** — Up from 438 in v1.1.0. Comprehensive coverage for CLI commands, skill routing, hook injection, pipeline integration, and path validation.
+
+### Changed
+- **Agent instructions rewritten for Backlog.md** — All 7 agent files (`beth.agent.md`, `developer.agent.md`, etc.) and `AGENTS.md` updated to reference `backlog` CLI instead of `bd` commands.
+- **Hook enforcement updated** — `verify-skills.mjs` now checks for `backlog task edit` compliance instead of `bd` commands.
+- **Templates synced** — All template files in `templates/` now match live `.github/` configuration.
+- **Test framework consolidated** — Migrated from mixed `node:test`/vitest to vitest-only imports across all test files.
+
+### Removed
+- **`beth-copilot close` command** — Entire close command and its 560-line implementation deleted.
+- **Beads stub functions** — Removed `bd`-related stubs from `bin/cli.js`.
+- **Dead code cleanup** — Removed 8 redundant/deprecated skills, unused `bs-buster` dependency, dead `bin/lib` files, legacy test scripts, empty barrel exports, and orphaned documentation.
+- **Dolt/beads references** — Purged from all production source code, agent instructions, templates, and documentation.
+
+### Fixed
+- **Template drift** — Templates now stay in sync with live `.github/` config via the `update` command.
+- **Duplicate tools in beth.agent.md** — Removed duplicate tool entries in frontmatter.
+- **Dead pathValidation.ts exports** — Cleaned unused exports that inflated the public API surface.
+- **Pre-push guard test isolation** — Removed unused `child_process` mock that caused CI failures.
+
+---
+
 ## [1.1.0] - 2026-03-10
 
 ### Added
@@ -13,7 +63,7 @@ All notable changes to Beth are documented here. Format based on [Keep a Changel
 - **`npx beth-copilot close` enforcement** — 3-layer close enforcement: (1) open blocker dependencies via `bd dep list`, (2) open children via `bd children`, (3) mandatory test subtasks (unit/e2e/security) for epics. `--force` bypasses all checks.
 - **Pre-push hook** — Git pre-push hook enforcing branch discipline: blocks pushes from `main`/`master` (exit 1), warns on non-epic branch names. Pure shell hook (no Node overhead). Auto-installed during `npx beth-copilot init`. Bypass with `BETH_SKIP_PUSH_GUARD=1`.
 - **Quality gate infrastructure** — `npm run test:gate` generates markdown test reports to `docs/test-reports/`. `scripts/quality-gate.mjs` runs vitest + legacy tests, parses results, generates report, exits non-zero on failure.
-- **Comprehensive CLI test suite** — 7 new test files: `close.e2e.test.ts`, `pre-push-guard.e2e.test.ts`, `quickstart-expanded.e2e.test.ts`, `cli-edge-cases.e2e.test.ts`, `framework-isolation.test.ts`, `init-logic.e2e.test.ts`, `doctor.e2e.test.ts`. 438 tests total (up from 485).
+- **Comprehensive CLI test suite** — 7 new test files: `close.e2e.test.ts`, `pre-push-guard.e2e.test.ts`, `quickstart-expanded.e2e.test.ts`, `cli-edge-cases.e2e.test.ts`, `framework-isolation.test.ts`, `init-logic.e2e.test.ts`, `doctor.e2e.test.ts`. 438 tests total.
 - **Doctor: Dolt database hygiene** — `checkDoltDatabases()` detects orphaned `*test*` databases and warns when user DB count exceeds threshold. Extracted `parseDoltDatabases()` with 18 unit tests.
 - **Session startup drift-prevention** — Mandatory 4-step session startup checklist in AGENTS.md: check uncommitted changes, unpushed commits, spot-check closed work, sync beads state.
 - **Beads disaster recovery docs** — `docs/BD-BACKUP-PARSER-FAILURE.md` with exact parser error, root cause, repro steps, and 3 recovery paths.

package/README.md

@@ -21,12 +21,12 @@ She commands seven specialized agents, each with their own expertise, tools, and
 | Layer | What It Does | Status |
 |-------|-------------|--------|
 | **Copilot Agents** | `.agent.md` definitions running in VS Code Agent Mode | Live |
-| **CLI Toolchain** | `beth init`, `beth doctor`, `beth quickstart` — TypeScript commands | Live |
+| **CLI Toolchain** | `beth init`, `beth doctor`, `beth land`, `beth update` — TypeScript commands | Live |
 | **Orchestration Engine** | Fan-out routing, tool calling loop, subagent spawning, handoffs | Live |
-| **Tool Abstraction** | 6 CLI tools + MCP bridge — uniform interface for all agent capabilities | Live |
+| **Agent Tools** | Copilot built-ins (codebase, readFile, editFiles, runSubagent) + optional MCP servers | Live |
 | **LLM Provider** | Azure OpenAI with Entra ID auth, streaming, retry, tool calling | Live |
 
-**814 tests.** 813 pass, 1 skip, 0 fail.
+**860 tests.** All passing.
 
 ---
 
@@ -55,11 +55,11 @@ flowchart LR
 | **LLM Provider** | Azure OpenAI via `openai` SDK | Entra ID auth (no API keys), streaming + tool calling |
 | **Auth** | `@azure/identity` DefaultAzureCredential | az login, managed identity, VS Code creds |
 | **Frontmatter** | `gray-matter` | Parses `.agent.md` and `SKILL.md` YAML |
-| **Testing** | Node.js built-in test runner | 814 tests — unit, integration, E2E |
-| **Task Tracking** | beads (`bd` CLI) | Dependency-aware issue tracking for agents |
-| **Package Manager** | pnpm | Lockfile committed |
+| **Testing** | vitest | 860 tests — unit, integration, E2E |
+| **Task Tracking** | Backlog.md (`backlog` CLI) | Markdown-based task tracking for agents and humans |
+| **Package Manager** | npm | Lockfile committed |
 
-**Production dependencies:** 1 (`gray-matter`). That's it. Minimal attack surface by design.
+**Production dependencies:** 1 (`gray-matter`). Minimal attack surface by design.
 
 ---
 
@@ -80,8 +80,8 @@ Then open VS Code, switch Copilot Chat to **Agent mode**, and type `@Beth`.
 
 **Verify everything works:**
 ```bash
-beth doctor       # Health check: Node.js, beads, agents, skills
-beth quickstart   # Init + doctor + beads setup in one shot
+beth doctor       # Health check: Node.js, agents, skills
+beth quickstart   # Init + doctor in one shot
 ```
 
 For detailed setup (prerequisites, task tracking, MCP servers): [docs/INSTALLATION.md](docs/INSTALLATION.md)
@@ -92,19 +92,21 @@ For detailed setup (prerequisites, task tracking, MCP servers): [docs/INSTALLATI
 
 | Command | What It Does |
 |---------|-------------|
-| `beth init` | Install agents, skills, VS Code settings, beads tracking |
+| `beth init` | Install agents, skills, VS Code settings, Backlog.md tracking, pre-push hook |
 | `beth init --force` | Overwrite existing files |
-| `beth doctor` | Validate Node.js ≥18, beads CLI, agents frontmatter, skills directories |
-| `beth quickstart` | Run init + doctor + beads init in one shot |
+| `beth doctor` | Validate Node.js ≥18, agents frontmatter, skills |
+| `beth quickstart` | Run init + doctor in one shot |
+| `beth land` | Automate session completion: tests, commit, push, verify sync |
+| `beth update` | Update project files to latest templates without full re-init |
 | `beth help` | Show all commands and options |
 
-**Flags:** `--force`, `--skip-backlog`, `--skip-mcp`, `--skip-beads`, `--verbose`
+**Flags:** `--force`, `--skip-backlog`, `--skip-mcp`, `--verbose`, `--skip-tests`, `--message/-m`, `--dry-run`, `--check-only`
 
 ---
 
 ## Agent Orchestration
 
-Beth doesn't micromanage. She delegates to specialists over **subagent** and **handoff** channels, tracks dependencies with beads, and holds every agent accountable.
+Beth doesn't micromanage. She delegates to specialists over **subagent** and **handoff** channels, tracks work in Backlog.md, and holds every agent accountable.
 
 ### The Family
 
@@ -118,17 +120,23 @@ Beth doesn't micromanage. She delegates to specialists over **subagent** and **h
 | **@tester** | The Enforcer | Quality assurance, accessibility, performance |
 | **@security-reviewer** | The Bodyguard | OWASP, compliance, threat modeling |
 
-### Delegation Model
+### Delegation Model (Hub-and-Spoke)
 
 ```mermaid
 flowchart LR
     Beth["@Beth"] -->|subagent| PM["PM"] & UX["UX"] & Dev["Dev"] & Sec["Sec"] & Test["Test"] & Res["Research"]
-    PM -.->|handoff| UX & Dev
-    Dev -.->|handoff| Test & UX
+    PM -.->|escalate| Beth
+    UX -.->|escalate| Beth
+    Dev -.->|escalate| Beth
+    Sec -.->|escalate| Beth
+    Test -.->|escalate| Beth
+    Res -.->|escalate| Beth
 
     style Beth fill:#1e3a5f,color:#fff
 ```
 
+All agents escalate exclusively to Beth — no lateral handoffs. Beth routes, agents execute.
+
 ### Subagent vs Handoff
 
 | Mechanism | Control | Use When |
@@ -216,24 +224,37 @@ Full details: [docs/MCP-SETUP.md](docs/MCP-SETUP.md)
 
 ## Skills (On-Demand Knowledge)
 
-Skills are domain-knowledge modules that agents load automatically when trigger phrases match. Each skill lives in `.github/skills/<name>/SKILL.md`.
+Skills are domain-knowledge modules that agents load automatically when trigger phrases match. Each skill lives in `.github/skills/<name>/SKILL.md` or `.github/prompts/<name>/PROMPT.md`.
 
 | Skill | Triggers On | Used By |
 |-------|------------|---------|
 | **PRD Generation** | "create a prd", "product requirements" | Product Manager |
-| **Framer Components** | "framer component", "property controls" | UX Designer |
+| **UI UX Pro Max** | "design system", "color palette", "style guide" | UX Designer, Developer |
+| **Web Design Guidelines** | "review my UI", "check accessibility" | UX Designer, Tester |
+| **Framer Components** | "framer component", "property controls" | UX Designer, Developer |
 | **React/Next.js Best Practices** | React performance, Next.js patterns | Developer |
-| **Web Design Guidelines** | "review my UI", "check accessibility" | UX Designer |
 | **shadcn/ui** | "shadcn", "ui component" | Developer |
 | **Security Analysis** | "security review", "OWASP", "threat model" | Security Reviewer |
-| **Azure Operations** | Azure resource management | Developer |
+| **Azure Operations** | Azure resource management (27+ Azure skills) | Developer |
 | **Web Search** | Internet research via Brave | Researcher |
 
+### Design & UI Skills
+
+Three complementary skills cover the full design-to-code pipeline. They don't overlap — each solves a different problem.
+
+| Skill | What It Does | When You Need It |
+|-------|-------------|------------------|
+| **[UI UX Pro Max](https://github.com/nextlevelbuilder/ui-ux-pro-max-skill)** | Design system generator — picks styles, colors, typography, and layout patterns from a searchable database of 67 styles, 161 color palettes, 57 font pairings, and 161 industry-specific reasoning rules. | Starting a new project or page. "What should this look like?" |
+| **Web Design Guidelines** | Code auditor — fetches live [Vercel Web Interface Guidelines](https://github.com/vercel-labs/web-interface-guidelines) and checks your actual files for accessibility, focus, form, and performance violations with `file:line` output. | Reviewing implemented code. "Is this built correctly?" |
+| **Framer Components** | Framer platform SDK reference — `addPropertyControls`, `ControlType`, code overrides, `RenderTarget`, auto-sizing, and Framer Motion integration. | Building custom components inside Framer. "How do I make this work in Framer?" |
+
+**Typical flow:** UI UX Pro Max generates the design system → Developer builds it → Web Design Guidelines audits the result. Framer Components is loaded only when targeting the Framer platform.
+
 ---
 
 ## How It Works
 
-Beth runs inside VS Code Copilot Agent Mode. The `@Beth` agent parses requests, delegates to specialist agents via subagent spawning, and tracks work through beads.
+Beth runs inside VS Code Copilot Agent Mode. The `@Beth` agent parses requests, delegates to specialist agents via subagent spawning, and tracks work through Backlog.md.
 
 ```mermaid
 flowchart LR
@@ -249,12 +270,12 @@ flowchart LR
 **Key capabilities:**
 - **Agent routing** — `@mention` parsing, subagent spawning, handoff chains
 - **Skill injection** — Domain knowledge loaded on trigger phrases
-- **Task tracking** — beads (`bd`) for epics, subtasks, dependencies
+- **Task tracking** — Backlog.md (`backlog`) for tasks, milestones, and progress
 - **MCP integration** — Optional external tool servers (shadcn, Playwright, Azure)
 
 ```
 @Beth implement the login page
-→ Beth routes to @developer, tracks work in beads
+→ Beth routes to @developer, tracks work in Backlog.md
 
 @Beth review this PR for security vulnerabilities
 → Beth routes to @security-reviewer, injects security-analysis skill
@@ -267,19 +288,21 @@ flowchart LR
 
 ---
 
-## Tool Abstraction Layer
+## Agent Tools
 
-A uniform interface for all agent capabilities — file I/O, terminal, search, beads, subagent spawning, and MCP server tools. Tools expose OpenAI-compatible function calling schemas so the LLM can invoke them directly.
+Beth's agents leverage VS Code Copilot's built-in tools alongside task tracking through the `backlog` CLI. The orchestration layer delegates to these capabilities:
 
-| Tool | What It Does | Key Features |
-|------|-------------|-------------- |
-| **readFile** | Read file contents | Line ranges, path validation, traversal guards |
-| **editFile** | Atomic string replacement | Single-match enforcement, whitespace-safe |
-| **search** | Ripgrep search | Node.js fallback, regex support, file filtering |
-| **terminal** | Execute shell commands | `execFile('/bin/sh')` — no shell injection, timeouts |
-| **beads** | Issue tracking | `bd create`, `npx beth-copilot close`, `bd list` via CLI wrapper |
-| **subagent** | Spawn nested agents | Returns structured result for orchestrator to process |
-| **MCP Bridge** | External tool servers | JSON-RPC 2.0 over stdio, JSONC config, namespaced tools |
+| Tool | What It Does |
+|------|-------------|
+| **codebase** | Semantic code search across the workspace |
+| **readFile** | Read file contents with line ranges |
+| **editFiles** | Atomic file modifications |
+| **runInTerminal** | Shell command execution |
+| **runSubagent** | Spawn specialist agents autonomously |
+| **backlog CLI** | `backlog task create`, `backlog board`, `backlog task edit` for tracking |
+| **MCP servers** | Optional external tools (shadcn, Playwright, Azure, Brave Search) |
+
+### Public API
 
 ```typescript
 import { loadAgents, loadSkills, getInferableAgents, buildTriggerMap } from 'beth-copilot';
@@ -309,112 +332,105 @@ flowchart LR
     CLI["beth"] --> Init["init"]
     CLI --> Doctor["doctor"]
     CLI --> QS["quickstart"]
+    CLI --> Land["land"]
+    CLI --> Update["update"]
     Init --> Templates[".agent.md · SKILL.md · settings"]
-    Doctor --> Checks["Node ≥18 · beads · agents · skills"]
+    Doctor --> Checks["Node ≥18 · agents · skills"]
     QS --> Init & Doctor
+    Update --> Diff["Template diffing"]
 ```
 
 **Commands:**
-- `beth init` — Scaffold agents, skills, VS Code settings, beads tracking
-- `beth doctor` — Validate Node.js, beads CLI, agent frontmatter, skill directories
-- `beth quickstart` — Run init + doctor + beads init in one shot
+- `beth init` — Scaffold agents, skills, VS Code settings, Backlog.md tracking
+- `beth doctor` — Validate Node.js, agent frontmatter, skill directories
+- `beth quickstart` — Run init + doctor in one shot
+- `beth land` — Automated session completion: tests, commit, push, verify sync
+- `beth update` — Update project files to latest templates (supports `--check-only`)
 
 ---
 
 ## TypeScript Core
 
-The engine that powers everything. Parses agent and skill definitions, manages conversations, routes requests, executes tools, and provides typed APIs for the full agentic loop.
+The engine that powers Beth. Parses agent and skill definitions, provides typed APIs for the agentic loop, and drives the CLI toolchain.
 
 ### Project Structure
 
 ```
 beth/
 ├── bin/
-│   └── cli.js                      # CLI entry point (init, doctor, quickstart, help)
+│   └── cli.js                      # CLI entry point (init, doctor, quickstart, land, update, help)
 ├── src/
 │   ├── index.ts                    # Barrel exports (all public API)
 │   ├── cli/commands/
 │   │   ├── doctor.ts               # System health validation
-│   │   └── quickstart.ts           # Guided setup flow
+│   │   ├── land.ts                 # Automated session completion
+│   │   ├── pre-push-guard.ts       # Branch discipline enforcement
+│   │   ├── quickstart.ts           # Guided setup flow
+│   │   └── update.ts               # Template update diffing
 │   ├── core/
-│   │   ├── orchestrator.ts         # Agentic loop: route → LLM → tools → response
-│   │   ├── router.ts               # @mention routing, skill matching, agent lookup
-│   │   ├── context.ts              # Conversation state, token truncation, skill injection
-│   │   ├── handoffs.ts             # Agent handoff transfers, loop detection
 │   │   ├── agents/
 │   │   │   ├── types.ts            # AgentDefinition, AgentFrontmatter, AgentHandoff
 │   │   │   └── loader.ts           # Parse .agent.md → typed definitions
 │   │   └── skills/
 │   │       ├── types.ts            # SkillDefinition, TriggerMap
 │   │       └── loader.ts           # Parse SKILL.md, extract triggers, match queries
-│   ├── lib/
-│   │   └── pathValidation.ts       # Traversal/injection guards
-│   ├── tools/
-│   │   ├── interface.ts            # Tool interface + toToolDefinition()
-│   │   ├── types.ts                # ToolError, ToolResult, ToolContext, ToolPermissions
-│   │   ├── registry.ts             # ToolRegistry: register, get, list, getDefinitions
-│   │   ├── cli/
-│   │   │   ├── readFile.ts         # File reading with line ranges
-│   │   │   ├── editFile.ts         # Atomic string replacement
-│   │   │   ├── search.ts           # Ripgrep with Node.js fallback
-│   │   │   ├── terminal.ts         # Secure command execution
-│   │   │   ├── beads.ts            # Issue tracking via bd CLI
-│   │   │   └── subagent.ts         # Agent spawning interface
-│   │   └── mcp/
-│   │       ├── client.ts           # JSON-RPC 2.0 over stdio
-│   │       └── bridge.ts           # JSONC config, tool namespacing
-│   └── providers/
-│       ├── interface.ts            # LLMProviderBase abstract class
-│       ├── azure.ts                # AzureOpenAIProvider (Entra ID, streaming, tools)
-│       ├── types.ts                # 17 types: ChatMessage, ToolCall, LLMError, etc.
-│       ├── retry.ts                # Exponential backoff with jitter
-│       ├── config.ts               # Environment + dotfile config loader
-│       └── streaming.ts            # StreamAccumulator, collectStream, mapStream
+│   └── lib/
+│       └── pathValidation.ts       # Traversal/injection guards
 ├── templates/
 │   └── .github/
 │       ├── agents/                 # 7 agent definitions (.agent.md)
-│       └── skills/                 # 8 skill modules (SKILL.md)
+│       └── skills/                 # 6 core skill modules (SKILL.md)
 └── docs/
     ├── INSTALLATION.md
     ├── MCP-SETUP.md
     ├── CLI-ARCHITECTURE.md
-    └── SYSTEM-FLOW.md
+    ├── SYSTEM-FLOW.md
+    ├── HOOKS-AND-HANDOFF-ENFORCEMENT.md
+    ├── E2E-SKILL-TESTS.md
+    ├── PR-REVIEW-PROCESS.md
+    └── SWARM-ARCHITECTURE.md
 ```
 
 ### Test Coverage
 
-**814 tests** (813 pass, 1 skip, 0 fail):
+**860 tests** (860 pass, 0 fail):
 
 | Suite | Tests | What It Covers |
 |-------|-------|---------------|
-| **Orchestration** | | |
-| Orchestrator | 30+ | Agentic loop, tool calling, subagent spawning, iteration limits |
-| AgentRouter | 30+ | @mention routing, skill matching, agent resolution |
-| ConversationContext | 30+ | Token truncation, skill injection, tool call repair |
-| HandoffManager | 30+ | Context transfer, depth limits, ping-pong detection |
-| **Tools** | | |
-| Tool interface | 20+ | Tool → ToolDefinition conversion, schema validation |
-| ToolRegistry | 20+ | Register, get, list, definitions, duplicate detection |
-| readFile | 30+ | Line ranges, path validation, encoding |
-| editFile | 30+ | String replacement, single-match enforcement |
-| search | 30+ | Ripgrep, Node.js fallback, regex, file filtering |
-| terminal | 30+ | Command execution, timeouts, output capture |
-| beads | 30+ | bd CLI wrapper, create/close/list/ready |
-| subagent | 30+ | Spawn interface, result marking, agent validation |
-| MCP client | 30+ | JSON-RPC 2.0, protocol handshake, tool listing |
-| MCP bridge | 30+ | JSONC parsing, tool namespacing, error handling |
-| Tool suite | 10+ | createDefaultRegistry, integration tests |
-| **Providers** | | |
-| Provider types | 40+ | LLMError codes, ChatMessage shapes, ToolDefinition schemas |
-| Provider retry | 40+ | Exponential backoff, jitter, transient error detection |
-| Provider config | 30+ | Env precedence, dotenv parsing, URL validation |
-| Provider streaming | 40+ | Chunk accumulation, tool call delta assembly |
-| Provider Azure | 30+ | Message mapping, response mapping, error wrapping |
-| **Core & CLI** | | |
-| Agent loader | 30+ | Frontmatter parsing, validation, code fence stripping, handoffs |
-| Skill loader | 30+ | Trigger extraction, query matching, trigger map building |
-| CLI E2E | 52 | Init/doctor pipeline, MCP template validation, help output |
-| Path validation | 33 | Traversal detection, injection prevention, allowlists |
+| **Skill Routing** | | |
+| Hook injection | 51 | Deterministic skill injection via SubagentStart hook |
+| Skill routing | 223 | Agent → skill mapping, trigger phrase matching |
+| Trigger coverage | 147 | All trigger phrases resolve to correct skills |
+| Disambiguation | 28 | Overlapping trigger phrase resolution |
+| Mapping completeness | 12 | Every agent has required skills mapped |
+| Pipeline integration | 41 | End-to-end skill loading through full pipeline |
+| Inject-skills hook | 20 | `inject-skills.mjs` unit tests |
+| Verify-skills hook | 9 | `verify-skills.mjs` compliance gate |
+| Smoke tests | 7 | Package exports, barrel imports |
+| **Core** | | |
+| Agent loader | 13 | `.agent.md` parsing, validation, code fence stripping |
+| Agent frontmatter | 32 | YAML frontmatter extraction, required fields |
+| Agent handoffs | 18 | Handoff chain validation, escalation patterns |
+| Agent tools | 25 | Tool declarations, permission schemas |
+| Agent types | 13 | Type definitions, discriminated unions |
+| Agent suite | 18 | Integration: load all 7 agents, validate consistency |
+| Skill loader | 20 | SKILL.md parsing, trigger extraction, query matching |
+| Path validation | 26 | Traversal detection, injection prevention, allowlists |
+| **CLI** | | |
+| Init | 24 | File scaffolding, template copying, idempotency |
+| Doctor | 15 | Node.js version, agent validation, skill checks |
+| Land | 62 | Test → commit → push pipeline, branch discipline |
+| Pre-push guard | 46 | Branch protection, main/master blocking |
+| Quickstart | 10 | Init + Doctor combined flow |
+| **CLI E2E** | | |
+| Init logic | 20 | End-to-end init with real filesystem |
+| Doctor | 21 | Health checks against real project structure |
+| Pipeline | 14 | Init → Doctor pipeline validation |
+| Help | 24 | Help output format, command listing |
+| MCP | 13 | MCP template validation and copying |
+| Edge cases | 13 | Flag combinations, error scenarios |
+| Pre-push guard | 11 | Git hook integration with temp repos |
+| Quickstart expanded | 11 | Full quickstart flow E2E |
 
 ---
 
@@ -500,37 +516,6 @@ Is it magic? No. It's just competence with very good hair.
 - **Node.js** ≥ 18
 - **VS Code** with GitHub Copilot extension
 - **GitHub Copilot Chat** in Agent mode
-- [**beads**](https://github.com/steveyegge/beads) for task tracking (`bd` CLI)
-
-### Installing Beads
-
-```bash
-curl -fsSL https://raw.githubusercontent.com/steveyegge/beads/main/scripts/install.sh | bash
-```
-
-**CGO Troubleshooting (Linux/WSL):** Beads uses Dolt (a Git-for-data database) which requires CGO. If `bd init` or `bd doctor` fails with CGO-related errors:
-
-```bash
-# Install C compiler toolchain (required for CGO)
-sudo apt-get update && sudo apt-get install -y build-essential gcc
-
-# Verify CGO is available
-export CGO_ENABLED=1
-go env CGO_ENABLED  # should print 1
-
-# Re-install beads
-curl -fsSL https://raw.githubusercontent.com/steveyegge/beads/main/scripts/install.sh | bash
-```
-
-**Common beads issues:**
-- `bd: command not found` — Add `~/.local/bin` to your PATH: `export PATH="$HOME/.local/bin:$PATH"`
-- `bd doctor` warnings about metadata — Run `bd doctor --fix` to auto-repair
-- Dolt migration errors — Delete `.beads/` and re-initialize with `bd init`
-
-```bash
-# Verify beads is working
-bd doctor
-```
 
 ### Optional: MCP Servers
 
@@ -542,10 +527,14 @@ See [MCP Integrations](#mcp-integrations) above or [docs/MCP-SETUP.md](docs/MCP-
 
 | Doc | Purpose |
 |-----|---------|
-| [Installation Guide](docs/INSTALLATION.md) | Full setup: prerequisites, VS Code config, beads |
+| [Installation Guide](docs/INSTALLATION.md) | Full setup: prerequisites, VS Code config, Backlog.md |
 | [MCP Setup](docs/MCP-SETUP.md) | Optional server integrations |
 | [CLI Architecture](docs/CLI-ARCHITECTURE.md) | Dual-interface design, implementation phases |
 | [System Flow](docs/SYSTEM-FLOW.md) | Agent orchestration diagrams |
+| [Hooks & Handoffs](docs/HOOKS-AND-HANDOFF-ENFORCEMENT.md) | Skill injection hooks, hub-and-spoke enforcement |
+| [E2E Skill Tests](docs/E2E-SKILL-TESTS.md) | Behavioral skill routing test plan |
+| [PR Review Process](docs/PR-REVIEW-PROCESS.md) | Code review checklist and workflow |
+| [Swarm Architecture](docs/SWARM-ARCHITECTURE.md) | Multi-agent swarm design (planned) |
 | [Contributing Guide](CONTRIBUTING.md) | How to contribute (PR process, review checklist) |
 | [Changelog](CHANGELOG.md) | Version history |
 | [Security Policy](SECURITY.md) | Vulnerability reporting |