@refactco/refact-os 1.5.0

package/lib/scaffold.js

@@ -0,0 +1,329 @@
+const crypto = require("crypto");
+const fs = require("fs");
+const path = require("path");
+const {
+  detectProjectType,
+  detectProjectTypes,
+  askProjectTypes,
+  normalizeProjectTypes,
+  primaryProjectType,
+  ensurePackageScripts,
+} = require("./project-utils");
+const {
+  loadConfig,
+  saveConfig,
+  configPath,
+  migrateFromAgents,
+  ensureStack,
+  getProjectTypes,
+  setAsanaProjectId,
+  askAsanaProjectId,
+  findMissingFields,
+} = require("./refact-config");
+const { generateAdapters } = require("./adapters");
+
+const TEMPLATE_BASE = path.resolve(__dirname, "..", "templates", "base");
+const TEMPLATE_OVERLAYS = path.resolve(__dirname, "..", "templates", "overlays");
+const PKG_VERSION = require("../package.json").version;
+
+// Names of the skills a given template tree (base or an overlay) ships. Used to
+// build the "shipped skills" manifest recorded in .refact-os.json, which is what
+// lets a later update prune skills the package has since removed or renamed —
+// without ever touching skills the user authored (those are never in the list).
+function listTemplateSkills(templateRoot) {
+  const dir = path.join(templateRoot, "agent", "skills");
+  if (!fs.existsSync(dir)) return [];
+  return fs
+    .readdirSync(dir, { withFileTypes: true })
+    .filter((e) => e.isDirectory() && fs.existsSync(path.join(dir, e.name, "SKILL.md")))
+    .map((e) => e.name);
+}
+
+// Project types that always carry a codebase — they pull in the `code` overlay
+// (code-development, add-codebase) automatically. A plain `blank` repo opts in
+// with `--overlay code` only if it's actually a codebase.
+const CODE_TYPES = ["wordpress", "nextjs"];
+
+// Files the user owns: created when missing, never overwritten on upgrade.
+function isSkipIfExists(relDest) {
+  if (relDest === "agent/AGENTS.md" || relDest === "agent/CLAUDE.md") return true;
+  // Root AGENTS.md / CLAUDE.md: written when absent (greenfield gets the thin
+  // pointer), but never overwritten — an existing repo may already have a real
+  // root AGENTS.md (its own contract), and force-writing the pointer over it
+  // destroys content. Same treatment as agent/AGENTS.md and README.md.
+  if (relDest === "AGENTS.md" || relDest === "CLAUDE.md") return true;
+  if (relDest === "README.md" || relDest === ".env.example") return true;
+  if (relDest === "wp-cli.yml.example") return true;
+  if (relDest.startsWith("docs/")) return true;
+  if (relDest.endsWith(".gitkeep")) return true;
+  return false; // canonical, package-managed (the agent/ payload + adapters)
+}
+
+function destFor(relPath) {
+  if (relPath === "env.example") return ".env.example";
+  return relPath;
+}
+
+// Copy a template tree (base or an overlay) into the target, honoring the
+// user-owned skip rules. Returns the list of destination paths written.
+function walkCopyTree(srcRoot, targetRoot, force, skip) {
+  const copied = [];
+  function rec(dir) {
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+      const abs = path.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        rec(abs);
+        continue;
+      }
+      const rel = path.relative(srcRoot, abs).split(path.sep).join("/");
+      if (rel === "gitignore") continue; // handled by ensureGitignoreEntries
+      if (typeof skip === "function" && skip(rel)) continue;
+      const dest = destFor(rel);
+      const writeForce = isSkipIfExists(dest) ? false : force;
+      const target = path.join(targetRoot, dest);
+      if (!writeForce && fs.existsSync(target)) continue;
+      fs.mkdirSync(path.dirname(target), { recursive: true });
+      fs.copyFileSync(abs, target);
+      if (dest.startsWith("agent/hooks/")) {
+        try {
+          fs.chmodSync(target, 0o755);
+        } catch (_err) {
+          // ignore on restricted filesystems
+        }
+      }
+      copied.push(dest);
+    }
+  }
+  rec(srcRoot);
+  return copied;
+}
+
+function ensureGitignoreEntries(targetRoot) {
+  const gitignorePath = path.join(targetRoot, ".gitignore");
+  const templateContent = fs.readFileSync(path.join(TEMPLATE_BASE, "gitignore"), "utf8");
+  if (!fs.existsSync(gitignorePath)) {
+    fs.writeFileSync(gitignorePath, templateContent, "utf8");
+    return "created";
+  }
+  return "unchanged";
+}
+
+// A repo is "brownfield" if it already has its own content beyond bootstrap
+// files (README/LICENSE/package manifests) and dotfiles (.git, .github, …). On a
+// brownfield repo, init adds only the agent layer and defers structure to the
+// `adopt` skill, rather than imposing the docs/ seed and apps/ over existing dirs.
+function repoHasOwnContent(targetRoot) {
+  const BOOTSTRAP = new Set([
+    "README.md", "README", "readme.md", "Readme.md",
+    "LICENSE", "LICENSE.md", "LICENSE.txt", "license",
+    "package.json", "package-lock.json", "pnpm-lock.yaml", "yarn.lock",
+    "node_modules", "agent",
+  ]);
+  let entries;
+  try {
+    entries = fs.readdirSync(targetRoot, { withFileTypes: true });
+  } catch (_err) {
+    return false;
+  }
+  return entries.some((e) => !e.name.startsWith(".") && !BOOTSTRAP.has(e.name));
+}
+
+function ensureWordPressDirectories(targetRoot) {
+  const wpContentRoot = path.join(targetRoot, "apps", "wordpress", "wp-content");
+  fs.mkdirSync(wpContentRoot, { recursive: true });
+  for (const dir of ["plugins", "themes", "mu-plugins"]) {
+    const subdir = path.join(wpContentRoot, dir);
+    fs.mkdirSync(subdir, { recursive: true });
+    const keepFile = path.join(subdir, ".gitkeep");
+    if (!fs.existsSync(keepFile)) fs.writeFileSync(keepFile, "", "utf8");
+  }
+}
+
+function computeContractHash() {
+  const p = path.join(TEMPLATE_BASE, "agent", "AGENTS.md");
+  return crypto.createHash("sha256").update(fs.readFileSync(p)).digest("hex");
+}
+
+// agent/AGENTS.md is skipIfExists, so the user keeps their customized copy. We
+// still flag when the upstream contract template shifts so they can merge by hand.
+function trackContractChange(config) {
+  const currentHash = computeContractHash();
+  if (!config._scaffold || typeof config._scaffold !== "object") config._scaffold = {};
+  if (!config._scaffold.templateHashes || typeof config._scaffold.templateHashes !== "object") {
+    config._scaffold.templateHashes = {};
+  }
+  const storedHash = config._scaffold.templateHashes["agent/AGENTS.md"];
+  config._scaffold.templateHashes["agent/AGENTS.md"] = currentHash;
+  if (!storedHash) return { firstRun: true, changed: false };
+  return { firstRun: false, changed: storedHash !== currentHash };
+}
+
+async function scaffoldProject(targetDir, options = {}) {
+  const resolvedTarget = path.resolve(targetDir || process.cwd());
+  const interactive = Boolean(options.interactive);
+  const force = options.force !== false;
+  const hadConfig = fs.existsSync(configPath(resolvedTarget));
+
+  const config = loadConfig(resolvedTarget);
+  const agentsMigration = migrateFromAgents(resolvedTarget, config);
+
+  const optionProjectTypes = Array.isArray(options.projectTypes)
+    ? options.projectTypes
+    : options.projectTypes
+      ? [options.projectTypes]
+      : [];
+  const explicitProjectTypes = normalizeProjectTypes([...optionProjectTypes, ...(options.projectType ? [options.projectType] : [])]);
+  const configTypes = getProjectTypes(config); // derived from `stack` keys (legacy keys already migrated above)
+
+  // Resolve the type list. An explicit (`--type`) or interactive choice is
+  // AUTHORITATIVE and replaces the stack; detection is only a *suggestion* for
+  // the prompt's default, never a silent commitment — so a stray wp-content dir
+  // can't lock a repo to wordpress before the user is even asked.
+  let projectTypes;
+  let userChose = false;
+  if (explicitProjectTypes.length > 0) {
+    projectTypes = explicitProjectTypes;
+    userChose = true;
+  } else if (interactive) {
+    const suggested = configTypes.length > 0 ? configTypes : detectProjectTypes(resolvedTarget);
+    projectTypes = await askProjectTypes(suggested.length > 0 ? suggested : ["blank"]);
+    userChose = true;
+  } else if (configTypes.length > 0) {
+    projectTypes = configTypes; // non-interactive re-run on a configured repo: keep it
+  } else {
+    projectTypes = ["blank"]; // non-interactive first scaffold (e.g. a CI run): minimal default
+  }
+  if (projectTypes.length === 0) projectTypes = ["blank"];
+
+  // `stack` is the single source of truth for the type list. An authoritative
+  // choice replaces it (so picking "blank" drops a previously-detected stack);
+  // otherwise types are merged, preserving any existing entry detail.
+  ensureStack(config, projectTypes, { replace: userChose });
+  projectTypes = getProjectTypes(config);
+  const projectType = primaryProjectType(projectTypes);
+
+  const asanaConfigured = "asana" in config && config.asana && "projectId" in config.asana;
+  if (!asanaConfigured) {
+    if (interactive) {
+      const raw = await askAsanaProjectId();
+      setAsanaProjectId(config, raw);
+    } else {
+      // Asana is optional. Record an explicit null so a non-interactive setup
+      // never leaves /refact blocked on a missing key; configure it later
+      // (interactively, by editing .refact-os.json, or via `/refact sync asana`).
+      setAsanaProjectId(config, "");
+    }
+  }
+
+  // Brownfield vs greenfield. Decided once (at first init) and recorded, so a
+  // later `init`/update never suddenly imposes structure on an adopted repo.
+  // `--seed` (options.seed) forces the full scaffold and graduates a brownfield
+  // repo to it. On a brownfield repo we add ONLY the agent layer (base skills,
+  // root pointers, config, adapters) and defer the docs/ seed, apps/, and type
+  // overlays to the `adopt` skill, which reconciles them with existing dirs.
+  let brownfield;
+  if (options.seed) {
+    brownfield = false;
+  } else if (!hadConfig) {
+    brownfield = repoHasOwnContent(resolvedTarget);
+  } else {
+    brownfield = Boolean(config._scaffold && config._scaffold.brownfield);
+  }
+  if (!config._scaffold || typeof config._scaffold !== "object") config._scaffold = {};
+  config._scaffold.brownfield = brownfield;
+
+  // On a brownfield repo, skip the substrate seed (docs/) and convention files
+  // (.env.example) — they're not core agent payload, and an existing repo likely
+  // has its own env/docs conventions. `adopt` adds what's actually needed.
+  const brownfieldSkip = (rel) => rel.startsWith("docs/") || rel === "env.example";
+  const copied = walkCopyTree(TEMPLATE_BASE, resolvedTarget, force, brownfield ? brownfieldSkip : null);
+  // Track which skills the package ships THIS run (base + any applied overlays).
+  // Recorded as the shipped-skills manifest so a later update can prune cleanly.
+  const shippedSkills = new Set(listTemplateSkills(TEMPLATE_BASE));
+  // Overlays add only what a project genuinely needs. Sources:
+  //  - one per project type in the stack (wordpress, nextjs) — greenfield only
+  //  - `code` auto-applied when the stack has a code-bearing type — greenfield only
+  //  - any explicit `--overlay <name>` (e.g. code, client) — applies ALWAYS, so an
+  //    adopted (brownfield) repo can opt into a skill-pack on request.
+  const overlayNames = new Set();
+  if (!brownfield) {
+    for (const type of projectTypes) {
+      if (type !== "blank") overlayNames.add(type);
+    }
+    if (projectTypes.some((t) => CODE_TYPES.includes(t))) overlayNames.add("code");
+  }
+  for (const name of Array.isArray(options.overlays) ? options.overlays : []) {
+    const n = String(name || "").trim().toLowerCase();
+    if (n) overlayNames.add(n);
+  }
+  // On a brownfield repo, copy only the overlay's agent/ payload (skills/hooks/
+  // scripts) — never its convention/structure files (e.g. wp-cli.yml.example),
+  // same as the base seed. Greenfield gets the whole overlay.
+  const overlaySkip = brownfield ? (rel) => !rel.startsWith("agent/") : null;
+  for (const name of overlayNames) {
+    const overlayDir = path.join(TEMPLATE_OVERLAYS, name);
+    if (fs.existsSync(overlayDir)) {
+      copied.push(...walkCopyTree(overlayDir, resolvedTarget, force, overlaySkip));
+      for (const s of listTemplateSkills(overlayDir)) shippedSkills.add(s);
+    }
+  }
+
+  // Safe prune: a skill the package shipped on a previous run but no longer ships
+  // (removed or renamed upstream) is deleted from the consumer's canonical
+  // agent/skills/. Only previously-shipped skills are eligible — user-authored
+  // skills are never in the manifest, so they're never touched. (Adapters are
+  // regenerated below, so the stale wrapper disappears too.)
+  const prevShipped = Array.isArray(config._scaffold && config._scaffold.shippedSkills)
+    ? config._scaffold.shippedSkills
+    : [];
+  const prevVersion = config._scaffold && config._scaffold.version ? config._scaffold.version : null;
+  const prunedSkills = [];
+  for (const name of prevShipped) {
+    if (shippedSkills.has(name)) continue;
+    const skillDir = path.join(resolvedTarget, "agent", "skills", name);
+    if (fs.existsSync(skillDir)) {
+      fs.rmSync(skillDir, { recursive: true, force: true });
+      prunedSkills.push(name);
+    }
+  }
+  config._scaffold.version = PKG_VERSION;
+  config._scaffold.shippedSkills = [...shippedSkills].sort();
+
+  const contract = trackContractChange(config);
+  const adapters = generateAdapters(resolvedTarget, { tools: options.tools });
+
+  if (!brownfield && projectTypes.includes("wordpress")) {
+    ensureWordPressDirectories(resolvedTarget);
+  }
+  if (!brownfield) {
+    fs.mkdirSync(path.join(resolvedTarget, "apps"), { recursive: true });
+  }
+  const gitignoreStatus = ensureGitignoreEntries(resolvedTarget);
+
+  const configPathWritten = saveConfig(resolvedTarget, config);
+  const missingFields = findMissingFields(config);
+  const packageStatus = ensurePackageScripts(resolvedTarget);
+
+  return {
+    target: resolvedTarget,
+    projectType,
+    projectTypes,
+    brownfield,
+    version: PKG_VERSION,
+    prevVersion,
+    prunedSkills,
+    filesWritten: copied.length,
+    adapters,
+    configPath: configPathWritten,
+    missingFields: missingFields.map((f) => f.path),
+    agentsMigration,
+    packageStatus,
+    gitignoreStatus,
+    contractChanged: contract.changed,
+  };
+}
+
+module.exports = {
+  detectProjectType,
+  scaffoldProject,
+};

