@reforma/agentflow 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Reforma contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,252 @@
+# AgentFlow
+
+An opinionated workflow for producing high-quality, production-ready changes
+with coding agents.
+
+Medium and large tasks are difficult to carry through in a single chat without
+losing quality. The scope grows during implementation, earlier requirements
+disappear into the history, and unanswered questions are left for the agent to
+decide. Those decisions are often wrong. The longer the chat runs, the less
+reliable its context becomes, while compacting it or moving the work to a new
+chat loses the reasoning behind earlier decisions.
+
+For anything bigger than a quick fix, we usually start by exploring the existing
+feature, code, or technology. Once the agent knows the ground, we grill the idea
+and talk through the tricky parts before touching code. Then we usually write a
+plan and split the work into PR-sized chunks. Small tasks can skip the plan and
+go straight to implementation.
+
+Work through the chunks in order, however you prefer: stay in the same chat,
+summarize it between PRs, start a fresh chat, or write the code yourself. Review
+and commit each PR before moving to the next one, while the diff is still small
+enough to clean up properly. When the context gets noisy, summarize it or write
+a handoff to disk before continuing.
+
+The core loop is:
+
+```text
+Research → Grill → Plan → PR → Review → Commit
+                          ↑                  │
+                          └──── Next PR ─────┘
+```
+
+Research is optional, small tasks can skip the plan, and a handoff is only
+needed when you move the work to a fresh context.
+
+Reusable agent skills are published from `skills/`:
+
+- `/research` — save technology or landscape research for later chats
+- `/grill` — question an idea until the important decisions are clear
+- `/plan` — split the work into PR-sized slices
+- `/code-review` — review each slice for reuse and unnecessary complexity
+- `/handoff` — save context before moving to a fresh chat
+- `/tdd` — work through one red-green slice at a time
+
+---
+
+## The Loop
+
+Research helps when the agent does not know the area, and most larger tasks also need a plan. But almost every task goes through Grill. Small, obvious changes can go straight from Grill to implementation.
+
+1. Learn how it works (optional)
+2. Sharpen the idea with Grill
+3. Slice the work into PRs
+4. Implement one PR
+5. Agent review
+6. Your review, then commit
+7. Refresh the context when needed or start the new chat
+
+Repeat steps 4–7 until every PR in the plan is complete.
+
+### Step 1. Learn how it works (optional)
+
+Research does not require a skill. Even a simple prompt like "Find out how
+authentication works in this project" can make the implementation much easier.
+
+This step is optional, but highly recommended when the agent has not worked in
+the area before. It lets the agent understand what it will be changing before
+the implementation starts.
+
+Use `/research` when the findings should survive the current chat. It saves the
+research artifacts under `.agentflow/<feature>/research/`, ready to attach after
+context compaction or in a new chat.
+
+Even if you skip this step, Grill will fill in any gaps.
+
+### Step 2. Sharpen the idea with Grill
+
+Grill is the core of AgentFlow and the one step used for the most tasks.
+
+Run `/grill` after research, or start with it when research is not needed.
+
+The agent explains how it understands the task, surfaces assumptions and
+decision points, and recommends an answer for each one. You confirm or correct
+that understanding. If your answers open new questions, the agent continues
+until nothing important is left unclear.
+
+This gives the implementation an agreed starting point instead of leaving the
+agent to fill in gaps on its own.
+
+### Step 3. Plan and slice the work into PRs
+
+For a larger task, planning usually follows Grill in the same chat. If you asked
+Grill to plan next, it loads `/plan` automatically. You can also run `/plan`
+yourself.
+
+In a normal chat, `/plan` saves the result to `.agentflow/<slug>/plan.md`. In
+Native Plan mode, the agent uses its built-in planning flow and native plan
+artifact instead.
+
+The plan breaks the feature into PRs that can be shipped one by one. A PR is the
+smallest complete change with one coherent outcome and a clear way to verify it,
+not a fixed number of files or lines.
+
+Larger work is usually sliced from foundations to consumers. A full-stack
+feature might start with behavior-preserving refactoring, continue with shared
+types and backend work, and finish with the frontend. A frontend feature might
+move from reusable components, through shared runtime or wiring, to the
+user-facing interface.
+
+These are examples, not a required template. A small feature stays as one
+vertical slice. Feature-local components and wiring stay with the interface
+that first uses them instead of becoming placeholder PRs.
+
+Keep the plan updated as the work changes.
+
+**Done when:** someone can open the plan, find the next PR, and see how to
+verify it.
+
+### Step 4. Implement one PR
+
+Implement the first unchecked PR and nothing beyond it. Without a plan, keep the
+change small enough to review. You can stay in the current chat, start a fresh
+one, or write the code yourself. Bring the plan and latest handoff when moving
+to another chat. Use `/tdd` for test-first work.
+
+Load any relevant skills named in `AGENTS.md`. If work spills into a later PR,
+update the plan instead of silently expanding the current one.
+
+**Done when:** the PR does what the plan promised, and the plan matches the work.
+
+### Step 5. Agent review
+
+Run `/code-review` on the completed PR. It looks for code to reuse, unnecessary
+wrappers, and avoidable complexity. It fixes small local problems and returns a
+verdict: keep, shrink, or burn.
+
+**Done when:** the review has run and its local fixes are applied.
+
+### Step 6. Your review, then commit
+
+Read the diff yourself, then commit it using the project's normal workflow.
+
+**Done when:** the PR is reviewed and committed.
+
+### Step 7. Refresh the context when needed
+
+Keep the current chat if it still has useful context. When it gets noisy,
+summarize it or start a fresh one. Run `/handoff` to save what shipped, what
+changed, and which PR comes next.
+
+Attach the plan and handoff to a fresh chat when they exist.
+
+**Done when:** you can start the next PR without reconstructing the previous
+work. Return to step 4.
+
+## Install
+
+Install the complete workflow in a project:
+
+```bash
+npx @reforma/agentflow init
+```
+
+The command installs every AgentFlow skill, writes `AGENTFLOW.md`, and ignores
+the local `.agentflow/` artifacts. It prints a short pointer you can add to
+`AGENTS.md` when you want agents in that project to follow the full loop.
+
+Install only one skill without the workflow:
+
+```bash
+npx skills add reforma-dev/agentflow --skill plan
+```
+
+Update the complete workflow:
+
+```bash
+npx @reforma/agentflow@latest update
+```
+
+Or update one independently installed skill:
+
+```bash
+npx skills update plan
+```
+
+---
+
+## Why AgentFlow?
+
+Coding agents can handle large changes, but chat history is a poor place to
+keep requirements, scope, and decisions. AgentFlow moves that information into
+small files and gives each PR a clear boundary.
+
+- **Learn the ground before estimating the work** — the agent sees the existing
+  behavior and code before discussing a solution.
+- **Resolve decisions before coding** — `/grill` exposes assumptions while they
+  are still cheap to change.
+- **Keep changes reviewable** — the plan divides a large feature into PR-sized
+  slices that are implemented and reviewed in order.
+- **Preserve context between sessions** — the review artifacts, plan and handoff tell the next agent what is true and what comes next.
+- **Use an opinionated workflow without heavy artifacts** — the sequence is
+  fixed, while the documentation is limited to one plan and one current
+  handoff.
+
+### How we compare
+
+OpenSpec and Spec Kit try to cover most of spec-driven development with their
+own commands, templates, and artifacts. AgentFlow does not try to be an
+all-in-one system. It adds a small, opinionated loop to the way you already
+build software.
+
+**vs. [OpenSpec](https://github.com/Fission-AI/OpenSpec)** — OpenSpec manages
+proposals, requirements, designs, tasks, and completed changes. That works when
+specs are the center of the process, but it also means adopting OpenSpec's
+artifact system. AgentFlow does not require a spec tree. Most work needs one
+plan and a handoff only when the context moves to a new chat.
+
+**vs. [Spec Kit](https://github.com/github/spec-kit)** — Spec Kit provides a
+thorough, phase-based process with a constitution, specifications, plans, and
+task lists. AgentFlow gives you an order of work without asking you to move the
+rest of your development process into the framework.
+
+**vs. an unstructured chat** — Working directly in chat is enough for a small
+fix. On larger changes, AgentFlow keeps decisions out of transient history,
+limits scope to one reviewable slice, and gives the next session a reliable
+starting point.
+
+## Releasing
+
+Add a changeset with every publishable change:
+
+```bash
+bun run changeset
+```
+
+When that changeset reaches `main`, the publish workflow tests the package,
+updates its version and changelog, publishes it to npm through trusted
+publishing, and commits the release files back to `main`. A separate job then
+publishes the matching versioned Agent Skills release on GitHub.
+
+The npm trusted publisher for `@reforma/agentflow` must point at
+`reforma-dev/agentflow/.github/workflows/publish_npm.yml`.
+
+Validate a release locally without publishing:
+
+```bash
+gh skill publish --dry-run
+bun run test
+bun publish --dry-run
+```
+
+AgentFlow is available under the [MIT License](LICENSE).

package/bin/agentflow.js

@@ -0,0 +1,189 @@
+#!/usr/bin/env node
+
+// src/cli.ts
+import { existsSync as existsSync2, readFileSync as readFileSync3 } from "node:fs";
+import { dirname as dirname2, resolve as resolve3 } from "node:path";
+import { fileURLToPath } from "node:url";
+
+// src/project.ts
+import {
+  existsSync,
+  readFileSync,
+  renameSync,
+  writeFileSync
+} from "node:fs";
+import { resolve } from "node:path";
+var GENERATED_MARKER = "<!-- Generated by AgentFlow CLI. Run `npx @reforma/agentflow@latest update` to refresh. -->";
+var AGENTS_SNIPPET = "**Agent loop:** [AGENTFLOW.md](AGENTFLOW.md) — optional research → grill → usually `/plan` → sequential PRs (implement → `/code-review` → commit) → refresh context when needed.";
+function generatedWorkflow(workflow) {
+  return `${GENERATED_MARKER}
+
+${workflow.trimEnd()}
+`;
+}
+function isGeneratedWorkflow(path) {
+  return existsSync(path) && readFileSync(path, "utf8").startsWith(GENERATED_MARKER);
+}
+function writeAtomically(path, contents) {
+  const temporaryPath = `${path}.agentflow-tmp`;
+  writeFileSync(temporaryPath, contents);
+  renameSync(temporaryPath, path);
+}
+function ensureIgnored(cwd) {
+  const path = resolve(cwd, ".gitignore");
+  const current = existsSync(path) ? readFileSync(path, "utf8") : "";
+  const alreadyIgnored = current.split(/\r?\n/).some((line) => /^\/?\.agentflow\/?$/.test(line.trim()));
+  if (alreadyIgnored) {
+    return;
+  }
+  const separator = current.length === 0 || current.endsWith(`
+`) ? "" : `
+`;
+  writeAtomically(path, `${current}${separator}.agentflow/
+`);
+}
+
+// src/skills.ts
+import { spawnSync } from "node:child_process";
+import { readFileSync as readFileSync2 } from "node:fs";
+import { createRequire } from "node:module";
+import { dirname, resolve as resolve2 } from "node:path";
+var AGENTFLOW_SKILLS = [
+  "research",
+  "grill",
+  "plan",
+  "code-review",
+  "handoff",
+  "tdd"
+];
+var SKILLS_SOURCE = "reforma-dev/agentflow";
+var runSkills = (args) => {
+  const require2 = createRequire(import.meta.url);
+  const packagePath = require2.resolve("skills/package.json");
+  const packageJson = JSON.parse(readFileSync2(packagePath, "utf8"));
+  const relativeBin = typeof packageJson.bin === "string" ? packageJson.bin : packageJson.bin.skills;
+  if (!relativeBin) {
+    throw new Error("The installed skills package does not expose a skills bin.");
+  }
+  const result = spawnSync(process.execPath, [resolve2(dirname(packagePath), relativeBin), ...args], { stdio: "inherit" });
+  if (result.error) {
+    throw result.error;
+  }
+  return result.status ?? 1;
+};
+
+// src/cli.ts
+var packageRoot = resolve3(dirname2(fileURLToPath(import.meta.url)), "..");
+var packageJson = JSON.parse(readFileSync3(resolve3(packageRoot, "package.json"), "utf8"));
+function parseOptions(args, command) {
+  const forwarded = [];
+  for (let index = 0;index < args.length; index += 1) {
+    const argument = args[index];
+    if (argument === "--agent" || argument === "-a") {
+      if (command !== "init") {
+        throw new Error(`${argument} is only supported by init.`);
+      }
+      const agent = args[index + 1];
+      if (!agent || agent.startsWith("-")) {
+        throw new Error(`${argument} requires an agent name.`);
+      }
+      forwarded.push(argument, agent);
+      index += 1;
+      continue;
+    }
+    if (argument === "--global" || argument === "-g") {
+      forwarded.push(argument);
+      continue;
+    }
+    if (argument === "--project" || argument === "-p") {
+      if (command !== "update") {
+        throw new Error(`${argument} is only supported by update.`);
+      }
+      forwarded.push(argument);
+      continue;
+    }
+    if (argument === "--yes" || argument === "-y") {
+      forwarded.push(argument);
+      continue;
+    }
+    throw new Error(`Unknown option: ${argument}`);
+  }
+  return forwarded;
+}
+function help() {
+  return `AgentFlow ${packageJson.version}
+
+Usage:
+  agentflow init [--agent <name>] [--global] [--yes]
+  agentflow update [--global | --project] [--yes]
+  agentflow --version
+
+Commands:
+  init      Install all AgentFlow skills and write AGENTFLOW.md
+  update    Update installed AgentFlow skills and refresh AGENTFLOW.md
+
+AgentFlow prints the AGENTS.md snippet for you to add manually.
+`;
+}
+function runCli(args, {
+  cwd = process.cwd(),
+  stdout = process.stdout,
+  stderr = process.stderr,
+  runSkills: executeSkills = runSkills,
+  workflow = readFileSync3(resolve3(packageRoot, "README.md"), "utf8")
+} = {}) {
+  const [command, ...optionArgs] = args;
+  if (!command || command === "--help" || command === "-h") {
+    stdout.write(help());
+    return 0;
+  }
+  if (command === "--version" || command === "-v") {
+    stdout.write(`${packageJson.version}
+`);
+    return 0;
+  }
+  if (command !== "init" && command !== "update") {
+    stderr.write(`Unknown command: ${command}
+
+${help()}`);
+    return 1;
+  }
+  try {
+    const forwarded = parseOptions(optionArgs, command);
+    const workflowPath = resolve3(cwd, "AGENTFLOW.md");
+    if (existsSync2(workflowPath) && !isGeneratedWorkflow(workflowPath)) {
+      throw new Error("AGENTFLOW.md is not managed by AgentFlow CLI. Move it or merge it manually before continuing.");
+    }
+    if (command === "update" && !existsSync2(workflowPath)) {
+      throw new Error("AgentFlow is not initialized here. Run `agentflow init`.");
+    }
+    const skillsArgs = command === "init" ? ["add", SKILLS_SOURCE, "--skill", "*", ...forwarded] : ["update", ...AGENTFLOW_SKILLS, ...forwarded];
+    const status = executeSkills(skillsArgs);
+    if (status !== 0) {
+      stderr.write(`Agent skills ${command} failed with exit code ${status}.
+`);
+      return status;
+    }
+    writeAtomically(workflowPath, generatedWorkflow(workflow));
+    ensureIgnored(cwd);
+    if (command === "init") {
+      stdout.write(`AgentFlow initialized.
+
+Add this line to AGENTS.md:
+
+${AGENTS_SNIPPET}
+`);
+    } else {
+      stdout.write(`AgentFlow updated.
+`);
+    }
+    return 0;
+  } catch (error) {
+    stderr.write(`${error instanceof Error ? error.message : String(error)}
+`);
+    return 1;
+  }
+}
+
+// src/bin.ts
+process.exitCode = runCli(process.argv.slice(2));

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@reforma/agentflow",
+  "version": "0.0.1",
+  "description": "An opinionated workflow for shipping production-ready changes with coding agents.",
+  "author": "Reforma, Inc. <dev@reforma.ai>",
+  "type": "module",
+  "bin": {
+    "agentflow": "bin/agentflow.js"
+  },
+  "files": [
+    "bin",
+    "skills",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "bun build src/bin.ts --target=node --outfile=bin/agentflow.js --external skills",
+    "typecheck": "tsc --noEmit",
+    "changeset": "bunx @changesets/cli",
+    "version-packages": "bunx @changesets/cli version",
+    "release": "bunx @changesets/cli publish",
+    "test": "bun test",
+    "validate:skills": "gh skill publish --dry-run",
+    "prepublishOnly": "bun run typecheck && bun run test && bun run build"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/reforma-dev/agentflow.git"
+  },
+  "homepage": "https://github.com/reforma-dev/agentflow#readme",
+  "bugs": "https://github.com/reforma-dev/agentflow/issues",
+  "keywords": [
+    "agent-skills",
+    "coding-agents",
+    "cursor",
+    "claude-code",
+    "codex"
+  ],
+  "license": "MIT",
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "skills": "1.5.23"
+  },
+  "devDependencies": {
+    "@changesets/cli": "3.0.1",
+    "@types/bun": "1.4.0",
+    "@types/node": "26.4.0",
+    "typescript": "7.0.2"
+  }
+}

