@clemrig/factory 0.2.1 → 0.4.0

package/dist/system/issues.js

@@ -0,0 +1,66 @@
+import { access, mkdir, readdir, readFile, stat, writeFile, } from "node:fs/promises";
+import { dirname, join } from "node:path";
+/** Where the issues are, relative to the repository. */
+export const issuesPath = join(".factory", "issues");
+/** `.factory/issues/<slug>/<kind>.md`, relative to the repository: the only place that names these paths. */
+export function artifactPath(slug, kind) {
+    return join(issuesPath, slug, `${kind}.md`);
+}
+/** Every folder of `.factory/issues/`; none before the first issue. */
+export async function listIssueFolders(repository) {
+    const root = join(repository, issuesPath);
+    const entries = await readdir(root, { withFileTypes: true }).catch((error) => {
+        if (error.code === "ENOENT")
+            return [];
+        throw error;
+    });
+    const folders = [];
+    for (const entry of entries) {
+        if (!entry.isDirectory())
+            continue;
+        const files = await readdir(join(root, entry.name));
+        // A folder without its files is not an issue (an abandoned one, say).
+        if (!["issue.md", "spec.md", "plan.md"].some((file) => files.includes(file)))
+            continue;
+        const changes = await Promise.all([".", ...files].map((file) => stat(join(root, entry.name, file)).then(({ mtimeMs }) => mtimeMs, 
+        // An editor's temporary file may go between the listing and now.
+        (error) => {
+            if (error.code === "ENOENT")
+                return 0;
+            throw error;
+        })));
+        // One unreadable issue.md leaves the other issues readable.
+        const issue = await readArtifact(repository, entry.name, "issue").then((text) => ({ text }), (error) => ({
+            error: error instanceof Error ? error.message : String(error),
+        }));
+        folders.push({
+            slug: entry.name,
+            ...("text" in issue
+                ? { issue: issue.text }
+                : { unreadable: issue.error }),
+            hasSpec: files.includes("spec.md"),
+            changedAt: new Date(Math.max(...changes)).toISOString(),
+        });
+    }
+    return folders;
+}
+export async function writeArtifact(repository, slug, kind, text) {
+    const path = artifactPath(slug, kind);
+    await mkdir(dirname(join(repository, path)), { recursive: true });
+    await writeFile(join(repository, path), text);
+    return path;
+}
+export async function hasArtifact(repository, slug, kind) {
+    return access(join(repository, artifactPath(slug, kind))).then(() => true, () => false);
+}
+/** The artifact's text, or nothing when the issue has none. */
+export async function readArtifact(repository, slug, kind) {
+    if (!(await hasArtifact(repository, slug, kind)))
+        return undefined;
+    return readFile(join(repository, artifactPath(slug, kind)), "utf8");
+}
+/** A draft handed over by an agent, wherever it wrote it. */
+export function readDraft(path) {
+    return readFile(path, "utf8");
+}
+//# sourceMappingURL=issues.js.map

package/dist/system/issues.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"issues.js","sourceRoot":"","sources":["../../src/system/issues.ts"],"names":[],"mappings":"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"}

package/dist/system/lock.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Runs `work` while holding the lock file `path`, created atomically: two
+ * processes never hold it together. A holder is awaited up to `waitMs`; a lock
+ * still there after that, left by a process that stopped, is named in the error.
+ */
+export declare function exclusively<T>(path: string, work: () => Promise<T>, waitMs?: number): Promise<T>;
+/** Runs `work` alone among the factory's runs of this working tree: the lock lives in its Git directory. */
+export declare function withTreeLock<T>(dir: string, work: () => Promise<T>): Promise<T>;

package/dist/system/lock.js

