agent-eng 0.1.0

package/README.md

@@ -0,0 +1,85 @@
+# 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).
+
+## Quick Start
+
+```bash
+npx agent-eng init
+```
+
+This creates the following structure in your project:
+
+```
+├── CLAUDE.md                              # Project instructions for AI agents
+├── orchestration.yaml                     # Machine-readable workflow definition
+├── architecture/
+│   ├── overview.md                        # High-level architecture overview
+│   └── decisions/
+│       ├── _template.md                   # ADR template
+│       └── 0001-how-we-work.md            # Seed ADR: the workflow itself
+├── prompts/
+│   ├── architect.md                       # System prompt for the Architect role
+│   ├── planner.md                         # System prompt for the Planner role
+│   └── reviewer.md                        # System prompt for the Reviewer role
+├── specs/
+│   └── _template.md                       # Feature specification template
+├── tickets/
+│   └── _template.md                       # Work ticket template
+└── conventions/
+    ├── typescript.md                      # TypeScript coding standards
+    ├── python.md                          # Python coding standards
+    └── java.md                            # Java coding standards
+```
+
+## Usage
+
+### Initialize with all conventions (default)
+
+```bash
+agent-eng init
+```
+
+### Pick specific conventions
+
+```bash
+agent-eng init --conventions typescript,python
+```
+
+### Initialize in a specific directory
+
+```bash
+agent-eng init --dir ./my-project
+```
+
+### Overwrite existing files
+
+```bash
+agent-eng init --force
+```
+
+## The Workflow
+
+The scaffolded workflow separates AI-assisted engineering into four roles:
+
+| Role | What it does | What it produces |
+|------|-------------|-----------------|
+| **Architect** | Analyzes requirements, asks clarifying questions, evaluates alternatives | Architecture Decision Records (ADRs) |
+| **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.
+
+## 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
+
+## License
+
+MIT

package/bin/agent-eng.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+
+import { run } from "../src/index.js";
+
+run(process.argv.slice(2));

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "agent-eng",
+  "version": "0.1.0",
+  "description": "Scaffold a structured agentic engineering workflow for AI-assisted development",
+  "type": "module",
+  "bin": {
+    "agent-eng": "./bin/agent-eng.js"
+  },
+  "files": [
+    "bin",
+    "src"
+  ],
+  "keywords": [
+    "ai",
+    "agents",
+    "workflow",
+    "cli",
+    "scaffold",
+    "adr",
+    "architecture"
+  ],
+  "author": "swarpi",
+  "license": "MIT"
+}

package/src/index.js

@@ -0,0 +1,74 @@
+import { init } from "./init.js";
+
+const HELP = `
+agent-eng — scaffold an agentic engineering workflow
+
+Usage:
+  agent-eng init [options]     Set up the workflow in the current directory
+
+Options:
+  --conventions <list>   Comma-separated list: typescript,python,java (default: all)
+  --dir <path>           Target directory (default: current directory)
+  --force                Overwrite existing files
+  -h, --help             Show this help
+
+Examples:
+  agent-eng init
+  agent-eng init --conventions typescript,python
+  agent-eng init --dir ./my-project --conventions java
+`;
+
+export function run(args) {
+  const command = args[0];
+
+  if (!command || command === "-h" || command === "--help") {
+    console.log(HELP.trim());
+    process.exit(0);
+  }
+
+  if (command === "init") {
+    const options = parseInitArgs(args.slice(1));
+    init(options);
+    return;
+  }
+
+  console.error(`Unknown command: ${command}`);
+  console.log('Run "agent-eng --help" for usage.');
+  process.exit(1);
+}
+
+function parseInitArgs(args) {
+  const options = {
+    conventions: ["typescript", "python", "java"],
+    dir: process.cwd(),
+    force: false,
+  };
+
+  for (let i = 0; i < args.length; i++) {
+    switch (args[i]) {
+      case "--conventions":
+        options.conventions = args[++i]?.split(",").map((s) => s.trim()) ?? [];
+        break;
+      case "--dir":
+        options.dir = args[++i];
+        break;
+      case "--force":
+        options.force = true;
+        break;
+      case "-h":
+      case "--help":
+        console.log(HELP.trim());
+        process.exit(0);
+    }
+  }
+
+  const valid = new Set(["typescript", "python", "java"]);
+  for (const c of options.conventions) {
+    if (!valid.has(c)) {
+      console.error(`Unknown convention: ${c}. Choose from: ${[...valid].join(", ")}`);
+      process.exit(1);
+    }
+  }
+
+  return options;
+}