package/skills/code-review/SKILL.md

@@ -0,0 +1,117 @@
+---
+name: code-review
+description: >-
+  Strict review of reuse, wrappers, and architecture. Reviewers collect, then
+  you apply fixes. Verdict is keep, shrink, or burn.
+license: MIT
+disable-model-invocation: true
+---
+
+# code-review
+
+Reviewers collect; **you apply fixes** — including obvious local defects, without asking. Done when production code is **smaller and less wrapped**, calling what already exists. Verdict: `keep` / `shrink` / `burn`.
+
+Bugs are incidental: whoever already read the files reports ones they saw. Do not launch a bot to hunt bugs.
+
+## Scope
+
+User-named paths / symbols / area win. Named fixed point (branch, tag, `main`, PR) → `git diff <fixed>...HEAD` (three-dot), still honor a path allowlist inside it.
+
+Otherwise: `git diff --no-color` and `git diff --cached --no-color`. No local diff → conversation files. Still nothing → `git show --stat --patch --no-color HEAD`.
+
+Do not broaden past that scope except to match existing patterns. Preserve unrelated user changes.
+
+**Allowlist** = those files. Every bot and every edit stays inside it (imports from an allowlisted file are ok).
+
+## 1. Triage
+
+Read the allowlisted diff. Write **one** launch line, then collect or skip to fix.
+
+| Launch line             | When                                                                                                |
+| ----------------------- | --------------------------------------------------------------------------------------------------- |
+| `parent-only`           | Default. The whole diff fits in one read.                                                           |
+| `one: <bot> — <reason>` | One row matches **and** the parent cannot finish the verdict from this read. Reason names that gap. |
+| `army: <bots>`          | User said full / strict / army. One wave of matching rows except bugbot.                            |
+| named bots              | User named them. Those names only. Includes `bugbot` if they said it.                               |
+
+**One-bot pick** (not army, not named): first match only.
+
+1. **reuse** — may have reinvented or wrapped something that already exists, **and** that existing API is not obvious from this read (outside the allowlist, or too many files to hunt). A new file on a small diff is not enough.
+2. **smell** — roughly ≥4 production files and wrappers / pass-throughs / muddy shape; reuse did not match.
+3. **security** — actual trust surface (auth, secrets, injection, user input, sandbox, network); reuse and smell did not match.
+
+No match → `parent-only`. A `.ts` file, “several files”, or “tests in the allowlist” is not a launch.
+
+| Bot      | Type              | Launch                                     |
+| -------- | ----------------- | ------------------------------------------ |
+| Reuse    | `reuse-review`    | Pick 1, army if that row matches, or named |
+| Smells   | `smell-review`    | Pick 2, army if that row matches, or named |
+| Security | `security-review` | Pick 3, army if that row matches, or named |
+| Bugbot   | `bugbot`          | User named `bugbot` only                   |
+
+Parent always does reuse / wrappers / verdict itself (nearest `AGENTS.md`; React / MobX / copy / tests → matching craft skill). A bot is extra eyes, not a replacement.
+
+## 2. Collect
+
+`parent-only` → skip this step.
+
+Launch **only** the bots on the launch line. Army: one parallel wave. Otherwise exactly one. They must not edit. `run_in_background: false`, no `resume`.
+
+**Brief** (every bot, plus the allowlist):
+
+```text
+Primary: reuse (existing APIs vs new wrappers), architecture, cleanliness.
+Verdict required: keep | shrink | burn — one line, why.
+Incidental: bugs you already saw while reading. Do not hunt bugs.
+```
+
+**Reuse / smells** — `description` exactly `Reuse Review` / `Smell Review`. They inspect git. Prompt: allowlist + brief.
+
+**Security / bugbot** — `description` exactly `Security Review` / `Bugbot`. They compute the diff. Prompt:
+
+```text
+Full Repository Path: <workspace root>
+Diff: uncommitted changes
+Custom Instructions: Review ONLY these files (ignore other uncommitted changes):
+- <allowlist path>
+
+Primary: reuse (existing APIs vs new wrappers), architecture, cleanliness.
+Verdict required: keep | shrink | burn — one line, why.
+Incidental: bugs you already saw while reading. Do not hunt bugs.
+```
+
+Empty diff on committed HEAD/branch work → retry once with `Diff: branch changes`. Bugbot still empty → retry once with `Diff: natural language` and a per-file Change Description. Wrong prompt: retry once, then stop that bot and say so.
+
+**Spec (you):** user-passed path, or issue/PR in commit messages (Linear, GitHub), or the plan in this conversation. Do not hunt a specs tree the user did not name. Missing/partial/scope-creep → findings for Fix. No source → skip.
+
+## 3. Fix
+
+Normalize: `severity | confidence | file:line | finding | fix`. Drop `confidence: low`. Dedup.
+
+Bar (even if a bot under-reported):
+
+1. **Reuse** — existing helper/component/API does the job → call it. No parallel wrapper. Duplicate implementations in the allowlist → keep the better one, retarget imports, delete the rest.
+2. **Wrappers** — pass-throughs, extra HTML/JSX, one-off barrels/helpers: inline or delete. Do not wrap a wrapper.
+3. **Shrink** — net-fewer prod lines (tests excluded) by deleting wrappers, dupes, and orphans — not by packing lines. Nested ternaries, dense one-liners, and mashed concerns are not shrink. Clarity wins when they conflict. Preserve behavior: only how, not what. A new file/helper is wrong unless it deletes more than it adds. If prod cannot shrink, say why.
+4. **Orphans** — unused imports, locals, helpers, exports, files, or commented-out blocks **this allowlisted change** made dead. Before delete: Grep real uses, including dynamic `import()` / string path lookups. Zero uses → delete. Package public export / cross-app API without monorepo Grep proof → defer. Pre-existing dead outside the allowlist → leave. Unsure → defer (no knip/depcheck/ts-prune sweeps).
+5. **Verdict** — local `burn`/`shrink` (inline, delete the new file, call the existing API) → do it. Whole-shape `burn` → say so and defer; do not nibble.
+6. **Tests in the allowlist** — keep real behavior tests; delete mock-theater / dupes / empty / greenwash. Do not invent tests for a prod-only change. Do not reshape prod to please a weak test.
+7. **Obvious** — a named local defect (broken emit, silent wrong path, leftover after a failed write) → fix this turn. Do not ask.
+
+Incidental bugs: fix if local; else defer. Do not hunt.
+
+Default-accept reuse/smell findings that serve the bar when the fix is local. Skip only with `needs product call` / `this is the contract` / `too large`.
+
+Tie-break: existing helper > inline > new helper. You fix — do not delegate. No edits outside the allowlist. No re-hunt. Small in-scope shrink → do it; larger → defer. Do not rerun collectors unless a fix likely created a new bug.
+
+## 4. Verify
+
+No pass / done / clean claim without a command you ran in **this** turn. Identify the command → run it full → read exit and failures → then claim. A previous run, “should pass”, or lint-for-compile is not evidence.
+
+Targeted: the project's test and lint for the allowlist (nearest `AGENTS.md`).
+
+Bug you fixed with no covering test → add a regression test or list `no test: …`.
+
+## Output
+
+Launch line; **verdict** (`keep` / `shrink` / `burn` + one line); what changed; prod smaller or why not; wrappers gone / APIs reused; orphans deleted or deferred (Grep gap / public API); incidental bugs fixed or deferred; tests judged or `no tests in allowlist`; spec gaps or `no spec`; deferred (`severity | file:line | reason`); tests/lint **this turn** (command + exit). No “fix or skip?” for local findings.

