create-religion 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (80) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +47 -0
  3. package/dist/bin/religion.js +209 -0
  4. package/dist/lib/dashboard.js +123 -0
  5. package/dist/lib/doctor.js +164 -0
  6. package/dist/lib/install.js +170 -0
  7. package/dist/lib/paths.js +40 -0
  8. package/dist/lib/state.js +117 -0
  9. package/dist/lib/status.js +88 -0
  10. package/package.json +40 -0
  11. package/template/.agents/skills/audit/SKILL.md +169 -0
  12. package/template/.agents/skills/auto/SKILL.md +110 -0
  13. package/template/.agents/skills/browser-tests/SKILL.md +65 -0
  14. package/template/.agents/skills/check/SKILL.md +86 -0
  15. package/template/.agents/skills/ci/SKILL.md +79 -0
  16. package/template/.agents/skills/complete/SKILL.md +184 -0
  17. package/template/.agents/skills/debug/SKILL.md +72 -0
  18. package/template/.agents/skills/discovery/SKILL.md +83 -0
  19. package/template/.agents/skills/distill/SKILL.md +95 -0
  20. package/template/.agents/skills/doctor/SKILL.md +65 -0
  21. package/template/.agents/skills/extend/SKILL.md +102 -0
  22. package/template/.agents/skills/feature/SKILL.md +172 -0
  23. package/template/.agents/skills/feature/reference/spec-template.md +67 -0
  24. package/template/.agents/skills/fix/SKILL.md +76 -0
  25. package/template/.agents/skills/implement/SKILL.md +174 -0
  26. package/template/.agents/skills/overview/SKILL.md +150 -0
  27. package/template/.agents/skills/overview/reference/project-overview-template.md +101 -0
  28. package/template/.agents/skills/prototype/SKILL.md +90 -0
  29. package/template/.agents/skills/release/SKILL.md +88 -0
  30. package/template/.agents/skills/rollback/SKILL.md +114 -0
  31. package/template/.agents/skills/setup/SKILL.md +105 -0
  32. package/template/.agents/skills/status/SKILL.md +63 -0
  33. package/template/.agents/skills/tests/SKILL.md +90 -0
  34. package/template/.agents/skills/try/SKILL.md +59 -0
  35. package/template/.claude/hooks/guard-rendered-output.mjs +49 -0
  36. package/template/.claude/hooks/guard-tier-one.mjs +63 -0
  37. package/template/.claude/hooks/write-handoff.mjs +83 -0
  38. package/template/.claude/skills/audit/SKILL.md +169 -0
  39. package/template/.claude/skills/auto/SKILL.md +110 -0
  40. package/template/.claude/skills/browser-tests/SKILL.md +65 -0
  41. package/template/.claude/skills/check/SKILL.md +86 -0
  42. package/template/.claude/skills/ci/SKILL.md +79 -0
  43. package/template/.claude/skills/complete/SKILL.md +184 -0
  44. package/template/.claude/skills/debug/SKILL.md +72 -0
  45. package/template/.claude/skills/discovery/SKILL.md +83 -0
  46. package/template/.claude/skills/distill/SKILL.md +95 -0
  47. package/template/.claude/skills/doctor/SKILL.md +65 -0
  48. package/template/.claude/skills/extend/SKILL.md +102 -0
  49. package/template/.claude/skills/feature/SKILL.md +172 -0
  50. package/template/.claude/skills/feature/reference/spec-template.md +67 -0
  51. package/template/.claude/skills/fix/SKILL.md +76 -0
  52. package/template/.claude/skills/implement/SKILL.md +174 -0
  53. package/template/.claude/skills/overview/SKILL.md +150 -0
  54. package/template/.claude/skills/overview/reference/project-overview-template.md +101 -0
  55. package/template/.claude/skills/prototype/SKILL.md +90 -0
  56. package/template/.claude/skills/release/SKILL.md +88 -0
  57. package/template/.claude/skills/rollback/SKILL.md +114 -0
  58. package/template/.claude/skills/setup/SKILL.md +105 -0
  59. package/template/.claude/skills/status/SKILL.md +63 -0
  60. package/template/.claude/skills/tests/SKILL.md +90 -0
  61. package/template/.claude/skills/try/SKILL.md +59 -0
  62. package/template/AGENTS.md +206 -0
  63. package/template/CLAUDE.md +175 -0
  64. package/template/religion/.state/README.md +10 -0
  65. package/template/religion/.state/settings-template.json +19 -0
  66. package/template/religion/build-plan.md +43 -0
  67. package/template/religion/config.json +26 -0
  68. package/template/religion/context/ai-interaction.md +84 -0
  69. package/template/religion/context/coding-standards.md +77 -0
  70. package/template/religion/context/current-work.md +8 -0
  71. package/template/religion/context/findings.md +9 -0
  72. package/template/religion/context/handoff.md +8 -0
  73. package/template/religion/context/project-overview.md +8 -0
  74. package/template/religion/history/features/README.md +8 -0
  75. package/template/religion/history/fixes/README.md +6 -0
  76. package/template/religion/history/rollbacks/README.md +7 -0
  77. package/template/religion/learning/journal.md +7 -0
  78. package/template/religion/learning/lessons.md +8 -0
  79. package/template/religion/project-plan.md +49 -0
  80. package/template/religion/reference/README.md +7 -0
