beth-copilot 1.0.18 → 2.0.0

package/README.md

@@ -12,64 +12,33 @@ They broke her wings once. They forgot she had claws.
 
 ## What Is This?
 
-Beth is a **multi-agent AI orchestrator** with a TypeScript runtime, CLI toolchain, MCP integrations, and agent-to-agent (A2A) delegation—all driven by a ruthless coordinator who runs your development team the way Beth Dutton runs Schwartz & Meyer.
+Beth is a **multi-agent AI orchestrator** with a TypeScript runtime, CLI toolchain, MCP integrations, and subagent delegation—all driven by a ruthless coordinator who runs your development team the way Beth Dutton runs Schwartz & Meyer.
 
-She commands seven specialized agents, each with their own expertise, tools, and handoff chains. On top of the GitHub Copilot agent layer, Beth ships a **TypeScript core engine** with a full agentic loop: agent routing, conversation context management, tool calling, subagent spawning, and agent-to-agent handoffs—all backed by an Azure OpenAI LLM provider with streaming and retry.
+She commands seven specialized agents, each with their own expertise, tools, and handoff chains. On top of the GitHub Copilot agent layer, Beth ships a **TypeScript core engine** with a full agentic loop: agent routing, conversation context management, tool calling, subagent spawning, and agent handoffs—all backed by an Azure OpenAI LLM provider with streaming and retry.
 
 **The system has four execution layers:**
 
 | 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 close`, `beth land` — 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 |
 | **LLM Provider** | Azure OpenAI with Entra ID auth, streaming, retry, tool calling | Live |
 
-**814 tests.** 813 pass, 1 skip, 0 fail.
+**478 tests.** 477 pass, 1 skip, 0 fail.
 
 ---
 
 ## Architecture
 
 ```mermaid
-flowchart TB
-    subgraph Input["Entry Points"]
-        Copilot["VS Code Copilot Chat"]
-        CLI["Beth CLI"]
-    end
-
-    subgraph Engine["Orchestration Engine"]
-        Orch["Orchestrator<br/><i>Route → LLM → Tools → Response</i>"]
-    end
-
-    subgraph Agents["Specialist Agents"]
-        Beth["@Beth"]
-        PM["@product-manager"]
-        UX["@ux-designer"]
-        Dev["@developer"]
-        Sec["@security-reviewer"]
-        Test["@tester"]
-        Res["@researcher"]
-    end
-
-    subgraph Capabilities["Capabilities"]
-        Tools["Tools<br/><i>files · terminal · search · beads</i>"]
-        Skills["Skills<br/><i>PRD · React · shadcn · security</i>"]
-        MCPs["MCP Servers<br/><i>shadcn · Playwright · Azure</i>"]
-    end
-
-    LLM["Azure OpenAI<br/><i>Entra ID · Streaming</i>"]
-
-    Copilot & CLI --> Orch
-    Orch --> Beth
-    Beth -->|"delegates"| PM & UX & Dev & Sec & Test & Res
-    Orch <-->|"chat"| LLM
-    Orch --> Tools & Skills & MCPs
+flowchart LR
+    Input["Copilot Chat / CLI"] --> Beth["@Beth"]
+    Beth --> Agents["PM · UX · Dev · Sec · Test · Research"]
+    Beth --> Skills["Skills · MCP"]
 
     style Beth fill:#1e3a5f,color:#fff
-    style Engine fill:#fff3e0
-    style Capabilities fill:#e3f2fd
 ```
 
 ---
@@ -86,11 +55,11 @@ flowchart TB
 | **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 + Node.js test runner | 478 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.
 
 ---
 
@@ -111,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)
@@ -123,19 +92,20 @@ 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 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`
 
 ---
 
-## Agent-to-Agent (A2A) Orchestration
+## 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
 
@@ -149,40 +119,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 |
 
