@clemrig/factory 0.3.0 → 0.4.0

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":"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"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@clemrig/factory",
-  "version": "0.3.0",
-  "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.3.0",
-    "@clemrig/flow-ui": "0.1.2"
+    "@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/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>`.