@@ -0,0 +1,110 @@
1
+ ---
2
+ name: auto
3
+ summary: run the loop unattended, within explicit bounds
4
+ description: "Run the reviewed loop without stopping between steps, within bounds you set. With no argument it takes one work item and stops before completing it; `all` runs the remaining build plan; a number runs that many items. Specs, implements, verifies, applies the configured gates, repairs confirmed high-severity findings, and completes each item. Its invocation grants committing, dependency installs, and remote reads for the run, and grants nothing else: it still stops to ask before any merge. Use only when the user runs $auto or explicitly asks for an unattended run."
5
+ ---
6
+
7
+ # auto - the same loop, without the pauses
8
+
9
+ Explicit opt-in only. Never suggest this as a next action, and never fall into it because
10
+ several items are queued.
11
+
12
+ Same skills, same gates, same evidence. The only difference is that it does not stop
13
+ between steps.
14
+
15
+ ## Bounds
16
+
17
+ - `$auto` - one work item, stopping **before** completing it, with a review packet.
18
+ - `$auto all` - the remaining build plan, completing each item, until it runs out or hits
19
+ a bound.
20
+ - `$auto 3` - the next three items, completing each.
21
+ - `$auto resume` - continue an interrupted run from the file-backed state.
22
+
23
+ `auto.maxItems` caps successful completions. `auto.maxRepairAttempts` caps repeated
24
+ attempts at the same finding. `auto.finalAudit` adds one review across everything the run
25
+ produced.
26
+
27
+ ## What the invocation grants
28
+
29
+ Running this authorizes, for this run only: committing, installing dependencies, and
30
+ network reads. That is the second authority tier, and the invocation is the approval.
31
+
32
+ It grants **nothing** in the first tier. Merging, pushing, deploying, publishing, deleting
33
+ data, and rewriting history each still stop and ask, every time, no matter how many items
34
+ remain.
35
+
36
+ Under `git.mode: trunk` there is no merge, so a run completes items and keeps going. Under
37
+ `branch-per-item` it stops once per item to ask. That is not a flaw in the mode; landing
38
+ work on a shared branch is a decision, and it stays one.
39
+
40
+ ## Step 1 - preflight once
41
+
42
+ Before the first item:
43
+
44
+ - Configuration is valid. Stop and point at $doctor if not.
45
+ - The overview is fresh, or regenerate it.
46
+ - No open question blocks the queued items. One that does stops the run **before** any work
47
+ starts, naming the question, since a run that stops halfway through item four is worse
48
+ than one that never began.
49
+ - The working tree is clean, or the only dirt belongs to work being resumed.
50
+ - The plan has unchecked items.
51
+
52
+ State the bounds, the gates in force, and how many items are in range. Then start.
53
+
54
+ ## Step 2 - each item
55
+
56
+ For every item, in plan order:
57
+
58
+ 1. **Spec it**, following $feature, including the sizing and the self-critique. Do
59
+ not skip the critique because nobody is reading: it is what catches an oversized step
60
+ before it becomes an unreviewable diff.
61
+ 2. **Implement it**, following $implement, with no prompt between steps. Verify each
62
+ step against what it touched.
63
+ 3. **Apply the gates** from `qualityGates`, then run the full `Verify`.
64
+ 4. **Repair confirmed findings** at P0 and P1, within this item's scope, then re-review them
65
+ in a subagent with fresh context. Give up after `auto.maxRepairAttempts` and stop with
66
+ the finding recorded rather than trying variations.
67
+ 5. **Complete it**, following $complete, which archives, ticks the plan, prunes the
68
+ ledger, and commits. Ask before any merge.
69
+ 6. **Report one line** and move on.
70
+
71
+ ## Step 3 - stop
72
+
73
+ Stop immediately, keeping all state intact, when any of these happens:
74
+
75
+ - a check fails and two repair attempts do not fix it
76
+ - a product decision is needed that the plans do not answer
77
+ - a finding cannot be repaired within the item's scope
78
+ - work would touch anything in the first authority tier
79
+ - an item turns out to need splitting in a way that changes the plan
80
+ - a bound is reached
81
+ - the same failure appears twice in a row across different items, which means something
82
+ systemic and further items will not fix it
83
+
84
+ A stopped run leaves the branch, the spec, and the ticked steps exactly as they are.
85
+ `$auto resume` picks up from there, because the state is in files rather than in the run.
86
+
87
+ ## Step 4 - report
88
+
89
+ - items completed, by name, and what each delivered
90
+ - what stopped the run, exactly, and the state it stopped in
91
+ - findings raised, repaired, and still open
92
+ - checks run, and any that could not run
93
+ - the resume command, when one applies
94
+
95
+ Never report an item as complete when its gate did not pass. An unattended run that
96
+ overstates what it did is worse than one that stopped early, because nobody was watching
97
+ the part it got wrong.
98
+
99
+ ## Rules
100
+
101
+ - Explicit invocation only.
102
+ - The gates are the same gates. Unattended is not a reason to lower one.
103
+ - Never merge, push, deploy, publish, or delete without asking, however long the queue is.
104
+ - Never widen an item's scope to make its gate pass.
105
+ - Stop on ambiguity. There is nobody to ask mid-run, so a guess compounds silently.
106
+
107
+ ## Formatting
108
+
109
+ Match the conventions in `religion/context/ai-interaction.md`: concise, scannable
110
+ markdown, lists for enumerations and tables for matrices rather than dense paragraphs.
@@ -0,0 +1,65 @@
1
+ ---
2
+ name: browser-tests
3
+ summary: set up a repeatable browser test harness and record its command
4
+ description: "Add or normalize a repeatable browser test harness, reusing an existing runner where there is one and otherwise preferring Playwright for web and browser-extension projects. Adds one project-relevant smoke test, records the command in the entry file, and proves it runs. Distinct from live browser evidence during a check: this is regression coverage that runs unattended and for other people. Use when the user runs $browser-tests, asks to add browser or end-to-end tests, or asks to make browser behavior repeatable."
5
+ ---
6
+
7
+ # browser-tests - repeatable browser coverage
8
+
9
+ $check drives a real browser to prove one work item behaves. This sets up a harness
10
+ that keeps proving it, unattended, for everyone.
11
+
12
+ Different jobs. Live browser evidence answers "does this work now", with no setup and full
13
+ fidelity. A harness answers "did we break it", forever, and runs where nobody is watching.
14
+ A project can want either, both, or neither.
15
+
16
+ ## Step 1 - look first
17
+
18
+ Reuse a compatible runner if one exists. If not, prefer Playwright for web and
19
+ browser-extension projects: it installs its own browsers, runs headless, and is the
20
+ ecosystem default.
21
+
22
+ Say what you propose, including that it downloads browser binaries, before installing.
23
+
24
+ ## Step 2 - set it up minimally
25
+
26
+ Install it, add the configuration, and write **one** smoke test that exercises something
27
+ this project actually does. Not a test that loads a page and asserts the title: a test that
28
+ would fail if the project's main path broke.
29
+
30
+ Keep the configuration small. Base URL, one browser, a way to start the project. Sharding,
31
+ matrices, and visual snapshots are later choices, and adding them now means maintaining
32
+ them from a position of no evidence that they help.
33
+
34
+ ## Step 3 - record the command
35
+
36
+ Add it to the Commands section of the entry file as `Browser tests`.
37
+
38
+ Once declared, specs can include focused browser coverage for stable behavioral outcomes,
39
+ and checks can run it as one evidence source. It does not prove visual fidelity, real
40
+ signed-in behavior, or browser chrome, and must never be described as though it did.
41
+
42
+ ## Step 4 - prove it
43
+
44
+ Run the command and show the output. Then break the assertion and show it failing, so the
45
+ harness is known to be wired to the project rather than passing vacuously.
46
+
47
+ ## Step 5 - report
48
+
49
+ What was installed, the exact command, what the smoke test covers, and what it does not.
50
+
51
+ Say explicitly that this is **not** added to `Verify` or to continuous integration unless
52
+ the user asks. Browser tests are slow and flakier than unit tests; putting them in the
53
+ default gate is a real cost and should be a decision, not a side effect.
54
+
55
+ ## Rules
56
+
57
+ - One harness per project. Reuse before installing.
58
+ - One smoke test, not a suite. Coverage grows with the work that needs it.
59
+ - Never claim the harness proves something it does not observe.
60
+ - Not in `Verify` or continuous integration without an explicit yes.
61
+
62
+ ## Formatting
63
+
64
+ Match the conventions in `religion/context/ai-interaction.md`: concise, scannable
65
+ markdown, lists for enumerations and tables for matrices rather than dense paragraphs.
@@ -0,0 +1,86 @@
1
+ ---
2
+ name: check
3
+ summary: prove the current work does what its spec says, against the running project
4
+ description: "Prove the current work actually does what its spec says by running the real project and observing behavior against each stated outcome. Picks its evidence from what the project is: a live browser for web work, captured command output for a CLI, request and response for an API, plus any configured test harness. Reports pass or fail per outcome with the evidence that decided it. Never edits source, never commits; fixing belongs to $implement. Use when the user runs $check, asks to confirm the work behaves correctly, wants proof before completing, or wants a change checked in the running project rather than only in the build."
5
+ ---
6
+
7
+ # check - prove the work against the running project
8
+
9
+ Where this sits:
10
+
11
+ implement -> [check] -> complete
12
+ (built it) (prove it) (close it out)
13
+
14
+ The build passing means the code compiles. This skill answers a different question: does it
15
+ actually do what the spec said it would. Those are not the same question, and only one of
16
+ them is what the user asked for.
17
+
18
+ It observes. It never edits source, installs anything, commits, or fixes what it finds.
19
+
20
+ ## Step 1 - read what must be true
21
+
22
+ Read `religion/context/current-work.md` and take the stated outcome from every build step,
23
+ plus anything in the Goal and Testing sections that makes a claim about behavior. Those
24
+ outcomes are the checklist. Nothing else is in scope.
25
+
26
+ If the spec is still the stub, say so and stop.
27
+
28
+ ## Step 2 - pick the evidence
29
+
30
+ Choose by what the project actually is. Never assume a harness exists, and never install one.
31
+
32
+ | Project shape | Evidence |
33
+ | --- | --- |
34
+ | Web interface | Drive a real browser: navigate, interact, screenshot each outcome, and read the console and network for errors the page does not show |
35
+ | Command line tool | Run the real command with real arguments and capture stdout, stderr, and exit status |
36
+ | Service or API | Issue real requests and record status, headers, and body |
37
+ | Library | Exercise the public interface the way a consumer would, not through internals |
38
+ | Background work | Trigger it and observe its effect, not just that it was scheduled |
39
+
40
+ When the entry file declares a browser test command, run it too, as one source among
41
+ several. Do not treat it as proof of visual fidelity, real signed-in behavior, browser
42
+ chrome, or anything else it does not actually observe.
43
+
44
+ Start the project the way its own commands say to. If it cannot start, that is the finding:
45
+ report it and stop rather than reasoning about what would have happened.
46
+
47
+ ## Step 3 - check each outcome
48
+
49
+ For each one, state what you did, what you observed, and whether it matched.
50
+
51
+ - **Pass** needs observed behavior. Not a passing build, not code that looks correct, not
52
+ a plausible argument.
53
+ - **Fail** names what happened instead, with the evidence.
54
+ - **Could not check** is its own result, with the reason. It is never a pass. A required
55
+ outcome that cannot be checked is a blocker.
56
+
57
+ Check the unhappy paths the spec named: empty and malformed input, the error and empty
58
+ states, the first-run case. A feature that works only on the happy path is not done, and
59
+ this is where that gets caught rather than after it ships.
60
+
61
+ ## Step 4 - report
62
+
63
+ Lead with the verdict, then the evidence.
64
+
65
+ - each outcome, with pass, fail, or could not check, and what proved it
66
+ - what was run, exactly
67
+ - anything observed that the spec did not ask about but that looks wrong
68
+ - next action: $implement when something failed, $complete when everything
69
+ passed
70
+
71
+ Never say passed, verified, or working without naming the command, route, screenshot, or
72
+ output behind it.
73
+
74
+ ## Rules
75
+
76
+ - Observe, never repair. A failure is reported, not fixed.
77
+ - Never install a runner, a browser, or a dependency to make a check possible. Report the
78
+ gap.
79
+ - Do not widen scope beyond the spec's stated outcomes, except to report something clearly
80
+ broken that you happened to see.
81
+ - A check that could not run is a blocker, never a pass.
82
+
83
+ ## Formatting
84
+
85
+ Match the conventions in `religion/context/ai-interaction.md`: concise, scannable
86
+ markdown, lists for enumerations and tables for matrices rather than dense paragraphs.
@@ -0,0 +1,79 @@
1
+ ---
2
+ name: ci
3
+ summary: define one Verify command and the GitHub workflow that runs it
4
+ description: "Set up automatic checks around one documented Verify command. Detects the real stack, package manager, default branch, and existing workflows; combines only the checks the project actually has into one command; records it in the entry file; creates .github/workflows/verify.yml when that does not overwrite existing continuous integration; runs the command locally; and stops before pushing or changing any remote setting. Use when the user runs $ci, asks to add continuous integration, GitHub Actions, or pull-request checks."
5
+ ---
6
+
7
+ # ci - one command, run automatically
8
+
9
+ The mental model, in three parts:
10
+
11
+ - **Verify is the recipe.** One local command running the checks this project already has,
12
+ in order: typecheck, then tests, then build.
13
+ - **The workflow is the worker.** It runs that same command on pull requests and on the
14
+ default branch.
15
+ - **A branch rule is the lock.** Requiring the check before merge is a remote setting, and
16
+ a separate decision this skill does not make.
17
+
18
+ The recipe turns nothing on by magic. A project with typechecking and a build but no test
19
+ runner gets a Verify command with two parts, and gains the third when $tests adds a
20
+ runner.
21
+
22
+ ## Step 1 - detect
23
+
24
+ The stack and runtime version, the package manager and its install command, the checks that
25
+ actually exist, the default branch, and any workflows already present.
26
+
27
+ Never assume. A `test` script that runs `echo "no tests"` is not a test command, and
28
+ treating it as one produces a green check that means nothing.
29
+
30
+ ## Step 2 - define Verify
31
+
32
+ Combine only checks that exist, in order: typecheck, tests, build. Never invent one to fill
33
+ the recipe.
34
+
35
+ For a JavaScript or TypeScript project, prefer a package script named `verify` using the
36
+ detected package manager. For other stacks, use the native task runner or the exact
37
+ combined command.
38
+
39
+ Record it in the Commands section of the entry file as `Verify`. That is what
40
+ implementation and completion will run, so it has to be exactly right.
41
+
42
+ ## Step 3 - the workflow
43
+
44
+ Write `.github/workflows/verify.yml` running that same command on pull requests and on
45
+ pushes to the default branch.
46
+
47
+ - Use the project's real runtime version and install command.
48
+ - Grant `contents: read` and nothing more.
49
+ - Cache the package manager's store if that is straightforward.
50
+
51
+ **Never overwrite existing continuous integration.** If a workflow already runs these
52
+ checks, say so, show where they overlap, and stop. Two workflows running the same suite
53
+ doubles the cost and halves the trust in both.
54
+
55
+ ## Step 4 - run it locally
56
+
57
+ Run the Verify command exactly as written. If it fails, the recipe is wrong or the project
58
+ is broken, and either way it must not be committed in that state.
59
+
60
+ ## Step 5 - report and stop
61
+
62
+ The command, where it is recorded, the workflow created or the overlap found, the local
63
+ result, and what remains a separate decision.
64
+
65
+ Stop before pushing. Requiring the check in the repository's settings is a remote change
66
+ and needs its own yes, on top of the push.
67
+
68
+ ## Rules
69
+
70
+ - Only real checks go in Verify.
71
+ - Never overwrite an existing workflow.
72
+ - No git hooks, coverage thresholds, browser tests, security scanners, or version matrices.
73
+ Those are later choices, made deliberately.
74
+ - Do not push, and do not change any remote setting.
75
+
76
+ ## Formatting
77
+
78
+ Match the conventions in `religion/context/ai-interaction.md`: concise, scannable
79
+ markdown, lists for enumerations and tables for matrices rather than dense paragraphs.
@@ -0,0 +1,184 @@
1
+ ---
2
+ name: complete
3
+ summary: run the final gate, archive the work, commit it, and close it out
4
+ 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."
5
+ ---
6
+
7
+ # complete - close out the finished work
8
+
9
+ Where this sits:
10
+
11
+ implement -> [complete] -> next item
12
+ (built it) (gate, archive, commit, merge)
13
+
14
+ The work is built and reviewed. This skill decides whether it is actually done, records it
15
+ in the project's history, and lands it.
16
+
17
+ ## Before you start
18
+
19
+ **Read `religion/config.json`.** A missing file means defaults; an unparseable one stops
20
+ here and points at $doctor.
21
+
22
+ **Confirm there is something to complete.** `religion/context/current-work.md` holds a
23
+ real spec, not the stub. Uncommitted step work is expected under `git.checkpoints: none`,
24
+ so do not require the steps to be pre-committed.
25
+
26
+ ## Step 0 - the final safety pass
27
+
28
+ Report blockers only. Stop before Step 1 if any of these fail.
29
+
30
+ - **The full `Verify` command passed in this session.** Implementation verified each step
31
+ against what it touched; this is where the whole suite runs. If the entry file declares
32
+ no `Verify` command, run the build, plus the test command when one is declared and the
33
+ work touched logic. A check that cannot run is a blocker, not a pass.
34
+ - **Every build step is ticked.** An unticked step is work the spec asked for that nobody
35
+ confirmed landed. To finish without it, remove it from the spec first and say why.
36
+ - **No P0 or P1 finding is `open` or `fixed`** in `religion/context/findings.md`. `fixed`
37
+ blocks on purpose: the repair exists but no review has looked at it. Run $audit
38
+ to move it to `closed`. The only other ways past are `accepted`, which only the user may
39
+ set and which records their reason, and `invalid`, which needs review evidence. A
40
+ missing ledger means no findings.
41
+ - **With `verification.logicTests: "required"`**, logic changes have a configured runner
42
+ and passing focused tests.
43
+ - **With `verification.uiEvidence: "required"`**, interface outcomes have direct browser
44
+ evidence, not build output alone.
45
+
46
+ Then **report, without blocking**, anything in the working tree that is not tied to this
47
+ spec. A dirty findings ledger is expected. Anything else is about to be committed, so name
48
+ the files and let the user decide before continuing.
49
+
50
+ Never claim passed, verified, or working without naming the command, route, screenshot, or
51
+ output that proves it.
52
+
53
+ ## Step 1 - apply the configured gates
54
+
55
+ Read `qualityGates`. Reuse evidence already produced during this work item rather than
56
+ repeating it.
57
+
58
+ - **`audit`**: `manual` runs only on request. `when-sensitive` runs for authentication,
59
+ authorization, payments, secrets, personal data, migrations, destructive operations,
60
+ external side effects, security boundaries, or unusually broad changes. `always` runs
61
+ every time.
62
+ - **`check`**: `manual` runs only on request. `when-behavioral` runs when an outcome needs
63
+ observed runtime behavior: a click, a request, a download, a background job, a flow
64
+ across screens. `always` runs every time.
65
+
66
+ Run `check` first, then `audit`. A required gate that cannot run is a blocker. If an audit
67
+ raises a new P0 or P1, completion stops and the repair goes back to $implement.
68
+
69
+ Set the spec's status to `verified` once this passes, then archive it.
70
+
71
+ ## Step 2 - record the work
72
+
73
+ Read the spec's type.
74
+
75
+ - **Feature** - archive to `religion/history/features/NN-name.md`, where `NN` is the
76
+ build-plan number, and tick that item in the build plan, plus its parent once every
77
+ sub-item is ticked.
78
+ - **Fix** - archive to `religion/history/fixes/name.md`. A fix is not a plan item, so
79
+ there is nothing to tick.
80
+ - **Rollback** - archive to `religion/history/rollbacks/YYYY-MM-DD-NN-name.md`, leaving
81
+ the original feature archive intact. Untick the target item, and append a short note to
82
+ that line with the date and the rollback's archive path. Keep the number stable.
83
+
84
+ The number lives in the path. It never appears in the commit message.
85
+
86
+ **Record what landed.** After the work commit exists in Step 3, append a `## Landed`
87
+ section to the archive with the exact commits this item produced, oldest first, and the
88
+ commit that preceded them:
89
+
90
+ ## Landed
91
+
92
+ **Base:** <40-character sha of the commit before this item>
93
+ **Commits:** <40-character sha>, <40-character sha>
94
+ **Product paths:** src/export.ts, src/routes/export.ts
95
+
96
+ Full identifiers only, never abbreviated. This is what makes a later reversal possible:
97
+ without it, reconstructing which commits belong to an item means guessing from messages and
98
+ dates, and guessing wrong reverses somebody else's work. Under `git.mode: trunk` the item's
99
+ commits sit among others on the same branch, so this record is the only reliable boundary.
100
+
101
+ **Prune the ledger.** Append every `closed`, `accepted`, and `invalid` entry to a
102
+ `## Findings` section in the archive just written, at its final status, with the reason
103
+ preserved for accepted entries. Prefix each identifier with the archive name so it is
104
+ globally unique: item 12's `F-03` becomes `12/F-03`, and that prefixed form is the
105
+ permanent reference.
106
+
107
+ Then remove only those entries from the ledger. `open`, `fixed`, and `unverified` entries
108
+ stay, with their identifiers, so nothing is silently dropped. A `fixed` P2 does not block
109
+ completion but must survive verbatim for a later review. Reset the ledger to its stub only
110
+ when nothing unresolved remains.
111
+
112
+ **Reset the active spec** to its stub, exactly as shipped.
113
+
114
+ **Discard consumed prototypes.** If this work built its look from throwaway static mockups
115
+ and an early step ported their tokens into the real stylesheet, delete `prototypes/` as
116
+ part of this work. Prototypes that are real components are not throwaway: leave them.
117
+
118
+ Do not commit yet.
119
+
120
+ ## Step 3 - the work commit
121
+
122
+ Stage everything: any uncommitted step work, plus the archive, plan, and ledger changes
123
+ from Step 2. Make one commit.
124
+
125
+ feat: export reports as CSV
126
+
127
+ - streaming serializer for large result sets
128
+ - /reports/export route
129
+ - empty and error states
130
+
131
+ Conventional prefix, a subject saying what the change does, and a short body naming what
132
+ changed. Never a plan number, a roadmap reference, or any AI attribution: someone reading
133
+ this history later has none of those documents open.
134
+
135
+ If checkpoints already committed the steps, this commit carries the bookkeeping and the
136
+ history reads as the build sequence followed by its closing entry. Then offer to squash
137
+ the item into one commit. Squashing rewrites history, so it needs an explicit yes, and it
138
+ is refused outright when any of those commits has already been pushed.
139
+
140
+ ## Step 4 - land it
141
+
142
+ Under **`git.mode: trunk`** the work is already on the branch you were on. There is nothing
143
+ to merge. Go to Step 5.
144
+
145
+ Under **`branch-per-item`**:
146
+
147
+ 1. Squash-merge into the default branch, only with an explicit yes, so the item lands as
148
+ one commit however many checkpoints the branch carried.
149
+ 2. Delete the branch after a clean merge.
150
+ 3. Stop.
151
+
152
+ Then, in either mode, ask separately whether to push. **Approval to merge is not approval
153
+ to push.** Push only after an explicit yes to pushing, in this conversation. If there is no
154
+ remote, say so rather than guessing.
155
+
156
+ ## Step 5 - say how to try it
157
+
158
+ Always end with the manual walkthrough for what just landed: what to start, where to go,
159
+ what to click or run, what to expect, and what would count as wrong. This is instructions
160
+ for a person, never a claim that the review happened.
161
+
162
+ For a rollback, say how to confirm the removed behavior is gone, and name one unaffected
163
+ path that should still work.
164
+
165
+ Then point at what is next: $feature for the next planned item, or $fix.
166
+
167
+ ## Rules
168
+
169
+ - The work item is the unit of history.
170
+ - Do not complete failing or unfinished work. The full `Verify`, or the fallback build and
171
+ tests, must pass first.
172
+ - Never land work while a P0 or P1 finding is `open` or `fixed`. The recorded ways past
173
+ without code are `accepted`, by the user's explicit decision with their reason, or
174
+ `invalid`, backed by review evidence. Both travel into the archive; neither is a silent
175
+ drop.
176
+ - A rollback preserves the original archive and adds its own. Never rewrite history to
177
+ make a feature look as though it never existed.
178
+ - Merging and pushing are the user's calls, and they are two separate calls.
179
+ - One item per completion. A parent with unticked sub-items stays unticked.
180
+
181
+ ## Formatting
182
+
183
+ Match the conventions in `religion/context/ai-interaction.md`: concise, scannable
184
+ markdown, lists for enumerations and tables for matrices rather than dense paragraphs.
@@ -0,0 +1,72 @@
1
+ ---
2
+ name: debug
3
+ summary: reproduce and isolate a failure without changing anything
4
+ description: "Diagnose a failing test, broken build, crash, error, regression, or unexpected behavior without editing source or project state. Reproduces the symptom with the smallest reliable command, localizes the failing path, then tests competing hypotheses in parallel subagents and reports the root cause with the evidence that established it. Hands confirmed repair work to $fix or $implement. Use when the user runs $debug, asks why something is failing or broken, wants a root-cause investigation, or wants to understand a failure before fixing it."
5
+ ---
6
+
7
+ # debug - find out what is actually wrong
8
+
9
+ Diagnosis is separate from repair on purpose. An agent that is allowed to fix while it
10
+ looks will fix three things on the way to understanding one, and none of those changes were
11
+ reviewed against a spec.
12
+
13
+ This skill changes nothing: no source edits, no state files, no commits, no installs.
14
+
15
+ ## Step 1 - reproduce
16
+
17
+ Find the smallest command that reliably shows the failure, and run it. Record the exact
18
+ command, the output, and the exit status.
19
+
20
+ If it does not reproduce, that is the finding. Say what you ran and what happened instead,
21
+ and ask what differs about the environment where it fails. An intermittent failure is
22
+ reported as intermittent, with how many attempts of what kind, rather than treated as
23
+ fixed because the second run passed.
24
+
25
+ ## Step 2 - localize
26
+
27
+ Narrow to the smallest region that still fails. Read the stack trace properly, including
28
+ the parts pointing into dependencies. Check what changed recently in that area.
29
+
30
+ State what you have ruled out, and how. A localization that cannot say what it excluded has
31
+ not narrowed anything.
32
+
33
+ ## Step 3 - test hypotheses in parallel
34
+
35
+ List the plausible causes. For each one, state what would be true if it were the cause and
36
+ what would disprove it. A hypothesis that nothing could disprove is not a hypothesis.
37
+
38
+ Run each as its own subagent, given the reproduction command, the localized region, and one
39
+ hypothesis. Each returns evidence for or against; none of them edits anything. Then weigh
40
+ what comes back.
41
+
42
+ Parallel matters here because hypotheses are independent and reproduction is often slow.
43
+ Four subagents that each run a two-minute reproduction cost two minutes, not eight.
44
+
45
+ Do not stop at the first plausible story. A hypothesis that explains the symptom is not the
46
+ cause until the evidence rules the others out, and the cheapest place to notice that is
47
+ before a repair has been built on it.
48
+
49
+ ## Step 4 - report
50
+
51
+ - **What fails**, and the exact command that shows it.
52
+ - **The cause**, when the evidence supports one, at a specific file and line.
53
+ - **The evidence**, per hypothesis: what was tested, what came back, what it ruled in or
54
+ out.
55
+ - **What is still unknown**, when the evidence was not conclusive. Say that plainly rather
56
+ than presenting the best guess as the answer.
57
+ - **The repair**, described but not made: what would need to change, and roughly how large
58
+ it is.
59
+ - **Next action**: $fix for an unplanned repair, $implement when it belongs to
60
+ work already in progress.
61
+
62
+ ## Rules
63
+
64
+ - Change nothing. No source, no state, no commits, no dependency installs.
65
+ - Report the cause you can prove, not the one you like.
66
+ - A reproduction that fails to reproduce is a result worth reporting.
67
+ - Never present a hypothesis as a conclusion.
68
+
69
+ ## Formatting
70
+
71
+ Match the conventions in `religion/context/ai-interaction.md`: concise, scannable
72
+ markdown, lists for enumerations and tables for matrices rather than dense paragraphs.