@ksoftm/create-arc 1.0.5

package/LICENSE

@@ -0,0 +1,23 @@
+MIT License
+
+Copyright (c) 2026 Ksoftm (Kajalan)
+
+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.
+
+ARC is inspired by DOX (https://github.com/agent0ai/dox) by agent0ai, MIT licensed.

package/README.md

@@ -0,0 +1,56 @@
+# @ksoftm/create-arc
+
+Scaffold and drive the **ARC framework** (Align → Refine → Construct) — plan-driven development for AI agents, in pure Markdown. Zero dependencies, any language, any agent.
+
+```bash
+npx @ksoftm/create-arc init                          # scaffold ARC into the current project
+npx @ksoftm/create-arc new "Add per-key rate limit"  # open and register a new unit of work
+npx @ksoftm/create-arc status                         # every arc at a glance
+npx @ksoftm/create-arc doctor                         # verify the registry is consistent
+```
+
+## What ARC is
+
+Every unit of development is an **arc**: one Markdown file under `.arc/` that holds its whole story — the user's raw instructions (verbatim, append-only), the current plan, a refinement log, a task list, a worklog, and a status. The agent plans before it builds, refines the plan when the ask changes, and logs every edit — so any later session resumes from the arc, not the chat history. Full concept and protocol: **https://github.com/KsoftmHub/arc-framework-v1**.
+
+## Install
+
+Run on demand with `npx @ksoftm/create-arc …` (no install), or add it to a project:
+
+```bash
+npm i -D @ksoftm/create-arc
+```
+
+Requires Node ≥ 18.
+
+## Commands
+
+| Command | What it does |
+|---|---|
+| `init [dir]` | Scaffold `ARC.md` + `.arc/` (index, template, standing maintenance arc, `notes/`, `archive/`). Idempotent — never overwrites. |
+| `new "Title" [--dir=.] [--tags=a,b]` | Take the next sequential ID, create the arc from the template, and register its row in the index. |
+| `status [dir] [--json]` | Print a table (or JSON) of every arc: ID, status, plan version, task progress, and which to resume. |
+| `doctor [dir]` | Consistency checks — index ↔ file bijection, ID/`next_id` sanity, valid statuses. Exits non-zero on problems (CI-friendly). |
+
+Common options: `--owner NAME` (defaults to `git config user.name`); `--tags a,b` on `new`; `--json` on `status`; `--version`, `--help`.
+
+## What `init` produces
+
+```
+your-project/
+├── ARC.md                         the protocol your AI agent reads
+└── .arc/
+    ├── INDEX.md                   registry of all arcs + next_id counter
+    ├── _TEMPLATE.md               the blank arc shape
+    ├── ARC-0000-maintenance.md    standing lane for trivial fixes
+    ├── notes/                     long research, linked from arcs
+    └── archive/                   closed arcs (history is kept, never deleted)
+```
+
+## Then what?
+
+Give your AI agent development instructions as usual. With `ARC.md` in the repo — and the companion [ARC skill](https://github.com/KsoftmHub/arc-framework-v1) if you use Claude — the agent files each instruction into an arc verbatim, plans it, refines when you change your mind, builds, and logs progress.
+
+## License
+
+MIT © Ksoftm (Kajalan)

package/bin/cli.js

@@ -0,0 +1,326 @@
+#!/usr/bin/env node
+/**
+ * create-arc — scaffold and manage the ARC plan-driven development framework.
+ *
+ *   npx @ksoftm/create-arc init [dir] [--owner=NAME]
+ *   npx @ksoftm/create-arc new "Short imperative title" [--dir=.] [--tags=a,b] [--owner=NAME]
+ *   npx @ksoftm/create-arc status [dir] [--json]
+ *   npx @ksoftm/create-arc doctor [dir]
+ *
+ * Zero dependencies. Node >= 18. ARC protocol: see ARC.md after init.
+ */
+
+import { execFileSync } from "node:child_process";
+import {
+  existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync,
+} from "node:fs";
+import { basename, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const TEMPLATES = fileURLToPath(new URL("../templates/", import.meta.url));
+
+// Read a UTF-8 file and normalize line endings to LF, so every downstream
+// regex (frontmatter, fields, task markers) behaves identically regardless of
+// whether the file was checked out with CRLF (Windows/Git autocrlf) or LF.
+const readText = (p) => readFileSync(p, "utf8").replace(/\r\n/g, "\n").replace(/\r/g, "\n");
+
+const PKG = JSON.parse(readText(new URL("../package.json", import.meta.url)));
+
+const PLACEMENT = {
+  "ARC.md": "ARC.md",
+  "INDEX.md": ".arc/INDEX.md",
+  "_TEMPLATE.md": ".arc/_TEMPLATE.md",
+  "ARC-0000-maintenance.md": ".arc/ARC-0000-maintenance.md",
+};
+const DIRS = [".arc/notes", ".arc/archive"];
+const VALID_STATUSES = new Set([
+  "draft", "planned", "refining", "in-progress", "blocked", "review", "done", "cancelled",
+]);
+
+/* ----------------------------- small helpers ----------------------------- */
+
+const today = () => new Date().toISOString().slice(0, 10);
+
+const slugify = (title, max = 40) =>
+  (title.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/-{2,}/g, "-").replace(/^-|-$/g, "")
+    .slice(0, max).replace(/-$/, "")) || "arc";
+
+function detectOwner(dir) {
+  try {
+    const name = execFileSync("git", ["-C", dir, "config", "user.name"], {
+      encoding: "utf8", timeout: 5000, stdio: ["ignore", "pipe", "ignore"],
+    }).trim();
+    if (name) return name;
+  } catch { /* not a git repo / git absent */ }
+  return "user";
+}
+
+const BOOLEAN_FLAGS = new Set(["json", "help", "version"]);
+
+function parseArgv(argv) {
+  const flags = {}; const pos = [];
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a.startsWith("--")) {
+      const eq = a.indexOf("=");
+      if (eq > -1) { flags[a.slice(2, eq)] = a.slice(eq + 1); continue; }
+      const key = a.slice(2);
+      const next = argv[i + 1];
+      if (!BOOLEAN_FLAGS.has(key) && next !== undefined && !next.startsWith("--")) {
+        flags[key] = next; i++;            // --owner NAME form
+      } else flags[key] = true;            // --json / trailing flag form
+    } else pos.push(a);
+  }
+  return { pos, flags };
+}
+
+const frontmatter = (text) => text.match(/^---\n([\s\S]*?)\n---/)?.[1] ?? "";
+
+function field(front, key, fallback = "?") {
+  const m = front.match(new RegExp(`^${key}:\\s*(.*?)\\s*(?:#.*)?$`, "m"));
+  const v = m?.[1]?.trim();
+  return v || fallback;
+}
+
+const setField = (block, key, value) =>
+  block.replace(new RegExp(`^${key}:.*$`, "m"), `${key}: ${value}`);
+
+function listArcFiles(arcDir) {
+  const ls = (d) => existsSync(d)
+    ? readdirSync(d).filter((f) => /^ARC-\d+.*\.md$/.test(f)).sort().map((f) => join(d, f))
+    : [];
+  return { active: ls(arcDir), archived: ls(join(arcDir, "archive")) };
+}
+
+/* -------------------------------- commands ------------------------------- */
+
+function cmdInit(target, flags) {
+  const dir = resolve(target ?? ".");
+  if (!existsSync(dir)) return fail(`target does not exist: ${dir}`);
+  const owner = flags.owner || detectOwner(dir);
+  const date = today();
+  let created = 0, skipped = 0;
+
+  for (const d of DIRS) {
+    mkdirSync(join(dir, d), { recursive: true });
+    const keep = join(dir, d, ".gitkeep");
+    if (!existsSync(keep)) writeFileSync(keep, "");
+  }
+  for (const [src, rel] of Object.entries(PLACEMENT)) {
+    const dest = join(dir, rel);
+    if (existsSync(dest)) { console.log(`  skip  ${rel} (exists)`); skipped++; continue; }
+    mkdirSync(join(dest, ".."), { recursive: true });
+    const text = readText(join(TEMPLATES, src))
+      .replaceAll("{{DATE}}", date).replaceAll("{{OWNER}}", owner);
+    writeFileSync(dest, text);
+    console.log(`  ok    ${rel}`);
+    created++;
+  }
+  console.log(`\nARC initialized at ${dir}  (created ${created}, skipped ${skipped}, owner: ${owner})`);
+  if (created) console.log("Next: tell your agent to read ARC.md, or run `create-arc new \"Title\"`.");
+  return 0;
+}
+
+function cmdNew(title, flags) {
+  if (!title) return fail('usage: create-arc new "Short imperative title" [--dir=.] [--tags=a,b]');
+  const dir = resolve(flags.dir ?? ".");
+  const arcDir = join(dir, ".arc");
+  const indexPath = join(arcDir, "INDEX.md");
+  const templatePath = join(arcDir, "_TEMPLATE.md");
+  if (!existsSync(indexPath) || !existsSync(templatePath)) {
+    return fail(`.arc/INDEX.md or _TEMPLATE.md missing in ${dir} — run \`create-arc init\` first`);
+  }
+
+  let index = readText(indexPath);
+  const m = index.match(/^next_id:\s*ARC-(\d+)\s*$/m);
+  if (!m) return fail("could not find 'next_id: ARC-NNNN' in INDEX.md");
+  const num = parseInt(m[1], 10);
+  const id = `ARC-${String(num).padStart(4, "0")}`;
+  const date = today();
+  const filename = `${id}-${slugify(title)}.md`;
+  const dest = join(arcDir, filename);
+  if (existsSync(dest)) return fail(`${dest} already exists`);
+
+  // build the arc file from the template
+  const tpl = readText(templatePath);
+  const fmMatch = tpl.match(/^---\n([\s\S]*?)\n---\n/);
+  if (!fmMatch) return fail("_TEMPLATE.md has no YAML frontmatter");
+  let front = fmMatch[1];
+  let body = tpl.slice(fmMatch[0].length);
+
+  front = setField(front, "id", id);
+  front = setField(front, "title", title);
+  front = setField(front, "status",
+    "draft            # draft | planned | refining | in-progress | blocked | review | done | cancelled");
+  front = setField(front, "created", date);
+  front = setField(front, "updated", date);
+  if (flags.owner) front = setField(front, "owner", flags.owner);
+  if (flags.tags) {
+    const tags = String(flags.tags).split(",").map((t) => t.trim()).filter(Boolean).join(", ");
+    front = setField(front, "tags", `[${tags}]`);
+  }
+  body = body.replace("# ARC-0000 · <Title>", `# ${id} · ${title}`);
+  writeFileSync(dest, `---\n${front}\n---\n${body}`);
+
+  // update the index: bump next_id, insert registry row
+  index = index.replace(/^next_id:\s*ARC-\d+\s*$/m, `next_id: ARC-${String(num + 1).padStart(4, "0")}`);
+  const row = `| ${id} | ${title} | draft | 1 | ${date} | — | [${filename}](${filename}) |`;
+  const lines = index.split("\n");
+  let insertAt = -1;
+  for (let i = 0; i < lines.length; i++) {
+    if (lines[i].startsWith("## Archived")) break;
+    if (/^\|\s*ARC-/.test(lines[i])) insertAt = i;
+  }
+  if (insertAt === -1) return fail("could not locate the Active table in INDEX.md");
+  lines.splice(insertAt + 1, 0, row);
+  writeFileSync(indexPath, lines.join("\n"));
+
+  console.log(`created  .arc/${filename}`);
+  console.log(`index    row added, next_id -> ARC-${String(num + 1).padStart(4, "0")}`);
+  console.log("Now fill in: Raw Instruction (verbatim), Plan, Tasks.");
+  return 0;
+}
+
+function parseArc(path, archived) {
+  const text = readText(path);
+  const front = frontmatter(text);
+  const section = text.match(/^## 4 · Tasks\n([\s\S]*?)(?=^## |(?![\s\S]))/m)?.[1] ?? text;
+  const markers = [...section.matchAll(/^- \[([ >x!-])\]/gm)].map((x) => x[1]);
+  const count = (c) => markers.filter((x) => x === c).length;
+  return {
+    id: field(front, "id", basename(path).split("-").slice(0, 2).join("-")),
+    title: field(front, "title"),
+    status: field(front, "status"),
+    plan_version: field(front, "plan_version", "1"),
+    updated: field(front, "updated"),
+    tasks_done: count("x"),
+    tasks_total: markers.length,
+    tasks_in_progress: count(">"),
+    tasks_blocked: count("!"),
+    archived,
+    file: path,
+  };
+}
+
+function cmdStatus(target, flags) {
+  const dir = resolve(target ?? ".");
+  const arcDir = join(dir, ".arc");
+  if (!existsSync(arcDir)) return fail(`${arcDir} not found — run \`create-arc init\` first`);
+
+  const { active, archived } = listArcFiles(arcDir);
+  const arcs = [...active.map((p) => parseArc(p, false)), ...archived.map((p) => parseArc(p, true))];
+
+  if (flags.json) { console.log(JSON.stringify(arcs, null, 2)); return 0; }
+  if (!arcs.length) { console.log("no arcs found"); return 0; }
+
+  const indexText = existsSync(join(arcDir, "INDEX.md")) ? readText(join(arcDir, "INDEX.md")) : "";
+  const focus = indexText.match(/^active_focus:\s*(.+)$/m)?.[1]?.trim();
+  const nextId = indexText.match(/^next_id:\s*(.+)$/m)?.[1]?.trim();
+
+  const headers = ["ID", "STATUS", "V", "TASKS", "UPDATED", "TITLE"];
+  const rows = arcs.map((a) => [
+    a.id,
+    a.status + (a.archived ? " (archived)" : ""),
+    a.plan_version,
+    (a.tasks_total ? `${a.tasks_done}/${a.tasks_total}` : "—") + (a.tasks_blocked ? ` !${a.tasks_blocked}` : ""),
+    a.updated,
+    a.title,
+  ]);
+  const w = headers.map((h, i) => Math.max(h.length, ...rows.map((r) => String(r[i]).length)));
+  const fmt = (r) => r.map((c, i) => String(c).padEnd(w[i])).join("  ");
+  console.log(fmt(headers));
+  console.log("-".repeat(fmt(headers).length));
+  rows.forEach((r) => console.log(fmt(r)));
+
+  const activeCount = arcs.filter((a) => !a.archived).length;
+  const resume = arcs.filter((a) => !a.archived && (a.status === "in-progress" || a.status === "refining"))
+    .map((a) => a.id);
+  let summary = `\n${activeCount} active, ${arcs.length - activeCount} archived`;
+  if (focus) summary += ` · focus: ${focus}`;
+  if (nextId) summary += ` · next_id: ${nextId}`;
+  console.log(summary);
+  if (resume.length) console.log(`resume from: ${resume.join(", ")} (read Status Notes + last Worklog entry)`);
+  return 0;
+}
+
+function cmdDoctor(target) {
+  const dir = resolve(target ?? ".");
+  const arcDir = join(dir, ".arc");
+  const indexPath = join(arcDir, "INDEX.md");
+  let failures = 0, warnings = 0;
+  const ok = (msg) => console.log(`  OK    ${msg}`);
+  const bad = (msg) => { console.log(`  FAIL  ${msg}`); failures++; };
+  const warn = (msg) => { console.log(`  WARN  ${msg}`); warnings++; };
+
+  if (!existsSync(arcDir)) return fail(`${arcDir} not found — run \`create-arc init\` first`);
+  if (!existsSync(indexPath)) { bad(".arc/INDEX.md missing"); return finish(); }
+
+  const index = readText(indexPath);
+  const { active, archived } = listArcFiles(arcDir);
+  const all = [...active.map((p) => ({ p, archived: false })), ...archived.map((p) => ({ p, archived: true }))];
+
+  // next_id sanity
+  const nm = index.match(/^next_id:\s*ARC-(\d+)\s*$/m);
+  const maxId = Math.max(-1, ...all.map(({ p }) => parseInt(basename(p).match(/^ARC-(\d+)/)?.[1] ?? "-1", 10)));
+  if (!nm) bad("next_id missing or malformed in INDEX.md");
+  else if (parseInt(nm[1], 10) <= maxId) bad(`next_id ARC-${nm[1]} is not greater than highest existing arc ARC-${String(maxId).padStart(4, "0")}`);
+  else ok(`next_id ARC-${nm[1]} > highest arc id`);
+
+  // file <-> index bijection, frontmatter integrity
+  const indexIds = new Set([...index.matchAll(/^\|\s*(ARC-\d{4})\s*\|/gm)].map((x) => x[1]));
+  for (const { p } of all) {
+    const fileId = basename(p).match(/^(ARC-\d{4})/)?.[1];
+    const front = frontmatter(readText(p));
+    const fmId = field(front, "id");
+    const status = field(front, "status");
+    if (fmId !== fileId) bad(`${basename(p)}: frontmatter id '${fmId}' != filename id '${fileId}'`);
+    if (!VALID_STATUSES.has(status)) bad(`${basename(p)}: invalid status '${status}'`);
+    if (!indexIds.has(fileId)) bad(`${basename(p)}: no row in INDEX.md`);
+    const inProg = [...readText(p).matchAll(/^- \[>\]/gm)].length;
+    if (inProg > 2) warn(`${basename(p)}: ${inProg} tasks marked [>] — keep at most 1–2 in progress`);
+  }
+  const fileIds = new Set(all.map(({ p }) => basename(p).match(/^(ARC-\d{4})/)?.[1]));
+  for (const id of indexIds) if (!fileIds.has(id)) bad(`INDEX.md row ${id} has no matching arc file`);
+  if (!failures) ok(`${all.length} arc file(s) ↔ INDEX rows consistent`);
+
+  return finish();
+
+  function finish() {
+    console.log(failures
+      ? `\ndoctor: ${failures} problem(s), ${warnings} warning(s)`
+      : `\ndoctor: healthy (${warnings} warning(s))`);
+    return failures ? 1 : 0;
+  }
+}
+
+/* --------------------------------- main ----------------------------------- */
+
+function fail(msg) { console.error(`error: ${msg}`); return 1; }
+
+function help() {
+  console.log(`create-arc v${PKG.version} — ARC plan-driven development (Align → Refine → Construct)
+
+Usage:
+  create-arc init [dir] [--owner=NAME]        scaffold ARC.md + .arc/ (idempotent)
+  create-arc new "Title" [--dir=.] [--tags=a,b] [--owner=NAME]
+                                              create + register the next arc
+  create-arc status [dir] [--json]            status table across all arcs
+  create-arc doctor [dir]                     consistency checks (exit 1 on problems)
+
+Protocol reference: ARC.md in your project root after init.`);
+  return 0;
+}
+
+const { pos, flags } = parseArgv(process.argv.slice(2));
+const cmd = pos[0];
+
+let code;
+if (flags.version || cmd === "version") { console.log(PKG.version); code = 0; }
+else if (!cmd || cmd === "help" || flags.help) code = help();
+else if (cmd === "init") code = cmdInit(pos[1], flags);
+else if (cmd === "new") code = cmdNew(pos.slice(1).join(" "), flags);
+else if (cmd === "status") code = cmdStatus(pos[1], flags);
+else if (cmd === "doctor") code = cmdDoctor(pos[1]);
+else code = fail(`unknown command '${cmd}' — try: create-arc help`);
+
+process.exit(code);

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@ksoftm/create-arc",
+  "version": "1.0.5",
+  "private": false,
+  "description": "Scaffold and manage ARC — plan-driven development for AI agents (Align → Refine → Construct). Pure-Markdown plans, tasks, worklogs and statuses in .arc/, for any language and any agent.",
+  "keywords": [
+    "arc",
+    "agents",
+    "agents-md",
+    "ai",
+    "ai-agents",
+    "plan-driven",
+    "planning",
+    "scaffold",
+    "claude",
+    "workflow"
+  ],
+  "license": "MIT",
+  "author": "Ksoftm (Kajalan)",
+  "type": "module",
+  "bin": {
+    "create-arc": "bin/cli.js"
+  },
+  "files": [
+    "bin",
+    "templates",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "test": "node --test"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/KsoftmHub/arc-framework-v1.git",
+    "directory": "packages/create-arc"
+  },
+  "homepage": "https://github.com/KsoftmHub/arc-framework-v1#readme",
+  "bugs": {
+    "url": "https://github.com/KsoftmHub/arc-framework-v1/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/templates/ARC-0000-maintenance.md

@@ -0,0 +1,50 @@
+---
+id: ARC-0000
+title: Maintenance (standing)
+status: in-progress
+created: {{DATE}}
+updated: {{DATE}}
+plan_version: 1
+owner: {{OWNER}}
+scope: ["*"]
+depends_on: []
+relates_to: []
+tags: [maintenance]
+---
+
+# ARC-0000 · Maintenance (standing)
+
+Perpetual arc for trivial changes: typo fixes, comment corrections, dependency
+bumps with no behavior change, formatting. **Rule of thumb:** if it needs a
+design decision, a plan, or more than a few minutes — it gets its own arc.
+
+## 1 · Raw Instructions
+
+### I1 — {{DATE}} (source: protocol)
+> Standing lane defined by ARC.md §Intake-4 for trivial maintenance work.
+
+## 2 · Plan (current — v1)
+
+**Goal:** Trivial fixes stay traceable without per-fix arc overhead.
+**Acceptance criteria:** every trivial change has a worklog entry here and an `[ARC-0000]` commit reference.
+
+## 3 · Refinement Log
+
+## 4 · Tasks
+
+(none — this arc is worklog-driven)
+
+## 5 · Worklog
+
+<!--
+### YYYY-MM-DD HH:MM — <what>
+- read: <…>
+- changed: <…>
+- summary: <…>
+-->
+
+## 6 · Status Notes
+
+**Current:** Open, perpetual.
+**Blockers:** none
+**Next:** —

package/templates/ARC.md

@@ -0,0 +1,150 @@
+# ARC framework
+
+- ARC is a plan-driven development protocol installed in this project
+- ARC = **Align → Refine → Construct**: capture the instruction, plan it, refine the plan when needed, only then build
+- Every unit of development (feature, fix, refactor, integration, experiment) is an **arc** — one Markdown file in `.arc/` that holds its full story: raw instructions, plan, refinements, tasks, worklog, and status
+- Any AI agent working in this repository must follow ARC across all development work
+
+## Prime Directive
+
+**No construction without an arc.**
+Code, configs, schemas, infra, and docs are only changed under an arc that covers the change. If no arc covers it, create or extend one first (see Intake).
+
+## Core Contract
+
+- One arc file per unit of development; the arc is the single source of truth for that work's intent, plan, progress, and history
+- Raw user instructions are **immutable and append-only** — never rewrite, summarize-in-place, or delete the user's words
+- Plans evolve only through logged refinements, never by silent rewrite
+- The codebase is truth for what currently *is*; arcs are truth for what was *asked*, what is *intended*, and what *happened*
+- Every edit session ends with an Update After Editing pass — an edit without a worklog entry is an unfinished edit
+
+## Layout
+
+```
+.arc/
+├── INDEX.md            # registry of all arcs: id, title, status, next_id counter
+├── _TEMPLATE.md        # copy this to start a new arc
+├── ARC-0001-slug.md    # active arcs live flat in .arc/
+├── ARC-0002-slug.md
+├── notes/              # optional: long research spilled out of an arc (linked back)
+└── archive/            # done/cancelled arcs move here; INDEX row remains
+```
+
+Arc filenames: `ARC-<NNNN>-<short-kebab-slug>.md`. IDs are sequential, never reused; take the next ID from `next_id` in INDEX.md and increment it.
+
+## Lifecycle
+
+```
+draft ──► planned ──────────────► in-progress ──► review ──► done ──► (archive/)
+            ▲                        │
+            │                        │ scope change / new instruction
+            └──────  refining  ◄─────┘
+                (plan_version + 1)
+any state ──► blocked (with reason) ──► back to prior state
+any state ──► cancelled ──► (archive/)
+```
+
+The two sanctioned flows:
+
+1. **Fast lane** — plan → develop: `draft → planned → in-progress → done`
+2. **Refine lane** — plan → refine/update → develop: `draft → planned → refining → planned (v2…vN) → in-progress → done`
+
+Rules:
+- `in-progress` requires an approved plan — explicit user approval, or implicit when the user clearly said to just do it
+- A new instruction arriving mid-construction sends the arc to `refining`; resume construction only after the plan and tasks absorb it
+- `done` requires all acceptance criteria checked and all tasks `[x]` or `[-]`
+
+## Intake (Align)
+
+When the user gives a development instruction:
+
+1. Read `.arc/INDEX.md`
+2. Decide:
+   - **Existing open arc covers it** → append the instruction verbatim to that arc's Raw Instructions, write a Refinement Log entry, update Plan and Tasks
+   - **Existing arc is done/archived** → create a new arc and link it via `relates_to`; do not reopen closed arcs
+   - **Nothing covers it** → copy `_TEMPLATE.md` to a new `ARC-NNNN-slug.md`, record the instruction verbatim as I1, draft the plan, register it in INDEX.md
+3. Record the instruction **verbatim** — typos, voice-transcription noise, and all. If wording is ambiguous, add an `interpreted:` line beneath it stating your reading; if the interpretation changes scope or risk, confirm with the user before moving past `planned`
+4. Trivial maintenance (typo-level, no design decision, ~minutes of work) may be logged as a worklog entry in the standing `ARC-0000-maintenance` arc instead of a new arc — but it is still logged
+
+## Read Before Editing
+
+Before touching any project file, in the current session:
+
+1. Read `.arc/INDEX.md`
+2. Open every arc whose `scope` covers the paths you expect to touch; read it fully — latest Raw Instructions, current Plan, open Tasks, and the last Worklog entries
+3. Read the actual source files you will change as they exist now
+4. If the project also has an AGENTS.md / DOX tree or similar, walk it too — arcs govern *what to build*; those docs govern *how to work in this codebase*
+5. If no arc covers a non-trivial change, stop and run Intake first
+
+Do not rely on memory from previous sessions or on the model's assumptions about file contents. Re-read the applicable arc chain and target files before editing.
+
+## Update After Editing
+
+Immediately after editing — same session, before reporting the task as done:
+
+1. Advance task states in the arc's Tasks section
+2. Append one Worklog entry: timestamp, tasks advanced, files read, files changed, summary, decisions made, follow-ups discovered
+3. Update frontmatter: `updated` date and `status`; bump `plan_version` only if the Plan section changed
+4. Sync the arc's row in `.arc/INDEX.md` (status, updated)
+5. Reference the arc ID in the commit message: `[ARC-0007] add redis limiter`
+6. On completion: check acceptance criteria, set `done`, move the file to `.arc/archive/`, keep the INDEX row pointing at the new path
+
+## Refinement Rules
+
+- Every new instruction on existing work becomes a numbered Raw Instruction entry (I2, I3, …) — verbatim, dated, with its source (chat, voice, issue, review)
+- Each refinement gets a Refinement Log entry: new `plan_version`, date, triggering instruction, what changed in the plan, and its task impact (tasks added / modified / removed)
+- The Plan section always shows only the **current** plan; history lives in the Refinement Log — never maintain two competing plans in one arc
+- Removed scope is moved to "Out of scope" with a one-line reason, not silently deleted
+
+## Status & Task Vocabulary
+
+Statuses: `draft` · `planned` · `refining` · `in-progress` · `blocked` · `review` · `done` · `cancelled`
+
+Task markers:
+
+```
+- [ ] T1 pending
+- [>] T2 in progress        (at most one or two at a time)
+- [x] T3 done
+- [!] T4 blocked: <reason>
+- [-] T5 cancelled: <reason>
+```
+
+Tasks are numbered `T1, T2, …` within an arc and never renumbered; new tasks append. Reference them everywhere as `ARC-0007/T3`.
+
+## Conflict & Drift
+
+- If an arc and the codebase disagree, the codebase is truth for the current state — record the drift in the Worklog, then fix the arc
+- Newer raw instructions override older ones within an arc; note the override in the Refinement Log
+- Arcs never weaken repository-wide rules, safety constraints, or verification requirements defined in AGENTS.md / DOX / CI
+
+## Session Resume
+
+Any agent, any tool, any time can resume work cold:
+
+1. Read `.arc/INDEX.md` → find arcs in `in-progress`, `refining`, or `blocked`
+2. Open each, read Status Notes and the last Worklog entry
+3. Continue from the open `[>]`/`[ ]` tasks — after running Read Before Editing
+
+This is the crash-recovery property: the arc, not the chat history, carries the state.
+
+## Style
+
+- Concise and operational; a plan is a contract, not an essay
+- Acceptance criteria must be objectively checkable
+- Keep an arc under ~300 lines; spill long research or option analysis to `.arc/notes/ARC-NNNN-topic.md` and link it
+- Append-only sections (Raw Instructions, Refinement Log, Worklog) are never edited retroactively; everything else is kept current and stale text is removed
+- Worklog entries record facts and decisions, not narration
+
+## Coexistence
+
+ARC composes with AGENTS.md, CLAUDE.md, DOX, and editor rule files. Division of labor: those describe the codebase and working conventions; ARC tracks intent, plans, and progress. If this file is referenced from an AGENTS.md, treat ARC as binding for all development work.
+
+## Initialization
+
+If `.arc/` does not exist yet, initialize ARC now before any other work:
+
+1. Create `.arc/INDEX.md` with an empty registry and `next_id: ARC-0001`
+2. Create `.arc/_TEMPLATE.md`, `.arc/notes/`, `.arc/archive/`
+3. Create `ARC-0000-maintenance.md` as the standing trivial-fix arc (status: `in-progress`, perpetual)
+4. If the user already gave development instructions, run Intake on them immediately

package/templates/INDEX.md

@@ -0,0 +1,25 @@
+# ARC Index
+
+next_id: ARC-0001
+active_focus: —
+
+## Active
+
+| ID | Title | Status | Plan v | Updated | Depends | File |
+|---|---|---|---|---|---|---|
+| ARC-0000 | Maintenance (standing) | in-progress | 1 | {{DATE}} | — | [ARC-0000-maintenance.md](ARC-0000-maintenance.md) |
+
+## Archived
+
+| ID | Title | Outcome | Closed | File |
+|---|---|---|---|---|
+| — | — | — | — | — |
+
+<!--
+Rules:
+- Take new IDs from next_id, then increment it — IDs are never reused.
+- Every arc file in .arc/ and .arc/archive/ has exactly one row here.
+- Sync a row's Status/Updated during every Update-After-Editing pass.
+- When an arc closes, move its file to archive/ and move its row to Archived
+  (Outcome: done | cancelled).
+-->

package/templates/_TEMPLATE.md

@@ -0,0 +1,81 @@
+---
+id: ARC-0000
+title: <short imperative title>
+status: draft            # draft | planned | refining | in-progress | blocked | review | done | cancelled
+created: YYYY-MM-DD
+updated: YYYY-MM-DD
+plan_version: 1
+owner: <user / team>
+scope: []                # paths this arc owns or touches, e.g. [src/api/, prisma/schema.prisma]
+depends_on: []           # arc IDs that must be done first, e.g. [ARC-0003]
+relates_to: []           # related arc IDs (context, successors of closed arcs)
+tags: []                 # e.g. [api, infra, bugfix]
+---
+
+# ARC-0000 · <Title>
+
+## 1 · Raw Instructions
+<!-- Append-only. Verbatim user words — never edited, never deleted. -->
+
+### I1 — YYYY-MM-DD (source: chat | voice | issue | review)
+> <exact instruction text>
+
+interpreted: <optional — your plain reading of an ambiguous/voice-noisy instruction; confirm with the user if it changes scope>
+
+## 2 · Plan (current — v1)
+<!-- Always reflects the CURRENT plan only. History lives in §3. -->
+
+**Goal:** <one sentence — what exists when this arc is done>
+
+**Approach:** <how, in a few lines — key technical decisions>
+
+**In scope:**
+- <…>
+
+**Out of scope:**
+- <…> — <reason>
+
+**Acceptance criteria:** <!-- objectively checkable -->
+- [ ] AC1 <…>
+- [ ] AC2 <…>
+
+**Affected paths:** <files/dirs expected to change — keep frontmatter `scope` in sync>
+
+**Risks / unknowns:** <optional>
+
+## 3 · Refinement Log
+<!-- Append-only. One entry per plan version bump. Empty until the first refinement. -->
+
+<!--
+### v2 — YYYY-MM-DD — triggered by I2
+- changed: <what changed in the plan and why>
+- task impact: added T5–T6; modified T3; cancelled T4
+-->
+
+## 4 · Tasks
+<!-- Numbered T1, T2, … — never renumber; append new tasks at the end.
+     Markers: [ ] pending · [>] in progress · [x] done · [!] blocked: reason · [-] cancelled: reason -->
+
+- [ ] T1 <…>
+- [ ] T2 <…>
+- [ ] T3 <…>
+
+## 5 · Worklog
+<!-- Append-only. One entry per Update-After-Editing pass. Newest at the bottom. -->
+
+<!--
+### YYYY-MM-DD HH:MM — <one-line session note>
+- tasks: T1 [>]→[x]; T2 →[>]
+- read: <files read before editing>
+- changed: <files created/modified/deleted>
+- summary: <what was actually done>
+- decisions: <choices made and why, if any>
+- follow-ups: <new tasks, questions for the user, discovered debt>
+-->
+
+## 6 · Status Notes
+<!-- Kept current — overwrite freely. The one place to glance for "where is this?" -->
+
+**Current:** <one-line truth of where this stands>
+**Blockers:** <none | …>
+**Next:** <the very next action>