package/skills/grill/SKILL.md

@@ -0,0 +1,57 @@
+---
+name: grill
+description: Relentless interview to sharpen a plan or design until every branch is resolved.
+license: MIT
+---
+
+# Grill
+
+Interview until you reach a shared understanding. Map the work as a **design tree**: every decision branches into the decisions that hang off it.
+
+Use this for non-trivial product/architecture calls. Do not grill a one-line fix.
+
+Do **not** create `CONTEXT.md`, ADRs, or tickets as you go. Capture settled decisions in the reply; if a lasting convention belongs in an `AGENTS.md`, say so and wait for the user to ask you to write it.
+
+## Rounds
+
+Start by restating the task, the decisions already implied by the request, and
+any assumptions you would otherwise make. If there are no open questions, ask
+the user to confirm this reading.
+
+Work the tree in **rounds**. The **frontier** is every decision whose prerequisites are already settled. Ask the whole frontier in one round: number each question and give your recommended answer. Then wait.
+
+```
+❓ **Q1** - **<title>**: <body, including choices>
+
+➡️ <your recommended answer>
+
+---
+
+❓ **Q2** - **<title>**: <body>
+
+➡️ <your recommended answer>
+```
+
+Each round of answers reshapes the tree. Recompute the frontier. A question that depends on another still open in this round belongs to a _later_ round.
+
+## Facts vs decisions
+
+Finding _facts_ is your job. When a frontier question needs something from the repo, look it up (nearest `AGENTS.md`) — don't ask the user for anything you can read. A running lookup is an unsettled prerequisite: ask the rest of the frontier now.
+
+The _decisions_ are the user's. Put each to them and wait.
+
+Push back when a simpler approach fits. Name blockers instead of designing around them. Recommend the project's default (nearest `AGENTS.md`: surgical, inline, no new files) unless the user has a reason not to.
+
+## Done
+
+The frontier is empty, every branch has been visited, and the user has confirmed
+the final reading. Nothing is silently assumed. Do not implement before this
+confirmation.
+
+After confirmation:
+
+- In Plan mode, continue with the agent's native planning flow.
+- If the user asked for a plan in a normal mode, load the `plan` skill and write
+  it in the same chat.
+- Otherwise, let the user choose the next step. A small task may continue
+  directly to implementation.

