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,174 @@
1
+ ---
2
+ name: implement
3
+ summary: build the current spec one reviewed step at a time
4
+ description: "Build the feature, fix, or rollback spec'd in religion/context/current-work.md, one small reviewable step at a time. Implements each step as the smallest change that satisfies its stated outcome, shows the diff and explains it in plain language, proves the outcome with evidence, ticks the step off so progress survives a cleared context, and resumes from the first unchecked step when interrupted. Repairs open high-severity findings as extra reviewed steps and has them re-reviewed independently. Ends with a review packet; the work commit and any merge belong to $complete. Use when the user runs $implement, or asks to build, start, continue, or resume the current work item once its spec is ready."
5
+ ---
6
+
7
+ # implement - build the current spec, one reviewed step at a time
8
+
9
+ Where this sits:
10
+
11
+ feature, fix, or rollback -> [implement] -> complete
12
+ (the spec) (build it) (commit, close it out)
13
+
14
+ The spec was written and reviewed. This skill turns it into code without vibe coding:
15
+ small steps, a visible diff and a plain-language explanation for each, evidence that its
16
+ outcome is met, and iteration until it works.
17
+
18
+ ## Before you start
19
+
20
+ **Read `religion/config.json`.** A missing file means defaults. If it exists but cannot
21
+ be parsed, stop and point at $doctor; a skill that is about to change code must not
22
+ guess past broken configuration.
23
+
24
+ **Read the spec.** If `religion/context/current-work.md` is still the stub, or its status
25
+ is already complete, stop and say to run $feature, $fix, or
26
+ $rollback first.
27
+
28
+ **Take the context.** Conventions from `religion/context/coding-standards.md`, the data
29
+ model from the project overview. Code that ignores them is rework, not progress.
30
+
31
+ **Resuming?** Steps already ticked (`- [x]`) mean this was started earlier and
32
+ interrupted, usually by a cleared context. That is expected and costs nothing. Read which
33
+ steps are done, check the working tree and recent commits to see what actually landed, and
34
+ continue from the **first unchecked step**. Do not start over, and do not re-verify
35
+ completed steps unless something suggests they broke.
36
+
37
+ **A rollback spec** carries `Type: Rollback`. Apply it by recomputing the diff command the
38
+ spec records, confirming it still matches, then applying it in reverse with three-way
39
+ conflict detection and staging it. Show the staged diff and confirm no workflow-owned path
40
+ was touched before presenting the step. Never write the reversal freehand, and never run a
41
+ whole-commit revert: the commits being reversed also carry the archive and plan bookkeeping
42
+ that must survive. On a conflict, stop and report the paths and the later commit involved
43
+ rather than resolving it.
44
+
45
+ ## Step 1 - position the work
46
+
47
+ Read `git.mode`.
48
+
49
+ **`trunk`** (the default) works on the branch already checked out. Do not create a branch.
50
+ If the current branch looks wrong for this work, say so and ask; do not switch or create
51
+ one unprompted.
52
+
53
+ **`branch-per-item`** creates and checks out a branch named from the spec using the
54
+ configured prefix. On a resume the branch exists already, so check it out rather than
55
+ creating a second one.
56
+
57
+ Either way, if the project is not a git repository, say so and ask the user to initialize
58
+ one. The loop needs history to be reviewable.
59
+
60
+ ## Step 2 - build one step
61
+
62
+ Set the spec's status to `in progress` before the first code change of this run, and again
63
+ whenever work resumes after a passing check and touches product code. That invalidates
64
+ stale verification state.
65
+
66
+ Work through the build steps **in order, one at a time**. For each:
67
+
68
+ 1. **Implement just that step.** The smallest change that satisfies its stated outcome.
69
+ Nothing from a later step, nothing nobody asked for.
70
+ 2. **Show the diff**, not whole files.
71
+ 3. **Explain it, and prove it.** What the step delivered, one line per changed file on
72
+ what it does and why, then the outcome shown true with evidence: command output, a
73
+ screenshot, a passing assertion. Keep it concrete; this is the comprehension gate, not
74
+ a ritual. Add a short **how to try it** line when there is a manual path.
75
+ 4. **Verify what the step touched.** Run the focused checks for this change: the relevant
76
+ test, the typecheck, whatever proves this diff. The full `Verify` command runs once
77
+ before the work is completed, so a step does not pay for the whole suite every time.
78
+ Run the full command earlier anyway if a step could plausibly break something far away.
79
+
80
+ With `verification.logicTests: "required"`, a logic change with no configured runner
81
+ stops and points at $tests. With `when-configured`, the gate applies only when a
82
+ test command is declared. When it is on, a step that adds in-scope logic ships a passing
83
+ test in the same diff. Interface and integration steps ride on running it, a screenshot,
84
+ and the build. With `verification.uiEvidence: "required"`, an interface outcome cannot
85
+ pass on build output alone.
86
+
87
+ Never install a runner mid-step unless this spec is what sets that runner up.
88
+ 5. **Iterate until it works.** If it fails, revise and re-test. After two or three
89
+ attempts that do not work, **stop**. Report what each attempt did and why you think it
90
+ is failing, and offer to hand it to $debug, which reproduces the failure and
91
+ tests competing hypotheses in parallel. Do not keep trying variations.
92
+ 6. **Tick the step** (`- [x]`) once its gate is satisfied, so progress survives a cleared
93
+ context. If the step repaired a finding, mark that finding `fixed` and note the repair
94
+ in its resolution line. Never mark it `closed`; see Step 3.
95
+ 7. **Then prompt, according to config.**
96
+
97
+ With `workflow.stepReview: "item"`, do not prompt. Continue to the next step and
98
+ collect everything into one packet at the end. Still stop early for a failed check, a
99
+ decision, a conflict, scope drift, or anything in the first tier of the authority rules.
100
+
101
+ With `stepReview: "every"`, offer only the options that config actually allows:
102
+
103
+ - **Continue** - move to the next step.
104
+ - **Commit checkpoint** - only when `git.checkpoints` is `every-step` or `squash`.
105
+ Choosing it is the approval that authorizes the commit. Commit just this step with a
106
+ conventional message describing what the change does.
107
+ - **Walk me through it** - a deeper, line-level explanation: why this approach, what
108
+ each part does, the gotchas. Then re-ask. A loop back, not a terminal choice.
109
+ - **Stop here** - pause. Say where things stand and how to resume.
110
+
111
+ Use the tool's short input prompt when there is one. When you have just produced a long
112
+ block to read, ask in plain text instead, so the prompt does not cover what is still
113
+ being read.
114
+
115
+ Never batch the whole item into one diff. A diff too large to read means the step was too
116
+ large; split it.
117
+
118
+ ## Step 3 - clear the ledger before handing off
119
+
120
+ Read `religion/context/findings.md`. A P0 or P1 finding that is `open` or `fixed` will
121
+ block completion, so close the loop now rather than discovering it later.
122
+
123
+ For each `open` P0 or P1:
124
+
125
+ 1. **Append it to the spec's build steps** first (`- [ ] Repair F-03 - <title>`), so the
126
+ repair is on the record and survives a cleared context.
127
+ 2. Build it through the same loop as Step 2: smallest change, diff, explanation, evidence.
128
+ 3. Tick the step and mark the finding `fixed`.
129
+
130
+ Then have the repairs re-reviewed. Run $audit over the repaired code **in a
131
+ subagent with fresh context**, and record what it returns. The independence is the point:
132
+ a repair is not done when the code changes, it is done when a review that did not write it
133
+ has looked at the result, because a fix can introduce a worse defect than the one it
134
+ removed. Reviewing your own repair in the context that produced it is not that review.
135
+
136
+ A finding that a user decides not to fix is `accepted`, and only they may set it, with
137
+ their reason recorded. A finding that looks wrong goes back to review to be marked
138
+ `invalid` with evidence. This skill sets neither.
139
+
140
+ ## Step 4 - hand off
141
+
142
+ When every step is built and its gate has passed, stop with a compact review packet:
143
+
144
+ - where the work sits: branch, or the current branch under trunk mode
145
+ - what changed, grouped by file or area
146
+ - checks run, with the exact command and result for each
147
+ - how to try it manually
148
+ - ledger state: any findings still `open` or `fixed`, by identifier
149
+ - known risks, skipped checks, or follow-ups
150
+ - next action, normally $complete
151
+
152
+ Set the spec's status to `verified` immediately before that packet, but only when every
153
+ required command, outcome, and configured gate actually passed. A gate that could not run
154
+ is a blocker, not a pass.
155
+
156
+ Then say that $complete runs the full `Verify`, archives the spec, updates the
157
+ build plan, makes the work commit, and asks separately before any merge or push.
158
+
159
+ ## Rules
160
+
161
+ - One small step per diff, and never a commit before its review gate is satisfied.
162
+ - Explain every change in plain language. Understanding the code is the point.
163
+ - Build only what the spec says. If the spec is wrong or thin, stop and fix the spec
164
+ first. Do not improvise around it.
165
+ - Follow the project's coding standards, including scoping user-owned queries by the
166
+ authenticated identity taken from the server.
167
+ - Checkpoints are optional rollback points. The work commit, any merge, and any push
168
+ belong to $complete.
169
+ - This skill does not merge, push, or complete.
170
+
171
+ ## Formatting
172
+
173
+ Match the conventions in `religion/context/ai-interaction.md`: concise, scannable
174
+ markdown, lists for enumerations and tables for matrices rather than dense paragraphs.
@@ -0,0 +1,150 @@
1
+ ---
2
+ name: overview
3
+ summary: distill the two planning documents into the project's source of truth
4
+ description: "Validate the two user-owned planning documents and generate religion/context/project-overview.md from them, the single source of truth every session loads. Proposes a normalized checkbox build plan when the plan is still loose bullets, separates what the product already does from what is queued, derives a concrete domain model and a code map, and records contradictions as open questions that can block work in the areas they affect. Also runs automatically when the plans have changed since the overview was generated. Use when the user runs $overview, has just written or edited the plans, asks to regenerate the project overview, or when another skill finds the overview stale."
5
+ ---
6
+
7
+ # overview - turn the two plans into the source of truth
8
+
9
+ Where this sits:
10
+
11
+ project-plan.md + build-plan.md -> [this skill] -> project-overview.md
12
+ (what and why) (what order) (what everything reads)
13
+
14
+ The plans are yours: long, rough, written in whatever order made sense at the time. The
15
+ overview is the distilled version every skill reads every session. Regenerating it is
16
+ cheap; working from a stale one is not.
17
+
18
+ ## When this runs
19
+
20
+ **Explicitly**, when the user asks.
21
+
22
+ **Automatically**, when a skill that reads the overview finds it stale. Any skill in that
23
+ position follows the steps below first, reports what changed, and then continues with what
24
+ it was asked to do. Nothing acts on a stale overview.
25
+
26
+ ## Staleness
27
+
28
+ The generated file carries a hash of the two plans it was built from:
29
+
30
+ <!-- religion:source-hash <16 hex characters> -->
31
+
32
+ Compute it exactly this way, so that two runs never disagree and report a false change:
33
+ concatenate the raw bytes of `religion/project-plan.md` then `religion/build-plan.md`
34
+ with nothing between them, take the SHA-256, and use the first 16 characters of the
35
+ lowercase hexadecimal digest.
36
+
37
+ cat religion/project-plan.md religion/build-plan.md | shasum -a 256 | cut -c1-16
38
+
39
+ Recompute it over the current plans. A mismatch means the plans moved and the overview did
40
+ not. A missing stamp means an overview generated before this mechanism existed, or one
41
+ hand-edited; treat both as stale.
42
+
43
+ ## Step 1 - read the plans
44
+
45
+ Read `religion/project-plan.md` and `religion/build-plan.md` in full, plus the existing
46
+ overview when there is one, so that a regeneration can report what changed rather than
47
+ just replacing the file.
48
+
49
+ Sections 6 through 8 of the project plan are optional. A plan that deleted them has not
50
+ made a mistake, and the corresponding overview headings are omitted rather than filled
51
+ with "not applicable".
52
+
53
+ ## Step 2 - validate, and propose fixes for approval
54
+
55
+ Check both plans are usable before generating from them:
56
+
57
+ - **Required sections.** Sections 1 through 5 of the project plan are answered, not left
58
+ as the placeholder prompts they ship with.
59
+ - **Build plan shape.** The build plan is a checkbox list. The loop reads those boxes to
60
+ know what is next and what is done, so a plain bullet list breaks progress tracking.
61
+ - **Item sizing.** Each build-plan item is a feature-sized outcome, not a whole product
62
+ area ("Auth, billing, and dashboard") or a loose task ("Database").
63
+ - **Item kind.** The build plan is for features. An item that describes something broken
64
+ ("search ranking is bad", "the switcher does not remember") is a fix, and an item that
65
+ describes reviewing rather than building ("audit the hook types") is a review pass.
66
+ Both have their own path and their own place in the history, and neither belongs in the
67
+ plan. Point them at $fix and $audit, and propose removing them.
68
+ - **Numbering.** Completed items keep their numbers, since archives refer back to them.
69
+
70
+ When something is wrong, show the exact proposed replacement and ask before writing. These
71
+ two files are the user's. Never edit them silently, and never rewrite prose that is merely
72
+ rough: a plan can be informal and still be usable, and only shape problems that actually
73
+ break the loop are worth proposing a change for.
74
+
75
+ If the user declines a proposed fix, say what will not work as a result and generate
76
+ anyway.
77
+
78
+ ## Step 3 - generate the overview
79
+
80
+ Write `religion/context/project-overview.md` following
81
+ `reference/project-overview-template.md`. Stamp the freshly computed source hash.
82
+
83
+ Three sections are real work rather than distillation.
84
+
85
+ **What it does** and **Roadmap** are deliberately separate. The first is the product's
86
+ identity, taken from section 3; the second is the queue, taken from the build plan. On a
87
+ new project they are nearly the same list. On an established one they barely overlap, and
88
+ collapsing them produces an overview claiming the product's features are whatever three
89
+ small things happen to be queued. Never merge them, and never fill one from the other.
90
+
91
+ **Domain model** turns the plan's list of nouns into concrete shapes with fields and
92
+ relationships. What that means depends on the project: persisted entities for something
93
+ with a database, the shapes read and emitted for a compiler or CLI, the public types and
94
+ their contracts for a library. A project with no database still has a domain model. Write
95
+ what it actually works with and say what kind it is.
96
+
97
+ **Code map** records where things live, derived by looking at the repository rather than
98
+ the plans, since neither plan describes layout. For several packages, name the boundary
99
+ each one owns. Without this, every spec re-derives the layout from scratch.
100
+
101
+ Mark any shape later work will depend on as load-bearing.
102
+
103
+ Derive, do not invent. If the plans do not determine something a section needs, that is an
104
+ open question, not a gap to fill with a plausible guess. The code map is the one exception:
105
+ it is read from the repository, because that is where the answer actually is.
106
+
107
+ ## Step 4 - record open questions
108
+
109
+ Contradictions and gaps go in the **Open questions** section, and each one names what it
110
+ affects:
111
+
112
+ - **Storage engine** (affects: data model, features 3 and 7) - section 5 names
113
+ Postgres while section 4 describes local SQLite files. Resolve in the plans and
114
+ regenerate.
115
+
116
+ The "affects" list is load-bearing, not decoration. Work touching a named area is blocked
117
+ while the question is open, and work elsewhere proceeds normally. Scope each one as
118
+ narrowly as the evidence allows: a question marked as affecting everything stops the
119
+ project, so only write that when it is true.
120
+
121
+ Raise a question only for a real conflict or a real gap that later work will hit. Stylistic
122
+ thinness is not an open question.
123
+
124
+ ## Step 5 - report
125
+
126
+ Lead with what changed, then the questions:
127
+
128
+ - **generated** or **regenerated**, and on a regeneration, what moved: sections added or
129
+ removed, shapes or fields that changed, items that entered or left the roadmap
130
+ - open questions, by title, and what each blocks
131
+ - any plan fix that was proposed, and whether it was applied
132
+ - the next action
133
+
134
+ On a first generation, say so plainly rather than reporting a diff against nothing.
135
+
136
+ ## Rules
137
+
138
+ - The two plans belong to the user. Propose, show the exact change, and wait. Never edit
139
+ them without approval.
140
+ - The overview is derived. Never hand-edit it, and never patch it to work around a plan
141
+ that says something different; fix the plan and regenerate.
142
+ - Derive from the plans only. An overview that states something neither plan supports is
143
+ worse than one with an open question, because nothing later will question it.
144
+ - Do not turn a rough plan into a polished one. Distil what is there.
145
+ - Scope every open question to what it genuinely affects.
146
+
147
+ ## Formatting
148
+
149
+ Match the conventions in `religion/context/ai-interaction.md`: concise, scannable
150
+ markdown, lists for enumerations and tables for matrices rather than dense paragraphs.
@@ -0,0 +1,101 @@
1
+ # <Project Name> - Project Overview
2
+
3
+ <!-- religion:source-hash <computed> -->
4
+
5
+ > <one line on what this project is>
6
+
7
+ ## Problem
8
+
9
+ What is broken today and why it matters, distilled from section 1 of the project plan.
10
+ Two or three sentences.
11
+
12
+ ## Users
13
+
14
+ Who this is for, from section 2. A short list of user kinds and what each needs. Note any
15
+ access tiers, such as anonymous versus signed in.
16
+
17
+ ## What it does
18
+
19
+ What this product already does, from section 3 of the plan. One line each. This is the
20
+ product's identity, not a work queue, and on an established project most of it is already
21
+ built. Mark the headline capability.
22
+
23
+ - **<capability>** - what it gives someone.
24
+
25
+ ## Roadmap
26
+
27
+ What is queued, in build-plan order, with its number. This is the work list, and it is a
28
+ different thing from the section above: on an established project the two barely overlap.
29
+
30
+ 1. **<item>** - what it delivers.
31
+ 2. **<item>** - what it delivers.
32
+
33
+ ## Domain model
34
+
35
+ The concrete shapes this project works with, derived from section 4 and the features that
36
+ use them. Real types with fields and relationships, not a restatement of the vague list in
37
+ the plan. This is usually the section a spec cannot be written without, and the one the
38
+ plan does not directly contain.
39
+
40
+ What belongs here depends on what the project is:
41
+
42
+ - **Stores data** - the persisted models: entities, fields, types, relationships.
43
+ - **Transforms input** (a compiler, a framework, a CLI, a parser) - the shapes it reads,
44
+ the shapes it emits, and the stages between them.
45
+ - **Provides an interface** (a library, a design system) - the public types and the
46
+ contracts they promise.
47
+
48
+ A project with no database is not a project with no domain model. Write the shapes it
49
+ actually works with, and say what kind they are.
50
+
51
+ ### <Shape>
52
+
53
+ - `field` (type) - what it holds
54
+ - relates to <other shape> by <field>
55
+
56
+ Mark anything later work depends on as load-bearing, so a change to it is understood as a
57
+ breaking change rather than an edit.
58
+
59
+ ## Code map
60
+
61
+ Where things live, so that work can name the files it will touch without re-deriving the
62
+ layout every time.
63
+
64
+ - `<path>` - what lives here, and when work belongs in it
65
+
66
+ For a repository with several packages, list them with the boundary each one owns, so it is
67
+ clear which one a given change belongs in.
68
+
69
+ ## Tech stack
70
+
71
+ From section 5, one line each on what it is for.
72
+
73
+ - **<technology>** - its role here
74
+
75
+ ## Monetization
76
+
77
+ From section 6. Omit this heading entirely when the plan has no such section.
78
+
79
+ ## UI and UX
80
+
81
+ From section 7: the look and feel, and the main routes or screens. Omit this heading
82
+ entirely when the plan has no such section.
83
+
84
+ - `/<route>` - what is there
85
+
86
+ ## Deployment
87
+
88
+ From section 8: host, app type, build and start commands, output directory, environment
89
+ variables by name, storage needs, background jobs, health path, domain notes. Omit this
90
+ heading entirely when the plan has no such section.
91
+
92
+ ## Open questions
93
+
94
+ Contradictions and gaps found between the two plans. Each one names what it affects, so
95
+ that work touching that area can be blocked while work elsewhere continues.
96
+
97
+ - **<short title>** (affects: <areas, features, or models>) - what the two plans say that
98
+ cannot both be true, or what is missing that later work will need. Resolve it in the
99
+ plans, then regenerate.
100
+
101
+ Delete this heading when there are none.
@@ -0,0 +1,90 @@
1
+ ---
2
+ name: prototype
3
+ summary: explore the look before building, as throwaway mockups or real components
4
+ description: "Explore how a project should look before the build loop starts. Asks what feel is wanted and which screens to draft, proposes a plan, then writes static mockups sharing one theme file to prototypes/. When the project already uses a component system, offers to prototype in that system instead, so the result is real components rather than something to port. Sits outside the reviewed loop, like scaffolding. Use when the user runs $prototype, names screens to mock up, or asks to explore the layout, theme, or look and feel."
5
+ ---
6
+
7
+ # prototype - lock the look before building it
8
+
9
+ Exploratory work, deliberately outside the spec loop. Deciding how something should look is
10
+ not a reviewable build step, and forcing it through one wastes both.
11
+
12
+ ## Step 1 - decide which kind
13
+
14
+ Look at the project. If it already has a component system with tokens and primitives, offer
15
+ to prototype **in that system**. Otherwise write **static mockups**.
16
+
17
+ | | Static mockups | In the component system |
18
+ | --- | --- | --- |
19
+ | Output | HTML and CSS in `prototypes/` | Real components in the project |
20
+ | Fidelity | Approximate | Exactly what ships |
21
+ | Afterwards | Tokens ported, folder deleted | Nothing to port, nothing to delete |
22
+ | Good for | Deciding a look from nothing | A project whose look is already decided |
23
+
24
+ Static mockups are the default because they are faster to throw away, and throwing away is
25
+ what usually happens to the first three attempts. Prototyping in the real system is better
26
+ once the direction is settled, because the port step is where the approximation creeps back
27
+ in.
28
+
29
+ Say which you propose and why. The user decides.
30
+
31
+ ## Step 2 - ask what is wanted
32
+
33
+ Do not start drawing. Ask:
34
+
35
+ - **The feel**, in adjectives, plus anything to look at: a site, a screenshot, a product
36
+ whose look is close.
37
+ - **Which screens**, and which one matters most. Draft that one first and get it right
38
+ before the others copy its decisions.
39
+ - **Constraints**: dark, light, or both; density; an existing brand.
40
+
41
+ Propose a short plan and get agreement before writing files.
42
+
43
+ ## Step 3 - static mockups
44
+
45
+ Write to `prototypes/`, one file per screen, all sharing `prototypes/theme.css`.
46
+
47
+ **Every colour, size, and spacing value lives in `theme.css` as a variable.** No exceptions.
48
+ That file is the actual output of this work: the mockups are disposable, the token set is
49
+ the decision, and a value hardcoded in one screen is a decision that will not survive.
50
+
51
+ Use realistic content. Placeholder text hides every layout problem worth finding: real
52
+ labels are longer than expected, real lists are emptier, real names break alignment.
53
+
54
+ Draft the primary screen, show it, iterate until it is right, then do the others.
55
+
56
+ ## Step 4 - prototyping in the component system
57
+
58
+ Build the screens with the project's own primitives and tokens, in the project.
59
+
60
+ Add tokens where the design needs values that do not exist yet, in the token layer, never
61
+ inline in a component. If the design fights the system repeatedly, that is a finding worth
62
+ reporting: either the design or the system is wrong, and knowing which is worth more than
63
+ the mockup.
64
+
65
+ These are not throwaway. Say what should be kept, what was a sketch, and what a later work
66
+ item should build on.
67
+
68
+ ## Step 5 - hand off
69
+
70
+ Say which mockups exist and where the tokens live.
71
+
72
+ For static mockups, note that the first build step of the first visual work item ports
73
+ `theme.css` into the project's real stylesheet, and that the folder is deleted once that
74
+ lands. For component prototypes, note there is nothing to port.
75
+
76
+ Then point at $feature. Prototypes inform the plan; they are not a work item.
77
+
78
+ ## Rules
79
+
80
+ - Ask before drawing. A mockup built from a guess wastes the round trip that would have
81
+ prevented it.
82
+ - Every value is a token.
83
+ - Real content, never placeholder text.
84
+ - Static mockups are throwaway and are deleted once consumed. Component prototypes are not.
85
+ - No product logic, no data layer, no routing. This is the look.
86
+
87
+ ## Formatting
88
+
89
+ Match the conventions in `religion/context/ai-interaction.md`: concise, scannable
90
+ markdown, lists for enumerations and tables for matrices rather than dense paragraphs.
@@ -0,0 +1,88 @@
1
+ ---
2
+ name: release
3
+ summary: prepare deployment readiness for Railway, Render, or Vercel
4
+ description: "Prepare a project to deploy to Railway, Render, or Vercel. Reads the plans, commands, package files, and existing provider configuration; creates or updates local configuration and an environment example; runs build and start checks; and reports the environment variables, the smoke-test path, and the blockers. Stops before deploying, creating a remote service, changing a remote environment, pushing, or publishing. Use when the user runs $release, asks about deployment readiness or provider configuration, or names a provider."
5
+ ---
6
+
7
+ # release - get ready to deploy, without deploying
8
+
9
+ Prepares. Does not deploy. Deploying, creating a remote service, changing remote
10
+ environment values, pushing, and publishing all need their own explicit yes, and this skill
11
+ stops before every one of them.
12
+
13
+ Run it after a completed item or a milestone, not as part of the build loop.
14
+
15
+ ## Step 1 - target and shape
16
+
17
+ Take the provider from the argument: `$release railway`, `$release render`, `$release vercel`.
18
+ Without one, read the deployment section of the project plan, and ask if it is not there.
19
+
20
+ Then establish what is actually being deployed, because the answer changes everything: a
21
+ static site, a server-rendered application, a service, a worker, a scheduled job, or several
22
+ of these together.
23
+
24
+ | Provider | Fits |
25
+ | --- | --- |
26
+ | **Railway** | Long-running services, workers, scheduled jobs, and anything wanting a managed database beside it |
27
+ | **Render** | Similar shapes, with static sites and cron as first-class kinds |
28
+ | **Vercel** | Front-end and edge-first applications, static output, serverless functions |
29
+
30
+ If the project's shape fits the chosen provider badly, say so once, plainly, with the
31
+ specific mismatch. Then proceed with what was asked.
32
+
33
+ ## Step 2 - survey
34
+
35
+ - Build and start commands, and the output directory for static output.
36
+ - The runtime version, and whether it is pinned.
37
+ - Every environment variable the code reads, **by name**, found by searching the source
38
+ rather than by trusting a checked-in example file which is usually stale.
39
+ - Data stores, caches, queues, and anything else it expects to exist.
40
+ - Background work: workers, scheduled jobs, migrations that must run before start.
41
+ - A health endpoint, if there is one.
42
+ - Existing provider configuration already in the repository.
43
+
44
+ ## Step 3 - write local configuration
45
+
46
+ Create or update only local files: the provider's configuration file, and an environment
47
+ example listing every variable by name.
48
+
49
+ **Never put a real secret in a file.** The example lists names and describes what each is
50
+ for. A value that looks like a credential is never copied into it, and never printed.
51
+
52
+ Preserve configuration that already exists. Show a diff for anything you change, and say
53
+ why.
54
+
55
+ Migrations that must run before start belong in the release or pre-deploy step the provider
56
+ offers, not in the build. Getting that wrong deploys code against a schema that has not
57
+ moved yet, which is the failure that takes a site down rather than failing a build.
58
+
59
+ ## Step 4 - check locally what can be checked
60
+
61
+ Run the build. Run the start command far enough to see it come up. Hit the health path if
62
+ there is one.
63
+
64
+ A failure here is a blocker, and finding it locally is the entire point of doing this
65
+ before deploying.
66
+
67
+ ## Step 5 - report
68
+
69
+ - **Blockers** first: what would fail, and why.
70
+ - **Environment variables**, by name, marking which have no local value yet.
71
+ - **The exact next step** for that provider, as a command or a console action, so the user
72
+ can take it themselves.
73
+ - **The smoke test**: what to hit after deploying and what should come back.
74
+ - **What was not verified** and cannot be locally: the real database, real credentials,
75
+ cold starts, the domain.
76
+
77
+ ## Rules
78
+
79
+ - Never deploy, create a remote service, change a remote environment, push, or publish.
80
+ Preparing is the whole job.
81
+ - Never write, print, or copy a secret value.
82
+ - Never claim a deployment will work. Report what was checked and what was not.
83
+ - Provider tooling may be used to read state. Using it to change anything is a separate yes.
84
+
85
+ ## Formatting
86
+
87
+ Match the conventions in `religion/context/ai-interaction.md`: concise, scannable
88
+ markdown, lists for enumerations and tables for matrices rather than dense paragraphs.