beth-copilot 1.0.18 → 2.0.0

package/templates/.vscode/settings.json

@@ -1,16 +1,16 @@
-{
-  // Beth Agent System - Recommended Settings
-  // These settings enable full agent orchestration capabilities
-
-  // Required: Allow Beth to delegate work to specialist agents
-  "chat.customAgentInSubagent.enabled": true,
-
-  // Enable agent mode in Copilot Chat
-  "chat.agent.enabled": true,
-
-  // Enable thinking/reasoning for complex tasks
-  "github.copilot.chat.agent.thinkingTool": true,
-
-  // Consistent locale for agent responses
-  "github.copilot.chat.localeOverride": "en"
-}
+{
+  // Beth Agent System - Recommended Settings
+  // These settings enable full agent orchestration capabilities
+
+  // Required: Allow Beth to delegate work to specialist agents
+  "chat.customAgentInSubagent.enabled": true,
+
+  // Enable agent mode in Copilot Chat
+  "chat.agent.enabled": true,
+
+  // Enable thinking/reasoning for complex tasks
+  "github.copilot.chat.agent.thinkingTool": true,
+
+  // Consistent locale for agent responses
+  "github.copilot.chat.localeOverride": "en"
+}

package/templates/AGENTS.md

@@ -1,95 +1,144 @@
 # Agent Instructions
 
-This project uses a **dual tracking system**:
+This project uses [Backlog.md](Backlog.md) for task tracking — the single source of truth for both agents and humans.
 