package/src/init.js

@@ -0,0 +1,80 @@
+import { cpSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const TEMPLATES = join(__dirname, "templates");
+
+const STRUCTURE = [
+  "architecture/overview.md",
+  "architecture/decisions/_template.md",
+  "architecture/decisions/0001-how-we-work.md",
+  "prompts/architect.md",
+  "prompts/planner.md",
+  "prompts/reviewer.md",
+  "specs/_template.md",
+  "tickets/_template.md",
+  "orchestration.yaml",
+  "CLAUDE.md",
+];
+
+export function init(options) {
+  const target = resolve(options.dir);
+  const created = [];
+  const skipped = [];
+
+  for (const file of STRUCTURE) {
+    const dest = join(target, file);
+    const src = join(TEMPLATES, file);
+
+    if (existsSync(dest) && !options.force) {
+      skipped.push(file);
+      continue;
+    }
+
+    mkdirSync(dirname(dest), { recursive: true });
+    cpSync(src, dest);
+    created.push(file);
+  }
+
+  for (const convention of options.conventions) {
+    const file = `conventions/${convention}.md`;
+    const dest = join(target, file);
+    const src = join(TEMPLATES, file);
+
+    if (existsSync(dest) && !options.force) {
+      skipped.push(file);
+      continue;
+    }
+
+    mkdirSync(dirname(dest), { recursive: true });
+    cpSync(src, dest);
+    created.push(file);
+  }
+
+  console.log("");
+  console.log("✔ Agentic workflow initialized");
+  console.log("");
+
+  if (created.length > 0) {
+    console.log("Created:");
+    for (const f of created) {
+      console.log(`  ${f}`);
+    }
+  }
+
+  if (skipped.length > 0) {
+    console.log("");
+    console.log("Skipped (already exist, use --force to overwrite):");
+    for (const f of skipped) {
+      console.log(`  ${f}`);
+    }
+  }
+
+  console.log("");
+  console.log("Next steps:");
+  console.log("  1. Review CLAUDE.md and customize for your project");
+  console.log("  2. Pick the conventions that match your stack");
+  console.log("  3. Start with the Architect: create your first ADR");
+  console.log("");
+}

package/src/templates/CLAUDE.md

@@ -0,0 +1,34 @@
+# Project
+
+This project uses a structured agentic engineering workflow. Before starting any work, read this document and the relevant references below.
+
+## Workflow
+
+This project separates AI-assisted work into four roles. Each role has a dedicated system prompt in `prompts/`.
+
+| Role | Prompt | Responsibility |
+|------|--------|----------------|
+| **Architect** | `prompts/architect.md` | Analyze requirements, ask clarifying questions, produce ADRs |
+| **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 |
+
+## Before Starting Any Ticket
+
+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
+
+## Key Directories
+
+- `architecture/decisions/` — Architecture Decision Records (ADRs)
+- `specs/` — Feature specifications
+- `tickets/` — Work items with acceptance criteria
+- `conventions/` — Language and framework coding standards
+- `prompts/` — System prompts for each agent role
+
+## Conventions
+
+Check `conventions/` for language-specific standards. Always follow the conventions for the language you're working in.

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

@@ -0,0 +1,63 @@
+# ADR-0001: How We Work with AI Agents
+
+**Status:** Accepted  
+**Date:** 2026-05-04  
+**Author:** swarpi
+
+## Context
+
+Working with AI coding assistants can be highly productive, but without structure it often leads to:
+- Inconsistent code quality and style
+- Decisions made without considering alternatives
+- 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.
+
+## Decision
+
+We adopt a role-based workflow with four distinct agent modes:
+
+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.
+
+3. **Executor** — Implements tickets. Follows conventions. References the ticket and relevant ADRs. Proposes a plan before coding.
+
+4. **Reviewer** — Reviews diffs against acceptance criteria and linked ADRs. Checks for convention violations. Does not fix issues directly — flags them for the executor.
+
+All significant decisions are recorded as ADRs. All work items are tickets with acceptance criteria. Conventions are documented per-language.
+
+## Consequences
+
+### Positive
+
+- Clear separation of concerns reduces cognitive overload per session
+- ADRs create a searchable decision history
+- Tickets with acceptance criteria make "done" unambiguous
+- 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)
+
+### Negative
+
+- More upfront documentation work
+- Overhead may feel excessive for small changes
+- Requires discipline to follow the process
+
+### Neutral
+
+- This is a personal workflow; team adoption would require additional coordination conventions
+
+## Alternatives Considered
+
+### Unstructured chat-based development
+
+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)
+
+Too heavyweight for a solo developer. We take the useful parts (clear acceptance criteria, documented decisions) without the ceremony.
+
+### Separate human architect with AI executor
+
+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.

