create-religion 0.1.0

package/template/.claude/skills/try/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: try
+summary: write the human walkthrough for reviewing the work yourself
+description: "Generate the manual walkthrough for the current or most recently completed work: what to start, where to go, what to click or run, what to expect, and what would count as wrong. Read-only, and written for a person rather than an agent. /complete emits one for every completed item automatically, so this is for asking again later or for work still in progress. Use when the user runs /try, asks how to see or test a change themselves, asks where to click, or wants a manual review path."
+---
+
+# try - the human review path
+
+/check is the agent proving the work. This is you checking it yourself, which is a
+different thing and catches different problems: the ones that are technically correct and
+still wrong.
+
+Read-only. It does not run the project unless asked to.
+
+## Step 1 - find the work
+
+Use `religion/context/current-work.md` when something is in progress. When it is the stub,
+use the most recent archive under `religion/history/`, and say which one you are describing.
+
+## Step 2 - write the walkthrough
+
+Read the spec's outcomes and the project's declared commands, then write instructions a
+person can follow without knowing how any of it was built.
+
+1. **Start it.** The exact command, and where it will be listening.
+2. **Get there.** The route, the screen, the command, the endpoint. Say how to reach it
+   from a cold start, including any state that has to exist first, such as being signed in
+   or having a record to act on.
+3. **Do the thing.** What to click, type, or run.
+4. **Expect this.** What should happen, concretely enough to disagree with.
+5. **This would be wrong.** The specific failure worth watching for. Skipping this makes
+   the whole walkthrough a confirmation exercise, because someone following instructions
+   tends to see what they were told to expect.
+
+Cover the unhappy paths too when they are quick: the empty state, the error case, what a
+second attempt does.
+
+For a rollback, say how to confirm the removed behavior is gone, and name one unaffected
+path that should still work.
+
+## Step 3 - keep it honest
+
+State any setup that will not be obvious: seed data, environment variables, a service that
+must be running, a browser signed into something.
+
+If a step cannot be described because the work has no observable effect, say so plainly.
+That is worth knowing before completion, not after.
+
+## Rules
+
+- Instructions for a person, never a claim that a person followed them. Generating a
+  walkthrough is not evidence of review.
+- Read-only. Do not start the project, change files, or run anything unless asked.
+- Concrete over complete. Five steps someone will actually follow beat twenty they will not.
+
+## Formatting
+
+Match the conventions in `religion/context/ai-interaction.md`: concise, scannable
+markdown, lists for enumerations and tables for matrices rather than dense paragraphs.

package/template/AGENTS.md

