create-religion 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nate
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,47 @@
+# create-religion
+
+A file-backed, spec-driven AI development workflow.
+
+```bash
+npx create-religion@latest
+```
+
+You write two planning documents. The workflow turns them into project context, work-item
+specs, and small reviewable build steps. You review every spec before code exists, and
+every diff before it lands.
+
+## What it installs
+
+- **22 skills** your AI tool can run: `feature`, `implement`, `check`, `audit`, `complete`,
+  and the rest of the loop around them.
+- **A state directory** holding your plans, the active spec, the findings ledger, and the
+  archive of everything finished.
+- **Enforcement hooks** for Claude Code, backing rules that apply to every supported tool.
+
+Works with Claude Code, Codex, GitHub Copilot, and OpenCode. Each tool's files are
+generated separately, so they carry that tool's own invocation syntax.
+
+## After installing
+
+1. Run the `setup` skill. On an existing codebase it surveys what is there and drafts your
+   plans from it.
+2. Fill in `religion/project-plan.md` and `religion/build-plan.md`.
+3. Run `overview`, then the loop: `feature`, `implement`, `check`, `complete`.
+
+## Commands
+
+```bash
+religion status      # where the work stands, and the one thing to do next
+religion doctor      # is the setup healthy
+religion dashboard   # a local read-only view
+religion update      # update the workflow files, preserving yours
+```
+
+`update` will not overwrite a file you have edited. It tells you what conflicts and backs
+up the original if you choose to replace it.
+
+## Documentation
+
+[github.com/foo-stack/religion](https://github.com/foo-stack/religion)
+
+MIT.

package/dist/bin/religion.js

@@ -0,0 +1,209 @@
+#!/usr/bin/env node
+/**
+ * The Religion command-line tool.
+ *
+ * Install and update the workflow files, and read project state. It never runs a workflow
+ * command: deciding what to build is the agent's job, and reporting what is true is this
+ * one's.
+ */
+import fs from "node:fs/promises";
+import fsSync from "node:fs";
+import path from "node:path";
+import readline from "node:readline/promises";
+import { fileURLToPath } from "node:url";
+import { startDashboard } from "../lib/dashboard.js";
+import { renderDoctor, runDoctor } from "../lib/doctor.js";
+import { ADAPTERS, applyInstall, planInstall, readManifest, wireHooks, writeManifest } from "../lib/install.js";
+import { findProjectRoot, STATE_DIR } from "../lib/paths.js";
+import { readProjectState } from "../lib/state.js";
+import { computeStatus, renderStatus } from "../lib/status.js";
+const here = path.dirname(fileURLToPath(import.meta.url));
+/**
+ * Finds the installed package root by walking up for the template.
+ *
+ * The depth differs between running from source and running from the build: in the
+ * repository this file sits at `bin/`, one level below the package, while a published
+ * install puts it at `dist/bin/`, two levels below. A fixed `..` is correct in exactly one
+ * of those, and gets the other silently wrong: the template resolves to a directory that
+ * does not exist, the walk returns nothing, and the install reports success having written
+ * no files.
+ */
+function findPackageRoot(from) {
+    let current = from;
+    for (let depth = 0; depth < 5; depth += 1) {
+        if (fsSync.existsSync(path.join(current, "template")))
+            return current;
+        const parent = path.dirname(current);
+        if (parent === current)
+            break;
+        current = parent;
+    }
+    throw new Error("Could not find the template directory. This install of create-religion is incomplete; reinstall it.");
+}
+const packageRoot = findPackageRoot(here);
+const templateRoot = path.join(packageRoot, "template");
+async function main(argv) {
+    const options = parse(argv);
+    if (options.command === "help")
+        return printHelp();
+    if (options.command === "install" || options.command === "update")
+        return runInstall(options);
+    const root = await findProjectRoot(options.target);
+    if (!root) {
+        console.error("No Religion project found here or in any parent directory.");
+        console.error("Run `religion install` from the project root to add one.");
+        process.exit(1);
+    }
+    if (options.command === "status") {
+        const status = computeStatus(await readProjectState(root));
+        console.log(options.json ? JSON.stringify(status, null, 2) : renderStatus(status));
+        return;
+    }
+    if (options.command === "doctor") {
+        const results = await runDoctor(root);
+        console.log(options.json ? JSON.stringify(results, null, 2) : renderDoctor(results));
+        if (results.some((r) => !r.ok))
+            process.exitCode = 1;
+        return;
+    }
+    const dashboard = await startDashboard(root);
+    console.log(`Religion dashboard: ${dashboard.url}`);
+    console.log("Read-only. Press Ctrl+C to stop.");
+    process.on("SIGINT", () => {
+        void dashboard.close().then(() => process.exit(0));
+    });
+}
+async function runInstall(options) {
+    const target = path.resolve(options.target);
+    const updating = options.command === "update";
+    const previous = await readManifest(target);
+    if (updating && !previous) {
+        console.log("No manifest found. Files matching the template will be adopted; others are conflicts.");
+    }
+    const adapters = options.adapters ?? previous?.adapters ?? (await chooseAdapters(options.yes));
+    const plan = await planInstall(templateRoot, target, adapters, previous);
+    const counts = {
+        create: plan.filter((p) => p.action === "create").length,
+        update: plan.filter((p) => p.action === "update").length,
+        conflict: plan.filter((p) => p.action === "conflict").length,
+        kept: plan.filter((p) => p.action === "seed-skip").length
+    };
+    console.log(`\nAdapters: ${adapters.map((a) => ADAPTERS[a].label).join(", ")}`);
+    console.log(`  create   ${counts.create}`);
+    console.log(`  update   ${counts.update}`);
+    console.log(`  keep     ${counts.kept}  (your files, never overwritten)`);
+    console.log(`  conflict ${counts.conflict}`);
+    for (const entry of plan.filter((p) => p.action === "conflict")) {
+        console.log(`    ${entry.relative}`);
+    }
+    if (options.dryRun) {
+        console.log("\nDry run. Nothing written.");
+        return;
+    }
+    if (plan.length === 0) {
+        throw new Error(`No template files found under ${templateRoot}. Nothing would be installed, which is never correct.`);
+    }
+    const result = await applyInstall(templateRoot, target, plan, { force: options.force });
+    await writeManifest(target, await version(), adapters, templateRoot, previous, result.conflicts);
+    console.log(`\nWrote ${result.written.length} file(s).`);
+    if (result.backups.length > 0)
+        console.log(`Backed up ${result.backups.length} conflicting file(s).`);
+    if (result.conflicts.length > 0) {
+        console.log(`\n${result.conflicts.length} file(s) were changed locally and left alone.` +
+            `\nReview them, then re-run with --force to replace them (originals are backed up).`);
+    }
+    if (adapters.includes("claude")) {
+        const wired = await wireHooks(target);
+        if (wired === "written") {
+            console.log("Wired the enforcement hooks into .claude/settings.json.");
+        }
+        else if (wired === "exists") {
+            console.log("\n.claude/settings.json already exists and was left alone." +
+                `\nTo enable the hooks, merge ${path.join(STATE_DIR, ".state", "settings-template.json")} into it.`);
+        }
+    }
+    if (!updating) {
+        console.log("\nNext: run the setup skill in your AI tool, then fill in the two plans.");
+    }
+}
+async function chooseAdapters(assumeYes) {
+    const all = Object.keys(ADAPTERS);
+    if (assumeYes || !process.stdin.isTTY)
+        return all;
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    console.log("\nWhich AI tools should this install for?");
+    all.forEach((a, i) => console.log(`  ${i + 1}. ${ADAPTERS[a].label}`));
+    const answer = (await rl.question("\nNumbers separated by commas, or blank for all: ")).trim();
+    rl.close();
+    if (!answer)
+        return all;
+    const chosen = answer
+        .split(",")
+        .map((part) => all[Number(part.trim()) - 1])
+        .filter((a) => a !== undefined);
+    return chosen.length > 0 ? chosen : all;
+}
+async function version() {
+    try {
+        const manifest = JSON.parse(await fs.readFile(path.join(packageRoot, "package.json"), "utf8"));
+        return manifest.version ?? "0.0.0";
+    }
+    catch {
+        return "0.0.0";
+    }
+}
+function parse(argv) {
+    const options = {
+        command: "install",
+        adapters: null,
+        json: false,
+        dryRun: false,
+        force: false,
+        yes: false,
+        target: process.cwd()
+    };
+    const commands = new Set(["install", "update", "status", "doctor", "dashboard", "help"]);
+    const adapters = [];
+    for (const arg of argv) {
+        if (commands.has(arg))
+            options.command = arg;
+        else if (arg === "--json")
+            options.json = true;
+        else if (arg === "--dry-run")
+            options.dryRun = true;
+        else if (arg === "--force")
+            options.force = true;
+        else if (arg === "--yes" || arg === "-y")
+            options.yes = true;
+        else if (arg === "--help" || arg === "-h")
+            options.command = "help";
+        else if (arg.startsWith("--") && arg.slice(2) in ADAPTERS)
+            adapters.push(arg.slice(2));
+        else if (!arg.startsWith("-"))
+            options.target = arg;
+    }
+    if (adapters.length > 0)
+        options.adapters = adapters;
+    return options;
+}
+function printHelp() {
+    console.log(`religion - a file-backed, spec-driven AI development workflow
+
+  religion install [dir]     add the workflow to a project
+  religion update  [dir]     update the workflow files, preserving your own
+  religion status            where the work stands, and what to do next
+  religion doctor            check the setup is healthy
+  religion dashboard         a local read-only view
+
+Options
+  --claude --codex --copilot --opencode   pick adapters (default: all)
+  --dry-run     show what would change, write nothing
+  --force       replace locally-changed managed files, backing them up first
+  --json        machine-readable output for status and doctor
+  --yes         no prompts
+`);
+}
+main(process.argv.slice(2)).catch((error) => {
+    console.error(error instanceof Error ? error.message : error);
+    process.exit(1);
+});

package/dist/lib/dashboard.js

@@ -0,0 +1,123 @@
+/**
+ * A local, read-only view of project state.
+ *
+ * Binds to the loopback interface only. It renders what the state files say and never
+ * writes, runs a workflow command, or starts the project.
+ */
+import http from "node:http";
+import fs from "node:fs/promises";
+import { readIfPresent, statePath } from "./paths.js";
+import { readProjectState } from "./state.js";
+import { computeStatus } from "./status.js";
+export async function startDashboard(root) {
+    const server = http.createServer((request, response) => {
+        void handle(root, request, response);
+    });
+    await new Promise((resolve) => server.listen(0, "127.0.0.1", resolve));
+    const address = server.address();
+    const port = typeof address === "object" && address ? address.port : 0;
+    return {
+        url: `http://127.0.0.1:${port}`,
+        close: () => new Promise((resolve) => server.close(() => resolve()))
+    };
+}
+async function handle(root, request, response) {
+    if (request.url === "/state.json") {
+        const state = await readProjectState(root);
+        const activity = await readActivity(root);
+        response.writeHead(200, { "content-type": "application/json" });
+        response.end(JSON.stringify({ status: computeStatus(state), plan: state.plan, findings: state.findings, activity }));
+        return;
+    }
+    response.writeHead(200, { "content-type": "text/html; charset=utf-8" });
+    response.end(PAGE);
+}
+async function readActivity(root) {
+    const raw = await readIfPresent(statePath(root, ".state", "run.json"));
+    if (!raw)
+        return null;
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
+export async function historyCount(root) {
+    let total = 0;
+    for (const kind of ["features", "fixes", "rollbacks"]) {
+        try {
+            const entries = await fs.readdir(statePath(root, "history", kind));
+            total += entries.filter((e) => e.endsWith(".md") && e !== "README.md").length;
+        }
+        catch {
+            // absent directory contributes nothing
+        }
+    }
+    return total;
+}
+const PAGE = `<!doctype html>
+<meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">
+<title>Religion</title>
+<style>
+  :root { color-scheme: light dark; --bg:#fbfbfa; --fg:#1a1a19; --dim:#6b6b68; --line:#e5e5e2; --card:#fff; --warn:#b45309; --block:#b91c1c; }
+  @media (prefers-color-scheme: dark) { :root { --bg:#16161a; --fg:#e8e8e6; --dim:#9a9a96; --line:#2a2a30; --card:#1e1e24; } }
+  * { box-sizing: border-box; }
+  body { margin:0; padding:2rem 1.25rem; background:var(--bg); color:var(--fg);
+         font:14px/1.6 ui-sans-serif,system-ui,-apple-system,sans-serif; }
+  main { max-width:56rem; margin:0 auto; }
+  h1 { font-size:1.1rem; margin:0 0 1.5rem; letter-spacing:-.01em; }
+  h1 span { color:var(--dim); font-weight:400; }
+  .next { background:var(--card); border:1px solid var(--line); border-radius:10px; padding:1rem 1.25rem; margin-bottom:1.25rem; }
+  .next b { font-size:1.15rem; font-family:ui-monospace,monospace; }
+  .next p { margin:.35rem 0 0; color:var(--dim); }
+  .grid { display:grid; gap:1rem; grid-template-columns:repeat(auto-fit,minmax(15rem,1fr)); }
+  .card { background:var(--card); border:1px solid var(--line); border-radius:10px; padding:1rem 1.25rem; }
+  .card h2 { font-size:.7rem; text-transform:uppercase; letter-spacing:.08em; color:var(--dim); margin:0 0 .6rem; }
+  .bar { height:5px; background:var(--line); border-radius:3px; overflow:hidden; margin:.5rem 0; }
+  .bar i { display:block; height:100%; background:var(--fg); }
+  ul { margin:.4rem 0 0; padding-left:1.1rem; }
+  li { margin:.2rem 0; }
+  .warn { color:var(--warn); } .block { color:var(--block); font-weight:600; }
+  .dim { color:var(--dim); }
+  code { font-family:ui-monospace,monospace; }
+</style>
+<main>
+  <h1>Religion <span id="root"></span></h1>
+  <div class="next"><b id="next">...</b><p id="why"></p></div>
+  <div class="grid">
+    <div class="card"><h2>Active work</h2><div id="work"></div></div>
+    <div class="card"><h2>Plan</h2><div id="plan"></div></div>
+    <div class="card"><h2>Findings</h2><div id="findings"></div></div>
+    <div class="card"><h2>Warnings</h2><div id="warnings"></div></div>
+  </div>
+</main>
+<script>
+const esc = (s) => String(s).replace(/[&<>]/g, (c) => ({ "&":"&amp;","<":"&lt;",">":"&gt;" }[c]));
+async function load() {
+  let d; try { d = await (await fetch("/state.json")).json(); } catch { return; }
+  const s = d.status;
+  next.textContent = "/" + s.next.command;
+  why.textContent = s.next.because;
+  work.innerHTML = s.work.active
+    ? "<b>" + esc(s.work.title || "untitled") + "</b><div class=bar><i style='width:" +
+      (s.work.stepsTotal ? Math.round(s.work.stepsDone / s.work.stepsTotal * 100) : 0) +
+      "%'></i></div><span class=dim>step " + s.work.stepsDone + " of " + s.work.stepsTotal +
+      (s.work.status ? " &middot; " + esc(s.work.status) : "") + "</span>"
+    : "<span class=dim>nothing in progress</span>";
+  plan.innerHTML = "<div class=bar><i style='width:" +
+    (s.plan.total ? Math.round(s.plan.done / s.plan.total * 100) : 0) + "%'></i></div><span class=dim>" +
+    s.plan.done + " of " + s.plan.total + " complete</span>" +
+    (s.plan.nextItem ? "<ul><li>" + esc(s.plan.nextItem) + "</li></ul>" : "");
+  findings.innerHTML = s.findings.total === 0
+    ? "<span class=dim>none</span>"
+    : (s.findings.blocking.length
+        ? "<ul>" + s.findings.blocking.map((f) => "<li class=block>" + esc(f) + "</li>").join("") + "</ul>"
+        : "") + "<span class=dim>" +
+      Object.entries(s.findings.byStatus).map(([k, v]) => v + " " + k).join(", ") + "</span>";
+  warnings.innerHTML = s.warnings.length
+    ? "<ul>" + s.warnings.map((w) => "<li class=warn>" + esc(w) + "</li>").join("") + "</ul>"
+    : "<span class=dim>none</span>";
+}
+load(); setInterval(load, 3000);
+</script>`;

package/dist/lib/doctor.js

@@ -0,0 +1,164 @@
+/**
+ * Deterministic health checks.
+ *
+ * Everything here is decidable by reading files, which is why it belongs in a program
+ * rather than in a skill. The skill's job is explaining what a failure means.
+ */
+import fs from "node:fs/promises";
+import path from "node:path";
+import { exists, readIfPresent, STATE_DIR, statePath } from "./paths.js";
+import { readProjectState } from "./state.js";
+const REQUIRED = [
+    "config.json",
+    "project-plan.md",
+    "build-plan.md",
+    "context/project-overview.md",
+    "context/coding-standards.md",
+    "context/ai-interaction.md",
+    "context/current-work.md",
+    "context/findings.md",
+    "history/features",
+    "history/fixes",
+    "history/rollbacks",
+    "reference"
+];
+const ALLOWED = {
+    "workflow.stepReview": ["every", "item"],
+    "git.mode": ["trunk", "branch-per-item"],
+    "git.checkpoints": ["none", "every-step", "squash"],
+    "verification.logicTests": ["when-configured", "required"],
+    "verification.uiEvidence": ["when-available", "required"],
+    "qualityGates.audit": ["manual", "when-sensitive", "always"],
+    "qualityGates.check": ["manual", "when-behavioral", "always"]
+};
+export async function runDoctor(root) {
+    const results = [];
+    const state = await readProjectState(root);
+    const missing = [];
+    for (const relative of REQUIRED) {
+        if (!(await exists(statePath(root, relative))))
+            missing.push(relative);
+    }
+    results.push({
+        name: "required files",
+        ok: missing.length === 0,
+        detail: missing.length === 0 ? `all ${REQUIRED.length} present` : `missing: ${missing.join(", ")}`,
+        blocks: missing.some((m) => m.startsWith("history/")) ? "completion" : "work"
+    });
+    if (!state.configValid) {
+        results.push({ name: "configuration", ok: false, detail: "config.json does not parse", blocks: "work" });
+    }
+    else {
+        const bad = invalidSettings(state.config);
+        results.push({
+            name: "configuration",
+            ok: bad.length === 0,
+            detail: bad.length === 0 ? "valid" : bad.join("; "),
+            blocks: "work"
+        });
+    }
+    const trees = [".claude/skills", ".agents/skills"];
+    const present = {};
+    for (const tree of trees) {
+        const dir = path.join(root, tree);
+        if (!(await exists(dir)))
+            continue;
+        present[tree] = (await fs.readdir(dir, { withFileTypes: true }))
+            .filter((e) => e.isDirectory())
+            .map((e) => e.name)
+            .sort();
+    }
+    const installed = Object.keys(present);
+    if (installed.length === 0) {
+        results.push({ name: "adapters", ok: false, detail: "no skill tree installed", blocks: "work" });
+    }
+    else if (installed.length === 1) {
+        results.push({
+            name: "adapters",
+            ok: true,
+            detail: `${installed[0]} with ${present[installed[0]]?.length ?? 0} skills`,
+            blocks: "nothing"
+        });
+    }
+    else {
+        const [a, b] = installed;
+        const same = JSON.stringify(present[a]) === JSON.stringify(present[b]);
+        results.push({
+            name: "adapters",
+            ok: same,
+            detail: same ? `${installed.length} trees, same skills` : `${a} and ${b} hold different skills`,
+            blocks: "nothing"
+        });
+    }
+    const entry = (await readIfPresent(path.join(root, "AGENTS.md"))) ??
+        (await readIfPresent(path.join(root, "CLAUDE.md")));
+    const placeholder = entry !== null && entry.includes(`${STATE_DIR}:setup-required`);
+    results.push({
+        name: "entry file commands",
+        ok: entry !== null && !placeholder,
+        detail: entry === null
+            ? "no entry file found"
+            : placeholder
+                ? "still the shipped placeholder; setup has not run"
+                : "filled in",
+        blocks: "work"
+    });
+    results.push({
+        name: "overview freshness",
+        ok: state.overviewPresent && state.overviewFresh !== false,
+        detail: !state.overviewPresent
+            ? "not generated yet"
+            : state.overviewFresh === false
+                ? "the plans changed after it was generated"
+                : "current",
+        blocks: "work"
+    });
+    const gitignore = (await readIfPresent(path.join(root, ".gitignore"))) ?? "";
+    const ignored = new RegExp(`^\\s*/?${STATE_DIR}/?\\s*$`, "m").test(gitignore);
+    results.push({
+        name: "visibility",
+        ok: true,
+        detail: ignored ? "state is local only" : "state is committed",
+        blocks: "nothing"
+    });
+    results.push({
+        name: "git",
+        ok: await exists(path.join(root, ".git")),
+        detail: (await exists(path.join(root, ".git"))) ? "repository present" : "not a git repository",
+        blocks: "completion"
+    });
+    return results;
+}
+function invalidSettings(config) {
+    const problems = [];
+    if (config === null || typeof config !== "object")
+        return ["not an object"];
+    for (const [key, allowed] of Object.entries(ALLOWED)) {
+        const value = key.split(".").reduce((node, part) => (node && typeof node === "object" ? node[part] : undefined), config);
+        if (value === undefined)
+            continue;
+        if (!allowed.includes(String(value))) {
+            problems.push(`${key} is "${String(value)}", expected one of ${allowed.join(", ")}`);
+        }
+    }
+    return problems;
+}
+export function renderDoctor(results) {
+    const failures = results.filter((r) => !r.ok);
+    const order = { work: 0, completion: 1, nothing: 2 };
+    const sorted = [...failures].sort((a, b) => order[a.blocks] - order[b.blocks]);
+    const out = [
+        failures.length === 0 ? "Healthy." : `${failures.length} problem(s).`,
+        ""
+    ];
+    for (const result of sorted) {
+        const what = result.blocks === "nothing" ? "cosmetic" : `blocks ${result.blocks}`;
+        out.push(`  FAIL  ${result.name} (${what})`, `          ${result.detail}`);
+    }
+    if (failures.length > 0)
+        out.push("");
+    for (const result of results.filter((r) => r.ok)) {
+        out.push(`  ok    ${result.name}: ${result.detail}`);
+    }
+    return out.join("\n");
+}