@jakkrichm/create-nexus-devflow 2.1.0 → 2.2.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 (56) hide show
  1. package/dist/bin/create-nexus-devflow.js +28 -4
  2. package/dist/bin/create-nexus-devflow.js.map +1 -1
  3. package/dist/lib/project-metadata.d.ts +1 -1
  4. package/dist/lib/project-metadata.js +3 -2
  5. package/dist/lib/project-metadata.js.map +1 -1
  6. package/dist/lib/update.js +7 -3
  7. package/dist/lib/update.js.map +1 -1
  8. package/package.json +1 -1
  9. package/template/.agents/skills/adopt/SKILL.md +58 -5
  10. package/template/.agents/skills/doctor/SKILL.md +23 -16
  11. package/template/.agents/skills/implement/SKILL.md +2 -2
  12. package/template/.agents/skills/onboard/SKILL.md +18 -17
  13. package/template/.agents/skills/rollback/SKILL.md +1 -1
  14. package/template/.claude/skills/00-explore/SKILL.md +2 -2
  15. package/template/.claude/skills/10-define/SKILL.md +2 -2
  16. package/template/.claude/skills/20-spec/SKILL.md +1 -2
  17. package/template/.claude/skills/30-plan/SKILL.md +1 -2
  18. package/template/.claude/skills/40-execute/SKILL.md +2 -2
  19. package/template/.claude/skills/50-verify/SKILL.md +2 -2
  20. package/template/.claude/skills/60-report/SKILL.md +2 -2
  21. package/template/.claude/skills/70-deliver/SKILL.md +2 -2
  22. package/template/.claude/skills/adopt/SKILL.md +191 -75
  23. package/template/.claude/skills/audit/SKILL.md +267 -133
  24. package/template/.claude/skills/autopilot/SKILL.md +226 -167
  25. package/template/.claude/skills/brainstorm/SKILL.md +62 -0
  26. package/template/.claude/skills/brief/SKILL.md +93 -92
  27. package/template/.claude/skills/check/SKILL.md +96 -76
  28. package/template/.claude/skills/ci/SKILL.md +140 -61
  29. package/template/.claude/skills/complete/SKILL.md +156 -101
  30. package/template/.claude/skills/convert-any-to-md/SKILL.md +2 -2
  31. package/template/.claude/skills/convert-any-to-md/references/setup.md +29 -0
  32. package/template/.claude/skills/convert-any-to-md/scripts/convert_any_to_md.py +487 -0
  33. package/template/.claude/skills/convert-any-to-md/scripts/requirements.txt +3 -0
  34. package/template/.claude/skills/debug/SKILL.md +124 -49
  35. package/template/.claude/skills/devflow/SKILL.md +9 -3
  36. package/template/.claude/skills/discovery/SKILL.md +150 -129
  37. package/template/.claude/skills/doctor/SKILL.md +195 -72
  38. package/template/.claude/skills/feature/SKILL.md +195 -151
  39. package/template/.claude/skills/fix/SKILL.md +41 -90
  40. package/template/.claude/skills/idea/SKILL.md +2 -2
  41. package/template/.claude/skills/implement/SKILL.md +189 -46
  42. package/template/.claude/skills/onboard/SKILL.md +216 -85
  43. package/template/.claude/skills/overview/SKILL.md +44 -29
  44. package/template/.claude/skills/prototype/SKILL.md +82 -27
  45. package/template/.claude/skills/release/SKILL.md +119 -130
  46. package/template/.claude/skills/report-html/SKILL.md +2 -2
  47. package/template/.claude/skills/rollback/SKILL.md +123 -77
  48. package/template/.claude/skills/status/SKILL.md +109 -0
  49. package/template/.claude/skills/test/SKILL.md +2 -2
  50. package/template/.claude/skills/tests/SKILL.md +126 -0
  51. package/template/.claude/skills/try/SKILL.md +77 -65
  52. package/template/AGENTS.md +2 -1
  53. package/template/devflow/build-plan.md +8 -0
  54. package/template/devflow/history/features/README.md +5 -0
  55. package/template/devflow/history/fixes/README.md +5 -0
  56. package/template/devflow/history/rollbacks/README.md +5 -0
