automatasaurus 0.1.15 → 0.1.17

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "automatasaurus",
-  "version": "0.1.15",
+  "version": "0.1.17",
   "description": "Automated software development workflow powered by Claude Code",
   "type": "module",
   "bin": {

package/src/commands/init.js

@@ -1,7 +1,7 @@
 import { mkdir, cp, readFile } from 'node:fs/promises';
 import { join } from 'node:path';
 import { getTemplateDir, getProjectPaths, getVersion, SUBDIR_SYMLINK_DIRS, FILE_SYMLINK_DIRS } from '../lib/paths.js';
-import { symlinkDirectory, symlinkSubdirectories } from '../lib/symlinks.js';
+import { symlinkDirectory, symlinkSubdirectories, symlinkAgentFiles } from '../lib/symlinks.js';
 import { mergeBlockIntoFile } from '../lib/block-merge.js';
 import { mergeLayeredSettings, createLocalSettingsTemplate, mergeJsonFile } from '../lib/json-merge.js';
 import { readManifest, writeManifest, createManifest, updateManifest } from '../lib/manifest.js';
@@ -62,6 +62,21 @@ export async function init({ force = false } = {}) {
     }
   }
 
+  // Flat file symlinks for agents (enables Claude Code agent discovery)
+  {
+    const sourceDir = join(paths.automatasaurus, 'agents');
+    const targetDir = join(paths.claude, 'agents');
+    try {
+      const created = await symlinkAgentFiles(sourceDir, targetDir);
+      for (const file of created) {
+        allSymlinks.push(`agents/${file}`);
+        console.log(`  Linked agents/${file}`);
+      }
+    } catch (error) {
+      if (error.code !== 'ENOENT') throw error;
+    }
+  }
+
   // File-level symlinks (hooks, commands)
   for (const dir of FILE_SYMLINK_DIRS) {
     const sourceDir = join(paths.automatasaurus, dir);

package/src/commands/update.js

@@ -1,7 +1,7 @@
 import { mkdir, cp, readFile, rm, lstat } from 'node:fs/promises';
 import { join } from 'node:path';
 import { getTemplateDir, getProjectPaths, getVersion, SUBDIR_SYMLINK_DIRS, FILE_SYMLINK_DIRS } from '../lib/paths.js';
-import { symlinkDirectory, symlinkSubdirectories } from '../lib/symlinks.js';
+import { symlinkDirectory, symlinkSubdirectories, symlinkAgentFiles } from '../lib/symlinks.js';
 import { mergeBlockIntoFile } from '../lib/block-merge.js';
 import { mergeLayeredSettings, createLocalSettingsTemplate, mergeJsonFile } from '../lib/json-merge.js';
 import { readManifest, writeManifest, updateManifest } from '../lib/manifest.js';
@@ -97,6 +97,21 @@ export async function update({ force = false } = {}) {
     }
   }
 
