agent-eng 0.10.0 → 0.11.0

package/package.json

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

package/src/templates/.claude/agents/executor.md

@@ -1,12 +1,14 @@
 ---
 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.
+description: Use for complex tickets that need guided execution with strict verification. For most tickets, prefer Claude Code plan mode (shift+tab) instead — it explores, plans, and implements in one session. Use this agent when you need enforced discipline (plan-before-code, mandatory verification) or when plan mode is unavailable.
 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.
 
+> **Note:** For most tickets, Claude Code's built-in plan mode (`shift+tab`) is the recommended execution path — it provides faster context continuity and integrated exploration. This agent exists for cases where you need enforced discipline or are running execution as part of the full agent pipeline.
+
 ## Responsibilities
 
 1. **Read the ticket fully** — Understand the acceptance criteria, linked ADRs, and specs before writing any code

package/src/templates/.claude/agents/planner.md

@@ -5,7 +5,7 @@ tools: Read, Grep, Glob, Write, Edit
 model: sonnet
 ---
 
-You are a planner agent. Your role is to decompose specs and ADRs into actionable tickets.
+You are a planner agent. Your role is to decompose specs and ADRs into actionable tickets scoped for execution via Claude Code plan mode.
 
 ## Responsibilities
 
@@ -13,7 +13,7 @@ You are a planner agent. Your role is to decompose specs and ADRs into actionabl
 2. **Decompose work** — Break features into small, focused tickets
 3. **Define acceptance criteria** — Each ticket must have testable completion criteria
 4. **Sequence work** — Order tickets to minimize blocked dependencies
-5. **Scope appropriately** — Each ticket should be completable in one focused session
+5. **Scope for plan mode** — Each ticket should be completable in a single Claude Code plan mode session
 
 ## Constraints
 
@@ -21,6 +21,7 @@ You are a planner agent. Your role is to decompose specs and ADRs into actionabl
 - Each ticket should be **independently mergeable** where possible
 - Acceptance criteria must be **specific and testable**
 - Link tickets to relevant ADRs and specs
+- **Size tickets for plan mode** — a ticket should be achievable in one focused session with plan mode (typically S or M size). If a ticket would require multiple plan mode sessions, split it
 
 ## Process
 

package/src/templates/.claude/agents/reviewer.md

@@ -18,7 +18,7 @@ You are a reviewer agent. Your role is to review code changes against acceptance
 ## Constraints
 
 - You **review and comment**, you do not write code
-- You flag issues for the executor to fix
+- You flag issues to be fixed (via plan mode or the executor agent)
 - You reference specific lines and files
 - You cite the relevant ADR or convention when flagging violations
 

package/src/templates/CLAUDE.md

@@ -1,67 +1,65 @@
 # Project
 
-This project uses a structured agentic engineering workflow. Before starting any work, read this document and the relevant references below.
+This project uses a hybrid agentic workflow: specialized agents handle process (decisions, planning, review), and Claude Code's plan mode handles execution.
 
-## Workflow
+## Workflow — Hybrid Approach
 
