cc-workspace 4.2.1 → 4.4.0

package/README.md

@@ -27,7 +27,7 @@ cd ~/projects/my-workspace
 npx cc-workspace init . "My Project"
 ```
 
-This creates an `orchestrator/` directory and installs 9 skills, 3 agents, 9 hooks, and 3 rules into `~/.claude/`.
+This creates an `orchestrator/` directory and installs 10 skills, 4 agents, 9 hooks, and 3 rules into `~/.claude/`.
 
 ### Configure (one time)
 
@@ -47,7 +47,8 @@ The init agent will:
 
 ```bash
 cd orchestrator/
-claude --agent team-lead
+claude --agent team-lead          # orchestration sessions
+claude --agent e2e-validator      # E2E validation (beta)
 ```
 
 The team-lead offers 4 modes:
@@ -68,7 +69,7 @@ npx cc-workspace update
 Updates all components if the package version is newer:
 - **Global**: skills, rules, agents in `~/.claude/`
 - **Local** (if `orchestrator/` found): hooks, settings.json, CLAUDE.md, templates, _TEMPLATE.md
-- **Never overwritten**: workspace.md, constitution.md, plans/
+- **Never overwritten**: workspace.md, constitution.md, plans/, e2e/
 
 ### Diagnostic
 
@@ -95,6 +96,15 @@ my-workspace/
 │   ├── workspace.md                 <- filled by workspace-init
 │   ├── constitution.md              <- filled by workspace-init
 │   ├── .sessions/                   <- session state (gitignored, created per session)
+│   ├── e2e/                         <- E2E test environment (beta)
+│   │   ├── e2e-config.md            <- agent memory (generated at first boot)
+│   │   ├── docker-compose.e2e.yml   <- generated at first boot
+│   │   ├── tests/                   <- headless API test scripts
+│   │   ├── chrome/
+│   │   │   ├── scenarios/           <- Chrome test flows per plan
+│   │   │   ├── screenshots/         <- evidence
+│   │   │   └── gifs/                <- recorded flows
+│   │   └── reports/                 <- per-plan E2E reports
 │   ├── templates/
 │   │   ├── workspace.template.md
 │   │   ├── constitution.template.md
@@ -198,6 +208,7 @@ parallel in each repo via Agent Teams.
 | **Teammates** | Sonnet 4.6 | Implement in an isolated worktree, test, commit. |
 | **Explorers** | Haiku | Read-only. Scan, verify consistency. |
 | **QA** | Sonnet 4.6 | Hostile mode. Min 3 problems found per service. |
+| **E2E Validator** | Sonnet 4.6 | Containers + Chrome browser testing (beta). |
 
 ### The 4 session modes
 
@@ -235,7 +246,7 @@ Protection layers:
 
 ---
 
-## The 9 skills
+## The 10 skills
 
 | Skill | Role | Trigger |
 |-------|------|---------|
@@ -248,19 +259,21 @@ Protection layers:
 | **cycle-retrospective** | Post-cycle learning (Haiku) | "Retro", "retrospective" |
 | **refresh-profiles** | Re-scan repo CLAUDE.md files (Haiku) | "Refresh profiles" |
 | **bootstrap-repo** | Generate a CLAUDE.md (Haiku) | "Bootstrap", "init CLAUDE.md" |
+| **e2e-validator** | E2E validation: containers + Chrome (beta) | `claude --agent e2e-validator` |
 
 All use `context: fork` — a skill's result is not in context when the
 next one starts. The plan on disk is the source of truth.
 
 ---
 
-## The 3 agents
+## The 4 agents
 
 | Agent | Model | Usage |
 |-------|-------|-------|
 | **team-lead** | Opus 4.6 | `claude --agent team-lead` — multi-service orchestration |
 | **workspace-init** | Sonnet 4.6 | `claude --agent workspace-init` — diagnostic + initial config |
 | **implementer** | Sonnet 4.6 | Task subagent with `isolation: worktree` — isolated implementation |
+| **e2e-validator** | Sonnet 4.6 | `claude --agent e2e-validator` — E2E validation with containers + Chrome (beta) |
 
 ---
 
@@ -385,9 +398,14 @@ cc-workspace/
     ├── cycle-retrospective/SKILL.md
     ├── refresh-profiles/SKILL.md
     ├── bootstrap-repo/SKILL.md
+    ├── e2e-validator/
+    │   └── references/
+    │       ├── container-strategies.md
+    │       ├── test-frameworks.md
+    │       └── scenario-extraction.md
     ├── hooks/                         <- 11 scripts (warning-only)
     ├── rules/                         <- 3 rules
-    └── agents/                        <- 3 agents (team-lead, implementer, workspace-init)
+    └── agents/                        <- 4 agents (team-lead, implementer, workspace-init, e2e-validator)
 ```
 
 ---
