specweave 1.0.593 → 2.0.3

package/src/templates/AGENTS.md.template

@@ -1,460 +1,89 @@
+<!-- SECTION:header required -->
 # {PROJECT_NAME}
 
-**Framework**: SpecWeave - Specification-First Development
-
----
-
-<!-- SECTION:rules required -->
-## Essential Rules
-
-```
-1. NEVER pollute project root with .md files
-2. Increment IDs unique (0001-9999)
-3. ONLY 4 files in increment root: metadata.json, spec.md, plan.md, tasks.md
-4. ALL reports/scripts/logs → increment subfolders (NEVER at root!)
-5. metadata.json MUST exist BEFORE spec.md can be created
-6. tasks.md + spec.md = SOURCE OF TRUTH (update after every task!)
-7. EVERY User Story MUST have **Project**: field
-8. For 2-level structures: EVERY US also needs **Board**: field
-```
-
-### Increment Folder Structure
-
-```
-.specweave/increments/0001-feature/
-├── metadata.json                  # REQUIRED - create FIRST
-├── spec.md                        # WHAT & WHY
-├── plan.md                        # HOW (optional)
-├── tasks.md                       # Task checklist
-├── reports/                       # ALL other .md files go here!
-├── scripts/                       # Helper scripts
-└── logs/                          # Execution logs
-    └── 2026-01-04/
-```
-<!-- /SECTION -->
-
----
-
-<!-- SECTION:orchestration required -->
-## Workflow Orchestration
-
-### 1. Plan Before Code (MANDATORY)
-
-BEFORE implementing ANY task — create an increment FIRST:
-1. Create increment: spec.md (WHAT/WHY) + plan.md (HOW) + tasks.md (checklist)
-2. Get user approval before implementing
-3. If something goes sideways → STOP and re-plan
-
-**No exceptions for "simple" tasks** — "simple", "quick", "basic" still require an increment. The only exception: user explicitly says "don't create an increment."
-
-**Setup/config actions are NOT implementation** — "connect github", "setup sync", "import issues" → use the matching setup command directly, not the increment workflow.
-
-See **Task Format** and **User Story Format** sections for templates.
-
-### 2. Verify Before Done
-
-Never mark a task complete without proving it works:
-- Code compiles/builds successfully
-- Run tests after every task: `npx vitest run` + `npx playwright test`
-- Review code quality before committing — check for duplication, readability issues, and inefficiencies (Claude Code: `/simplify`; other tools: manual review or linter)
-- `sw:grill` writes `grill-report.json` — CLI blocks closure without it
-- `sw:judge-llm` writes `judge-llm-report.json` — WAIVED if consent denied
-- Acceptance criteria actually satisfied
-
-### 2b. Auto-Closure (MANDATORY)
-
-When ALL tasks are complete, IMMEDIATELY run `sw:done` — do NOT stop to ask for user confirmation. Quality gates (grill, judge-llm, PM validation) ARE the review. If gates fail, the increment stays open. User can re-open if they disagree with closure.
-
-### 4. Large-Scale Changes
-
-For codebase-wide migrations or bulk refactors:
-- **Claude Code**: Use `/batch` — decomposes work into parallel agents with worktree isolation, each producing its own PR
-- **Other tools**: Break work into isolated branches (one per unit), implement each independently, review and merge separately
-- Always get approval on the decomposition plan before executing
-
-### 3. Dependencies First
-
-Satisfy dependencies BEFORE dependent operations.
-
-```
-Bad:  node script.js → Error → npm run build
-Good: npm run build → node script.js → Success
-```
-<!-- /SECTION -->
-
----
-
-<!-- SECTION:principles required -->
-## Core Principles (Quality)
-
-### Simplicity First
-- Write the simplest code that solves the problem
-- Avoid over-engineering and premature optimization
-- One function = one responsibility
-- If you can delete code and tests still pass, delete it
-- **Match tooling to complexity** — simple tasks (calculator, todo) need 0 domain plugins and vanilla code. Don't load heavyweight frameworks, design systems, or i18n for trivial features
-
-### No Laziness
-- Don't leave TODO comments for "later"
-- Don't skip error handling because "it probably won't fail"
-- Don't copy-paste without understanding
-- Test edge cases, not just happy paths
-
-### Minimal Impact
-- Change only what's necessary for the task
-- Don't refactor adjacent code unless asked
-- Keep PRs focused and reviewable
-- Preserve existing patterns unless improving them is the task
-
-### Demand Elegance (Balanced)
-- Code should be readable by humans first
-- Names should reveal intent
-- BUT: Don't over-abstract for hypothetical futures
-- Pragmatic > Perfect
-
-### DRY (Don't Repeat Yourself)
-- Flag repetitions aggressively — duplicated logic, config, or patterns
-- Extract shared code into reusable functions/modules
-- If you see the same block twice, refactor before adding a third
-- Applies to code, config, tests, and documentation alike
-
-### Plan Review Before Code
-- Review the full plan thoroughly before writing any code
-- Verify plan covers all ACs and edge cases before implementation
-- If the plan has gaps, fix the plan first — don't discover them mid-coding
-- Re-read the plan between tasks to stay aligned
-
-### Test Before Ship
-- Tests pass at every step — unit after each task, E2E before close, no exceptions
-- `sw:increment` generates BDD test plans during design via the sw-planner agent — verify they exist before `sw:do`
-- TDD cycle: `sw:tdd-red` → `sw:tdd-green` → `sw:tdd-refactor`
-- E2E with Playwright CLI (`npx playwright test`) is a blocking closure gate
-<!-- /SECTION -->
-
----
-
-<!-- SECTION:commands required -->
-## Commands Reference
-
-Commands are shown as `sw:<name>`. How you invoke them depends on your AI tool:
-
-| Tool | Invocation | Example |
-|------|-----------|---------|
-| **Claude Code** | Slash command | `/sw:do` |
-| **Cursor / Windsurf** | Type in chat | `sw:do` or describe the action |
-| **Copilot / ChatGPT** | Describe in chat | "Execute increment tasks" |
-| **Gemini CLI / Codex** | Reference in prompt | "Run sw:do on my increment" |
-| **Any tool** | SpecWeave CLI (where available) | `specweave validate 0001` |
-
-| Command | Purpose |
-|---------|---------|
-| `sw:increment "name"` | Plan new feature (PM-led) |
-| `sw:do` | Execute tasks from active increment |
-| `sw:done 0001` | Close increment (validates gates) |
-| `sw:progress` | Show task completion status |
-| `sw:validate 0001` | Quality check before closing |
-| `sw:progress-sync` | Sync tasks.md with reality |
-| `sw:sync-docs update` | Sync to living docs |
-| `sw-github:sync 0001` | Sync increment to GitHub issue |
-| `sw-jira:sync 0001` | Sync to Jira |
-| `sw-ado:sync 0001` | Sync to Azure DevOps |
-| `sw:sync-setup` | Connect GitHub/Jira/ADO integration |
-| `sw:import` | Import issues from external tools |
+SpecWeave project. Work happens in increments under `.specweave/increments/NNNN-slug/`. `spec.md` (Problem, ACs, Approach) is the source of truth; the ledger records who did what. This file is for Codex, OpenCode, Cursor, Gemini, Aider and humans; Claude Code reads CLAUDE.md (same content). Keep it under one page; project-specific notes go in **Project notes** at the bottom.
 <!-- /SECTION -->
 
