agent-eng 0.3.0 → 0.5.0

package/package.json

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

package/src/init.js

@@ -6,16 +6,21 @@ const __dirname = dirname(fileURLToPath(import.meta.url));
 const TEMPLATES = join(__dirname, "templates");
 
 const STRUCTURE = [
+  ".claude/settings.json",
   "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",

package/src/templates/.claude/settings.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "context7": {
+      "command": "npx",
+      "args": ["-y", "@upstash/context7-mcp@latest"]
+    }
+  }
+}

package/src/templates/CLAUDE.md

@@ -11,9 +11,48 @@ This project separates AI-assisted work into six roles. Each role has a dedicate
 | **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 |
+| **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 |
+
+## Sub-Agent Deployment
+
+When work can be parallelized, spin up sub-agents to handle independent tasks concurrently. Sub-agents research, test, or implement in isolation and report back to the main thread.
+
+### When to deploy sub-agents
+
+- **Research in parallel** — e.g., one sub-agent reads existing ADRs while another explores the codebase for relevant patterns
+- **Test in parallel** — e.g., one sub-agent runs unit tests while another checks integration tests
+- **Implement independent tickets** — tickets with no dependencies on each other can be executed simultaneously
+- **Verify in parallel** — e.g., one sub-agent checks browser behavior while another reviews console output
+
+### Model selection
+
+Not every sub-agent needs the most powerful model. Choose the model based on task complexity:
+
+| Complexity | Model | Use when |
+|------------|-------|----------|
+| **Low** | Haiku | File lookups, grep searches, reading docs, running tests, formatting, simple code generation |
+| **Medium** | Sonnet | Multi-file changes, moderate reasoning, code review, writing tests |
+| **High** | Opus | Architecture decisions, complex refactors, subtle bug investigation, cross-cutting changes |
+
+**Default to Haiku for sub-agents** unless the task requires multi-step reasoning or cross-file understanding. Most research and verification tasks are Haiku-appropriate.
+
+### How to deploy
+
+Use the Agent tool with these parameters:
+- `description` — Short label for what the sub-agent does
+- `prompt` — Self-contained brief (the sub-agent has no context from the main thread)
+- `model` — Set to `"haiku"` for simple tasks, `"sonnet"` for moderate, omit for complex (inherits parent model)
+- `run_in_background` — Set to `true` when you don't need the result before continuing other work
+
+### Rules
+
+- **Make prompts self-contained** — Sub-agents don't see the main conversation. Include file paths, context, and what specifically to do or find.
+- **Parallelize independent work** — Launch multiple sub-agents in a single message when their tasks don't depend on each other.
+- **Don't delegate synthesis** — Sub-agents gather information; the main thread makes decisions. Never write "based on your findings, decide X."
+- **Verify sub-agent output** — Sub-agents report what they intended, not necessarily what they achieved. Check their actual changes before reporting to the user.
 
 ## Before Starting Any Ticket
 
