@reforma/agentflow 0.0.1 → 1.1.0

package/AGENTFLOW.md

@@ -0,0 +1,85 @@
+# AgentFlow
+
+Use this loop for changes larger than an obvious quick fix:
+
+```text
+Research → Grill → Plan → PR → Review → Commit
+                          ↑                  │
+                          └──── Next PR ─────┘
+```
+
+Research is optional. Small tasks can skip the plan. Write a handoff only when
+the work moves to a fresh context.
+
+## 1. Learn how it works
+
+Explore the existing feature, code, or technology before proposing a change.
+Use `/research` when the findings must survive the current chat. Save reusable
+findings under `.agentflow/<feature>/research/`.
+
+Skip this step when the area and required change are already clear.
+
+## 2. Sharpen the task
+
+Run `/grill`. List assumptions, unresolved decisions, what is in and out of the
+task, and how the result will be checked.
+
+Continue until no open decision can change how the work will be done. Then
+proceed directly for a small task or load `/plan` for larger work.
+
+## 3. Plan PR-sized slices
+
+Save the plan to `.agentflow/<feature>/plan.md`.
+
+Each row is the smallest complete, independently shippable change that does one
+useful thing and has one clear way to test it. Put lower-level pieces before the
+code that uses them.
+
+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.
+
+Keep the plan current as implementation changes. Record scope changes and new
+decisions in the plan instead of letting the active PR grow silently.
+
+## 4. Implement one PR
+
+Implement the first unchecked row and nothing beyond it. Without a plan, keep
+the change small enough to review as one useful result.
+
+Load the relevant project skills. Use `/tdd` when the work should proceed
+test-first.
+
+Verify the slice using the checks named in the plan. Check its row only after
+the implementation and verification are complete, then update later rows to
+match what remains.
+
+## 5. Review
+
+Run `/code-review` against the completed slice. Fix local findings and reduce
+the change when the review verdict requires it.
+
+Read the final diff yourself after the agent review.
+
+## 6. Commit
+
+Commit the verified slice using the project's normal workflow. Then return to
+the first unchecked row.
+
+## 7. Refresh context when needed
+
+Continue in the current chat while its context remains useful. When it becomes
+noisy, summarize it or start a fresh chat.
+
+Run `/handoff` before moving unfinished work to a fresh context. Save the result
+to `.agentflow/<feature>/handoff.md` with what shipped, what changed, and which
+PR comes next. Bring the plan and handoff into the new context, then resume from
+the first unchecked row.

package/README.md

@@ -44,7 +44,7 @@ Reusable agent skills are published from `skills/`:
 
 ---
 
-## The Loop
+## 🔄 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.
 
@@ -58,7 +58,12 @@ Research helps when the agent does not know the area, and most larger tasks also
 
 Repeat steps 4–7 until every PR in the plan is complete.
 
-### Step 1. Learn how it works (optional)
+AgentFlow keeps research, plans, handoffs, and local setup state under
+`.agentflow/`. Version control is your choice: ignore the directory for a
+private workflow, or commit it to share the work with your team like an
+OpenSpec workspace.
+
+### 🔍 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.
@@ -73,7 +78,7 @@ 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
+### 🔥 Step 2. Sharpen the idea with Grill
 
 Grill is the core of AgentFlow and the one step used for the most tasks.
 
@@ -84,10 +89,9 @@ 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.
+Now the agent does not have to fill in the gaps while coding.
 
-### Step 3. Plan and slice the work into PRs
+### 🗂️ 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`
@@ -98,14 +102,14 @@ 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.
+smallest complete change that does one useful thing and has a clear way to check
+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.
+Larger work usually starts with lower-level pieces and moves to the code that
+uses them. 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
@@ -113,10 +117,7 @@ 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
+### 🛠️ 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
@@ -126,34 +127,28 @@ 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.
+Before review, update `plan.md`: check the completed PR only after its checks
+pass, then apply any scope changes to later rows.
 
-### Step 5. Agent review
+### 🤖 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
+### ✅ 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
+### 🔄 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.
+Attach the plan and handoff to a fresh chat when they exist, then return to step 4.
 
-## Install
+## 📦 Install
 
 Install the complete workflow in a project:
 
@@ -161,9 +156,22 @@ Install the complete workflow in a project:
 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.
