@afokapu/atdd-bun 0.1.1 → 0.1.3

package/README.md

@@ -137,16 +137,17 @@ bun run atdd-bun init
 ```
 
 It creates `.githooks/` dispatchers, sets a worktree-local `core.hooksPath`,
-and generates `.github/workflows/atdd-bun.yml` when it is absent. It never
-overwrites another hook path or an existing generated workflow unless you
-explicitly pass `--replace`. Installing the dependency alone deliberately does
+generates `.github/workflows/atdd-bun.yml`, and installs the coding-agent skill
+when they are absent. It never overwrites another hook path, an existing
+generated workflow, or an existing skill unless you explicitly pass `--replace`. Installing the dependency alone deliberately does
 neither: package installation must not mutate a repository through postinstall.
 
-Use `hooks install` or `ci init` when only one surface is wanted:
+Use `hooks install`, `ci init`, or `agent init` when only one surface is wanted:
 
 ```sh
 bun run atdd-bun hooks install
 bun run atdd-bun ci init
+bun run atdd-bun agent init
 ```
 
 The hooks enforce protected-branch blocking, micro-commit limits, mass-delete
@@ -161,6 +162,24 @@ bun run atdd-bun hooks uninstall
 Hooks can be bypassed by Git and therefore are never the merge gate. The CI
 workflow and GitHub branch ruleset are the authority for merging.
 
+## Agent skill: the lifecycle in the agent's context
+
+`agent init` gives every coding agent the same short ATDD skill:
+
+- `.agents/skills/atdd/SKILL.md`: the vendor-neutral Agent Skills path (Codex,
+  GitHub Copilot, Cursor, Gemini CLI, and others);
+- `.claude/skills/atdd/SKILL.md`: Claude Code;
+- a managed `<!-- atdd-bun:start -->` block in `AGENTS.md` pointing at the skill,
+  for agents that read `AGENTS.md` but not skills. The rest of `AGENTS.md` is
+  never touched.
+
+The skill names the lifecycle PLAN → RED → GREEN → SMOKE → REFACTOR → TRACE, the
+conventions each stage follows, and the `atdd-bun` profile that gates it. It
+points at the conventions shipped in this package instead of restating them, so
+it stays correct as they change; after upgrading, refresh it with
+`bun run atdd-bun agent init --replace`. The skill steers the agent; the
+profiles, hooks, and CI remain the enforcement.
+
 ## CI: the merge gate
 
 Generate the repository-owned workflow with:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@afokapu/atdd-bun",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/afokapu/atdd-bun.git"

package/src/agent.ts

@@ -0,0 +1,31 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+
+const root = resolve(import.meta.dir, "..");
+const version = (await Bun.file(join(root, "package.json")).json() as { version: string }).version;
+const render = async (path: string) => (await readFile(join(root, "templates/agents", path), "utf8")).replace("{{VERSION}}", version);
+// .agents/skills is the vendor-neutral Agent Skills path (Codex, Copilot, Cursor, Gemini CLI, …); .claude/skills is Claude Code's.
+const skillPaths = [".agents/skills/atdd/SKILL.md", ".claude/skills/atdd/SKILL.md"];
+const block = /<!-- atdd-bun:start[\s\S]*?<!-- atdd-bun:end -->\n?/;
+
+/** Write the ATDD skill for every agent and a managed pointer block in AGENTS.md. Existing files and an
+ * existing block are kept unless `replace`; the rest of AGENTS.md is never touched. */
+export async function agentInit(repo = process.cwd(), replace = false) {
+  const written: string[] = [], kept: string[] = [];
+  for (const path of skillPaths) {
+    const output = join(repo, path);
+    if (existsSync(output) && !replace) { kept.push(output); continue; }
+    await mkdir(dirname(output), { recursive: true }); await writeFile(output, await render("atdd/SKILL.md")); written.push(output);
+  }
+  const agents = join(repo, "AGENTS.md"), current = existsSync(agents) ? await readFile(agents, "utf8") : "", managed = await render("AGENTS.block.md");
+  if (block.test(current) && !replace) kept.push(agents);
+  else { await writeFile(agents, block.test(current) ? current.replace(block, managed) : current + (current && !current.endsWith("\n\n") ? (current.endsWith("\n") ? "\n" : "\n\n") : "") + managed); written.push(agents); }
+  if (!written.length) return { ok: false, message: `${kept.join(", ")} exist; use --replace` };
+  return { ok: true, message: written.join("\n") };
+}
+export async function agentStatus(repo = process.cwd()) {
+  const agents = join(repo, "AGENTS.md"), missing = skillPaths.map(path => join(repo, path)).filter(path => !existsSync(path));
+  if (!existsSync(agents) || !block.test(await readFile(agents, "utf8"))) missing.push(`${agents} (atdd-bun block)`);
+  return { ok: !missing.length, message: missing.length ? `missing: ${missing.join(", ")}` : [...skillPaths, "AGENTS.md"].map(path => join(repo, path)).join("\n") };
+}

package/src/cli.ts

@@ -2,6 +2,7 @@
 import { enforce, profileNames, type Profile } from "./enforce";
 import { finishWorktree, hookEvents, hooksStatus, installHooks, runHook, startWorktree, uninstallHooks, worktreeStatus } from "./hooks";
 import { ciInit, ciStatus } from "./ci";
+import { agentInit, agentStatus } from "./agent";
 import { releaseCheck } from "./release";
 import { initializeRepository } from "./setup";
 
@@ -14,6 +15,7 @@ const usage = {
     "atdd-bun hooks <install|uninstall|status> [--replace]",
     "atdd-bun worktree <start|finish|status>",
     "atdd-bun ci <init|status> [--replace]",
+    "atdd-bun agent <init|status> [--replace]",
     "atdd-bun release check",
   ],
   profiles: profileNames,
@@ -64,6 +66,10 @@ if (args[0] === "ci") {
   const result = args[1] === "init" ? await ciInit(process.cwd(), args.includes("--replace")) : args[1] === "status" ? await ciStatus() : fail("ci requires init or status");
   console[result.ok ? "log" : "error"](result.message); process.exit(result.ok ? 0 : 1);
 }
+if (args[0] === "agent") {
+  const result = args[1] === "init" ? await agentInit(process.cwd(), args.includes("--replace")) : args[1] === "status" ? await agentStatus() : fail("agent requires init or status");
+  console[result.ok ? "log" : "error"](result.message); process.exit(result.ok ? 0 : 1);
+}
 if (args[0] === "release") {
   if (args[1] !== "check") fail("release requires check");
   const result = await releaseCheck(); console[result.ok ? "log" : "error"](result.message); process.exit(result.ok ? 0 : 1);

package/src/setup.ts

@@ -1,7 +1,8 @@
 import { ciInit, ciStatus } from "./ci";
 import { hooksStatus, installHooks } from "./hooks";
+import { agentInit, agentStatus } from "./agent";
 
-/** Install the package's two opt-in local surfaces without touching unrelated
+/** Install the package's three opt-in local surfaces without touching unrelated
  * workflows or hook paths. Dependency installation itself never calls this. */
 export async function initializeRepository(root = process.cwd(), replace = false) {
   const existingHooks = await hooksStatus(root);
@@ -11,5 +12,9 @@ export async function initializeRepository(root = process.cwd(), replace = false
   const existingCi = await ciStatus(root);
   const ci = replace || !existingCi.ok ? await ciInit(root, replace) : existingCi;
   if (!ci.ok) return { ok: false, message: `CI workflow: ${ci.message}` };
-  return { ok: true, message: `hooks: ${hooks.message}\nCI workflow: ${ci.message}` };
+
+  const existingAgent = await agentStatus(root);
+  const agent = replace || !existingAgent.ok ? await agentInit(root, replace) : existingAgent;
+  if (!agent.ok) return { ok: false, message: `agent skill: ${agent.message}` };
+  return { ok: true, message: `hooks: ${hooks.message}\nCI workflow: ${ci.message}\nagent skill: ${agent.message}` };
 }

package/templates/agents/AGENTS.block.md

@@ -0,0 +1,5 @@
+<!-- atdd-bun:start — generated by @afokapu/atdd-bun {{VERSION}}; run `atdd-bun agent init --replace` to refresh -->
+## ATDD lifecycle
+
+Before changing code, tests, or `plan/`, follow `.agents/skills/atdd/SKILL.md`: PLAN → RED → GREEN → SMOKE → REFACTOR → TRACE, passing each stage's `atdd-bun` gate before starting the next.
+<!-- atdd-bun:end -->

package/templates/agents/atdd/SKILL.md

@@ -0,0 +1,16 @@
+---
+name: atdd
+description: Use before writing or changing code, tests, or plan/ files in this repository. New intent is decomposed and delivered through the ATDD lifecycle PLAN → RED → GREEN → SMOKE → REFACTOR → TRACE, each stage gated by atdd-bun. Skip PLAN only when the change fits an acceptance that already exists.
+---
+<!-- Generated by @afokapu/atdd-bun {{VERSION}}. Do not edit; run `atdd-bun agent init --replace`. -->
+
+Conventions live in `node_modules/@afokapu/atdd-bun/` (`planner-nodes/nodes/`, `conventions/`). Read the ones a stage names; do not restate them. Finish each stage by passing its gate before starting the next.
+
+1. PLAN — Decompose the intent into wagon → WMBT → acceptance → train/interlocking → journey → contract under `plan/`, following `planner.decomposition.*`; every WMBT declares a SMOKE acceptance. Gate: `bun run atdd-bun planner`.
+2. RED — For each acceptance, write a test headed `// URN: test:{wagon}:{feature}:{ACC-ID}` and `// Phase: RED` that fails for the missing behaviour (`tester.bun.red-*`). Gate: `bun run atdd-bun tester`.
+3. GREEN — Write the least code that passes; each source file carries `URN: component:{wagon}:{feature}:{Name}:{side}:{layer}` and a `Tested-By:` block (`coder.bun.green-*`). Gate: `bun test`.
+4. SMOKE — Prove the SMOKE acceptance through the real entry point with no mocks or spies, asserting only on observable output: HTTP, markup, stdout, exit code (`tester.bun.smoke-*`, `planner.smoke.*`). Gate: `bun run atdd-bun tester`.
+5. REFACTOR — With tests green, reduce complexity, fix layering, and remove security faults until the rules pass, without changing behaviour (`coder.bun.complexity-*`, `quality-*`, `composition-*`, `security-*`). Gate: `bun run atdd-bun coder security`.
+6. TRACE — Every acceptance has a test, every test resolves to a declared acceptance, every source file resolves to its tests. Gate: `bun run atdd-bun traceability`, then `bun run atdd-bun all`.
+
+When a gate fails, open `<rule_id>.convention.yaml` for the reported rule ID and fix the artifact. Never skip, suppress, or edit a convention to get green.