----
-
-<!-- SECTION:nonclaudetools required -->
-## Non-Claude Tools (Cursor, Copilot, etc.)
-
-Claude Code has automatic hooks and orchestration. Other tools must do these manually.
-
-### Capability Comparison
-
-| Capability | Claude Code | Non-Claude Tools |
-|------------|-------------|------------------|
-| **Plan Mode** | `EnterPlanMode` → `/sw:increment` | Manual: Create spec.md + plan.md + tasks.md |
-| **Subagents** | `Task` tool for parallel work | Split into multiple chat sessions |
-| **Verification** | PostToolUse hooks auto-validate | Manual: Run tests, check ACs |
-| **Code quality** | `/simplify` (3 parallel review agents) | Manual: lint, review for duplication/readability/perf |
-| **Batch migration** | `/batch` (worktree-isolated parallel agents) | Manual: one branch per unit, implement separately |
-| **Hooks** | Auto-run on events | YOU must mimic (see below) |
-| **Task sync** | Automatic AC updates | Manual: Edit tasks.md + spec.md |
-| **Skills** | Auto-activate on keywords | Read SKILL.md, follow manually |
-
-### Manual Hook Checklist
-
-**After EVERY task completion:**
-1. Update tasks.md: `[ ] pending` → `[x] completed`
-2. Update spec.md ACs if satisfied: `[ ] AC` → `[x] AC`
-3. Review code quality: check for duplication, readability, performance issues (Claude Code: `/simplify`)
-4. Run `sw:progress-sync`
-5. Run `sw-github:sync <id>` (if GitHub configured)
-
-**After all ACs for a User Story are done:**
-- Run `sw:sync-docs update`
-
-**After increment completion:**
-1. `sw:validate <id>`
-2. `sw:sync-docs update`
-3. `sw-github:close-issue <id>`
-
-**Session start:**
-1. `specweave jobs` (check background jobs)
-2. `sw:progress` (check current state)
-3. `sw:do` (continue work)
-
-**Background jobs**: Monitor with `specweave jobs` (clone-repos, import-issues, living-docs-builder, sync-external).
-<!-- /SECTION -->
-
----
-
-<!-- SECTION:syncworkflow -->
-## Sync Workflow
-
-### Source of Truth
-
-| Level | Location | Update Method |
-|-------|----------|---------------|
-| **Source** | tasks.md + spec.md | Edit directly |
-| **Derived** | .specweave/docs/internal/specs/ | `sw:sync-docs update` |
-| **Mirror** | GitHub/Jira/ADO | `sw-github:sync`, `sw-jira:sync`, `sw-ado:sync` |
-
-**Update order**: ALWAYS tasks.md/spec.md FIRST → progress-sync → sync-docs → external tools
-
-### Sync Commands
-
-| Command | When to Run |
-|---------|-------------|
-| `sw:progress-sync` | After editing tasks.md |
-| `sw:sync-docs update` | After US complete |
-| `sw-github:sync <id>` | After each task |
-| `sw-github:close-issue <id>` | On increment done |
-| `sw-jira:sync <id>` | After each task |
-| `sw-ado:sync <id>` | After each task |
-<!-- /SECTION -->
-
----
-
-<!-- SECTION:contextloading -->
-## Context Loading
-
-### Efficient Context Management
-
-```
-Read only what's needed for the current task:
-- Active increment: spec.md, tasks.md (always)
-- Supporting docs: only when referenced in tasks
-- Living docs: load per-US when implementing
-```
-
-### Token-Efficient Approach
-
-1. Start with increment's `tasks.md` - contains current task list
-2. Reference `spec.md` for acceptance criteria
-3. Load living docs only when needed for context
-4. Avoid loading entire documentation trees
-<!-- /SECTION -->
-
----
-
 <!-- SECTION:structure -->
