create-claude-rails 0.1.2 → 0.3.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/README.md +3 -3
- package/lib/cli.js +103 -17
- package/lib/copy.js +16 -2
- package/lib/metadata.js +3 -2
- package/lib/reset.js +193 -0
- package/package.json +1 -1
- package/templates/EXTENSIONS.md +32 -32
- package/templates/README.md +3 -3
- package/templates/skills/{upgrade → cor-upgrade}/SKILL.md +23 -23
- package/templates/skills/{upgrade → cor-upgrade}/phases/apply.md +3 -3
- package/templates/skills/{upgrade → cor-upgrade}/phases/detect-current.md +14 -14
- package/templates/skills/{upgrade → cor-upgrade}/phases/diff-upstream.md +3 -3
- package/templates/skills/extract/SKILL.md +168 -0
- package/templates/skills/link/SKILL.md +52 -0
- package/templates/skills/onboard/SKILL.md +55 -22
- package/templates/skills/onboard/phases/detect-state.md +21 -39
- package/templates/skills/onboard/phases/generate-context.md +1 -1
- package/templates/skills/onboard/phases/interview.md +86 -72
- package/templates/skills/onboard/phases/modularity-menu.md +21 -18
- package/templates/skills/onboard/phases/options.md +98 -0
- package/templates/skills/onboard/phases/post-onboard-audit.md +20 -2
- package/templates/skills/onboard/phases/summary.md +1 -1
- package/templates/skills/onboard/phases/work-tracking.md +231 -0
- package/templates/skills/perspectives/_groups-template.yaml +1 -1
- package/templates/skills/perspectives/architecture/SKILL.md +275 -0
- package/templates/skills/perspectives/box-health/SKILL.md +8 -8
- package/templates/skills/perspectives/data-integrity/SKILL.md +2 -2
- package/templates/skills/perspectives/documentation/SKILL.md +4 -5
- package/templates/skills/perspectives/historian/SKILL.md +250 -0
- package/templates/skills/perspectives/process/SKILL.md +3 -3
- package/templates/skills/perspectives/skills-coverage/SKILL.md +294 -0
- package/templates/skills/perspectives/system-advocate/SKILL.md +191 -0
- package/templates/skills/perspectives/usability/SKILL.md +186 -0
- package/templates/skills/publish/SKILL.md +72 -0
- package/templates/skills/seed/phases/scan-signals.md +7 -3
- package/templates/skills/unlink/SKILL.md +35 -0
- /package/templates/skills/{upgrade → cor-upgrade}/phases/merge.md +0 -0
|
@@ -0,0 +1,52 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: link
|
|
3
|
+
description: |
|
|
4
|
+
Set up local development linking for Claude on Rails. Detects whether
|
|
5
|
+
you're in the CoR source repo or a consuming project and runs the
|
|
6
|
+
appropriate npm link command. Use when: "link", "local dev", "use local
|
|
7
|
+
CoR", "/link".
|
|
8
|
+
---
|
|
9
|
+
|
|
10
|
+
# /link — Local Development Linking
|
|
11
|
+
|
|
12
|
+
## Purpose
|
|
13
|
+
|
|
14
|
+
Connect a consuming project to a local checkout of Claude on Rails so
|
|
15
|
+
template changes are immediately available without publishing to npm.
|
|
16
|
+
|
|
17
|
+
## Context Detection
|
|
18
|
+
|
|
19
|
+
Before doing anything, determine where you are:
|
|
20
|
+
|
|
21
|
+
**CoR source repo** (`package.json` has `name: "create-claude-rails"`):
|
|
22
|
+
- Run `npm link` to register the package globally
|
|
23
|
+
- This makes the local checkout available to any project that links to it
|
|
24
|
+
- Tell the user: "Registered locally. In your other projects, run `/link`
|
|
25
|
+
to connect them to this checkout."
|
|
26
|
+
|
|
27
|
+
**Any other project** (anything that isn't the CoR source repo):
|
|
28
|
+
- Run `npm link create-claude-rails` to point to the local CoR checkout
|
|
29
|
+
- Verify it worked: check that `npx create-claude-rails --help` resolves
|
|
30
|
+
to the local version
|
|
31
|
+
- If CoR is already installed (`.corrc.json` exists): "Linked to local
|
|
32
|
+
CoR. Run `/cor-upgrade` to pull template changes into your installed
|
|
33
|
+
skills."
|
|
34
|
+
- If CoR is not yet installed: "Linked to local CoR. Run
|
|
35
|
+
`npx create-claude-rails` to install."
|
|
36
|
+
|
|
37
|
+
## Prerequisites
|
|
38
|
+
|
|
39
|
+
The CoR source repo must have been linked first (`npm link` from the CoR
|
|
40
|
+
directory). If a consuming project tries to link and the global link
|
|
41
|
+
doesn't exist, npm will error. In that case, tell the user to run `/link`
|
|
42
|
+
in their CoR checkout first.
|
|
43
|
+
|
|
44
|
+
## What This Encodes
|
|
45
|
+
|
|
46
|
+
- `npm link` (in source) registers a global symlink to the package
|
|
47
|
+
- `npm link create-claude-rails` (in consumer) creates a local symlink
|
|
48
|
+
to the globally registered package
|
|
49
|
+
- The link survives across terminal sessions
|
|
50
|
+
- The link uses whatever is on disk — no version pinning, no caching
|
|
51
|
+
- After linking, `npx create-claude-rails` and `/cor-upgrade` both
|
|
52
|
+
resolve to the local checkout
|
|
@@ -2,16 +2,22 @@
|
|
|
2
2
|
name: onboard
|
|
3
3
|
description: |
|
|
4
4
|
Conversational interview that generates the initial context layer for a
|
|
5
|
-
project adopting
|
|
5
|
+
project adopting Claude on Rails. Re-runnable at different maturity stages — each run
|
|
6
6
|
refines based on what the project has learned. Use when: "onboard",
|
|
7
|
-
"set up
|
|
7
|
+
"set up CoR", "bootstrap", "/onboard".
|
|
8
8
|
related:
|
|
9
9
|
- type: file
|
|
10
10
|
path: .claude/skills/onboard/phases/detect-state.md
|
|
11
|
-
role: "Detect existing
|
|
11
|
+
role: "Detect existing CoR artifacts and determine run mode"
|
|
12
12
|
- type: file
|
|
13
13
|
path: .claude/skills/onboard/phases/interview.md
|
|
14
14
|
role: "Conversational interview questions"
|
|
15
|
+
- type: file
|
|
16
|
+
path: .claude/skills/onboard/phases/work-tracking.md
|
|
17
|
+
role: "Choose work tracking system (SQLite vs markdown vs external)"
|
|
18
|
+
- type: file
|
|
19
|
+
path: .claude/skills/onboard/phases/options.md
|
|
20
|
+
role: "Structured decision points before generation"
|
|
15
21
|
- type: file
|
|
16
22
|
path: .claude/skills/onboard/phases/generate-context.md
|
|
17
23
|
role: "Generate or update context files"
|
|
@@ -33,7 +39,7 @@ related:
|
|
|
33
39
|
|
|
34
40
|
## Purpose
|
|
35
41
|
|
|
36
|
-
Generate the context layer that makes every other
|
|
42
|
+
Generate the context layer that makes every other CoR skill work. Without
|
|
37
43
|
context — what is this project, what stack does it use, what breaks, who
|
|
38
44
|
works on it — the session loop runs blind. Orient reads files that don't
|
|
39
45
|
exist yet. Debrief records lessons into a structure that hasn't been
|
|
@@ -69,7 +75,7 @@ Onboard is re-runnable. What it does depends on what already exists:
|
|
|
69
75
|
|
|
70
76
|
### 1. First Run (no _context.md)
|
|
71
77
|
|
|
72
|
-
No
|
|
78
|
+
No CoR context layer exists yet. This is the full interview: who are you,
|
|
73
79
|
what is this, what breaks, what do you need. Generates the complete
|
|
74
80
|
initial context layer — `_context.md`, CLAUDE.md additions, system-status.md,
|
|
75
81
|
and session loop wiring. The goal is a working session loop by the end of
|
|
@@ -77,7 +83,7 @@ the conversation.
|
|
|
77
83
|
|
|
78
84
|
### 2. Early Re-Run (sparse artifacts)
|
|
79
85
|
|
|
80
|
-
Some
|
|
86
|
+
Some CoR artifacts exist but the project is young. The session loop has
|
|
81
87
|
run a few times and the user has learned what works and what doesn't.
|
|
82
88
|
The interview shifts to refinement: What has the session loop taught you
|
|
83
89
|
that CLAUDE.md doesn't reflect? What friction have you hit? What context
|
|
@@ -86,7 +92,7 @@ existing files rather than creating new ones.
|
|
|
86
92
|
|
|
87
93
|
### 3. Mature Re-Run (rich context)
|
|
88
94
|
|
|
89
|
-
The project has been using
|
|
95
|
+
The project has been using CoR for a while. Context files are populated,
|
|
90
96
|
multiple modules are active, patterns have accumulated. The interview
|
|
91
97
|
becomes a health check: Which modules are you actually using? Is anything
|
|
92
98
|
ready to retire? What gaps have you noticed? Are there new areas the
|
|
@@ -98,7 +104,7 @@ doesn't have to declare it.
|
|
|
98
104
|
|
|
99
105
|
## Why This Matters
|
|
100
106
|
|
|
101
|
-
Every
|
|
107
|
+
Every CoR skill reads from the context layer. Orient reads `_context.md`
|
|
102
108
|
to know what files to check. Plan reads it to know where work items live.
|
|
103
109
|
Perspectives read it to know where to look. If the context layer is empty
|
|
104
110
|
or wrong, every skill downstream is degraded. Onboard is the foundation
|
|
@@ -113,9 +119,9 @@ the periodic recalibration that keeps the context layer honest.
|
|
|
113
119
|
|
|
114
120
|
### 1. Detect State
|
|
115
121
|
|
|
116
|
-
Read `phases/detect-state.md` for how to scan existing
|
|
122
|
+
Read `phases/detect-state.md` for how to scan existing CoR artifacts.
|
|
117
123
|
|
|
118
|
-
**Default (absent/empty):** Scan for the standard
|
|
124
|
+
**Default (absent/empty):** Scan for the standard CoR artifact set:
|
|
119
125
|
`_context.md`, `system-status.md`, `orient/phases/`, `debrief/phases/`,
|
|
120
126
|
`pib.db`, `_groups.yaml`, `memory/patterns/`. Count what exists, classify
|
|
121
127
|
its richness (empty file vs populated), and determine the run mode. Report
|
|
@@ -149,12 +155,37 @@ by now?
|
|
|
149
155
|
|
|
150
156
|
This is a conversation, not a form. Ask 2-3 questions at a time, not all
|
|
151
157
|
at once. Follow up on answers — if the user mentions a pain point, dig
|
|
152
|
-
into it. If something sounds like it maps to a specific
|
|
158
|
+
into it. If something sounds like it maps to a specific CoR module, note
|
|
153
159
|
it for the modularity menu phase. The interview is the most valuable
|
|
154
160
|
phase because it captures knowledge that no amount of file scanning can
|
|
155
161
|
surface.
|
|
156
162
|
|
|
157
|
-
### 3.
|
|
163
|
+
### 3. Work Tracking
|
|
164
|
+
|
|
165
|
+
Read `phases/work-tracking.md` for how to present work tracking options.
|
|
166
|
+
|
|
167
|
+
**Default (absent/empty):** Detect existing work tracking (pib.db,
|
|
168
|
+
tasks.md, GitHub Issues, custom phase files). Present two built-in
|
|
169
|
+
options — SQLite database (pib-db) or markdown file (tasks.md) — plus
|
|
170
|
+
bring-your-own for external systems. User picks one, the other, or
|
|
171
|
+
neither. The choice is recorded in `.corrc.json` under `workTracking`
|
|
172
|
+
and feeds into generate-context and generate-session-loop.
|
|
173
|
+
|
|
174
|
+
### 4. Options
|
|
175
|
+
|
|
176
|
+
Read `phases/options.md` for how to present structured decision points.
|
|
177
|
+
|
|
178
|
+
**Default (absent/empty):** If the interview revealed open decisions
|
|
179
|
+
(tech stack undecided, architecture unclear, "what would you recommend?"),
|
|
180
|
+
present 2-3 options per decision with trade-offs. Uses architecture and
|
|
181
|
+
boundary-conditions perspectives internally to evaluate each option.
|
|
182
|
+
Skips automatically when the user already has clear opinions or this is
|
|
183
|
+
a re-run.
|
|
184
|
+
|
|
185
|
+
The user's choices feed into generate-context. Deferred decisions are
|
|
186
|
+
noted as open questions in `_context.md`.
|
|
187
|
+
|
|
188
|
+
### 5. Generate Context
|
|
158
189
|
|
|
159
190
|
Read `phases/generate-context.md` for how to create or update the context
|
|
160
191
|
layer from interview answers.
|
|
@@ -173,7 +204,7 @@ would change as diffs — never overwrite without showing the delta. Let
|
|
|
173
204
|
the user approve, modify, or reject each change. The user owns their
|
|
174
205
|
context files; onboard proposes, never imposes.
|
|
175
206
|
|
|
176
|
-
###
|
|
207
|
+
### 6. Generate Session Loop
|
|
177
208
|
|
|
178
209
|
Read `phases/generate-session-loop.md` for how to wire orient and debrief
|
|
179
210
|
phase files.
|
|
@@ -196,9 +227,9 @@ In re-run mode, examine existing phase files and propose refinements based
|
|
|
196
227
|
on what the interview surfaced. If the user said "orient never shows me X,"
|
|
197
228
|
that's a signal to update the work-scan or health-checks phase.
|
|
198
229
|
|
|
199
|
-
###
|
|
230
|
+
### 7. Modularity Menu
|
|
200
231
|
|
|
201
|
-
Read `phases/modularity-menu.md` for which
|
|
232
|
+
Read `phases/modularity-menu.md` for which CoR modules to present.
|
|
202
233
|
|
|
203
234
|
**Default (absent/empty):** Present the module hierarchy with adoption
|
|
204
235
|
recommendations based on the interview. The session loop is always set up.
|
|
@@ -209,7 +240,7 @@ they can always add more later.
|
|
|
209
240
|
In re-run mode, show what's adopted alongside what's available. Surface
|
|
210
241
|
retirement candidates — modules that were adopted but aren't being used.
|
|
211
242
|
|
|
212
|
-
###
|
|
243
|
+
### 8. Summary
|
|
213
244
|
|
|
214
245
|
Read `phases/summary.md` for how to present results.
|
|
215
246
|
|
|
@@ -221,7 +252,7 @@ through use as orient and debrief reveal what's missing.
|
|
|
221
252
|
In re-run mode, present a before/after view: what the context layer
|
|
222
253
|
looked like before, what changed, and why.
|
|
223
254
|
|
|
224
|
-
###
|
|
255
|
+
### 9. Post-Onboard Audit
|
|
225
256
|
|
|
226
257
|
Read `phases/post-onboard-audit.md` for the configuration sanity check.
|
|
227
258
|
|
|
@@ -240,8 +271,10 @@ pre-flight check, not a deferred finding.
|
|
|
240
271
|
|
|
241
272
|
| Phase | Absent = | What it customizes |
|
|
242
273
|
|-------|----------|-------------------|
|
|
243
|
-
| `detect-state.md` | Default: scan standard
|
|
274
|
+
| `detect-state.md` | Default: scan standard CoR artifacts | What artifacts to scan and how to determine mode |
|
|
244
275
|
| `interview.md` | Default: mode-adapted questions | What to ask and how to follow up |
|
|
276
|
+
| `work-tracking.md` | Default: detect & present choices | What work tracking system to use (pib-db, markdown, or external) |
|
|
277
|
+
| `options.md` | Default: present decisions with trade-offs | What decisions to surface and how to frame options |
|
|
245
278
|
| `generate-context.md` | Default: create/update _context.md, CLAUDE.md, system-status.md | What files to generate and how |
|
|
246
279
|
| `generate-session-loop.md` | Default: wire orient/debrief phases | How to set up the session loop |
|
|
247
280
|
| `modularity-menu.md` | Default: present module hierarchy | Which modules to present and how |
|
|
@@ -254,7 +287,7 @@ Onboard is a companion, not a configurator. The framing is "let's figure
|
|
|
254
287
|
out what your project needs" — not "I'll set up your system now." The
|
|
255
288
|
interview is genuine curiosity about the project, not a checklist to get
|
|
256
289
|
through. When the user describes a pain point, the right response is to
|
|
257
|
-
understand it, not to immediately map it to a
|
|
290
|
+
understand it, not to immediately map it to a CoR module.
|
|
258
291
|
|
|
259
292
|
This matters because the quality of the context layer depends on the
|
|
260
293
|
quality of the conversation. A mechanical interview produces mechanical
|
|
@@ -284,13 +317,13 @@ Examples of phases mature adopters add:
|
|
|
284
317
|
|
|
285
318
|
## Calibration
|
|
286
319
|
|
|
287
|
-
**Core failure this targets:** Starting
|
|
320
|
+
**Core failure this targets:** Starting CoR adoption with empty context
|
|
288
321
|
files, causing the session loop to run without knowing anything about the
|
|
289
322
|
project it's supposed to help.
|
|
290
323
|
|
|
291
324
|
### Without Skill (Bad)
|
|
292
325
|
|
|
293
|
-
A project adopts
|
|
326
|
+
A project adopts CoR. They copy the skeleton files, run `/orient` — it
|
|
294
327
|
reads a blank `_context.md` and an empty `system-status.md`, reports
|
|
295
328
|
nothing useful. They run `/debrief` — it tries to close work items but
|
|
296
329
|
doesn't know where work is tracked. They create a plan — perspectives
|
|
@@ -305,7 +338,7 @@ discovering context gaps one at a time.
|
|
|
305
338
|
|
|
306
339
|
### With Skill (Good)
|
|
307
340
|
|
|
308
|
-
A project adopts
|
|
341
|
+
A project adopts CoR and runs `/onboard`. The interview asks what the
|
|
309
342
|
project is, what stack it uses, what hurts. The user mentions they have a
|
|
310
343
|
Rails app with a PostgreSQL database, three developers, and a recurring
|
|
311
344
|
problem with stale feature flags. From the conversation, onboard generates
|
|
@@ -1,76 +1,58 @@
|
|
|
1
|
-
# Detect State — Scan
|
|
1
|
+
# Detect State — Scan Claude on Rails Artifacts and Determine Mode
|
|
2
2
|
|
|
3
|
-
Scan the project for existing
|
|
3
|
+
Scan the project for existing CoR artifacts to determine whether this is
|
|
4
4
|
a first run, early re-run, or mature re-run. The mode determination
|
|
5
5
|
drives how every subsequent phase behaves.
|
|
6
6
|
|
|
7
7
|
When this file is absent or empty, the default behavior is: scan for the
|
|
8
|
-
standard
|
|
8
|
+
standard CoR artifact set, classify each artifact's richness, and
|
|
9
9
|
determine the mode. To explicitly skip state detection (force first-run
|
|
10
10
|
mode), write only `skip: true`.
|
|
11
11
|
|
|
12
|
-
##
|
|
12
|
+
## Fast Path
|
|
13
13
|
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
14
|
+
Check for `_context.md` (or `.claude/skills/perspectives/_context.md`).
|
|
15
|
+
If it doesn't exist, the mode is **first-run** — skip the full scan and
|
|
16
|
+
move to the interview immediately. No need to check 10 artifact types
|
|
17
|
+
when the primary signal is absent.
|
|
17
18
|
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
19
|
+
Also read `.corrc.json` if it exists — it records which modules the CLI
|
|
20
|
+
installed and which were skipped (with reasons). The interview phase uses
|
|
21
|
+
this to skip redundant questions.
|
|
21
22
|
|
|
22
|
-
|
|
23
|
-
interview phase uses this to skip redundant questions and the modularity
|
|
24
|
-
menu uses `skipped` reasons to ask about alternatives.
|
|
23
|
+
## Full Scan (re-runs only)
|
|
25
24
|
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
Check for these artifacts and classify each as absent, empty, or populated:
|
|
25
|
+
Only when `_context.md` exists, scan these artifacts to distinguish
|
|
26
|
+
early vs mature re-run:
|
|
29
27
|
|
|
30
28
|
| Artifact | Path Pattern | Indicates |
|
|
31
29
|
|----------|-------------|-----------|
|
|
32
|
-
| Project context | `_context.md` or `.claude/skills/perspectives/_context.md` | Context layer exists |
|
|
33
30
|
| System status | `system-status.md` | State tracking exists |
|
|
34
31
|
| Orient phases | `.claude/skills/orient/phases/*.md` | Session loop is wired |
|
|
35
32
|
| Debrief phases | `.claude/skills/debrief/phases/*.md` | Session loop is wired |
|
|
36
33
|
| Work tracking DB | `pib.db` | Work tracking is active |
|
|
37
34
|
| Perspective groups | `_groups.yaml` or `.claude/skills/perspectives/_groups.yaml` | Audit system configured |
|
|
38
|
-
| Memory patterns | `memory/patterns/*.md` | Feedback loop is active |
|
|
35
|
+
| Memory patterns | `memory/patterns/*.md` or `.claude/memory/patterns/*.md` | Feedback loop is active |
|
|
39
36
|
| CLAUDE.md | Root `CLAUDE.md` | Project instructions exist |
|
|
40
37
|
| Rules files | `.claude/rules/*.md` | Scoped instructions exist |
|
|
41
38
|
| Hook config | `.claude/settings.json` or `.claude/settings.local.json` | Enforcement hooks exist |
|
|
42
39
|
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
**First run:** `_context.md` does not exist. No PIB context layer has been
|
|
46
|
-
generated yet. Even if other artifacts exist (e.g., a CLAUDE.md written
|
|
47
|
-
by hand), the absence of the generated context file means onboard hasn't
|
|
48
|
-
run before.
|
|
49
|
-
|
|
50
|
-
**Early re-run:** `_context.md` exists but the artifact set is sparse.
|
|
51
|
-
Fewer than 5 of the scanned artifacts are populated. The session loop
|
|
52
|
-
may be wired but modules like work tracking, audit, and enforcement are
|
|
53
|
-
not yet active. The project is young — it has been through a few sessions
|
|
54
|
-
but hasn't accumulated rich process infrastructure.
|
|
55
|
-
|
|
56
|
-
**Mature re-run:** `_context.md` exists and 5 or more scanned artifacts
|
|
57
|
-
are populated. The project has a working session loop, some form of work
|
|
58
|
-
tracking, and at least one additional module (audit, enforcement, or
|
|
59
|
-
memory). The context layer has had time to accumulate gaps and drift.
|
|
40
|
+
**Early re-run:** Fewer than 5 of the above are populated.
|
|
41
|
+
**Mature re-run:** 5 or more are populated.
|
|
60
42
|
|
|
61
43
|
## Output
|
|
62
44
|
|
|
63
|
-
|
|
45
|
+
For first-run: `Mode: first-run` — that's it. Move on.
|
|
46
|
+
|
|
47
|
+
For re-runs, report a structured summary that subsequent phases can
|
|
64
48
|
reference:
|
|
65
49
|
|
|
66
50
|
```
|
|
67
|
-
Mode:
|
|
51
|
+
Mode: early-rerun | mature-rerun
|
|
68
52
|
|
|
69
53
|
Artifacts found:
|
|
70
|
-
- _context.md: populated (last modified 2026-03-15)
|
|
71
54
|
- system-status.md: populated
|
|
72
55
|
- orient phases: 3 files (context.md, work-scan.md, health-checks.md)
|
|
73
|
-
- debrief phases: 2 files (inventory.md, update-state.md)
|
|
74
56
|
- pib.db: absent
|
|
75
57
|
- memory patterns: 4 files
|
|
76
58
|
...
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# Generate Context — Create or Update Context Files
|
|
2
2
|
|
|
3
|
-
Transform interview answers into the files that make the rest of
|
|
3
|
+
Transform interview answers into the files that make the rest of Claude on Rails
|
|
4
4
|
functional. This is where conversation becomes infrastructure — but it
|
|
5
5
|
is always a proposal, never an imposition.
|
|
6
6
|
|
|
@@ -5,7 +5,7 @@ listen to answers, follow up on what's interesting or unclear. The quality
|
|
|
5
5
|
of the context layer depends directly on the quality of this conversation.
|
|
6
6
|
|
|
7
7
|
When this file is absent or empty, the default behavior is: ask mode-
|
|
8
|
-
adapted questions as described below,
|
|
8
|
+
adapted questions as described below, one at a time, with follow-ups.
|
|
9
9
|
To explicitly skip the interview (e.g., when generating context from
|
|
10
10
|
existing documentation), write only `skip: true`.
|
|
11
11
|
|
|
@@ -60,7 +60,7 @@ are valid starting points.
|
|
|
60
60
|
|
|
61
61
|
## First-Run Questions
|
|
62
62
|
|
|
63
|
-
The detect-state phase identified this as a first run (no
|
|
63
|
+
The detect-state phase identified this as a first run (no CoR context
|
|
64
64
|
layer exists). But "first run" covers two very different situations:
|
|
65
65
|
|
|
66
66
|
### Greenfield (no project yet, or near-empty directory)
|
|
@@ -69,21 +69,17 @@ The user just ran the CLI in an empty or near-empty directory. There's
|
|
|
69
69
|
nothing to scan, no workflow to reflect on yet. Questions must be
|
|
70
70
|
**forward-looking** — about intentions, not retrospection.
|
|
71
71
|
|
|
72
|
-
**
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
**Round 3 — Scope and shape (adapt based on Rounds 1-2):**
|
|
84
|
-
- How big is this? A weekend project, something you'll be working on
|
|
85
|
-
for months?
|
|
86
|
-
- What does done look like, roughly?
|
|
72
|
+
**Questions (ask one at a time, in order — skip or reorder based on
|
|
73
|
+
what the conversation reveals):**
|
|
74
|
+
1. What are you trying to build?
|
|
75
|
+
2. What will you be using Claude Code for on this project?
|
|
76
|
+
3. How do you usually keep track of what needs to be done?
|
|
77
|
+
4. Will anyone else be working on this with you?
|
|
78
|
+
5. Have you struggled with anything on past projects that you'd want
|
|
79
|
+
to get ahead of this time?
|
|
80
|
+
6. How big is this? A weekend project, something you'll be working on
|
|
81
|
+
for months?
|
|
82
|
+
7. What does done look like, roughly?
|
|
87
83
|
|
|
88
84
|
**Follow-up instincts:**
|
|
89
85
|
- If they describe something ambitious, ask what the first milestone is
|
|
@@ -98,26 +94,23 @@ The user ran the CLI in a project that already has substance. There are
|
|
|
98
94
|
files to scan — use them for tech detection instead of asking. Focus the
|
|
99
95
|
conversation on **work and pain**, not tooling.
|
|
100
96
|
|
|
101
|
-
**Before
|
|
97
|
+
**Before asking:** Scan the project for tech signals (package.json,
|
|
102
98
|
Cargo.toml, requirements.txt, Dockerfile, .github/, etc.). Note what
|
|
103
99
|
you find — it informs your follow-ups but doesn't replace the
|
|
104
100
|
conversation. Don't announce what you found; weave it in naturally.
|
|
105
101
|
|
|
106
|
-
**
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
- How do you currently keep track of what needs to be done?
|
|
119
|
-
- What does a typical working session on this project look like?
|
|
120
|
-
- Is there a deploy pipeline or remote environment?
|
|
102
|
+
**Questions (ask one at a time, in order — skip or reorder based on
|
|
103
|
+
what the conversation reveals):**
|
|
104
|
+
1. Tell me about this project. What does it do?
|
|
105
|
+
2. What are you mainly working on right now?
|
|
106
|
+
3. What tends to break or get forgotten?
|
|
107
|
+
4. What do you wish Claude knew about this project from the very start
|
|
108
|
+
of every session?
|
|
109
|
+
5. Is there anything that fails silently — things that go wrong without
|
|
110
|
+
anyone noticing until it's too late?
|
|
111
|
+
6. How do you currently keep track of what needs to be done?
|
|
112
|
+
7. What does a typical working session on this project look like?
|
|
113
|
+
8. Is there a deploy pipeline or remote environment?
|
|
121
114
|
|
|
122
115
|
**Follow-up instincts:**
|
|
123
116
|
- If someone mentions a pain point, ask *why* it happens and how often
|
|
@@ -131,63 +124,84 @@ conversation. Don't announce what you found; weave it in naturally.
|
|
|
131
124
|
The session loop has been running. Shift from "what is this" to "what
|
|
132
125
|
have you learned."
|
|
133
126
|
|
|
134
|
-
**
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
- Has the project changed since the initial onboard? New components,
|
|
148
|
-
shifted priorities, different pain points?
|
|
149
|
-
- Are you ready for any of the modules you skipped last time?
|
|
150
|
-
- Anything you've been doing manually that should be automated?
|
|
127
|
+
**Questions (ask one at a time, in order — skip or reorder based on
|
|
128
|
+
what the conversation reveals):**
|
|
129
|
+
1. What has the session loop taught you that the context files don't
|
|
130
|
+
currently capture?
|
|
131
|
+
2. Does orient give you what you need at session start? What's missing?
|
|
132
|
+
3. Does debrief close the right loops? What falls through?
|
|
133
|
+
4. Where have you hit friction with the current setup?
|
|
134
|
+
5. Are there things you keep having to tell Claude that should already be
|
|
135
|
+
in the context?
|
|
136
|
+
6. Any phase files that aren't pulling their weight?
|
|
137
|
+
7. Has the project changed since the initial onboard?
|
|
138
|
+
8. Are you ready for any of the modules you skipped last time?
|
|
139
|
+
9. Anything you've been doing manually that should be automated?
|
|
151
140
|
|
|
152
141
|
## Mature Re-Run Questions
|
|
153
142
|
|
|
154
143
|
The system has been running long enough to accumulate both value and
|
|
155
144
|
cruft. This is a health check.
|
|
156
145
|
|
|
157
|
-
**
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
|
|
166
|
-
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
|
|
174
|
-
|
|
175
|
-
|
|
146
|
+
**Questions (ask one at a time, in order — skip or reorder based on
|
|
147
|
+
what the conversation reveals):**
|
|
148
|
+
1. Which modules are you actually using regularly?
|
|
149
|
+
2. Anything that felt useful at first but you've stopped relying on?
|
|
150
|
+
3. Are there modules you adopted but never really configured properly?
|
|
151
|
+
4. What gaps have you noticed? Things the system should catch but doesn't.
|
|
152
|
+
5. Has the project's architecture or priorities shifted since the last
|
|
153
|
+
onboard run?
|
|
154
|
+
6. Any new pain points that weren't there before?
|
|
155
|
+
7. Is anything ready to retire?
|
|
156
|
+
8. Could any of your custom phase files be simplified now that you know
|
|
157
|
+
what you actually need?
|
|
158
|
+
9. Are there patterns in your memory/feedback that suggest a structural
|
|
159
|
+
change rather than another rule?
|
|
160
|
+
|
|
161
|
+
## Scope Boundary
|
|
162
|
+
|
|
163
|
+
You are configuring the **process layer** — what Claude should know about
|
|
164
|
+
this project, how sessions start and end, what to track and check. You
|
|
165
|
+
are NOT:
|
|
166
|
+
|
|
167
|
+
- Recommending tech stacks, frameworks, or architecture
|
|
168
|
+
- Advising on what to build or how to build it
|
|
169
|
+
- Making product decisions
|
|
170
|
+
|
|
171
|
+
If the user asks "what should I use?" or "what do you recommend?" for
|
|
172
|
+
their actual project, redirect: "That's a great question for your first
|
|
173
|
+
working session after we finish setup. Right now I'm just learning about
|
|
174
|
+
your project so the session loop knows what to look for. What do you
|
|
175
|
+
know so far about what you'll be building?"
|
|
176
|
+
|
|
177
|
+
Record what they tell you about their intentions and tools — that goes
|
|
178
|
+
into `_context.md`. But choosing those tools is their decision, not
|
|
179
|
+
onboard's job.
|
|
176
180
|
|
|
177
181
|
## Conversation Guidelines
|
|
178
182
|
|
|
179
|
-
- **
|
|
183
|
+
- **One question at a time.** Ask a single question, wait for the answer,
|
|
184
|
+
then ask the next one. Never stack multiple questions in one message.
|
|
185
|
+
The rounds below are a *sequence*, not a batch — each bullet is its own
|
|
186
|
+
turn. Follow-ups based on the answer take priority over the next
|
|
187
|
+
planned question.
|
|
180
188
|
- **Follow up on substance.** If an answer reveals something important,
|
|
181
189
|
dig into it before moving on to the next topic.
|
|
182
|
-
- **Note
|
|
190
|
+
- **Note CoR module signals.** When someone describes a pain point that
|
|
183
191
|
maps to a specific module, note it internally for the modularity menu
|
|
184
192
|
phase — but don't interrupt the conversation to pitch the module.
|
|
185
193
|
- **Don't assume answers.** Even if you can see the project's files, ask
|
|
186
194
|
about things like pain points and priorities that only the user knows.
|
|
195
|
+
- **Earn the right to ask about specifics.** Don't ask about tech stack,
|
|
196
|
+
deployment pipelines, or architecture until the conversation has shown
|
|
197
|
+
the user has context to give a meaningful answer. Lead with open
|
|
198
|
+
questions ("tell me about this project") and let specifics emerge
|
|
199
|
+
naturally. If the user is non-technical or early in their thinking,
|
|
200
|
+
those questions may never be appropriate — and that's fine.
|
|
187
201
|
- **Summarize before generating.** After the interview, reflect back what
|
|
188
202
|
you heard: "Here's what I'm taking away from this conversation..." Let
|
|
189
203
|
the user correct before generating files.
|
|
190
|
-
- **For skipped modules (.
|
|
204
|
+
- **For skipped modules (.corrc.json):** If the CLI's `skipped` field
|
|
191
205
|
shows a module was opted out with a reason, weave that into the
|
|
192
206
|
conversation naturally. "I see you're tracking work somewhere else —
|
|
193
207
|
tell me about that" rather than "Module work-tracking was skipped."
|