@jakkrichm/create-nexus-devflow 2.12.0 → 2.12.1
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/package.json +1 -1
- package/template/.agents/skills/onboard/SKILL.md +43 -2
- package/template/.agents/skills/overview/SKILL.md +25 -12
- package/template/.claude/skills/onboard/SKILL.md +43 -2
- package/template/.claude/skills/overview/SKILL.md +25 -12
- package/template/devflow/analysis/REQ-20260903-001-sync-upstream-ai-blueprint/codebase-impact.md +46 -0
- package/template/devflow/build-plan.md +8 -0
- package/template/devflow/context/ai-interaction.md +2 -0
- package/template/devflow/inbox/REQ-20260903-001-sync-upstream-ai-blueprint/clarifications.md +34 -0
- package/template/devflow/inbox/REQ-20260903-001-sync-upstream-ai-blueprint/parsed.md +66 -0
- package/template/devflow/inbox/REQ-20260903-001-sync-upstream-ai-blueprint/raw/upstream-v152-diff.md +16 -0
package/package.json
CHANGED
|
@@ -29,7 +29,48 @@ and project behavior already exist and need to be reflected into the plans.
|
|
|
29
29
|
No argument is required. If the user provides context about the stack, hosting,
|
|
30
30
|
database, auth, or preferred tool, use it as a hint and verify against files.
|
|
31
31
|
|
|
32
|
-
## Step 0 - confirm
|
|
32
|
+
## Step 0 - confirm Git and make an unborn repository usable
|
|
33
|
+
|
|
34
|
+
Before reading application code or changing setup files, confirm both Git states:
|
|
35
|
+
|
|
36
|
+
```bash
|
|
37
|
+
git rev-parse --is-inside-work-tree
|
|
38
|
+
git rev-parse --verify HEAD
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
If this is not a Git repository, stop and ask the user to initialize one, then
|
|
42
|
+
rerun `/onboard`.
|
|
43
|
+
|
|
44
|
+
An existing first commit may contain only the scaffold or may already contain
|
|
45
|
+
DevFlow. Both are valid. Do not ask the user to rewrite either history shape.
|
|
46
|
+
|
|
47
|
+
If Git reports an unborn `HEAD`, handle it here instead of sending the user away
|
|
48
|
+
to run Git commands:
|
|
49
|
+
|
|
50
|
+
1. Inspect status and build a safe scaffold-only candidate from paths outside
|
|
51
|
+
`AGENTS.md`, `CLAUDE.md`, `.agents/`, `.claude/`, and `devflow/`. Exclude
|
|
52
|
+
secrets, dependencies, caches, build output, generated state, and anything
|
|
53
|
+
else that should not enter source control. Include the existing `.gitignore`
|
|
54
|
+
when it is safe.
|
|
55
|
+
2. Resolve the intended default branch from a remote default when available,
|
|
56
|
+
then an existing `main` or `master`, then Git's configured initial branch,
|
|
57
|
+
and otherwise `main`. Preserve the current unborn branch name as the setup
|
|
58
|
+
branch when it is not the intended default. If the intended name is genuinely
|
|
59
|
+
ambiguous, ask only that one question.
|
|
60
|
+
3. Show the exact candidate and the branch result, then ask once:
|
|
61
|
+
`Create the initial scaffold commit and continue Onboard? (Recommended)`
|
|
62
|
+
State that this creates one local commit and never pushes.
|
|
63
|
+
4. On approval, stage only the reviewed candidate, verify the staged diff, and
|
|
64
|
+
commit it as `chore: scaffold application`. If needed, rename the unborn
|
|
65
|
+
branch before committing so the root commit establishes the intended default
|
|
66
|
+
branch. Then create or return to the named setup branch at that same commit
|
|
67
|
+
and continue Onboard in the same run.
|
|
68
|
+
|
|
69
|
+
If there is no safe scaffold candidate, stop with the exact blocker rather than
|
|
70
|
+
creating an empty or mixed root commit. Never create the commit without explicit
|
|
71
|
+
approval.
|
|
72
|
+
|
|
73
|
+
Then confirm this is onboarding, not adoption.
|
|
33
74
|
|
|
34
75
|
Inspect the repository and the two planning docs:
|
|
35
76
|
|
|
@@ -41,7 +82,7 @@ Inspect the repository and the two planning docs:
|
|
|
41
82
|
Continue only with setup files such as `AGENTS.md`, `coding-standards.md`,
|
|
42
83
|
`.gitignore`, and optional notes.
|
|
43
84
|
|
|
44
|
-
Never run a framework scaffolder.
|
|
85
|
+
Never run a framework scaffolder. DevFlow is already overlaid.
|
|
45
86
|
|
|
46
87
|
## Step 1 - survey the project facts
|
|
47
88
|
|
|
@@ -81,8 +81,8 @@ commit. Never create this commit silently.
|
|
|
81
81
|
Treat this as the initial pre-feature state only when all of these are true:
|
|
82
82
|
|
|
83
83
|
- the project is a Git repository with an existing `HEAD` commit
|
|
84
|
-
- the current branch is the default branch,
|
|
85
|
-
|
|
84
|
+
- the current branch is the default branch, or it is a dedicated setup branch
|
|
85
|
+
whose starting commit exactly matches the current default-branch tip
|
|
86
86
|
- the version of `devflow/context/project-overview.md` in `HEAD` does not
|
|
87
87
|
already contain a generated overview baseline
|
|
88
88
|
- `devflow/context/` has no active task-isolated workspace directories (`devflow/context/{xxx-slug}/`)
|
|
@@ -91,11 +91,11 @@ Treat this as the initial pre-feature state only when all of these are true:
|
|
|
91
91
|
- `devflow/build-plan.md` contains no checked feature items
|
|
92
92
|
- the DevFlow workflow is meant to be committed, not kept local-only
|
|
93
93
|
|
|
94
|
-
If there is no `HEAD` yet, stop and
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
94
|
+
If there is no `HEAD` yet, stop and send the user back to `/onboard`, which owns
|
|
95
|
+
the initial scaffold commit recovery. Overview never creates a root commit. If a
|
|
96
|
+
dedicated setup branch did not start at the current default tip, stop with that
|
|
97
|
+
exact mismatch. These are recoverable initial handoffs, not permission to offer
|
|
98
|
+
another baseline after one is committed.
|
|
99
99
|
|
|
100
100
|
Detect local-only mode with Git, not memory. Use `git check-ignore` on the
|
|
101
101
|
present workflow paths. If `.agents/`, `.claude/`, `devflow/`, or `CLAUDE.md`
|
|
@@ -103,7 +103,7 @@ are ignored as part of the onboarding local-only choice, skip the offer and
|
|
|
103
103
|
continue to the normal `/feature` guidance. `AGENTS.md` remaining public does not
|
|
104
104
|
make a local-only setup eligible.
|
|
105
105
|
|
|
106
|
-
Before asking:
|
|
106
|
+
Before asking, record the resolved default branch and its exact tip:
|
|
107
107
|
|
|
108
108
|
1. Read `git status`, the staged diff, the unstaged diff, and untracked paths.
|
|
109
109
|
2. Build a candidate containing only DevFlow installation, adapter,
|
|
@@ -111,16 +111,21 @@ Before asking:
|
|
|
111
111
|
`CLAUDE.md`, `.agents/`, `.claude/`, and `devflow/`. Include `.gitignore`
|
|
112
112
|
only when every changed hunk is clearly an onboarding or DevFlow ignore
|
|
113
113
|
entry.
|
|
114
|
-
3.
|
|
115
|
-
|
|
114
|
+
3. Include the installer-owned `devflow/.state/manifest.json` and
|
|
115
|
+
`devflow/.state/.gitignore` when present. Exclude transient state such as
|
|
116
|
+
`run.json`, backups, and staging, plus secrets, logs, caches, dependencies,
|
|
117
|
+
build output, and application source.
|
|
116
118
|
4. Stop if any staged change or dirty path falls outside the candidate, or if an
|
|
117
119
|
allowed file contains an unrelated hunk. Do not mix app scaffolding or other
|
|
118
120
|
user work into this commit. Tell the user exactly what must be committed,
|
|
119
121
|
moved, or restored first, then leave the repository unchanged.
|
|
120
122
|
5. If the candidate is empty, skip the offer.
|
|
121
123
|
6. Show the exact candidate paths and their diff before asking:
|
|
122
|
-
`
|
|
123
|
-
State that accepting creates one local commit
|
|
124
|
+
`Finalize the DevFlow baseline locally? (Recommended)`
|
|
125
|
+
State that accepting creates one local commit. When running on a dedicated
|
|
126
|
+
setup branch, it also fast-forwards the unchanged default branch to that
|
|
127
|
+
commit, returns to the default branch, and deletes the setup branch. It never
|
|
128
|
+
pushes.
|
|
124
129
|
|
|
125
130
|
If the user accepts, stage only the reviewed candidate, show the staged paths
|
|
126
131
|
and diff summary, verify no other path is staged, and commit with this exact
|
|
@@ -130,6 +135,14 @@ message:
|
|
|
130
135
|
chore: establish DevFlow project baseline
|
|
131
136
|
```
|
|
132
137
|
|
|
138
|
+
For a dedicated setup branch, verify before committing that the default tip is
|
|
139
|
+
still the one shown in the prompt. After the commit, require a clean working
|
|
140
|
+
tree, switch to the default branch, run `git merge --ff-only <setup-branch>`, and
|
|
141
|
+
delete the setup branch locally. The single approval above covers only these
|
|
142
|
+
named local actions. If the default moved or any check fails, stop without
|
|
143
|
+
merging or deleting. Then confirm the final branch and working tree and recommend
|
|
144
|
+
`/feature`.
|
|
145
|
+
|
|
133
146
|
Then confirm the working tree state and recommend `/feature`. If the user
|
|
134
147
|
declines, leave the repository untouched and explain that these setup and
|
|
135
148
|
planning changes will remain uncommitted until they create the baseline later.
|
|
@@ -29,7 +29,48 @@ and project behavior already exist and need to be reflected into the plans.
|
|
|
29
29
|
No argument is required. If the user provides context about the stack, hosting,
|
|
30
30
|
database, auth, or preferred tool, use it as a hint and verify against files.
|
|
31
31
|
|
|
32
|
-
## Step 0 - confirm
|
|
32
|
+
## Step 0 - confirm Git and make an unborn repository usable
|
|
33
|
+
|
|
34
|
+
Before reading application code or changing setup files, confirm both Git states:
|
|
35
|
+
|
|
36
|
+
```bash
|
|
37
|
+
git rev-parse --is-inside-work-tree
|
|
38
|
+
git rev-parse --verify HEAD
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
If this is not a Git repository, stop and ask the user to initialize one, then
|
|
42
|
+
rerun `/onboard`.
|
|
43
|
+
|
|
44
|
+
An existing first commit may contain only the scaffold or may already contain
|
|
45
|
+
DevFlow. Both are valid. Do not ask the user to rewrite either history shape.
|
|
46
|
+
|
|
47
|
+
If Git reports an unborn `HEAD`, handle it here instead of sending the user away
|
|
48
|
+
to run Git commands:
|
|
49
|
+
|
|
50
|
+
1. Inspect status and build a safe scaffold-only candidate from paths outside
|
|
51
|
+
`AGENTS.md`, `CLAUDE.md`, `.agents/`, `.claude/`, and `devflow/`. Exclude
|
|
52
|
+
secrets, dependencies, caches, build output, generated state, and anything
|
|
53
|
+
else that should not enter source control. Include the existing `.gitignore`
|
|
54
|
+
when it is safe.
|
|
55
|
+
2. Resolve the intended default branch from a remote default when available,
|
|
56
|
+
then an existing `main` or `master`, then Git's configured initial branch,
|
|
57
|
+
and otherwise `main`. Preserve the current unborn branch name as the setup
|
|
58
|
+
branch when it is not the intended default. If the intended name is genuinely
|
|
59
|
+
ambiguous, ask only that one question.
|
|
60
|
+
3. Show the exact candidate and the branch result, then ask once:
|
|
61
|
+
`Create the initial scaffold commit and continue Onboard? (Recommended)`
|
|
62
|
+
State that this creates one local commit and never pushes.
|
|
63
|
+
4. On approval, stage only the reviewed candidate, verify the staged diff, and
|
|
64
|
+
commit it as `chore: scaffold application`. If needed, rename the unborn
|
|
65
|
+
branch before committing so the root commit establishes the intended default
|
|
66
|
+
branch. Then create or return to the named setup branch at that same commit
|
|
67
|
+
and continue Onboard in the same run.
|
|
68
|
+
|
|
69
|
+
If there is no safe scaffold candidate, stop with the exact blocker rather than
|
|
70
|
+
creating an empty or mixed root commit. Never create the commit without explicit
|
|
71
|
+
approval.
|
|
72
|
+
|
|
73
|
+
Then confirm this is onboarding, not adoption.
|
|
33
74
|
|
|
34
75
|
Inspect the repository and the two planning docs:
|
|
35
76
|
|
|
@@ -41,7 +82,7 @@ Inspect the repository and the two planning docs:
|
|
|
41
82
|
Continue only with setup files such as `AGENTS.md`, `coding-standards.md`,
|
|
42
83
|
`.gitignore`, and optional notes.
|
|
43
84
|
|
|
44
|
-
Never run a framework scaffolder.
|
|
85
|
+
Never run a framework scaffolder. DevFlow is already overlaid.
|
|
45
86
|
|
|
46
87
|
## Step 1 - survey the project facts
|
|
47
88
|
|
|
@@ -81,8 +81,8 @@ commit. Never create this commit silently.
|
|
|
81
81
|
Treat this as the initial pre-feature state only when all of these are true:
|
|
82
82
|
|
|
83
83
|
- the project is a Git repository with an existing `HEAD` commit
|
|
84
|
-
- the current branch is the default branch,
|
|
85
|
-
|
|
84
|
+
- the current branch is the default branch, or it is a dedicated setup branch
|
|
85
|
+
whose starting commit exactly matches the current default-branch tip
|
|
86
86
|
- the version of `devflow/context/project-overview.md` in `HEAD` does not
|
|
87
87
|
already contain a generated overview baseline
|
|
88
88
|
- `devflow/context/` has no active task-isolated workspace directories (`devflow/context/{xxx-slug}/`)
|
|
@@ -91,11 +91,11 @@ Treat this as the initial pre-feature state only when all of these are true:
|
|
|
91
91
|
- `devflow/build-plan.md` contains no checked feature items
|
|
92
92
|
- the DevFlow workflow is meant to be committed, not kept local-only
|
|
93
93
|
|
|
94
|
-
If there is no `HEAD` yet, stop and
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
94
|
+
If there is no `HEAD` yet, stop and send the user back to `/onboard`, which owns
|
|
95
|
+
the initial scaffold commit recovery. Overview never creates a root commit. If a
|
|
96
|
+
dedicated setup branch did not start at the current default tip, stop with that
|
|
97
|
+
exact mismatch. These are recoverable initial handoffs, not permission to offer
|
|
98
|
+
another baseline after one is committed.
|
|
99
99
|
|
|
100
100
|
Detect local-only mode with Git, not memory. Use `git check-ignore` on the
|
|
101
101
|
present workflow paths. If `.agents/`, `.claude/`, `devflow/`, or `CLAUDE.md`
|
|
@@ -103,7 +103,7 @@ are ignored as part of the onboarding local-only choice, skip the offer and
|
|
|
103
103
|
continue to the normal `/feature` guidance. `AGENTS.md` remaining public does not
|
|
104
104
|
make a local-only setup eligible.
|
|
105
105
|
|
|
106
|
-
Before asking:
|
|
106
|
+
Before asking, record the resolved default branch and its exact tip:
|
|
107
107
|
|
|
108
108
|
1. Read `git status`, the staged diff, the unstaged diff, and untracked paths.
|
|
109
109
|
2. Build a candidate containing only DevFlow installation, adapter,
|
|
@@ -111,16 +111,21 @@ Before asking:
|
|
|
111
111
|
`CLAUDE.md`, `.agents/`, `.claude/`, and `devflow/`. Include `.gitignore`
|
|
112
112
|
only when every changed hunk is clearly an onboarding or DevFlow ignore
|
|
113
113
|
entry.
|
|
114
|
-
3.
|
|
115
|
-
|
|
114
|
+
3. Include the installer-owned `devflow/.state/manifest.json` and
|
|
115
|
+
`devflow/.state/.gitignore` when present. Exclude transient state such as
|
|
116
|
+
`run.json`, backups, and staging, plus secrets, logs, caches, dependencies,
|
|
117
|
+
build output, and application source.
|
|
116
118
|
4. Stop if any staged change or dirty path falls outside the candidate, or if an
|
|
117
119
|
allowed file contains an unrelated hunk. Do not mix app scaffolding or other
|
|
118
120
|
user work into this commit. Tell the user exactly what must be committed,
|
|
119
121
|
moved, or restored first, then leave the repository unchanged.
|
|
120
122
|
5. If the candidate is empty, skip the offer.
|
|
121
123
|
6. Show the exact candidate paths and their diff before asking:
|
|
122
|
-
`
|
|
123
|
-
State that accepting creates one local commit
|
|
124
|
+
`Finalize the DevFlow baseline locally? (Recommended)`
|
|
125
|
+
State that accepting creates one local commit. When running on a dedicated
|
|
126
|
+
setup branch, it also fast-forwards the unchanged default branch to that
|
|
127
|
+
commit, returns to the default branch, and deletes the setup branch. It never
|
|
128
|
+
pushes.
|
|
124
129
|
|
|
125
130
|
If the user accepts, stage only the reviewed candidate, show the staged paths
|
|
126
131
|
and diff summary, verify no other path is staged, and commit with this exact
|
|
@@ -130,6 +135,14 @@ message:
|
|
|
130
135
|
chore: establish DevFlow project baseline
|
|
131
136
|
```
|
|
132
137
|
|
|
138
|
+
For a dedicated setup branch, verify before committing that the default tip is
|
|
139
|
+
still the one shown in the prompt. After the commit, require a clean working
|
|
140
|
+
tree, switch to the default branch, run `git merge --ff-only <setup-branch>`, and
|
|
141
|
+
delete the setup branch locally. The single approval above covers only these
|
|
142
|
+
named local actions. If the default moved or any check fails, stop without
|
|
143
|
+
merging or deleting. Then confirm the final branch and working tree and recommend
|
|
144
|
+
`/feature`.
|
|
145
|
+
|
|
133
146
|
Then confirm the working tree state and recommend `/feature`. If the user
|
|
134
147
|
declines, leave the repository untouched and explain that these setup and
|
|
135
148
|
planning changes will remain uncommitted until they create the baseline later.
|
package/template/devflow/analysis/REQ-20260903-001-sync-upstream-ai-blueprint/codebase-impact.md
ADDED
|
@@ -0,0 +1,46 @@
|
|
|
1
|
+
# Codebase Impact & Blast Radius Analysis
|
|
2
|
+
|
|
3
|
+
> **Requirement ID**: `REQ-20260903-001-sync-upstream-ai-blueprint`
|
|
4
|
+
> **Date**: 2026-09-03
|
|
5
|
+
> **Complexity Score**: `Low-to-Medium (Controlled Enhancement)`
|
|
6
|
+
> **Risk Level**: `Low (No Breaking Changes, Backward-Compatible)`
|
|
7
|
+
|
|
8
|
+
---
|
|
9
|
+
|
|
10
|
+
## 1. Blast Radius Map (ขอบเขตผลกระทบ)
|
|
11
|
+
|
|
12
|
+
```mermaid
|
|
13
|
+
graph TD
|
|
14
|
+
Upstream["Upstream AI Blueprint v1.5.2"] --> Onboard[".agents & .claude /skills/onboard/SKILL.md"]
|
|
15
|
+
Upstream --> Overview[".agents & .claude /skills/overview/SKILL.md"]
|
|
16
|
+
Upstream --> Context["devflow/context/ai-interaction.md"]
|
|
17
|
+
Upstream --> E2E["scripts/e2e/scenarios/unborn-onboarding.ts"]
|
|
18
|
+
Upstream --> Validator["scripts/validate-framework.ts"]
|
|
19
|
+
|
|
20
|
+
Onboard --> TemplateOnboard["packages/create-nexus-devflow template"]
|
|
21
|
+
Overview --> TemplateOverview["packages/create-nexus-devflow template"]
|
|
22
|
+
Context --> TemplateContext["packages/create-nexus-devflow template"]
|
|
23
|
+
```
|
|
24
|
+
|
|
25
|
+
---
|
|
26
|
+
|
|
27
|
+
## 2. Affected Files & Modules (รายการไฟล์ที่ได้รับผลกระทบ)
|
|
28
|
+
|
|
29
|
+
| File Path | Action | Description |
|
|
30
|
+
| :--- | :--- | :--- |
|
|
31
|
+
| `.agents/skills/onboard/SKILL.md` | `MODIFY` | เพิ่ม Step 0 ตรวจจับ Unborn repository และเสนอกระบวนการ Root scaffold commit |
|
|
32
|
+
| `.claude/skills/onboard/SKILL.md` | `MODIFY` | ปรับปรุงพฤติกรรมให้ตรงกับ `.agents/` |
|
|
33
|
+
| `.agents/skills/overview/SKILL.md` | `MODIFY` | เพิ่มความสามารถ Setup branch baseline finalization (`git merge --ff-only`) |
|
|
34
|
+
| `.claude/skills/overview/SKILL.md` | `MODIFY` | ปรับปรุงพฤติกรรมให้ตรงกับ `.agents/` |
|
|
35
|
+
| `devflow/context/ai-interaction.md` | `MODIFY` | อัปเดตระเบียบการ baseline commit บน setup branch |
|
|
36
|
+
| `scripts/e2e/scenarios/unborn-onboarding.ts` | `NEW` | เพิ่มชุดทดสอบ E2E scenario ตัวที่ 9 สำหรับ unborn repo & fast-forward baseline |
|
|
37
|
+
| `scripts/validate-framework.ts` | `MODIFY` | เพิ่ม verification contracts สำหรับ onboard unborn check และ overview finalization prompt |
|
|
38
|
+
| `packages/create-nexus-devflow/template/` | `SYNC` | ซิงก์ template ผ่าน `npm run check` |
|
|
39
|
+
|
|
40
|
+
---
|
|
41
|
+
|
|
42
|
+
## 3. Risk & Breaking Change Assessment
|
|
43
|
+
|
|
44
|
+
- **Contract Breaking Risk**: `None` — ไม่มีการเปลี่ยนแปลงโครงสร้างคำสั่งหรือโฟลเดอร์หลัก ทุกการเปลี่ยนแปลงเป็นส่วนขยายเพื่อรองรับ Edge Case ที่ยังไม่มี commit
|
|
45
|
+
- **Git Safety Risk**: `Zero Remote Exposure` — มีการล็อกกฎความปลอดภัยไม่ให้มีการ push ไปยัง remote ในระหว่าง Onboard และ Overview อย่างเข้มงวด
|
|
46
|
+
- **Test Coverage Impact**: เพิ่ม Coverage โดยมี scenario ใหม่ `unborn-onboarding.ts` ในชุด E2E Agent Runner
|
|
@@ -204,3 +204,11 @@
|
|
|
204
204
|
- *Dependencies*: Feature 20, Feature 21, DISC-20260903-001
|
|
205
205
|
- *Scope*: พอร์ตและปรับแต่ง Hardened Dashboard Activity State Helper (`.agents/skills/doctor/scripts/run-state.mjs` และ `.claude/`), บังคับใช้ Zero-Manual Writes กับ `devflow/.state/run.json`, ปรับใช้ On-Demand Context Loading Protocol พร้อมแยก Reference Templates ย่อย (`reference/`), เพิ่ม Unit Tests `run-state-helper.test.ts`, อัปเดต `scripts/validate-framework.ts`, `AGENTS.md`, `CLAUDE.md` และยืนยันการผ่าน 100%
|
|
206
206
|
|
|
207
|
+
---
|
|
208
|
+
|
|
209
|
+
## 🔄 Phase 26: Upstream AI Blueprint v1.5.2 Synchronization
|
|
210
|
+
|
|
211
|
+
- [x] **26. Sync Upstream v1.5.2 (Unborn Repository Onboarding & Branch Baseline Finalization) (`REQ-20260903-001`, `071-sync-upstream-ai-blueprint-v152`)** `[Size: S]`
|
|
212
|
+
- *Dependencies*: Feature 25, REQ-20260903-001
|
|
213
|
+
- *Scope*: เพิ่มการตรวจจับและกู้คืน Unborn Git repository ใน `/onboard` ด้วย Scaffold Initial Commit (`chore: scaffold application`), รองรับการ Finalize DevFlow Baseline บน Dedicated Setup Branch ด้วย `git merge --ff-only` ใน `/overview`, เพิ่มชุดทดสอบ E2E Scenario `scripts/e2e/scenarios/unborn-onboarding.ts`, อัปเดต `devflow/context/ai-interaction.md` และอัปเดต Framework Static Contracts ผ่าน 100%
|
|
214
|
+
|
|
@@ -52,6 +52,8 @@ devflow/
|
|
|
52
52
|
### ⚡ The Unified 4-Stage Task-Isolated Living Spec Lifecycle
|
|
53
53
|
*ขับเคลื่อนการพัฒนาทุกระดับด้วย **Task-Isolated Living Spec (`devflow/context/{xxx-slug}/spec.md`)** ที่รวมความลึกระดับ Architect Mode เข้ากับความคล่องตัวระดับ Lean Velocity โดยแยก Workspace ของแต่ละงานออกจากกัน 100%:*
|
|
54
54
|
|
|
55
|
+
After the first successful `/overview`, DevFlow offers a reviewed local commit for the initial workflow setup and plans before Feature 1. It shows the exact candidate diff and asks first. It skips local-only installations and stops rather than mixing app source or unrelated work into the baseline. When setup work is on a dedicated branch, the same approval can finalize the local baseline and fast-forward it into the unchanged default branch. It never pushes.
|
|
56
|
+
|
|
55
57
|
```text
|
|
56
58
|
/feature (หรือ /fix) ──▶ /implement ──▶ /check ──▶ /complete
|
|
57
59
|
```
|
|
@@ -0,0 +1,34 @@
|
|
|
1
|
+
# Socratic Clarification Checklist (REQ-20260903-001)
|
|
2
|
+
|
|
3
|
+
> **Requirement ID**: `REQ-20260903-001-sync-upstream-ai-blueprint`
|
|
4
|
+
> **Audience**: System Analyst, Tech Lead, Framework Maintainer
|
|
5
|
+
> **Status**: `Ready for Review`
|
|
6
|
+
|
|
7
|
+
---
|
|
8
|
+
|
|
9
|
+
## 🔍 Socratic Review & Alignment Questions
|
|
10
|
+
|
|
11
|
+
### 1. Root Scaffold Commit Convention
|
|
12
|
+
- [x] **Question**: รูปแบบ Commit Message สำหรับ Scaffold แรกใน Unborn Repo ควรใช้รูปแบบใด?
|
|
13
|
+
- **Proposed Decision**: `chore: scaffold application` (มาตรฐานเดียวกับ Upstream AI Blueprint และ Conventional Commits)
|
|
14
|
+
- **Safety Check**: ต้องไม่รวมโฟลเดอร์ `devflow/`, `AGENTS.md`, `CLAUDE.md`, `.agents/`, `.claude/` เข้าไปใน Root Commit นี้เด็ดขาด
|
|
15
|
+
|
|
16
|
+
### 2. Setup-Branch Fast-Forward Merge Rule
|
|
17
|
+
- [x] **Question**: ใน `/overview` หากผู้ใช้วางแผนบน dedicated branch (เช่น `feature/devflow-plans`) การรวมกลับเข้า `main` ต้องทำอย่างไร?
|
|
18
|
+
- **Proposed Decision**: บังคับใช้ `git merge --ff-only` เท่านั้นเพื่อรักษา Linear Git History หากมีการแตก branch ออกไปแบบ non-fast-forward จะต้องหยุดและรายงาน mismatch ทันที
|
|
19
|
+
- **Safety Check**: ยืนยันการลบ local setup branch หลัง merge สำเร็จ เพื่อไม่ให้มี branch ขยะค้าง
|
|
20
|
+
|
|
21
|
+
### 3. Local-Only & Remote Push Guard
|
|
22
|
+
- [x] **Question**: การทำ Finalize Baseline มีโอกาสหลุดรัน `git push` หรือไม่?
|
|
23
|
+
- **Proposed Decision**: ล็อกกฎชัดเจนใน `SKILL.md` ว่าทุกคำสั่งใน Onboard และ Overview ทำงานในระดับ Local Git เท่านั้น (No Push)
|
|
24
|
+
|
|
25
|
+
---
|
|
26
|
+
|
|
27
|
+
## 📋 Actionable Checklist for Implementation
|
|
28
|
+
|
|
29
|
+
- [ ] ปรับปรุง `.agents/skills/onboard/SKILL.md` และ `.claude/skills/onboard/SKILL.md` เพื่อตรวจจับ Unborn `HEAD` และเสนอ Scaffold Root Commit
|
|
30
|
+
- [ ] ปรับปรุง `.agents/skills/overview/SKILL.md` และ `.claude/skills/overview/SKILL.md` สำหรับ Setup-Branch Baseline Finalization (`git merge --ff-only`)
|
|
31
|
+
- [ ] อัปเดต `devflow/context/ai-interaction.md` ให้ระบุสิทธิการทำ Baseline Finalization บน Setup Branch
|
|
32
|
+
- [ ] พอร์ต E2E Scenario `scripts/e2e/scenarios/unborn-onboarding.ts` ให้เข้ากับโครงสร้างและชื่อคำสั่งของ Nexus-DevFlow
|
|
33
|
+
- [ ] เพิ่ม static verification contract ใน `scripts/validate-framework.ts`
|
|
34
|
+
- [ ] รันการตรวจสอบความถูกต้องของระบบครบทุก Lane (`npm run check:static`, `npm test`, `npm run check`)
|
|
@@ -0,0 +1,66 @@
|
|
|
1
|
+
# Business & Technical Requirement Specification (REQ-20260903-001)
|
|
2
|
+
|
|
3
|
+
> **Requirement ID**: `REQ-20260903-001-sync-upstream-ai-blueprint`
|
|
4
|
+
> **Source**: Upstream AI Blueprint v1.5.2 (`5b46859`)
|
|
5
|
+
> **Status**: `Parsed & Normalized`
|
|
6
|
+
> **Target Release**: Nexus-DevFlow v2.12.1 / Feature `071`
|
|
7
|
+
|
|
8
|
+
---
|
|
9
|
+
|
|
10
|
+
## 1. Executive Summary (ภาพรวมผู้บริหาร)
|
|
11
|
+
|
|
12
|
+
การอัปเดตเพื่อซิงก์ความสามารถและมาตรฐานความปลอดภัย Git จาก Upstream AI Blueprint v1.5.2 เข้าสู่ Nexus-DevFlow:
|
|
13
|
+
1. **การจัดการ Unborn Repository ใน `/onboard`**: รองรับกรณีที่โปรเจกต์เพิ่งรัน `git init` แต่ยังไม่มี First Commit (Unborn `HEAD`) โดย `/onboard` จะตรวจจับอัตโนมัติ เสนอสร้าง Reviewed Scaffold Initial Commit และตั้ง Default Branch (`main`) ให้พร้อมใช้งานทันทีโดยไม่ให้ผู้ใช้ต้องออกจาก IDE ไปพิมพ์คำสั่ง Git เอง
|
|
14
|
+
2. **Setup-Branch Baseline Finalization ใน `/overview`**: รองรับกรณีการ Onboard และวางแผนบน Dedicated Setup Branch (เช่น `feature/devflow-plans`) โดยเมื่ออนุมัติ Baseline Commit จะทำการ commit, fast-forward merge กลับเข้าสู่ `main`, สลับ branch และลบ setup branch ให้เรียบร้อยแบบ Local-Only
|
|
15
|
+
3. **Dedicated E2E Automated Scenario (`unborn-onboarding.ts`)**: ชุดทดสอบ Agentic E2E ตรวจสอบพฤติกรรมของ AI Agent ตั้งแต่ Unborn Repo -> Onboarding -> Baseline Fast-Forward
|
|
16
|
+
|
|
17
|
+
---
|
|
18
|
+
|
|
19
|
+
## 2. Target Persona & User Stories
|
|
20
|
+
|
|
21
|
+
| Persona | Problem Statement | Desired Outcome |
|
|
22
|
+
| :--- | :--- | :--- |
|
|
23
|
+
| **New Project Developer** | Scaffold โปรเจกต์ใหม่และรัน `git init` แต่ยังไม่ได้ commit พอรัน `/onboard` AI มัก error หรือสับสนเรื่อง branch | `/onboard` ตรวจจับสถานะ unborn repository และช่วยสร้าง scaffold commit แรกให้อัตโนมัติหลังกดอนุมัติ |
|
|
24
|
+
| **Branch-Isolated Developer** | ต้องการวางแผน DevFlow บน setup branch ชั่วคราวก่อนเริ่มฟีเจอร์แรก | `/overview` อนุมัติ Baseline แล้วรวมกลับเข้า `main` แบบ Fast-Forward และลบ branch ชั่วคราวให้อัตโนมัติ |
|
|
25
|
+
| **DevFlow Maintainer** | ต้องการให้ Nexus-DevFlow มี Feature & Safety Parity 100% กับ Upstream AI Blueprint | มีชุดทดสอบ E2E scenario และ static contracts รองรับ |
|
|
26
|
+
|
|
27
|
+
---
|
|
28
|
+
|
|
29
|
+
## 3. Functional Requirements (FR)
|
|
30
|
+
|
|
31
|
+
### FR-1: Unborn Git Pre-flight & Scaffold Initial Commit (`/onboard`)
|
|
32
|
+
- **FR-1.1**: เมื่อเริ่มทำงาน `/onboard` (Step 0) ต้องตรวจสอบ `git rev-parse --is-inside-work-tree` และ `git rev-parse --verify HEAD`
|
|
33
|
+
- **FR-1.2**: หากไม่มี `HEAD` (Unborn repository):
|
|
34
|
+
- กรอง Candidate Files เฉพาะไฟล์โครงสร้างของ Application (ยกเว้น workflow files เช่น `AGENTS.md`, `CLAUDE.md`, `.agents/`, `.claude/`, `devflow/`)
|
|
35
|
+
- ค้นหา default branch (จาก `main`, `master`, หรือ Git default)
|
|
36
|
+
- ถามยืนยัน 1 ครั้ง: `Create the initial scaffold commit and continue Onboard? (Recommended)`
|
|
37
|
+
- เมื่อได้รับอนุมัติ สร้าง commit `chore: scaffold application` บน default branch และสลับกลับมา setup branch (ถ้ามี) เพื่อ onboard ต่อทันที
|
|
38
|
+
|
|
39
|
+
### FR-2: Branch-Aware Baseline Finalization (`/overview`)
|
|
40
|
+
- **FR-2.1**: ใน `/overview` อนุญาตให้ทำงานบน Default Branch หรือ Dedicated Setup Branch ที่แตกมาจาก Tip ของ Default Branch
|
|
41
|
+
- **FR-2.2**: หากรันบน Unborn Repo ให้แจ้งให้ไปรัน `/onboard` ก่อน (ไม่สร้าง root commit ใน overview)
|
|
42
|
+
- **FR-2.3**: ปรับ Prompt ข้อความยืนยันเป็น: `Finalize the DevFlow baseline locally? (Recommended)`
|
|
43
|
+
- **FR-2.4**: รวม metadata installer `devflow/.state/manifest.json` เข้า Baseline Commit โดยยกเว้น transient state `run.json`
|
|
44
|
+
- **FR-2.5**: หากรันบน Setup Branch เมื่ออนุมัติแล้ว จะทำการ:
|
|
45
|
+
1. Commit `chore: establish DevFlow project baseline` บน setup branch
|
|
46
|
+
2. สลับกลับไป default branch (`git checkout main`)
|
|
47
|
+
3. รัน `git merge --ff-only <setup-branch>`
|
|
48
|
+
4. ลบ setup branch ในเครื่อง (`git branch -d <setup-branch>`)
|
|
49
|
+
5. อยู่บนสถานะ clean working tree พร้อมเริ่ม `/feature`
|
|
50
|
+
|
|
51
|
+
### FR-3: E2E Test Suite Extension (`unborn-onboarding.ts`)
|
|
52
|
+
- **FR-3.1**: เพิ่มไฟล์ Scenario `scripts/e2e/scenarios/unborn-onboarding.ts`
|
|
53
|
+
- **FR-3.2**: ทดสอบ Full Flow ใน Sandbox: `git init` -> setup branch -> overlay DevFlow -> `/onboard` -> `/overview` -> fast-forward `main`
|
|
54
|
+
|
|
55
|
+
---
|
|
56
|
+
|
|
57
|
+
## 4. Non-Functional Requirements (NFR)
|
|
58
|
+
|
|
59
|
+
1. **Security & Local-Only Guarantee**:
|
|
60
|
+
- ห้ามรัน `git push` ในทุกกรณีของการทำ Baseline Finalization
|
|
61
|
+
- ห้ามรวม Application Source Code ปะปนเข้ากับ Baseline Commit
|
|
62
|
+
- ป้องกัน Secret / Token หลุดเข้า Root Commit โดยตรวจสอบ `.gitignore`
|
|
63
|
+
2. **Token & Prompt Efficiency**:
|
|
64
|
+
- การปรับแต่งคำอธิบายและข้อความใน `SKILL.md` ทั้ง `.agents/` และ `.claude/` ต้องคงความกระชับ ไม่เกินงบประมาณตัวอักษร
|
|
65
|
+
3. **Adapter Parity**:
|
|
66
|
+
- ทั้ง 5 Adapters (Google Antigravity, Claude Code, OpenAI Codex, GitHub Copilot, OpenCode) ต้องได้รับพฤติกรรมที่เท่าเทียมกัน
|
package/template/devflow/inbox/REQ-20260903-001-sync-upstream-ai-blueprint/raw/upstream-v152-diff.md
ADDED
|
@@ -0,0 +1,16 @@
|
|
|
1
|
+
# Upstream AI Blueprint v1.5.2 Changes Summary
|
|
2
|
+
|
|
3
|
+
Commit: 5b468599890a6d59a1570e343e6241db5ffd0ae9
|
|
4
|
+
Author: Brad Traversy <traversymedia@gmail.com>
|
|
5
|
+
Date: Thu Sep 3 08:30:38 2026 -0400
|
|
6
|
+
Message: fix: handle repositories without an initial commit
|
|
7
|
+
|
|
8
|
+
## Modified Files:
|
|
9
|
+
- `.agents/skills/onboard/SKILL.md` (+43, -1)
|
|
10
|
+
- `.agents/skills/overview/SKILL.md` (+41, -21)
|
|
11
|
+
- `.claude/skills/onboard/SKILL.md` (+43, -1)
|
|
12
|
+
- `.claude/skills/overview/SKILL.md` (+41, -21)
|
|
13
|
+
- `blueprint/context/ai-interaction.md` (+4, -2)
|
|
14
|
+
- `packages/create-ai-blueprint/package.json` (+1, -1)
|
|
15
|
+
- `scripts/e2e/scenarios/unborn-onboarding.ts` (+85)
|
|
16
|
+
- `scripts/validate-blueprint.ts` (+23, -5)
|