package/skills/handoff/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: handoff
+description: >-
+  Save AGENTFLOW context to disk before continuing in a fresh chat.
+license: MIT
+disable-model-invocation: true
+---
+
+# Handoff
+
+Use this after an implementation PR when the next slice will continue in a
+fresh chat. Write a file the next chat can `@`-attach. The handoff + plan are
+the durable source of truth.
+
+Loop: the repo-root loop doc (`README.md` or `AGENTFLOW.md`).
+
+## Steps
+
+1. **Find the plan.** Path the user named, the last handoff, or the plan in this
+   thread.
+2. **This PR.** What shipped (paths, commit hash if any). Done-when met or not.
+3. **Bleed.** Work that belongs to a later plan row but landed, or should have.
+   Fold it into the plan: check off this PR, rewrite later rows. Do not leave
+   the next chat to discover leftover files.
+4. **Next PR.** Title + done-when from the updated plan. One row only.
+5. **Write** `.agentflow/<slug>/handoff.md` (create dirs). Reuse the same slug
+   for the feature so the next chat overwrites this file. Not OS temp.
+6. **Print** the path and what the fresh chat should attach.
+
+Redact secrets. Do not paste diffs or OpenSpec bodies — point at paths.
+
+If the user passed a focus, that is the next chat’s Next PR.
+
+## File
+
+```markdown
+# Handoff: <slug>
+
+> Next chat: read this file and the plan. Implement **only** Next PR.
+> Do not resurrect discarded approaches from Cursor summarize.
+
+## Plan
+
+path: <file the next chat can open>
+sync: updated | unchanged
+
+## This PR
+
+<title>
+done when: <criterion> — met | not met
+shipped: <paths, commit if any>
+
+## Bleed
+
+<what leaked into / out of later PRs, and how the plan changed>
+none
+
+## Next PR
+
+<title>
+done when: <criterion>
+suggested: tdd / code-review / craft skills for the next slice
+```