-This project separates AI-assisted work into eight 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`.
+Agents own the **process** — architecture decisions, work decomposition, quality gates, and maintenance. Claude Code plan mode owns the **execution** — implementing individual tickets efficiently within a single session.
 
-| 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 |
-| **Summarizer** | `summarizer` | Generate executive summaries of completed sprints or features for stakeholders |
+| Phase | How | When |
+|-------|-----|------|
+| **Decide** | `/architect` agent | New feature, significant design choice, unclear requirements |
+| **Map** | `/system-architect` agent | New system or major structural change |
+| **Decompose** | `/planner` agent | ADR/spec ready, work needs to be broken into tickets |
+| **Execute** | Claude Code **plan mode** (`shift+tab`) | Implementing a specific ticket |
+| **Test** | `/qa-tester` agent | Feature implementation complete |
+| **Review** | `/reviewer` agent | Code and tests ready for validation |
+| **Maintain** | `/custodian` agent | After a batch of work, or CLAUDE.md > 200 lines |
+| **Report** | `/summarizer` agent | Sprint or feature complete, stakeholder update needed |
 
-## Sub-Agent Deployment
+### Why hybrid?
 
-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.
+- Agents enforce **separation of concerns** — the Architect can't write code, the Reviewer can't fix issues
+- Plan mode provides **speed and context continuity** — it explores, plans, and executes in one session
+- Artifacts (ADRs, tickets, reviews) **persist across sessions** — plan mode's output is code, agents' output is documentation
 
-### When to deploy sub-agents
+### Choosing the right tool
 
-- **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
+**Use an agent** when the task produces a persistent artifact (ADR, ticket, review, summary) or when role separation matters (the person deciding shouldn't be the person implementing).
 
-### Model selection
+**Use plan mode** when you have a well-scoped ticket with clear acceptance criteria and want to go from plan to working code in one session.
 
-Not every sub-agent needs the most powerful model. Choose the model based on task complexity:
+**Quick fixes and bug fixes** don't need the full pipeline — use plan mode directly, or just implement without ceremony. The workflow exists to help, not to slow down trivial changes.
 
-| 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 |
+## Before Starting Any Feature
 
-**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.
+1. Check if an ADR exists in `architecture/decisions/` — if not, run `/architect` first
+2. Check if tickets exist in `tickets/` — if not, run `/planner` first
+3. For each ticket: use plan mode (`shift+tab`) to implement it
+4. After implementation: run `/reviewer` to validate against acceptance criteria
+5. If the ticket touches an existing ADR's scope, verify the decision still holds
 
-### How to deploy
+## Before Starting Any Ticket (in plan mode)
 
-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
+1. Read the ticket fully, including all linked documents
+2. Read any referenced ADRs in `architecture/decisions/`
+3. Check relevant conventions in `conventions/`
+4. Let plan mode explore and propose the implementation plan
+5. Verify the work end-to-end before marking done
 
-### Rules
+## Sub-Agent Deployment
 
-- **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.
+When work can be parallelized, spin up sub-agents for independent tasks concurrently.
 
-## Before Starting Any Ticket
+### Model selection
 
-1. Read the ticket fully, including all linked documents
-2. Read any referenced ADRs in `architecture/decisions/`
-3. Check if there's a relevant spec in `specs/`
-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
+| Complexity | Model | Use when |
+|------------|-------|----------|
+| **Low** | Haiku | File lookups, grep, reading docs, running tests, formatting |
+| **Medium** | Sonnet | Multi-file changes, code review, writing tests |
+| **High** | Opus | Architecture decisions, complex refactors, subtle bugs |
+
+**Default to Haiku** unless the task requires multi-step reasoning or cross-file understanding.
 
 ## Key Files and Directories
 
@@ -71,11 +69,11 @@ 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
-- `.claude/agents/` — Subagent definitions for each role (Architect, Planner, Executor, etc.)
+- `.claude/agents/` — Subagent definitions for each 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.
+- **Context7** — Pulls up-to-date, version-specific documentation from live code libraries. Use `resolve` then `get-library-docs` before writing code that depends on a third-party library.
 
 ## Conventions
 

package/src/templates/architecture/decisions/0001-how-we-work.md

@@ -2,6 +2,7 @@
 
 **Status:** Accepted  
 **Date:** 2026-05-04  
+**Updated:** 2026-05-08  
 **Author:** swarpi
 
 ## Context
@@ -12,19 +13,40 @@ Working with AI coding assistants can be highly productive, but without structur
 - Lost context between sessions
 - No clear separation between planning and execution
 
-We need a workflow that maximizes the benefits of AI assistance while maintaining engineering rigor.
+We need a workflow that maximizes the benefits of AI assistance while maintaining engineering rigor. However, a fully agent-driven pipeline adds friction for execution — Claude Code's built-in plan mode is faster and maintains better context continuity when implementing well-scoped work.
 
 ## Decision
 
-We adopt a role-based workflow with four distinct agent modes:
+We adopt a **hybrid approach**: specialized agents own the process, Claude Code plan mode owns execution.
+
+### Agents (process)
 
 1. **Architect** — Focuses on design decisions. Produces ADRs. Asks clarifying questions before deciding. Has read access to the codebase but does not write code.
 
-2. **Planner** — Takes specs and ADRs as input. Decomposes work into tickets with clear acceptance criteria. Does not implement.
+2. **Planner** — Takes specs and ADRs as input. Decomposes work into tickets scoped for plan mode sessions. Does not implement.
+
+3. **QA Tester** — Writes automated tests after implementation. Covers acceptance criteria, edge cases, and regressions.
+
+4. **Reviewer** — Reviews diffs against acceptance criteria and linked ADRs. Checks for convention violations. Does not fix issues directly — flags them for fixing.
+
+5. **Custodian** — Keeps CLAUDE.md lean and current. Routes large content to external files.
+
+6. **Summarizer** — Produces non-technical executive summaries of completed work.
+
+### Plan mode (execution)
+
+Each ticket from the Planner is executed using Claude Code's plan mode (`shift+tab`). Plan mode:
+- Explores the codebase and proposes a plan before implementing
+- Executes within a single session with full context continuity
+- Adapts its depth to the task — simple ticket, simple plan
 
-3. **Executor** — Implements tickets. Follows conventions. References the ticket and relevant ADRs. Proposes a plan before coding.
+The **Executor agent** remains as a fallback for cases where plan mode is unavailable or strict verification discipline is needed.
 
-4. **Reviewer** — Reviews diffs against acceptance criteria and linked ADRs. Checks for convention violations. Does not fix issues directly — flags them for the executor.
+### When to skip the pipeline
+
+- Bug fixes, typos, and small changes → plan mode directly
+- Well-understood changes with no architectural implications → plan mode directly
+- New features or significant decisions → full pipeline starting with Architect
 
 All significant decisions are recorded as ADRs. All work items are tickets with acceptance criteria. Conventions are documented per-language.
 
@@ -35,14 +57,15 @@ All significant decisions are recorded as ADRs. All work items are tickets with
 - Clear separation of concerns reduces cognitive overload per session
 - ADRs create a searchable decision history
 - Tickets with acceptance criteria make "done" unambiguous
+- Plan mode provides fast, context-aware execution without agent switching overhead
 - Conventions prevent style drift across sessions
-- Role separation allows using different models for different tasks (e.g., larger model for architecture, faster model for execution)
+- The workflow adapts to task size — no ceremony for small changes
 
 ### Negative
 
-- More upfront documentation work
-- Overhead may feel excessive for small changes
-- Requires discipline to follow the process
+- More upfront documentation work for new features
+- Requires discipline to follow the process for larger changes
+- Plan mode doesn't produce persistent artifacts the way the Executor agent does
 
 ### Neutral
 
@@ -54,10 +77,14 @@ All significant decisions are recorded as ADRs. All work items are tickets with
 
 Just talk to the AI and let it write code directly. Rejected because it leads to inconsistent decisions and lost context.
 
-### Heavy-process frameworks (e.g., full Agile ceremony)
+### Fully agent-driven pipeline (previous approach)
 
-Too heavyweight for a solo developer. We take the useful parts (clear acceptance criteria, documented decisions) without the ceremony.
+All eight agents in sequence, including Executor for implementation. Rejected because plan mode provides better context continuity and speed for execution, and the Executor agent was frequently skipped by plan mode anyway.
+
+### Plan mode only (no agents)
 
-### Separate human architect with AI executor
+Use plan mode for everything. Rejected because plan mode doesn't enforce role separation (the same session that decides also implements), produces no persistent artifacts (ADRs, tickets, reviews), and doesn't scale to multi-session features.
 
-Keeps all design decisions with the human. Rejected because AI architects can surface alternatives humans wouldn't consider, and documenting the reasoning in ADRs preserves human oversight.
+### Heavy-process frameworks (e.g., full Agile ceremony)
+
+Too heavyweight for a solo developer. We take the useful parts (clear acceptance criteria, documented decisions) without the ceremony.

package/src/templates/architecture/overview.md

@@ -8,13 +8,25 @@ This document provides a high-level view of the system architecture.
 2. **Written artifacts** — Decisions, plans, and reviews are documented, not just discussed
 3. **Verify before execute** — Plans are reviewed before implementation begins
 4. **Single source of truth** — Each piece of information lives in one canonical place
+5. **Right tool for the job** — Agents own process; plan mode owns execution
 
-## The Flow
+## The Flow (Hybrid)
 
 ```