-### A2A Delegation Model
+### Delegation Model (Hub-and-Spoke)
 
 ```mermaid
-flowchart TB
-    subgraph Orchestration["Beth Orchestration Layer"]
-        BethCore["@Beth<br/><i>Routes work · Spawns subagents</i>"]
-    end
-
-    subgraph Specialists["Specialist Agents"]
-        PM["@product-manager<br/>Requirements · Priorities"]
-        R["@researcher<br/>User insights · Market intel"]
-        UX["@ux-designer<br/>Component specs · Design tokens"]
-        D["@developer<br/>React/TS/Next.js · Implementation"]
-        S["@security-reviewer<br/>Threat modeling · Vulnerabilities"]
-        T["@tester<br/>QA · a11y · Performance"]
-    end
+flowchart LR
+    Beth["@Beth"] -->|subagent| PM["PM"] & UX["UX"] & Dev["Dev"] & Sec["Sec"] & Test["Test"] & Res["Research"]
+    PM -.->|escalate| Beth
+    UX -.->|escalate| Beth
+    Dev -.->|escalate| Beth
+    Sec -.->|escalate| Beth
+    Test -.->|escalate| Beth
+    Res -.->|escalate| Beth
 
-    BethCore -->|"Product Strategy"| PM
-    BethCore -->|"User Research"| R
-    BethCore -->|"UX Design"| UX
-    BethCore -->|"Development"| D
-    BethCore -->|"Security Review"| S
-    BethCore -->|"Quality Assurance"| T
-
-    PM -.->|"subagent"| R
-    PM -.->|"subagent"| UX
-    UX -.->|"subagent"| D
-    D -.->|"subagent"| T
-    S -.->|"subagent"| D
-    T -.->|"subagent"| D
-
-    style BethCore fill:#1e3a5f,color:#fff
+    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 |
@@ -205,33 +158,27 @@ runSubagent({
 sequenceDiagram
     participant U as User
     participant B as Beth
-    participant PM as Product Manager
-    participant UX as UX Designer
-    participant D as Developer
-    participant S as Security
-    participant T as Tester
-
-    U->>B: "Build me a feature"
-    B->>B: Assess & Plan
-
-    B->>PM: Define requirements
-    PM-->>B: PRD + user stories
-
-    B->>UX: Design the experience
-    UX-->>B: Component specs + tokens
-
-    B->>D: Implement feature
-    D-->>B: Implementation complete
-
-    par Parallel quality gates
-        B->>S: Security review
-        S-->>B: OWASP approved
+    participant PM as PM
+    participant UX as UX
+    participant D as Dev
+    participant S as Sec
+    participant T as Test
+
+    U->>B: Request
+    B->>PM: Requirements
+    PM-->>B: PRD
+    B->>UX: Design
+    UX-->>B: Specs
+    B->>D: Build
+    D-->>B: Done
+    par Quality gates
+        B->>S: Security
+        S-->>B: Approved
     and
-        B->>T: Test & verify
-        T-->>B: a11y + regression pass
+        B->>T: Verify
+        T-->>B: Pass
     end
-
-    B->>U: Feature complete ✅
+    B->>U: Ship ✅
 ```
 
 **Bug Hunt?** Tester → Developer → Security → Tester
@@ -276,83 +223,73 @@ 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 |
 | **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.
+
 ---
 
-## Orchestration Engine (Fan-Out Pattern)
+## How It Works
 
-The orchestration engine is Beth's brain — the full agentic loop that processes user messages through routing, skill injection, LLM calls, tool execution, and subagent spawning.
+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 TB
-    User["User Message"] --> Route["AgentRouter\n@mention · skill match · default"]
-    Route --> Context["ConversationContext\nBuild system prompt + history"]
-    Context --> Skills{"Skill triggers match?"}
-    Skills -->|yes| Inject["Inject skill into system prompt"]
-    Skills -->|no| LLM
-    Inject --> LLM["LLM Call\nAzure OpenAI"]
-    LLM --> Decision{"Response type?"}
-    Decision -->|text| Done["Return response"]
-    Decision -->|tool calls| ToolExec["Execute tools\nvia ToolRegistry"]
-    ToolExec --> SubCheck{"Subagent request?"}
-    SubCheck -->|yes| SubAgent["Spawn child loop\ndepth-limited"]
-    SubCheck -->|no| ToolResult["Return tool result"]
-    SubAgent --> ToolResult
-    ToolResult --> LLM
-    Decision -->|handoff| Handoff["HandoffManager\nContext transfer"]
-    Handoff --> Route
-
-    style User fill:#1e3a5f,color:#fff
-    style LLM fill:#e8f5e9
-    style ToolExec fill:#e3f2fd
-    style SubAgent fill:#fff3e0
+flowchart LR
+    Msg["@Beth message"] --> Route["Agent Router"]
+    Route -->|subagent| Agent["Specialist"]
+    Agent -->|tools| Work["Code · Test · Review"]
+    Agent -->|done| Route
+    Route --> Done["Response"]
+
+    style Route fill:#1e3a5f,color:#fff
 ```
 
 **Key capabilities:**
-- **Agent routing** — `@mention` parsing, skill trigger matching, current-agent stickiness
-- **Fan-out tool calling** — Iterative LLM → tool call → result → LLM loop (up to 25 iterations)
-- **Subagent spawning** — Nested agent loops with depth limiting (default: 3 levels deep)
-- **Handoff management** — Context transfer between agents with conversation summaries, ping-pong loop detection
-- **Context window management** — Token-estimated truncation with tool call/result consistency repair
-- **Observer callbacks** — Hook into routing decisions, LLM calls, tool executions, handoffs for logging/UI
+- **Agent routing** — `@mention` parsing, subagent spawning, handoff chains
+- **Skill injection** — Domain knowledge loaded on trigger phrases
+- **Task tracking** — Backlog.md (`backlog`) for tasks, milestones, and progress
+- **MCP integration** — Optional external tool servers (shadcn, Playwright, Azure)
 
-```typescript
-// Full orchestrator usage
-import { Orchestrator, createDefaultRegistry } from 'beth-copilot';
-
-const orchestrator = new Orchestrator({
-  agents: loadAgents('.github/agents'),
-  skills: loadSkills('.github/skills'),
-  provider: new AzureOpenAIProvider(config),
-  toolRegistry: createDefaultRegistry(),
-  toolContext: { workingDir: process.cwd(), permissions: { ... } },
-});
-
-const result = await orchestrator.processMessage('Implement the login page');
-// result.response — final text
-// result.agentId — who handled it
-// result.toolCallsExecuted — what tools ran
-// result.subagentResults — any nested agent work
-// result.injectedSkills — skills loaded for this turn
 ```
+@Beth implement the login page
+→ 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
+
+@Beth plan the dashboard feature
+→ Beth routes to @product-manager for requirements, then @ux-designer for specs
+```
+
+> Invoke Beth by selecting `@Beth` in VS Code Copilot Chat (Agent Mode).
 
 ---
 
 ## Tool Abstraction Layer
 