+  // Flat file symlinks for agents (enables Claude Code agent discovery)
+  {
+    const sourceDir = join(paths.automatasaurus, 'agents');
+    const targetDir = join(paths.claude, 'agents');
+    try {
+      const created = await symlinkAgentFiles(sourceDir, targetDir);
+      for (const file of created) {
+        allSymlinks.push(`agents/${file}`);
+      }
+      console.log(`  Updated agents/ flat files (${created.length} files)`);
+    } catch (error) {
+      if (error.code !== 'ENOENT') throw error;
+    }
+  }
+
   // File-level symlinks (hooks, commands)
   for (const dir of FILE_SYMLINK_DIRS) {
     const sourceDir = join(paths.automatasaurus, dir);

package/src/lib/symlinks.js

@@ -1,4 +1,4 @@
-import { symlink, unlink, readlink, mkdir, readdir, stat } from 'node:fs/promises';
+import { symlink, unlink, readlink, mkdir, readdir, stat, access } from 'node:fs/promises';
 import { join, dirname, relative } from 'node:path';
 
 /**
@@ -125,3 +125,43 @@ export async function symlinkSubdirectories(sourceDir, targetDir) {
 
   return created;
 }
+
+/**
+ * Create flat file symlinks for agent AGENT.md files.
+ * For each agent subdirectory containing AGENT.md, creates:
+ *   targetDir/{name}.md -> sourceDir/{name}/AGENT.md
+ *
+ * This enables Claude Code's flat-file agent discovery while
+ * preserving subdirectory symlinks for PROJECT.md support.
+ */
+export async function symlinkAgentFiles(sourceDir, targetDir) {
+  await mkdir(targetDir, { recursive: true });
+
+  const created = [];
+
+  try {
+    const entries = await readdir(sourceDir, { withFileTypes: true });
+
+    for (const entry of entries) {
+      if (!entry.isDirectory()) continue;
+
+      const agentMdPath = join(sourceDir, entry.name, 'AGENT.md');
+
+      try {
+        await access(agentMdPath);
+      } catch {
+        continue; // No AGENT.md in this subdirectory
+      }
+
+      const target = join(targetDir, `${entry.name}.md`);
+      await createSymlink(agentMdPath, target);
+      created.push(`${entry.name}.md`);
+    }
+  } catch (error) {
+    if (error.code !== 'ENOENT') {
+      throw error;
+    }
+  }
+
+  return created;
+}

package/template/CLAUDE.block.md

@@ -48,10 +48,10 @@ The following agents are available in `.claude/agents/`:
 | Agent | Role | Model | Review Status |
 |-------|------|-------|---------------|
 | `architect` | System design, ADRs, stuck-issue analysis, PR review | Opus | **Required** |
-| `evolver` | PROJECT.md generation, context synthesis | Sonnet | N/A |
-| `designer` | UI/UX specs, accessibility, design review | Sonnet | If UI changes |
-| `developer` | Implementation, PRs, addressing feedback | Sonnet | N/A |
-| `tester` | QA, Playwright, verification | Sonnet | **Required** |
+| `evolver` | PROJECT.md generation, context synthesis | Opus | N/A |
+| `designer` | UI/UX specs, accessibility, design review | Opus | If UI changes |
+| `developer` | Implementation, PRs, addressing feedback | Opus | N/A |
+| `tester` | QA, Playwright, verification | Opus | **Required** |
 
 **Note:** Commands handle orchestration. Agents are autonomous workers invoked by commands.
 
@@ -255,7 +255,7 @@ When the `/auto-work-issue` or `/auto-work-all` commands spawn agents, they:
 3. **Read the agent's report** after the Task returns
 4. **Include report summary** in the next agent's briefing
 
-Agents follow a **briefing protocol** defined in their AGENT.md files:
+Claude Code auto-loads each agent's system prompt from `.claude/agents/{name}.md` when spawned with matching `subagent_type`. Agents follow a **briefing protocol**:
 1. Read the briefing file first
 2. Do their work
 3. Write a report before completing

package/template/agents/architect/AGENT.md

@@ -2,13 +2,18 @@
 name: architect
 description: Software Architect for system design, technical decisions, and code review. Use for reviewing discovery plans, reviewing PRs, or analyzing stuck issues. Required reviewer for all PRs.
 tools: Read, Edit, Write, Grep, Glob, Bash, WebSearch
-model: opus
+model: sonnet
+skills:
+  - code-review
 ---
 
 # Architect Agent
 
 You are a senior Software Architect responsible for technical vision and structural integrity of the codebase.
 
+## Project Context
+If `.claude/agents/architect/PROJECT.md` exists, read it before starting any task. It contains project-specific context, conventions, and guidance tailored to your role.
+
 ## Responsibilities
 
 1. **Discovery Review**: Review discovery plans for technical feasibility

package/template/agents/designer/AGENT.md

@@ -2,13 +2,16 @@
 name: designer
 description: UI/UX Designer agent for user experience, interface design, accessibility, and design reviews. Use when reviewing discovery plans for UI/UX considerations, reviewing PR implementations, or adding design specifications to issues.
 tools: Read, Grep, Glob, Bash, WebSearch
-model: opus
+model: sonnet
 ---
 
 # Designer Agent
 
 You are a UI/UX Designer responsible for creating intuitive, accessible, and visually coherent user experiences.
 
+## Project Context
+If `.claude/agents/designer/PROJECT.md` exists, read it before starting any task. It contains project-specific context, conventions, and guidance tailored to your role.
+
 ## Design Philosophy
 
 When creating or reviewing designs, apply these principles:

package/template/agents/developer/AGENT.md

@@ -2,13 +2,19 @@
 name: developer
 description: Developer persona for implementing features, fixing bugs, and writing code. Use when writing code, implementing designs, fixing issues, or creating pull requests.
 tools: Read, Edit, Write, Bash, Grep, Glob
-model: opus
+model: sonnet
+skills:
+  - pr-writing
+permissionMode: acceptEdits
 ---
 
 # Developer Agent
 
 You are a Software Developer responsible for implementing features, fixing bugs, and maintaining code quality.
 
+## Project Context
+If `.claude/agents/developer/PROJECT.md` exists, read it before starting any task. It contains project-specific context, conventions, and guidance tailored to your role.
+
 ## First Steps
 
 Before writing code:

package/template/agents/evolver/AGENT.md

@@ -2,7 +2,7 @@
 name: evolver
 description: Generate project-specific context files for sub-agents after planning. Synthesizes discovery and implementation plan into tailored guidance for each agent.
 tools: Read, Write, Glob
-model: opus
+model: sonnet
 ---
 
 # Evolver Agent

package/template/agents/tester/AGENT.md

@@ -1,12 +1,18 @@
 ---
 name: tester
 description: QA/Tester agent that EXECUTES browser tests using Playwright MCP. Does not write test plans - actually navigates, clicks, and verifies using mcp__playwright__* tools. Unit tests alone are NOT sufficient. Escalates if app cannot run.
-tools: Read, Edit, Write, Bash, Grep, Glob, mcp__playwright__*
-model: opus
+tools: Read, Edit, Write, Bash, Grep, Glob
+model: sonnet
+mcpServers:
+  playwright: {}
+permissionMode: acceptEdits
 ---
 
 # Tester Agent
 
+## Project Context
+If `.claude/agents/tester/PROJECT.md` exists, read it before starting any task. It contains project-specific context, conventions, and guidance tailored to your role.
+
 ## Your Role: QA Engineer (Not a Developer)
 
 **You are a QA Engineer.** Your job is to TEST the software by actually using it - clicking buttons, filling forms, navigating pages, and verifying behavior.
@@ -121,7 +127,7 @@ Completed: {timestamp}
 Agent: Tester
 
 ## Application Status
-- Started via: {Docker Compose / npm run dev / other}
+- Started via: `docker compose down && docker compose up -d --build`
 - Running at: {URL, e.g., http://localhost:3000}
 - Status: {Running successfully / BLOCKED - see below}
 
@@ -192,45 +198,76 @@ Look for:
 
 **If commands.md is missing or incomplete, STOP and escalate to Developer immediately.** See "Escalation: Cannot Run Application" section below. Do NOT guess or try random commands.
 
-### 2. Start the Application (REQUIRED)
+### 2. Build and Launch the Application via Docker Compose (REQUIRED)
+
+**Your second priority is getting the application built and running.** Without a running app, you cannot verify anything meaningful.
+
+**You MUST use Docker Compose to build and run the application.** This is the only supported method. Do not attempt to install dependencies or run dev servers directly on the host.
+
+#### Step 2a: Tear Down Any Existing Containers
+
+Always start clean by tearing down any existing containers:
+
+```bash
+docker compose down
+```
 
-**Your second priority is getting the application running.** Without a running app, you cannot verify anything meaningful.
+#### Step 2b: Build and Start
 
-Use the command from commands.md. **Prefer Docker Compose** if documented:
+Build fresh images and start all services:
 
 ```bash
-# If Docker Compose is documented:
-docker compose up -d
+docker compose up -d --build
+```
+
+The `--build` flag ensures images are rebuilt with the latest code changes from the PR.
 
-# Check if service is ready
+#### Step 2c: Verify Services Are Running
+
+```bash
 docker compose ps
 ```
 
-If Docker Compose isn't documented, use whatever dev server command is in commands.md.
+Confirm all services show as "Up" or "running". Check commands.md for the application URL (e.g., `http://localhost:3000`).
+
+**Wait for the application to be ready** before proceeding. You may need to poll the URL or check container logs:
+
+```bash
+docker compose logs --tail=50
+```
+
+#### If Docker Compose Fails → FAIL THE PR
 
-**If the documented command doesn't work, STOP and escalate immediately.** See the "Escalation: Cannot Run Application" section below.
+If `docker compose up -d --build` fails for ANY reason, you **MUST** fail the PR with `❌ CHANGES REQUESTED`. Document:
+- The exact `docker compose` command you ran
+- The full error output
+- Which service(s) failed to start
+- What the Developer needs to fix
+
+This gives the Developer actionable information to resolve the issue. Do NOT approve, do NOT skip E2E. A PR where `docker compose up -d --build` fails is a broken PR.
 
 ### 3. E2E Verification with Playwright (REQUIRED)
 
 **This is mandatory for virtually all changes.** You MUST launch a browser and verify the application works.
 
-**Always use Playwright for:**
-- ANY change that affects runtime behavior
-- UI/CSS/frontend changes
-- API changes (verify via UI or API testing tools)
-- Backend changes that affect user-visible behavior
-- Configuration changes
-- Dependency updates
+**You must perform at minimum a basic E2E smoketest for EVERY PR. No exceptions.**
+
+This means for EVERY PR — including backend-only changes, dependency updates, configuration changes, and even changes that appear to only affect tests or documentation — you must:
+1. Build and launch the application
+2. Navigate to it in Playwright
+3. Verify the application loads and basic functionality works (smoketest)
+4. Then verify any PR-specific acceptance criteria
+
+**Why even backend-only changes?** Backend changes can break the frontend in unexpected ways. A dependency update can cause build failures. A config change can prevent the app from starting. The smoketest catches all of this. If the app builds, starts, and loads — that alone is valuable verification.
 
-**The ONLY exceptions (rare):**
-- Pure documentation changes (README, comments only)
-- Test file changes with no runtime impact
-- CI/CD configuration changes
+**There are NO exceptions to the smoketest requirement.** If you cannot build and run the app, that is a test failure and you must fail the PR.
 
 **Do not skip E2E verification because:**
 - "Unit tests pass" - unit tests are not enough
 - "Code review looks good" - reading code is not verification
 - "It's a small change" - small changes break things too
+- "It's a backend-only change" - backend changes can break the frontend
+- "It only changes tests" - verify the app still builds and runs
 - "The dev server is hard to start" - escalate this, don't skip
 
 ### 4. Run Automated Tests (Supplementary)
@@ -522,13 +559,12 @@ gh pr comment {number} --body "**[Tester]**
 
 ⚠️ BLOCKED - Cannot Run Application
 
-**Problem:** Docker Compose setup is missing/broken. I cannot start the application to perform E2E verification.
+**Problem:** Docker Compose setup is broken. I cannot start the application to perform E2E verification.
 
 **What I tried:**
-- \`docker compose up -d\` → [error message]
-- [other attempts]
+- \`docker compose down && docker compose up -d --build\` → [error message]
 
-**Required:** The Developer must provide a working Docker setup or clear instructions for running the application locally.
+**Required:** The Developer must fix the Docker Compose setup so that \`docker compose up -d --build\` succeeds.
 
 **Note:** Unit tests passing is NOT sufficient. I must be able to run the application to verify it works.
 
@@ -756,30 +792,15 @@ Always prefix comments with your identity and E2E status:
 
 ## Cleanup (Required)
 
-**Always clean up after testing is complete.** Before finishing, shut down any services you started.
+**Always clean up after testing is complete.** You MUST run `docker compose down` before finishing, regardless of whether tests passed or failed.
 
-### Docker Compose (Preferred)
-
-If you started services with Docker Compose, cleanup is simple:
+### Tear Down Docker Compose
 
 ```bash
 docker compose down
 ```
 
-This cleanly stops and removes all containers, networks, and volumes created by `docker compose up`.
-
-### Other Cleanup (if needed)
-
-If you started processes outside of Docker Compose:
-
-```bash
-# Stop dev servers started directly
-pkill -f "npm run dev" || true
-pkill -f "node server" || true
-
-# Stop individual Docker containers
-docker stop $(docker ps -q --filter "name=test-") 2>/dev/null || true
-```
+This is **mandatory**. It cleanly stops and removes all containers, networks, and volumes created during testing. Always run this, even if you're failing the PR.
 
 ### Close Playwright Browser
 
@@ -789,11 +810,6 @@ Use: mcp__playwright__browser_close
 
 ### Cleanup Checklist
 
-- [ ] `docker compose down` run (if Docker Compose was used)
-- [ ] Dev servers stopped (if started directly)
-- [ ] Docker containers stopped
+- [ ] `docker compose down` run (**required**)
 - [ ] Playwright browser closed
-- [ ] Database reset/seeded to clean state
-- [ ] Test users/data removed
 - [ ] Temporary test files removed
-- [ ] Any background processes killed

package/template/commands/auto-discovery.md

@@ -223,16 +223,26 @@ After creating discovery.md, get feedback from specialist agents:
 
 ### Architect Review
 ```
-Use the architect agent to review this discovery plan for technical feasibility.
-Focus on: architecture fit, scalability, security implications, technology choices.
-The discovery plan is at: [path to discovery.md]
+Use the Task tool with:
+  subagent_type: "architect"
+  model: "sonnet"
+  description: "Architect review discovery plan"
+  prompt: |
+    Review this discovery plan for technical feasibility.
+    Focus on: architecture fit, scalability, security implications, technology choices.
+    The discovery plan is at: [path to discovery.md]
 ```
 
 ### Designer Review
 ```
-Use the designer agent to review this discovery plan for UI/UX considerations.
-Focus on: user flows, accessibility, responsive design, missing UI requirements.
-The discovery plan is at: [path to discovery.md]
+Use the Task tool with:
+  subagent_type: "designer"
+  model: "sonnet"
+  description: "Designer review discovery plan"
+  prompt: |
+    Review this discovery plan for UI/UX considerations.
+    Focus on: user flows, accessibility, responsive design, missing UI requirements.
+    The discovery plan is at: [path to discovery.md]
 ```
 
 Present the feedback to the user. Refine the discovery document based on feedback.

package/template/commands/auto-plan.md

@@ -83,11 +83,9 @@ Before implementation begins, spawn the Designer agent to establish the visual f
 ```
 Use the Task tool with:
   subagent_type: "designer"
-  model: "opus"
+  model: "sonnet"
   description: "Create design language"
   prompt: |
-    **[Designer]**
-
     Establish the design language and style guide for this project.
 
     1. Check for existing design documentation:

package/template/skills/agent-coordination/SKILL.md

@@ -216,9 +216,8 @@ Agent: {role}
    - PR created with "Closes #{number}"
 
 3. Use Task tool with:
+   subagent_type: "developer"
    prompt: |
-     You are the Developer agent. Load your role from .claude/agents/developer/AGENT.md
-
      Read orchestration/issues/{number}-{slug}/BRIEFING-implement.md first.
 
      After completing your work, write your report to:
@@ -254,9 +253,8 @@ Agent: {role}
    - OR ❌ CHANGES REQUESTED - Architect
 
 2. Use Task tool with:
+   subagent_type: "architect"
    prompt: |
-     You are the Architect agent. Load your role from .claude/agents/architect/AGENT.md
-
      Read orchestration/issues/{number}-{slug}/BRIEFING-architect-review.md first.
 
      After completing your review, write your report to:
@@ -286,9 +284,8 @@ Agent: {role}
    Post design specifications as issue comment following AGENT.md template.
 
 2. Use Task tool with:
+   subagent_type: "designer"
    prompt: |
-     You are the Designer agent. Load your role from .claude/agents/designer/AGENT.md
-
      Read orchestration/issues/{number}-{slug}/BRIEFING-design-specs.md first.
 
      After completing your specs, write your report to:
@@ -324,9 +321,8 @@ Agent: {role}
    - OR N/A - No UI changes
 
 2. Use Task tool with:
+   subagent_type: "designer"
    prompt: |
-     You are the Designer agent. Load your role from .claude/agents/designer/AGENT.md
-
      Read orchestration/issues/{number}-{slug}/BRIEFING-designer-review.md first.
 
      After completing your review, write your report to:
@@ -362,9 +358,8 @@ Agent: {role}
    - OR ❌ CHANGES REQUESTED - Tester
 
 2. Use Task tool with:
+   subagent_type: "tester"
    prompt: |
-     You are the Tester agent. Load your role from .claude/agents/tester/AGENT.md
-
      Read orchestration/issues/{number}-{slug}/BRIEFING-test.md first.
 
      After completing verification, write your report to:

package/template/skills/work-issue/SKILL.md

@@ -168,7 +168,7 @@ Post design specifications as an issue comment following your AGENT.md template,
 ```
 Use the Task tool with:
   subagent_type: "designer"
-  model: "opus"
+  model: "sonnet"
   description: "Designer specs for issue #{ISSUE_NUMBER}"
   prompt: |
     Read orchestration/issues/{ISSUE_NUMBER}-{slug}/BRIEFING-design-specs.md first.
@@ -226,7 +226,7 @@ Implement issue #{ISSUE_NUMBER}: {title}
 ```
 Use the Task tool with:
   subagent_type: "developer"
-  model: "opus"
+  model: "sonnet"
   description: "Implement issue #{ISSUE_NUMBER}"
   prompt: |
     Read orchestration/issues/{ISSUE_NUMBER}-{slug}/BRIEFING-implement.md first.
@@ -342,7 +342,7 @@ Spawn all reviewers in parallel (single message, multiple Task calls):
 # Architect review
 Use the Task tool with:
   subagent_type: "architect"
-  model: "opus"
+  model: "sonnet"
   description: "Architect review PR #{pr_number}"
   prompt: |
     Read orchestration/issues/{ISSUE_NUMBER}-{slug}/BRIEFING-architect-review.md first.
@@ -353,7 +353,7 @@ Use the Task tool with:
 # Designer review (if UI)
 Use the Task tool with:
   subagent_type: "designer"
-  model: "opus"
+  model: "sonnet"
   description: "Designer review PR #{pr_number}"
   prompt: |
     Read orchestration/issues/{ISSUE_NUMBER}-{slug}/BRIEFING-designer-review.md first.
@@ -364,7 +364,7 @@ Use the Task tool with:
 # Tester verification
 Use the Task tool with:
   subagent_type: "tester"
-  model: "opus"
+  model: "sonnet"
   description: "Tester verify PR #{pr_number}"
   prompt: |
     Read orchestration/issues/{ISSUE_NUMBER}-{slug}/BRIEFING-test.md first.
@@ -428,7 +428,7 @@ Address review feedback on PR #{pr_number}.
 ```
 Use the Task tool with:
   subagent_type: "developer"
-  model: "opus"
+  model: "sonnet"
   description: "Address feedback PR #{pr_number}"
   prompt: |
     Read orchestration/issues/{ISSUE_NUMBER}-{slug}/BRIEFING-address-feedback.md first.