+AgentFlow first asks which parts to install: the skills, the concise
+`AGENTFLOW.md` loop, and a one-line pointer in `AGENTS.md`. When you choose the
+skills, the `skills` CLI handles the skill picker, target agents, project or
+global scope, and installation method.
+
+Use its standard AgentFlow flags when the destination is already known:
+
+```bash
+npx @reforma/agentflow init --global --agent cursor
+```
+
+For automation, accept every default without prompts:
+
+```bash
+npx @reforma/agentflow init --yes
+```
 
 Install only one skill without the workflow:
 
@@ -177,6 +185,10 @@ Update the complete workflow:
 npx @reforma/agentflow@latest update
 ```
 
+Updates are non-interactive after setup and refresh only the AgentFlow parts
+selected during initialization. In a project without AgentFlow, `update`
+starts the same setup as `init`.
+
 Or update one independently installed skill:
 
 ```bash
@@ -185,24 +197,7 @@ 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
+## ⚖️ 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
@@ -221,11 +216,11 @@ 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.
+fix. On larger changes, AgentFlow keeps decisions out of chat history, limits
+scope to one reviewable slice, and gives the next session enough context to
+continue.
 
-## Releasing
+## 🚀 Releasing
 
 Add a changeset with every publishable change:
 
@@ -238,9 +233,6 @@ 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
@@ -249,4 +241,12 @@ bun run test
 bun publish --dry-run
 ```
 
+## 📖 License
+
 AgentFlow is available under the [MIT License](LICENSE).
+
+## 👤 Maintainer
+
+<img src="https://github.com/kachurun.png" width="100" height="100" alt="@kachurun's avatar" style="border-radius: 50%;">
+
+Maintained with ❤️ by [@kachurun](https://github.com/kachurun)

package/bin/agentflow.js

@@ -1,20 +1,23 @@
 #!/usr/bin/env node
 
 // src/cli.ts
+import { cancel, isCancel, multiselect } from "@clack/prompts";
 import { existsSync as existsSync2, readFileSync as readFileSync3 } from "node:fs";
-import { dirname as dirname2, resolve as resolve3 } from "node:path";
+import { dirname as dirname3, resolve as resolve3 } from "node:path";
 import { fileURLToPath } from "node:url";
 
 // src/project.ts
 import {
   existsSync,
+  mkdirSync,
   readFileSync,
   renameSync,
   writeFileSync
 } from "node:fs";
-import { resolve } from "node:path";
+import { dirname, 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.";
+var AGENTS_POINTER = "Check @AGENTFLOW.md to follow the development workflow.";
+var SETUP_COMPONENTS = ["skills", "workflow", "agents"];
 function generatedWorkflow(workflow) {
   return `${GENERATED_MARKER}
 
@@ -25,21 +28,37 @@ function isGeneratedWorkflow(path) {
   return existsSync(path) && readFileSync(path, "utf8").startsWith(GENERATED_MARKER);
 }
 function writeAtomically(path, contents) {
+  mkdirSync(dirname(path), { recursive: true });
   const temporaryPath = `${path}.agentflow-tmp`;
   writeFileSync(temporaryPath, contents);
   renameSync(temporaryPath, path);
 }
