@alexandrealvaro/agentic 0.1.0-beta.1 → 0.3.0-beta.1

package/README.md

@@ -2,106 +2,167 @@
 
 A starter kit for engineering production code with LLMs. Lean templates and init prompts grounded in established standards: [Anthropic Skills](https://code.claude.com/docs/en/skills), [Claude Code subagents](https://code.claude.com/docs/en/sub-agents), [agents.md](https://agents.md), Nygard ADRs, and [Google Labs DESIGN.md](https://github.com/google-labs-code/design.md).
 
-> **Status:** v0.1.0-beta — early. The CLI works for AGENTS.md bootstrap (`npx @alexandrealvaro/agentic@beta init`); other artifact commands are in development. The manual workflow below stays fully usable for everything. Report rough edges via [GitHub Issues](https://github.com/alexandremendoncaalvaro/agentic-development/issues).
+> **Status:** v0.2 in development on the `cli` branch — the CLI installs the full skill set (universal: `agentic-bootstrap`, `agentic-philosophy`, `agentic-architecture`, `agentic-adr`, `agentic-task`, `agentic-audit`, `agentic-review`; conditional: `agentic-design` for frontend, `agentic-subagent` for Claude Code, `agentic-skill` opt-in) into Claude Code or Codex. Each skill produces its artifact (or runs its operation) via the agent's native conversational UI. v0.1.0-beta on npm still prints prompts; the v0.2 release ships once the polish chunk lands. Report rough edges via [GitHub Issues](https://github.com/alexandremendoncaalvaro/agentic-development/issues).
 
 ## Prerequisites
 
 An agentic coding tool that reads markdown files. Examples here use **Claude Code** and **Codex CLI** (primary tools the author uses); the kit also works with [Antigravity](https://antigravity.google), [Gemini CLI](https://github.com/google-gemini/gemini-cli), Cursor, Continue, Aider, and any other tool that follows the [agents.md](https://agents.md) open standard.
 
-For the CLI path: Node.js 18+ (only needed if you use `npx`/`npm install`; the manual workflow has no runtime dependencies).
+For the CLI path: Node.js 18+. The CLI is the recommended path. Paste-into-agent prompts (see [Manual prompts](#manual-prompts) below) remain as an alternative for users who don't want to run an installer — same artifacts, same patterns.
 
-## What's here
+For the philosophy and full reasoning behind the kit, see [WORKFLOW.md](WORKFLOW.md).
 
-- **[WORKFLOW.md](WORKFLOW.md)** — the philosophy: how to engineer with LLMs without vibe-coding. Read this first.
-- **[templates/](templates/)** — pure templates. Copy and fill, or have your agent fill them via the matching prompt.
-- **[prompts/](prompts/)** — init prompts to paste into your agent. Each generates one artifact from its template.
+## Install & use
 
-## How to use
+```bash
+cd your-project
+npx @alexandrealvaro/agentic@beta init
+```
+
+The CLI installs the universal skill set into your agent's native location, plus conditional skills based on what your project needs:
+
+* **Claude Code:** `.claude/skills/<skill-name>/SKILL.md` (plus `.claude/agents/<name>.md` for skills that ship a subagent)
+* **Codex:** `.agents/skills/<skill-name>/SKILL.md` (+ `agents/openai.yaml`)
 
-This kit is a **reference repository, not a per-project dependency.** Templates and prompts stay here; only the generated artifacts (AGENTS.md, ARCHITECTURE.md, ADRs, etc.) end up in your target project. The pattern matches how [GitHub's spec-kit](https://github.com/github/spec-kit) and [cookiecutter](https://cookiecutter.readthedocs.io/) handle distribution — templates in one place, outputs in another, never mixed.
+Two categories ([ADR-0007](doc/adr/0007-workflow-operational-skills.md)) and two installation modes (universal = always; conditional = depends on project signals or opt-in):
 
-### Quickstart (CLI, beta)
+| Skill | Category | Installs | What it does | Invoke |
+| --- | --- | --- | --- | --- |
+| `agentic-bootstrap` | spec-driven | universal | Scans the repo, writes `AGENTS.md` ≤150 lines | `/agentic-bootstrap` |
+| `agentic-architecture` | spec-driven | universal | Scans the code, writes `ARCHITECTURE.md` | `/agentic-architecture` |
+| `agentic-adr` | spec-driven | universal | Drafts `doc/adr/NNNN-<slug>.md` from the conversation | `/agentic-adr` |
+| `agentic-task` | spec-driven | universal | Drafts `doc/tasks/NNNN-<slug>.md` (checkbox + Notes format) | `/agentic-task` |
+| `agentic-audit` | spec-driven | universal | Read-only drift report (AGENTS.md / ARCHITECTURE.md / ADRs) | `/agentic-audit` |
+| `agentic-philosophy` | workflow-operational | universal | Universal agent guardrails — auto-loads on non-trivial work | implicit |
+| `agentic-review` | workflow-operational | universal | Fresh-context code review per WORKFLOW §10; structured findings, no "approve" | `/agentic-review <range>` |
+| `agentic-design` | spec-driven | auto if frontend detected | Bootstrap `DESIGN.md` from existing tokens (Figma, tailwind.config, tokens.json, CSS custom props) | `/agentic-design` |
+| `agentic-subagent` | spec-driven | auto if installing for Claude Code | Drafts `.claude/agents/<name>.md` (Claude Code only — Codex has no subagent primitive) | `/agentic-subagent` |
+| `agentic-skill` | spec-driven | opt-in only | Drafts a new Claude Code or Codex skill at the appropriate path | `/agentic-skill` |
 
-For AGENTS.md bootstrap, the fastest path is the CLI — no clone needed:
+A short TUI shows the detected mode, agent, and feature signals (frontend / `.claude/` / `.agents/` presence) and lets you toggle the conditional skills. Non-interactive flags: `--agent claude-code | codex | both`, `--yes` to skip confirmations — auto-checked conditionals (e.g., `agentic-design` if the project has React) install; `agentic-skill` stays opt-in. Re-running on an installed project is idempotent — unchanged files report `·`, divergent ones prompt to replace.
+
+If your project already has an `AGENTS.md` (or `CLAUDE.md`), the installer appends a managed `Skills installed by agentic` section bracketed by `<!-- agentic-managed-skills:start -->` / `:end -->` markers. User content outside those markers is byte-preserved; re-runs update only the managed block.
+
+## Updating an existing project
+
+To pull upstream kit changes into a project that already has agentic skills installed:
 
 ```bash
 cd your-project
-npx @alexandrealvaro/agentic@beta init
+npx @alexandrealvaro/agentic@beta update
 ```
 
-The CLI auto-detects greenfield/brownfield/audit mode, then prints a self-contained prompt (templates inlined) for you to paste into your agent. Add `--mode greenfield|brownfield|audit` to override detection.
+`update` is a separate command from `init` (clearer intent) and runs a three-way diff against a state file the kit writes at install time:
+
+* `.claude/agentic-state.json` — for Claude Code installs.
+* `.agents/agentic-state.json` — for Codex installs.
 
-> **Beta scope:** Only `init` (AGENTS.md) is in v0.1.0-beta. For ARCHITECTURE.md, ADRs, design tokens, skills, and subagents, use the [manual workflow](#manual-workflow) below until those CLI commands ship.
+These state files are committed to your repo so the whole team shares one view of what skill version is in place. They record kit version, per-skill version, and the SHA of every shipped file at the time of last install. The three-way diff uses those SHAs to distinguish *user-edited* files from *kit-changed* files and acts accordingly:
 
-### Manual workflow
+| File state | Action |
+| --- | --- |
+| New file in the kit | install |
+| Kit unchanged, you didn't touch it | report unchanged |
+| Kit unchanged, you edited it | keep your edits |
+| Kit changed, you didn't touch it | silent update |
+| Kit changed, you also edited it | prompt with diff (default: skip) |
+| Skill removed from the kit or de-selected | prompt before removing your file (default: keep) |
 
-Required for every artifact except AGENTS.md right now, and useful as a fallback for `init` if you want to run prompts directly without the CLI.
+Useful flags:
 
-#### Setup (once)
+* `--dry-run` — print the action plan without writing anything. Always start here when you're not sure what will happen.
+* `--force` — overwrite user-edited files on conflict (non-interactive default: no). Escape hatch when you genuinely want kit-side content to win.
+* `--agent claude-code | codex | both` — restrict the update to one agent.
+* `--yes` — non-interactive, accepts defaults (skip on conflict, keep orphans). Combine with `--force` if you want overwrites in CI.
 
-1. Read [`WORKFLOW.md`](WORKFLOW.md) — the philosophy that everything else follows from.
-2. Clone this repo to a location outside your projects:
+If the project was installed with a kit version older than v0.3 (no state file present), the first `update` falls back to today's byte-compare behavior, then writes the state file so subsequent runs use the three-way diff.
 
-   ```bash
-   git clone https://github.com/alexandremendoncaalvaro/agentic-development.git ~/dev/agentic-development
-   ```
+The `agentic-review` skill writes the assembled WORKFLOW §10 handoff to `.agentic/reviews/<ISO-timestamp>-<scope>.md` before delegating to the fresh-context reviewer (Claude Code) or before instructing you to `/clear` and paste (Codex). These files are ephemeral audit artifacts — add `.agentic/reviews/` to your `.gitignore`.
 
-   **Never copy this kit into your target project.** Only the generated artifacts go there.
+For persistent install:
 
-#### Give the agent access to templates
+```bash
+npm install -g @alexandrealvaro/agentic@beta
+agentic init
+```
 
-When you paste a prompt from `prompts/`, the agent needs to read the matching template in `templates/`. Two ways to grant access:
+## Manual prompts
 
-- **Recommended** — start the agent with the kit added. In Claude Code, from your target project's directory:
-  ```
-  claude --add-dir <path-to-this-kit>
-  ```
-  The agent can then read templates via the relative paths the prompts use.
-- **Standalone** — copy the content of both `prompts/<X>.md` and `templates/<X>.md` into the agent session. No setup, slightly more friction.
+If you prefer to skip the installer, the same artifacts can be generated by pasting prompts directly into your agent. Each prompt file has the literal text to copy, plus the matching template structure:
+
+| Artifact | Prompt | Template | Lives at |
+| --- | --- | --- | --- |
+| `AGENTS.md` | [prompts/agents.md](prompts/agents.md) | [agents-project](templates/agents-project.md) | repo root |
+| `ARCHITECTURE.md` | [prompts/architecture.md](prompts/architecture.md) | [architecture](templates/architecture.md) | repo root |
+| ADR | [prompts/adr.md](prompts/adr.md) | [adr](templates/adr.md) | `doc/adr/NNNN-<title>.md` |
+| Task | [prompts/task.md](prompts/task.md) | [task](templates/task.md) | `doc/tasks/NNNN-<slug>.md` |
+| `DESIGN.md` | [prompts/design.md](prompts/design.md) | (no template — bootstrap from existing tokens) | repo root |
+| Skill | [prompts/skill.md](prompts/skill.md) | [skill](templates/skill.md) | `.claude/skills/<name>/SKILL.md` |
+| Subagent | [prompts/subagent.md](prompts/subagent.md) | [subagent](templates/subagent.md) | `.claude/agents/<name>.md` |
 
-#### Workflows by scenario
+Prompts reference templates by relative path. Two ways to give your agent access:
 
-**New project (greenfield).** Initialize git and set up the project structure, then paste `prompts/agents.md`. The agent interviews you about stack, build, test, conventions, and security boundaries, then writes `AGENTS.md` at the repo root. As architectural and design decisions emerge, use `prompts/architecture.md`, `prompts/adr.md`, `prompts/design.md`, `prompts/skill.md`, and `prompts/subagent.md` for each new artifact.
+- **Browse on GitHub.** Open the prompt and template files in tabs, copy both into your agent session. No install.
+- **Use the npm-installed package as a kit folder.** If you ran `npm install -g @alexandrealvaro/agentic@beta`, the kit is already on disk. For Claude Code from your project's directory:
+  ```bash
+  claude --add-dir "$(npm root -g)/@alexandrealvaro/agentic"
+  ```
+  The agent then reads the templates locally via the paths the prompts use.
 
-**Existing project (brownfield).** Same prompts. The project-wide ones (`prompts/agents.md`, `prompts/architecture.md`) instruct the agent to read the codebase, verify what you told them, and flag any mismatch before writing — so contradictions get surfaced instead of trusted. The per-artifact prompts (ADR, design, skill, subagent) work on a single decision or asset and don't need this verification. Backfill ADRs only for decisions that matter going forward; don't try to rewrite history.
+## Workflows by scenario
 
-**Revisiting / auditing existing specs.** When specs may have drifted from code, paste:
+**New project (greenfield).** Initialize git and project structure, then run `agentic init` to install the universal skill set plus any auto-detected conditional skills. From inside Claude Code or Codex: `/agentic-bootstrap` produces `AGENTS.md`, `/agentic-architecture` produces `ARCHITECTURE.md`, `/agentic-adr` records each binding decision, `/agentic-task` opens trackable work items, `/agentic-audit` flags drift, `/agentic-review <range>` runs a fresh-context review of a diff, `/agentic-design` bootstraps `DESIGN.md` from your tokens (frontend projects), `/agentic-subagent` and `/agentic-skill` scaffold custom subagents and skills. `agentic-philosophy` auto-loads on non-trivial work.
 
-> *"Read AGENTS.md (or ARCHITECTURE.md). Compare with the current state of the codebase. For every place where the spec disagrees with the code, list the disagreement and suggest whether the spec or the code should change. Do not rewrite the spec yourself — flag and wait."*
+**Existing project (brownfield).** Same flow. The project-wide skills (`/agentic-bootstrap`, `/agentic-architecture`) follow a **scan-first pattern**: the agent reads the codebase first, pre-fills every placeholder it can verify, then asks you only about the genuine gaps and conflicts — no philosophical questions, no interview-by-section. The per-artifact skills (`/agentic-adr`, `/agentic-task`, `/agentic-design`, `/agentic-skill`, `/agentic-subagent`) work on a single decision or asset and don't need codebase-wide verification. Backfill ADRs only for decisions that matter going forward.
 
-Apply judgment manually; don't let the agent rewrite specs unattended.
+**Revisiting / auditing existing specs.** Run `/agentic-audit` from inside Claude Code or Codex. The skill reads `AGENTS.md`, `ARCHITECTURE.md`, and `doc/adr/` and produces a drift list — one finding per line, format `[file or section]: spec says X, code says Y. Suggested resolution: change spec / change code / discuss.` Read-only — never rewrites specs. Apply judgment manually before changing anything.
 
-**Project already built with agents.** Treat missing artifacts as brownfield (generate via the relevant prompt) and existing artifacts as audit (run the comparison prompt above).
+**Reviewing your own diff.** Run `/agentic-review <range>` (e.g. `/agentic-review main..HEAD` or `/agentic-review PR#42`). The skill assembles the diff, the relevant spec slice (`AGENTS.md`, applicable ADRs, the task's Acceptance Criteria), and delegates to a fresh-context reviewer subagent — no inherited bias from the session that wrote the code (WORKFLOW §10). Returns structured findings grouped Blocker / Concern / Note. Codex variant uses `/clear` + paste handoff since Codex has no subagent primitive.
 
-#### What ends up in your target project
+**Project already built with agents.** Treat missing artifacts as brownfield (run the relevant skill) and existing artifacts as audit (`/agentic-audit`).
+
+## What ends up in your target project
 
 Only the generated outputs — never templates, prompts, or this guide:
 
 ```
 your-project/
-├── AGENTS.md
+├── AGENTS.md                   (with a managed "Skills installed by agentic" section
+│                                appended below your content if AGENTS.md already existed)
 ├── ARCHITECTURE.md
-├── DESIGN.md                  (optional, UI projects)
+├── DESIGN.md                   (optional, frontend projects)
 ├── doc/
-│   └── adr/
-│       └── NNNN-<title>.md
-└── .claude/
-    ├── skills/<name>/SKILL.md
-    └── agents/<name>.md
+│   ├── adr/
+│   │   └── NNNN-<title>.md
+│   └── tasks/
+│       └── NNNN-<slug>.md
+├── .agentic/
+│   └── reviews/                (gitignored — ephemeral §10 review handoffs)
+├── .claude/                    (Claude Code targets)
+│   ├── agentic-state.json      (kit install state — committed)
+│   ├── skills/agentic-*/SKILL.md
+│   └── agents/fresh-context-reviewer.md
+└── .agents/                    (Codex targets, cc-sdd convention)
+    ├── agentic-state.json      (kit install state — committed)
+    └── skills/agentic-*/{SKILL.md, agents/openai.yaml}
 ```
 
-### Reference table
+The pattern matches how [GitHub's spec-kit](https://github.com/github/spec-kit) and [cookiecutter](https://cookiecutter.readthedocs.io/) handle distribution — templates in one place, outputs in another, never mixed.
+
+## Develop or fork
+
+Want to contribute, fork, or run the CLI from source?
 
-| Artifact          | Template                                                                                      | Prompt                                              | Lives at                          |
-| ----------------- | --------------------------------------------------------------------------------------------- | --------------------------------------------------- | --------------------------------- |
-| `AGENTS.md`       | [agents-general](templates/agents-general.md) + [agents-project](templates/agents-project.md) | [prompts/agents.md](prompts/agents.md)              | repo root                         |
-| `ARCHITECTURE.md` | [architecture](templates/architecture.md)                                                     | [prompts/architecture.md](prompts/architecture.md)  | repo root                         |
-| ADR               | [adr](templates/adr.md)                                                                       | [prompts/adr.md](prompts/adr.md)                    | `doc/adr/NNNN-<title>.md`         |
-| `DESIGN.md`       | (no template — bootstrap from existing tokens)                                                | [prompts/design.md](prompts/design.md)              | repo root                         |
-| Skill             | [skill](templates/skill.md)                                                                   | [prompts/skill.md](prompts/skill.md)                | `.claude/skills/<name>/SKILL.md`  |
-| Subagent          | [subagent](templates/subagent.md)                                                             | [prompts/subagent.md](prompts/subagent.md)          | `.claude/agents/<name>.md`        |
+```bash
+git clone https://github.com/alexandremendoncaalvaro/agentic-development.git
+cd agentic-development
+npm install
+node bin/agentic.js init
+```
 
-Templates carry pure structure. Prompts carry the spec links, conventions, and the literal text to paste.
+Branch layout:
+- `main` — manual workflow source of truth (no CLI code; the npm package gets promoted here when mature).
+- `cli` — CLI development (you're here). Beta releases are published from this branch.
 
 ## License
 

package/WORKFLOW.md

@@ -49,7 +49,20 @@ Avoid putting implementation code in docs unless it's executable, generated, or
 
 The split is simple. **Docs are for the *why*** — decisions, not history. Git tracks history; docs explain the reasoning that won't survive otherwise. **Code is for the *what*** — clean naming and small units make logic self-evident, and the more your code does this work, the less your docs need to.
 
-Comments are exceptions. They justify *why* a non-obvious choice was made — never *what* the line does. No commented-out code, and no orphan `TODO` or `FIXME`: every deferred item references an issue, ADR, or explicit follow-up.
+Comments are exceptions. They justify *why* a non-obvious choice was made — never *what* the line does. No commented-out code, and no orphan `TODO` or `FIXME`: every deferred item references a tracked work item — a GitHub Issue or a per-task file under `doc/tasks/NNNN-*.md`.
+
+### Documentation Discipline
+
+Eight rules apply to every document the agent or the human writes in the project. They are framed against the failure modes the kit has actually seen — bloated `AGENTS.md`, README pages that drift into changelogs, decision artifacts diluted by speculation.
+
+1. **Definitions and decisions only.** Documentation captures what is true now and the decisions that brought it there. Speculation, history, and unfounded plans are out. A deferred decision is in scope when it is *recorded* — an accepted ADR or a task file is fundamentação; "we might do X later" without a record is speculation and is cut.
+2. **No dates, version stamps, `DRAFT` markers, or changelogs in narrative documents.** Applies to `README.md`, `AGENTS.md` / `CLAUDE.md`, `ARCHITECTURE.md`, `DESIGN.md`, specs, and any prose page. **Decision-record artifacts are exempt** — ADRs under `doc/adr/` (Nygard `Status` lifecycle requires a date) and tasks under `doc/tasks/` (append-only `Notes` log is the auditability surface). Use git history for narrative-doc evolution; keep the dated lifecycle inside the artifacts that need it.
+3. **No emoji anywhere.** Not in docs, code, source comments, commit messages, PR bodies, or skill outputs. Severity tags use plain words (`Blocker / Concern / Note`); status uses words (`accepted / superseded`); structural cues use Markdown.
+4. **Business context first.** Every document opens with *why* — the problem, the constraint, the user — before *what* and *how*. The first paragraph answers "what would break if this document didn't exist".
+5. **One scope per document. No duplication.** If two documents would say the same thing, link instead of copying. The canonical location owns the content; everywhere else references it.
+6. **Code is the primary documentation of behavior.** Comments justify *why* a non-obvious choice was made — never restate *what* the line does. If the comment is needed to explain *what*, rename or refactor.
+7. **No commented-out code; no orphan `TODO` / `FIXME` in source.** Every deferred item references a tracked work item — a GitHub Issue, or a per-task file under `doc/tasks/NNNN-*.md` (the kit's file-based tracking surface). The trace must be addressable from the source line.
+8. **Tests are living documentation of behavior.** Test names and assertions should read as the spec they enforce. When the spec changes, the test changes; when the test changes, the spec it documents must already have changed.
 
 ## 3. Format by Evidence
 
@@ -89,7 +102,7 @@ Cite specific files, not "the codebase." Use just-in-time retrieval: pass paths
 For non-trivial changes, four phases:
 
 1. **Explore (read-only).** Plan mode in your agent. Read, build a mental model, no edits.
-2. **Plan.** Agent writes a Markdown plan. You edit before approving.
+2. **Plan.** Agent writes a Markdown plan. You edit before approving. For non-trivial multi-step work, structure the plan as a per-task file (`doc/tasks/<NNNN>-<slug>.md`) with checkbox acceptance criteria and execution steps — the agent toggles checkboxes as it works rather than rewriting paragraphs, keeping edits cheap and resumable across sessions.
 3. **Implement.** Execute the approved plan; verify each step before moving to the next.
 4. **Commit.** One logical change per commit.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alexandrealvaro/agentic",
-  "version": "0.1.0-beta.1",
+  "version": "0.3.0-beta.1",
   "description": "Bootstrap and audit AGENTS.md, ARCHITECTURE.md, ADRs, skills, and subagents for engineering production code with LLMs",
   "type": "module",
   "bin": {
@@ -20,7 +20,7 @@
   },
   "scripts": {
     "start": "node bin/agentic.js",
-    "test": "node bin/agentic.js --help && node bin/agentic.js init --help",
+    "test": "node bin/agentic.js --help && node bin/agentic.js init --help && node bin/agentic.js update --help && node --test test/*.test.js",
     "prepublishOnly": "npm test"
   },
   "keywords": [
@@ -48,7 +48,9 @@
   },
   "dependencies": {
     "@clack/prompts": "^1.3.0",
-    "clipboardy": "^5.3.1",
     "commander": "^12.1.0"
+  },
+  "devDependencies": {
+    "js-yaml": "^4.1.0"
   }
 }

package/prompts/agents.md

@@ -4,10 +4,18 @@ Open standard: [agents.md](https://agents.md) (Linux Foundation / Agentic AI Fou
 
 ## Paste to your agent
 
-> Read [`templates/agents-general.md`](../templates/agents-general.md) and [`templates/agents-project.md`](../templates/agents-project.md). Interview me one section at a time to fill `agents-project.md`'s placeholders: stack, build/test/lint commands, repo layout (only what's not obvious from the tree), commit conventions, security boundaries, real gotchas you can confirm by reading the code.
+> Read [`templates/agents-project.md`](../templates/agents-project.md). Your job: produce a single `AGENTS.md` at the repo root, ≤150 lines, every line operational. Generic agent behavior (think-before-coding, verify-before-done, etc.) does **not** belong here — that lives in the `agentic-philosophy` skill.
 >
-> **Do not invent values.** When I don't know something, leave `<TODO>` and move on. After the interview, read the codebase to verify what I told you and flag any mismatch.
+> **Step 1 — Scan.** Read `package.json` / `pyproject.toml` / `Cargo.toml` / `go.mod` / equivalent, `README.md`, top-level directories, `doc/` and `doc/adr/` if present, `.claude/` if present, lockfiles, hook configs (`.husky/`, `.pre-commit-config.yaml`, `.github/workflows/`), `git remote -v`. Build a model of stack, entry points, build/test commands, conventions, quality gates, security boundaries, gotchas confirmed by code.
 >
-> Output a single `AGENTS.md` at the repo root: filled `agents-project.md` content first, then `agents-general.md` content appended (drop its H1 — `agents-project.md`'s `# AGENTS.md` owns the merged document).
+> **Step 2 — Pre-fill.** For every `<placeholder>` in [`templates/agents-project.md`](../templates/agents-project.md), fill it from observed signals. No fabrication. If a section has no signal, mark `<TODO: not yet wired>` in one line and move on — do not write meta-prose explaining the gap.
 >
-> Cut every line you can — bloat makes the agent ignore rules.
+> **Step 3 — Show me only the gaps.** Print:
+> - (a) placeholders you could not fill from repo signals;
+> - (b) signals that conflict (e.g. two test commands, two style configs).
+>
+> One question per gap. Skip everything you filled confidently. Do **not** ask philosophical questions ("is this doc primarily for agents or humans?", "what's the most important quality bar?") — those are decisions, not interview material.
+>
+> **Step 4 — On my confirmation, write `AGENTS.md`.** Cut every line that does not change agent behavior. No "External Resources" section (the agent derives URLs from `git remote` / `package.json`). No marketing prose. No appended Universal Agent Behavior block.
+>
+> If something I say contradicts what the code shows, surface the conflict. Don't silently trust me; don't silently trust the code. Flag and wait.

package/prompts/architecture.md

@@ -4,8 +4,18 @@ Pairs with ADRs in `doc/adr/`. Architecture is the binding pattern; ADRs are ind
 
 ## Paste to your agent
 
-> Read [`templates/architecture.md`](../templates/architecture.md). Interview me one section at a time to fill its placeholders: overview, layers and boundaries, patterns (data access, HTTP handlers, async/messaging, errors, validation), naming, observability, deployment topology.
+> Read [`templates/architecture.md`](../templates/architecture.md). Your job: produce `ARCHITECTURE.md` at the repo root.
 >
-> Before writing each section, read the codebase to verify the claim is real. **Do not invent.** Leave `<TODO>` for unknowns.
+> **Step 1 — Scan the code.** Read top-level dirs, the main entry points (servers, CLI, jobs), boundary code (handlers, repos, gateways, middleware), config and env loading, observability hooks, deploy config (`Dockerfile`, `compose.yml`, `k8s/`, `terraform/`, GitHub Actions). Existing ADRs in `doc/adr/` are binding — read them all.
 >
-> Output `ARCHITECTURE.md` at the repo root. At the end, list any decision that should become an ADR — don't write them yet, just flag.
+> **Step 2 — Pre-fill.** For each placeholder, fill from what the code actually does: layers and boundaries, data access pattern, HTTP middleware chain, async/messaging, error and validation patterns, naming, logging/metrics/tracing, deployment topology. No fabrication.
+>
+> **Step 3 — Show me only the gaps.** Print:
+> - (a) placeholders without a code signal;
+> - (b) places where the code shows two competing patterns (e.g. some handlers go through middleware, some don't).
+>
+> One question per gap.
+>
+> **Step 4 — On my confirmation, write the file.** Cut every line that does not lock a binding pattern. At the end, list any decision that should become an ADR — flag, do not write the ADR yet.
+>
+> If something I say contradicts what the code shows, surface the conflict. Don't silently trust me; don't silently trust the code.

package/prompts/task.md

@@ -0,0 +1,26 @@
+# Bootstrap a Task
+
+A per-task tracking file optimized for LLM editing: status changes via single checkbox toggles, append-only Notes log, no rewrites of large blocks.
+
+## Where it lives
+
+`doc/tasks/<NNNN>-<short-slug>.md` — sequential numbering, kebab-case slug, mirrors the ADR convention (`doc/adr/`).
+
+## Why this format
+
+Toggling a checkbox is a single-character `Edit` operation. Rewriting a paragraph is risky and expensive in tokens. Markdown checklists make the LLM's edits cheap, reviewable, and idempotent. Pattern documented in [spec-kit's tasks.md](https://github.com/github/spec-kit/blob/main/templates/commands/tasks.md), [taskmd](https://medium.com/@driangle/taskmd-task-management-for-the-ai-era-92d8b476e24e), [Backlog.md](https://github.com/MrLesk/Backlog.md), and [Claude Code's Tasks API](https://platform.claude.com/docs/en/agent-sdk/todo-tracking).
+
+## Paste to your agent
+
+> Use [`templates/task.md`](../templates/task.md) to draft `doc/tasks/<NNNN>-<short-slug>.md` (next available number) for the task: `<one-line task description>`.
+>
+> Interview me to fill:
+> - Context: why this task, what problem it solves
+> - Acceptance Criteria: measurable conditions per [WORKFLOW.md §1](../WORKFLOW.md), each as a checkbox — pass/fail must be observable, not aspirational ("loads in under 2s" not "fast enough")
+> - Plan: concrete sequential steps with file paths where applicable, each as a checkbox
+>
+> Status starts at `proposed`. Created: today. Owner: ask me. Board ref: leave blank unless I provide one. Leave Notes empty (it gets filled during execution). Definition of Done section stays as in the template.
+>
+> **Do not invent values.** When I don't know something, leave `<TODO>` and ask. Stop after writing the file. Wait for me to start work.
+>
+> When working on the task later, edit the file by toggling checkboxes (`- [ ]` → `- [x]`) and appending to Notes — never rewrite existing sections.