package/lib/validate.js

@@ -0,0 +1,145 @@
+const fs = require("fs");
+const path = require("path");
+const { listSkills, INDEX_THRESHOLD, readSkillIndex, skillFrontmatterSlice } = require("./adapters");
+const { parseFrontmatter } = require("./frontmatter");
+
+// The universal base. docs/deliverables/ is intentionally NOT here — it's
+// earned/added by the `client` overlay, since internal/ops/research repos
+// never ship external deliverables.
+const REQUIRED_DIRS = [
+  "agent",
+  "agent/skills",
+  "docs",
+  "docs/sources/raw",
+  "docs/context",
+  "docs/task",
+];
+
+const REQUIRED_FILES = ["agent/AGENTS.md", "docs/index.md", "docs/decisions.md"];
+
+const FORBIDDEN_DIRS = ["agent/workflows", "agent/evals"];
+
+const REQUIRED_SKILL_FIELDS = ["name", "description", "when_to_use", "pattern"];
+const VALID_PATTERNS = ["procedure", "orchestrator", "review"];
+// Description-length warn bounds. The spec's sweet spot is ~100–200 chars; we
+// only warn on egregious outliers (a near-empty description, or a paragraph
+// that belongs in the body) so the signal stays trustworthy.
+const DESC_MIN = 40;
+const DESC_MAX = 300;
+
+function validateRepo(targetRoot) {
+  const errors = [];
+  const warnings = [];
+
+  for (const dir of REQUIRED_DIRS) {
+    if (!fs.existsSync(path.join(targetRoot, dir))) errors.push(`Missing required directory: ${dir}/`);
+  }
+  for (const file of REQUIRED_FILES) {
+    if (!fs.existsSync(path.join(targetRoot, file))) errors.push(`Missing required file: ${file}`);
+  }
+  for (const dir of FORBIDDEN_DIRS) {
+    if (fs.existsSync(path.join(targetRoot, dir))) {
+      errors.push(`Forbidden folder ${dir}/ — move its contents into agent/skills/<name>/SKILL.md (orchestrator/review pattern).`);
+    }
+  }
+
+  const skills = listSkills(targetRoot);
+  if (skills.length === 0 && fs.existsSync(path.join(targetRoot, "agent", "skills"))) {
+    warnings.push("agent/skills/ has no skills with a SKILL.md.");
+  }
+
+  const skillNames = new Set(skills);
+  for (const name of skills) {
+    const skillPath = path.join(targetRoot, "agent", "skills", name, "SKILL.md");
+    const fm = parseFrontmatter(fs.readFileSync(skillPath, "utf8"));
+    if (!fm) {
+      errors.push(`${name}: SKILL.md has no YAML frontmatter.`);
+      continue;
+    }
+    for (const field of REQUIRED_SKILL_FIELDS) {
+      if (!fm[field] || (Array.isArray(fm[field]) && fm[field].length === 0)) {
+        errors.push(`${name}: missing required frontmatter field "${field}".`);
+      }
+    }
+    if (fm.name && fm.name !== name) {
+      warnings.push(`${name}: frontmatter name "${fm.name}" does not match folder "${name}".`);
+    }
+
+    // Pattern contract (orchestrator | procedure | review).
+    if (fm.pattern && !VALID_PATTERNS.includes(fm.pattern)) {
+      errors.push(`${name}: invalid pattern "${fm.pattern}" — must be one of ${VALID_PATTERNS.join(", ")}.`);
+    }
+    const nextSkills = fm.next_skills || [];
+    const subAgents = fm.sub_agents || [];
+    if (fm.pattern === "orchestrator" && nextSkills.length === 0 && subAgents.length === 0) {
+      errors.push(`${name}: orchestrator pattern must reference at least one other skill via next_skills or sub_agents.`);
+    }
+    if (fm.pattern === "review" && nextSkills.length > 0) {
+      warnings.push(`${name}: review pattern usually declares next_skills: [] (it judges rather than chains).`);
+    }
+
+    // requires_approval is optional but must be boolean when present.
+    if ("requires_approval" in fm && !["true", "false"].includes(String(fm.requires_approval))) {
+      errors.push(`${name}: requires_approval must be true or false (got "${fm.requires_approval}").`);
+    }
+
+    // Resolver-slice quality (warn-level). These fields are read at selection
+    // time, so keep them present and tight; noise here trains people to ignore
+    // warnings, hence the deliberately lenient bounds.
+    if (!("next_skills" in fm)) {
+      warnings.push(`${name}: no next_skills key — declare next_skills: [] explicitly so a terminal chain reads as intentional, not forgotten.`);
+    }
+    if (fm.description) {
+      const len = String(fm.description).length;
+      if (len < DESC_MIN) {
+        warnings.push(`${name}: description is very short (${len} chars) — it should convey the trigger, not just restate the name.`);
+      } else if (len > DESC_MAX) {
+        warnings.push(`${name}: description is ${len} chars — aim for the ~100–200 sweet spot; move detail into when_to_use or the body (it's read at every skill selection).`);
+      }
+    }
+
+    for (const ref of nextSkills) {
+      if (ref && !skillNames.has(ref)) {
+        errors.push(`${name}: next_skills references "${ref}" which does not exist.`);
+      }
+    }
+    for (const ref of subAgents) {
+      if (ref && !skillNames.has(ref)) {
+        warnings.push(`${name}: sub_agents references "${ref}" which is not a local skill.`);
+      }
+    }
+  }
+
+  // Derived skill index (large catalogs): if present, it must match the skills
+  // on disk and the catalog must actually be over the threshold.
+  const index = readSkillIndex(targetRoot);
+  if (index) {
+    if (index._invalid) {
+      errors.push("agent/skills/.index.json is not valid JSON. Run `npm run refact:sync`.");
+    } else {
+      // Full-slice compare, not just names: a changed when_to_use / when_not_to_use /
+      // next_skills with no re-sync is real resolver drift the agent would act on.
+      const expected = skills.map((n) => skillFrontmatterSlice(targetRoot, n));
+      const indexed = index.skills || [];
+      if (JSON.stringify(indexed) !== JSON.stringify(expected)) {
+        errors.push("Skill index drift: agent/skills/.index.json does not match agent/skills/ frontmatter. Run `npm run refact:sync`.");
+      }
+    }
+  } else if (skills.length >= INDEX_THRESHOLD) {
+    warnings.push(`agent/skills/ has ${skills.length} skills (>= ${INDEX_THRESHOLD}) but no generated index. Run \`npm run refact:sync\` to build one.`);
+  }
+
+  // Adapters in sync: every canonical skill should have a generated .cursor wrapper.
+  const cursorSkills = path.join(targetRoot, ".cursor", "skills");
+  if (fs.existsSync(cursorSkills)) {
+    for (const name of skills) {
+      if (!fs.existsSync(path.join(cursorSkills, name, "SKILL.md"))) {
+        warnings.push(`Adapter drift: .cursor/skills/${name}/ missing. Run \`npm run refact:sync\`.`);
+      }
+    }
+  }
+
+  return { ok: errors.length === 0, errors, warnings, skillCount: skills.length };
+}
+
+module.exports = { validateRepo, parseFrontmatter };

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@refactco/refact-os",
+  "version": "1.5.0",
+  "description": "Installable scaffolder for the agent-first repo standard: minimum-seed substrate + canonical agent/ skill catalog with generated tool adapters",
+  "keywords": [
+    "agent",
+    "agents",
+    "agents-md",
+    "agent-first",
+    "scaffolder",
+    "ai",
+    "claude-code",
+    "cursor",
+    "skills",
+    "developer-tools"
+  ],
+  "license": "MIT",
+  "author": "Refact (https://refact.co)",
+  "homepage": "https://github.com/refactco/refact-os#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/refactco/refact-os.git"
+  },
+  "bugs": {
+    "url": "https://github.com/refactco/refact-os/issues"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "files": [
+    "bin",
+    "lib",
+    "templates",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "bin": {
+    "refact-os": "bin/refact-os.js"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "init": "node ./bin/refact-os.js init"
+  }
+}

package/templates/base/AGENTS.md

@@ -0,0 +1,9 @@
+# AGENTS.md
+
+> Thin pointer. The canonical contract for this engagement is [`agent/AGENTS.md`](agent/AGENTS.md).
+
+- **Contract** (stack, hard rules, growth triggers): [`agent/AGENTS.md`](agent/AGENTS.md)
+- **Project index** (where everything lives): [`docs/index.md`](docs/index.md)
+- **Available moves** (skills): read each `SKILL.md` frontmatter under [`agent/skills/`](agent/skills/)
+
+`.cursor/` and `.claude/` are generated from `agent/` — never edit them by hand.

package/templates/base/CLAUDE.md

@@ -0,0 +1,3 @@
+# CLAUDE.md
+
+> Thin pointer. See [`agent/CLAUDE.md`](agent/CLAUDE.md) and the canonical contract [`agent/AGENTS.md`](agent/AGENTS.md).

package/templates/base/README.md

@@ -0,0 +1,54 @@
+# <TODO: project name>
+
+> <TODO: one-line description of this engagement.>
+
+A Refact engagement scaffolded by [`refact-os`](https://github.com/refactco/refact-os). The entry point for agents is [`agent/AGENTS.md`](agent/AGENTS.md); the project map is [`docs/index.md`](docs/index.md).
+
+## Quickstart
+
+```bash
+npm install
+cp .env.example .env       # fill in per-user tokens
+```
+
+## Where things live
+
+| Path | What's in it |
+|---|---|
+| `agent/` | Canonical agent contract, skills, hooks, scripts. `.cursor/` and `.claude/` are generated from here. |
+| `docs/sources/raw/` | Evidence — inbound material as received (email, transcripts, agent chats). |
+| `docs/context/`, `docs/decisions.md` | Knowledge — curated truth, decisions, open questions, learnings. |
+| `docs/task/` | Task — tickets (`open/`, `closed/`). |
+| `docs/deliverables/` | Output — reviewed, ready-to-share artifacts. |
+| `apps/` | Product code, tracked as part of this engagement. |
+| `.refact-os.json` | Scaffold metadata: project `stack` (types, hosting, runtime, per-env deploy config) and Asana project ID. |
+
+## Common commands
+
+In Cursor / Claude Code, via the `refact` skill:
+
+- `/refact init` — post-scaffold checklist: complete `.refact-os.json` (stack types, hosting, runtime, environments), create `.env`, set up git, etc.
+- `/refact process docs` — walk new files under `docs/sources/raw/`, update `docs/context/`, mark them processed.
+- `/refact status` — show what's unprocessed and which decisions are open.
+- `/refact get chat history` — sync agent chats into `docs/sources/raw/agent-transcripts/`.
+- `/refact sync asana` — pull Asana tickets into `docs/task/`.
+- `/refact update the package` — bump or reinstall `refact-os` itself.
+
+In the shell:
+
+```bash
+npm run refact:sync        # regenerate .cursor/ and .claude/ from agent/
+npm run refact:validate    # check structure + skill frontmatter
+npm run refact:update      # re-pull the refact-os package payload
+npm run chats:import       # import agent chat history
+npm run asana:sync         # sync Asana tickets
+```
+
+> `refact:*` are backed by the `refact-os` devDependency. If one reports `command not found`, run `npm install` once; for subcommands without an alias use `npx refact-os <cmd>` (e.g. `npx refact-os sync company`).
+
+## Conventions
+
+- Decisions go in `docs/decisions.md` with the source data they were based on.
+- Pending decisions go in `docs/context/open-decisions.md` with a responsible person.
+- Per-user secrets live in `.env` (gitignored). Template: `.env.example`.
+- Never edit `.cursor/` or `.claude/` by hand — change `agent/` and run `npm run refact:sync`.

package/templates/base/agent/AGENTS.md

@@ -0,0 +1,60 @@
+# AGENTS.md
+
+> The canonical contract for this engagement. Map, not a manual — if you need detail, follow the link or load the relevant skill.
+>
+> Stack, hosting, and per-environment deploy config live in `.refact-os.json` — run `/refact init` to fill them in.
+
+## What this is
+
+A Refact engagement scaffolded by `refact-os`. This file is the shared agent contract; `docs/` is the substrate (evidence, knowledge, task, output) and `agent/skills/` is the move set. Tool-native folders (`.cursor/`, `.claude/`) are **generated** from this `agent/` directory — never edit them by hand.
+
+## Where to find what
+
+| You need… | Go to |
+|---|---|
+| The project index / canonical record | `docs/index.md` |
+| Inbound material as received (evidence) | `docs/sources/raw/` |
+| Curated truth (knowledge) | `docs/context/`, `docs/decisions.md` |
+| Company context (brand, team, pitch) | `docs/context/company/` — synced from `refact-operation` via `npx refact-os sync company`; do not edit here |
+| In-progress work (tickets) | `docs/task/` (`open/`, `closed/` emerge as tickets accumulate) |
+| Shipped artifacts | `docs/deliverables/` — present only on client-facing engagements (`client` overlay) |
+| Product code | `apps/` — present only when the repo has code (`code` overlay) |
+| Stack, hosting & per-env deploy config | `.refact-os.json` — keyed by project type (the keys are the type list); each holds `hosting`, `runtime`, and `environments` |
+| What moves the agent can make | `agent/skills/` (read each `SKILL.md` frontmatter) |
+
+## Hard rules (never)
+
+1. Never commit secrets — `.env` is gitignored; per-user tokens stay there.
+2. Never disable auth/capability/sanitization to "make it work".
+3. Never push directly to `main` or force-push to `main`; confirm QA approved on staging before any production promotion.
+4. Never record a finalized decision in `docs/decisions.md` without the source data it was based on (see the file's entry format).
+5. Never edit generated tool folders (`.cursor/`, `.claude/`) by hand — change `agent/` and re-run `npm run refact:sync`.
+6. Always default to the most agentic-first path: the right answer to "how do I do this?" is to connect to the service and do it yourself, not to hand work back to a human. When blocked by missing access, never stop at "I can't" — give the human the exact steps to grant it (which CLI to authenticate, which token/scope to set, which integration to connect) and proceed once granted. Solutions that need human intervention are less favorable than ones you can run end-to-end. Where a self-service path carries real risk, add the check-and-balance instead of stopping (surface the diff for sign-off, gate risky writes, treat untrusted sources cautiously).
+
+## Structure growth (the agent owns this past the seed)
+
+The seed is small and fixed. Grow it as content earns it:
+
+- New inbound material → invoke `ingest-input` (saves to `docs/sources/raw/`).
+- First ticket → `docs/task/open/<yyyy-mm-dd>-<slug>.md`.
+- First draft of an artifact → `docs/internal/<type>/<slug>.md` (create `internal/` on the fly).
+- Draft approved → promote it to `docs/deliverables/` and flip `status: sent` (the `create-deliverable` skill, from the `client` overlay, does this).
+- Canonical truth worth pinning down → create the canonical record file and link it from `docs/index.md`.
+- `docs/decisions.md` gets painful to scan → split by date range (`docs/decisions/2026-Q1.md`), not by topic.
+- Same move executed a **third** time → capture it as a skill under `agent/skills/<verb-object>/` (set `pattern:`), then run `npm run refact:sync`. (The second time, just note it — you don't yet know which variations matter.)
+- Writing that skill → make it *process, not content* (read project facts from `docs/`, don't bake them in); put any counting/scanning/parsing in a `scripts/` helper the skill runs, so the model interprets results rather than enumerating by hand; and declare the full resolver frontmatter (`when_to_use`, `when_not_to_use`, `next_skills` — `[]` if terminal). Reach for a script the skill calls, not a new always-on tool.
+
+## Branches & PRs
+
+- Branches: `feat/<ticket>-<slug>`, `fix/<ticket>-<slug>`, `chore/<slug>`.
+- PR titles: Conventional Commits. On repos with code, changes go through the `code-development` skill (`code` overlay).
+
+## Tooling (`refact-os`)
+
+- `npm run refact:sync` (regenerate `.cursor/`/`.claude/` from `agent/`), `npm run refact:validate` (check structure + skill frontmatter), `npm run refact:update` (re-pull the package payload). These are npm scripts backed by the `refact-os` devDependency.
+- If a script errors with `refact-os: command not found` (or `Missing script`), the package isn't installed yet — run `npm install` once, then retry. To run a subcommand without a script alias (e.g. `sync company`), use `npx refact-os sync company`.
+
+## When unsure
+
+- Ask one focused clarifying question instead of guessing on scope, naming, or role.
+- For decisions affecting client data or billing: stop, log it in `docs/context/open-decisions.md` with a responsible person, and wait for sign-off.

package/templates/base/agent/CLAUDE.md

@@ -0,0 +1,7 @@
+# CLAUDE.md
+
+Claude Code entry point for this engagement. The canonical contract is [AGENTS.md](./AGENTS.md) in this same folder — read it first.
+
+Skills live in `agent/skills/` (canonical) and are mirrored into `.claude/skills/` (generated). Discover available moves by reading each `SKILL.md`'s frontmatter; load a body only when you select that skill.
+
+Do not edit `.claude/` or `.cursor/` by hand — they are generated from `agent/`. Change `agent/` and run `npm run refact:sync`.