@@ -0,0 +1,35 @@
+import { rm, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { gitDir } from "./git.js";
+/**
+ * Runs `work` while holding the lock file `path`, created atomically: two
+ * processes never hold it together. A holder is awaited up to `waitMs`; a lock
+ * still there after that, left by a process that stopped, is named in the error.
+ */
+export async function exclusively(path, work, waitMs = 10_000) {
+    const until = Date.now() + waitMs;
+    for (;;) {
+        try {
+            await writeFile(path, `${process.pid}\n`, { flag: "wx" });
+            break;
+        }
+        catch (error) {
+            if (error.code !== "EEXIST")
+                throw error;
+            if (Date.now() >= until)
+                throw new Error(`${path} has been held for ${Math.round(waitMs / 1000)} s: if no implement run is starting, remove it`);
+            await new Promise((resolve) => setTimeout(resolve, 50));
+        }
+    }
+    try {
+        return await work();
+    }
+    finally {
+        await rm(path, { force: true });
+    }
+}
+/** Runs `work` alone among the factory's runs of this working tree: the lock lives in its Git directory. */
+export async function withTreeLock(dir, work) {
+    return exclusively(join(await gitDir(dir), "factory-implement.lock"), work);
+}
+//# sourceMappingURL=lock.js.map

package/dist/system/lock.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lock.js","sourceRoot":"","sources":["../../src/system/lock.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,EAAE,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AACjD,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AAElC;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAC/B,IAAY,EACZ,IAAsB,EACtB,MAAM,GAAG,MAAM;IAEf,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,MAAM,CAAC;IAClC,SAAS,CAAC;QACR,IAAI,CAAC;YACH,MAAM,SAAS,CAAC,IAAI,EAAE,GAAG,OAAO,CAAC,GAAG,IAAI,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;YAC1D,MAAM;QACR,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,IAAK,KAA+B,CAAC,IAAI,KAAK,QAAQ;gBAAE,MAAM,KAAK,CAAC;YACpE,IAAI,IAAI,CAAC,GAAG,EAAE,IAAI,KAAK;gBACrB,MAAM,IAAI,KAAK,CACb,GAAG,IAAI,sBAAsB,IAAI,CAAC,KAAK,CAAC,MAAM,GAAG,IAAI,CAAC,gDAAgD,CACvG,CAAC;YACJ,MAAM,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,CAAC;QAC1D,CAAC;IACH,CAAC;IACD,IAAI,CAAC;QACH,OAAO,MAAM,IAAI,EAAE,CAAC;IACtB,CAAC;YAAS,CAAC;QACT,MAAM,EAAE,CAAC,IAAI,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;IAClC,CAAC;AACH,CAAC;AAED,4GAA4G;AAC5G,MAAM,CAAC,KAAK,UAAU,YAAY,CAChC,GAAW,EACX,IAAsB;IAEtB,OAAO,WAAW,CAAC,IAAI,CAAC,MAAM,MAAM,CAAC,GAAG,CAAC,EAAE,wBAAwB,CAAC,EAAE,IAAI,CAAC,CAAC;AAC9E,CAAC"}

package/dist/system/templates.d.ts

@@ -1,6 +1,7 @@
 /**
  * Creates `.factory/` in `cwd` from the package's templates, its `package.json`
- * pinned to this factory version. An existing `.factory/` is refused untouched.
+ * pinned to this factory version, and the `issue` skill. An existing
+ * `.factory/` or skill is refused, with nothing written.
  */
 export declare function createFromTemplates(cwd: string): Promise<{
     factoryDir: string;

package/dist/system/templates.js

@@ -1,13 +1,70 @@
-import { cp, mkdir, readFile, rename, writeFile } from "node:fs/promises";
-import { join } from "node:path";
+import { cp, lstat, mkdir, readFile, readlink, rename, symlink, writeFile, } from "node:fs/promises";
+import { basename, dirname, join, relative, resolve } from "node:path";
 /** Both `src/system/` and `dist/system/` sit two levels below the package root. */
 const root = new URL("../../", import.meta.url);
+/** The `issue` skill: read by Pi and Codex there, by Claude Code through a folder link. */
+const skillDir = join(".agents", "skills", "issue");
+async function exists(path) {
+    return lstat(path).then(() => true, (error) => {
+        if (error.code === "ENOENT")
+            return false;
+        throw error;
+    });
+}
+/**
+ * Where a path really leads: through every link on the way, dangling ones
+ * included, and through what does not exist yet.
+ */
+async function location(path, links = 0) {
+    if (links > 40)
+        throw new Error(`Too many links on the way to ${path}`);
+    const parent = dirname(path);
+    const here = parent === path
+        ? path
+        : join(await location(parent, links), basename(path));
+    const stats = await lstat(here).catch((error) => {
+        if (error.code === "ENOENT")
+            return undefined;
+        throw error;
+    });
+    if (!stats?.isSymbolicLink())
+        return here;
+    return location(resolve(dirname(here), await readlink(here)), links + 1);
+}
+/**
+ * Where the skill goes, and Claude Code's link to it, both where the paths
+ * really lead: `.agents`, `.claude` and their `skills` may be links, even to
+ * folders that do not exist yet. No link when `.claude/skills` leads to
+ * `.agents/skills`, which then holds the skill. The link's target is relative
+ * to the folder it lands in.
+ */
+async function skillPlaces(cwd) {
+    const agents = await location(join(resolve(cwd), ".agents", "skills"));
+    const claude = await location(join(resolve(cwd), ".claude", "skills"));
+    const skill = { path: join(agents, "issue"), shown: join(cwd, skillDir) };
+    if (claude === agents)
+        return { skill };
+    return {
+        skill,
+        link: {
+            path: join(claude, "issue"),
+            target: relative(claude, skill.path),
+            shown: join(cwd, ".claude", "skills", "issue"),
+        },
+    };
+}
 /**
  * Creates `.factory/` in `cwd` from the package's templates, its `package.json`
- * pinned to this factory version. An existing `.factory/` is refused untouched.
+ * pinned to this factory version, and the `issue` skill. An existing
+ * `.factory/` or skill is refused, with nothing written.
  */
 export async function createFromTemplates(cwd) {
     const factoryDir = join(cwd, ".factory");
+    // Everything is decided before anything is written.
+    const { skill, link } = await skillPlaces(cwd);
+    for (const { path, shown } of [skill, ...(link ? [link] : [])])
+        if (await exists(path))
+            throw new Error(`${shown} already exists`);
     try {
         await mkdir(factoryDir);
     }
@@ -25,6 +82,15 @@ export async function createFromTemplates(cwd) {
         type: "module",
         dependencies: { "@clemrig/factory": version },
     }, null, 2)}\n`);
+    await mkdir(dirname(skill.path), { recursive: true });
+    await cp(new URL("templates/skills/issue/", root), skill.path, {
+        recursive: true,
+    });
+    if (link) {
+        await mkdir(dirname(link.path), { recursive: true });
+        // Codex ignores a SKILL.md that is itself a link: the link is the folder's.
+        await symlink(link.target, link.path);
+    }
     return { factoryDir, version };
 }
 //# sourceMappingURL=templates.js.map

package/dist/system/templates.js.map

@@ -1 +1 @@
-{"version":3,"file":"templates.js","sourceRoot":"","sources":["../../src/system/templates.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAC1E,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAEjC,mFAAmF;AACnF,MAAM,IAAI,GAAG,IAAI,GAAG,CAAC,QAAQ,EAAE,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC;AAEhD;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,mBAAmB,CACvC,GAAW;IAEX,MAAM,UAAU,GAAG,IAAI,CAAC,GAAG,EAAE,UAAU,CAAC,CAAC;IACzC,IAAI,CAAC;QACH,MAAM,KAAK,CAAC,UAAU,CAAC,CAAC;IAC1B,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAK,KAA+B,CAAC,IAAI,KAAK,QAAQ;YACpD,MAAM,IAAI,KAAK,CAAC,GAAG,UAAU,iBAAiB,CAAC,CAAC;QAClD,MAAM,KAAK,CAAC;IACd,CAAC;IACD,MAAM,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC,KAAK,CAC5B,MAAM,QAAQ,CAAC,IAAI,GAAG,CAAC,cAAc,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,CAC/B,CAAC;IACzB,MAAM,EAAE,CAAC,IAAI,GAAG,CAAC,iBAAiB,EAAE,IAAI,CAAC,EAAE,UAAU,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAC5E,kEAAkE;IAClE,MAAM,MAAM,CAAC,IAAI,CAAC,UAAU,EAAE,WAAW,CAAC,EAAE,IAAI,CAAC,UAAU,EAAE,YAAY,CAAC,CAAC,CAAC;IAC5E,MAAM,SAAS,CACb,IAAI,CAAC,UAAU,EAAE,cAAc,CAAC,EAChC,GAAG,IAAI,CAAC,SAAS,CACf;QACE,OAAO,EAAE,IAAI;QACb,IAAI,EAAE,QAAQ;QACd,YAAY,EAAE,EAAE,kBAAkB,EAAE,OAAO,EAAE;KAC9C,EACD,IAAI,EACJ,CAAC,CACF,IAAI,CACN,CAAC;IACF,OAAO,EAAE,UAAU,EAAE,OAAO,EAAE,CAAC;AACjC,CAAC"}
+{"version":3,"file":"templates.js","sourceRoot":"","sources":["../../src/system/templates.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,EAAE,EACF,KAAK,EACL,KAAK,EACL,QAAQ,EACR,QAAQ,EACR,MAAM,EACN,OAAO,EACP,SAAS,GACV,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEvE,mFAAmF;AACnF,MAAM,IAAI,GAAG,IAAI,GAAG,CAAC,QAAQ,EAAE,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC;AAEhD,2FAA2F;AAC3F,MAAM,QAAQ,GAAG,IAAI,CAAC,SAAS,EAAE,QAAQ,EAAE,OAAO,CAAC,CAAC;AAEpD,KAAK,UAAU,MAAM,CAAC,IAAY;IAChC,OAAO,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,CACrB,GAAG,EAAE,CAAC,IAAI,EACV,CAAC,KAA4B,EAAE,EAAE;QAC/B,IAAI,KAAK,CAAC,IAAI,KAAK,QAAQ;YAAE,OAAO,KAAK,CAAC;QAC1C,MAAM,KAAK,CAAC;IACd,CAAC,CACF,CAAC;AACJ,CAAC;AAED;;;GAGG;AACH,KAAK,UAAU,QAAQ,CAAC,IAAY,EAAE,KAAK,GAAG,CAAC;IAC7C,IAAI,KAAK,GAAG,EAAE;QAAE,MAAM,IAAI,KAAK,CAAC,gCAAgC,IAAI,EAAE,CAAC,CAAC;IACxE,MAAM,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7B,MAAM,IAAI,GACR,MAAM,KAAK,IAAI;QACb,CAAC,CAAC,IAAI;QACN,CAAC,CAAC,IAAI,CAAC,MAAM,QAAQ,CAAC,MAAM,EAAE,KAAK,CAAC,EAAE,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC;IAC1D,MAAM,KAAK,GAAG,MAAM,KAAK,CAAC,IAAI,CAAC,CAAC,KAAK,CAAC,CAAC,KAA4B,EAAE,EAAE;QACrE,IAAI,KAAK,CAAC,IAAI,KAAK,QAAQ;YAAE,OAAO,SAAS,CAAC;QAC9C,MAAM,KAAK,CAAC;IACd,CAAC,CAAC,CAAC;IACH,IAAI,CAAC,KAAK,EAAE,cAAc,EAAE;QAAE,OAAO,IAAI,CAAC;IAC1C,OAAO,QAAQ,CAAC,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,MAAM,QAAQ,CAAC,IAAI,CAAC,CAAC,EAAE,KAAK,GAAG,CAAC,CAAC,CAAC;AAC3E,CAAC;AAED;;;;;;GAMG;AACH,KAAK,UAAU,WAAW,CAAC,GAAW;IAIpC,MAAM,MAAM,GAAG,MAAM,QAAQ,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,SAAS,EAAE,QAAQ,CAAC,CAAC,CAAC;IACvE,MAAM,MAAM,GAAG,MAAM,QAAQ,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,SAAS,EAAE,QAAQ,CAAC,CAAC,CAAC;IACvE,MAAM,KAAK,GAAG,EAAE,IAAI,EAAE,IAAI,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,KAAK,EAAE,IAAI,CAAC,GAAG,EAAE,QAAQ,CAAC,EAAE,CAAC;IAC1E,IAAI,MAAM,KAAK,MAAM;QAAE,OAAO,EAAE,KAAK,EAAE,CAAC;IACxC,OAAO;QACL,KAAK;QACL,IAAI,EAAE;YACJ,IAAI,EAAE,IAAI,CAAC,MAAM,EAAE,OAAO,CAAC;YAC3B,MAAM,EAAE,QAAQ,CAAC,MAAM,EAAE,KAAK,CAAC,IAAI,CAAC;YACpC,KAAK,EAAE,IAAI,CAAC,GAAG,EAAE,SAAS,EAAE,QAAQ,EAAE,OAAO,CAAC;SAC/C;KACF,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,mBAAmB,CACvC,GAAW;IAEX,MAAM,UAAU,GAAG,IAAI,CAAC,GAAG,EAAE,UAAU,CAAC,CAAC;IACzC,oDAAoD;IACpD,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,GAAG,MAAM,WAAW,CAAC,GAAG,CAAC,CAAC;IAC/C,KAAK,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;QAC5D,IAAI,MAAM,MAAM,CAAC,IAAI,CAAC;YAAE,MAAM,IAAI,KAAK,CAAC,GAAG,KAAK,iBAAiB,CAAC,CAAC;IACrE,IAAI,CAAC;QACH,MAAM,KAAK,CAAC,UAAU,CAAC,CAAC;IAC1B,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAK,KAA+B,CAAC,IAAI,KAAK,QAAQ;YACpD,MAAM,IAAI,KAAK,CAAC,GAAG,UAAU,iBAAiB,CAAC,CAAC;QAClD,MAAM,KAAK,CAAC;IACd,CAAC;IACD,MAAM,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC,KAAK,CAC5B,MAAM,QAAQ,CAAC,IAAI,GAAG,CAAC,cAAc,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,CAC/B,CAAC;IACzB,MAAM,EAAE,CAAC,IAAI,GAAG,CAAC,iBAAiB,EAAE,IAAI,CAAC,EAAE,UAAU,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAC5E,kEAAkE;IAClE,MAAM,MAAM,CAAC,IAAI,CAAC,UAAU,EAAE,WAAW,CAAC,EAAE,IAAI,CAAC,UAAU,EAAE,YAAY,CAAC,CAAC,CAAC;IAC5E,MAAM,SAAS,CACb,IAAI,CAAC,UAAU,EAAE,cAAc,CAAC,EAChC,GAAG,IAAI,CAAC,SAAS,CACf;QACE,OAAO,EAAE,IAAI;QACb,IAAI,EAAE,QAAQ;QACd,YAAY,EAAE,EAAE,kBAAkB,EAAE,OAAO,EAAE;KAC9C,EACD,IAAI,EACJ,CAAC,CACF,IAAI,CACN,CAAC;IACF,MAAM,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IACtD,MAAM,EAAE,CAAC,IAAI,GAAG,CAAC,yBAAyB,EAAE,IAAI,CAAC,EAAE,KAAK,CAAC,IAAI,EAAE;QAC7D,SAAS,EAAE,IAAI;KAChB,CAAC,CAAC;IACH,IAAI,IAAI,EAAE,CAAC;QACT,MAAM,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QACrD,4EAA4E;QAC5E,MAAM,OAAO,CAAC,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,IAAI,CAAC,CAAC;IACxC,CAAC;IACD,OAAO,EAAE,UAAU,EAAE,OAAO,EAAE,CAAC;AACjC,CAAC"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@clemrig/factory",
-  "version": "0.2.1",
-  "description": "Write agent workflows in TypeScript inside any repository, run them in the terminal and watch them in a local dashboard",
+  "version": "0.4.0",
+  "description": "Take a repository's issues from spec to pull request with agents, watch them on a local Kanban, and run the repository's own workflows",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -22,6 +22,7 @@
   },
   "files": [
     "dist",
+    "prompts",
     "templates"
   ],
   "engines": {
@@ -38,7 +39,8 @@
     "prepack": "npm run build"
   },
   "dependencies": {
-    "@clemrig/flow": "0.2.0",
-    "@clemrig/flow-ui": "0.1.1"
+    "@clemrig/factory-ui": "0.1.0",
+    "@clemrig/flow": "0.4.0",
+    "@clemrig/flow-ui": "0.2.0"
   }
 }

package/prompts/implement/implement.md

@@ -0,0 +1,21 @@
+You implement an approved plan in this repository.
+
+First read the repository's agent instructions: `AGENTS.md` at the root and in each directory you touch.
+Follow their conventions and validation guidance. Ignore `.factory/` and never change it.
+
+The request gives the spec, approved and unchanging, and the plan. Implement the plan, tests included, and run
+the relevant checks yourself before answering.
+
+Never commit, switch branches or push: the run commits, pushes and opens the pull request itself, and it stops
+if you commit or switch branches.
+
+When the request contains `feedback`, it reports what failed after your previous answer, a check or the
+review: fix that, then answer again.
+
+Answer with:
+
+- `summary`: what you changed, in a few sentences.
+- `criteria`: each acceptance criterion once, with the evidence that it is met (tests, files).
+- `deviations`: where you departed from the plan and why; empty if nowhere.
+
+Write in English.

package/prompts/implement/plan.md

@@ -0,0 +1,20 @@
+You plan the implementation of an approved spec in this repository. You change nothing.
+
+Before planning, read the repository's agent instructions: `AGENTS.md` at the root and in each directory the
+change will touch, and follow them. Ignore `.factory/`: the other issues there are history, not the current
+truth, and `.factory/runs/` holds agents' outputs.
+
+The request gives the issue's slug and its spec. The spec is approved and does not change: plan what it asks,
+nothing more. When something is unclear, choose the interpretation most consistent with the code and record it
+in `risks`.
+
+Answer with a plan of verifiable steps:
+
+- `summary`: the approach, in a few sentences.
+- `steps`: each names the acceptance criteria it serves (`AC1`…), the files it creates or changes, and the
+  tests that prove it. Every acceptance criterion is served by at least one step.
+- `commit`: the conventional commit subject of the whole change, for example
+  `feat(api): export watchlists as CSV`, at most 72 characters.
+- `risks`: what could go wrong and what you assumed; empty if nothing.
+
+Write in English.

package/prompts/implement/review.md

@@ -0,0 +1,17 @@
+You review a change against its approved spec, independently. You change nothing.
+
+Read the repository's agent instructions: `AGENTS.md` at the root and in the directories the change touches.
+Ignore `.factory/`: it holds other issues' history and agents' outputs, which you must not rely on.
+
+The request gives the spec, the diff of the change, and the repository's checks, which all passed. Do not take
+anything on trust: verify each acceptance criterion in the code and the tests, reading files beyond the diff
+when needed. Look for unmet criteria, defects, regressions, missing or weak tests, security problems and
+departures from the repository's conventions.
+
+Answer with:
+
+- `criteria`: each acceptance criterion once, `met` or `not_met`, with its evidence (file, test, behavior).
+- `findings`: `blocking` for an unmet criterion, a defect or a regression; `minor` for an improvement that is
+  not required. Give the file when relevant.
+
+The change is approved only when every criterion is met and no finding is blocking. Write in English.

package/templates/init/factory.ts

@@ -1,4 +1,39 @@
+import { type AgentProfile, defineFactory } from "@clemrig/factory";
 import ask from "./workflows/ask/index.ts";
 
-/** The workflows of this repository, run with `factory run <name>`. */
-export default [ask];
+const minutes = 60_000;
+const opus = {
+  runtime: "claude-code",
+  model: "claude-opus-5-5",
+  thinking: "high",
+} as const;
+const reader = {
+  ...opus,
+  tools: ["Read", "Grep", "Glob"],
+  timeoutMs: 20 * minutes,
+} satisfies AgentProfile;
+
+/**
+ * This repository's factory: `factory run issue-save` and `factory run
+ * implement --issue <slug>` take an issue from its spec to a pull request.
+ */
+export default defineFactory({
+  // The repository's checks, run in order, without a shell: before the run on
+  // the main branch, then after each implementation. Replace this example.
+  verify: [{ name: "test", command: ["npm", "test"], timeoutMs: 10 * minutes }],
+  // The budget of an implement run, in USD; --max-cost-usd changes it for one run.
+  maxCostUsd: 25,
+  profiles: {
+    plan: reader,
+    implement: {
+      ...opus,
+      tools: ["Read", "Grep", "Glob", "Edit", "Write", "Bash"],
+      // The listed tools run; anything else is refused instead of waiting for a prompt.
+      permissionMode: "dontAsk",
+      timeoutMs: 60 * minutes,
+    },
+    review: reader,
+  },
+  // This repository's own workflows, run with `factory run <name>`.
+  workflows: [ask],
+});

package/templates/init/workflows/ask/index.ts

@@ -34,7 +34,8 @@ export default defineWorkflow({
       { ok: "answer" },
     ),
     // AGENT: prompts/answer.md, with the question and the commits as context.
-    // Read-only by default: its tools can read the repository, not change it.
+    // Claude Code runs with this machine's configuration; `tools` limits it to
+    // reading the repository.
     answer: node(
       agent({
         profile: {

package/templates/skills/issue/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: issue
+description: "Create or specify a factory issue in .factory/issues/<slug>/: capture an idea as issue.md, then clarify it with the operator into a spec.md ready for factory run implement. Use when the operator wants to add an issue, write or refine a spec, or prepare work for the factory."
+---
+
+# Issue
+
+You move an issue through the first two columns of the factory's Kanban: **Backlog** (its `issue.md` exists)
+and **Specifying** (its `spec.md` exists). You never write these files yourself: `factory run issue-save` checks
+a draft and writes it at the right place. Talk with the operator in their language.
+
+## Find or create the issue
+
+Issues live in `.factory/issues/<slug>/`; read them to find the one the operator means. For a new issue,
+propose a slug (lowercase words separated by hyphens; it also names the issue's branch), a title and a short
+description of the need. Once the operator agrees, save the issue (see Save).
+
+## Specify
+
+1. Read the repository's agent instructions (`AGENTS.md` at the root and in the directories concerned) and the
+   relevant code. Change nothing.
+2. Ask the operator questions, a few at a time, until you can fill every section without inventing anything.
+   Do not ask what the code or the docs already answer. For each question, give its practical consequence
+   and your recommendation.
+3. Describe what and why, never how: the run that implements the spec plans the technical work itself.
+4. Propose the complete spec and wait for the operator's agreement, then save it (see Save).
+
+Other issues in `.factory/issues/` are history, not the current truth: rely on the code and the docs.
+
+## Format
+
+`issue.md`:
+
+```markdown
+# <Title>
+
+<Description of the need>
+```
+
+`spec.md`:
+
+```markdown
+# <Title>
+
+## Objective
+<The problem and why it matters>
+
+## Scope
+<What the change includes>
+
+## Out of scope
+<What it explicitly excludes>
+
+## Acceptance criteria
+- AC1: <A fact observable from outside>
+- AC2: <…>
+
+## Constraints
+<Limits imposed on the solution>
+```
+
+- Exactly these five sections, in this order, with nothing between the title and the first one.
+- No section is empty: write `None.` when there is nothing to say.
+- Acceptance criteria contains only `- AC<n>: <criterion>` items, numbered from AC1 without gaps; an indented
+  line continues the criterion above it. Each criterion is a fact that a user, an API client or an operator
+  can check, not an implementation detail.
+- Headings stay in English; the content may be in any language.
+
+## Save
+
+1. Write the draft to a new file outside the repository, for example in a directory created by `mktemp -d`.
+2. From the repository, run
+   `factory run issue-save --issue <slug> --kind issue --file <absolute path>` for `issue.md`, or
+   `--kind spec` for `spec.md`.
+3. `Saved .factory/issues/<slug>/<kind>.md` means it is done. Otherwise the command lists every problem: fix
+   the draft and run it again. It refuses a spec whose issue does not exist yet.
+
+## Boundaries
+
+Never write in `.factory/issues/` directly, never commit, and never run `factory run implement`. When the spec
+is saved, tell the operator the next steps: review it, commit it and push it on the main branch, then run
+`factory run implement --issue <slug>`.