@@ -69,7 +69,7 @@ obsolete overlay content in the product README slot:
69
69
  - Create a small root `README.md` stub for the actual project using the detected
70
70
  project name, one-line purpose when known, and the Commands from `AGENTS.md`.
71
71
  Keep it minimal if the project plan is not filled yet.
72
- - Do not move or copy the workflow document into `blueprint/`. Agents use the
72
+ - Do not move or copy the workflow document into `devflow/`. Agents use the
73
73
  local skills, plans, and context files directly.
74
74
  - Remove any `AGENTS.md` claim that a project README explains the Blueprint
75
75
  workflow.
@@ -91,7 +91,7 @@ If no test command exists, say so explicitly. Do not claim tests are a gate unti
91
91
  a real test command is configured.
92
92
 
93
93
  If `CLAUDE.md` exists and still has the placeholder `# Project Name`, replace it
94
- with the detected project name. Keep the `@AGENTS.md` and `@blueprint/...`
94
+ with the detected project name. Keep the `@AGENTS.md` and `@devflow/...`
95
95
  imports intact. Do not move detailed app context into `CLAUDE.md`; that belongs
96
96
  in `AGENTS.md` and the generated project overview.
97
97
 
@@ -147,17 +147,17 @@ preserving existing entries. Typical examples include dependencies, build output
147
147
  framework caches, logs, environment files, test output, temporary files, and OS or
148
148
  editor files.
149
149
 
150
- Ask how Blueprint workflow files should be handled in git, unless the user
150
+ Ask how DevFlow workflow files should be handled in git, unless the user
151
151
  already gave a preference:
152
152
 
153
153
  ```text
154
- Blueprint visibility?
154
+ DevFlow visibility?
155
155
 
156
- 1. Commit Blueprint workflow files
156
+ 1. Commit DevFlow workflow files
157
157
  Portable. Best for teams and working across machines.
158
158
 
159
- 2. Keep Blueprint workflow files local
160
- Adds .agents/, .claude/, blueprint/, and CLAUDE.md to .gitignore.
159
+ 2. Keep DevFlow workflow files local
160
+ Adds .agents/, .claude/, devflow/, and CLAUDE.md to .gitignore.
161
161
  Keeps AGENTS.md public as the lightweight project agent guide.
162
162
  ```
163
163
 
@@ -166,37 +166,38 @@ Recommend option 1 by default. If the user chooses option 2:
166
166
  - Add this block to `.gitignore`, preserving existing entries:
167
167
 
168
168
  ```gitignore
169
- # AI Blueprint local workflow files
169
+ # DevFlow local workflow files
170
170
  .agents/
171
171
  .claude/
172
- blueprint/
172
+ devflow/
173
173
  CLAUDE.md
174
174
  ```
175
175
 
176
176
  - Keep `AGENTS.md` tracked. It remains the lightweight public project guide for
177
177
  commands and conventions.
178
178
  - Make `AGENTS.md` public-safe: keep project description, commands, testing gate,
179
- and coding conventions, but remove or avoid Blueprint workflow explanations,
179
+ and coding conventions, but remove or avoid DevFlow workflow explanations,
180
180
  hidden adapter paths, workflow-document pointers, and core skill lists that
181
181
  would expose the local-only workflow.
182
182
  - Explain that local-only mode hides the workflow contents from the repo, but the
183
183
  `.gitignore` names still reveal the ignored paths.
184
- - Explain that Blueprint state, specs, findings, and history will not travel
185
- with the repo; another machine needs the Blueprint reinstalled or restored
184
+ - Explain that DevFlow state, specs, findings, and history will not travel
185
+ with the repo; another machine needs DevFlow reinstalled or restored
186
186
  locally.
187
- - If any of `.agents/`, `.claude/`, `blueprint/`, or
187
+ - If any of `.agents/`, `.claude/`, `devflow/`, or
188
188
  `CLAUDE.md` are already tracked, say `.gitignore` will not hide tracked files.