package/src/templates/architecture/decisions/_template.md

@@ -0,0 +1,41 @@
+# ADR-NNNN: Title
+
+**Status:** Proposed | Accepted | Deprecated | Superseded by ADR-NNNN  
+**Date:** YYYY-MM-DD  
+**Author:** Name
+
+## Context
+
+What is the issue that we're seeing that motivates this decision or change?
+
+## Decision
+
+What is the change that we're proposing and/or doing?
+
+## Consequences
+
+What becomes easier or more difficult to do because of this change?
+
+### Positive
+
+- Benefit 1
+- Benefit 2
+
+### Negative
+
+- Tradeoff 1
+- Tradeoff 2
+
+### Neutral
+
+- Side effect that is neither positive nor negative
+
+## Alternatives Considered
+
+### Alternative 1
+
+Description and why it was rejected.
+
+### Alternative 2
+
+Description and why it was rejected.

package/src/templates/architecture/overview.md

@@ -0,0 +1,25 @@
+# Architecture Overview
+
+This document provides a high-level view of the system architecture.
+
+## Core Principles
+
+1. **Separation of concerns** — Different cognitive tasks get different prompts and contexts
+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
+
+## The Flow
+
+```
+Requirement → Architect → ADR/Spec → Planner → Tickets → Executor → Code → Reviewer → Merged
+```
+
+## Artifact Types
+
+| Artifact | Purpose | Location |
+|----------|---------|----------|
+| ADR | Record architectural decisions | `architecture/decisions/` |
+| Spec | Define feature requirements | `specs/` |
+| Ticket | Actionable work item | `tickets/` |
+| Convention | Language/framework standards | `conventions/` |

package/src/templates/conventions/java.md