@@ -395,7 +413,7 @@ cc-workspace/
 ## Idempotence
 
 Both `init` and `update` are safe to re-run:
-- **Never overwritten**: `workspace.md`, `constitution.md`, `plans/*.md` (user content)
+- **Never overwritten**: `workspace.md`, `constitution.md`, `plans/*.md`, `e2e/` (user content)
 - **Always regenerated**: `settings.json`, `block-orchestrator-writes.sh` (security), `CLAUDE.md`, `_TEMPLATE.md`
 - **Always copied**: hooks, templates
 - **Always regenerated on init**: `service-profiles.md` (fresh scan)
@@ -403,6 +421,87 @@ Both `init` and `update` are safe to re-run:
 
 ---
 
+## E2E Validator (beta)
+
+A dedicated agent that validates completed plans by running services in containers
+and testing scenarios — including Chrome browser-driven UI tests.
+
+```bash
+cd orchestrator/
+claude --agent e2e-validator
+```
+
+### First boot — setup
+
+On first boot (no `e2e/e2e-config.md`), the agent:
+1. Reads `workspace.md` for repos and stacks
+2. Scans repos for existing `docker-compose.yml` and test frameworks
+3. If docker-compose exists: generates an overlay (`docker-compose.e2e.yml`)
+4. If not: builds the config interactively with you
+5. Writes `e2e/e2e-config.md` (its persistent memory)
+
+### Modes
+
+| Mode | Description |
+|------|-------------|
+| `validate <plan>` | Test a specific completed plan (API tests) |
+| `validate <plan> --chrome` | Same + Chrome browser UI tests |
+| `run-all` | Run all E2E tests (headless) |
+| `run-all --chrome` | Run all E2E tests + Chrome |
+| `setup` | Re-run first boot setup |
+
+Add `--fix` to any mode to dispatch teammates for fixing failures.
+
+### How it works
+
+1. Creates `/tmp/` worktrees on session branches (from the plan)
+2. Starts services via `docker compose up`
+3. Waits for health checks
+4. Runs existing test suites + generates API scenario tests from the plan
+5. With `--chrome`: drives Chrome via chrome-devtools MCP (navigate, fill forms,
+   click, take screenshots, record GIFs, check network requests and console)
+6. Generates report with evidence (screenshots, GIFs, network traces)
+7. Tears down containers and worktrees
+
+### Chrome testing
+
+With `--chrome`, the agent:
+- Navigates the frontend in your real Chrome browser
+- Plays user scenarios extracted from the plan
+- Takes screenshots at each step as evidence
+- Records GIFs of complete flows
+- Checks the 4 mandatory UX states (loading, empty, error, success)
+- Tests responsive layouts (mobile viewport)
+- Verifies network requests match the API contract
+- Checks console for errors
+
+### Requirements
+
+- **Docker** (docker compose v2)
+- **Chrome** with chrome-devtools MCP server (for `--chrome` mode)
+- Completed plan (all tasks ✅) with session branches
+
+---
+
+## Changelog v4.3.0 -> v4.4.0
+
+| # | Feature | Detail |
+|---|---------|--------|
+| 1 | **E2E Validator agent (beta)** | New `e2e-validator` agent: validates completed plans by running services in containers. Supports headless API tests and Chrome browser-driven UI tests with screenshots and GIF recording. |
+| 2 | **Chrome testing mode** | `--chrome` flag drives the user's Chrome browser via chrome-devtools MCP. Navigates, fills forms, clicks, takes screenshots, records GIFs, checks network and console. |
+| 3 | **E2E directory structure** | `orchestrator/e2e/` created during init/update. Contains docker-compose overlay, test scripts, Chrome scenarios, screenshots, GIFs, and reports. Never overwritten by updates. |
+| 4 | **Container strategies** | Reference docs for overlay and standalone docker-compose patterns per stack (PHP, Node, Python, Go, Vue, React). |
+| 5 | **Scenario extraction** | Reference doc for extracting testable E2E scenarios from completed plans (API endpoints, Chrome flows, UX states). |
+| 6 | **5 modes** | setup, validate, validate --chrome, run-all, run-all --chrome. Optional --fix dispatches teammates. |
+
+---
+
+## Changelog v4.2.0 -> v4.3.0
+
+> Minor improvements and bug fixes.
+
+---
+
 ## Changelog v4.1.4 -> v4.2.0
 
 | # | Feature | Detail |

package/bin/cli.js