189
189
  Ask before running
190
- `git rm --cached -r .agents .claude blueprint CLAUDE.md`, and
190
+ `git rm --cached -r .agents .claude devflow CLAUDE.md`, and
191
191
  only run it if the user explicitly approves. Never delete the local files.
192
192
 
193
193
  Then report which adapter folders are needed:
194
194
 
195
- - Codex only: keep `AGENTS.md`, `.agents/`, and `blueprint/`; `CLAUDE.md` and
195
+ - Codex, Antigravity, and GitHub Copilot: keep `AGENTS.md`, `.agents/`, and `devflow/`; `CLAUDE.md` and
196
196
  `.claude/` can be deleted.
197
- - Claude Code only: keep `AGENTS.md`, `CLAUDE.md`, `.claude/`, and `blueprint/`;
197
+ - Claude Code only: keep `AGENTS.md`, `CLAUDE.md`, `.claude/`, and `devflow/`;
198
198
  `.agents/` can be deleted.
199
- - Mixed tools: keep both adapters.
199
+ - OpenCode: shares either `.agents/` or `.claude/` compatible skill tree without duplicate folders.
200
+ - Mixed tools: keep both `.agents/` and `.claude/` adapters.
200
201
 
201
202
  Do not delete adapters unless the user explicitly asks.
202
203
 
@@ -71,7 +71,7 @@ changed. Exclude these protected workflow paths:
71
71
 
72
72
  - `.agents/**`
73
73
  - `.claude/**`
74
- - `blueprint/**`
74
+ - `devflow/**`
75
75
  - `AGENTS.md`
76
76
  - `CLAUDE.md`
77
77
  - `prototypes/**`
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: 00-explore
3
- description: "[Devflow] Explore stage in DevFlow 2.0 - explore a request, route supporting inquiry, and decide whether delivery work should begin without allocating a running ID."
3
+ description: "[devflow][D] Explore stage in DevFlow 2.0 - explore a request, route supporting inquiry, and decide whether delivery work should begin without allocating a running ID."
4
4
  argument-hint: "{title, request, or discovery-id}"
5
5
  ---
6
6
 
@@ -81,4 +81,4 @@ Record selected routes, returned findings, open questions, decision, and rationa
81
81
  ## Next Workflow Recommendation
82
82
 
83
83
  - **Primary**: `10-define {discovery_id}` only after approved Proceed
84
- - **Defer/Reject**: No next command needed
84
+ - **Defer/Reject**: No next command needed
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: 10-define
3
- description: "[Devflow] Define stage in DevFlow 2.0 - turn an approved discovery into a bounded delivery run in context/current-run with stable scope."
3
+ description: "[devflow][D] Define stage in DevFlow 2.0 - turn an approved discovery into a bounded delivery run in context/current-run with stable scope."
4
4
  argument-hint: "{approved discovery-id, discovery path, running-id, or run path}"
5
5
  ---
6
6
 
@@ -51,4 +51,4 @@ Require:
51
51
  - Write `devflow/context/current-run/10-define.md`.
52
52
  - Update `devflow/context/current-stage.md`:
53
53
  - `Active Running ID`: `{ID}`
54
- - `Current Stage`: `10-define (Completed -> Ready for 20-spec)`
54
+ - `Current Stage`: `10-define (Completed -> Ready for 20-spec)`
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: 20-spec
3
- description: "[Devflow] Spec stage in DevFlow 2.0 - write the formal markdown-first specification from a stable definition."
3
+ description: "[devflow][D] Spec stage in DevFlow 2.0 - write the formal markdown-first specification from a stable definition."
4
4
  argument-hint: "{running-id or workspace path}"
5
5
  ---
6
6
 
@@ -153,4 +153,3 @@ Report:
153
153
  - Use `Research` when a requirement, rule, or integration constraint still lacks evidence.
154
154
  - Use `Spec-Research`, `Competitor`, or `PRD` when the contract needs stronger external, product, or market framing before planning.
