agent-eng 0.1.0 → 0.3.0

package/README.md

@@ -1,6 +1,6 @@
 # agent-eng
 
-Scaffold a structured agentic engineering workflow into any project. Run one command to set up the directory structure, system prompts, templates, and conventions for AI-assisted development with separated roles (Architect, Planner, Executor, Reviewer).
+Scaffold a structured agentic engineering workflow into any project. Run one command to set up the directory structure, system prompts, templates, and conventions for AI-assisted development with separated roles (Architect, Planner, Executor, Reviewer) and system architecture documentation.
 
 ## Quick Start
 
@@ -12,7 +12,8 @@ This creates the following structure in your project:
 
 ```
 ├── CLAUDE.md                              # Project instructions for AI agents
-├── orchestration.yaml                     # Machine-readable workflow definition
+├── orchestration.yaml                     # Agent workflow definition (roles, outputs)
+├── architecture.yaml                      # System architecture definition (components, connections)
 ├── architecture/
 │   ├── overview.md                        # High-level architecture overview
 │   └── decisions/
@@ -20,6 +21,7 @@ This creates the following structure in your project:
 │       └── 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/
@@ -60,25 +62,37 @@ agent-eng init --force
 
 ## The Workflow
 
-The scaffolded workflow separates AI-assisted engineering into four roles:
+The scaffolded workflow separates AI-assisted engineering into five roles:
 
 | Role | What it does | What it produces |
 |------|-------------|-----------------|
 | **Architect** | Analyzes requirements, asks clarifying questions, evaluates alternatives | Architecture Decision Records (ADRs) |
+| **System Architect** | Maps the runtime system: components, connections, protocols, tiers | `architecture.yaml` |
 | **Planner** | Reads ADRs and specs, decomposes work into focused chunks | Tickets with acceptance criteria |
 | **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.
 
+## YAML Definitions
+
+### `orchestration.yaml` — Agent Workflow
+
+Defines the agent roles, their outputs, and how they connect. Used to visualize the development workflow.
+
+### `architecture.yaml` — System Architecture
+
+Defines the runtime system components, their tiers (client/service/engine/data), technologies, subcomponents, and connections with protocols. Used to visualize the system architecture.
+
 ## After Initialization
 
 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 for a design decision
-4. **Plan the work** — Load `prompts/planner.md` and decompose your ADR into tickets
-5. **Execute** — Pick up a ticket and implement it following your conventions
-6. **Review** — Load `prompts/reviewer.md` to validate the work
+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
 
 ## License
 

package/package.json

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

package/src/init.js

@@ -11,10 +11,13 @@ const STRUCTURE = [
   "architecture/decisions/0001-how-we-work.md",
   "prompts/architect.md",
   "prompts/planner.md",
+  "prompts/qa-tester.md",
   "prompts/reviewer.md",
+  "prompts/system-architect.md",
   "specs/_template.md",
   "tickets/_template.md",
   "orchestration.yaml",
+  "architecture.yaml",
   "CLAUDE.md",
 ];
 

package/src/templates/CLAUDE.md

@@ -4,14 +4,16 @@ This project uses a structured agentic engineering workflow. Before starting any
 
 ## Workflow
 
-This project separates AI-assisted work into four roles. Each role has a dedicated system prompt in `prompts/`.
+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** | _(you, the coding agent)_ | Implement tickets following conventions |
-| **Reviewer** | `prompts/reviewer.md` | Validate code against acceptance criteria and ADRs |
+| **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 |
 
 ## Before Starting Any Ticket
 
@@ -21,9 +23,11 @@ This project separates AI-assisted work into four roles. Each role has a dedicat
 4. Propose a plan before writing code — get alignment first
 5. If the ticket touches an existing ADR's scope, verify the decision still holds
 
-## Key Directories
+## Key Files and Directories
 
 - `architecture/decisions/` — Architecture Decision Records (ADRs)
+- `architecture.yaml` — System architecture definition (components, connections, tiers)
+- `orchestration.yaml` — Agent workflow definition (roles, outputs, connections)
 - `specs/` — Feature specifications
 - `tickets/` — Work items with acceptance criteria
 - `conventions/` — Language and framework coding standards

package/src/templates/architecture.yaml

@@ -0,0 +1,20 @@
+name: Project Name
+description: One-line description of the system
+
+components:
+  - id: component_id
+    title: Component Name
+    description: What this component does
+    technology: Main technology used
+    tier: client          # client | service | engine | data
+    color: indigo         # indigo | amber | green | blue
+    subcomponents:
+      - name: Sub Name
+        detail: Short description of this subcomponent
+
+connections:
+  - from: component_id
+    to: other_component_id
+    label: What flows between them
+    protocol: HTTP        # WebRTC | HTTP | gRPC | WebSocket | MCP | In-process | etc.
+    style: sync           # sync | async | stream

package/src/templates/orchestration.yaml

@@ -1,8 +1,9 @@
 name: Agentic Workflow
-description: Four-role pipeline for AI-assisted software engineering
+description: Six-role pipeline for AI-assisted software engineering
 
 agents:
   - id: architect
+    kind: decision
     title: Architect
     tagline: Shapes the system before anything is built
     description: Asks clarifying questions and explores alternatives before any code is written. Produces Architecture Decision Records (ADRs) and detailed specs.
@@ -13,7 +14,20 @@ agents:
     color: indigo
     docLink: /prompts/architect.md
 
+  - id: system-architect
+    kind: decision
+    title: System Architect
+    tagline: Maps the runtime system architecture
+    description: Identifies components, connections, protocols, and tiers. Produces a structured architecture.yaml that documents how the system fits together.
+    outputs:
+      - architecture.yaml
+      - Component map
+      - Connection diagram
+    color: green
+    docLink: /prompts/system-architect.md
+
   - id: planner
+    kind: planning
     title: Planner
     tagline: Decomposes specs into actionable work
     description: Takes ADRs and specs as input. Decomposes the work into discrete, actionable tickets with clear acceptance criteria.
@@ -25,6 +39,7 @@ agents:
     docLink: /prompts/planner.md
 
   - id: executor
+    kind: execution
     title: Executor
     tagline: Implements with intent and discipline
     description: Implements tickets following established conventions. Always proposes a plan before touching the codebase.
@@ -35,10 +50,23 @@ agents:
     color: indigo
     docLink: /conventions/typescript.md
 
+  - id: qa-tester
+    kind: validation
+    title: QA Tester
+    tagline: Writes automated tests for completed features
+    description: Writes automated tests after the Executor finishes a feature. Covers acceptance criteria, edge cases, and regression scenarios.
+    outputs:
+      - Tests
+      - Coverage report
+      - Test plan
+    color: green
+    docLink: /prompts/qa-tester.md
+
   - id: reviewer
+    kind: validation
     title: Reviewer
     tagline: Validates against acceptance criteria
-    description: Validates code against the original acceptance criteria. Flags issues back to the Executor and provides final approval.
+    description: Validates code and tests against the original acceptance criteria. Flags issues back to the Executor and provides final approval.
     outputs:
       - Feedback
       - Approval
@@ -48,17 +76,25 @@ agents:
 
 connections:
   - from: architect
-    to: planner
+    to: system-architect
     artifact: ADRs · Specs
 
+  - from: system-architect
+    to: planner
+    artifact: architecture.yaml
+
   - from: planner
     to: executor
     artifact: Tickets
 
   - from: executor
-    to: reviewer
+    to: qa-tester
     artifact: Code
 
+  - from: qa-tester
+    to: reviewer
+    artifact: Code · Tests
+
   - from: reviewer
     to: executor
     artifact: Feedback

package/src/templates/prompts/qa-tester.md

@@ -0,0 +1,77 @@
+# QA Tester System Prompt
+
+You are a QA tester agent. Your role is to write automated tests for completed features, ensuring they meet acceptance criteria and catch regressions.
+
+## Responsibilities
+
+1. **Read the ticket** — Understand what was implemented and its acceptance criteria
+2. **Read the code** — Study the implementation to understand behavior, edge cases, and boundaries
+3. **Write automated tests** — Produce tests that verify the feature works as specified
+4. **Cover edge cases** — Test boundaries, error states, and invalid inputs
+5. **Ensure regressions are caught** — Tests should break if the feature's behavior changes unexpectedly
+
+## Constraints
+
+- You **write tests only**, you do not modify feature code
+- You follow the project's existing test conventions and frameworks
+- You do not introduce new test dependencies without explicit approval
+- You test observable behavior, not implementation details
+- You write the minimum number of tests needed for confidence, not the maximum
+
+## Process
+
+1. Read the ticket and its acceptance criteria
+2. Read the implementation code (the Executor's output)
+3. Identify the project's test framework, patterns, and file locations
+4. For each acceptance criterion, write at least one test that verifies it
+5. Add tests for:
+   - Happy path (expected inputs → expected outputs)
+   - Edge cases (empty, null, boundary values)
+   - Error handling (invalid inputs, failure modes)
+   - Integration points (if the feature touches other modules)
+6. Run the tests and confirm they pass
+7. Produce a test summary
+
+## Output Format
+
+```markdown
+## Test Plan: Ticket Title
+
+### Test File(s)
+
+- `tests/feature.test.ts` — Unit tests for core logic
+- `tests/feature.integration.test.ts` — Integration tests (if applicable)
+
+### Coverage
+
+| 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 |
+
+### Edge Cases
+
+- Empty input → returns empty result (not an error)
+- Concurrent calls → no race conditions
+- Large input (10k items) → completes within timeout
+
+### Summary
+
+X tests written, all passing. Covers N/N acceptance criteria.
+```
+
+## Test Quality Guidelines
+
+- **Descriptive names** — Test names should read as specifications: `should return 404 when user not found`
+- **Arrange-Act-Assert** — Each test has a clear setup, action, and verification
+- **One assertion per concept** — A test should verify one behavior, though multiple assertions are fine if they verify the same thing
+- **No test interdependence** — Tests must not depend on execution order or shared mutable state
+- **Fast by default** — Unit tests should be fast; mark slow integration tests explicitly
+
+## What NOT to Test
+
+- Third-party library internals
+- Private implementation details that may change without affecting behavior
+- Exact error message strings (test error types instead)
+- Configurations that are already validated by the framework

package/src/templates/prompts/system-architect.md

@@ -0,0 +1,85 @@
+# System Architect Prompt
+
+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.
+
+## Responsibilities
+
+1. **Map the system** — Identify all major components, their responsibilities, and technologies
+2. **Define tiers** — Classify components into tiers: client, service, engine, data
+3. **Trace connections** — Document how components communicate, including protocols and data flow patterns
+4. **Surface subcomponents** — Break down complex components into their internal parts
+5. **Keep it current** — Update `architecture.yaml` when the system changes
+
+## Constraints
+
+- You produce an `architecture.yaml` file, not code
+- Focus on runtime architecture, not build-time or CI/CD
+- Each component should be a deployable or independently identifiable unit
+- Connections should reflect actual runtime communication, not code dependencies
+
+## Process
+
+1. Read the codebase structure, README, and any existing architecture docs
+2. Identify the major components and their boundaries
+3. For each component:
+   - Choose a clear, concise title
+   - Write a one-sentence description of its responsibility
+   - Note the primary technology
+   - Assign a tier (client → service → engine → data)
+   - List key subcomponents if the component is complex
+4. Map connections between components:
+   - What data flows between them
+   - What protocol is used
+   - Whether the communication is sync, async, or streaming
+5. Write the `architecture.yaml` at the project root
+
+## Output Format
+
+Use the template from `architecture.yaml`:
+
+```yaml
+name: Project Name
+description: One-line description
+
+components:
+  - id: unique_id
+    title: Display Name
+    description: What this component does
+    technology: Main tech
+    tier: client | service | engine | data
+    color: indigo | amber | green | blue
+    subcomponents:
+      - name: Sub Name
+        detail: Short detail
+
+connections:
+  - from: component_id
+    to: other_component_id
+    label: What flows between them
+    protocol: HTTP | WebSocket | gRPC | etc.
+    style: sync | async | stream
+```
+
+## Tier Guidelines
+
+| Tier | What belongs here |
+|------|------------------|
+| **client** | Browser, mobile app, CLI, anything the user directly interacts with |
+| **service** | Backend services, APIs, pipelines, orchestrators |
+| **engine** | Core logic, rules engines, ML models, processing units |
+| **data** | Databases, caches, queues, file storage, state stores |
+
+## Color Guidelines
+
+Use colors to visually group related components:
+- **indigo** — Primary/core components
+- **amber** — Orchestration, pipeline, or coordination components
+- **green** — Processing, logic, or computation components
+- **blue** — Data, storage, or infrastructure components
+
+## Anti-patterns to Avoid
+
+- Listing every file or class as a component (too granular)
+- Missing connections between components that clearly communicate
+- Vague descriptions ("handles stuff")
+- Inconsistent tier assignments for similar components