-## Project Structure
+## Structure
 
 ```
 .specweave/
-├── increments/           # Feature increments (0001-9999)
-│   └── 0001-feature/
-│       ├── metadata.json # Increment metadata - REQUIRED
-│       ├── spec.md       # WHAT & WHY (user stories, ACs)
-│       ├── plan.md       # HOW (architecture, APIs) - optional
-│       └── tasks.md      # Task checklist with test plans
-├── docs/internal/
-│   ├── strategy/         # PRD, business requirements
-│   ├── specs/            # Living docs (extracted user stories)
-│   │   └── {project}/    # Per-project specs
-│   ├── architecture/     # HLD, ADRs, technical design
-│   └── delivery/         # CI/CD, deployment guides
-└── state/                # Runtime state (active increment, caches)
+  increments/NNNN-slug/   spec.md (Problem · ACs · Approach) · tasks.md (tasks + rendered board) · ledger.jsonl (claims/done, CLI-written) · handoff.md · reports/ (evidence; binaries in reports/artifacts/, gitignored)
+  docs/                    ADRs and hand-written docs (read before changing architecture)
+  config.json
 ```
+Only those files (plus optional `plan.md` when Approach outgrows a page, and `scripts/`) live in an increment root; everything else goes in `reports/`. Commit messages start with the increment id: `0042: add login form`.
 