155
155
  - Use `grill-with-docs` when available if clarification could materially change acceptance criteria, edge cases, exclusions, or rules.
156
-
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: 30-plan
3
- description: "[Devflow] Plan stage in DevFlow 2.0 - transform 20-spec.md into an executable task breakdown with test decisions."
3
+ description: "[devflow][D] Plan stage in DevFlow 2.0 - transform 20-spec.md into an executable task breakdown with test decisions."
4
4
  ---
5
5
  # Phase 30: Plan Implementation
6
6
 
@@ -218,4 +218,3 @@ If `Approval Status` is still pending or major dependencies remain unresolved:
218
218
  - **Reason**: Plans often discover stable patterns that future sessions should reuse.
219
219
  - **Suggested Command**: `Wiki project ingest devflow/runs/{ID}-*30-plan.md`
220
220
 
221
-
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: 40-execute
3
- description: "[Devflow] Execute stage in DevFlow 2.0 - execute planned tasks incrementally with evidence and unit tests."
3
+ description: "[devflow][D] Execute stage in DevFlow 2.0 - execute planned tasks incrementally with evidence and unit tests."
4
4
  ---
5
5
  # Phase 40: Execute Code
6
6
 
@@ -158,4 +158,4 @@ Report:
158
158
  - **Needed**: `yes` when coding discovers a reusable implementation pattern, gotcha, or context optimization.
159
159
  - **Scope**: `project` unless the discovery is about DevFlow itself.
160
160
  - **Reason**: Coding findings are useful only when they are stable enough to help future tasks.
161
- - **Suggested Command**: `Wiki project ingest devflow/runs/{ID}-*40-execute.md`
161
+ - **Suggested Command**: `Wiki project ingest devflow/runs/{ID}-*40-execute.md`
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: 50-verify
3
- description: "[Devflow] Verify stage in DevFlow 2.0 - perform senior QA review, record evidence, and decide pass or return-to-implement."
3
+ description: "[devflow][D] Verify stage in DevFlow 2.0 - perform senior QA review, record evidence, and decide pass or return-to-implement."
4
4
  ---
5
5
 
6
6
  # Phase 50: Verify Quality
@@ -52,4 +52,4 @@ Execute verification across all essential quality dimensions:
52
52
  Report:
53
53
  - QA verdict across all verification lanes
54
54
  - Evidence commands and outputs
55
- - Next command: `60-report {ID}` (if pass) or `40-execute {ID}` (if fail)
55
+ - Next command: `60-report {ID}` (if pass) or `40-execute {ID}` (if fail)
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: 60-report
3
- description: "[Devflow] Report stage in DevFlow 2.0 - produce standardized markdown summary report with retrospective lessons learned."
3
+ description: "[devflow][D] Report stage in DevFlow 2.0 - produce standardized markdown summary report with retrospective lessons learned."
4
4
  argument-hint: "{running-id or workspace path}"
5
5
  ---
6
6
 
@@ -54,4 +54,4 @@ Structure the report in **Thai (`th`)**:
54
54
  ## Next Workflow Recommendation
55
55
 
56
56
  - **Primary**: `70-deliver {ID}`
57
- - **Optional Standalone HTML**: `/report:html`
57
+ - **Optional Standalone HTML**: `/report:html`
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: 70-deliver
3
- description: "[Devflow] Deliver stage in DevFlow 2.0 - package verified work for delivery, archive run to categorized history, git merge, PR, or deployment."
3
+ description: "[devflow][D] Deliver stage in DevFlow 2.0 - package verified work for delivery, archive run to categorized history, git merge, PR, or deployment."
4
4
  argument-hint: "{running-id or workspace path}"
5
5
  ---
6
6
 
@@ -69,4 +69,4 @@ Set `devflow/context/current-stage.md` to:
69
69
  - `Active Running ID`: `None (Idle)`
70
70
  - `Current Stage`: `Idle (Ready for new run)`
71
71
  - `Last Completed Run`: `{ID} ({YYYY-MM-DD})`
