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.
- package/LICENSE +21 -0
- package/README.md +47 -0
- package/dist/bin/religion.js +209 -0
- package/dist/lib/dashboard.js +123 -0
- package/dist/lib/doctor.js +164 -0
- package/dist/lib/install.js +170 -0
- package/dist/lib/paths.js +40 -0
- package/dist/lib/state.js +117 -0
- package/dist/lib/status.js +88 -0
- package/package.json +40 -0
- package/template/.agents/skills/audit/SKILL.md +169 -0
- package/template/.agents/skills/auto/SKILL.md +110 -0
- package/template/.agents/skills/browser-tests/SKILL.md +65 -0
- package/template/.agents/skills/check/SKILL.md +86 -0
- package/template/.agents/skills/ci/SKILL.md +79 -0
- package/template/.agents/skills/complete/SKILL.md +184 -0
- package/template/.agents/skills/debug/SKILL.md +72 -0
- package/template/.agents/skills/discovery/SKILL.md +83 -0
- package/template/.agents/skills/distill/SKILL.md +95 -0
- package/template/.agents/skills/doctor/SKILL.md +65 -0
- package/template/.agents/skills/extend/SKILL.md +102 -0
- package/template/.agents/skills/feature/SKILL.md +172 -0
- package/template/.agents/skills/feature/reference/spec-template.md +67 -0
- package/template/.agents/skills/fix/SKILL.md +76 -0
- package/template/.agents/skills/implement/SKILL.md +174 -0
- package/template/.agents/skills/overview/SKILL.md +150 -0
- package/template/.agents/skills/overview/reference/project-overview-template.md +101 -0
- package/template/.agents/skills/prototype/SKILL.md +90 -0
- package/template/.agents/skills/release/SKILL.md +88 -0
- package/template/.agents/skills/rollback/SKILL.md +114 -0
- package/template/.agents/skills/setup/SKILL.md +105 -0
- package/template/.agents/skills/status/SKILL.md +63 -0
- package/template/.agents/skills/tests/SKILL.md +90 -0
- package/template/.agents/skills/try/SKILL.md +59 -0
- package/template/.claude/hooks/guard-rendered-output.mjs +49 -0
- package/template/.claude/hooks/guard-tier-one.mjs +63 -0
- package/template/.claude/hooks/write-handoff.mjs +83 -0
- package/template/.claude/skills/audit/SKILL.md +169 -0
- package/template/.claude/skills/auto/SKILL.md +110 -0
- package/template/.claude/skills/browser-tests/SKILL.md +65 -0
- package/template/.claude/skills/check/SKILL.md +86 -0
- package/template/.claude/skills/ci/SKILL.md +79 -0
- package/template/.claude/skills/complete/SKILL.md +184 -0
- package/template/.claude/skills/debug/SKILL.md +72 -0
- package/template/.claude/skills/discovery/SKILL.md +83 -0
- package/template/.claude/skills/distill/SKILL.md +95 -0
- package/template/.claude/skills/doctor/SKILL.md +65 -0
- package/template/.claude/skills/extend/SKILL.md +102 -0
- package/template/.claude/skills/feature/SKILL.md +172 -0
- package/template/.claude/skills/feature/reference/spec-template.md +67 -0
- package/template/.claude/skills/fix/SKILL.md +76 -0
- package/template/.claude/skills/implement/SKILL.md +174 -0
- package/template/.claude/skills/overview/SKILL.md +150 -0
- package/template/.claude/skills/overview/reference/project-overview-template.md +101 -0
- package/template/.claude/skills/prototype/SKILL.md +90 -0
- package/template/.claude/skills/release/SKILL.md +88 -0
- package/template/.claude/skills/rollback/SKILL.md +114 -0
- package/template/.claude/skills/setup/SKILL.md +105 -0
- package/template/.claude/skills/status/SKILL.md +63 -0
- package/template/.claude/skills/tests/SKILL.md +90 -0
- package/template/.claude/skills/try/SKILL.md +59 -0
- package/template/AGENTS.md +206 -0
- package/template/CLAUDE.md +175 -0
- package/template/religion/.state/README.md +10 -0
- package/template/religion/.state/settings-template.json +19 -0
- package/template/religion/build-plan.md +43 -0
- package/template/religion/config.json +26 -0
- package/template/religion/context/ai-interaction.md +84 -0
- package/template/religion/context/coding-standards.md +77 -0
- package/template/religion/context/current-work.md +8 -0
- package/template/religion/context/findings.md +9 -0
- package/template/religion/context/handoff.md +8 -0
- package/template/religion/context/project-overview.md +8 -0
- package/template/religion/history/features/README.md +8 -0
- package/template/religion/history/fixes/README.md +6 -0
- package/template/religion/history/rollbacks/README.md +7 -0
- package/template/religion/learning/journal.md +7 -0
- package/template/religion/learning/lessons.md +8 -0
- package/template/religion/project-plan.md +49 -0
- 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.
|