@@ -225,8 +225,10 @@ function generateSettings(orchDir) {
         // block-orchestrator-writes.sh is NOT here — it's in team-lead agent
         // frontmatter only. Putting it in settings.json would block teammates
         // from writing in their worktrees.
-        withMatcher("Teammate", "validate-spawn-prompt.sh", 5),
-        withMatcher("Bash", "guard-session-checkout.sh", 5)
+        // guard-session-checkout.sh is NOT here — it's in implementer agent
+        // frontmatter only. team-lead doesn't have Bash, and teammates don't
+        // inherit orchestrator hooks.
+        withMatcher("Teammate", "validate-spawn-prompt.sh", 5)
       ],
       SessionStart: [
         withoutMatcher("session-start-context.sh", 10)
@@ -281,6 +283,7 @@ You clarify, plan, delegate, track.
 cd orchestrator/
 claude --agent workspace-init   # first time: diagnostic + config
 claude --agent team-lead         # work sessions
+claude --agent e2e-validator     # E2E validation of completed plans
 \`\`\`
 
 ## Initialization (workspace-init)
@@ -303,8 +306,10 @@ Run once. Idempotent — can be re-run to re-diagnose.
 - Service profiles: \`./plans/service-profiles.md\`
 - Active plans: \`./plans/*.md\`
 - Active sessions: \`./.sessions/*.json\`
+- E2E config: \`./e2e/e2e-config.md\`
+- E2E reports: \`./e2e/reports/\`
 
-## Skills (9)
+## Skills (10)
 - **dispatch-feature**: 4 modes, clarify → plan → waves → collect → verify
 - **qa-ruthless**: adversarial QA, min 3 findings per service
 - **cross-service-check**: inter-repo consistency
@@ -314,6 +319,7 @@ Run once. Idempotent — can be re-run to re-diagnose.
 - **cycle-retrospective**: post-cycle learning (haiku)
 - **refresh-profiles**: re-reads repo CLAUDE.md files (haiku)
 - **bootstrap-repo**: generates a CLAUDE.md for a repo (haiku)
+- **e2e-validator**: E2E validation of completed plans (beta) — containers + Chrome
 
 ## Rules
 1. No code in repos — delegate to teammates
@@ -331,6 +337,7 @@ Run once. Idempotent — can be re-run to re-diagnose.
 13. Retrospective cycle after each completed feature
 14. Session branches for parallel isolation — teammates use session/{name}, never create own branches
 15. Never \`git checkout -b\` in repos — use \`git branch\` (no checkout) to avoid disrupting parallel sessions
+16. E2E validation via \`claude --agent e2e-validator\` after plans are complete
 `;
 }
 