72
- - `Last Updated`: `{YYYY-MM-DD}`
72
+ - `Last Updated`: `{YYYY-MM-DD}`
@@ -1,95 +1,211 @@
1
1
  ---
2
2
  name: adopt
3
- description: "[Devflow] Survey existing brownfield codebase and bootstrap DevFlow context files."
3
+ description: "[devflow][B] Bring the blueprint into an existing (brownfield) codebase. Surveys the real repo, interviews for intent, generates the owned plans and coding standards, documents existing verification and CI, asks whether DevFlow workflow files should be committed or kept local-only, and points to the optional standalone CI setup. Use when the user runs /adopt, is overlaying the blueprint onto an app that already has meaningful code, or asks to adopt or bootstrap the workflow into an existing project. For freshly scaffolded or early projects, use onboard instead."
4
4
  ---
5
5
 
6
- # adopt - Bootstrap Nexus-DevFlow from an Existing Codebase
6
+ # adopt - bootstrap the blueprint from an existing codebase
7
7
 
8
8
  Where this sits in the workflow:
9
9
 
10
- ```text
11
- existing codebase -> [adopt] -> project-overview + coding-standards -> 00-explore or 10-define
12
- (already has code) (survey + (seeded from the real code; (first feature / refactoring
13
- interview) shipped architecture documented) delivery lifecycle)
14
- ```
10
+ existing codebase -> [adopt] -> project-plan + build-plan + coding-standards -> /overview -> normal loop
11
+ (already has code) (survey + (seeded from the real code; shipped (project- (/feature,
12
+ interview) features already checked off) overview.md) /implement, ...)
15
13
 
16
- Standard onboarding assumes a freshly scaffolded, near-empty app. That does not fit a codebase that already has thousands of lines of working code.
14
+ The standard onboarding assumes a freshly scaffolded, near-empty app: you write
15
+ the two plans from scratch and build forward. That doesn't fit a project that
16
+ already has thousands of lines of working code. `/adopt` is the brownfield
17
+ on-ramp: it reads what's already there, asks you only for what the code can't tell
18
+ it (the *why* and the *roadmap*), and produces the same input files the rest of
19
+ the workflow expects - so an existing project joins the loop without you
20
+ hand-writing everything.
17
21
 
18
- `adopt` is the brownfield on-ramp for Nexus-DevFlow: it reads what is already there, asks only for what the code cannot reveal (the *intent*, the *why*, and the *upcoming roadmap*), and produces the exact context files the rest of the DevFlow lifecycle expects (`project-overview.md`, `coding-standards.md`, `AGENTS.md` commands).
19
-
20
- ---
22
+ It generates the inputs; it does not generate `project-overview.md`. That stays
23
+ `/overview`'s job. `/adopt` ends by telling you to run `/overview`.
21
24
 
22
25
  ## Input
23
26
 