@@ -0,0 +1,206 @@
+# AGENTS.md
+
+Instructions for AI coding agents working in this project. This is the cross-tool entry
+point, read by Codex, GitHub Copilot, or OpenCode, and by any other agent that looks for `AGENTS.md`. Claude Code
+reads `CLAUDE.md`, which covers the same workflow.
+
+## What this is
+
+A description of your project and the problem it solves.
+
+Religion is a workflow layer, not an application skeleton. To start a new project,
+scaffold the app first in an empty folder, then install Religion on top. Never run a
+framework scaffolder inside a directory that already holds these files; it fails because
+the directory is not empty.
+
+## Read these for full context
+
+Read these before acting. They are the project's own definition of what it is and how work
+is done here, and they outrank anything you infer from the code alone.
+
+- `religion/config.json` - deterministic workflow settings
+- `religion/context/project-overview.md` - the project's source of truth
+- `religion/context/coding-standards.md` - conventions to follow
+- `religion/context/ai-interaction.md` - how to work with the user on this project
+- `religion/context/current-work.md` - the one feature, fix, or rollback in progress
+- `religion/context/handoff.md` - where the work sits and what to read first
+- `religion/context/findings.md` - the findings ledger, when it holds anything
+- `religion/learning/lessons.md` - what previous runs learned about this project
+
+## Workflow
+
+Build one feature, fix, or rollback at a time, behind review gates.
+
+The loop is:
+
+    $feature -> review the spec -> $implement -> $check -> $audit -> $complete
+
+Each step's instructions are plain markdown skills any capable agent can read and follow.
+The spec is written before code exists, so it can be reviewed before a line is built.
+Implementation lands one small step at a time, each with a diff to read and evidence that
+its stated outcome was met.
+
+`religion/context/current-work.md` holds exactly one work item. Finish it, archive it,
+then start the next. Progress lives in checkboxes inside that file, so a cleared context
+costs nothing: a fresh session reads which steps are ticked and resumes from the first
+one that is not.
+
+## Skills
+
+The workflow is defined by the skills in `.agents/skills`. Each one is a `SKILL.md` you can read
+and follow directly.
+
+- `audit`         - review the code itself across four lenses, recording findings in the ledger
+- `auto`          - run the loop unattended, within explicit bounds
+- `browser-tests` - set up a repeatable browser test harness and record its command
+- `check`         - prove the current work does what its spec says, against the running project
+- `ci`            - define one Verify command and the GitHub workflow that runs it
+- `complete`      - run the final gate, archive the work, commit it, and close it out
+- `debug`         - reproduce and isolate a failure without changing anything
+- `discovery`     - a guided planning conversation that drafts the two plans
+- `distill`       - promote proven observations from the journal into loaded lessons
+- `doctor`        - check the setup is healthy and explain anything that is not
+- `extend`        - author a new skill for this workflow, with its routing tests
+- `feature`       - turn a build-plan item into a reviewed, buildable spec
+- `fix`           - spec an unplanned bug or small change, or repair a recorded finding
+- `implement`     - build the current spec one reviewed step at a time
+- `overview`      - distill the two planning documents into the project's source of truth
+- `prototype`     - explore the look before building, as throwaway mockups or real components
+- `release`       - prepare deployment readiness for Railway, Render, or Vercel
+- `rollback`      - plan a guarded reversal of completed work, preserving its history
+- `setup`         - tune the installation to this project, greenfield or existing
+- `status`        - say where the work stands and what to do next
+- `tests`         - set up unit testing, or backfill coverage for logic that already exists
+- `try`           - write the human walkthrough for reviewing the work yourself
+
+Invoke a skill with its name, as `$feature`, or ask in plain language, such as
+"spec the next feature." In tools without a dedicated invocation syntax, ask the agent to
+follow the matching `SKILL.md`. The conventions in `religion/context/` apply however a
+step is invoked.
+
+These commands are the structured path, not a cage. You can describe a feature, fix, or
+change directly at any time; the same conventions still apply, because they are always in
+context. Use the skills when you want the repeatable loop, the review gates, and the
+written history.
+
+## Authority
+
+Actions fall into three tiers. This is the whole of it: no skill may widen its own
+authority, and no setting in `religion/config.json` can move an action to a lower tier.
+
+**Always ask, every time.** No mode, setting, or prior approval grants these. Approval for
+one is never approval for another, and an approval given earlier in a session does not
+carry to a later instance.
+
+- merging into the default branch
+- pushing to any remote
+- deploying, publishing, or sending anything outward
+- deleting files or data, and any rewrite of existing history
+- changing a remote service, its configuration, or its secrets
+
+**Ask unless an automated run is underway.** In normal work these need an explicit yes at
+the time. Invoking an automated mode grants them for that run only, because that
+invocation is the approval:
+
+- committing, including step checkpoints
+- installing or upgrading dependencies
+- network calls that reach a remote service
+
+An automated run's grant never reaches the first tier. It commits freely and still stops
+to ask before it merges.
+
+**Free.** Reading files, searching, running the project's own build, tests, linters, and
+type checks, driving the app locally, and writing the workflow's own state files under
+`religion/`.
+
+## Evidence
+
+Never claim that something passed, is verified, or works without naming what proves it:
+the exact command and its result, the route and what appeared, the screenshot, or the
+output. "It should work" is not evidence, and neither is a summary of what the code
+intends to do.
+
+A required check that cannot run is a blocker, not a pass. Say so plainly and stop.
+
+## Git
+
+`git.mode` decides where work lands. It ships as `trunk`.
+
+**`trunk`** keeps work on the branch you already have checked out. Nothing is branched,
+nothing is merged, and the first tier of the authority rules stays dormant because there
+is no merge to ask about. This is the default because creating branches is a decision
+that belongs to you, not to a workflow.
+
+**`branch-per-item`** creates a branch per work item using the configured prefix, then
+squash-merges it once the work is done and you have said yes. The merge and any push are
+asked for separately: agreeing to a merge is never agreement to push.
+
+`git.checkpoints` decides what happens to intermediate work, in either mode:
+
+| Value | Behavior |
+| --- | --- |
+| `none` | Steps accumulate in the working tree; completion makes one commit for the whole item. |
+| `every-step` | Each approved step becomes its own commit, left in place. |
+| `squash` | Each approved step is committed, then completion collapses them into one. |
+
+In `trunk` mode, `squash` collapses commits on the branch you are working on, which
+rewrites local history. That is a first-tier action: it is never done without asking, and
+never done at all when any of those commits has already been pushed.
+
+## Review cadence
+
+`workflow.stepReview` decides how often implementation stops for you. It ships as
+`every`: each step ends with a diff to read and approve before the next one starts. Set
+it to `item` to collect the steps into one review packet at the end.
+
+Either way, implementation stops early and asks whenever a check fails, a decision is
+needed, a conflict appears, the work drifts outside its spec, or something in the first
+tier of the authority rules comes up.
+
+## Activity
+
+Any skill that changes something writes an activity record to
+`religion/.state/run.json` as its **first action**, before inspecting the project or
+calling anything else, and replaces it at meaningful milestones. Read-only skills do not.
+
+This is generated local state. It is never committed, never part of a work commit, and
+never contains secrets, raw output, prompts, or user content.
+
+```json
+{
+  "schemaVersion": 1,
+  "command": "auto",
+  "status": "running",
+  "summary": "Building the remaining plan",
+  "detail": "Implementing item 3.",
+  "boundary": "local-only",
+  "startedAt": "<ISO-8601>",
+  "updatedAt": "<ISO-8601>",
+  "resumeCommand": "$auto resume",
+  "progress": { "current": 2, "total": 5, "label": "items" },
+  "item": { "id": "3", "title": "Export reports" }
+}
+```
+
+`status` is `running`, `blocked`, `ready`, or `completed`. Use `ready` when a skill reached
+its intended handoff, such as an unattended run waiting for review. Use `blocked` with the
+exact recovery command when work can resume. `boundary` is `read-only`, `reviewed`, or
+`local-only`. Everything after `updatedAt` is optional.
+
+Writing this record grants nothing and bypasses nothing. A failure to write it is reported
+and ignored: reporting must never turn into a workflow failure.
+
+## Commands
+
+<!-- religion:setup-required -->
+
+Fill this in with the project's real commands. `$setup` detects them and proposes
+the list; until it runs, treat this section as unverified.
+
+- Dev server: `<command>`
+- Build: `<command>`
+- Test: `<command>`
+
+Testing is opt-in. A declared test command is what turns testing into a gate for
+logic-bearing work. If this project has no test runner, `$tests` adds one and
+updates this section.

