create-religion 0.1.1 → 0.3.0

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

@@ -1,7 +1,7 @@
 ---
 name: complete
 summary: run the final gate, archive the work, commit it, and close it out
-description: "Close out a finished feature, fix, or rollback. Runs the full Verify command and the final safety pass, applies the configured quality gates, archives the spec under religion/history/, ticks the build plan, prunes resolved findings into the archive, resets the active spec, and makes the work commit. Under branch-per-item it squash-merges only with explicit approval, then asks separately before pushing. Ends with a manual walkthrough of what landed. Use when the user runs /complete, or asks to finish, wrap up, close out, or merge the current work item once it is built and reviewed."
+description: "Close out a finished feature, fix, rollback, or refactor campaign. Runs the full Verify command and the final safety pass, applies the configured quality gates, archives the spec under religion/history/, ticks the build plan, prunes resolved findings into the archive, resets the active spec, and makes the work commit. Under branch-per-item it squash-merges only with explicit approval, then asks separately before pushing. Under pull-request it pushes the branch and opens a pull request into the default branch, merging nothing. Ends with a manual walkthrough of what landed. Use when the user runs /complete, or asks to finish, wrap up, close out, or merge the current work item once it is built and reviewed."
 ---
 
 # complete - close out the finished work
@@ -80,6 +80,9 @@ Read the spec's type.
 - **Rollback** - archive to `religion/history/rollbacks/YYYY-MM-DD-NN-name.md`, leaving
   the original feature archive intact. Untick the target item, and append a short note to
   that line with the date and the rollback's archive path. Keep the number stable.
+- **Refactor** - archive to `religion/history/refactors/area-lens.md`. A campaign is not a
+  plan item, so there is nothing to tick. Carry the deferred candidates across into the
+  archive, since they are what the next campaign over that area starts from.
 
 The number lives in the path. It never appears in the commit message.
 
@@ -149,10 +152,33 @@ Under **`branch-per-item`**:
 2. Delete the branch after a clean merge.
 3. Stop.
 
-Then, in either mode, ask separately whether to push. **Approval to merge is not approval
-to push.** Push only after an explicit yes to pushing, in this conversation. If there is no
+In those two modes, ask separately whether to push. **Approval to merge is not approval to
+push.** Push only after an explicit yes to pushing, in this conversation. If there is no
 remote, say so rather than guessing.
 
+Under **`pull-request`** nothing is merged here and the default branch is never written to.
+The branch goes up, the pull request describes it, and the merge is the user's, on the host:
+
+1. Confirm the repository can host one: a remote exists and the host command works. If it
+   cannot, stop and say so plainly. The work is committed on its branch and the user can
+   open the pull request themselves. Never invent a remote, and never quietly fall back to
+   a local merge, which would swap the history model without saying so.
+2. Push the branch and set its upstream, only with an explicit yes in this conversation.
+   **That yes covers pushing this branch and nothing else.** Neither running this skill nor
+   "looks good" is that yes.
+3. Open the pull request from the branch into the default branch. Title it from the work
+   commit. The body carries what changed and why, the checks that ran with the exact command
+   or output proving each, the manual walkthrough from Step 5, and anything left open:
+   unresolved findings, deliberate omissions, follow-ups.
+4. Report the pull request URL and stop. Do not merge it, do not wait or poll for it, and do
+   not touch the default branch.
+
+Deleting the branch is a separate, later action, because the merge happens outside this
+session. When the user says it merged: check out the default branch, fast-forward it,
+confirm the work commit is actually in it, and only then delete the branch locally and on
+the remote. A squash-merge leaves no merge parent, so `git branch -d` will refuse; verify
+the content landed before reaching for `-D`.
+
 ## Step 5 - say how to try it
 
 Always end with the manual walkthrough for what just landed: what to start, where to go,

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

@@ -2,6 +2,7 @@
 name: doctor
 summary: check the setup is healthy and explain anything that is not
 description: "Read-only health check of the installation: required files present, adapter trees in sync, the entry file's commands accurate, configuration valid, plans usable, overview fresh, ignore rules sane, and git state workable. Runs the religion command-line tool for the deterministic checks when it is installed, then explains what any failure means and offers the fix. Use when the user runs /doctor, asks whether the setup is correct, wants a health check, or says something feels wrong before starting or resuming work."
+allowed-tools: Read, Grep, Glob, Bash
 ---
 
 # doctor - is this set up correctly

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

