agent-eng 0.6.0 → 0.8.0

package/README.md

@@ -8,22 +8,27 @@ Scaffold a structured agentic engineering workflow into any project. Run one com
 npx agent-eng init
 ```
 
-This creates the following structure in your project:
+This creates the following structure in your project: 
 
 ```
 ├── CLAUDE.md                              # Project instructions for AI agents
 ├── orchestration.yaml                     # Agent workflow definition (roles, outputs)
 ├── architecture.yaml                      # System architecture definition (components, connections)
+├── .claude/
+│   ├── settings.json                      # Claude Code project settings (MCP servers)
+│   └── agents/                            # Auto-wired Claude Code subagents — invoke via Agent tool
+│       ├── architect.md
+│       ├── system-architect.md
+│       ├── planner.md
+│       ├── executor.md
+│       ├── qa-tester.md
+│       ├── reviewer.md
+│       └── custodian.md
 ├── architecture/
 │   ├── overview.md                        # High-level architecture overview
 │   └── decisions/
 │       ├── _template.md                   # ADR template
 │       └── 0001-how-we-work.md            # Seed ADR: the workflow itself
-├── prompts/
-│   ├── architect.md                       # System prompt for the Architect role
-│   ├── system-architect.md                # System prompt for system architecture mapping
-│   ├── planner.md                         # System prompt for the Planner role
-│   └── reviewer.md                        # System prompt for the Reviewer role
 ├── specs/
 │   └── _template.md                       # Feature specification template
 ├── tickets/
@@ -72,7 +77,7 @@ The scaffolded workflow separates AI-assisted engineering into five roles:
 | **Executor** | Implements tickets following conventions, proposes plan first | Code and PRs |
 | **Reviewer** | Validates code against acceptance criteria and ADRs | Approval or actionable feedback |
 
-Each role has a dedicated system prompt in `prompts/` that you can load into your AI assistant to set the context for that type of work.
+Each role is wired as a Claude Code subagent in `.claude/agents/`. Invoke them via the Agent tool (`subagent_type: "architect"`, etc.), or just describe the task — Claude will route to the right subagent based on each agent's `description` frontmatter.
 
 ## YAML Definitions
 
@@ -88,11 +93,11 @@ Defines the runtime system components, their tiers (client/service/engine/data),
 
 1. **Review `CLAUDE.md`** — Customize the project instructions for your specific project
 2. **Pick your conventions** — Keep the ones that match your stack, remove the rest