-function ensureIgnored(cwd) {
-  const path = resolve(cwd, ".gitignore");
+function ensureAgentsPointer(cwd) {
+  const path = resolve(cwd, "AGENTS.md");
   const current = existsSync(path) ? readFileSync(path, "utf8") : "";
-  const alreadyIgnored = current.split(/\r?\n/).some((line) => /^\/?\.agentflow\/?$/.test(line.trim()));
-  if (alreadyIgnored) {
+  if (current.split(/\r?\n/).some((line) => line.trim() === AGENTS_POINTER)) {
     return;
   }
   const separator = current.length === 0 || current.endsWith(`
 `) ? "" : `
 `;
-  writeAtomically(path, `${current}${separator}.agentflow/
+  writeAtomically(path, `${current}${separator}${AGENTS_POINTER}
+`);
+}
+function readSetupConfig(cwd) {
+  const path = resolve(cwd, ".agentflow/config.json");
+  if (!existsSync(path)) {
+    return null;
+  }
+  const config = JSON.parse(readFileSync(path, "utf8"));
+  if (config.version !== 1 || !Array.isArray(config.components) || config.components.some((component) => !SETUP_COMPONENTS.includes(component))) {
+    throw new Error(".agentflow/config.json is not a valid AgentFlow config.");
+  }
+  return config;
+}
+function writeSetupConfig(cwd, components) {
+  const config = { version: 1, components };
+  writeAtomically(resolve(cwd, ".agentflow/config.json"), `${JSON.stringify(config, null, 2)}
 `);
 }
 
@@ -47,7 +66,7 @@ function ensureIgnored(cwd) {
 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";
+import { dirname as dirname2, resolve as resolve2 } from "node:path";
 var AGENTFLOW_SKILLS = [
   "research",
   "grill",
@@ -65,7 +84,7 @@ var runSkills = (args) => {
   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" });
+  const result = spawnSync(process.execPath, [resolve2(dirname2(packagePath), relativeBin), ...args], { stdio: "inherit" });
   if (result.error) {
     throw result.error;
   }
@@ -73,7 +92,7 @@ var runSkills = (args) => {
 };
 
 // src/cli.ts
-var packageRoot = resolve3(dirname2(fileURLToPath(import.meta.url)), "..");
+var packageRoot = resolve3(dirname3(fileURLToPath(import.meta.url)), "..");
 var packageJson = JSON.parse(readFileSync3(resolve3(packageRoot, "package.json"), "utf8"));
 function parseOptions(args, command) {
   const forwarded = [];
@@ -119,18 +138,36 @@ Usage:
   agentflow --version
 
 Commands:
-  init      Install all AgentFlow skills and write AGENTFLOW.md
-  update    Update installed AgentFlow skills and refresh AGENTFLOW.md
+  init      Choose and install AgentFlow components
+  update    Update AgentFlow, installing it first when needed
 
-AgentFlow prints the AGENTS.md snippet for you to add manually.
+The skills CLI handles skill, agent, scope, and installation choices.
 `;
 }
-function runCli(args, {
+async function promptSetup() {
+  const selected = await multiselect({
+    message: "What do you want to install?",
+    options: [
+      { value: "skills", label: "AgentFlow skills" },
+      { value: "workflow", label: "AGENTFLOW.md" },
+      { value: "agents", label: "AGENTS.md pointer" }
+    ],
+    initialValues: [...SETUP_COMPONENTS],
+    required: true
+  });
+  if (isCancel(selected)) {
+    cancel("AgentFlow setup cancelled.");
+    return null;
+  }
+  return selected;
+}
+async function runCli(args, {
   cwd = process.cwd(),
   stdout = process.stdout,
   stderr = process.stderr,
+  promptSetup: selectSetup = promptSetup,
   runSkills: executeSkills = runSkills,
-  workflow = readFileSync3(resolve3(packageRoot, "README.md"), "utf8")
+  workflow = readFileSync3(resolve3(packageRoot, "AGENTFLOW.md"), "utf8")
 } = {}) {
   const [command, ...optionArgs] = args;
   if (!command || command === "--help" || command === "-h") {
@@ -151,27 +188,42 @@ ${help()}`);
   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.");
+    const config = readSetupConfig(cwd);
+    const legacyInstall = !config && isGeneratedWorkflow(workflowPath);
+    const installing = command === "init" || !config && !legacyInstall;
+    const assumeDefaults = forwarded.includes("--yes") || forwarded.includes("-y");
+    const components = installing ? assumeDefaults ? [...SETUP_COMPONENTS] : await selectSetup() : config?.components ?? ["skills", "workflow"];
+    if (!components) {
+      return 0;
     }
-    if (command === "update" && !existsSync2(workflowPath)) {
-      throw new Error("AgentFlow is not initialized here. Run `agentflow init`.");
+    if (components.includes("workflow") && existsSync2(workflowPath) && !isGeneratedWorkflow(workflowPath)) {
+      throw new Error("AGENTFLOW.md is not managed by AgentFlow CLI. Move it or merge it manually before continuing.");
     }
-    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}.
+    if (components.includes("skills")) {
+      const installOptions = forwarded.filter((option) => option !== "--project" && option !== "-p");
+      const skillsArgs = installing ? [
+        "add",
+        SKILLS_SOURCE,
+        ...assumeDefaults ? ["--skill", "*"] : [],
+        ...installOptions
+      ] : ["update", ...AGENTFLOW_SKILLS, ...forwarded];
+      const status = executeSkills(skillsArgs);
+      if (status !== 0) {
+        const operation = installing ? "install" : "update";
+        stderr.write(`Agent skills ${operation} failed with exit code ${status}.
 `);
-      return status;
+        return status;
+      }
+    }
+    if (components.includes("workflow")) {
+      writeAtomically(workflowPath, generatedWorkflow(workflow));
     }
-    writeAtomically(workflowPath, generatedWorkflow(workflow));
-    ensureIgnored(cwd);
-    if (command === "init") {
+    if (components.includes("agents")) {
+      ensureAgentsPointer(cwd);
+    }
+    writeSetupConfig(cwd, components);
+    if (installing) {
       stdout.write(`AgentFlow initialized.
-
-Add this line to AGENTS.md:
-
-${AGENTS_SNIPPET}
 `);
     } else {
       stdout.write(`AgentFlow updated.
@@ -186,4 +238,4 @@ ${AGENTS_SNIPPET}
 }
 
 // src/bin.ts
-process.exitCode = runCli(process.argv.slice(2));
+process.exitCode = await runCli(process.argv.slice(2));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reforma/agentflow",
-  "version": "0.0.1",
+  "version": "1.1.0",
   "description": "An opinionated workflow for shipping production-ready changes with coding agents.",
   "author": "Reforma, Inc. <dev@reforma.ai>",
   "type": "module",
@@ -10,11 +10,13 @@
   "files": [
     "bin",
     "skills",
+    "AGENTFLOW.md",
     "README.md",
     "LICENSE"
   ],
   "scripts": {
-    "build": "bun build src/bin.ts --target=node --outfile=bin/agentflow.js --external skills",
+    "prepare": "node -e \"if (process.env.CI === 'true' || process.env.SKIP_GIT_HOOKS === '1') process.exit(0); require('child_process').execSync('bunx simple-git-hooks', {stdio:'inherit'})\"",
+    "build": "bun build src/bin.ts --target=node --outfile=bin/agentflow.js --external skills --external @clack/prompts",
     "typecheck": "tsc --noEmit",
     "changeset": "bunx @changesets/cli",
     "version-packages": "bunx @changesets/cli version",
@@ -23,6 +25,9 @@
     "validate:skills": "gh skill publish --dry-run",
     "prepublishOnly": "bun run typecheck && bun run test && bun run build"
   },
+  "simple-git-hooks": {
+    "commit-msg": "bunx --no-install commitlint --edit \"$1\""
+  },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/reforma-dev/agentflow.git"
@@ -44,12 +49,69 @@
     "access": "public"
   },
   "dependencies": {
+    "@clack/prompts": "1.7.0",
     "skills": "1.5.23"
   },
   "devDependencies": {
     "@changesets/cli": "3.0.1",
+    "@commitlint/cli": "21.2.2",
+    "@commitlint/config-conventional": "21.2.2",
     "@types/bun": "1.4.0",
     "@types/node": "26.4.0",
+    "simple-git-hooks": "2.14.0",
     "typescript": "7.0.2"
+  },
+  "commitlint": {
+    "extends": [
+      "@commitlint/config-conventional"
+    ],
+    "rules": {
+      "type-enum": [
+        2,
+        "always",
+        [
+          "feat",
+          "fix",
+          "chore",
+          "refactor",
+          "docs",
+          "test",
+          "ci",
+          "perf",
+          "revert"
+        ]
+      ],
+      "type-case": [
+        2,
+        "always",
+        "lower-case"
+      ],
+      "type-empty": [
+        2,
+        "never"
+      ],
+      "subject-empty": [
+        2,
+        "never"
+      ],
+      "subject-min-length": [
+        1,
+        "always",
+        4
+      ],
+      "body-max-line-length": [
+        1,
+        "always",
+        250
+      ],
+      "subject-case": [
+        2,
+        "never",
+        [
+          "pascal-case",
+          "upper-case"
+        ]
+      ]
+    }
   }
 }

package/skills/plan/SKILL.md

@@ -26,6 +26,10 @@ plan.
 ```markdown
 # <Feature>
 
+> Keep this plan current during implementation.
+> Check a PR only after its done-when and verification pass.
+> Record scope changes before leaving the PR.
+
 **Goal:** one sentence
 **Approach:** 2–3 sentences — the chosen reading
 **Reuse:** existing APIs this plan calls (`path`)