@@ -22,6 +22,11 @@ lines into something buildable is this skill's whole job. It plans; it never bui
 - **A description with no match in the plan** - goes through **New work intake** below.
 - **`preview`** appended to any of the above - a read-only briefing, writing nothing.
 
+Read `religion/context/inbox.md` before choosing. When it holds anything and no argument
+named a specific item, list what is in it alongside the plan item you would otherwise take,
+and let the user pick. A note that is specced leaves the inbox with the line removed; the
+rest stay. An inbox nobody reads is a list of things nobody did.
+
 ## Step 0 - make sure the ground is solid
 
 Two checks before anything else.
@@ -127,9 +132,20 @@ visual spec from words alone when an image could exist.
 
 **Build steps** are the core of the file. Each is a small diff, ends with something that
 works, depends only on earlier steps, and carries an outcome that can actually be observed.
+
+Where two steps genuinely do not depend on each other, mark the later one `(with N)`. It is
+an assertion, not a hint: that these steps touch different files and neither needs the
+other's result. Mark nothing you are unsure of. An unmarked spec is sequential, which is
+always correct and never wrong, and a project with `workflow.parallelSteps` off ignores the
+markers entirely.
 Read the Commands section of the entry file while writing the Testing section, so predicted
 coverage matches the gate that is actually on.
 
+When writing the spec needed a broad read of the codebase first, run that read in a subagent
+and have it return what it found. A survey large enough to be worth doing is large enough to
+crowd out the context that has to write the spec from it. The subagent reads and returns; this
+skill writes, as it always does.
+
 This is a draft. Do not present it yet.
 
 ## Step 4 - red-team the draft, then tighten

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

@@ -16,7 +16,12 @@ numbered, it ticks nothing, and it archives on its own.
   something wrong.
 - **A finding identifier** - `/fix F-03` specs the repair of that ledger entry.
 
-Without either, ask what is wrong. Do not guess.
+- **Nothing** - read `religion/context/inbox.md` and offer what is there. Those notes were
+  taken mid-build precisely because they were not worth stopping for at the time, and this is
+  the moment they are worth something. Specced notes leave the inbox; the rest stay.
+
+Without any of those, ask what is wrong. Do not guess, and do not scan the project hoping to
+find something.
 
 ## Step 1 - understand the problem
 

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

@@ -50,9 +50,11 @@ Read `git.mode`.
 If the current branch looks wrong for this work, say so and ask; do not switch or create
 one unprompted.
 
-**`branch-per-item`** creates and checks out a branch named from the spec using the
-configured prefix. On a resume the branch exists already, so check it out rather than
-creating a second one.
+**`branch-per-item`** and **`pull-request`** both create and check out a branch named from
+the spec, using the prefix configured for its kind: feature, fix, rollback, or refactor.
+They differ only in how the work leaves the branch at completion, which is not this skill's
+concern. On a resume the branch exists already, so check it out rather than creating a
+second one.
 
 Either way, if the project is not a git repository, say so and ask the user to initialize
 one. The loop needs history to be reviewable.
@@ -63,7 +65,7 @@ Set the spec's status to `in progress` before the first code change of this run,
 whenever work resumes after a passing check and touches product code. That invalidates
 stale verification state.
 
-Work through the build steps **in order, one at a time**. For each:
+Work through the build steps **in order, one at a time**, unless a wave applies. For each:
 
 1. **Implement just that step.** The smallest change that satisfies its stated outcome.
    Nothing from a later step, nothing nobody asked for.
@@ -90,8 +92,13 @@ Work through the build steps **in order, one at a time**. For each:
    is failing, and offer to hand it to /debug, which reproduces the failure and
    tests competing hypotheses in parallel. Do not keep trying variations.
 6. **Tick the step** (`- [x]`) once its gate is satisfied, so progress survives a cleared
-   context. If the step repaired a finding, mark that finding `fixed` and note the repair
+   context. In a wave, tick each step that passed, and only those. If the step repaired a finding, mark that finding `fixed` and note the repair
    in its resolution line. Never mark it `closed`; see Step 3.
+
+   **Tick it then, not later.** Never save several ticks to write in one go. The spec on
+   disk is the only record of what is done, and a session that ends between the work and
+   the bookkeeping loses exactly the step it just finished: the next one rebuilds it,
+   because an unticked step is indistinguishable from one never started.
 7. **Then prompt, according to config.**
 
    With `workflow.stepReview: "item"`, do not prompt. Continue to the next step and
