@stonepandastudio/cairn 0.4.2 → 0.5.0

package/README.md

@@ -3,8 +3,9 @@
 Shared AI workflow scaffolding, kept in sync across several repos.
 
 Each repo carries an `ai/` folder and a `.claude/commands/` folder holding the same
-workflow — brief → description → plan → execute → review → QA, with the steps
-mirrored into an issue tracker. Copied between repos by hand, they drift.
+workflow — brief → description → plan → execute → review, with the steps optionally
+mirrored into an issue tracker. Hand-copied between repos, they drift. cairn renders
+them from one set of presets and reports where existing copies disagree.
 
 A cairn is a stack of stones left to mark a trail. That is what this does: it leaves
 markers — a manifest of what it generated, and a report of where the copies stopped
@@ -15,33 +16,40 @@ npm i -D @stonepandastudio/cairn
 npx cairn init --stack nestjs,typeorm --tracker jira-server --project-key MYPROJ --story-type Task
 ```
 
-## What v1 does
+## What it does
 
 | Command | |
 |---|---|
 | `cairn tracker <cmd>` | Issue tracker client (`jira-server` / `youtrack` / `none`). Replaces the copied `ai/scripts/*.js` clients |
 | `cairn doctor` | Cross-repo drift report, plus per-repo generated-file state |
 | `cairn init` | Makes a repo cairn-managed: writes `cairn.config.json`, `_cairn/`, and the shim |
+| `cairn render` | Scaffolds `ai/` + `.claude/commands/` from the bundled presets, from the repo's stack + workflow |
 
-Template rendering — generating the command stubs, `WORKFLOW.md` and the agent role
-contracts from one workflow declaration — is v2, and deliberately not in this release.
-v1 swaps the tracker client under the consuming repos; bundling prompt changes into
-the same release would make any regression impossible to attribute.
+`cairn render` is **greenfield only**: it writes files that do not exist, records them
+in the manifest, and leaves anything already on disk alone (reporting it). The
+three-way merge that would re-render over local edits — `cairn sync` — is not built
+yet; for a fresh repo there is nothing to merge.
 
 ## The two folders
 
 ```
 repo/
-  cairn.config.json      you edit this. cairn only ever reads it.
-  _cairn/                cairn writes this. nobody hand-edits it.
-    manifest.json        what was generated, from which template, at which hash
-    scripts/jira.js      vendored shim
-  ai/                    project-owned. cairn never touches it.
-    contexts/  progress/  tasks/  infrastructure/
+  cairn.config.json     you edit this. cairn only ever reads it.
+  _cairn/               cairn writes this. nobody hand-edits it.
+    manifest.json       what was generated, from which template, at which hash
+    scripts/jira.js     vendored tracker shim
+  .claude/commands/     rendered from the workflow — one stub per step
+  ai/
+    agents/             rendered from presets/core + your stack's slots
+    AGENTS.md  WORKFLOW.md   rendered
+    infrastructure/code-guidelines.md   rendered once as a seed — then it is yours
+    contexts/  tasks/   yours, never written by cairn
 ```
 
-The boundary is the whole design. Hand-edited config living inside a generated
-directory is how generated directories acquire state nobody dares regenerate.
+`cairn render` seeds the rendered files once and records them in the manifest; it
+never rewrites a file you have edited (that is `cairn sync`, not built yet). The
+boundary is the whole design: hand-edited config living inside a generated directory
+is how generated directories acquire state nobody dares regenerate.
 
 Generated files are **committed**, not gitignored. Claude Code discovers
 `.claude/commands/` and agent docs from disk, and a prompt change should show up in
@@ -88,7 +96,7 @@ environment wins over the file. If the repo's own app reads those same names, se
 `create-task`, `create-story`, `close-story` and friends are all still accepted, and
 output formats are byte-for-byte what the old scripts printed. Existing prose
 references name these strings and the agents parse the output, so they are kept
-until the v2 pass regenerates those documents.
+until a render pass regenerates those documents from the presets.
 
 ## Doctor
 
@@ -124,11 +132,12 @@ match what is on disk?
 |---|---|
 | `MANAGED` | on-disk hash matches what cairn wrote |
 | `MODIFIED` | someone hand-edited a generated file |
-| `OUTDATED` | cairn has newer content for it — needs template hashes, wired in v2 |
+| `OUTDATED` | cairn has newer content for it — needs template hashes; comes with `cairn sync` |
 | `DELETED` | it is gone; a future `cairn sync` will restore it |
 
-v1 reports `MANAGED`, `MODIFIED` and `DELETED`. `OUTDATED` and the `sync` that acts
-on these states arrive with the v2 renderer.
+Today the doctor reports `MANAGED`, `MODIFIED` and `DELETED`. `OUTDATED` (needs the
+template hashes threaded through) and `cairn sync` (the three-way merge that acts on
+these states) are still to come — `cairn render` is greenfield-only for now.
 
 A file can be perfectly in sync across repos while being hand-edited away from its
 template, and vice versa. `MODIFIED` outranks `OUTDATED` in the report because
@@ -152,8 +161,8 @@ overwriting a hand edit is the destructive outcome.
   `ai/INITIAL_PROMPT.md` is explicitly excluded: variants at ~0% shared content make
   it a per-project document, not a drifted template.
 
-v2 splits this flat file into a per-project `workspace.json` plus an opt-in hub that
-references the projects for cross-project comparison. See `DESIGN.md`.
+A later release splits this flat file into a per-project `workspace.json` plus an
+opt-in hub that references the projects for cross-project comparison. See `DESIGN.md`.
 
 ## Layout
 
@@ -164,10 +173,12 @@ lib/manifest.js        generated-file hashing and state
 lib/paint.js           ANSI + table rendering
 lib/tracker/           index (registry), cli, jira-server, youtrack, none
 lib/doctor/            index (analysis + report), scan, normalize, diff
+lib/render/            engine (a small template engine), index (driver), cli
 lib/init.js            cairn init
 templates/shims/       vendored shim source
+presets/               core/ + framework/ORM/styling presets rendered by `cairn render`
 schema.json            JSON Schema for cairn.config.json
 test/run.js            dependency-free test runner
 ```
 
-No runtime dependencies. Node >= 18. `npm test` runs 56 tests.
+No runtime dependencies. Node >= 18. `npm test` runs 61 tests.

package/bin/cairn.js

@@ -19,6 +19,7 @@ Usage: cairn <command> [options]
   tracker <cmd> [...]   issue tracker client   (cairn tracker --help)
   doctor [options]      cross-repo drift report (cairn doctor --help)
   init [options]        make a repo cairn-managed (cairn init --help)
+  render [options]      scaffold ai/ from the bundled presets (cairn render --help)
   version               print version
 
 Run \`cairn <command> --help\` for command options.
@@ -40,6 +41,10 @@ function main() {
       process.exitCode = require('../lib/init').main(rest);
       return;
 
+    case 'render':
+      process.exitCode = require('../lib/render/cli').main(rest);
+      return;
+
     case 'version':
     case '--version':
     case '-v':

package/lib/init.js

@@ -58,6 +58,7 @@ Usage: cairn init [options]
                            (only when the repo's app reads JIRA_*/YOUTRACK_* itself)
   --no-shim                do not vendor or replace the ai/scripts/*.js client shims
   --force                  overwrite an existing cairn.config.json
+  --render                 also scaffold ai/ from the presets after init
   --force-shims            also replace an ai/scripts/*.js shim that was hand-edited
                            since cairn wrote it (kept untouched otherwise)
   --dry-run                print what would be written, write nothing
@@ -75,6 +76,7 @@ function parseArgs(argv) {
     shim: true,
     force: false,
     forceShims: false,
+    render: false,
     dryRun: false,
     color: process.stdout.isTTY,
   };
@@ -90,6 +92,7 @@ function parseArgs(argv) {
     else if (a === '--no-shim') args.shim = false;
     else if (a === '--force') args.force = true;
     else if (a === '--force-shims') args.forceShims = args.force = true;
+    else if (a === '--render') args.render = true;
     else if (a === '--dry-run') args.dryRun = true;
     else if (a === '--no-color') args.color = false;
     else if (a === '-h' || a === '--help') args.help = true;
@@ -233,6 +236,13 @@ function main(argv = process.argv.slice(2)) {
     console.log(paint.dim(`\n  Next: ensure .env has ${envVars.join(', ')}, then run`));
     console.log(paint.dim(`        npx cairn tracker list-statuses ${args.projectKey}`));
   }
+
+  if (args.render) {
+    console.log('');
+    require('./render/cli').renderInto(repoPath, { paint });
+  } else {
+    console.log(paint.dim(`\n  Next: \`cairn render\` to scaffold ai/ from the presets`));
+  }
   return 0;
 }
 

package/lib/render/cli.js

@@ -0,0 +1,106 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const { loadRepoConfig, findRepoRoot, ConfigError } = require('../config');
+const { readManifest, emptyManifest, record, writeManifest, manifestPath } = require('../manifest');
+const { makePaint } = require('../paint');
+const { planRender } = require('./index');
+
+const PRESETS_DIR = path.join(__dirname, '..', '..', 'presets');
+
+const HELP = `cairn render — scaffold a repo's ai/ from the bundled presets
+
+Usage: cairn render [options]
+
+  --repo <path>    repo to render into (default: the repo cairn.config.json is in)
+  --dry-run        print what would be written, write nothing
+  --no-color       disable ANSI colour
+
+Reads the repo's cairn.config.json (run \`cairn init\` first) — the stack list,
+tracker, and any agent overrides. Greenfield only: it writes files that do not
+exist and records them in the manifest; anything already on disk is left alone.
+`;
+
+function parseArgs(argv) {
+  const args = { repo: null, dryRun: false, color: process.stdout.isTTY };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--repo') args.repo = argv[++i];
+    else if (a === '--dry-run') args.dryRun = true;
+    else if (a === '--no-color') args.color = false;
+    else if (a === '-h' || a === '--help') args.help = true;
+    else {
+      console.error(`Unknown argument: ${a}`);
+      return { error: 2 };
+    }
+  }
+  return args;
+}
+
+// Shared by `cairn render` and `cairn init --render`.
+function renderInto(repoPath, { dryRun = false, paint } = {}) {
+  const config = loadRepoConfig(repoPath, { required: true });
+  const manifest = readManifest(repoPath) || emptyManifest();
+  paint = paint || makePaint(false);
+
+  const { planned, kept } = planRender({ config, presetsDir: PRESETS_DIR, manifest, repoPath });
+
+  if (dryRun) {
+    console.log(paint.bold(`cairn render --dry-run  ${repoPath}`));
+    for (const [rel, , , note] of planned) {
+      console.log(`  ${paint.green('would write')}  ${rel}${note ? paint.dim(`  (${note})`) : ''}`);
+    }
+    for (const k of kept) console.log(paint.yellow(`  would keep    ${k.rel}  (${k.reason})`));
+    if (!planned.length && !kept.length) console.log(paint.dim('  nothing to render'));
+    return 0;
+  }
+
+  let wrote = 0;
+  for (const [rel, content, source] of planned) {
+    const abs = path.join(repoPath, rel);
+    fs.mkdirSync(path.dirname(abs), { recursive: true });
+    fs.writeFileSync(abs, content, 'utf8');
+    record(manifest, rel, source, content);
+    console.log(`  ${paint.green('wrote')}  ${rel}`);
+    wrote++;
+  }
+  if (wrote) {
+    writeManifest(repoPath, manifest);
+    console.log(`  ${paint.green('wrote')}  ${path.relative(repoPath, manifestPath(repoPath)).replace(/\\/g, '/')}`);
+  }
+  for (const k of kept) console.log(paint.yellow(`  kept   ${k.rel}  (${k.reason})`));
+  if (!wrote && !kept.length) console.log(paint.dim('  nothing to render — all current'));
+  return 0;
+}
+
+function main(argv = process.argv.slice(2)) {
+  const args = parseArgs(argv);
+  if (args.error) return args.error;
+  if (args.help) {
+    process.stdout.write(HELP);
+    return 0;
+  }
+
+  const start = args.repo ? path.resolve(args.repo) : process.cwd();
+  const repoPath = args.repo ? start : findRepoRoot(start);
+  if (!repoPath || !fs.existsSync(path.join(repoPath, 'cairn.config.json'))) {
+    console.error(`No cairn.config.json found — run \`cairn init\` first`);
+    return 2;
+  }
+
+  const paint = makePaint(args.color);
+  try {
+    if (!args.dryRun) console.log(paint.bold(`cairn render  ${repoPath}`));
+    return renderInto(repoPath, { dryRun: args.dryRun, paint });
+  } catch (e) {
+    if (e instanceof ConfigError) {
+      console.error(e.message);
+      return 2;
+    }
+    throw e;
+  }
+}
+
+module.exports = { main, renderInto, HELP, PRESETS_DIR };

package/lib/render/engine.js

@@ -0,0 +1,148 @@
+'use strict';
+
+// A very small template engine — the subset of Handlebars the preset files use
+// and nothing more. Pure: no fs, no cairn knowledge. The driver in ./index.js
+// supplies the context and the `{{> stack/… }}` partial resolver.
+//
+// Supported:
+//   {{ path }}            substitution, not HTML-escaped (output is markdown)
+//   {{ this.x }}          `this` and dotted paths, plus @index / @index_1 / @first / @last inside #each
+//   {{#if path}}…{{/if}}  with optional {{else}}
+//   {{#each path}}…{{/each}}
+//   {{> stack/name }}     resolved by the caller-supplied resolvePartial(name, ctx)
+//   {{! comment }}        dropped
+//   a leading <!-- cairn preset: … --> or <!-- cairn:… --> block is dropped
+
+const TOKEN = /(\{\{!(?:(?!\}\})[\s\S])*\}\}|\{\{\{[^}]*\}\}\}|\{\{[#/>]?\s*[^}]*?\}\})/;
+
+// Drop cairn's own editorial comments — `<!-- cairn preset: … -->` /
+// `{{! … }}` — wherever they sit in a template. They document the preset for a
+// human reading `presets/` and must not reach the rendered output. Then tidy the
+// whitespace a block tag on its own line would otherwise leave behind (Mustache's
+// "standalone" rule), and collapse the runs of blank lines that removing a
+// comment block opens up.
+function stripHeaderComment(src) {
+  return String(src)
+    .replace(/^/, '')
+    .replace(/[ \t]*<!--\s*cairn[:\s][\s\S]*?-->[ \t]*\n?/g, '')
+    .replace(/^[ \t]*\{\{!(?:(?!\}\})[\s\S])*\}\}[ \t]*\r?\n/gm, '')
+    .replace(/\{\{!(?:(?!\}\})[\s\S])*\}\}/g, '')
+    .replace(/^[ \t]*(\{\{[#/][^}]*\}\}|\{\{\s*else\s*\}\})[ \t]*\r?\n/gm, '$1')
+    .replace(/\n{3,}/g, '\n\n')
+    .replace(/^\n+/, '');
+}
+
+function tokenize(src) {
+  return src
+    .split(TOKEN)
+    .filter((s) => s !== '' && s !== undefined)
+    .map((s) => {
+      const m = s.match(/^\{\{([#/>!]?)\s*([\s\S]*?)\s*\}\}$/);
+      if (!m) return { t: 'text', v: s };
+      const [, sigil, body] = m;
+      if (sigil === '!') return { t: 'comment' };
+      if (sigil === '>') return { t: 'partial', v: body.trim() };
+      if (sigil === '#') {
+        const [kw, arg] = body.split(/\s+/, 2);
+        return { t: 'open', kw, arg };
+      }
+      if (sigil === '/') return { t: 'close', kw: body.trim() };
+      if (body === 'else') return { t: 'else' };
+      return { t: 'var', v: body.trim() };
+    });
+}
+
+// Build a nested node tree from the flat token list.
+function parse(tokens) {
+  const root = { kw: 'root', body: [], else: null };
+  const stack = [root];
+  let target = 'body';
+
+  for (const tok of tokens) {
+    const top = stack[stack.length - 1];
+    const sink = target === 'else' ? top.else : top.body;
+
+    if (tok.t === 'comment') continue;
+    if (tok.t === 'text') sink.push({ t: 'text', v: tok.v });
+    else if (tok.t === 'var') sink.push({ t: 'var', v: tok.v });
+    else if (tok.t === 'partial') sink.push({ t: 'partial', v: tok.v });
+    else if (tok.t === 'open') {
+      const node = { t: 'block', kw: tok.kw, arg: tok.arg, body: [], else: [] };
+      sink.push(node);
+      stack.push(node);
+      target = 'body';
+    } else if (tok.t === 'else') {
+      target = 'else';
+    } else if (tok.t === 'close') {
+      if (stack.length < 2 || top.kw !== tok.kw) {
+        throw new Error(`template: unbalanced {{/${tok.kw}}}`);
+      }
+      stack.pop();
+      target = 'body';
+    }
+  }
+  if (stack.length !== 1) throw new Error(`template: unclosed {{#${stack[stack.length - 1].kw}}}`);
+  return root.body;
+}
+
+function lookup(ctx, path) {
+  if (path === 'this') return ctx.this;
+  if (path.startsWith('@')) return ctx['@'] ? ctx['@'][path] : undefined;
+  let cur = path.startsWith('this.') ? ctx.this : ctx;
+  for (const key of path.replace(/^this\./, '').split('.')) {
+    if (cur == null) return undefined;
+    cur = cur[key];
+  }
+  return cur;
+}
+
+function truthy(v) {
+  return Array.isArray(v) ? v.length > 0 : v !== undefined && v !== null && v !== false && v !== '';
+}
+
+function renderNodes(nodes, ctx, resolvePartial) {
+  let out = '';
+  for (const node of nodes) {
+    if (node.t === 'text') {
+      out += node.v;
+    } else if (node.t === 'var') {
+      const v = lookup(ctx, node.v);
+      out += v === undefined || v === null ? '' : String(v);
+    } else if (node.t === 'partial') {
+      const resolved = resolvePartial(node.v, ctx);
+      out += resolved == null ? '' : renderNodes(parse(tokenize(stripHeaderComment(resolved))), ctx, resolvePartial);
+    } else if (node.t === 'block' && node.kw === 'if') {
+      const branch = truthy(lookup(ctx, node.arg)) ? node.body : node.else;
+      out += renderNodes(branch, ctx, resolvePartial);
+    } else if (node.t === 'block' && node.kw === 'each') {
+      const list = lookup(ctx, node.arg);
+      if (Array.isArray(list)) {
+        list.forEach((item, i) => {
+          const child = {
+            ...ctx,
+            this: item,
+            '@': {
+              '@index': i,
+              '@index_1': i + 1,
+              '@first': i === 0,
+              '@last': i === list.length - 1,
+            },
+          };
+          out += renderNodes(node.body, child, resolvePartial);
+        });
+      } else if (node.else.length) {
+        out += renderNodes(node.else, ctx, resolvePartial);
+      }
+    }
+  }
+  return out;
+}
+
+// Render `src` against `ctx`. `resolvePartial(name, ctx)` returns the raw text for
+// a `{{> name }}` include, or null to emit nothing.
+function render(src, ctx = {}, resolvePartial = () => null) {
+  const clean = stripHeaderComment(String(src));
+  return renderNodes(parse(tokenize(clean)), ctx, resolvePartial);
+}
+
+module.exports = { render, stripHeaderComment };

package/lib/render/index.js

@@ -0,0 +1,210 @@
+'use strict';
+
+// cairn render — turn the bundled `presets/` into a repo's `ai/` scaffolding.
+//
+// Greenfield only: it writes files that do not exist, records them in the
+// manifest, and leaves anything already on disk alone (reporting it). The
+// three-way merge that would let it re-render over local edits is `cairn sync`,
+// which is not built yet — for a fresh repo there is nothing to merge.
+
+const fs = require('fs');
+const path = require('path');
+
+const { render, stripHeaderComment } = require('./engine');
+const { hashContent } = require('../manifest');
+
+const PRIMARY_ONLY_SLOTS = new Set(['plan-step-ordering', 'architect-references']);
+
+const DEFAULT_WORKFLOW = {
+  steps: [
+    { id: 'brief', fn: 'create_brief', command: 'create-brief', role: 'architect', oneLine: 'creates the task brief scaffold' },
+    { id: 'describe', fn: 'enrich_description', command: 'enrich-description', role: 'architect', oneLine: 'iterative discussion, then writes the enriched description' },
+    { id: 'plan', fn: 'plan_task', command: 'plan-task', role: 'architect', oneLine: 'produces the implementation plan and context-doc updates' },
+    { id: 'execute', fn: 'execute_plan', command: 'execute-plan', role: 'developer', oneLine: 'implements the plan' },
+    { id: 'review', fn: 'code_review', command: 'code-review', role: 'reviewer', oneLine: 'checks the result against the plan and the guidelines' },
+  ],
+};
+
+const ROLE_MODEL = { architect: 'Sonnet', developer: 'Haiku', reviewer: 'Sonnet' };
+
+function cap(s) {
+  return s ? s[0].toUpperCase() + s.slice(1) : s;
+}
+
+function trackerContext(t = {}) {
+  const provider = t.provider || 'none';
+  const remote = provider === 'jira-server' || provider === 'youtrack';
+  return {
+    provider,
+    remote,
+    providerLabel: { 'jira-server': 'Jira', youtrack: 'YouTrack', none: 'no tracker' }[provider] || provider,
+    exampleKey: t.projectKey || (remote ? 'PROJ' : 'TASK'),
+    slug: provider === 'jira-server' ? 'jira' : provider === 'youtrack' ? 'youtrack' : 'tracker',
+    subtaskMarker: provider === 'youtrack' ? 'youtrack-subtask' : 'jira-subtask',
+    reviewStage: (t.statuses && t.statuses.done) || 'Review',
+    parentTerm: remote ? 'parent issue' : 'task',
+    childTerm: remote ? 'child issue' : 'step',
+  };
+}
+
+function loadWorkflow(config, presetsDir) {
+  if (config.workflow && Array.isArray(config.workflow.steps)) return config.workflow;
+  const file = path.join(presetsDir, 'core', 'workflow.json');
+  if (fs.existsSync(file)) {
+    try {
+      return JSON.parse(fs.readFileSync(file, 'utf8'));
+    } catch {
+      /* fall through to the built-in default */
+    }
+  }
+  return DEFAULT_WORKFLOW;
+}
+
+function buildContext(config, presetsDir) {
+  const stack = config.stack && config.stack.length ? config.stack : ['unknown'];
+  const tracker = trackerContext(config.tracker);
+  const workflow = loadWorkflow(config, presetsDir);
+
+  const agents = config.agents || {};
+  const roleName = (role) =>
+    (agents[role] && agents[role].name) || `${cap(stack[0])}${cap(role)}Agent`;
+  const roleDoc = (role) => (agents[role] && agents[role].doc) || `ai/agents/${role}.md`;
+
+  workflow.steps.forEach((s) => {
+    s.agentName = roleName(s.role);
+    s.agentDoc = roleDoc(s.role);
+    s.model = ROLE_MODEL[s.role] || null;
+    s.trackerAction = tracker.remote ? s.trackerAction || 'sync — see the rows below' : 'n/a';
+    s.tracker = tracker.remote && s.role === 'architect' ? true : null;
+  });
+
+  return {
+    stack,
+    tracker,
+    workflow,
+    model: config.model || 'claude-sonnet-5',
+    architectAgent: roleName('architect'),
+    developerAgent: roleName('developer'),
+    reviewerAgent: roleName('reviewer'),
+    project: {
+      assistantName:
+        (config.vars && config.vars.assistantName) || `${cap(stack[0])} Dev Assistant`,
+    },
+    agents: ['architect', 'developer', 'reviewer'].map((r) => ({ name: roleName(r), doc: roleDoc(r) })),
+    ...(config.vars || {}),
+  };
+}
+
+function makeResolvePartial(stack, presetsDir) {
+  return (name) => {
+    const m = name.match(/^stack\/(.+)$/);
+    if (!m) return null;
+    const slot = m[1];
+    const entries = PRIMARY_ONLY_SLOTS.has(slot) ? stack.slice(0, 1) : stack;
+    const parts = [];
+    for (const entry of entries) {
+      const file = path.join(presetsDir, entry, 'slots', `${slot}.md`);
+      if (fs.existsSync(file)) parts.push(stripHeaderComment(fs.readFileSync(file, 'utf8')).trim());
+    }
+    if (!parts.length) return null;
+    // Table-row slots (every part starts with `|`) concatenate line-to-line;
+    // prose slots need a blank line between them.
+    const sep = parts.every((p) => p.startsWith('|')) ? '\n' : '\n\n';
+    return parts.join(sep);
+  };
+}
+
+function readPreset(presetsDir, rel) {
+  const file = path.join(presetsDir, rel);
+  return fs.existsSync(file) ? fs.readFileSync(file, 'utf8') : null;
+}
+
+// Concatenate `<entry>/code-guidelines.md` for every stack entry that ships one.
+function codeGuidelines(stack, presetsDir, ctx, resolvePartial) {
+  const blocks = [];
+  for (const entry of stack) {
+    const raw = readPreset(presetsDir, `${entry}/code-guidelines.md`);
+    if (raw) blocks.push(render(raw, ctx, resolvePartial).trim());
+  }
+  return blocks.length ? blocks.join('\n\n---\n\n') + '\n' : null;
+}
+
+// Returns { planned: [[rel, content, source, note?]], kept: [{ rel, reason }] }.
+// `manifest` + `repoPath` drive the greenfield guard: a file cairn has not
+// written is never touched, and one it wrote but a human has since edited is
+// kept and reported (the re-render that respects local edits is `cairn sync`).
+function planRender({ config, presetsDir, manifest = { files: {} }, repoPath = null }) {
+  const ctx = buildContext(config, presetsDir);
+  const resolvePartial = makeResolvePartial(ctx.stack, presetsDir);
+
+  const targets = [];
+
+  const stub = readPreset(presetsDir, 'core/commands/_stub.md');
+  if (stub) {
+    for (const step of ctx.workflow.steps) {
+      targets.push([
+        `.claude/commands/${step.command}.md`,
+        render(stub, { ...ctx, step }, resolvePartial),
+        'core/commands/_stub.md',
+      ]);
+    }
+  }
+
+  const stepFor = (role) => ctx.workflow.steps.find((s) => s.role === role) || {};
+  for (const role of ['architect', 'developer', 'reviewer']) {
+    const raw = readPreset(presetsDir, `core/agents/${role}.md`);
+    if (raw) {
+      targets.push([
+        `ai/agents/${role}.md`,
+        render(raw, { ...ctx, step: stepFor(role) }, resolvePartial),
+        `core/agents/${role}.md`,
+      ]);
+    }
+  }
+
+  for (const [rel, src] of [
+    ['ai/AGENTS.md', 'core/AGENTS.md'],
+    ['ai/WORKFLOW.md', 'core/WORKFLOW.md'],
+  ]) {
+    const raw = readPreset(presetsDir, src);
+    if (raw) targets.push([rel, render(raw, ctx, resolvePartial), src]);
+  }
+
+  const guidelines = codeGuidelines(ctx.stack, presetsDir, ctx, resolvePartial);
+  if (guidelines) {
+    targets.push([
+      'ai/infrastructure/code-guidelines.md',
+      guidelines,
+      'presets:<stack>/code-guidelines.md',
+      'seed — fork it, cairn will not re-render over your edits',
+    ]);
+  }
+
+  const planned = [];
+  const kept = [];
+  for (const [rel, content, source, note] of targets) {
+    const entry = manifest.files[rel];
+    const abs = repoPath ? path.join(repoPath, rel) : null;
+    const onDisk = abs && fs.existsSync(abs) ? fs.readFileSync(abs, 'utf8') : null;
+
+    if (entry && onDisk !== null && hashContent(onDisk) !== entry.hash) {
+      kept.push({ rel, reason: 'hand-edited since cairn wrote it' });
+      continue;
+    }
+    if (entry && onDisk !== null && hashContent(content) === entry.hash) continue; // current, on disk
+    if (entry && onDisk !== null) {
+      kept.push({ rel, reason: 'the template changed — `cairn sync` will merge it' });
+      continue;
+    }
+    if (!entry && onDisk !== null) {
+      kept.push({ rel, reason: 'already on disk, not written by cairn' });
+      continue;
+    }
+    // Not on disk: brand new, or a manifested file that was deleted — (re)write it.
+    planned.push([rel, content, source, entry ? 'restoring' : note]);
+  }
+
+  return { planned, kept, context: ctx };
+}
+
+module.exports = { planRender, buildContext, trackerContext, DEFAULT_WORKFLOW };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stonepandastudio/cairn",
-  "version": "0.4.2",
+  "version": "0.5.0",
   "description": "Shared AI workflow scaffolding for Stone Panda repos — issue tracker client and drift doctor.",
   "license": "UNLICENSED",
   "repository": {
@@ -24,6 +24,7 @@
     "bin/",
     "lib/",
     "templates/",
+    "presets/",
     "schema.json",
     "README.md"
   ],