-### Repository Structure
-
-**Every workspace uses `repositories/` to organize code. Each repo has its own `.specweave/`:**
-
-```
-workspace/
-├── .specweave/config.json          # Workspace config ONLY
-├── repositories/
-│   ├── org/frontend/
-│   │   └── .specweave/increments/  # Frontend increments HERE
-│   ├── org/backend/
-│   │   └── .specweave/increments/  # Backend increments HERE
-│   └── org/shared/
-│       └── .specweave/increments/  # Shared increments HERE
-```
-
-**Rules**: Each repo manages its own increments. Never create increments in the workspace root.
+`tasks.md` format (the CLI parses it): `### T-01 Title` followed by one line `- AC: AC-01, AC-02 | Files: src/login.ts, src/login.test.ts | Test: npm test -- login`. `ledger.jsonl` is one JSON object per line, append-only: `{"t":"T-01","e":"claim|done|skip|release|block","by":"<tool>@<host>","at":"<ISO>","evidence":"<sha>","note":"<why>"}` (`evidence` required for `done`, `note` required for `skip`, both optional elsewhere).
 <!-- /SECTION -->
 
----
-
-<!-- SECTION:agents -->
-## Agents (Roles)
+<!-- SECTION:loop required -->
+## The loop
 
-{AGENTS_SECTION}
+| Step | Command (each step is also a standalone skill you can install into any tool with `npx vskill install anton-abyzov/specweave/sw-do` — same for `sw-increment`, `sw-review`, `sw-handoff`, `sw-task`) |
+|---|---|
+| Plan a feature: write `spec.md` (Problem, Scope, `AC-01…` checkboxes, Approach: files that change, order of work, risks, decisions), get approval before any code | `specweave create-increment "title"` |
+| Work the tasks | `specweave task next` → `specweave task claim T-NN` → implement → commit (`NNNN: …`) → `specweave task done T-NN --run "<test cmd>"` (the command runs through your OS shell: cmd.exe on Windows, sh elsewhere) |
+| Verify the whole increment | `specweave verify` |
+| Review before closing (recommended for anything that ships) | in a fresh session: read spec.md, list findings by severity citing path:line, re-verify each before writing `reports/review.md`; the authoring session never approves its own work |
+| Close (needs a green verify or `--reason "<why>"`) | `specweave complete NNNN` |
+| Stop for any reason | `specweave handoff` |
 
