@agile-vibe-coding/avc 0.2.3 → 0.3.2

package/README.md

@@ -1,5 +1,477 @@
-# ⚠️ UNDER DEVELOPMENT - DO NOT USE ⚠️
+# Agile Vibe Coding (AVC)
 
-This package is currently under active development and is not ready for production use.
+**A CLI and web UI toolkit for structured AI-assisted software development**
 
-**[CLI Commands Reference →](../COMMANDS.md)**
+AVC is a toolkit — combining a command-line interface with an interactive web-based kanban board — that implements the principles of the [Agile Vibe Coding Manifesto](https://agilevibecoding.org). It provides ceremonies, assets, and validation workflows that guide AI coding agents toward coherent, long-term software delivery — shaping context, constraints, and verification so that LLM limitations don't silently degrade your project.
+
+## How to Install
+
+```bash
+npm install -g @agile-vibe-coding/avc
+```
+
+Then, in your project root directory:
+
+```bash
+avc
+```
+
+This launches the AVC interactive CLI. From there:
+
+1. Run `/init` to initialize AVC in your project (creates `.avc/` config directory and `.env` for API keys)
+2. Run `/kanban` to launch the web-based kanban board at `http://localhost:4174`
+3. From the kanban board, configure your LLM provider in **Settings** (API keys, ceremony models)
+4. Start the **Sponsor Call** ceremony to define your project scope
+5. Run **Sprint Planning** to decompose into Epics and Stories
+6. Use **Seed** to break Stories into Tasks, then **Run** to implement code
+
+AVC auto-detects available API keys and switches ceremony models accordingly — if only one provider key is set, all ceremonies use that provider automatically.
+
+## Core Concepts
+
+AVC organizes AI-assisted development through three pillars: a **hierarchical asset structure** for context management, **ceremonies** that drive project planning and decomposition, and **multi-perspective validation** that catches issues before they reach code.
+
+### Assets Hierarchy
+
+The Assets Hierarchy establishes a structured folder architecture to organize work items and documentation. Each node contains a `doc.md` (scoped documentation), a `context.md` (canonical specification generated by LLM context writers with tool-augmented API reference discovery), and a `work.json` (work item definition with validation tests).
+
+```
+project/
+├── doc.md                                    # project-level documentation
+├── context.md                                # project context
+├── coding-order.md                           # dependency graph + phased implementation order
+├── coding-order.json                         # structured phase data for kanban board
+└── context-0001/
+    ├── doc.md                                # epic-specific documentation
+    ├── context.md                            # project + epic context (accumulated)
+    ├── work.json                             # work item (EPIC)
+    └── context-0001-0001/
+        ├── doc.md                            # story-specific documentation
+        ├── context.md                        # project + epic + story context
+        ├── work.json                         # work item (STORY)
+        └── context-0001-0001-0001/
+            ├── doc.md                        # task-specific documentation
+            ├── context.md                    # full accumulated context
+            ├── work.json                     # work item (TASK)
+            ├── context-0001-0001-0001-0001/
+            │   ├── doc.md                    # subtask documentation
+            │   ├── context.md                # full accumulated context
+            │   └── work.json                 # work item (SUBTASK)
+            └── context-0001-0001-0001-0002/
+                ├── ...
+```
+
+### Documentation
+
+Each node in the hierarchy maintains a single `doc.md` file, scoped to introduce only the information that is new and specific to that node — no duplication of what parent levels already define. Agents accumulate the full picture by reading all `doc.md` files along the path from root to the current node.
+
+### Work Item
+
+Work items define what needs to get done, including dependencies, acceptance criteria, validation scores, and implementation metadata.
+
+```json
+{
+  "id": "context-0001-0001-0001",
+  "name": "Implement Calculator Layout",
+  "type": "task",
+  "description": "Create the responsive HTML/CSS grid layout for the calculator UI",
+  "acceptance": [
+    "Calculator renders with display area and button grid",
+    "Layout adapts from 320px mobile to desktop widths",
+    "Touch targets are minimum 44x44 CSS pixels"
+  ],
+  "status": "ready",
+  "dependencies": ["context-0001-0001-0001"],
+  "children": [],
+  "metadata": {
+    "codingPhase": 2,
+    "codingOrder": 5,
+    "created": "2026-03-26T20:59:37.935+01:00",
+    "ceremony": "sprint-planning",
+    "validationResult": {
+      "averageScore": 96,
+      "overallStatus": "excellent"
+    }
+  }
+}
+```
+
+
+#### Work Items Flow
+
+Work items are implemented bottom-up in the tree.
+Start with the smallest, most concrete tasks (leaf nodes). Once those are done and validated, move up to their parents.
+
+If it has children, it waits.
+
+**Implementation Rules**
+
+1. **Start at the bottom**
+   - Begin with the deepest atomic tasks (leaf nodes).
+   - Tasks should be small, self-contained, and testable.
+
+2. **Parents wait for children**
+   - A parent work item cannot start until:
+     - All child items are marked `completed`
+     - All related tests are passing
+   - No partial roll-ups.
+
+3. **Parallel work — with limits**
+   - Parallel implementation is allowed only for **sibling nodes**.
+   - Do not parallelize across dependency chains.
+   - If two items depend on each other (directly or indirectly), they must be executed sequentially.
+
+
+**Example execution order**
+
+```
+context-0001/                          # Epic
+├── context-0001-0001/                 # Story
+│   ├── context-0001-0001-0001/        # Task
+│   │   ├── context-0001-0001-0001-0001/  <- 1. Implement first (atomic subtask)
+│   │   └── context-0001-0001-0001-0002/  <- 1. Parallel with sibling -0001
+│   │   # Task starts only after both subtasks complete
+│   └── context-0001-0001-0002/        <- 2. Parallel with sibling task -0001
+│   # Story starts only after both tasks complete
+└── context-0001-0002/                 <- 2. Parallel with sibling story -0001
+    # Epic completes only after both stories complete
+```
+
+### Hierarchical Documentation
+
+Every work item carries two documentation files with distinct roles:
+
+- **`context.md`** — Structured canonical specification. Fixed sections (Identity, Purpose, Scope In/Out, Features, NFRs, Dependencies, Success Criteria). Machine-oriented: micro-check validators score against it, auto-fixers refine it, doc-writers derive from it. This is the **single source of truth** for what a work item delivers.
+
+- **`doc.md`** — Narrative documentation. Prose written for developers and implementation agents. Explains *how things work together* — API contracts, error handling, data models, business rules, edge cases. Generated from `context.md` by doc-writer agents and enriched with implementation-ready detail.
+
+Both files follow the **hierarchical inheritance** principle: each level introduces only what is new and specific to its scope — no duplication of what parent levels already define. Context flows downward, and each child inherits its parent's decisions without repeating their justification.
+
+Research confirms this approach. Gloaguen et al. (2025) found that broad, comprehensive context files reduce agent task-success rates and increase inference cost by more than 20% ([arXiv:2602.11988](https://arxiv.org/abs/2602.11988)). The key principle: agents perform best when context is **minimal and scoped** — only what is new at each level.
+
+```
+project/
+├── context.md              # Project context — tech stack, deployment, team, constraints
+├── doc.md                  # Project narrative — mission, target users, full scope brief
+└── context-0001/           # Epic
+    ├── context.md          # Epic spec — domain purpose, features, NFRs, in/out scope
+    ├── doc.md              # Epic narrative — how features connect, security considerations
+    ├── work.json           # Epic metadata (name, domain, validation scores)
+    └── context-0001-0001/  # Story
+        ├── context.md      # Story spec — user story, acceptance criteria, dependencies
+        ├── doc.md          # Story narrative — API contracts, error tables, DB fields
+        ├── work.json       # Story metadata (name, userType, validation scores)
+        └── context-0001-0001-0001/  # Task
+            ├── doc.md      # Task narrative — implementation pattern for this task
+            └── work.json   # Task metadata
+```
+
+**When an agent implements task `context-0001-0001-0001`**, it reads all `doc.md` files along the path (project -> epic -> story -> task) as its complete context. Each level adds one layer of specificity: the project defines the stack, the epic defines the domain rules, the story defines the endpoint contract, and the task defines the implementation pattern for one piece of that story.
+
+
+#### Validation Order
+
+Testing follows the same bottom-up execution model as implementation:
+
+1. **Subtask (Unit) tests must pass first.**
+2. Once all subtask tests pass, run **Task (Integration) tests**.
+3. Only when all task tests pass, run **Story (E2E) tests**.
+4. Only when all stories pass, run **Epic (System) tests**.
+
+No higher-level tests should run if lower-level tests are failing.
+
+This ensures:
+- Failures are caught at the smallest possible scope
+- Debugging remains localized and efficient
+- System-level validation reflects fully verified lower layers
+
+## Ceremonies
+
+AVC ceremonies guide a project from initial vision through to implementable work units. Each ceremony produces structured artifacts that feed into the next.
+
+```mermaid
+graph LR
+    A[Sponsor Call] --> B[Sprint Planning]
+    B --> C[Seed]
+    C --> D[Run]
+    D --> E[Human Review]
+    E --> D
+    E --> B
+```
+
+All ceremonies are launched from the **kanban board** (`/kanban` in the CLI). Each ceremony has its own model configuration in Settings, with per-stage model selection and provider presets.
+
+### Sponsor Call
+
+The foundational ceremony. Through a guided questionnaire, it captures the project's mission, scope, and constraints, then generates the root `doc.md` and project brief. All downstream ceremonies build on this output.
+
+### Sprint Planning
+
+Decomposes the project scope into domain-based Epics and Stories, validates each work item through multi-agent domain expert review, and generates hierarchical documentation. The ceremony runs through these phases:
+
+#### Scope Collection
+
+Before any LLM call, the system gathers and prepares all inputs the decomposer will need. No LLM is involved — this phase is pure file I/O and data preparation.
+
+1. **Read project scope** — Loads the root `doc.md` (generated by Sponsor Call) which contains the full project brief: mission statement, target users, initial scope, deployment target, technical considerations, and security requirements. This document is the single source of truth for what the project should build.
+
+2. **Analyse existing hierarchy** — Scans `.avc/project/` for any Epics and Stories already on disk from prior sprint planning runs. For each existing Epic it reads `work.json` to extract the name, domain, description, features, and story names.
+
+This phase produces five outputs that flow into downstream stages:
+
+| Output | Type | Consumed by |
+|--------|------|-------------|
+| `scope` | Full text of `doc.md` | Decomposition — injected into the LLM prompt as the project scope to decompose |
+| `existingEpics` | Map of epic name -> id | Decomposition — listed in the prompt under "Existing Epics (DO NOT DUPLICATE)" so the LLM skips them |
+| `existingStories` | Map of story name -> id | Decomposition — listed in the prompt under "Existing Stories (DO NOT DUPLICATE)" |
+| `preRunSnapshot` | Array of rich epic objects (id, name, domain, description, story names) | Duplicate Detection (Stage 4.1) — passed to the duplicate detector agent as existing on-disk epics for cross-run overlap analysis |
+| `maxEpicNum` / `maxStoryNums` | Counters tracking the highest existing context IDs | Documentation & Output — used to assign sequential IDs to new Epics and Stories without colliding with existing ones |
+
+All outputs are held in memory and passed as function arguments through the stage pipeline — nothing is written to disk during this phase.
+
+#### Decomposition
+
+The system calls the LLM to break the project scope into Epics (domain-based groupings) and Stories (user-facing capabilities per Epic) — as many as needed to fully cover the scope. The decomposer agent calibrates granularity to project complexity: a single-file app gets 1-2 epics, a multi-service project gets 6-15.
+
+**Agent** — [`src/cli/agents/epic-story-decomposer.md`](src/cli/agents/epic-story-decomposer.md) — defines domain-driven design rules, project complexity calibration, the JSON output schema, scope completeness guidelines, tech stack fidelity requirements, dependency completeness rules, and the story split pattern for overly broad stories.
+
+**Output** — A `hierarchy` JSON object containing an `epics` array. Each epic carries `id`, `name`, `domain`, `description`, `features`, `dependencies`, and a nested `stories` array. Each story carries `id`, `name`, `userType`, `description`, `acceptance` (criteria array), and `dependencies`. Dependencies are normalized to context IDs (not names) before writing to disk.
+
+**Quality gate** — After decomposition, a quality check verifies structural issues (0-story epics, invalid ID formats, missing acceptance criteria). If issues are found, the decomposer retries with violation feedback (up to 3 retries).
+
+#### Duplicate Avoidance
+
+Sprint planning runs incrementally — each run generates new Epics and Stories alongside those already on disk from prior runs. Duplicate avoidance works in three layers:
+
+1. **Prompt-level prevention** — Before calling the LLM, existing Epic and Story names are injected into the prompt with an explicit instruction to skip them.
+
+2. **LLM-based semantic deduplication** — A second LLM call ([`src/cli/agents/duplicate-detector.md`](src/cli/agents/duplicate-detector.md)) analyses the newly generated epics for semantic overlaps. On any LLM error, the system falls back to Jaccard-similarity algorithmic deduplication.
+
+3. **Story scope review** — One LLM call per Epic reviews each Story's scope for cohesion. Stories that mix too many concerns are split into focused vertical slices.
+
+#### Context Generation
+
+After decomposition, each Epic and Story receives a canonical `context.md` — a structured specification that serves as the single source of truth for validation and documentation.
+
+The system runs a **Write -> Review -> Refine** loop (up to 3 rounds per item) using paired agents:
+
+- **Context Writer** ([`context-writer-epic.md`](src/cli/agents/context-writer-epic.md) / [`context-writer-story.md`](src/cli/agents/context-writer-story.md)) generates the initial context.
+- **Context Reviewer** ([`context-reviewer-epic.md`](src/cli/agents/context-reviewer-epic.md) / [`context-reviewer-story.md`](src/cli/agents/context-reviewer-story.md)) independently audits the generated context.
+- If the reviewer finds issues, the writer refines. This loop ensures context quality without relying on a single LLM pass.
+
+Context generation enforces consistency checks:
+
+- **Auth mechanism detection** — Detects whether the project has no auth, session-based auth, or JWT from the project brief. Projects with no backend/no login get `mechanism: none` — no auth boilerplate is injected.
+- **Cross-reference accuracy** — Validates that epic IDs referenced in dependency sections point to correct epics.
+- **Rate limit consistency** — Flags contradictions such as "10 requests/min" in one section vs "10 requests/sec" in another.
+
+#### External API Documentation Discovery
+
+When context writers generate `context.md` for stories or epics that integrate with external services, they can call a `fetch_api_reference` tool that resolves API documentation through [Context7](https://context7.com) (Upstash) — topic-specific, LLM-optimized documentation for thousands of libraries and APIs. This prevents hallucinating API details like payload formats, field names, and authentication mechanisms.
+
+#### Project Scaffolding Epic (Auto-Generated)
+
+After all domain epic and story contexts are generated, the system automatically creates a **Project Scaffolding** epic (`context-0000`) that bootstraps the project's development environment. Unlike domain epics which are generated during decomposition, the scaffolding epic is generated **last** so it can read the actual tech requirements from every epic and story context.
+
+**How it works:**
+
+1. **Tech extraction** — scans all cached context.md files for technology mentions using pattern matching.
+2. **LLM generation** — calls the scaffolding generator agent with the extracted tech requirements. The agent generates 2-4 stories adapted to the project's actual stack.
+3. **Dependency injection** — the scaffolding epic is inserted as the first epic. All domain epics are programmatically updated to depend on it. Scaffolding stories are chained sequentially (story 2 depends on story 1, etc.) so only the first story starts as `ready`.
+
+#### Micro-Check Validation (3-Tier)
+
+Each Epic and Story is validated through a 3-tier micro-check system: hundreds of small, atomic YES/NO quality checks run in parallel across 15 domain perspectives, followed by cross-reference consistency checks, deterministic scoring, and targeted auto-fixes.
+
+The validation flow per work item:
+
+1. **Context extraction** — A single LLM call infers the project's deployment type, tech stack, and domain characteristics.
+
+2. **Perspective selection** — An AI selector picks which domain perspectives are relevant per Epic/Story, excluding inapplicable roles.
+
+3. **Tier 1 — Domain checks** (~342 checks across 15 perspectives):
+   - Each check is 1-2 small LLM calls: an applicability gate and a YES/NO quality question.
+   - Checks run in parallel, limited by the `concurrency` setting (default 5).
+   - Each perspective has 7-19 checks defined in JSON files under [`src/cli/checks/`](src/cli/checks/).
+
+4. **Tier 2 — Cross-reference checks** (~28 checks):
+   - Run after all Tier 1 checks complete — they depend on Tier 1 evidence.
+   - Verify that different perspectives agree (e.g., security role model matches API endpoint access control).
+
+5. **Tier 3 — Scoring + fixing** (0 LLM calls for scoring, 1 LLM call per fix):
+   - **Deterministic scoring** based on pass/fail counts by severity.
+   - **Atomic per-check fixes** for critical/major failures: each fix is 1 LLM call, verified after application, reverted if the check still fails.
+
+6. **Story splitting** — If a story remains below threshold with 15+ acceptance criteria, it's split into 2-3 focused stories that replace the original and re-enter validation.
+
+Check definitions are JSON files in [`src/cli/checks/`](src/cli/checks/). They can be customized per project via the kanban board's Settings -> Agents tab.
+
+#### Documentation & Output
+
+The final phase writes all files to disk and generates two documentation layers:
+
+1. **Write hierarchy files** — Renumbers IDs to sequential order, normalizes dependencies from names to IDs, writes `work.json` and `context.md` for each item. Computes coding order from the dependency graph.
+2. **Generate doc.md** — One LLM call per Epic and Story, converting `context.md` -> narrative `doc.md`.
+3. **Enrich story docs** — One LLM call per Story, augmenting `doc.md` with implementation-ready detail (API contracts, error tables, DB fields).
+4. **Set ready status** — Items with no unresolved dependencies are set to `ready` status. Items whose dependencies are not yet completed stay `planned`.
+
+#### Implementation Ordering
+
+AVC computes a dependency-based implementation order from the epic/story dependency graph using topological sort (Kahn's algorithm). Epics are grouped into parallelizable phases — Phase 1 has no dependencies, Phase 2 depends only on Phase 1, etc.
+
+Outputs:
+- **`coding-order.md`** — Human-readable document with Mermaid dependency graph, critical path, and phased story order.
+- **`coding-order.json`** — Structured data for the kanban board with phase assignments and ordering metadata.
+
+Each work item's `work.json` receives `codingPhase` and `codingOrder` fields. The kanban board displays phase badges (P1, P2, etc.) and supports a "Phase" grouping mode.
+
+#### Resume After Failure
+
+If sprint planning fails mid-ceremony (after files are written to disk), the system detects the aborted run on the next start and offers **Resume** or **Start Fresh**. Resume rebuilds the hierarchy from disk and skips directly to the remaining stages (doc generation, enrichment), avoiding re-running expensive decomposition and validation.
+
+### Seed (Kanban Seed Button)
+
+Decomposes a Story into Tasks (2-5) and Subtasks (1-3 per Task), creating atomic work units ready for AI-assisted implementation. Each unit gets its own `context.md`, `doc.md`, and `work.json` in the asset hierarchy.
+
+#### Decompose -> Validate -> Refine Loop
+
+Seed uses the same iterative quality pattern as Sprint Planning:
+
+1. **Decompose** — LLM ([`task-subtask-decomposer.md`](src/cli/agents/task-subtask-decomposer.md)) breaks the story into tasks with acceptance criteria, dependencies, and subtasks.
+2. **Structural validation** (deterministic) — checks ID formats, task count (2-5), subtask count (1-3), and acceptance criteria presence. No LLM cost.
+3. **Semantic validation** (LLM, [`seed-validator.md`](src/cli/agents/seed-validator.md)) — checks story AC coverage, task distinctness, naming clarity, AC quality, dependency correctness, and subtask granularity.
+4. **Refinement** — if validation fails, violations are fed back to the decomposer for the next iteration (up to 3 retries).
+
+#### Dependency Gating
+
+Before seeding, the system checks whether the story's dependencies (other stories, parent epic dependencies) are all `completed`. If not, the Seed button shows the blocker list and prevents execution.
+
+#### Kanban Integration
+
+The Seed button appears on story cards in the kanban board detail modal. It runs as a background worker process via `TaskRunnerService`, streaming progress via WebSocket. Multiple stories can be seeded in parallel. Model configuration is available in Settings -> Ceremony Models -> Seed.
+
+### Run (Kanban Run Button)
+
+Implements a task's code in an isolated git worktree using AI agents, runs tests, and merges to the main branch on success.
+
+#### Worktree Lifecycle
+
+1. **Pre-flight check** — verifies package.json and git repo exist.
+2. **Create worktree** — `git worktree add .avc/worktrees/{taskId} -b avc/{taskId}` creates an isolated branch.
+3. **Read documentation chain** — walks the full hierarchy (project -> epic -> story -> task -> subtasks), concatenating all `doc.md` and `context.md` files into a single context string.
+4. **Code generation** (LLM, [`code-implementer.md`](src/cli/agents/code-implementer.md)) — generates source files and tests following traceability rules: hierarchy-prefixed naming, JSDoc provenance headers, functional purity, domain vocabulary.
+5. **Code validation** (LLM, [`code-validator.md`](src/cli/agents/code-validator.md)) — verifies generated code against check definitions in [`src/cli/checks/code/`](src/cli/checks/code/). If violations found, feeds them back to the implementer (up to 3 iterations).
+6. **Run tests** — executes the project's test command in the worktree. If tests fail, the worktree is cleaned up and the task is marked `failed`.
+7. **Commit and merge** — stages all changes, commits, merges to main with `--no-ff`, then cleans up the worktree and branch.
+
+#### Function Registry
+
+After implementation, the task's `work.json` receives a `functions` array listing every generated function with its file path, type, purity flag, line count, and which acceptance criterion it satisfies. This registry propagates upward — stories aggregate from tasks, epics from stories. The kanban board displays it under a "Code" tab.
+
+#### Configuration
+
+The Run ceremony is configured in `.avc/avc.json` with per-stage model selection (`code-generation`, `code-validation`), `maxValidationIterations`, and `acceptanceThreshold`. Code check definitions in `src/cli/checks/code/` are customizable via the kanban Settings -> Agents tab.
+
+### Kanban Board (`/kanban`)
+
+Interactive web-based kanban board for visualizing and managing work items across workflow stages (Backlog, Ready, In Progress, Review, Done). Supports filtering, grouping (by status, epic, type, or implementation phase), and real-time WebSocket updates.
+
+The kanban board is the primary interface for running ceremonies, configuring models, managing API keys, and monitoring progress. All ceremonies (Sponsor Call, Sprint Planning, Seed, Run) are launched from the board.
+
+#### Seed and Run Buttons
+
+Story cards display a **Seed** button that decomposes the story into tasks. Task cards display a **Run** button that implements the code in a worktree. Both buttons check dependencies before execution and show streaming progress logs. Multiple seeds and runs can execute in parallel.
+
+
+## Multi-Provider LLM Support
+
+AVC supports **different LLM providers for each ceremony stage**, allowing you to optimize for cost, speed, or quality.
+
+### Supported Providers
+
+- **Claude** (Anthropic) — Best for long-form documentation, complex reasoning, structured thinking
+- **Gemini** (Google) — Fast and cost-effective for iteration-heavy tasks
+- **OpenAI** — GPT models via API key or OAuth
+- **Xiaomi MiMo** — MiMo V2 models (Flash, Pro, Omni) via OpenAI-compatible API. Flash ($0.09/$0.29 per 1M tokens) for validation, Pro ($1/$3, 1M context) for reasoning-heavy stages. Get a key at [platform.xiaomimimo.com](https://platform.xiaomimimo.com).
+- **Local** (LM Studio / Ollama) — Run ceremonies with local models via OpenAI-compatible API. Supports tool-augmented context generation with streaming fallback. Set `LOCAL_LLM_URL` in `.env` or auto-discovers on standard ports.
+
+### API Keys
+
+Set in `.env` file (created by `/init`):
+
+```bash
+ANTHROPIC_API_KEY=sk-ant-...
+GEMINI_API_KEY=...
+OPENAI_API_KEY=sk-...
+XIAOMI_API_KEY=sk-...
+LOCAL_LLM_URL=http://localhost:1234/v1  # optional
+```
+
+### Auto-Provider Fallback
+
+When a ceremony starts, AVC checks if the configured provider has a valid API key. If not, it automatically switches all ceremony stages to the first available provider (priority: Claude -> Gemini -> OpenAI -> Xiaomi -> Local), applies the provider's preset models for each stage, and persists the change to `avc.json`. This means you only need one API key to get started — AVC configures everything else.
+
+### Per-Stage Model Configuration
+
+Each ceremony has multiple stages (e.g., decomposition, validation, context-generation), each configurable with its own provider and model. Provider presets define optimal model choices per stage (e.g., Opus for architecture, Haiku for validation). Configure via the kanban Settings -> Ceremony Models tab.
+
+
+## AI Agent Strategy: Single Prompt Approach
+
+AVC uses a **single prompt strategy** where agent instructions and task data are combined into one user message, rather than separating them into system instructions and user prompts.
+
+**Why:**
+1. **Research Evidence**: Studies show LLMs experience 40-80% performance degradation when combining knowledge retrieval with instruction-following in separate channels ([arXiv:2410.12972](https://arxiv.org/html/2410.12972v2)).
+2. **Explicit Role Establishment**: Placing agent instructions FIRST in the prompt ensures the model fully internalizes its role before processing task data.
+3. **Provider Agnostic**: Works identically across all supported providers without provider-specific workarounds.
+
+**Agent Templates** ([`src/cli/agents/`](src/cli/agents/)):
+- **Generation**: `project-documentation-creator.md`, `epic-story-decomposer.md`, `context-writer-epic.md`, `context-writer-story.md`, `scaffolding-generator.md`, `code-implementer.md`
+- **Validation**: `validator-documentation.md`, `seed-validator.md`, `code-validator.md`, micro-check definitions in [`src/cli/checks/`](src/cli/checks/)
+- **Support**: `duplicate-detector.md`, `doc-writer-epic.md`, `doc-writer-story.md`, `story-doc-enricher.md`
+
+
+## Code Generation Rules
+
+AVC enforces coding rules on AI-generated code to ensure full traceability from requirements to implementation. These rules are enforced by check definitions in [`src/cli/checks/code/`](src/cli/checks/code/) and validated by the code-validator agent during the Run ceremony.
+
+### Hierarchy-Prefixed Naming
+
+Every function and class name embeds its work item hierarchy path: `e{epicNum}_s{storyNum}_t{taskNum}_{descriptiveName}`. Files use kebab-case: `e0001-s0002-t0003-function-name.js`. This enables instant traceability: `grep -r "e0001_s0002"` finds all code for Story 0002.
+
+### Function Size and Responsibility
+
+Soft target: 5-25 lines per function. Hard rule: one function = one responsibility, mapping to one acceptance criterion.
+
+### Functional Purity
+
+Business logic must be pure functions (same input, same output, no side effects). Side effects (file I/O, API calls, database) are isolated in boundary functions. Pure functions are tagged with `pure: true` in the function registry.
+
+### Documentation and Provenance
+
+Every generated file includes a provenance header with `@file`, `@story`, `@task`, `@agent`, `@generated` tags. Every exported function includes JSDoc with `@satisfies` referencing a specific acceptance criterion.
+
+### Test Traceability
+
+Every test `describe` block references an acceptance criterion ID. Every acceptance criterion must have at least one function and one test.
+
+### File Organization
+
+One primary exported function per file. File name matches function name in kebab-case with hierarchy prefix. Tests colocate with source as `*.test.js` files.
+
+### Domain-Language Naming
+
+Function names use vocabulary from the documentation chain — domain nouns and domain verbs, not generic terms (`process`, `handle`, `do`).
+
+
+## References
+
+1. **Anthropic's Best Practices for Long-Running Agents** — [Effective Harnesses for Long-Running Agents](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents)
+
+2. **Microservices Architecture** — [Microservices Patterns](https://microservices.io/patterns/microservices.html)
+
+3. **Agile Manifesto** — [Agile Principles](https://agilemanifesto.org/principles.html)
+
+4. **LLM Limitations Research** — [arXiv:2410.12972](https://arxiv.org/html/2410.12972v2) — 40-80% performance drops when combining knowledge and instruction-following in separate channels.
+
+5. **Hierarchical Documentation Strategy** — Gloaguen et al. (2025) — [arXiv:2602.11988](https://arxiv.org/abs/2602.11988) — Comprehensive context files reduce agent task-success rates by 20%+.

package/cli/agents/agent-selector.md

@@ -44,6 +44,8 @@ Explicitly exclude roles whose domain is entirely absent from this work item AND
 - Exclude `frontend`, `ui`, `ux` if the project has no frontend (`hasFrontend = false`) AND the item has no UI requirements
 - Exclude `api` if the item involves only internal implementation with no API surface (public or between services)
 - Exclude `database` if the item has no persistence, data modeling, or query requirements
+- Exclude `ui` at **epic level** unless the epic's primary focus is a visual design system, component library, or front-end experience architecture. For infrastructure, auth, API, backend, and data epics, `ui` is better evaluated at story level where design detail exists.
+- Exclude `ux` at **epic level** unless the epic is explicitly about user flows, onboarding, or information architecture. UX concerns are more actionable at story granularity.
 
 ## Output Format
 
@@ -108,6 +110,27 @@ Item: Story "As a user, I want to upload a profile picture", acceptance: ["Suppo
 }
 ```
 
+### Example 4: Web app, Epic "Foundation Services" (infrastructure domain)
+
+Project context: `deploymentType: local, hasCloud: false, hasCI_CD: false, hasMobileApp: false, hasFrontend: true, techStack: ["node.js", "react", "sqlite"]`
+
+Item: Epic "Foundation Services", domain: infrastructure, features: ["JWT auth", "rate limiting", "audit logging", "session management"]
+
+```json
+{
+  "selected": ["solution-architect", "developer", "security", "backend", "database", "api"],
+  "excluded": ["ui", "ux", "mobile", "cloud", "devops", "data"],
+  "reasons": {
+    "ui": "Infrastructure epic — visual design review belongs at story level",
+    "ux": "Infrastructure epic — UX flow review belongs at story level",
+    "mobile": "No mobile app in this project",
+    "cloud": "Local deployment — no cloud services involved",
+    "devops": "No CI/CD pipeline in this project",
+    "data": "No analytics or data pipeline in this epic"
+  }
+}
+```
+
 ### Example 3: Pure API project, Epic "Rate Limiting & Throttling"
 
 Project context: `deploymentType: kubernetes, hasCloud: true, hasCI_CD: true, hasMobileApp: false, hasFrontend: false, techStack: ["go", "redis", "postgresql", "kubernetes"]`

package/cli/agents/code-implementer.md

@@ -0,0 +1,117 @@
+# Code Implementer Agent
+
+You are an expert software engineer generating production-quality code from a fully specified task. Your output must satisfy all acceptance criteria and follow strict traceability and quality rules.
+
+## Your Task
+
+Given a task's documentation chain (project → epic → story → task → subtasks), generate all source files and test files needed to implement the task.
+
+## Input Format
+
+You receive:
+- `## Hierarchy Prefix` — the naming prefix for this task (e.g., `e0001_s0002_t0003`)
+- `## Task ID` — the full task ID (e.g., `context-0001-0002-0003`)
+- `## Acceptance Criteria` — numbered list of ACs from work.json
+- `## Documentation Chain` — concatenated doc.md + context.md from project through task
+- `## Coding Rules Summary` — the rules your code must follow
+
+## Output Format
+
+Return ONLY valid JSON:
+
+```json
+{
+  "files": [
+    {
+      "path": "src/domain/e0001-s0002-t0003-function-name.js",
+      "content": "full file content with provenance header and JSDoc",
+      "functions": ["e0001_s0002_t0003_functionName"]
+    }
+  ],
+  "tests": [
+    {
+      "path": "src/domain/e0001-s0002-t0003-function-name.test.js",
+      "content": "full test file content",
+      "acceptanceCriteria": ["context-0001-0002-0003#AC1"]
+    }
+  ],
+  "functionRegistry": [
+    {
+      "name": "e0001_s0002_t0003_functionName",
+      "file": "src/domain/e0001-s0002-t0003-function-name.js",
+      "type": "exported",
+      "pure": true,
+      "satisfies": "context-0001-0002-0003#AC1",
+      "lines": 18
+    }
+  ],
+  "summary": "Brief description of what was implemented"
+}
+```
+
+## Coding Rules
+
+### 1. Hierarchy-Prefixed Naming
+- Every exported function: `{prefix}_{descriptiveCamelCase}`
+- Every exported class: `{Prefix}_{DescriptivePascalCase}` (capitalize each segment)
+- Every helper function in the same file: same prefix
+- Every test describe block: `'{prefix}#ACn: description'`
+- File names: prefix in kebab-case + function name in kebab-case
+
+### 2. Provenance Header
+Every file starts with:
+```javascript
+/**
+ * @file relative/path/to/file.js
+ * @story {storyId} — {storyName}
+ * @task {taskId} — {taskName}
+ * @agent code-implementer
+ * @generated {ISO-8601 timestamp}
+ */
+```
+
+### 3. JSDoc with @satisfies
+Every exported function has:
+```javascript
+/**
+ * Description of what this function does.
+ * @satisfies {taskId}#AC{n} — "{acceptance criterion text}"
+ * @param {type} name - description
+ * @returns {type} description
+ */
+```
+
+### 4. Function Size
+- Target: 5-25 lines per function body
+- One function = one responsibility
+- If a block needs a comment to explain it, extract it into a named function
+- Orchestration methods may reach ~50 lines if each line is a single function call
+
+### 5. Functional Purity
+- Business logic functions must be pure (same input → same output, no side effects)
+- Side effects (file I/O, API calls, database) go in separate boundary functions
+- Mark pure functions with `pure: true` in the function registry
+
+### 6. Domain Naming
+- Use nouns and verbs from the documentation chain
+- Never use generic names: processData, handleRequest, doWork, updateDB
+- Prefer domain terms: bookAppointment, validateSlotAvailability, computeReminderSchedule
+
+### 7. File Organization
+- One primary exported function per file
+- File name = function name in kebab-case with hierarchy prefix
+- Tests colocate with source: `*.test.js` alongside `*.js`
+
+### 8. Test Coverage
+- Every acceptance criterion must have at least one test
+- describe blocks reference the AC: `describe('{prefix}#AC1: ...', () => { ... })`
+- Test observable behavior, not implementation details
+
+## Important Rules
+
+1. **Generate complete files** — not diffs, not patches, not pseudocode
+2. **Include all imports** — every file must be self-contained and runnable
+3. **Follow the tech stack** from the project documentation exactly
+4. **Implement ONLY what the task requires** — no extra features, no premature abstractions
+5. **Every function must trace to an AC** — no orphan code
+6. **Use the exact hierarchy prefix provided** — do not invent your own