@@ -0,0 +1,110 @@
+# Java Conventions
+
+## Runtime and Build
+
+- **Java version**: 21 (LTS)
+- **Build tool**: Gradle with Kotlin DSL (`build.gradle.kts`)
+- **Framework**: Spring Boot 3.x (unless otherwise specified)
+
+## Code Style
+
+### Modern Java Features
+
+- **Records** over POJOs for immutable data
+- **Pattern matching** with `switch` expressions and `instanceof`
+- **Virtual threads** for concurrent I/O (Project Loom)
+- **Sealed classes** for closed hierarchies
+- **No Lombok** — use records and IDE generation instead
+
+```java
+public record User(String id, String name, String email) {}
+
+public sealed interface Result<T> permits Success, Failure {
+    record Success<T>(T value) implements Result<T> {}
+    record Failure<T>(String error) implements Result<T> {}
+}
+
+String describe(Object obj) {
+    return switch (obj) {
+        case User u -> "User: " + u.name();
+        case String s -> "String: " + s;
+        case null -> "null";
+        default -> "Unknown";
+    };
+}
+```
+
+### Null Handling
+
+- Prefer `Optional<T>` for return types that may be absent
+- Use `@Nullable` and `@NonNull` annotations from JSpecify
+- Avoid returning `null` from public methods
+
+```java
+public Optional<User> findUser(String id) {
+    return Optional.ofNullable(repository.get(id));
+}
+```
+
+### Dependency Injection
+
+- Constructor injection (not field injection)
+- Final fields for injected dependencies
+- `@RequiredArgsConstructor` is forbidden (no Lombok)
+
+```java
+@Service
+public class UserService {
+    private final UserRepository repository;
+    private final EmailService emailService;
+    
+    public UserService(UserRepository repository, EmailService emailService) {
+        this.repository = repository;
+        this.emailService = emailService;
+    }
+}
+```
+
+### Streams and Collections
+
+- Prefer immutable collections: `List.of()`, `Set.of()`, `Map.of()`
+- Use streams for transformations, not side effects
+- Avoid nested streams; extract to methods
+
+```java
+var activeUsers = users.stream()
+    .filter(User::isActive)
+    .toList();
+```
+
+## File Organization
+
+- One public class per file
+- Package-private classes for implementation details
+- Test classes in parallel `src/test/java` hierarchy
+
+## Naming
+
+- `camelCase` for methods, variables, parameters
+- `PascalCase` for classes, interfaces, enums, records
+- `SCREAMING_SNAKE_CASE` for constants
+- Interfaces: noun or adjective, no `I` prefix
+- Implementations: descriptive name, not `Impl` suffix
+
+## Async / Concurrency
+
+- Use virtual threads for blocking I/O (not reactive)
+- `CompletableFuture` for async composition when needed
+- Prefer structured concurrency (preview feature) when stable
+
+```java
+try (var executor = Executors.newVirtualThreadPerTaskExecutor()) {
+    executor.submit(() -> processRequest(request));
+}
+```
+
+## Testing
+
+- JUnit 5 with AssertJ for assertions
+- Mockito for mocking (sparingly)
+- Testcontainers for integration tests

package/src/templates/conventions/python.md

@@ -0,0 +1,107 @@
+# Python Conventions
+
+## Tooling
+
+- **Package/project manager**: uv (not pip, poetry, or pipenv)
+- **Formatter/Linter**: Ruff
+- **Type checker**: Pyright (strict mode)
+- **Test runner**: pytest
+
+## Project Setup
+
+```bash
+uv init project-name
+cd project-name
+uv add --dev ruff pyright pytest
+```
+
+## Code Style
+
+### Type Hints
+
+- Type hints on all function signatures
+- Use `from __future__ import annotations` for forward references
+- Use `typing` module for generics and unions
+
+```python
+from __future__ import annotations
+from typing import TypeVar, Sequence
+
+T = TypeVar("T")
+
+def first(items: Sequence[T]) -> T | None:
+    return items[0] if items else None
+```
+
+### Functions
+
+- Prefer pure functions over methods when no state is needed
+- Use dataclasses or named tuples for structured data
+- Avoid mutable default arguments
+
+```python
+from dataclasses import dataclass
+
+@dataclass(frozen=True)
+class User:
+    id: str
+    name: str
+    email: str
+
+def get_user(user_id: str) -> User | None:
+    ...
+```
+
+### Error Handling
+
+- Use explicit exception types
+- Prefer returning `None` or a result type over raising for expected cases
+- Document raised exceptions in docstrings
+
+```python
+class ParseError(Exception):
+    pass
+
+def parse_config(raw: str) -> Config:
+    """Parse configuration from string.
+    
+    Raises:
+        ParseError: If the configuration is invalid.
+    """
+    ...
+```
+
+### Imports
+
+- Use absolute imports
+- Group: standard library, third-party, local
+- One import per line for `from` imports with multiple items
+
+```python
+import json
+from pathlib import Path
+
+import httpx
+
+from myproject.config import settings
+from myproject.models import User
+```
+
+## File Organization
+
+- One module per file, named after the primary class/function
+- Use `__init__.py` for package exports only
+- Co-locate tests in `tests/` directory mirroring `src/` structure
+
+## Naming
+
+- `snake_case` for functions, variables, modules
+- `PascalCase` for classes
+- `SCREAMING_SNAKE_CASE` for constants
+- `_private` prefix for internal names
+
+## Async
+
+- Use `asyncio` for concurrent I/O
+- Prefer `async/await` over callbacks
+- Use `asyncio.gather` for concurrent operations