-3. **Start with the Architect** — Load `prompts/architect.md` and create your first ADR
-4. **Map the system** — Load `prompts/system-architect.md` and create your `architecture.yaml`
-5. **Plan the work** — Load `prompts/planner.md` and decompose your ADR into tickets
-6. **Execute** — Pick up a ticket and implement it following your conventions
-7. **Review** — Load `prompts/reviewer.md` to validate the work
+3. **Start with the Architect** — Ask Claude to use the `architect` subagent to create your first ADR
+4. **Map the system** — Use the `system-architect` subagent to create your `architecture.yaml`
+5. **Plan the work** — Use the `planner` subagent to decompose your ADR into tickets
+6. **Execute** — Use the `executor` subagent to implement a ticket following your conventions
+7. **Test & Review** — Use the `qa-tester` and `reviewer` subagents to validate the work
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-eng",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "description": "Scaffold a structured agentic engineering workflow for AI-assisted development",
   "type": "module",
   "bin": {

package/src/index.js

@@ -18,7 +18,7 @@ Examples:
   agent-eng init --dir ./my-project --conventions java
 `;
 
-export function run(args) {
+export async function run(args) {
   const command = args[0];
 
   if (!command || command === "-h" || command === "--help") {
@@ -28,7 +28,7 @@ export function run(args) {
 
   if (command === "init") {
     const options = parseInitArgs(args.slice(1));
-    init(options);
+    await init(options);
     return;
   }
 

package/src/init.js

@@ -1,4 +1,5 @@
-import { cpSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { appendFileSync, cpSync, existsSync, mkdirSync, readFileSync } from "node:fs";
+import { createInterface } from "node:readline";
 import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 
@@ -8,26 +9,35 @@ const TEMPLATES = join(__dirname, "templates");
 const STRUCTURE = [
   ".github/workflows/notify-site.yml",
   ".claude/settings.json",
+  ".claude/agents/architect.md",
+  ".claude/agents/custodian.md",
+  ".claude/agents/executor.md",
+  ".claude/agents/planner.md",
+  ".claude/agents/qa-tester.md",
+  ".claude/agents/reviewer.md",
+  ".claude/agents/system-architect.md",
   "architecture/overview.md",
   "architecture/decisions/_template.md",
   "architecture/decisions/0001-how-we-work.md",
-  "prompts/architect.md",
-  "prompts/custodian.md",
-  "prompts/executor.md",
-  "prompts/planner.md",
-  "prompts/qa-tester.md",
-  "prompts/reviewer.md",
-  "prompts/system-architect.md",
   "specs/_template.md",
   "tickets/_template.md",
   "tickets/_backlog.md",
   "tickets/example/001-example-ticket.md",
   "orchestration.yaml",
   "architecture.yaml",
-  "CLAUDE.md",
 ];
 
-export function init(options) {
+function prompt(question) {
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  return new Promise((resolve) => {
+    rl.question(question, (answer) => {
+      rl.close();
+      resolve(answer.trim().toLowerCase());
+    });
+  });
+}
+
+export async function init(options) {
   const target = resolve(options.dir);
   const created = [];
   const skipped = [];
@@ -46,6 +56,34 @@ export function init(options) {
     created.push(file);
   }
 
+  // Handle CLAUDE.md separately — prompt user if it already exists
+  const claudeDest = join(target, "CLAUDE.md");
+  const claudeSrc = join(TEMPLATES, "CLAUDE.md");
+
+  if (!existsSync(claudeDest) || options.force) {
+    mkdirSync(dirname(claudeDest), { recursive: true });
+    cpSync(claudeSrc, claudeDest);
+    created.push("CLAUDE.md");
+  } else {
+    console.log("");
+    console.log("CLAUDE.md already exists.");
+    console.log("  1) Skip — keep existing file");
+    console.log("  2) Append — add agent-eng content to the end");
+    console.log("  3) Replace — overwrite with agent-eng template");
+    const answer = await prompt("Choose [1/2/3] (default: 1): ");
+
+    if (answer === "2" || answer === "append") {
+      const content = readFileSync(claudeSrc, "utf8");
+      appendFileSync(claudeDest, "\n\n" + content);
+      created.push("CLAUDE.md (appended)");
+    } else if (answer === "3" || answer === "replace") {
+      cpSync(claudeSrc, claudeDest);
+      created.push("CLAUDE.md (replaced)");
+    } else {
+      skipped.push("CLAUDE.md");
+    }
+  }
+
   for (const convention of options.conventions) {
     const file = `conventions/${convention}.md`;
     const dest = join(target, file);
@@ -84,7 +122,7 @@ export function init(options) {
   console.log("Next steps:");
   console.log("  1. Review CLAUDE.md and customize for your project");
   console.log("  2. Pick the conventions that match your stack");
-  console.log("  3. Start with the Architect: create your first ADR");
+  console.log("  3. Start with the Architect subagent: ask Claude to use the 'architect' agent to create your first ADR");
   console.log("  4. Add the SITE_REBUILD_TOKEN secret and 'showcase' topic to enable auto site rebuilds");
   console.log("");
 }

package/src/templates/{prompts → .claude/agents}/architect.md

@@ -1,4 +1,9 @@
-# Architect System Prompt
+---
+name: architect
+description: Use when the user wants to design a system, evaluate architectural alternatives, or produce an Architecture Decision Record (ADR). This agent asks clarifying questions before deciding and does not write application code.
+tools: Read, Grep, Glob, Write, Edit, WebFetch
+model: opus
+---
 
 You are an architect agent. Your role is to make design decisions and produce Architecture Decision Records (ADRs).
 
@@ -12,7 +17,7 @@ You are an architect agent. Your role is to make design decisions and produce Ar
 
 ## Constraints
 
-- You have **read access** to the codebase but **do not write code**
+- You have **read access** to the codebase but **do not write application code**
 - You produce ADRs, not implementations
 - You ask questions before making decisions, not after
 - You document tradeoffs, not just the chosen path

package/src/templates/{prompts → .claude/agents}/custodian.md

@@ -1,4 +1,9 @@
-# Custodian System Prompt
+---
+name: custodian
+description: Use periodically (after a batch of tickets, or when CLAUDE.md grows past 200 lines) to keep CLAUDE.md lean, current, and routed to external files. Modifies only CLAUDE.md and the files it links to.
+tools: Read, Write, Edit, Grep, Glob
+model: haiku
+---
 
 You are a custodian agent. Your role is to maintain the project's `CLAUDE.md` file — keeping it accurate, lean, and well-routed.
 
@@ -41,7 +46,7 @@ You are a custodian agent. Your role is to maintain the project's `CLAUDE.md` fi
 - Business context or domain knowledge → `docs/context/<topic>.md`
 - Style guides → `conventions/style.md` or similar
 - API contracts or integration details → `docs/<integration>.md`
-- Large workflow instructions → `prompts/<role>.md`
+- Large workflow / role instructions → `.claude/agents/<role>.md`
 
 ## Routing format
 

package/src/templates/{prompts → .claude/agents}/executor.md

@@ -1,4 +1,9 @@
-# Executor System Prompt
+---
+name: executor
+description: Use when the user wants to implement a specific ticket. Reads the ticket, proposes a plan first, then implements following project conventions and ADRs. Verifies work end-to-end before marking done.
+tools: Read, Write, Edit, Grep, Glob, Bash, WebFetch
+model: sonnet
+---
 
 You are an executor agent. Your role is to implement tickets by writing code that follows the project's conventions and architecture decisions.
 

package/src/templates/{prompts → .claude/agents}/planner.md

@@ -1,4 +1,9 @@
-# Planner System Prompt
+---
+name: planner
+description: Use when the user has an ADR or spec and wants it decomposed into actionable tickets with acceptance criteria. Produces tickets in feature folders and updates the backlog.
+tools: Read, Grep, Glob, Write, Edit
+model: sonnet
+---
 
 You are a planner agent. Your role is to decompose specs and ADRs into actionable tickets.
 

package/src/templates/{prompts → .claude/agents}/qa-tester.md

@@ -1,4 +1,9 @@
-# QA Tester System Prompt
+---
+name: qa-tester
+description: Use after a feature is implemented to write automated tests covering the acceptance criteria, edge cases, and regressions. Does not modify feature code.
+tools: Read, Write, Edit, Grep, Glob, Bash
+model: sonnet
+---
 
 You are a QA tester agent. Your role is to write automated tests for completed features, ensuring they meet acceptance criteria and catch regressions.
 
@@ -46,9 +51,9 @@ You are a QA tester agent. Your role is to write automated tests for completed f
 
 | Acceptance Criterion | Test(s) | Status |
 |---|---|---|
-| Criterion 1 | `should handle valid input` | ✅ Pass |
-| Criterion 2 | `should reject empty input`, `should reject null` | ✅ Pass |
-| Criterion 3 | `should return paginated results` | ✅ Pass |
+| Criterion 1 | `should handle valid input` | Pass |
+| Criterion 2 | `should reject empty input`, `should reject null` | Pass |
+| Criterion 3 | `should return paginated results` | Pass |
 
 ### Edge Cases
 

package/src/templates/{prompts → .claude/agents}/reviewer.md

@@ -1,4 +1,9 @@
-# Reviewer System Prompt
+---
+name: reviewer
+description: Use to review a diff or completed ticket against acceptance criteria, ADRs, and conventions. Flags issues with specific file:line references but does not fix them.
+tools: Read, Grep, Glob, Bash
+model: sonnet
+---
 
 You are a reviewer agent. Your role is to review code changes against acceptance criteria and architectural decisions.
 

package/src/templates/{prompts → .claude/agents}/system-architect.md

@@ -1,4 +1,9 @@
-# System Architect Prompt
+---
+name: system-architect
+description: Use when the user wants to map or update the runtime architecture of the project — components, tiers, connections, protocols. Produces or updates `architecture.yaml`.
+tools: Read, Grep, Glob, Write, Edit
+model: sonnet
+---
 
 You are a system architect agent. Your role is to define and document the system architecture of a project as a structured `architecture.yaml` file.
 

package/src/templates/CLAUDE.md

@@ -4,17 +4,17 @@ This project uses a structured agentic engineering workflow. Before starting any
 
 ## Workflow
 
-This project separates AI-assisted work into six roles. Each role has a dedicated system prompt in `prompts/`.
-
-| Role | Prompt | Responsibility |
-|------|--------|----------------|
-| **Architect** | `prompts/architect.md` | Analyze requirements, ask clarifying questions, produce ADRs |
-| **System Architect** | `prompts/system-architect.md` | Map and document system architecture as `architecture.yaml` |
-| **Planner** | `prompts/planner.md` | Decompose specs and ADRs into actionable tickets |
-| **Executor** | `prompts/executor.md` | Implement tickets, verify work before requesting feedback |
-| **QA Tester** | `prompts/qa-tester.md` | Write automated tests for completed features |
-| **Reviewer** | `prompts/reviewer.md` | Validate code and tests against acceptance criteria and ADRs |
-| **Custodian** | `prompts/custodian.md` | Keep CLAUDE.md lean (≤200 lines), current, and routed to external files |
+This project separates AI-assisted work into seven roles. Each role is a Claude Code subagent in `.claude/agents/` — invoke them via the Agent tool with `subagent_type: "<name>"` (e.g., `subagent_type: "architect"`). Claude will also auto-route work to the appropriate subagent based on each agent's `description`.
+
+| Role | Subagent | Responsibility |
+|------|----------|----------------|
+| **Architect** | `architect` | Analyze requirements, ask clarifying questions, produce ADRs |
+| **System Architect** | `system-architect` | Map and document system architecture as `architecture.yaml` |
+| **Planner** | `planner` | Decompose specs and ADRs into actionable tickets |
+| **Executor** | `executor` | Implement tickets, verify work before requesting feedback |
+| **QA Tester** | `qa-tester` | Write automated tests for completed features |
+| **Reviewer** | `reviewer` | Validate code and tests against acceptance criteria and ADRs |
+| **Custodian** | `custodian` | Keep CLAUDE.md lean (≤200 lines), current, and routed to external files |
 
 ## Sub-Agent Deployment
 
@@ -70,7 +70,7 @@ Use the Agent tool with these parameters:
 - `specs/` — Feature specifications
 - `tickets/` — Work items organized by feature folder, with `_backlog.md` as the sprint board
 - `conventions/` — Language and framework coding standards
-- `prompts/` — System prompts for each agent role
+- `.claude/agents/` — Subagent definitions for each role (Architect, Planner, Executor, etc.)
 
 ## MCP Servers
 

package/src/templates/orchestration.yaml

@@ -12,7 +12,7 @@ agents:
       - Specs
       - Constraints
     color: indigo
-    docLink: /prompts/architect.md
+    docLink: /.claude/agents/architect.md
 
   - id: system-architect
     kind: decision
@@ -24,7 +24,7 @@ agents:
       - Component map
       - Connection diagram
     color: green
-    docLink: /prompts/system-architect.md
+    docLink: /.claude/agents/system-architect.md
 
   - id: planner
     kind: planning
@@ -36,7 +36,7 @@ agents:
       - Milestones
       - Criteria
     color: indigo
-    docLink: /prompts/planner.md
+    docLink: /.claude/agents/planner.md
 
   - id: executor
     kind: execution
@@ -48,7 +48,7 @@ agents:
       - PRs
       - Plan docs
     color: indigo
-    docLink: /prompts/executor.md
+    docLink: /.claude/agents/executor.md
 
   - id: qa-tester
     kind: validation
@@ -60,7 +60,7 @@ agents:
       - Coverage report
       - Test plan
     color: green
-    docLink: /prompts/qa-tester.md
+    docLink: /.claude/agents/qa-tester.md
 
   - id: reviewer
     kind: validation
@@ -72,7 +72,7 @@ agents:
       - Approval
       - Notes
     color: amber
-    docLink: /prompts/reviewer.md
+    docLink: /.claude/agents/reviewer.md
 
   - id: custodian
     kind: maintenance
@@ -82,8 +82,8 @@ agents:
     outputs:
       - Updated CLAUDE.md
       - Extracted reference files
-    color: gray
-    docLink: /prompts/custodian.md
+    color: blue
+    docLink: /.claude/agents/custodian.md
 
 connections:
   - from: architect