@@ -417,7 +424,7 @@ function updateLocal() {
   const hooksDir = path.join(orchDir, ".claude", "hooks");
   if (fs.existsSync(hooksDir)) {
     // Clean obsolete hooks before copying new ones
-    const obsoleteHooks = ["block-orchestrator-writes.sh", "worktree-create-context.sh", "verify-cycle-complete.sh"];
+    const obsoleteHooks = ["block-orchestrator-writes.sh", "worktree-create-context.sh", "verify-cycle-complete.sh", "guard-session-checkout.sh"];
     for (const f of obsoleteHooks) {
       const fp = path.join(hooksDir, f);
       if (fs.existsSync(fp)) fs.unlinkSync(fp);
@@ -474,8 +481,19 @@ function updateLocal() {
     ok(".sessions/ created");
   }
 
-  // ── NEVER touch: workspace.md, constitution.md, plans/*.md, service-profiles.md ──
-  info(`${c.dim}workspace.md, constitution.md, plans/ — preserved${c.reset}`);
+  // ── e2e/ (create if missing — never overwrite existing) ──
+  const e2eDir = path.join(orchDir, "e2e");
+  if (!fs.existsSync(e2eDir)) {
+    mkdirp(path.join(e2eDir, "tests"));
+    mkdirp(path.join(e2eDir, "chrome", "scenarios"));
+    mkdirp(path.join(e2eDir, "chrome", "screenshots"));
+    mkdirp(path.join(e2eDir, "chrome", "gifs"));
+    mkdirp(path.join(e2eDir, "reports"));
+    ok("e2e/ directory created");
+  }
+
+  // ── NEVER touch: workspace.md, constitution.md, plans/*.md, e2e/ ──
+  info(`${c.dim}workspace.md, constitution.md, plans/, e2e/ — preserved${c.reset}`);
 
   return true;
 }
@@ -491,6 +509,11 @@ function setupWorkspace(workspacePath, projectName) {
   mkdirp(path.join(orchDir, "plans"));
   mkdirp(path.join(orchDir, "templates"));
   mkdirp(path.join(orchDir, ".sessions"));
+  mkdirp(path.join(orchDir, "e2e", "tests"));
+  mkdirp(path.join(orchDir, "e2e", "chrome", "scenarios"));
+  mkdirp(path.join(orchDir, "e2e", "chrome", "screenshots"));
+  mkdirp(path.join(orchDir, "e2e", "chrome", "gifs"));
+  mkdirp(path.join(orchDir, "e2e", "reports"));
   ok("Structure created");
 
   // ── Templates ──
@@ -573,7 +596,9 @@ function setupWorkspace(workspacePath, projectName) {
     fs.writeFileSync(gi, [
       ".claude/bash-commands.log", ".claude/worktrees/", ".claude/modified-files.log",
       ".sessions/",
-      "plans/*.md", "!plans/_TEMPLATE.md", "!plans/service-profiles.md", ""
+      "plans/*.md", "!plans/_TEMPLATE.md", "!plans/service-profiles.md",
+      "e2e/chrome/screenshots/", "e2e/chrome/gifs/", "e2e/reports/",
+      "e2e/docker-compose.e2e.yml", "e2e/e2e-config.md", ""
     ].join("\n"));
     ok(".gitignore");
   }
@@ -631,13 +656,14 @@ function setupWorkspace(workspacePath, projectName) {
   log(`  ${c.dim}Directory${c.reset}  ${orchDir}`);
   log(`  ${c.dim}Repos${c.reset}      ${repos.length} detected`);
   log(`  ${c.dim}Hooks${c.reset}      ${hookCount} scripts`);
-  log(`  ${c.dim}Skills${c.reset}     9 ${c.dim}(~/.claude/skills/)${c.reset}`);
+  log(`  ${c.dim}Skills${c.reset}     10 ${c.dim}(~/.claude/skills/)${c.reset}`);
   log("");
   log(`  ${c.bold}Next steps:${c.reset}`);
   log(`    ${c.cyan}cd orchestrator/${c.reset}`);
   log(`    ${c.cyan}claude --agent workspace-init${c.reset}   ${c.dim}# first time: diagnostic + config${c.reset}`);
   log(`    ${c.dim}  └─ type "go" to start the diagnostic${c.reset}`);
   log(`    ${c.cyan}claude --agent team-lead${c.reset}        ${c.dim}# orchestration sessions${c.reset}`);
+  log(`    ${c.cyan}claude --agent e2e-validator${c.reset}    ${c.dim}# E2E validation (beta)${c.reset}`);
   if (reposWithoutClaude.length > 0) {
     log("");
     warn(`${reposWithoutClaude.length} repo(s) without CLAUDE.md: ${c.bold}${reposWithoutClaude.join(", ")}${c.reset}`);
@@ -672,7 +698,7 @@ function doctor() {
   // Skills count
   if (fs.existsSync(GLOBAL_SKILLS)) {
     const skills = fs.readdirSync(GLOBAL_SKILLS, { withFileTypes: true }).filter(e => e.isDirectory());
-    check(`Skills (${skills.length}/9)`, skills.length >= 9, `only ${skills.length} found`);
+    check(`Skills (${skills.length}/10)`, skills.length >= 10, `only ${skills.length} found`);
   }
 
   // Rules
@@ -681,7 +707,7 @@ function doctor() {
   }
 
   // Agents
-  for (const a of ["team-lead.md", "implementer.md", "workspace-init.md"]) {
+  for (const a of ["team-lead.md", "implementer.md", "workspace-init.md", "e2e-validator.md"]) {
     check(`Agent: ${a}`, fs.existsSync(path.join(GLOBAL_AGENTS, a)), "missing");
   }
 
@@ -704,6 +730,7 @@ function doctor() {
     check("templates/", fs.existsSync(path.join(cwd, "templates")), "missing");
     check(".claude/hooks/", fs.existsSync(path.join(cwd, ".claude", "hooks")), "missing");
     check(".sessions/", fs.existsSync(path.join(cwd, ".sessions")), "missing — run: npx cc-workspace update");
+    check("e2e/", fs.existsSync(path.join(cwd, "e2e")), "missing — run: npx cc-workspace update");
     const configured = !fs.readFileSync(path.join(cwd, "workspace.md"), "utf8").includes("[UNCONFIGURED]");
     check("workspace.md configured", configured, "[UNCONFIGURED] — run: claude --agent workspace-init");
   } else if (hasOrch) {
@@ -840,6 +867,7 @@ switch (command) {
     log(`    ${c.cyan}claude --agent workspace-init${c.reset}   ${c.dim}# first time${c.reset}`);
     log(`    ${c.dim}  └─ type "go" to start the diagnostic${c.reset}`);
     log(`    ${c.cyan}claude --agent team-lead${c.reset}        ${c.dim}# work sessions${c.reset}`);
+    log(`    ${c.cyan}claude --agent e2e-validator${c.reset}    ${c.dim}# E2E validation (beta)${c.reset}`);
     log("");
     break;
   }