package/src/templates/conventions/typescript.md

@@ -0,0 +1,95 @@
+# TypeScript Conventions
+
+## Compiler Settings
+
+- **Strict mode**: Always enable `"strict": true` in tsconfig
+- **Target**: ES2022 or later
+- **Module**: ESNext with bundler module resolution
+
+## Tooling
+
+- **Formatter/Linter**: Biome (not ESLint + Prettier)
+- **Test runner**: Vitest
+- **Package manager**: pnpm preferred, npm acceptable
+
+## Code Style
+
+### Types
+
+- Prefer `interface` for object shapes, `type` for unions/intersections
+- Always annotate function parameters and return types
+- Use `unknown` over `any`; narrow with type guards
+- Prefer `readonly` for immutable data
+
+```typescript
+interface User {
+  readonly id: string;
+  name: string;
+  email: string;
+}
+
+function getUser(id: string): Promise<User | null> {
+  // ...
+}
+```
+
+### Functions
+
+- Prefer arrow functions for callbacks and short functions
+- Use named function declarations for top-level functions
+- Avoid classes unless modeling stateful entities
+
+```typescript
+// Preferred: named function at module level
+function calculateTotal(items: Item[]): number {
+  return items.reduce((sum, item) => sum + item.price, 0);
+}
+
+// Preferred: arrow for inline callbacks
+const activeUsers = users.filter((u) => u.isActive);
+```
+
+### Error Handling
+
+- Use explicit error types, not `catch (e: any)`
+- Prefer returning `Result<T, E>` types over throwing for expected failures
+- Reserve exceptions for unexpected/unrecoverable errors
+
+```typescript
+type Result<T, E> = { ok: true; value: T } | { ok: false; error: E };
+
+function parseConfig(raw: string): Result<Config, ParseError> {
+  // ...
+}
+```
+
+### Imports
+
+- Use named imports, avoid default exports
+- Group imports: external, then internal, then relative
+- Use `type` imports for type-only imports
+
+```typescript
+import { readFile } from "node:fs/promises";
+import type { Config } from "@/types";
+import { parseConfig } from "./parser";
+```
+
+## File Organization
+
+- One primary export per file
+- Co-locate tests: `foo.ts` and `foo.test.ts` in the same directory
+- Use `index.ts` only for re-exports, not implementation
+
+## Naming
+
+- `camelCase` for variables, functions, parameters
+- `PascalCase` for types, interfaces, classes, enums
+- `SCREAMING_SNAKE_CASE` for constants
+- Prefix booleans with `is`, `has`, `should`, `can`
+
+## Async
+
+- Always use `async/await` over raw Promises
+- Handle all promise rejections
+- Use `Promise.all` for independent concurrent operations

package/src/templates/orchestration.yaml

@@ -0,0 +1,67 @@
+name: Agentic Workflow
+description: Four-role pipeline for AI-assisted software engineering
+
+agents:
+  - id: architect
+    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.
+    outputs:
+      - ADRs
+      - Specs
+      - Constraints
+    color: indigo
+    docLink: /prompts/architect.md
+
+  - id: planner
+    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.
+    outputs:
+      - Tickets
+      - Milestones
+      - Criteria
+    color: indigo
+    docLink: /prompts/planner.md
+
+  - id: executor
+    title: Executor
+    tagline: Implements with intent and discipline
+    description: Implements tickets following established conventions. Always proposes a plan before touching the codebase.
+    outputs:
+      - Code
+      - PRs
+      - Plan docs
+    color: indigo
+    docLink: /conventions/typescript.md
+
+  - id: reviewer
+    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.
+    outputs:
+      - Feedback
+      - Approval
+      - Notes
+    color: amber
+    docLink: /prompts/reviewer.md
+
+connections:
+  - from: architect
+    to: planner
+    artifact: ADRs · Specs
+
+  - from: planner
+    to: executor
+    artifact: Tickets
+
+  - from: executor
+    to: reviewer
+    artifact: Code
+
+  - from: reviewer
+    to: executor
+    artifact: Feedback
+    type: feedback
+
+layout: diamond

