agent-eng 0.1.0 → 0.2.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.2.0",
   "description": "Scaffold a structured agentic engineering workflow for AI-assisted development",
   "type": "module",
   "bin": {

package/src/init.js

@@ -12,9 +12,11 @@ const STRUCTURE = [
   "prompts/architect.md",
   "prompts/planner.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

@@ -9,6 +9,7 @@ This project separates AI-assisted work into four roles. Each role has a dedicat
 | 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 |
@@ -21,9 +22,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,5 +1,5 @@
 name: Agentic Workflow
-description: Four-role pipeline for AI-assisted software engineering
+description: Five-role pipeline for AI-assisted software engineering
 
 agents:
   - id: architect
@@ -13,6 +13,17 @@ agents:
     color: indigo
     docLink: /prompts/architect.md
 
+  - id: system-architect
+    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
     title: Planner
     tagline: Decomposes specs into actionable work
@@ -48,9 +59,13 @@ 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

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