-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.
+A uniform interface for all agent capabilities — file I/O, terminal, search, task tracking, subagent spawning, and MCP server tools. Tools expose OpenAI-compatible function calling schemas so the LLM can invoke them directly.
 
 | Tool | What It Does | Key Features |
 |------|-------------|-------------- |
@@ -360,77 +297,47 @@ A uniform interface for all agent capabilities — file I/O, terminal, search, b
 | **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`, `bd close`, `bd list` via CLI wrapper |
+| **backlog** | Task tracking | `backlog task create`, `backlog board`, `backlog task edit` via CLI |
 | **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 |
 
 ```typescript
-import { createDefaultRegistry, ToolRegistry, loadAllMCPTools } from 'beth-copilot';
+import { loadAgents, loadSkills, getInferableAgents, buildTriggerMap } from 'beth-copilot';
 
-// Built-in tools
-const registry = createDefaultRegistry();
-// → readFile, editFile, search, terminal, beads, subagent
+// Inspect loaded agent definitions
+const { agents, errors: agentErrors } = loadAgents('.github/agents');
+// → each AgentDefinition has: id, frontmatter (name, tools, handoffs), body
 
-// Add MCP server tools
-const { tools: mcpTools } = await loadAllMCPTools('.vscode/mcp.json');
-for (const tool of mcpTools) {
-  registry.register(tool); // e.g., mcp_shadcn_listComponents
-}
+// Find agents available for subagent spawning
+const subagents = getInferableAgents({ agents, errors: agentErrors });
+// → agents with infer: true in frontmatter
 
-// Get OpenAI function calling definitions
-const definitions = registry.getDefinitions();
-// Pass to LLM as tools parameter
+// Inspect loaded skill modules and their trigger phrases
+const { skills, errors: skillErrors } = loadSkills('.github/skills');
+const triggerMap = buildTriggerMap({ skills, errors: skillErrors });
+// → Map of trigger phrase → SkillDefinition for runtime injection
 ```
 
 ---
 
-## LLM Provider Layer
+## CLI Toolchain
 
-The TypeScript core includes a production-ready provider abstraction for running Beth outside VS Code.
+The CLI handles scaffolding and health checks — distributing agent and skill files to target projects.
 
 ```mermaid
 flowchart LR
-    subgraph Config["Configuration"]
-        Env["process.env"]
-        DotEnv["~/.beth/.env"]
-    end
-
-    subgraph Auth["Authentication"]
-        Entra["Entra ID<br/><i>DefaultAzureCredential</i>"]
-    end
-
-    subgraph Provider["Provider"]
-        Base["LLMProviderBase<br/><i>Abstract interface</i>"]
-        AzureOAI["AzureOpenAIProvider<br/><i>chat · chatStream · countTokens</i>"]
-    end
-
-    subgraph Resilience["Resilience"]
-        RetryMod["Exponential Backoff<br/><i>Jitter · 3 retries</i>"]
-        Errors["LLMError<br/><i>Typed error codes</i>"]
-    end
-
-    subgraph Streaming["Streaming"]
-        Accum["StreamAccumulator<br/><i>Content + tool call assembly</i>"]
-        Collect["collectStream<br/><i>Full response</i>"]
-        Map["mapStream<br/><i>Transform chunks</i>"]
-    end
-
-    Env --> AzureOAI
-    DotEnv --> AzureOAI
-    Entra --> AzureOAI
-    Base --> AzureOAI
-    RetryMod --> AzureOAI
-    AzureOAI --> Accum
-    AzureOAI --> Collect
-    Errors --> RetryMod
+    CLI["beth"] --> Init["init"]
+    CLI --> Doctor["doctor"]
+    CLI --> QS["quickstart"]
+    Init --> Templates[".agent.md · SKILL.md · settings"]
+    Doctor --> Checks["Node ≥18 · agents · skills"]
+    QS --> Init & Doctor
 ```
 
-**Key capabilities:**
-- **Entra ID auth** — No API keys. Uses `DefaultAzureCredential` (az login, managed identity, VS Code creds)
-- **Streaming** — `chatStream()` yields `ChatChunk` objects with incremental tool call delta assembly
-- **Retry** — Exponential backoff with jitter for 429/5xx/network errors. Non-transient errors fail fast
-- **Config** — `process.env` → `~/.beth/.env` precedence chain
-- **193 provider tests** covering types, retry, config, streaming, and Azure client
+**Commands:**
+- `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
 
 ---
 