package/src/templates/prompts/architect.md

@@ -0,0 +1,61 @@
+# Architect System Prompt
+
+You are an architect agent. Your role is to make design decisions and produce Architecture Decision Records (ADRs).
+
+## Responsibilities
+
+1. **Analyze requirements** — Understand what needs to be built and why
+2. **Ask clarifying questions** — Before deciding, surface ambiguities and gather context
+3. **Consider alternatives** — Evaluate at least 2-3 approaches before recommending one
+4. **Produce ADRs** — Document decisions using the template in `architecture/decisions/_template.md`
+5. **Reference existing decisions** — Check `architecture/decisions/` for relevant prior ADRs
+
+## Constraints
+
+- You have **read access** to the codebase but **do not write code**
+- You produce ADRs, not implementations
+- You ask questions before making decisions, not after
+- You document tradeoffs, not just the chosen path
+
+## Process
+
+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:
+   - 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
+
+## Output Format
+
+When producing an ADR, use the template format with proper frontmatter:
+
+```markdown
+# ADR-NNNN: Title
+
+**Status:** Proposed
+**Date:** YYYY-MM-DD
+**Author:** ...
+
+## Context
+...
+
+## Decision
+...
+
+## Consequences
+...
+
+## Alternatives Considered
+...
+```
+
+## Anti-patterns to Avoid
+
+- Making decisions without documenting alternatives
+- Jumping to implementation details
+- Ignoring existing ADRs that set relevant precedents
+- Deciding before asking clarifying questions

package/src/templates/prompts/planner.md

@@ -0,0 +1,78 @@
+# Planner System Prompt
+
+You are a planner agent. Your role is to decompose specs and ADRs into actionable tickets.
+
+## Responsibilities
+
+1. **Read specs and ADRs** — Understand what needs to be built and the constraints
+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
+
+## Constraints
+
+- You produce **tickets**, not code
+- Each ticket should be **independently mergeable** where possible
+- Acceptance criteria must be **specific and testable**
+- Link tickets to relevant ADRs and specs
+
+## Process
+
+1. Read the spec or feature request
+2. Identify the relevant ADRs and conventions
+3. 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:
+   - 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
+
+## Output Format
+
+Use the ticket template from `tickets/_template.md`:
+
+```markdown
+# Ticket: Title
+
+**Status:** Todo
+**Priority:** P1
+**Estimate:** M
+**Related:** ADR-0001, Spec: Feature Name
+
+## Context
+...
+
+## Goal
+...
+
+## Acceptance Criteria
+- [ ] ...
+
+## Out of Scope
+...
+
+## Notes
+...
+```
+
+## Sizing Guidelines
+
+| Size | Scope |
+|------|-------|
+| XS | Single-file change, <30 min |
+| S | Few files, <1 hour |
+| M | Feature slice, 1-3 hours |
+| L | Multi-component, 3-6 hours |
+| XL | Should probably be split |
+
+## Anti-patterns to Avoid
+
+- Tickets that are too vague ("implement the feature")
+- Missing acceptance criteria
+- Tickets that depend on unwritten tickets
+- Scope creep beyond the referenced spec

package/src/templates/prompts/reviewer.md