24
- A description of what the project is, if provided. Otherwise, inspect the repository directly. No argument is required.
25
-
26
- ---
27
-
28
- ## Step 0 - Confirm Brownfield Safety
29
-
30
- Inspect `devflow/context/project-overview.md` and `devflow/context/coding-standards.md`:
31
-
32
- - If they contain default placeholders or empty templates, proceed.
33
- - If they already hold rich, user-owned content, stop and inform the user; offer to refresh specific sections rather than overwriting existing context without confirmation.
34
-
35
- Never run a framework scaffolder (DevFlow is an overlay, never a generator).
36
-
37
- ---
38
-
39
- ## Step 1 - Survey the Codebase (Read-Only)
40
-
41
- Read the repository to establish the facts. Change nothing in this step:
42
-
43
- - **Stack & Tooling**: Languages, frameworks, and versions from manifest files (`package.json`, `requirements.txt`, `pyproject.toml`, `go.mod`, `Cargo.toml`, etc.). Note the active package manager from lockfiles.
44
- - **Commands**: Real dev, build, test, lint, and verify scripts.
45
- - **Conventions in Practice**: Directory layout, component naming, state management, styling, data-fetching, error handling, validation. Read what the code *actually does*.
46
- - **Testing Reality**: Inspect existing test suites, runners, and coverage. Be honest about test status.
47
- - **Shipped Capabilities & Architecture**: Inferred from routes, pages, controllers, database schemas, and entry points.
27
+ A description of what the project is, if the user offers one. Otherwise just the
28
+ repository itself. No argument is required.
29
+
30
+ ## Step 0 - confirm it's brownfield and safe
31
+
32
+ Look at `devflow/project-plan.md` and `devflow/build-plan.md`.
33
+
34
+ - If they're missing or still the empty worksheet/placeholder, proceed.
35
+ - If they already hold real content, this project is already adopted. Stop and say
36
+ so; offer to refresh a specific file instead of overwriting work the user owns.
37
+
38
+ Never overwrite a filled-in plan without explicit confirmation. Never run a
39
+ framework scaffolder (the blueprint is an overlay, never a generator).
40
+
41
+ Protect the project README:
42
+
43
+ - If the root `README.md` already looks like a real project README, leave it
44
+ alone.
45
+ - If the root `README.md` is the copied DevFlow workflow doc (for example it
46
+ starts with `# AI Coding Blueprint`), report it as obsolete overlay content
47
+ and ask before replacing or removing it. Do not move it into `devflow/`.
48
+ - Do not create or overwrite a root project README for a brownfield app unless
49
+ the user explicitly asks. The existing project face belongs to the app, not the
50
+ workflow.
51
+
52
+ ## Step 1 - survey the codebase (read-only)
53
+
54
+ Read the repo to establish the facts. Change nothing in this step. Establish:
55
+
56
+ - **Stack and tooling** - language(s), framework(s), and versions, from the real
57
+ manifest (`package.json`, `requirements.txt`, `pyproject.toml`, `go.mod`,
58
+ `Gemfile`, `Cargo.toml`, etc.). Note the package manager actually in use (lockfile).
59
+ - **Commands** - the real dev / build / test / lint scripts. These feed the
60
+ Commands section of `AGENTS.md` and, per the testing opt-in switch, decide
61
+ whether a testing gate even applies.
62
+ - **Conventions in practice** - directory layout, component/file naming, styling
63
+ approach, state management, data-fetching pattern, error handling. Read what the
64
+ code *does*, not what a default template prescribes.
65
+ - **Testing reality** - is a runner configured and are there tests, or none? Be
66
+ honest; don't describe a gate the project doesn't have.
67
+ - **Verification and CI** - note any combined verification command, GitHub
68
+ remote, `.github/workflows/`, or external CI. Preserve what already exists.
69
+ - **What the app already does** - the shipped features, inferred from routes,
70
+ pages, entry points, and modules. This becomes the *checked* part of the build plan.
71
+
72
+ Keep notes; you'll turn them into the files in Step 3.
73
+
74
+ ## Step 2 - interview for intent
75
+
76
+ The code reveals *what* and *how*, never *why* or *what next*. Ask the user a short
77
+ set of questions (aim for three to five, not an interrogation) to fill the gaps:
78
+
79
+ - What is this project for, and who uses it? (the problem and the users)
80
+ - Is the stack and structure you found intentional, or are there parts they'd call
81
+ legacy / want to change?
82
+ - What do you want to build next? (the unchecked items in the build plan)
83
+ - Anything the survey got wrong or missed?
84
+
85
+ If the user already gave intent up front, skip what they've answered. Don't ask
86
+ what you can read from the code.
87
+
88
+ ## Step 3 - generate the inputs
89
+
90
+ Write these, drawn from the survey (facts) and the interview (intent). Mark every
91
+ inference you're unsure of with a clear `> TODO (confirm)` so the user can correct
92
+ it rather than inherit a wrong guess.
93
+
94
+ - **`devflow/project-plan.md`** - the what & why, following the existing
95
+ worksheet structure (problem, users, features, data, tech, monetization, UI/UX).
96
+ The "features" and "tech" sections describe what *already exists*; the rest comes
97
+ from the interview.
98
+ - **`devflow/build-plan.md`** - the ordered feature list as a checklist. **Mark
99
+ shipped features `- [x]`** (this is the brownfield difference: the build plan
100
+ reflects reality, so most of an existing app starts checked) and the roadmap
101
+ items from the interview as `- [ ]`. This makes `/status` and `/feature` work
102
+ immediately - the next unchecked item is genuinely what's next.
103
+ - **`devflow/context/coding-standards.md`** - rewrite the default to match the
104
+ project's *actual* conventions from Step 1, not the shipped Next.js/Prisma
105
+ defaults. Keep the Writing and Comments sections; replace the stack-specific ones
106
+ with what the code really does. Its Testing section must reflect the real testing
107
+ state (the opt-in switch is a `test` command in `AGENTS.md`).
108
+ - **`AGENTS.md` Commands section** - fill in the real dev / build / test / lint
109
+ commands you found, so the rest of the workflow (and the testing gate) uses the
110
+ project's actual scripts. Include `Verify` when a real combined command exists.
111
+
112
+ Do not write `project-overview.md`; that's `/overview`'s job, downstream of these.
113
+
114
+ ## Step 4 - point to optional CI setup
115
+
116
+ Do not create or change Verify commands or GitHub workflows during adoption.
117
+ Report any verification command or CI already present. When equivalent automatic
118
+ pull-request checks are absent, mention the optional standalone setup:
48
119
 