-**Usage**: Adopt role perspective when working on related tasks.
+Without the `specweave` CLI: create the folder by hand (id = highest existing 4-digit prefix + 1, zero-padded); append one JSON line per event to `ledger.jsonl` as UTF-8 without BOM, LF-terminated, e.g. `{"t":"T-01","e":"claim","by":"<tool>@<host>","at":"<ISO>"}` (bash: `>>`; PowerShell: `[IO.File]::AppendAllText('ledger.jsonl', $line + "`n")`, never `>>`, it writes UTF-16); mark done with the same line using `"e":"done","evidence":"<commit sha>"` after the Test command exits 0; write `reports/verify.md` with the real test output and say the increment is ready to close (closing itself needs the CLI).
+Start every feature with an increment, even a small one, unless the user says "no increment". Fix a bug by writing the failing test first, then fixing the code without touching the test.
 <!-- /SECTION -->
 
----
-
-<!-- SECTION:skills -->
-## Skills (Capabilities)
-
-{SKILLS_SECTION}
-
-**Claude Code**: Skills auto-activate based on keywords in your prompt.
-
-**Non-Claude Tools**: Skills are installed in your tool's native rules folder:
-
-| Tool | Skills Location | Auto-loaded? |
-|------|----------------|-------------|
-| Cursor | `.cursor/skills/` | Yes |
-| GitHub Copilot | `.github/skills/` | Yes (as workspace instructions) |
-| Gemini CLI | `.gemini/` | Reference in prompt |
-| OpenAI Codex | `.codex/skills/` | Reference in prompt |
-| Windsurf | `.windsurf/skills/` | Yes |
-| Continue.dev | `.continue/skills/` | Yes |
-| Cline | `.cline/skills/` | Yes |
-| Zed | `.zed/skills/` | Yes |
-| Amazon Q Developer | `.amazonq/skills/` | Yes |
-| JetBrains AI | `.junie/skills/` | Yes |
-| Aider | `.aider/skills/` | Reference in prompt |
-| Tabnine | `.tabnine/skills/` | Yes |
-| Generic (any tool) | `AGENTS.md` (inlined) | Manual |
+<!-- SECTION:verify required -->
+## Verification before "done"
 
-Install/refresh skills: `specweave refresh-plugins`
+Run the project's build/test/lint (see **Commands**) before reporting any task complete and paste the real output. A task is done only when its **Test** command exits 0. Never skip, weaken, or delete a test to make it pass. Never set `status: completed` by hand; use `specweave complete`.
 <!-- /SECTION -->
 
----
+<!-- SECTION:parallel required -->
+## Working in parallel (any tool, any account)
 
-<!-- SECTION:taskformat required -->
-## Task Format
+1. One worktree per agent, named after the agent: `git worktree add ../NNNN-<agent> -b inc/NNNN-<agent>` (e.g. `../0042-codex -b inc/0042-codex`). The branch name must contain the increment id.
+2. Claim before editing: `specweave task claim T-NN` (or `specweave task next`). Edit only that task's **Files**; need another file → claim its task or add a task. A claim older than 2h with no `done` is stale and may be re-claimed.
+3. Never edit ledger lines or another task's status; append only. On a git conflict in `ledger.jsonl` keep every line from both sides.
+4. `done` needs the task's **Test** command exit 0 and a commit sha. A task that turns out unnecessary is closed with `specweave task skip T-NN --reason "..."` (no CLI: append a `skip` ledger line with a reason), never ticked.
+5. When you stop: `specweave task release --all-mine` then `specweave handoff`.
 
-```markdown
-### T-001: Task Title
-**User Story**: US-001
-**Satisfies ACs**: AC-US1-01, AC-US1-02
-**Status**: [ ] pending / [x] completed
-
-**Test Plan** (BDD):
-- Given [context] → When [action] → Then [result]
-```
+Resuming: find the active increment with `specweave status` (or the `NNNN-*` folder whose `metadata.json` has `"status": "active"`), read `spec.md`, then the latest `handoff.md`, then `specweave task next`.
 <!-- /SECTION -->
 
----
-
-<!-- SECTION:usformat required -->
-## User Story Format (CRITICAL for spec.md)
-
-**MANDATORY: Every User Story MUST have `**Project**:` field!**
-
-```markdown
-### US-001: Feature Name
-**Project**: my-app          # ← MANDATORY! Get from: specweave context projects
-**Board**: digital-ops       # ← MANDATORY for 2-level structures ONLY
-
-**As a** user
-**I want** [goal]
-**So that** [benefit]
+<!-- SECTION:conventions required -->
+## Conventions
 
-**Acceptance Criteria**:
-- [ ] **AC-US1-01**: [Criterion 1]
-- [ ] **AC-US1-02**: [Criterion 2]
-```
-
-**How to get Project/Board values:**
-```bash
-# Run BEFORE creating any increment:
-specweave context projects
-
-# 1-level output (single project):
-# {"level":1,"projects":[{"id":"my-app"}]}
-# → Use: **Project**: my-app
-
-# 2-level output (multi-project with boards):
-# {"level":2,"projects":[...],"boardsByProject":{"corp":[{"id":"digital-ops"}]}}
-# → Use: **Project**: corp AND **Board**: digital-ops
-```
+- Secrets: confirm a key is present without printing its value (`grep -q NAME .env` or `Select-String -Quiet NAME .env`); never commit `.env*`.
+- Prefer deleting code over adapting it; change only what the task needs.
+- Check `.specweave/docs/` ADRs before architectural changes; record new decisions in spec.md **Approach** or an ADR. When a new increment replaces an old one, create it with `--supersedes NNNN` (or set `supersedes` in its metadata.json) instead of leaving the old one open.
 <!-- /SECTION -->
 
----
-
-<!-- SECTION:workflows -->
-## Workflows
-
-### Creating Increment
-1. Run `specweave context projects` → store project IDs
-2. `mkdir -p .specweave/increments/XXXX-feature`
-3. Create `metadata.json` (MUST be FIRST)
-4. Create `spec.md` — every US needs `**Project**:` field (see User Story Format)
-5. Create `tasks.md` (task checklist with BDD tests)
-6. Optional: `plan.md` for complex features
-7. **Verify** tasks.md has `**Test Plan**:` for every task with testable ACs
-8. **Verify** E2E scenarios exist for user-facing user stories — re-run `sw:plan --force` if missing
-
-### Completing Tasks
-1. Implement the task
-2. Run unit tests: `npx vitest run`
-3. Run E2E tests (if task touches UI/API): `npx playwright test`
-4. Only mark task `[x]` after tests pass
-5. Review code quality before committing (Claude Code: `/simplify`; other tools: lint + manual review)
-6. Update tasks.md: `[ ] pending` → `[x] completed`
-7. Update spec.md: check off satisfied ACs
-8. Sync to external trackers if enabled
-9. If 3 consecutive test failures: STOP, re-plan, ask user
-
-### Closing Increment (AUTO — do NOT stop to ask)
-1. Full test suite: `npx vitest run`
-2. Full E2E: `npx playwright test`
-3. `sw:grill <id>` — writes `grill-report.json` (CLI requires it)
-4. `sw:done <id>` — validates report files + PM 3 gates (tasks, tests, docs) + syncs to GitHub/Jira/ADO
-
-**CRITICAL**: When all tasks are done, IMMEDIATELY chain to closure. Quality gates (grill, judge-llm, PM validation) ARE the review. Never stop to ask "should I close?" — just close it. If a gate fails, the increment stays open. User can re-open if they disagree.
+<!-- SECTION:umbrella when="umbrella" -->
+- Umbrella projects only: nested repos live under `repositories/<org>/<repo>/`; commit inside each nested repo, then the umbrella.
 <!-- /SECTION -->
 
----
-
-<!-- SECTION:troubleshooting required -->
+<!-- SECTION:troubleshooting -->
 ## Troubleshooting
 
 | Issue | Fix |
-|-------|-----|
-| Commands not working (non-Claude) | Read `plugins/specweave/commands/<name>.md`, follow manually |
-| GitHub/Jira not updating | `sw:progress-sync` → `sw:sync-docs update` → `sw-github:sync <id>` |
-| .md files in project root | `mv *.md .specweave/increments/<current>/reports/` |
-| Progress % wrong | Update tasks.md manually or `sw:progress-sync` |
-| Tool crashes on start | Load only active increment's spec.md + tasks.md, not entire docs/ |
-| Missing **Project**: field | `specweave context projects`, add `**Project**:` to every US |
-| Skills not activating (non-Claude) | Expected — read SKILL.md from `plugins/specweave*/skills/` |
+|---|---|
+| `specweave` not found | `npm i -g specweave` (optional; the loop works without it) |
+| Instructions out of date after upgrade | `specweave update` |
+| Unsure who owns a task | `specweave task list` |
 <!-- /SECTION -->
 
----
+## Commands
 
-<!-- SECTION:docs -->
-## Documentation
+| Action | Command |
+|---|---|
+| Build | `{{BUILD_CMD}}` |
+| Test | `{{TEST_CMD}}` |
+| Lint | `{{LINT_CMD}}` |
 
-| Resource | Purpose |
-|----------|---------|
-| CLAUDE.md | Quick reference (Claude Code) |
-| AGENTS.md | This file (all AI tools) |
-| verified-skill.com | Official documentation |
-| .specweave/docs/ | Project-specific docs |
-<!-- /SECTION -->
+If a cell still says TODO, fill it in from `package.json`/`Makefile` and commit; `specweave verify` runs these rows.
 
----
+## Project notes
 
-**Generated by SpecWeave** - Specification-first AI development
-**Compatible with**: Claude Code, Cursor, Copilot, Gemini CLI, ChatGPT, and more
-**Last Updated**: {TIMESTAMP}
+(architecture map, things agents get wrong here, recurring mistakes — keep it short)