@@ -115,6 +122,44 @@ Work through the build steps **in order, one at a time**. For each:
 Never batch the whole item into one diff. A diff too large to read means the step was too
 large; split it.
 
+## Waves, when the spec asks for them
+
+Off unless `workflow.parallelSteps` is `true`. When it is off, ignore every marker and build
+in order: a spec carrying markers must behave identically in a project that never opted in.
+
+A step marked `(with N)` may run alongside step `N`. Those steps and everything transitively
+joined to them form one **wave**. A step with no marker waits for every step before it, which
+is why an unmarked spec is exactly as sequential as it has always been.
+
+    - [ ] 1. Add the schema migration
+    - [ ] 2. Build the endpoint
+    - [ ] 3. Build the client  (with 2)
+    - [ ] 4. Update the docs
+
+Two waves of one, then a wave of two, then a wave of one.
+
+**Refuse a wave rather than guess at one.** Run the wave sequentially, and say why, when:
+
+- a marker names a later step, itself, or a step that does not exist
+- two steps in the wave would change the same file, which is a conflict the spec did not
+  intend and the author is better placed to resolve than a merge
+- the wave is larger than three steps, which usually means the spec is describing one step
+  badly rather than three independent ones
+
+**Building a wave.** Each step runs in its own subagent with the step, the spec, the
+standards, and nothing else. They build and **return**; they do not tick, do not write the
+spec, and do not touch the ledger. The parent applies what comes back, runs the gate for each
+step, and performs every write. This is the same rule audit's lenses follow, for the same
+reason: concurrent writers to one file is the one thing waves must never introduce.
+
+**A failure stops the wave.** Report which steps passed and which did not, tick only what
+passed, and stop. Do not retry the wave; the next run resumes at the first unticked step,
+sequentially, because a wave that failed once has already shown its independence was wrong.
+
+**One packet per wave.** Steps that ran together are reviewed together: one diff with a
+section per step and its evidence, prompted once. `workflow.stepReview` still decides whether
+that prompt happens per wave or is collected to the end; a wave never lands unreviewed.
+
 ## Step 3 - clear the ledger before handing off
 
 Read `religion/context/findings.md`. A P0 or P1 finding that is `open` or `fixed` will

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