@@ -0,0 +1,67 @@
+# Reviewer System Prompt
+
+You are a reviewer agent. Your role is to review code changes against acceptance criteria and architectural decisions.
+
+## Responsibilities
+
+1. **Check acceptance criteria** — Verify each criterion in the ticket is satisfied
+2. **Validate against ADRs** — Ensure changes follow established architectural decisions
+3. **Check conventions** — Verify code follows the relevant language conventions
+4. **Identify issues** — Flag problems but don't fix them directly
+5. **Provide actionable feedback** — Be specific about what needs to change
+
+## Constraints
+
+- You **review and comment**, you do not write code
+- You flag issues for the executor to fix
+- You reference specific lines and files
+- You cite the relevant ADR or convention when flagging violations
+
+## Process
+
+1. Read the ticket and its acceptance criteria
+2. Read any linked ADRs and the relevant conventions file
+3. Review the diff:
+   - Does each acceptance criterion have corresponding changes?
+   - Do the changes violate any ADRs?
+   - Do the changes follow conventions?
+   - Are there obvious bugs or edge cases?
+4. Produce a review with:
+   - Checklist of acceptance criteria (pass/fail)
+   - List of issues (if any) with specific locations
+   - Overall verdict (approve / request changes)
+
+## Output Format
+
+```markdown
+## Review: Ticket Title
+
+### Acceptance Criteria
+
+- [x] Criterion 1 — Satisfied in `src/file.ts:42`
+- [ ] Criterion 2 — **Not satisfied**: missing error handling for empty input
+- [x] Criterion 3 — Satisfied
+
+### Issues
+
+1. **Convention violation** (`src/file.ts:15`): Missing type annotation on `processData` return value. See `conventions/typescript.md`.
+
+2. **Potential bug** (`src/file.ts:28`): `items.map()` will throw if `items` is undefined. The ticket's acceptance criteria require handling empty states.
+
+### Verdict
+
+**Request changes** — 1 acceptance criterion not met, 2 issues to address.
+```
+
+## Severity Levels
+
+- **Blocker** — Must fix before merge (bugs, security, broken acceptance criteria)
+- **Should fix** — Convention violations, code smells
+- **Nit** — Style preferences, minor suggestions (prefix with "nit:")
+
+## Anti-patterns to Avoid
+
+- Vague feedback ("this could be better")
+- Rewriting code instead of describing the issue
+- Blocking on style preferences when conventions don't specify
+- Missing the forest for the trees (focus on acceptance criteria first)

package/src/templates/specs/_template.md

@@ -0,0 +1,55 @@
+# Spec: Feature Name
+
+**Status:** Draft | In Review | Approved | Implemented  
+**Date:** YYYY-MM-DD  
+**Author:** Name  
+**Related ADRs:** ADR-NNNN, ADR-NNNN
+
+## Summary
+
+One-paragraph description of the feature.
+
+## Motivation
+
+Why are we building this? What problem does it solve?
+
+## Requirements
+
+### Functional Requirements
+
+1. The system must...
+2. The system must...
+3. The system should...
+
+### Non-Functional Requirements
+
+- Performance: ...
+- Security: ...
+- Accessibility: ...
+
+## User Stories
+
+### Story 1: [User role] can [action]
+
+As a [role], I want to [action] so that [benefit].
+
+**Acceptance criteria:**
+- [ ] Criterion 1
+- [ ] Criterion 2
+
+## Technical Approach
+
+High-level approach to implementation. Reference relevant ADRs.
+
+## Out of Scope
+
+What this feature explicitly does NOT include.
+
+## Open Questions
+
+- [ ] Question 1
+- [ ] Question 2
+
+## Appendix
+
+Any supporting information, mockups, or diagrams.

package/src/templates/tickets/_template.md

@@ -0,0 +1,39 @@
+# Ticket: Title
+
+**Status:** Todo | In Progress | In Review | Done  
+**Priority:** P0 | P1 | P2 | P3  
+**Estimate:** XS | S | M | L | XL  
+**Related:** ADR-NNNN, Spec: Feature Name
+
+## Context
+
+Brief background on why this work is needed. Link to the relevant spec or ADR.
+
+## Goal
+
+One sentence describing what "done" looks like.
+
+## Acceptance Criteria
+
+- [ ] Criterion 1 — specific, testable condition
+- [ ] Criterion 2 — specific, testable condition
+- [ ] Criterion 3 — specific, testable condition
+- [ ] Tests pass
+- [ ] No lint errors
+- [ ] Documentation updated (if applicable)
+
+## Out of Scope
+
+What this ticket explicitly does NOT include. Helps prevent scope creep.
+
+## Notes
+
+Any additional context, edge cases to consider, or implementation hints.
+
+## Implementation Plan
+
+_To be filled in by the executor before starting work._
+
+1. Step 1
+2. Step 2
+3. Step 3