agent-eng 0.2.0 → 0.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-eng",
-  "version": "0.2.0",
+  "version": "0.4.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",
+  "tickets/_backlog.md",
+  "tickets/example/001-example-ticket.md",
   "orchestration.yaml",
   "architecture.yaml",
   "CLAUDE.md",

package/src/templates/CLAUDE.md

@@ -4,7 +4,7 @@ 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 |
 |------|--------|----------------|
@@ -12,7 +12,8 @@ This project separates AI-assisted work into four roles. Each role has a dedicat
 | **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
 
@@ -28,7 +29,7 @@ This project separates AI-assisted work into four roles. Each role has a dedicat
 - `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
+- `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
 

package/src/templates/orchestration.yaml

@@ -1,8 +1,9 @@
 name: Agentic Workflow
-description: Five-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.
@@ -14,6 +15,7 @@ agents:
     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.
@@ -25,6 +27,7 @@ agents:
     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.
@@ -36,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.
@@ -46,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
@@ -71,9 +88,13 @@ connections:
     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/planner.md

@@ -21,24 +21,39 @@ You are a planner agent. Your role is to decompose specs and ADRs into actionabl
 
 1. Read the spec or feature request
 2. Identify the relevant ADRs and conventions
-3. Break the work into logical chunks:
+3. Create a feature folder under `tickets/<feature-name>/`
+4. Break the work into logical chunks:
    - Start with infrastructure/setup if needed
    - Core functionality next
    - Edge cases and polish last
-4. For each chunk, create a ticket with:
+5. For each chunk, create a numbered ticket (`001-`, `002-`, ...) in the feature folder:
    - Clear context linking to the spec
    - A one-sentence goal
    - Testable acceptance criteria (checkboxes)
    - Explicit out-of-scope items
-5. Review the full set for gaps and dependencies
+6. Update `tickets/_backlog.md` with the new tickets in priority order
+7. Review the full set for gaps and dependencies
 
 ## Output Format
 
-Use the ticket template from `tickets/_template.md`:
+Use the ticket template from `tickets/_template.md`. Place tickets in feature folders:
+
+```
+tickets/
+├── _backlog.md                    ← sprint board
+├── _template.md                   ← ticket template
+├── auth/
+│   ├── 001-login-flow.md
+│   └── 002-signup-flow.md
+└── payments/
+    ├── 001-checkout.md
+    └── 002-refund.md
+```
 
 ```markdown
 # Ticket: Title
 
+**Feature:** feature-name
 **Status:** Todo
 **Priority:** P1
 **Estimate:** M

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/tickets/_backlog.md

@@ -0,0 +1,35 @@
+# Backlog
+
+Track and prioritize work across features. Move tickets between sections as they progress.
+
+## Current Sprint
+
+_Tickets actively being worked on this cycle._
+
+| Ticket | Feature | Priority | Status | Assignee |
+|--------|---------|----------|--------|----------|
+| | | | | |
+
+## Up Next
+
+_Tickets ready to be picked up in the next cycle._
+
+| Ticket | Feature | Priority | Estimate |
+|--------|---------|----------|----------|
+| | | | |
+
+## Backlog
+
+_Tickets that are planned but not yet scheduled._
+
+| Ticket | Feature | Priority | Estimate |
+|--------|---------|----------|----------|
+| | | | |
+
+## Done
+
+_Completed tickets. Move here when done, newest first._
+
+| Ticket | Feature | Completed |
+|--------|---------|-----------|
+| | | |

package/src/templates/tickets/_template.md

@@ -1,5 +1,6 @@
 # Ticket: Title
 
+**Feature:** feature-folder-name  
 **Status:** Todo | In Progress | In Review | Done  
 **Priority:** P0 | P1 | P2 | P3  
 **Estimate:** XS | S | M | L | XL  

package/src/templates/tickets/example/001-example-ticket.md

@@ -0,0 +1,38 @@
+# Ticket: Example Ticket
+
+**Feature:** example  
+**Status:** Todo  
+**Priority:** P1  
+**Estimate:** S  
+**Related:** ADR-0001
+
+## Context
+
+This is an example ticket inside a feature folder. Each feature gets its own directory under `tickets/`. Tickets within a feature are numbered sequentially (001, 002, ...) to indicate order.
+
+## Goal
+
+Demonstrate the ticket structure so new contributors know the format.
+
+## Acceptance Criteria
+
+- [ ] Criterion 1 — specific, testable condition
+- [ ] Criterion 2 — specific, testable condition
+- [ ] Tests pass
+- [ ] No lint errors
+
+## Out of Scope
+
+Anything not directly related to this feature.
+
+## Notes
+
+Delete this example folder when you create your first real feature.
+
+## Implementation Plan
+
+_To be filled in by the executor before starting work._
+
+1. Step 1
+2. Step 2
+3. Step 3