package/template/CLAUDE.md

@@ -0,0 +1,175 @@
+# Project Name
+
+Agent instructions for this project. The files below are imported so they stay loaded
+every session: Religion keeps project state in files rather than in the conversation,
+which is what makes a cleared context survivable.
+
+@religion/context/project-overview.md
+@religion/context/coding-standards.md
+@religion/context/ai-interaction.md
+@religion/context/current-work.md
+@religion/context/handoff.md
+@religion/learning/lessons.md
+
+## What this is
+
+A description of your project and the problem it solves.
+
+Religion is a workflow layer, not an application skeleton. To start a new project,
+scaffold the app first in an empty folder, then install Religion on top. Never run a
+framework scaffolder inside a directory that already holds these files; it fails because
+the directory is not empty.
+
+## Workflow
+
+Build one feature, fix, or rollback at a time, behind review gates.
+
+The loop is:
+
+    /feature -> review the spec -> /implement -> /check -> /audit -> /complete
+
+Each step's instructions are plain markdown skills any capable agent can read and follow.
+The spec is written before code exists, so it can be reviewed before a line is built.
+Implementation lands one small step at a time, each with a diff to read and evidence that
+its stated outcome was met.
+
+`religion/context/current-work.md` holds exactly one work item. Finish it, archive it,
+then start the next. Progress lives in checkboxes inside that file, so a cleared context
+costs nothing: a fresh session reads which steps are ticked and resumes from the first
+one that is not.
+
+## Skills
+
+The workflow is defined by the skills in `.claude/skills`, which Claude Code discovers on its
+own. Run one as `/feature`, or just describe what you want; the right skill is
+selected from the request.
+
+`religion/config.json` holds this project's deterministic workflow settings. Read it
+before acting. A missing file means built-in defaults. If it exists but cannot be parsed,
+stop and run `/doctor` rather than guessing past it.
+
+These commands are the structured path, not a cage. You can describe a feature, fix, or
+change directly at any time; the same conventions still apply, because they are always in
+context.
+
+## Authority
+
+Actions fall into three tiers. This is the whole of it: no skill may widen its own
+authority, and no setting in `religion/config.json` can move an action to a lower tier.
+
+**Always ask, every time.** No mode, setting, or prior approval grants these. Approval for
+one is never approval for another, and an approval given earlier in a session does not
+carry to a later instance.
+
+- merging into the default branch
+- pushing to any remote
+- deploying, publishing, or sending anything outward
+- deleting files or data, and any rewrite of existing history
+- changing a remote service, its configuration, or its secrets
+
+**Ask unless an automated run is underway.** In normal work these need an explicit yes at
+the time. Invoking an automated mode grants them for that run only, because that
+invocation is the approval:
+
+- committing, including step checkpoints
+- installing or upgrading dependencies
+- network calls that reach a remote service
+
+An automated run's grant never reaches the first tier. It commits freely and still stops
+to ask before it merges.
+
+**Free.** Reading files, searching, running the project's own build, tests, linters, and
+type checks, driving the app locally, and writing the workflow's own state files under
+`religion/`.
+
+## Evidence
+
+Never claim that something passed, is verified, or works without naming what proves it:
+the exact command and its result, the route and what appeared, the screenshot, or the
+output. "It should work" is not evidence, and neither is a summary of what the code
+intends to do.
+
+A required check that cannot run is a blocker, not a pass. Say so plainly and stop.
+
+## Git
+
+`git.mode` decides where work lands. It ships as `trunk`.
+
+**`trunk`** keeps work on the branch you already have checked out. Nothing is branched,
+nothing is merged, and the first tier of the authority rules stays dormant because there
+is no merge to ask about. This is the default because creating branches is a decision
+that belongs to you, not to a workflow.
+
+**`branch-per-item`** creates a branch per work item using the configured prefix, then
+squash-merges it once the work is done and you have said yes. The merge and any push are
+asked for separately: agreeing to a merge is never agreement to push.
+
+`git.checkpoints` decides what happens to intermediate work, in either mode:
+
+| Value | Behavior |
+| --- | --- |
+| `none` | Steps accumulate in the working tree; completion makes one commit for the whole item. |
+| `every-step` | Each approved step becomes its own commit, left in place. |
+| `squash` | Each approved step is committed, then completion collapses them into one. |
+
+In `trunk` mode, `squash` collapses commits on the branch you are working on, which
+rewrites local history. That is a first-tier action: it is never done without asking, and
+never done at all when any of those commits has already been pushed.
+
+## Review cadence
+
+`workflow.stepReview` decides how often implementation stops for you. It ships as
+`every`: each step ends with a diff to read and approve before the next one starts. Set
+it to `item` to collect the steps into one review packet at the end.
+
+Either way, implementation stops early and asks whenever a check fails, a decision is
+needed, a conflict appears, the work drifts outside its spec, or something in the first
+tier of the authority rules comes up.
+
+## Activity
+
+Any skill that changes something writes an activity record to
+`religion/.state/run.json` as its **first action**, before inspecting the project or
+calling anything else, and replaces it at meaningful milestones. Read-only skills do not.
+
+This is generated local state. It is never committed, never part of a work commit, and
+never contains secrets, raw output, prompts, or user content.
+
+```json
+{
+  "schemaVersion": 1,
+  "command": "auto",
+  "status": "running",
+  "summary": "Building the remaining plan",
+  "detail": "Implementing item 3.",
+  "boundary": "local-only",
+  "startedAt": "<ISO-8601>",
+  "updatedAt": "<ISO-8601>",
+  "resumeCommand": "/auto resume",
+  "progress": { "current": 2, "total": 5, "label": "items" },
+  "item": { "id": "3", "title": "Export reports" }
+}
+```
+
+`status` is `running`, `blocked`, `ready`, or `completed`. Use `ready` when a skill reached
+its intended handoff, such as an unattended run waiting for review. Use `blocked` with the
+exact recovery command when work can resume. `boundary` is `read-only`, `reviewed`, or
+`local-only`. Everything after `updatedAt` is optional.
+
+Writing this record grants nothing and bypasses nothing. A failure to write it is reported
+and ignored: reporting must never turn into a workflow failure.
+
+## Commands
+
+<!-- religion:setup-required -->
+
+Fill this in with the project's real commands. `/setup` detects them and proposes
+the list; until it runs, treat this section as unverified.
+
+- Dev server: `<command>`
+- Build: `<command>`
+- Test: `<command>`
+
+Testing is opt-in. A declared test command is what turns testing into a gate for
+logic-bearing work. If this project has no test runner, `/tests` adds one and
+updates this section.