package/skills/plan/SKILL.md

@@ -0,0 +1,81 @@
+---
+name: plan
+description: >-
+  Use when the user asks to write or update an implementation plan split into
+  PR-sized slices after decisions are settled. Not the interview (grill) and
+  not the end-of-PR baton (handoff).
+license: MIT
+---
+
+# Plan
+
+Write **one** plan that another developer or agent can pick up. Do not implement. Do not write a handoff.
+
+If important decisions are still open, load `grill` first. Resume the plan after
+the user confirms the final reading. One-line or obvious scope can skip the
+plan.
+
+## Where
+
+- **Plan mode:** plan artifact / reply only. No `.agentflow/` files.
+- **Agent mode:** `.agentflow/<slug>/plan.md` (kebab-case from the feature; reuse the slug). Print the path.
+- Another machine or person: OpenSpec or a `*.md` on the branch.
+
+## Shape
+
+```markdown
+# <Feature>
+
+**Goal:** one sentence
+**Approach:** 2–3 sentences — the chosen reading
+**Reuse:** existing APIs this plan calls (`path`)
+
+## Files
+
+- `path` — what changes (or `create`)
+
+- [ ] PR 1 — <title>
+      done when: <observable>
+      verify: <command>
+
+- [ ] PR 2 — …
+```
+
+Each row is the smallest complete, independently shippable change with one
+coherent outcome and one verification story. Order rows from foundations to
+their consumers.
+
+## Slicing
+
+Common shapes:
+
+- **Full-stack feature:** behavior-preserving refactoring, then shared types and
+  backend, then frontend integration.
+- **Frontend feature:** reusable components, then shared runtime or wiring, then
+  user-facing interfaces.
+- **Small feature:** one complete vertical slice.
+
+Give a foundation its own row when it is independently useful. Keep
+feature-local components and wiring with their first consumer. Split distinct
+outcomes or architectural decisions that can ship separately.
+
+## Rules
+
+- Ground every row in files you read. Cite a path → it exists, or mark `create`.
+- One approach. No menu, no TBD, no “handle edge cases”, no “similar to PR n”.
+- File map before rows. Reuse before create.
+- Tight: settled model + rows. Cut prose, keep paths.
+- `done when` is observable. `verify` is the command the implementer runs.
+
+## Self-check
+
+1. Every settled decision has a row or is named out of scope.
+2. Every path exists or is marked `create`.
+3. No placeholders.
+4. Another developer or agent can open the file and ship PR 1 without this conversation.
+5. Every row leaves the repository working and does not need the next row to
+   justify its code.
+
+## Output
+
+Print the path. The implementer starts with the first unchecked row, in this context or a new one.