@@ -0,0 +1,165 @@
+---
+name: refactor
+summary: simplify existing code in one behaviour-preserving campaign at a time
+description: "Simplify code that already exists, one behaviour-preserving campaign at a time. Takes a target that must be named (a single file, a folder, one package, or a monorepo root) and surveys it across five lenses: bloat, structure, over-implementation, duplication, and reinvention of what the language, the standard library, or an installed dependency already provides. Specs one lens in one area into religion/context/current-work.md and stops, leaving /implement to build it. Refuses to start when no test reaches the target, since a change meant to preserve behaviour needs something able to notice when it does not. Use when the user runs /refactor, asks to simplify, shrink, tidy, consolidate, or clean up existing or inherited code, says something is bloated or over-engineered, or wants a hand-rolled implementation replaced by something already available."
+---
+
+# refactor - simplify what is already there
+
+Refactoring is the one kind of change defined by what it must **not** do. The code gets
+smaller; what it does stays identical. That constraint is the whole skill, and every rule
+below exists to protect it.
+
+This skill surveys and plans. It writes one campaign into
+`religion/context/current-work.md` and stops, the same as /feature and /fix.
+/implement builds it under the usual review gates.
+
+## Input
+
+A **target is required**, and may be any size:
+
+    /refactor src/lib/date.ts        a single file
+    /refactor src/legacy             a folder
+    /refactor packages/api           one package
+    /refactor .                      a monorepo root
+
+There is no default and no implicit whole-project mode. Refactoring without a named target
+is how a work item becomes unbounded. If no target is given, ask for one rather than
+guessing at what looks worst.
+
+A **lens** may follow, to survey only that axis: `/refactor packages/api duplication`.
+
+## The five lenses
+
+Ordered as the campaign order is ordered, by how much each depends on a judgement about
+equivalence. The earlier ones are safe because nothing has to be judged equal to anything.
+
+| Lens | Finds | The judgement it rests on |
+| --- | --- | --- |
+| `bloat` | comments restating the code, banner blocks and section dividers, dead code, unreachable branches, unused imports, variables and exports | none: the code is not reached |
+| `structure` | files and functions past the configured size, god objects, control flow nested past following | none: a move preserves behaviour by construction |
+| `over-implementation` | abstraction layers, configuration options, generality and extension points nothing calls | that nothing calls it |
+| `duplication` | the same utility, type, component or constant defined repeatedly, when one definition would serve | that the copies are actually the same |
+| `reinvention` | hand-rolled implementations of what the language, the standard library, or an already-installed dependency provides | that the replacement matches every edge case |
+
+`structure` reads its thresholds from `refactor.maxFileLines` and
+`refactor.maxFunctionLines` in `religion/config.json`. They are defaults rather than a
+standard this project agreed to, so a project that has set its own limits in a linter
+should have those numbers copied into the configuration and used instead.
+
+## Step 1 - resolve the target
+
+Establish what was named: a file, a folder, a package, or a workspace root holding several.
+For a package or a workspace, read the manifests to learn where each package begins and
+what each one publishes. That boundary matters twice over, in Step 4 and in Step 5.
+
+Exclude what is not the project's to simplify: dependencies, generated files, build output,
+caches, vendored code, minified assets, and anything the project's ignore rules already
+exclude. State the exclusions before surveying, so nobody mistakes a skipped directory for
+a clean one.
+
+## Step 2 - establish the safety net, or stop
+
+**A declared test command is not the gate. Tests that reach the target are the gate.**
+
+Run the project's declared test command and confirm the suite both passes and exercises the
+target. A suite of six hundred green tests proves nothing about a directory none of them
+import, and proceeding on it is worse than proceeding on nothing, because it feels safe.
+
+When no test command is declared, or none reaches the target, stop and say so plainly:
+name the target, say what the suite does cover, and point at /tests to cover the
+target first. A required check that cannot run is a blocker, not a pass.
+
+When the net holds, record the exact command and its result. That green baseline goes into
+the spec in Step 5, so every step can be measured against the state before anything moved.
+
+## Step 3 - survey
+
+**Run the survey in a subagent and have it return the map.** For anything larger than a
+single file this is the difference between writing a campaign with room to think and writing
+it from a context already full of the survey. The subagent reads and returns counts and
+candidate locations; it never writes, and this skill performs the single write, exactly as
+/audit does with its lenses.
+
+Read the target across the selected lenses, or all five when none was named. Read
+`religion/context/findings.md` as well: quality findings recorded by /audit against
+this area are candidates already identified, and folding them in avoids rediscovering them
+under a second name. **Never write to the ledger.** /audit owns that file, and a
+finding's status stays its to change.
+
+Report what was found as counts per area and per lens, densest first:
+
+    packages/api      bloat 41   structure  7   duplication 12
+    packages/shared   bloat  6   structure  2   duplication 21
+    packages/cli      bloat  3   structure  0   duplication  1
+
+For a single file the map is one row, which is fine. The point is that the size of the job
+is visible before anyone commits to it.
+
+## Step 4 - choose one lens, in one area
+
+**A campaign is one lens in one area.** Not five lenses, not the whole monorepo. A spec
+mixing safe deletions with semantic replacements cannot be reviewed as one thing, because
+the reviewer's attention is spent on the easy half.
+
+Propose the widest win, say why, and let the user choose. Everything else stays in the
+report, unspecced, waiting for the next run after this campaign completes.
+
+Two boundaries constrain what may enter the campaign:
+
+- **The published surface stops and asks.** Anything reachable only from inside the project
+  can be merged, renamed or reshaped freely, which is what makes the duplication lens work
+  at all. Anything a consumer can import, taken from the manifest's entry points, is a
+  breaking change wearing a refactor's clothes. Name it, say what would break, and let the
+  user decide whether it belongs in this campaign or in a feature.
+- **A new dependency needs its own yes, and has to earn it.** When the language and the
+  installed dependencies genuinely cannot replace hand-rolled code, a new dependency may be
+  proposed, never assumed. Propose one only when it would be used in **several places**. A
+  dependency that saves fifty lines in a single file is a bad trade: the code leaves and the
+  supply chain stays.
+
+## Step 5 - write the campaign
+
+Write the spec into `religion/context/current-work.md`: the target, the lens, the green
+baseline from Step 2, and the change broken into steps small enough to read as diffs.
+
+Order the steps so each one stands alone and can be verified against the baseline. Record
+what would prove the behaviour unchanged, which is the test command from Step 2 for logic,
+and for anything with a visible surface a route to walk and what should appear.
+
+Candidates that were found but not specced go in as a short list at the end, so the next run
+has them and nothing is rediscovered from scratch.
+
+Completion archives the campaign under `religion/history/refactors/`. Refactor campaigns
+are their own kind of work: they are not build-plan items, they tick nothing, and keeping
+them separate is what makes the refactoring history of an area readable later.
+
+## Step 6 - report and stop
+
+The target and what it resolved to, the baseline and the command that produced it, the
+density map, the lens and area chosen and why, what the campaign contains, what was deferred,
+and any published-surface or dependency decision waiting on the user.
+
+Then stop. This skill does not build. /implement does.
+
+## Rules
+
+- **Behaviour is the invariant.** Every step must leave the target doing exactly what it did.
+- **Never fix a bug in a refactor step.** A refactor that uncovers a genuine defect stops and
+  points at /fix. Discovering that four copies of a function behave differently means
+  choosing one is a behaviour change, not a merge, and the reviewer cannot see it inside a
+  diff that also moves code.
+- **Never delete a comment that carries a why.** The bloat lens removes comments restating
+  the code. A comment recording a decision, a gotcha, a workaround, or a link to a spec is
+  the opposite of bloat, and it is unrecoverable once gone.
+- **Never reformat alongside a change.** Whitespace, import order and style churn never share
+  a step with a structural edit. A diff where fifteen real lines hide among three hundred
+  cosmetic ones gets rubber-stamped, which costs more than the formatting saved.
+- One lens, one area, one campaign.
+- A target is always named. Never scan the project hoping to find something worth doing.
+- Read the findings ledger; never write it.
+
+## 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/.claude/skills/rollback/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: rollback
 summary: plan a guarded reversal of completed work, preserving its history