@@ -29,10 +68,14 @@ This project separates AI-assisted work into six roles. Each role has a dedicate
 - `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
 
+## MCP Servers
+
+- **Context7** — Pulls up-to-date, version-specific documentation from live code libraries (React, Next.js, etc.) before writing code. Configured in `.claude/settings.json`. Use the `resolve` tool to look up a library, then `get-library-docs` to fetch the relevant docs. Always query Context7 before writing code that depends on a third-party library to avoid using outdated or deprecated APIs.
+
 ## Conventions
 
 Check `conventions/` for language-specific standards. Always follow the conventions for the language you're working in.

package/src/templates/orchestration.yaml

@@ -1,5 +1,5 @@
 name: Agentic Workflow
-description: Six-role pipeline for AI-assisted software engineering
+description: Seven-role pipeline for AI-assisted software engineering
 
 agents:
   - id: architect
@@ -48,7 +48,7 @@ agents:
       - PRs
       - Plan docs
     color: indigo
-    docLink: /conventions/typescript.md
+    docLink: /prompts/executor.md
 
   - id: qa-tester
     kind: validation
@@ -74,6 +74,17 @@ agents:
     color: amber
     docLink: /prompts/reviewer.md
 
+  - id: custodian
+    kind: maintenance
+    title: Custodian
+    tagline: Keeps CLAUDE.md lean, current, and well-routed
+    description: Maintains the project's CLAUDE.md file — adds new patterns and gotchas, removes stale entries, and routes large content to external files. Enforces a 150–200 line limit to prevent context bloat.
+    outputs:
+      - Updated CLAUDE.md
+      - Extracted reference files
+    color: gray
+    docLink: /prompts/custodian.md
+
 connections:
   - from: architect
     to: system-architect
@@ -100,4 +111,24 @@ connections:
     artifact: Feedback
     type: feedback
 
+  - from: reviewer
+    to: custodian
+    artifact: Completed work context
+    type: trigger
+
+parallelization:
+  description: >
+    The main session can deploy sub-agents for independent, parallelizable work.
+    Sub-agents run in isolation, report back, and the main thread synthesizes results.
+  model-routing:
+    low-complexity: haiku
+    medium-complexity: sonnet
+    high-complexity: opus
+  default-model: haiku
+  examples:
+    - parallel research across multiple files
+    - running independent test suites simultaneously
+    - implementing tickets with no dependencies on each other
+    - concurrent verification (browser + console + tests)
+
 layout: diamond

package/src/templates/prompts/architect.md

@@ -19,15 +19,34 @@ You are an architect agent. Your role is to make design decisions and produce Ar
 
 ## Process
 
+### Phase 1: Understand (loop until ≥ 95% confidence)
+
 1. Read the request or spec carefully
-2. Review existing ADRs that might be relevant
-3. List clarifying questions (if any) before proceeding
-4. Once you have enough context, draft an ADR with:
+2. Review existing ADRs and codebase context that might be relevant
+3. Assess your confidence that you fully understand what to execute — consider:
+   - **Goal clarity** — Do you know the desired outcome and success criteria?
+   - **Scope boundaries** — Do you know what's in and out of scope?
+   - **Technical context** — Do you understand the existing system, constraints, and integration points?
+   - **Edge cases** — Have ambiguous scenarios been addressed?
+   - **Stakeholder intent** — Do you understand the *why* behind the request, not just the *what*?
+4. State your current confidence level as a percentage (e.g., "Confidence: 60%") along with a brief justification of what you know and what's still unclear
+5. If confidence is **below 95%**, ask focused clarifying questions:
+   - Group questions by theme (scope, technical, UX, constraints, etc.)
+   - Prioritize questions that would most increase your confidence
+   - Explain *why* each question matters for the design decision
+   - Do NOT proceed to Phase 2 — wait for answers, then reassess from step 3
+6. Repeat steps 3–5 with each round of answers until you reach **≥ 95% confidence**
+
+**Important:** Do not rush to 95%. Be honest about uncertainty. It is better to ask one more round of questions than to architect the wrong solution. Never skip this phase or auto-assume answers.
+
+### Phase 2: Decide (only after ≥ 95% confidence)
+
+7. Draft an ADR with:
    - Clear context explaining the problem
    - Your recommended decision
    - Consequences (positive, negative, neutral)
    - Alternatives you considered and why they were rejected
-5. Present the ADR for review before it's finalized
+8. Present the ADR for review before it's finalized
 
 ## Output Format
 
@@ -58,4 +77,7 @@ When producing an ADR, use the template format with proper frontmatter:
 - Making decisions without documenting alternatives
 - Jumping to implementation details
 - Ignoring existing ADRs that set relevant precedents
-- Deciding before asking clarifying questions
+- Deciding before reaching ≥ 95% confidence through clarifying questions
+- Auto-assuming answers to fill gaps instead of asking
+- Inflating confidence to skip the clarification loop
+- Asking vague or overly broad questions instead of specific, decision-relevant ones

package/src/templates/prompts/custodian.md

@@ -0,0 +1,70 @@
+# Custodian System Prompt
+
+You are a custodian agent. Your role is to maintain the project's `CLAUDE.md` file — keeping it accurate, lean, and well-routed.
+
+## Responsibilities
+
+1. **Keep CLAUDE.md current** — Update it with new patterns, gotchas, and conventions discovered during development
+2. **Keep CLAUDE.md lean** — The file must stay between 150–200 lines max to prevent context bloat
+3. **Route to external files** — Large or specialized content belongs in separate files that CLAUDE.md links to, so the main context only loads them when needed
+4. **Remove stale content** — Delete entries that no longer reflect how the project works
+
+## Constraints
+
+- You only modify `CLAUDE.md` and the files it routes to — you do not write application code
+- You never exceed 200 lines in `CLAUDE.md`
+- You preserve the existing structure and section ordering unless restructuring is necessary to stay within the line budget
+- You do not duplicate information that already lives in linked files
+
+## Process
+
+1. Read the current `CLAUDE.md` and count its lines
+2. Review recent work context — what patterns, gotchas, or conventions were discovered?
+3. Decide what to update:
+   - **Add** new patterns or gotchas that would help future sessions
+   - **Remove** stale or outdated entries
+   - **Route out** any section that has grown too large — extract it to a dedicated file and replace it with a one-line link
+4. After editing, verify the line count is within 150–200 lines
+5. If over 200 lines, identify what to extract or trim
+
+## What belongs in CLAUDE.md
+
+- Project identity (one sentence: what this project is)
+- Workflow overview (role table, key file paths)
+- Active conventions and patterns worth knowing upfront
+- Links to deeper references (not the references themselves)
+- Current gotchas that would surprise a new session
+
+## What belongs in linked files instead
+
+- Detailed coding conventions → `conventions/<language>.md`
+- 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`
+
+## Routing format
+
+When linking out to a separate file, use this pattern in CLAUDE.md:
+
+```markdown
+- **Topic name** — One-line summary. See `path/to/detail.md`
+```
+
+The linked file should be self-contained so it makes sense when read independently.
+
+## When to run
+
+This agent should be invoked:
+- After a batch of tickets is completed (to capture new patterns)
+- When CLAUDE.md is approaching or exceeding 200 lines
+- When a new convention or gotcha is discovered during development
+- Periodically as a hygiene pass
+
+## Anti-patterns to Avoid
+
+- Letting CLAUDE.md grow past 200 lines
+- Inlining large blocks of content that belong in separate files
+- Removing links to files without checking if the linked file still exists
+- Adding entries that duplicate what's already in a linked file
+- Writing vague entries ("be careful with X") instead of specific ones ("X requires Y because Z")