package/skills/research/SKILL.md

@@ -0,0 +1,133 @@
+---
+name: research
+description: >-
+  Research a codebase, feature, technology, or external landscape and save a
+  reusable map under .agentflow/<feature>/research/. Use when later work should
+  not repeat the same investigation. Not for a one-file lookup.
+license: MIT
+---
+
+# Research
+
+Learn how an area works and leave a map that another chat can use without
+repeating the investigation. Research only. Do not plan or implement the change.
+
+The user can ask for research in a regular prompt. Use this skill when the
+findings should survive context compaction or move to another chat.
+
+## Output
+
+Write to:
+
+```text
+.agentflow/<slug>/research/
+├── index.md
+└── <topic>.md
+```
+
+Use a short kebab-case slug for the feature or question. Reuse the directory
+when continuing the same research.
+
+`index.md` is a short map, not the full report. It contains:
+
+- the question and scope
+- a short summary
+- links to every topic page
+- the important files, modules, or sources
+- open questions that research could not answer
+
+Split detailed findings by domain, module, flow, or independent question. Each
+topic page owns one coherent area and must make sense when attached to a chat on
+its own. If a later chat could use one part without the others, put that part in
+its own file.
+
+Keep a narrow investigation in `index.md` instead of creating empty pages. For
+larger research, keep details out of `index.md` and link to the topic pages.
+
+Write the notes in the user's language.
+
+## Research the code
+
+When the question is about an existing project:
+
+1. Read the nearest `AGENTS.md` and the repository's exploration rules.
+2. Try the current behavior when possible.
+3. Find the entry points, public interfaces, modules, and data flow.
+4. Follow the important path end to end. Verify call graph guesses with text
+   search.
+5. Record exact file paths and symbol names with one line explaining each role.
+6. Capture constraints, gotchas, and existing APIs that later work should reuse.
+
+Do not dump search results or source code. Explain how the pieces connect.
+Separate what you observed from what you inferred.
+
+## Research a technology
+
+When the question is about a library, platform, or approach:
+
+1. Check the version and setup used by the project.
+2. Search the web and read current primary documentation and official sources.
+3. Find the APIs and constraints relevant to the question.
+4. Connect the findings back to the project's files and current architecture.
+5. Record dated source links.
+
+The result should explain what applies here, not summarize the entire
+technology.
+
+## Research a landscape
+
+When comparing tools, competitors, or options:
+
+1. State the question and the filter used to keep or reject candidates.
+2. Record what the project already has.
+3. Open current primary sources and date the snapshot.
+4. Explain why each kept option fits the question.
+5. Name rejected options and the reason.
+6. End with ranked next moves when the user asked what to adopt or build.
+
+A catalog dump is not research. Every item must help answer the question.
+
+## Suggested page shape
+
+```markdown
+# <Topic>
+
+## Summary
+
+<What a later chat needs to know>
+
+## How it works
+
+<Behavior or flow>
+
+## Relevant files and modules
+
+- `path/to/file.ts` — role
+
+## Constraints
+
+- <constraint or gotcha>
+
+## Sources
+
+- <dated primary source>
+
+## Open questions
+
+- <unanswered question>
+```
+
+Use only the sections that fit the topic.
+
+## Done
+
+Research is complete when a fresh chat can answer these questions from the
+notes:
+
+1. How does this area work?
+2. Where are the important files, modules, or sources?
+3. What constraints will affect the work?
+4. What is still unknown?
+
+Print the path to `index.md` and a short takeaway. Do not paste the full notes
+into the reply.

