agent-eng 0.5.0 → 0.7.0

package/README.md

@@ -14,16 +14,21 @@ 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.5.0",
+  "version": "0.7.0",
   "description": "Scaffold a structured agentic engineering workflow for AI-assisted development",
   "type": "module",
   "bin": {

package/src/init.js

@@ -6,17 +6,18 @@ const __dirname = dirname(fileURLToPath(import.meta.url));
 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",
@@ -83,6 +84,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/.github/workflows/notify-site.yml

@@ -0,0 +1,21 @@
+name: Notify Site of Content Update
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - 'orchestration.yaml'
+      - 'architecture.yaml'
+      - 'README.md'
+
+jobs:
+  notify:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Trigger site rebuild
+        uses: peter-evans/repository-dispatch@v3
+        with:
+          token: ${{ secrets.SITE_REBUILD_TOKEN }}
+          repository: swarpi/swarpi.github.io
+          event-type: showcase-updated

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
@@ -83,7 +83,7 @@ agents:
       - Updated CLAUDE.md
       - Extracted reference files
     color: gray
-    docLink: /prompts/custodian.md
+    docLink: /.claude/agents/custodian.md
 
 connections:
   - from: architect