package/template/religion/.state/README.md

@@ -0,0 +1,10 @@
+# Generated local state
+
+Machine-written files that are never committed:
+
+- `manifest.json` - the installed version and the hashes of managed files, so an update can
+  tell a local edit from a stale copy instead of overwriting either.
+- `run.json` - what the workflow is doing right now, for the status view and the dashboard.
+
+Nothing here is a record of the work. Deleting it costs the update path its conflict
+detection and the dashboard its activity view, and costs the project nothing.

package/template/religion/.state/settings-template.json

@@ -0,0 +1,19 @@
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [{ "type": "command", "command": "node .claude/hooks/guard-tier-one.mjs" }]
+      },
+      {
+        "matcher": "Edit|Write",
+        "hooks": [{ "type": "command", "command": "node .claude/hooks/guard-rendered-output.mjs" }]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [{ "type": "command", "command": "node .claude/hooks/write-handoff.mjs" }]
+      }
+    ]
+  }
+}

package/template/religion/build-plan.md

@@ -0,0 +1,43 @@
+# Build Plan
+
+> The second planning document you own. Keep it high level even when `project-plan.md` is
+> detailed: one line per feature, in rough build order. The depth lives in each work
+> item's spec.
+
+## Format
+
+Use checkboxes. The build loop reads them: `feature` with no argument specs the
+first unchecked item, and `complete` checks it off. That is what makes progress
+survive a cleared context, so keep the list a checklist.
+
+Each item should be a feature-sized outcome, not a loose task or a whole product area.
+
+Good:
+
+- [ ] 1. **Skill submission** - upload a package and save its metadata
+- [ ] 2. **Validation result** - run checks and show pass or fail per submission
+- [ ] 3. **Directory listing** - browse and filter what has been published
+
+Avoid: "Upload stuff", "Database", "Make it look nice", or one line holding auth, billing,
+and deployment at once.
+
+A large item gets split into sub-items when it is spec'd, as `4a`, `4b`, and so on. Each
+sub-item is its own work item with its own review and its own archive entry.
+
+## Keeping it going
+
+This is a living roadmap, not a frozen record of the first release. Keep completed items
+checked and append new unchecked ones as the project grows. Headings such as `## Later`
+keep a long plan readable without changing how the next item is found.
+
+Do not renumber completed items: their archives refer back to those numbers. Continue with
+the next unused number. If a new feature changes the product direction, users, data,
+stack, or deployment, update `project-plan.md` too, then re-run `overview`.
+
+Scaffolding the application and prototyping the look are pre-build steps, not features.
+Start with the first real slice of functionality.
+
+## Plan
+
+- [ ] 1. **Feature one** - what it delivers
+- [ ] 2. **Feature two** - what it delivers