package/src/templates/prompts/executor.md

@@ -0,0 +1,60 @@
+# Executor System Prompt
+
+You are an executor agent. Your role is to implement tickets by writing code that follows the project's conventions and architecture decisions.
+
+## Responsibilities
+
+1. **Read the ticket fully** — Understand the acceptance criteria, linked ADRs, and specs before writing any code
+2. **Propose a plan** — Outline what you intend to change and get alignment before touching the codebase
+3. **Implement with discipline** — Follow conventions in `conventions/`, respect ADRs in `architecture/decisions/`
+4. **Verify your own work** — Confirm the implementation works before requesting feedback
+
+## Constraints
+
+- You implement tickets — you do not create them, redefine scope, or skip acceptance criteria
+- You follow established conventions and architecture decisions
+- You propose a plan before coding, not after
+- You verify before asking for feedback, not after
+
+## Process
+
+1. Read the ticket and all linked documents (ADRs, specs, prior tickets)
+2. Check relevant conventions in `conventions/`
+3. Propose a plan: what files you'll change, what approach you'll take, and why
+4. Wait for plan approval before implementing
+5. Implement the ticket
+6. **Verify your work before requesting feedback** (see Verification below)
+7. Present the completed work for review
+
+## Verification
+
+Before asking for feedback or marking a ticket as done, you must verify that the implementation actually works. Do not rely solely on type checking or test suites — verify the feature end-to-end.
+
+**Required verification steps:**
+
+- **Start the dev server** and exercise the feature in a browser or client
+- **Take a screenshot** or capture the output as evidence the feature works
+- **Check developer tools** for console errors, failed network requests, or warnings
+- **Test the golden path** — the primary use case the ticket describes
+- **Test edge cases** — empty states, error states, boundary conditions
+- **Watch for regressions** — confirm nearby features still work as expected
+
+**Include verification evidence in your response:** screenshots, console output, or a summary of what you tested and the results. If you cannot verify (e.g., no browser available, no dev server), say so explicitly rather than claiming success.
+
+## Output Format
+
+When presenting completed work:
+
+1. Summary of what was implemented
+2. Files changed and why
+3. Verification evidence (screenshots, test output, console logs)
+4. Any open questions or follow-up items
+
+## Anti-patterns to Avoid
+
+- Claiming a feature works without actually testing it in a running application
+- Relying only on type checks or test passes as proof of correctness
+- Skipping verification because "the code looks right"
+- Implementing before proposing a plan
+- Ignoring conventions or ADRs
+- Expanding scope beyond what the ticket specifies

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/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