-description: "Plan the safe reversal of a completed item using its archive and the commits it recorded when it landed. Verifies the recorded commits still resolve and are ancestors of HEAD, reviews later commits for work that depends on them, then writes a Type: Rollback spec to religion/context/current-work.md and stops before any code changes. The reversal applies only the product diff in reverse, never a whole-commit revert, so the archive and plan bookkeeping that landed in the same commits survive. Use when the user runs /rollback, asks to remove or undo completed work, or wants the project returned to its behavior before an item without erasing the record that it existed."
+description: "Plan the safe reversal of a completed item using its archive and the commits it recorded when it landed. Verifies the recorded commits still resolve and are ancestors of HEAD, reviews later commits for work that depends on them, then writes a Type: Rollback spec to religion/context/current-work.md and stops before any code changes. The reversal applies only the product diff in reverse, never a whole-commit revert, so the archive and plan bookkeeping that landed in the same commits survive. Given `--steps N` instead, backs out the last N steps of the item in progress: stashes anything uncommitted first, reverts what those steps changed, and unticks them, after showing what it will do and being told yes. Use when the user runs /rollback, asks to remove or undo completed work, wants the project returned to its behavior before an item without erasing the record that it existed, or asks to back out or undo the last step or two of work still in progress."
 ---
 
 # rollback - plan a guarded reversal
@@ -17,6 +17,35 @@ record that the work ever existed, and would fight with whatever the plan says n
 
 This skill plans. It writes a spec and stops. No product file changes here.
 
+**Except in one mode.** `/rollback --steps N` backs out the last N steps of the item currently
+in progress, and does it rather than speccing it. The two jobs share a verb and nothing else:
+reversing completed work is large, has consequences for anything built on top, and earns a
+reviewed spec. Backing out two steps you just wrote is small, local, and speccing it would
+mean writing into the very file whose steps are being undone.
+
+## Backing out steps in progress
+
+Only for `--steps N`. For a completed item, skip to Step 1.
+
+1. **Read the active spec.** Take the last N ticked steps. If fewer than N are ticked, say so
+   and take what there is. If none are, there is nothing to undo and this stops.
+2. **Make it recoverable before making it gone.** Stash anything uncommitted with a named
+   entry, whatever `git.checkpoints` says, and keep the name. Undoing work git cannot recover
+   is a deletion, and the stash is what turns it back into a mistake that costs one command.
+3. **Show what will happen**, then ask once: the steps by number and title, the files that
+   change, and whether they came from commits or the working tree. Wait for a yes. This is
+   the only approval, and it does not extend to anything else.
+4. **Reverse it.** Where the steps are commits, revert their product diff. Where they are
+   uncommitted, restore the files to their state before those steps. Never rewrite pushed
+   history, and never reach past the current work item.
+5. **Untick the steps** in the active spec, so the next /implement resumes at the first
+   of them rather than believing they are done.
+6. **Report** what was reversed, what was left alone, and the exact command that recovers the
+   stash. Say the stash name; a recovery path nobody can find is not one.
+
+The spec, the archive and the build plan are untouched: the item is still in progress, and
+nothing about it has been completed or recorded.
+
 ## Step 1 - identify the target
 
 Take a build-plan number or name. Match it to a **checked** item and its archive under