package/skills/tdd/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: tdd
+description: >-
+  Use when the user wants to build features or fix bugs test-first,
+  mentions "red-green-refactor", or wants integration tests.
+license: MIT
+---
+
+# Test-Driven Development
+
+TDD is the red → green loop. This skill is the reference that makes that loop produce tests worth keeping: what a good test is, where tests go, the anti-patterns, and the rules of the loop. Every section applies on every cycle — consult them before and during the loop, not after.
+
+When exploring the codebase, read the nearest `AGENTS.md` so test names and interface vocabulary match the area's language. Explore per root `AGENTS.md`.
+
+## What a good test is
+
+Tests verify behavior through public interfaces, not implementation details. Code can change entirely; tests shouldn't. A good test reads like a specification — "user can checkout with valid cart" tells you exactly what capability exists — and survives refactors because it doesn't care about internal structure.
+
+See [tests.md](tests.md) for examples and [mocking.md](mocking.md) for mocking guidelines.
+
+## Seams — where tests go
+
+A **seam** is the public boundary you test at: the interface where you observe behavior without reaching inside. Tests live at seams, never against internals.
+
+**Test only at pre-agreed seams.** Before writing any test, write down the seams under test and confirm them with the user. No test is written at an unconfirmed seam. You can't test everything — agreeing the seams up front is how testing effort lands on the critical paths and complex logic instead of every edge case.
+
+Ask: "What's the public interface, and which seams should we test?"
+
+Root `AGENTS.md` wins: do not add a file, port, or wrapper so a test can reach inside. One real adapter is not a seam — two (production + test, or two backends) is. Don't invent `IFooService` for an in-process collaborator you own.
+
+## Anti-patterns
+
+- **Implementation-coupled** — mocks internal collaborators, tests private methods, or verifies through a side channel (querying the database instead of using the interface). The tell: the test breaks when you refactor but behavior hasn't changed.
+- **Tautological** — the assertion recomputes the expected value the way the code does (`expect(add(a, b)).toBe(a + b)`, a snapshot derived by hand the same way, a constant asserted equal to itself), so it passes by construction and can never disagree with the code. Expected values must come from an independent source of truth — a known-good literal, a worked example, the spec.
+- **Horizontal slicing** — writing all tests first, then all implementation. Bulk tests verify _imagined_ behavior: you test the _shape_ of things rather than user-facing behavior, the tests go insensitive to real changes, and you commit to test structure before understanding the implementation. Work in **vertical slices** instead — one test → one implementation → repeat, each test a **tracer bullet** that responds to what the last cycle taught you.
+
+## Rules of the loop
+
+- **Red before green.** Write the failing test first, then only enough code to pass it. Don't anticipate future tests or add speculative features.
+- **One slice at a time.** One seam, one test, one minimal implementation per cycle.
+- **Watch the color.** Red is not “wrote a test”. Run it. Confirm it fails because the behavior is missing — not a typo, import error, or existing pass. Passes immediately → you tested existing behavior; fix the test. Errors → fix the harness until it fails correctly, then implement. Green: run the same command; claim pass only from that output.
+- **Name the break.** Before the test body, name the production change that should make it fail. Cannot name one → wrong seam.
+- **Refactoring is not part of the loop.** It belongs to the review stage (see the `code-review` skill), not the red → green implementation cycle.

