@afokapu/atdd-bun 0.1.1 → 0.1.2

package/README.md

@@ -137,16 +137,18 @@ 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
+generates `.github/workflows/atdd-bun.yml`, and writes the coding-agent skill
+`.claude/skills/atdd/SKILL.md` 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 +163,16 @@ 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` writes `.claude/skills/atdd/SKILL.md`, a short skill that coding
+agents load before changing code, tests, or `plan/`. It 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.2",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/afokapu/atdd-bun.git"

package/src/agent.ts

@@ -0,0 +1,10 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { join, resolve } from "node:path";
+
+const root = resolve(import.meta.dir, "..");
+const template = join(root, "templates/claude/atdd/SKILL.md");
+const version = (await Bun.file(join(root, "package.json")).json() as { version: string }).version;
+const skillDir = (repo: string) => join(repo, ".claude/skills/atdd");
+export async function agentInit(repo = process.cwd(), replace = false) { const output = join(skillDir(repo), "SKILL.md"); if (existsSync(output) && !replace) return { ok: false, message: `${output} exists; use --replace` }; await mkdir(skillDir(repo), { recursive: true }); await writeFile(output, (await readFile(template, "utf8")).replace("{{VERSION}}", version)); return { ok: true, message: output }; }
+export async function agentStatus(repo = process.cwd()) { const output = join(skillDir(repo), "SKILL.md"); return { ok: existsSync(output), message: output }; }

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/claude/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.