49
- Keep structured notes for generation in Step 3.
50
-
51
- ---
52
-
53
- ## Step 2 - Interview for Intent
54
-
55
- The code reveals *what* and *how*, but not *why* or *what next*. Ask a short set of 3-4 questions to fill the gaps:
56
-
57
- 1. **Purpose & Users**: What is the core problem this project solves, and who are the target users?
58
- 2. **Architecture Status**: Is the current structure and stack intentional, or are there legacy parts/technical debt the team wants to change or refactor?
59
- 3. **Upcoming Roadmap**: What are the top priorities to build, fix, or refactor next?
60
- 4. **Clarifications**: Anything the survey got wrong or missed?
61
-
62
- *(If the user already provided this context in the prompt, skip questions that are already answered).*
63
-
64
- ---
65
-
66
- ## Step 3 - Generate the Context Artifacts
67
-
68
- Write the baseline context files drawn from the survey (facts) and interview (intent):
120
+ ```text
121
+ Run /ci or $ci when you want automatic GitHub checks.
122
+ ```
69
123
 
70
- 1. **`devflow/context/project-overview.md`**:
71
- - Project Name, Purpose, and Target Users
72
- - Architecture summary and directory layout
73
- - Shipped capabilities and existing major modules
74
- - Key technical stack components and verified commands
75
- - Known technical debt or architectural focus areas
124
+ Explain that CI is not required to finish adoption. The `/ci` skill owns
125
+ project-specific Verify and GitHub workflow setup.
76
126
 
77
- 2. **`devflow/context/coding-standards.md`**:
78
- - Rewrite defaults to reflect the project's *actual* conventions discovered in Step 1
79
- - Framework patterns, state management, error handling, styling, and test rules based on real code
127
+ ## Step 5 - ask about DevFlow visibility
80
128
 
81
- 3. **`AGENTS.md` Commands Section**:
82
- - Fill in the real dev, build, test, lint, and verify commands found during survey.
129
+ Ask how the DevFlow workflow files should be handled in git, unless the user
130
+ already gave a preference:
83
131
 
84
- ---
132
+ ```text
133
+ DevFlow visibility?
85
134
 
86
- ## Step 4 - Review Gate and Handoff
135
+ 1. Commit DevFlow workflow files
136
+ Portable. Best for teams and working across machines.
87
137
 
88
- Present the adoption summary for review:
138
+ 2. Keep DevFlow workflow files local
139
+ Adds .agents/, .claude/, devflow/, and CLAUDE.md to .gitignore.
140
+ Keeps AGENTS.md public as the lightweight project agent guide.
141
+ ```
89
142
 