-Requirement → Architect → ADR/Spec → Planner → Tickets → Executor → Code → Reviewer → Merged
+Requirement → Architect → ADR/Spec → Planner → Tickets → Plan Mode → Code → Reviewer → Merged
+                (agent)                (agent)            (built-in)        (agent)
 ```
 
+**Process phases** (agents): Architect, System Architect, Planner, Reviewer, QA Tester, Custodian, Summarizer
+**Execution phase** (plan mode): Claude Code's built-in plan mode implements each ticket in a focused session
+
+## When to Skip the Pipeline
+
+Not every change needs the full workflow:
+- **Bug fix or typo** → Plan mode directly, or just implement
+- **Small well-understood change** → Plan mode directly
+- **New feature or significant decision** → Start with Architect, then full pipeline
+
 ## Artifact Types
 
 | Artifact | Purpose | Location |

package/src/templates/orchestration.yaml

@@ -1,5 +1,7 @@
-name: Agentic Workflow
-description: Eight-role pipeline for AI-assisted software engineering
+name: Hybrid Agentic Workflow
+description: >
+  Agents own the process (decisions, planning, review, maintenance).
+  Claude Code plan mode owns execution (implementing tickets).
 
 agents:
   - id: architect
@@ -29,8 +31,8 @@ agents:
   - 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.
+    tagline: Decomposes specs into plan-mode-sized tickets
+    description: Takes ADRs and specs as input. Decomposes work into discrete tickets scoped for a single Claude Code plan mode session.
     outputs:
       - Tickets
       - Milestones
@@ -38,23 +40,39 @@ agents:
     color: indigo
     docLink: /.claude/agents/planner.md
 
+  - id: plan-mode
+    kind: execution
+    title: Plan Mode
+    tagline: Claude Code's built-in plan-then-execute cycle
+    description: >
+      Not a custom agent — this is Claude Code's native plan mode (shift+tab).
+      It explores the codebase, proposes a plan, gets approval, then implements.
+      Each ticket from the Planner is executed as a separate plan mode session.
+    outputs:
+      - Code
+      - PRs
+    color: indigo
+    builtin: true
+
   - 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.
+    title: Executor (fallback)
+    tagline: Guided execution with strict verification
+    description: >
+      Fallback for when plan mode is unavailable or when enforced verification
+      discipline is needed. Most tickets should use plan mode instead.
     outputs:
       - Code
       - PRs
       - Plan docs
-    color: indigo
+    color: gray
     docLink: /.claude/agents/executor.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.
+    description: Writes automated tests after implementation. Covers acceptance criteria, edge cases, and regression scenarios.
     outputs:
       - Tests
       - Coverage report
@@ -66,7 +84,7 @@ agents:
     kind: validation
     title: Reviewer
     tagline: Validates against acceptance criteria
-    description: Validates code and tests 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 for fixing and provides final approval.
     outputs:
       - Feedback
       - Approval
@@ -78,7 +96,7 @@ agents:
     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.
+    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.
     outputs:
       - Updated CLAUDE.md
       - Extracted reference files
@@ -89,7 +107,7 @@ agents:
     kind: reporting
     title: Summarizer
     tagline: Communicates completed work to stakeholders
-    description: Reads tickets, ADRs, specs, git history, and test results to produce concise, non-technical executive summaries of what was delivered and why it matters.
+    description: Reads tickets, ADRs, specs, git history, and test results to produce concise, non-technical executive summaries.
     outputs:
       - Executive summaries
       - Sprint recaps
@@ -98,6 +116,7 @@ agents:
     docLink: /.claude/agents/summarizer.md
 
 connections:
+  # Process phase: agents produce artifacts
   - from: architect
     to: system-architect
     artifact: ADRs · Specs
@@ -106,23 +125,46 @@ connections:
     to: planner
     artifact: architecture.yaml
 
+  # Execution phase: plan mode implements tickets
+  - from: planner
+    to: plan-mode
+    artifact: Tickets
+    note: Each ticket becomes a separate plan mode session
+
+  # Fallback execution path
   - from: planner
     to: executor
     artifact: Tickets
+    type: fallback
+    note: Use when plan mode is unavailable
+
+  # Validation phase
+  - from: plan-mode
+    to: qa-tester
+    artifact: Code
 
   - from: executor
     to: qa-tester
     artifact: Code
+    type: fallback
 
   - from: qa-tester
     to: reviewer
     artifact: Code · Tests
 
+  # Feedback loops
+  - from: reviewer
+    to: plan-mode
+    artifact: Feedback
+    type: feedback
+    note: Fix issues in a new plan mode session
+
   - from: reviewer
     to: executor
     artifact: Feedback
     type: feedback
 
+  # Maintenance triggers
   - from: reviewer
     to: custodian
     artifact: Completed work context
@@ -137,6 +179,7 @@ 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.
+    Plan mode sessions run sequentially (one ticket at a time) unless tickets are independent.
   model-routing:
     low-complexity: haiku
     medium-complexity: sonnet
@@ -145,7 +188,7 @@ parallelization:
   examples:
     - parallel research across multiple files
     - running independent test suites simultaneously
-    - implementing tickets with no dependencies on each other
+    - independent tickets can be executed in separate plan mode sessions
     - concurrent verification (browser + console + tests)
 
 layout: diamond