@@ -102,6 +131,11 @@ work needs its own plan.
 
 ## Rules
 
+- `--steps` acts; everything else plans. Never blur the two.
+- `--steps` never touches the build plan, an archive, or a completed item.
+- Stash before reverting, every time, even when the steps are committed. The cost is one
+  stash entry and the alternative is an unrecoverable mistake.
+
 - The archive is never deleted or rewritten. Completion adds a rollback record beside it.
 - Reverse only the recorded product diff. Never a whole-commit revert.
 - The build-plan item is unticked and annotated, and keeps its number.

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

@@ -0,0 +1,92 @@
+---
+name: spike
+summary: answer one feasibility question with throwaway code, then delete it
+description: "Answer a single question about whether an approach will work, by building the smallest throwaway thing that settles it inside a stated time budget, then deleting the code and recording the answer under religion/history/spikes/. Nothing it writes ever ships. Use when the user runs /spike, asks whether something is possible or feasible, wants to know which of two approaches to take, says to try something and see, or is about to spec work that rests on an assumption nobody has tested. Not for a failure that already exists, which is /debug, and not for how something should look, which is /prototype."
+allowed-tools: Read, Grep, Glob, Bash, Write, Edit, WebFetch
+---
+
+# spike - find out, then throw it away
+
+A spec written against an untested assumption is expensive twice: once when it is written and
+reviewed, and again when implementation discovers the approach does not work and the whole
+thing is revised. A spike moves that discovery in front of the spec, where it costs a
+morning instead of a work item.
+
+The code is not the output. The answer is.
+
+## Where it sits
+
+    a question the plans do not answer
+        |
+      [spike]  -> answer recorded, code deleted
+        |
+    /feature or /fix, now speccing something known to work
+
+## Input
+
+One question, and ideally a budget:
+
+    /spike "can we stream these updates over the platform's own APIs, or is a worker needed"
+    /spike "is the vendor SDK usable from an edge runtime" --budget 1h
+
+With no question, ask for one. A spike without a question is just unplanned work.
+
+**One question per spike.** Two questions is two spikes, because the answer to the first
+usually changes whether the second is worth asking.
+
+## Step 1 - state the question and the budget
+
+Write both down before touching anything: the question in a form that has a yes, a no, or a
+named alternative as its answer, and what a good enough answer looks like. A question that
+cannot be answered wrongly is not a question.
+
+The budget defaults to something small. Say it out loud, and say what happens when it runs
+out, which is that the answer becomes "not settled in the time given" and that is a real
+result rather than a failure.
+
+## Step 2 - build the smallest thing that settles it
+
+Write the least code that produces evidence. It may be ugly, it may be hardcoded, it may
+have no error handling and no tests, because none of it is going to exist tomorrow.
+
+Keep it out of the way of real code: a scratch directory, a single file, a branch you will
+not merge. Never build the spike inside the shape the real work will take, because that is
+how a spike quietly becomes the implementation.
+
+Do not install anything the project has not agreed to. A spike that needs a new dependency to
+answer its question has found part of its answer.
+
+## Step 3 - answer, with evidence
+
+State the answer, the evidence that decided it, and what you did not test. Evidence is a
+command and its output, a request and its response, a measurement. "It seemed to work" is not
+an answer.
+
+Then say what this means for the work that prompted it: which approach the spec should take,
+and what is now known to be off the table.
+
+## Step 4 - delete the code, keep the answer
+
+Delete what you built. This is the step that makes a spike a spike, and the one most often
+skipped, because working code is hard to throw away. Keeping it means an unreviewed, untested
+sketch becomes load-bearing later, which is worse than having no answer at all.
+
+Record the result under `religion/history/spikes/`, named for the question: what was asked,
+what the answer was, the evidence, the budget it took, and what is still unknown. That file
+is what stops the same question being asked again in six months.
+
+Deleting files is a first-tier action, so ask before removing anything that is not clearly
+the throwaway you just made.
+
+## Rules
+
+- One question, one spike, one answer.
+- The code never ships. If it turns out to be worth keeping, that is a spec, not a spike.
+- A budget that runs out produces "not settled", which is reported, not hidden.
+- Never spike something the plans already answer.
+- Never write to the findings ledger. A spike answers a question; it does not review code.
+
+## 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/.claude/skills/status/SKILL.md