package/skills/tdd/mocking.md

@@ -0,0 +1,50 @@
+# When to Mock
+
+Mock at **system boundaries** only:
+
+- External APIs (payment, email, third-party)
+- Time / randomness
+- Databases and filesystems — sometimes; prefer a real test DB / tmp dir when cheap
+
+Don't mock:
+
+- Your own classes / modules
+- Internal collaborators
+- Anything you control
+
+Use the project's test runner (nearest `AGENTS.md`). Vitest: `vi.fn`, `vi.mock`.
+
+## Designing for mockability
+
+**1. Pass the boundary in** — only when a second adapter is real (production + test, or two backends).
+
+```typescript
+// Easy to mock
+function processPayment(order: Order, paymentClient: PaymentClient) {
+  return paymentClient.charge(order.total);
+}
+
+// Hard to mock
+function processPayment(order: Order) {
+  const client = new StripeClient(process.env.STRIPE_KEY);
+  return client.charge(order.total);
+}
+```
+
+Don't invent `IFoo` for an in-process collaborator you own just so a test can mock it.
+
+**2. Prefer SDK-style interfaces over a generic fetcher**
+
+```typescript
+// GOOD: each function is independently mockable
+const api = {
+  getUser: (id: string) => fetch(`/users/${id}`),
+  createOrder: (data: OrderInput) =>
+    fetch("/orders", { method: "POST", body: JSON.stringify(data) }),
+};
+
+// BAD: mock needs conditional logic
+const api = {
+  fetch: (endpoint: string, options?: RequestInit) => fetch(endpoint, options),
+};
+```

package/skills/tdd/tests.md

@@ -0,0 +1,74 @@
+# Good and Bad Tests
+
+## Good tests
+
+Test through real interfaces, not mocks of internal parts.
+
+```typescript
+// GOOD: observable behavior
+it("should confirm checkout for a valid cart", async () => {
+  const cart = createCart();
+  cart.add(product);
+  const result = await checkout(cart, paymentMethod);
+  expect(result.status).toBe("confirmed");
+});
+```
+
+- Behavior callers care about
+- Public API only
+- Survives internal refactors
+- Describes WHAT, not HOW
+- One logical assertion per test
+
+## Bad tests
+
+**Implementation-detail** — coupled to internal structure.
+
+```typescript
+// BAD
+it("should call paymentService.process", async () => {
+  const process = vi.fn();
+  await checkout(cart, { process });
+  expect(process).toHaveBeenCalledWith(cart.total);
+});
+```
+
+Red flags: mocking internal collaborators, private methods, call counts/order, test name describes HOW, verifying through a side channel instead of the interface.
+
+```typescript
+// BAD: bypasses interface
+it("should save the user to the database", async () => {
+  await createUser({ name: "Alice" });
+  const row = await db.query("SELECT * FROM users WHERE name = ?", ["Alice"]);
+  expect(row).toBeDefined();
+});
+
+// GOOD: verifies through interface
+it("should make a created user retrievable", async () => {
+  const user = await createUser({ name: "Alice" });
+  const retrieved = await getUser(user.id);
+  expect(retrieved.name).toBe("Alice");
+});
+```
+
+**Tautological** — expected value restates the implementation.
+
+```typescript
+// BAD
+it("should sum line items", () => {
+  const items = [{ price: 10 }, { price: 5 }];
+  const expected = items.reduce((sum, i) => sum + i.price, 0);
+  expect(calculateTotal(items)).toBe(expected);
+});
+
+// GOOD: independent literal
+it("should sum line items", () => {
+  expect(calculateTotal([{ price: 10 }, { price: 5 }])).toBe(15);
+});
+```
+
+**Low-value mapping tests** — asserting `.map` / array shape with no behavior. Skip or drop them rather than warping production code for reachability (root `AGENTS.md`).
+
+## Mutation check
+
+A realistic production mutation (wrong branch, missing side effect, empty return) should fail at least one test. Nothing fails → tautological or untested.