create-religion 0.1.0 → 0.2.0

package/README.md

@@ -31,12 +31,14 @@ generated separately, so they carry that tool's own invocation syntax.
 ## 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
+npx create-religion status      # where the work stands, and the one thing to do next
+npx create-religion doctor      # is the setup healthy
+npx create-religion dashboard   # a local read-only view
+npx create-religion update      # update the workflow files, preserving yours
 ```
 
+Installing the package globally shortens these to `religion status` and the rest.
+
 `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.
 

package/dist/bin/religion.js

@@ -189,11 +189,14 @@ function parse(argv) {
 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
+Run as \`npx create-religion <command>\`, or as \`religion <command>\` when the package
+is installed globally.
+
+  install [dir]     add the workflow to a project
+  update  [dir]     update the workflow files, preserving your own
+  status            where the work stands, and what to do next
+  doctor            check the setup is healthy
+  dashboard         a local read-only view
 
 Options
   --claude --codex --copilot --opencode   pick adapters (default: all)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-religion",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "A file-backed, spec-driven AI development workflow. Spec before code, small reviewed diffs, and project state in markdown so a cleared context costs nothing.",
   "license": "MIT",
   "author": "Nate",

package/template/.agents/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. 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.
 

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

@@ -0,0 +1,159 @@
+---
+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
+
+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/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. 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.
 

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

@@ -0,0 +1,159 @@
+---
+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
+
+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/AGENTS.md

@@ -66,6 +66,7 @@ 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

package/template/religion/config.json

@@ -18,6 +18,10 @@
     "audit": "when-sensitive",
     "check": "when-behavioral"
   },
+  "refactor": {
+    "maxFileLines": 400,
+    "maxFunctionLines": 50
+  },
   "auto": {
     "maxItems": null,
     "maxRepairAttempts": 2,

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

@@ -29,7 +29,8 @@ 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
+   anything. For a bug or small change that is not in the plan, run `fix`. To simplify
+   code that already exists without changing what it does, run `refactor`. Review
    the spec before any code exists.
 2. **Implement.** Run `implement`. It builds one step at a time, never the whole
    item at once.

package/template/religion/context/current-work.md

@@ -1,8 +1,10 @@
 # Current Work
 
-> **Generated file.** Holds the one feature, fix, or rollback being built right now. Run
-> `feature` to spec a build-plan item, `fix` for an unplanned bug or change,
-> or `rollback` to plan a safe reversal. Build one thing at a time;
-> `complete` archives it under `religion/history/` and resets this file.
+> **Generated file.** Holds the one feature, fix, rollback, or refactor campaign being
+> built right now. Run `feature` to spec a build-plan item, `fix` for an
+> unplanned bug or change, `rollback` to plan a safe reversal, or `refactor` to
+> simplify existing code. Build one thing at a time; `complete` archives it under
+> `religion/history/` and resets this file.
 
-_Nothing in progress. Run `feature`, `fix`, or `rollback` to start._
+_Nothing in progress. Run `feature`, `fix`, `rollback`, or
+`refactor` to start._

package/template/religion/history/refactors/README.md

@@ -0,0 +1,9 @@
+# Completed refactors
+
+One file per completed campaign, named for the area and the lens it covered. Written by
+`complete`.
+
+A campaign is not a build-plan item, so these carry no number and nothing is ticked when one
+lands. They are kept apart from fixes because they answer a different question: not what went
+wrong here, but what has already been simplified, so a later run does not repeat work or
+undo a decision it cannot see.