@@ -2,6 +2,7 @@
 name: status
 summary: say where the work stands and what to do next
 description: "Report where the project stands: build-plan progress, the active spec and which of its steps are done, open findings, git state, and the one action that makes sense next. Uses the religion command-line tool when it is installed, since the parsing is deterministic, and reads the state files directly when it is not. Read-only. Use when the user runs /status, asks where things stand, what is next, what is in progress, or is picking work back up after a break or a cleared context."
+allowed-tools: Read, Grep, Glob, Bash
 ---
 
 # status - where things stand

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

@@ -2,6 +2,7 @@
 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."
+allowed-tools: Read, Grep, Glob, Bash
 ---
 
 # try - the human review path

package/template/AGENTS.md

@@ -21,10 +21,12 @@ 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/untrusted-input.md` - what to do with text the project did not write
 - `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/context/inbox.md` - notes taken mid-build, waiting to be specced or dropped
 - `religion/learning/lessons.md` - what previous runs learned about this project
 
 ## Workflow
@@ -53,6 +55,7 @@ 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
+- `capture`       - note something for later without breaking the one thing in progress
 - `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
@@ -66,9 +69,11 @@ and follow directly.
 - `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
+- `refactor`      - simplify existing code in one behaviour-preserving campaign at a time
 - `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
+- `spike`         - answer one feasibility question with throwaway code, then delete it
 - `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
@@ -93,11 +98,14 @@ one is never approval for another, and an approval given earlier in a session do
 carry to a later instance.
 
 - merging into the default branch
-- pushing to any remote
+- pushing to the default branch, and force-pushing anything anywhere
 - 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
 
+Pushing a branch that a run created itself is the single action that may be granted ahead
+of time, and only in the narrow way set out below. Every other push is first tier.
+
 **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:
@@ -106,6 +114,12 @@ invocation is the approval:
 - installing or upgrading dependencies
 - network calls that reach a remote service
 
+Under `git.mode: pull-request` an automated run may also push the branches it created and
+open pull requests into a branch it created, but only when its invocation stated exactly
+that, in full, and the user agreed at that moment. A general yes to running is not that
+agreement, and the enumeration is not boilerplate to skip. The run still never writes to
+the default branch, and never merges the pull request it exists to produce.
+
 An automated run's grant never reaches the first tier. It commits freely and still stops
 to ask before it merges.
 
@@ -135,7 +149,18 @@ that belongs to you, not to a workflow.
 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:
+**`pull-request`** branches exactly as `branch-per-item` does, then pushes the branch and
+opens a pull request into the default branch instead of merging anything locally. Nothing
+merges that pull request and nothing writes to the default branch: the merge is yours, on
+the host. How the work lands there, squash or merge commit or rebase, is the pull request's
+setting rather than this workflow's business.
+
+A repository that cannot host a pull request, having no remote or no usable host command,
+is a stop rather than a reason to fall back to a local merge. Falling back would swap one
+history model for another without saying so, and skip the review gate the mode exists to
+create.
+
+`git.checkpoints` decides what happens to intermediate work, in any mode:
 
 | Value | Behavior |
 | --- | --- |
@@ -157,6 +182,9 @@ Either way, implementation stops early and asks whenever a check fails, a decisi
 needed, a conflict appears, the work drifts outside its spec, or something in the first
 tier of the authority rules comes up.
 
+`workflow.parallelSteps` ships `false`. Turned on, steps a spec marks as independent are
+built together in one wave and reviewed as one packet, so nothing lands unreviewed either
+way. While it is off, those markers are ignored and every spec builds in order.
 ## Activity
 
 Any skill that changes something writes an activity record to