90
- - Shipped features and architectural baseline recorded
91
- - Inferred conventions and coding standards
92
- - Available verified commands in `AGENTS.md`
93
- - Recommended next step:
94
- - Run `00-explore` (or `00-explore`, `$00-explore`) to explore the next major initiative or feature
95
- - Run `10-define` (or `10-define`, `$10-define`) to immediately scope a delivery run for known roadmap items
143
+ Recommend option 1 by default. If the user chooses option 2:
144
+
145
+ - Add this block to `.gitignore`, preserving existing entries:
146
+
147
+ ```gitignore
148
+ # DevFlow local workflow files
149
+ .agents/
150
+ .claude/
151
+ devflow/
152
+ CLAUDE.md
153
+ ```
154
+
155
+ - Keep `AGENTS.md` tracked. It remains the lightweight public project guide for
156
+ commands and conventions.
157
+ - Make `AGENTS.md` public-safe: keep project description, commands, testing gate,
158
+ and coding conventions, but remove or avoid DevFlow workflow explanations,
159
+ hidden adapter paths, workflow-document pointers, and core skill lists that
160
+ would expose the local-only workflow.
161
+ - Explain that local-only mode hides the workflow contents from the repo, but the
162
+ `.gitignore` names still reveal the ignored paths.
163
+ - Explain that DevFlow state, specs, findings, and history will not travel
164
+ with the repo; another machine needs DevFlow reinstalled or restored
165
+ locally.
166
+ - Because adoption runs right after the DevFlow files were added to an
167
+ existing repository, they are more likely to already be staged or committed
168
+ than in a fresh install. If any of `.agents/`, `.claude/`, `devflow/`, or
169
+ `CLAUDE.md` are already tracked, say `.gitignore` will not hide tracked files.
170
+ Ask before running
171
+ `git rm --cached -r .agents .claude devflow CLAUDE.md`, and
172
+ only run it if the user explicitly approves. Never delete the local files.
173
+
174
+ ## Step 6 - review gate, then hand off
175
+
176
+ Stop and show the user what you generated, calling out:
177
+
178
+ - the **build-plan split** - what you marked shipped vs not, since that's the
179
+ judgment most worth their eyes,
180
+ - every `> TODO (confirm)` you left,
181
+ - anything the survey and the interview disagreed on,
182
+ - verification command and GitHub checks status,
183
+ - DevFlow visibility choice, and a tracked-file warning if local-only mode was
184
+ chosen after files were already tracked.
185
+
186
+ These files are the ones the user *owns*. Have them review and adjust, then tell
187
+ them to run `/overview` to distill the plans into `project-overview.md` and start
188
+ the normal loop.
189
+
190
+ ## Rules
191
+
192
+ - **Read-only until Step 3.** The survey changes nothing; only generation writes.
193
+ - **Reflect reality, don't prescribe.** `coding-standards.md` must match the code
194
+ that exists. A project using Zustand and REST routes should not be handed
195
+ standards about Server Actions and Prisma just because that's the default.
196
+ - **Never invent intent.** Ask for the why and the roadmap; mark anything inferred
197
+ with `> TODO (confirm)`. Silent guesses about purpose are the main failure mode.
198
+ - **Don't clobber owned work.** If the plans already have real content, confirm
199
+ before touching them. Never run a scaffolder.
200
+ - **Be honest about testing.** If there's no runner, say testing is opt-in and not
201
+ yet set up; don't describe a gate the project hasn't adopted.
202
+ - Keep `AGENTS.md` public in local-only mode unless the user explicitly asks for
203
+ a more advanced setup.
204
+ - Do not untrack DevFlow files with `git rm --cached` without a separate
205
+ explicit approval.
206
+
207
+ ## Formatting
208
+
209
+ Format the output to match the project's conventions in
210
+ `devflow/context/ai-interaction.md`: concise, scannable markdown, with lists for
211
+ enumerations and tables for matrices rather than dense paragraphs.