-| Tool | Audience | Purpose |
-|------|----------|---------|
-| [beads](https://github.com/steveyegge/beads) (`bd`) | Agents | Active work, dependencies, blockers, structured memory |
-| [Backlog.md](Backlog.md) | Humans | Completed work archive, decisions, readable changelog |
+## Backlog.md CLI Quick Reference
 
-**The rule:** beads is always current. Backlog.md gets updated when work completes.
+```bash
+# See everything at once (use --plain where supported to avoid TUI)
+backlog task list --plain              # All tasks grouped by status
+backlog task list -s "In Progress" --plain  # Filter by status
+backlog board                          # Kanban board (always plain-text)
+backlog overview                       # Project health stats (always plain-text)
+
+# Task lifecycle (--plain prevents TUI after mutation)
+backlog task create "Title" -d "Description" --plain   # Create
+backlog task edit BETH-X -s "In Progress" --plain       # Start
+backlog task edit BETH-X -s "Done" --plain              # Close
+backlog task edit BETH-X --append-notes "text" --plain  # Add notes
+
+# Search
+backlog search "query" --plain         # Fuzzy search across tasks
+```
+
+**CRITICAL:** Always use `--plain` flag on commands that support it (`task list`, `task create`, `task edit`, `search`) — without it, these commands open a TUI that agents cannot interact with. Commands like `board` and `overview` are already plain-text.
 
 ## Quick Setup
 
 ```bash
-# Install beads
-curl -fsSL https://raw.githubusercontent.com/steveyegge/beads/main/scripts/install.sh | bash
-
-# Initialize in your project
-bd init
+# Initialize Beth in your project
+npx beth-copilot init
 
-# Run doctor to verify setup
-bd doctor
+# Check system health
+npx beth-copilot doctor
 ```
 
-## Quick Reference
+## Session Startup (MANDATORY)
 
+**Every new session starts by verifying ground truth.** Trackers lie. Code doesn't.
+
+Before picking up new work — even continuing previous work — complete these checks:
+
+### 1. Check for uncommitted changes (formatter reverts)
 ```bash
-# Simple task
-bd create "Issue title" --description="What needs to be done" -l in_progress
+git status
+git diff --stat
+```
+Formatters, editors, and VS Code extensions can silently revert agent changes between sessions. If you see unexpected diffs, investigate before proceeding.
 
-# Epic for complex work
-bd create "Feature name" --type epic -p 1
+### 2. Check for unpushed commits
+```bash
+git log --oneline origin/$(git branch --show-current)..HEAD
+```
+If there are unpushed commits from a previous session, push them or understand why they weren't pushed.
 
-# Subtask with parent
-bd create "Subtask" --parent <epic-id>
+### 3. Review task status
+```bash
+backlog task list --plain              # See all tasks — what's open, done, in progress
+backlog task list -s "In Progress" --plain  # What's supposed to be active?
+```
+If a task says "In Progress" but the work is done, close it: `backlog task edit BETH-X -s "Done"`
+If a task says "Done" but the code disagrees, reopen it: `backlog task edit BETH-X -s "In Progress"`
 
-# Task with dependency
-bd create "Blocked task" --deps "<blocker-id>"
+### 4. Spot-check closed work is intact
+Pick 1-2 tasks closed in the last session and verify the changes are actually in the code:
+```bash
+# Example: verify an import was actually added
+grep -r "import.*ComponentName" src/
+```
+If the tracker says "done" but the code disagrees, re-apply the fix.
 
-# List issues / see what's ready
-bd list
-bd ready
+### The principle: Trust the code, not the tracker
 
-# View dependencies
-bd dep tree <id>
+> **War story (March 7, 2026):** A formatter reverted `app/workspace/agents/page.tsx` back to importing the old `WorkspaceAgents` component. The tracker said "routing wired up" but the code was back to the old state. Caught and fixed — but only because we checked.
 
-# Close an issue
-bd close <id>
-```
+This can happen to ANY file touched by agents. The most vulnerable are files touched by formatters on save. When in doubt, check the code.
 
 ## Workflow
 
 ### Simple Tasks
-1. `bd create "Task" -l in_progress`
-2. Do the work
-3. `bd close <id>`
-4. Update Backlog.md if significant
+1. Create a task: `backlog task create "Title" -d "Description" --plain`
+2. Mark it in progress: `backlog task edit BETH-X -s "In Progress" --plain`
+3. Do the work
+4. Mark it done: `backlog task edit BETH-X -s "Done" --plain`
 5. Commit and push
 
 ### Complex Work (Multi-Agent)
-1. `bd create "Feature" --type epic -p 1`
-2. Break into subtasks with `--parent` and `--deps`
-3. `bd ready` to find unblocked work
-4. Route to specialists with issue IDs
-5. Close subtasks as they complete
-6. `bd epic close-eligible` when all children done
-7. Update Backlog.md with summary
-8. Commit and push
+1. **Create/checkout** an epic branch from main:
+
+   ```bash
+   git fetch origin main
+   git checkout -b epic/<epic-id> origin/main
+   ```
+
+2. Create a parent task: `backlog task create "Epic title" -d "Description" --plain`
+3. Break into subtasks, route to specialists
+4. Each subtask: create → assign → work → mark done via `backlog task edit`
+5. Push the epic branch
+6. **Create a PR to `main`**
 
 ## Landing the Plane (Session Completion)
 
-**When ending a work session**, you MUST complete ALL steps below. Work is NOT complete until `git push` succeeds.
+**When ending a work session**, you MUST complete ALL steps below. Work is NOT complete until `git push` succeeds AND the PR is created.
 
 **MANDATORY WORKFLOW:**
 
-1. **Close beads issues** - `bd close <id>` for completed work
-2. **Create follow-up issues** - `bd create` for any remaining work
-3. **Update Backlog.md** - Add summary to Completed section for significant work
-4. **Run quality gates** (if code changed) - Tests, linters, builds
-5. **PUSH TO REMOTE** - This is MANDATORY:
+1. **Close tasks** - Mark all completed tasks as done:
+   ```bash
+   backlog task list -s "In Progress" --plain   # What's still open?
+   backlog task edit BETH-X -s "Done" --plain   # Close each completed task
+   ```
+2. **Run quality gates** (if code changed) - ALL tests must pass:
+   ```bash
+   npm test                   # Unit + integration tests
+   ```
+3. **Generate test report** (if code changed):
+   ```bash
+   npm run test:gate           # Runs tests + generates docs/test-reports/ report
+   ```
+4. **PUSH TO EPIC BRANCH** - This is MANDATORY:
+
    ```bash
    git add -A
-   git commit -m "description of work"
-   git pull --rebase
-   git push
+   git commit -m "<epic-id>: description of work"
+   git pull origin "epic/<epic-id>" --rebase
+   git push origin "epic/<epic-id>"
    git status  # MUST show "up to date with origin"
    ```
-6. **Verify** - All changes committed AND pushed
-7. **Hand off** - Provide context for next session
+
+5. **CREATE A PR TO `main`** - Use `gh` CLI to create a pull request:
+
+   ```bash
+   gh pr create --base main --head "epic/<epic-id>" --title "<epic-id>: <summary>" --body "## Summary\n<what was done>"
+   ```
+
+6. **Share the PR link** with the user
+7. **Hand off** - Provide context for next session including the epic ID, branch, and PR URL
 
 **CRITICAL RULES:**
-- Work is NOT complete until `git push` succeeds
+
+- Work is NOT complete until `git push` succeeds AND the PR is created
 - NEVER stop before pushing - that leaves work stranded locally
 - NEVER say "ready to push when you are" - YOU must push
 - If push fails, resolve and retry until it succeeds
+- The PR is how humans review your work. No PR = no review = no trust.

package/templates/Backlog.md

@@ -1,80 +1,80 @@
-# Backlog
-
-> *"I don't have time to explain things twice. Read this."*
-
-Last updated: <!-- Update this date when making changes -->
-
----
-
-## Completed
-
-| Task | Notes |
-|------|-------|
-| Initial setup | Beth agent system installed |
-
----
-
-## In Progress
-
-*Nothing currently in progress.*
-
----
-
-## Backlog (Prioritized)
-
-### High Priority (P1)
-
-- [ ] **Your first task** — Describe what needs to be done
-
-### Medium Priority (P2)
-
-- [ ] **Future work** — Things to do later
-
-### Low Priority (P3)
-
-- [ ] **Nice to have** — When you have time
-
----
-
-## Decisions
-
-| Decision | Rationale | Date |
-|----------|-----------|------|
-| Use Beth orchestrator | Coordinated multi-agent workflows | Today |
-
----
-
-## Status Summary
-
-**For Leadership:**
-
-Project initialized with Beth agent system.
-
-**What's Working:**
-
-- Beth agent (orchestrator) — Ready
-- Full agent roster — Ready
-- All skills — Loaded
-
-**What's Coming:**
-
-- Your roadmap here
-
-**Blockers:** None.
-
----
-
-## How We Track Work
-
-This file is the single source of truth. When you start work:
-
-1. Move the task to **In Progress**
-2. Do the work
-3. Move to **Completed** when done
-4. Commit changes
-
-No external tools. No databases. Just this markdown file.
-
----
-
-*"Now you know what's happening. Questions? I'll answer them. Complaints? Keep them to yourself."*
+# Backlog
+
+> *"I don't have time to explain things twice. Read this."*
+
+Last updated: <!-- Update this date when making changes -->
+
+---
+
+## Completed
+
+| Task | Notes |
+|------|-------|
+| Initial setup | Beth agent system installed |
+
+---
+
+## In Progress
+
+*Nothing currently in progress.*
+
+---
+
+## Backlog (Prioritized)
+
+### High Priority (P1)
+
+- [ ] **Your first task** — Describe what needs to be done
+
+### Medium Priority (P2)
+
+- [ ] **Future work** — Things to do later
+
+### Low Priority (P3)
+
+- [ ] **Nice to have** — When you have time
+
+---
+
+## Decisions
+
+| Decision | Rationale | Date |
+|----------|-----------|------|
+| Use Beth orchestrator | Coordinated multi-agent workflows | Today |
+
+---
+
+## Status Summary
+
+**For Leadership:**
+
+Project initialized with Beth agent system.
+
+**What's Working:**
+
+- Beth agent (orchestrator) — Ready
+- Full agent roster — Ready
+- All skills — Loaded
+
+**What's Coming:**
+
+- Your roadmap here
+
+**Blockers:** None.
+
+---
+
+## How We Track Work
+
+This file is the single source of truth. When you start work:
+
+1. Move the task to **In Progress**
+2. Do the work
+3. Move to **Completed** when done
+4. Commit changes
+
+No external tools. No databases. Just this markdown file.
+
+---
+
+*"Now you know what's happening. Questions? I'll answer them. Complaints? Keep them to yourself."*

package/templates/mcp.json.example

@@ -1,9 +1,6 @@
 {
   "$schema": "https://code.visualstudio.com/docs/copilot/chat/mcp-servers",
   "servers": {
-    "beads": {
-      "command": "beads-mcp"
-    },
     "shadcn": {
       "command": "npx",
       "args": ["shadcn@3.7.0", "mcp"]

package/assets/beth-portrait-small.txt

@@ -1,13 +0,0 @@
-[38;2;218;165;32m       .╭━━━━━━━╮.[0m
-[38;2;218;165;32m    ╭──╯[0m[38;2;235;210;160m ▒▓▓▓▓▒ [0m[38;2;218;165;32m╰──╮[0m
-[38;2;218;165;32m   ╱[0m[38;2;240;220;180m  ▓██████████▓  [0m[38;2;218;165;32m╲[0m
-[38;2;218;165;32m  ╱[0m[38;2;235;215;170m  ████[0m[38;2;139;90;43m▓▓[0m[38;2;235;215;170m██[0m[38;2;139;90;43m▓▓[0m[38;2;235;215;170m████  [0m[38;2;218;165;32m╲[0m
-[38;2;218;165;32m  │[0m[38;2;240;225;190m  ███ [0m[38;2;70;110;150m◉[0m[38;2;240;225;190m ██ [0m[38;2;70;110;150m◉[0m[38;2;240;225;190m ███  [0m[38;2;218;165;32m│[0m
-[38;2;218;165;32m  │[0m[38;2;235;210;165m   ███▄▄▄▄▄▄███   [0m[38;2;218;165;32m│[0m
-[38;2;218;165;32m  │[0m[38;2;230;200;150m    ▀██[0m[38;2;180;80;80m▄══▄[0m[38;2;230;200;150m██▀    [0m[38;2;218;165;32m│[0m
-[38;2;218;165;32m  │[0m[38;2;220;190;140m      ╰────╯      [0m[38;2;218;165;32m│[0m
-[38;2;218;165;32m  │[0m[38;2;200;175;130m   ▓██████████▓   [0m[38;2;218;165;32m│[0m
-[38;2;218;165;32m  ╲[0m[38;2;180;155;110m   ████████████   [0m[38;2;218;165;32m╱[0m
-[38;2;218;165;32m   ╲[0m[38;2;160;135;90m  ▀██████████▀  [0m[38;2;218;165;32m╱[0m
-[38;2;218;165;32m    ╰───╮      ╭───╯[0m
-[38;2;218;165;32m        ╰──────╯[0m