@@ -453,7 +360,7 @@ beth/
 │   │   ├── 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-to-agent transfers, loop detection
+│   │   ├── handoffs.ts             # Agent handoff transfers, loop detection
 │   │   ├── agents/
 │   │   │   ├── types.ts            # AgentDefinition, AgentFrontmatter, AgentHandoff
 │   │   │   └── loader.ts           # Parse .agent.md → typed definitions
@@ -471,7 +378,7 @@ beth/
 │   │   │   ├── editFile.ts         # Atomic string replacement
 │   │   │   ├── search.ts           # Ripgrep with Node.js fallback
 │   │   │   ├── terminal.ts         # Secure command execution
-│   │   │   ├── beads.ts            # Issue tracking via bd CLI
+│   │   │   ├── backlog.ts           # Task tracking via backlog CLI
 │   │   │   └── subagent.ts         # Agent spawning interface
 │   │   └── mcp/
 │   │       ├── client.ts           # JSON-RPC 2.0 over stdio
@@ -512,7 +419,7 @@ beth/
 | 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 |
+| backlog | 30+ | Backlog.md CLI wrapper, task tracking |
 | 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 |
@@ -537,29 +444,8 @@ Beth follows human-centered design methodology across agent workflows:
 
 ```mermaid
 flowchart LR
-    subgraph Empathize["1. Empathize"]
-        E["@researcher<br/>User interviews<br/>Pain points"]
-    end
-
-    subgraph Define["2. Define"]
-        D["@product-manager<br/>Problem framing<br/>Requirements"]
-    end
-
-    subgraph Ideate["3. Ideate"]
-        I["@ux-designer<br/>Component specs<br/>Patterns"]
-    end
-
-    subgraph Prototype["4. Prototype"]
-        P["@developer<br/>Build to learn<br/>Feature spikes"]
-    end
-
-    subgraph Test["5. Test"]
-        T["@tester<br/>Validate<br/>Accessibility"]
-    end
-
-    E --> D --> I --> P --> T
+    E["1. Empathize<br/>@researcher"] --> D["2. Define<br/>@product-manager"] --> I["3. Ideate<br/>@ux-designer"] --> P["4. Prototype<br/>@developer"] --> T["5. Test<br/>@tester"]
     T -.->|iterate| E
-    T -.->|iterate| I
 ```
 
 ---
@@ -577,36 +463,10 @@ Beth doesn't ship garbage:
 | **Test Coverage** | Unit + Integration + E2E | Tester |
 
 ```mermaid
-flowchart TB
-    subgraph Standards["Quality Standards"]
-        A11y["WCAG 2.1 AA"]
-        Perf["Core Web Vitals"]
-        Sec["OWASP Compliant"]
-        Type["Full TypeScript"]
-        Coverage["Test Coverage"]
-    end
-
-    subgraph Gates["Enforcement"]
-        Designer["UX Designer"]
-        Developer["Developer"]
-        Security["Security Reviewer"]
-        Tester["Tester"]
-    end
-
-    A11y --> Designer
-    Perf --> Developer
-    Sec --> Security
-    Type --> Developer
-    Coverage --> Tester
-
-    Designer --> Ship{Ship?}
-    Developer --> Ship
-    Security --> Ship
-    Tester --> Ship
-
-    Ship -->|All Pass| Deploy["🚀 Deploy"]
-    Ship -->|Fail| Fix["🔧 Fix & Retry"]
-    Fix --> Gates
+flowchart LR
+    Code["Code"] --> Gates["a11y · Perf · OWASP · Types · Tests"]
+    Gates -->|Pass| Ship["🚀 Ship"]
+    Gates -->|Fail| Fix["🔧 Fix"] --> Code
 ```
 
 ---
@@ -660,37 +520,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
 
@@ -702,7 +531,7 @@ 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 |