package/template/religion/config.json

@@ -0,0 +1,26 @@
+{
+  "schemaVersion": 1,
+  "workflow": {
+    "stepReview": "every"
+  },
+  "git": {
+    "mode": "trunk",
+    "checkpoints": "every-step",
+    "featureBranchPrefix": "feature/",
+    "fixBranchPrefix": "fix/",
+    "rollbackBranchPrefix": "rollback/"
+  },
+  "verification": {
+    "logicTests": "when-configured",
+    "uiEvidence": "when-available"
+  },
+  "qualityGates": {
+    "audit": "when-sensitive",
+    "check": "when-behavioral"
+  },
+  "auto": {
+    "maxItems": null,
+    "maxRepairAttempts": 2,
+    "finalAudit": false
+  }
+}

package/template/religion/context/ai-interaction.md

@@ -0,0 +1,84 @@
+# AI Interaction
+
+> How the agent works with you on this project. Yours to tune: the skills point here for
+> communication and formatting, so a change made here applies everywhere.
+
+## Communication
+
+- Be concise and direct. Lead with the answer, then the supporting detail.
+- Explain non-obvious decisions briefly. Skip the obvious ones.
+- Ask before a large refactor or an architectural change.
+- Do not add capabilities that are not in the current work item.
+- Never delete files without asking.
+
+## Output formatting
+
+Format every response for fast scanning, in whatever renders it.
+
+- **Real markdown, not walls of prose.** Bold labels, short lines, a blank line between
+  blocks.
+- **Enumerations are lists.** A sequence of steps, options, or findings is a list, never
+  an inline "(1)... (2)... (3)" run buried in a paragraph.
+- **Tables for matrices.** Comparing things across the same fields goes in a table.
+- **Backticks for code things:** identifiers, paths, commands, filenames.
+- **Do not over-format.** No deep bullet nests or decorative headers on a two-line reply.
+
+## The loop
+
+The spec for the work in progress lives in `religion/context/current-work.md`.
+
+1. **Spec.** Run `feature` with no argument to spec the first unchecked item in the
+   build plan, or name one. Add ` preview` to see what it involves without writing
+   anything. For a bug or small change that is not in the plan, run `fix`. Review
+   the spec before any code exists.
+2. **Implement.** Run `implement`. It builds one step at a time, never the whole
+   item at once.
+3. **Review.** Each step shows a diff, not whole files, with a short summary: what the
+   step delivered, one line per changed file on why, and its stated outcome shown true.
+4. **Verify.** If the entry file declares a `Verify` command, that exact command is the
+   automated gate. Otherwise the build runs, plus the test command when one is declared. A
+   step that adds logic ships a passing test when the test gate is on.
+5. **Iterate.** If it does not work, revise and re-test before moving on. Do not pile the
+   next step on a broken one.
+6. **Prove it.** Run `check` for an outside proof pass against the running app.
+7. **Review the code.** Run `audit` for a read-only quality pass. Findings go to the
+   ledger with durable identifiers; repairs happen through `implement`.
+8. **Complete.** Run `complete`. It runs the final safety pass, archives the spec
+   under `religion/history/`, checks the item off the build plan, resets the active spec,
+   and makes the work commit. It ends with a manual walkthrough of what landed.
+9. **Deploy, when it is time.** Run `release` after a completed item or a milestone
+   for provider config, environment review, and a smoke-test path.
+
+The skills are the structured path, not a requirement. You can describe a feature, fix, or
+change directly at any time, and it is built the same way: small steps, a diff you approve,
+these conventions. Use the skills when you want the repeatable loop and the written
+history; ask directly when you just want something done.
+
+## Resuming
+
+Progress lives in files, not in the conversation. The active spec holds each step checked
+off as it lands, and git holds the code. A fresh session loads the spec through the project
+entry file, so `implement` continues from the first unchecked step. There is no
+separate save or load.
+
+If you are unsure where things stand, run `status`. If you are unsure whether the
+setup is healthy, run `doctor`. Both are read-only.
+
+## When stuck
+
+- If something is not working after two or three attempts, stop and explain the problem.
+- Do not keep trying variations of the same fix.
+- Ask when the requirements are genuinely unclear, and only then.
+
+## Automated runs
+
+`auto` exists only as an explicit opt-in. Do not suggest it as the default next
+action. When invoked it runs without pausing after each passing step, within the bounds in
+`religion/config.json`. Its invocation grants the routine actions listed in the Authority
+section of the project entry file, and grants nothing beyond them.
+
+## Reviewing generated code
+
+Review it periodically, especially for authorization checks and input validation,
+performance traps such as repeated queries, edge cases the happy path skipped, and whether
+it matches the patterns already in the codebase.