@jakkrichm/create-nexus-devflow 2.11.1 → 2.12.1

package/template/.claude/skills/feature/reference/feature-spec-template.md

@@ -0,0 +1,82 @@
+# 📐 [{xxx-slug}] {title}
+
+> **Status**: In-Progress  
+> **Track**: Fast-Track (Task-Isolated Living Spec Mode - Feature)  
+> **Category**: Feature  
+> **Source**: `devflow/build-plan.md: Feature {n}` & `devflow/discoveries/{DISC-ID}/discovery.md`  
+> **Branch**: `feature/{xxx-slug}`  
+> **Started Date**: {YYYY-MM-DD}  
+> **Delivered Date**: TBD  
+> **Owner**: DevFlow Core Framework Team & AI  
+
+---
+
+## 1. Specification & Scope
+
+### 1.1 Problem Statement
+{คำอธิบายปัญหาและที่มาของความจำเป็นในการพัฒนาฟีเจอร์นี้}
+
+### 1.2 In-Scope
+1. {ขอบเขตการทำงานข้อที่ 1}
+2. {ขอบเขตการทำงานข้อที่ 2}
+
+### 1.3 Out-of-Scope
+- {สิ่งที่อยู่นอกเหนือขอบเขตหรือไม่ทำในรอบนี้}
+
+### 1.4 Acceptance Criteria (เกณฑ์การยอมรับ)
+- [ ] **AC-1**: {เกณฑ์การตรวจรับข้อที่ 1}
+- [ ] **AC-2**: {เกณฑ์การตรวจรับข้อที่ 2}
+
+---
+
+## 2. Plan & Test Strategy
+
+### 2.1 Files Modified / Created
+- `{file-path}` [NEW | MODIFY | DELETE]
+
+### 2.2 Quality Gates & Sensitivity Check
+- **Quality Gate Policy (`independentReview`)**: `manual` | `always` | `when-sensitive`
+- **UI Evidence / Browser Tests**: {Not applicable | Playwright / BrowserOS Neo}
+- **Review Strategy**: One feature-level review packet at completion
+
+### 2.3 Test Decision: Required (TDD) | Optional
+- **Rationale**: {เหตุผลความจำเป็นในการเขียน Unit Tests / TDD}
+
+---
+
+## 3. Implementation Checklist (Strict TDD)
+
+- [ ] **Task 1: {หัวข้องานที่ 1}**
+  - [ ] 1.1 `[TDD-Red]`: {เขียน Test เคสล้มเหลว}
+  - [ ] 1.2 `[TDD-Green]`: {เขียนโค้ดขั้นต่ำเพื่อให้ Test ผ่าน}
+  - [ ] 1.3 `[TDD-Refactor]`: {Refactor และตรวจให้ 100% Tests Green}
+
+- [ ] **Task 2: {หัวข้องานที่ 2}**
+  - [ ] 2.1 `[TDD-Red]`: ...
+  - [ ] 2.2 `[TDD-Green]`: ...
+  - [ ] 2.3 `[TDD-Refactor]`: ...
+
+---
+
+## 4. Verification Evidence Matrix
+
+### ⚖️ Axis 1: Standards, Architecture & Quality Gate
+- **Type Safety & Build Integrity**: TBD
+- **Automated Test Matrix**: TBD
+- **Static Contract Verification**: TBD
+- **Package Smoke Test**: TBD
+- **Findings Ledger**: ตรวจสอบ `findings.md` สะอาด 100%
+
+### 🎯 Axis 2: Spec Fidelity & Behavioral Acceptance Gate
+- [ ] **AC-1**: {หลักฐานการผ่านเกณฑ์ข้อที่ 1}
+- [ ] **AC-2**: {หลักฐานการผ่านเกณฑ์ข้อที่ 2}
+
+---
+
+## 5. Delivery Verification & Independent Receipt
+
+- **Delivery Date**: TBD
+- **Verification Verdict**: TBD
+- **Framework Tests**: TBD
+- **Static Contract**: TBD
+- **Package Smoke Test**: TBD

package/template/.claude/skills/implement/SKILL.md

@@ -6,6 +6,8 @@ argument-hint: "[{run-id, number, or name}]"
 
 # implement - build the target spec, one reviewed step at a time
 
+**Context reuse:** Reuse any required file already loaded in project instructions or the current session. Read it again only if absent, changed, or exact current bytes or line references are needed.
+
 **First action:** Before project inspection, preflight, or any other tool call,
 publish `running` to `devflow/.state/run.json` using the dashboard activity
 contract in `AGENTS.md`.
@@ -81,41 +83,7 @@ instead of creating a new one.
 
 ### Type: Rollback safeguard
 
-For a rollback spec, do not hand-delete the old feature and do not run a whole
-commit `git revert`. Completed feature commits also contain Blueprint history and
-plan bookkeeping, while `devflow/context/{xxx-slug}/spec.md` now contains the active rollback
-spec. Reversing the whole commit would damage that state.
-
-Before the first rollback build step:
-
-1. Re-resolve the target archive's introducing commit and confirm it matches the
-   full Target commit SHA recorded in the approved spec.
-2. Confirm the target is an ancestor of `HEAD`, has the recorded single parent,
-   and the only dirty path before applying the patch is the approved rollback
-   spec. Stop on drift.
-3. Preview the target's product diff while excluding `.agents/**`, `.claude/**`,
-   `devflow/**`, `AGENTS.md`, `CLAUDE.md`, and
-   `prototypes/**`. Confirm the preview is non-empty and matches the Product
-   paths in the spec.
-4. Apply that product diff in reverse with three-way conflict detection and
-   stage it. Substitute the two approved full SHAs before running:
-
-       git diff --binary <target-parent> <target-commit> -- . \
-         ':(exclude).agents/**' \
-         ':(exclude).claude/**' ':(exclude)devflow/**' \
-         ':(exclude)AGENTS.md' ':(exclude)CLAUDE.md' \
-         ':(exclude)prototypes/**' |
-         git apply --reverse --3way --index
-
-   Never omit the protected pathspec exclusions for convenience.
-5. Show both `git diff --cached` and `git status`. Confirm no protected path is
-   staged or modified before presenting the step for review.
-
-If the reverse patch conflicts, stop and report the exact paths and later commit
-that appears involved. Do not auto-resolve, discard, stash, reset, or switch to a
-broad checkout. Ask whether to resolve only the conflict allowed by the approved
-spec or abandon the attempt. A cascade into another completed feature needs a
-new rollback plan.
+When implementing a rollback task, follow the exact safety procedure in `reference/rollback-implementation.md`.
 
 ## Step 2 - build one step, review, iterate, checkpoint (Strict TDD)
 

package/template/.claude/skills/implement/reference/rollback-implementation.md

@@ -0,0 +1,35 @@
+# Rollback implementation safeguard
+
+Use this only when `stage.md` / `spec.md` indicates a rollback task.
+
+Do not hand-delete the old feature and do not run a whole-commit `git revert`.
+The completed commit also contains DevFlow history and plan bookkeeping.
+
+Before the first rollback step:
+
+1. Read `Target commit` and `Target parent`. Stop unless both values match
+   `^[0-9a-f]{40}$`.
+2. Resolve the archive's introducing commit and verify it has exactly one parent.
+   Stop on a merge target. Confirm the resolved commit exactly equals `Target
+   commit` and the resolved parent exactly equals `Target parent`.
+3. Confirm the target is an ancestor of `HEAD` and the approved rollback spec is
+   the only dirty path. Stop on drift.
+4. Preview the target's product diff while excluding `.agents/**`,
+   `.claude/**`, `devflow/**`, `AGENTS.md`, `CLAUDE.md`, and `prototypes/**`.
+   Confirm it is non-empty and matches the Product paths in the spec.
+5. Apply only the resolved product diff in reverse with three-way conflict
+   detection. Use only the resolved full SHA values:
+
+       git diff --binary <target-parent> <target-commit> -- . \
+         ':(exclude).agents/**' \
+         ':(exclude).claude/**' ':(exclude)devflow/**' \
+         ':(exclude)AGENTS.md' ':(exclude)CLAUDE.md' \
+         ':(exclude)prototypes/**' |
+         git apply --reverse --3way --index
+
+6. Show the staged diff and status. Stop if any protected path is staged or
+   modified.
+
+If the reverse patch conflicts, report the exact paths and later commit involved.
+Do not auto-resolve, discard, stash, reset, or broaden the rollback. Ask whether
+to resolve only the approved conflict or abandon the attempt.

package/template/.claude/skills/onboard/SKILL.md

@@ -29,7 +29,48 @@ and project behavior already exist and need to be reflected into the plans.
 No argument is required. If the user provides context about the stack, hosting,
 database, auth, or preferred tool, use it as a hint and verify against files.
 
-## Step 0 - confirm this is onboarding, not adoption
+## Step 0 - confirm Git and make an unborn repository usable
+
+Before reading application code or changing setup files, confirm both Git states:
+
+```bash
+git rev-parse --is-inside-work-tree
+git rev-parse --verify HEAD
+```
+
+If this is not a Git repository, stop and ask the user to initialize one, then
+rerun `/onboard`.
+
+An existing first commit may contain only the scaffold or may already contain
+DevFlow. Both are valid. Do not ask the user to rewrite either history shape.
+
+If Git reports an unborn `HEAD`, handle it here instead of sending the user away
+to run Git commands:
+
+1. Inspect status and build a safe scaffold-only candidate from paths outside
+   `AGENTS.md`, `CLAUDE.md`, `.agents/`, `.claude/`, and `devflow/`. Exclude
+   secrets, dependencies, caches, build output, generated state, and anything
+   else that should not enter source control. Include the existing `.gitignore`
+   when it is safe.
+2. Resolve the intended default branch from a remote default when available,
+   then an existing `main` or `master`, then Git's configured initial branch,
+   and otherwise `main`. Preserve the current unborn branch name as the setup
+   branch when it is not the intended default. If the intended name is genuinely
+   ambiguous, ask only that one question.
+3. Show the exact candidate and the branch result, then ask once:
+   `Create the initial scaffold commit and continue Onboard? (Recommended)`
+   State that this creates one local commit and never pushes.
+4. On approval, stage only the reviewed candidate, verify the staged diff, and
+   commit it as `chore: scaffold application`. If needed, rename the unborn
+   branch before committing so the root commit establishes the intended default
+   branch. Then create or return to the named setup branch at that same commit
+   and continue Onboard in the same run.
+
+If there is no safe scaffold candidate, stop with the exact blocker rather than
+creating an empty or mixed root commit. Never create the commit without explicit
+approval.
+
+Then confirm this is onboarding, not adoption.
 
 Inspect the repository and the two planning docs:
 
@@ -41,7 +82,7 @@ Inspect the repository and the two planning docs:
   Continue only with setup files such as `AGENTS.md`, `coding-standards.md`,
   `.gitignore`, and optional notes.
 
-Never run a framework scaffolder. The Blueprint is already overlaid.
+Never run a framework scaffolder. DevFlow is already overlaid.
 
 ## Step 1 - survey the project facts
 

package/template/.claude/skills/overview/SKILL.md

@@ -81,8 +81,8 @@ commit. Never create this commit silently.
 Treat this as the initial pre-feature state only when all of these are true:
 
 - the project is a Git repository with an existing `HEAD` commit
-- the current branch is the default branch, resolving the remote default when
-  available and otherwise accepting `main` or `master`
+- the current branch is the default branch, or it is a dedicated setup branch
+  whose starting commit exactly matches the current default-branch tip
 - the version of `devflow/context/project-overview.md` in `HEAD` does not
   already contain a generated overview baseline
 - `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:
 - `devflow/build-plan.md` contains no checked feature items
 - the DevFlow workflow is meant to be committed, not kept local-only
 
-If there is no `HEAD` yet, stop and ask the user to commit the app scaffold by
-itself before rerunning `/overview`; never create a root commit that mixes the
-app and DevFlow. If the initial run is on a non-default branch, stop and ask
-the user to return to the default branch first. These are recoverable initial
-handoffs, not permission to offer another baseline after one is committed.
+If there is no `HEAD` yet, stop and send the user back to `/onboard`, which owns
+the initial scaffold commit recovery. Overview never creates a root commit. If a
+dedicated setup branch did not start at the current default tip, stop with that
+exact mismatch. These are recoverable initial handoffs, not permission to offer
+another baseline after one is committed.
 
 Detect local-only mode with Git, not memory. Use `git check-ignore` on the
 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
 continue to the normal `/feature` guidance. `AGENTS.md` remaining public does not
 make a local-only setup eligible.
 
-Before asking:
+Before asking, record the resolved default branch and its exact tip:
 
 1. Read `git status`, the staged diff, the unstaged diff, and untracked paths.
 2. Build a candidate containing only DevFlow installation, adapter,
@@ -111,16 +111,21 @@ Before asking:
    `CLAUDE.md`, `.agents/`, `.claude/`, and `devflow/`. Include `.gitignore`
    only when every changed hunk is clearly an onboarding or DevFlow ignore
    entry.
-3. Exclude generated local state such as `devflow/.state/`, secrets, logs,
-   caches, dependencies, build output, and application source.
+3. Include the installer-owned `devflow/.state/manifest.json` and
+   `devflow/.state/.gitignore` when present. Exclude transient state such as
+   `run.json`, backups, and staging, plus secrets, logs, caches, dependencies,
+   build output, and application source.
 4. Stop if any staged change or dirty path falls outside the candidate, or if an
    allowed file contains an unrelated hunk. Do not mix app scaffolding or other
    user work into this commit. Tell the user exactly what must be committed,
    moved, or restored first, then leave the repository unchanged.
 5. If the candidate is empty, skip the offer.
 6. Show the exact candidate paths and their diff before asking:
-   `Create the initial planning baseline commit now? (Recommended)`
-   State that accepting creates one local commit and never pushes it.
+   `Finalize the DevFlow baseline locally? (Recommended)`
+   State that accepting creates one local commit. When running on a dedicated
+   setup branch, it also fast-forwards the unchanged default branch to that
+   commit, returns to the default branch, and deletes the setup branch. It never
+   pushes.
 
 If the user accepts, stage only the reviewed candidate, show the staged paths
 and diff summary, verify no other path is staged, and commit with this exact
@@ -130,6 +135,14 @@ message:
 chore: establish DevFlow project baseline
 ```
 
+For a dedicated setup branch, verify before committing that the default tip is
+still the one shown in the prompt. After the commit, require a clean working
+tree, switch to the default branch, run `git merge --ff-only <setup-branch>`, and
+delete the setup branch locally. The single approval above covers only these
+named local actions. If the default moved or any check fails, stop without
+merging or deleting. Then confirm the final branch and working tree and recommend
+`/feature`.
+
 Then confirm the working tree state and recommend `/feature`. If the user
 declines, leave the repository untouched and explain that these setup and
 planning changes will remain uncommitted until they create the baseline later.

package/template/.claude/skills/report-html/SKILL.md

@@ -30,16 +30,36 @@ When invoked:
    - Archived History: `devflow/history/{features|fixes|rollbacks}/{xxx-slug}.md`
 2. Parse spec sections, checklist steps, QA evidence, and verification logs.
 
-### 2. Render Interactive HTML Dashboard
+### 2. Diagram Pre-Check & Skill Auto-Install (Optional)
+If the spec involves architectural design, system topology, sequence flows, or if the user requests diagrams:
+1. **Inspect Existing Diagrams**:
+   Check `devflow/context/{xxx-slug}/diagrams/`. Any `.svg`, `.html`, or image files will be automatically embedded into the **System & Architecture Diagrams** showcase.
+2. **Auto-Detect & Install Diagram Skills**:
+   If diagrams are requested but not yet generated:
+   - Check if `.agents/skills/archify/` or `.agents/skills/diagram-design/` exists.
+   - If not installed, run CLI installation:
+     ```bash
+     # For technical architecture, dataflows, sequence traces, interactive motion
+     npx create-nexus-devflow skill add archify
+
+     # For editorial, business, quadrant, timeline, or radar diagrams
+     npx create-nexus-devflow skill add diagram-design
+     ```
+3. **Generate Diagram**:
+   Use the installed skill to create the diagram artifact in `devflow/context/{xxx-slug}/diagrams/{name}.html` (or `.svg`).
+4. **Native Mermaid Support**:
+   Any ` ```mermaid ` code block inside the document is automatically rendered visually via the dashboard's built-in theme-aware Mermaid.js engine.
+
+### 3. Render Interactive HTML Dashboard
 Execute the HTML generation engine or script:
 ```bash
 npm run report:html -- {RUNNING_ID}
 ```
 Or transform Markdown into a styled, standalone HTML document:
-- Output: `devflow/reports/{RUNNING_ID}-report.html` (or adjacent `{xxx-slug}.html`)
+- Output: `devflow/context/{xxx-slug}/report.html` (or adjacent `{xxx-slug}.html`)
 
-### 3. Output
+### 4. Output
 Provide:
-- Generated HTML file path: `file:///devflow/reports/{RUNNING_ID}-report.html`
-- Summary of sections rendered (Spec, Plan, Progress, QA Evidence, Release Notes)
+- Generated HTML file path: `file:///devflow/context/{xxx-slug}/report.html`
+- Summary of sections rendered (Spec, Plan, Progress, QA Evidence, Diagrams Showcase, Release Notes)
 - Instructions to open the file in any browser

package/template/.claude/skills/status/SKILL.md

@@ -5,38 +5,32 @@ description: "[devflow] Show where the project stands: build-plan progress, the
 
 # status - where the project stands right now
 
+**Context reuse:** Reuse any required file already loaded in project instructions or the current session. Read it again only if absent, changed, or exact current bytes or line references are needed.
+
 Where this sits in the workflow:
 
     any time  ->  [status]  ->  reads build-plan + current-feature + git
                   (read-only)   prints a short "you are here"
 
-This skill answers one question: *where am I?* It reads the files that already
-track progress and prints a short orientation. It is the fast way back in after a
-break, a context clear, or a day away. It never changes anything: no edits, no
-commits, no installs, no builds, no branch changes.
-
-Progress in this workflow lives in files, not the chat, so everything this skill
-reports comes from disk and git. That is the point: a fresh session can run
-`/status` and know exactly as much as the last one did.
+`/status` is orientation: where the project stands right now, what's done,
+what's in flight, whether there's drift between plans and reality, and what
+single action makes the most sense next. It is purely read-only: it reads files
+and git, prints a summary, and exits.
 
-For setup problems, missing files, placeholder plans, adapter drift, or questions
-about whether the Blueprint is installed correctly, run `/doctor` instead.
+Use `/doctor` instead when the user wants a full setup-and-health check.
 
 ## Input
 
 None. `/status` takes no argument.
 
-## What it reads
+## What it gathers
 
-Gather these, then summarize. Don't dump file contents; report the distilled
-state.
+Read these, distill them into a few lines, then stop. Do not dump file contents.
 
-1. **Build plan** - `devflow/build-plan.md`. Count checked vs unchecked leaf
-   items. Name the next unchecked leaf, the same target `/feature` would pick,
-   and note if a parent item was split into sub-items (`4a`, `4b`, ...).
-2. **Current work & Spec Queue** - scan `devflow/context/{xxx-slug}/`. Is something in
-   progress? If a feature, fix, or rollback spec is
-   present, report its type, name, running ID, which build steps are checked, and the
+1. **Build plan progress** - `devflow/build-plan.md`. How many features total, how
+   many are checked off (`- [x]`), what's the next unchecked item.
+2. **Current work** - `devflow/context/{xxx-slug}/spec.md` (Pure Multi-Run support). If active, how
+   many build steps total, how many are checked off, what is the description of the
    first unchecked step where `/implement` resumes. If multiple tasks are queued, list the active spec queue.
 3. **Findings** - `devflow/context/{xxx-slug}/findings.md`. Count findings by status and
    report open and fixed counts next to build-plan progress. Call out any P0 or
@@ -54,7 +48,8 @@ state.
 7. **Dashboard activity** - read `devflow/.state/run.json` when it exists.
    Report the command, mode, status, progress, boundary, and safe resume command.
    A missing file simply means no activity has been recorded. Invalid activity
-   state is a warning, not a blocker for the underlying workflow.
+   state is a warning, not a blocker for the underlying workflow; point to
+   `/doctor` to inspect and offer the approved generated-state reset.
 8. **Onboarding check** - Before recommending `/overview`, check whether `AGENTS.md`
    still contains the `<!-- devflow:onboarding-required -->` marker or standard template commands.
    When it does, onboarding is incomplete and `/onboard` is the next action.
@@ -84,6 +79,8 @@ A short, scannable summary, not a wall of text. Aim for something like:
 
 End with a single suggested next action, chosen in this order:
 
+- The project configuration is invalid -> `/doctor`.
+- Dashboard activity is malformed -> `/doctor`.
 - The overview is missing or stale and no feature is in progress -> `/overview`.
 - A spec is in progress with unchecked steps -> `/implement [id]` and name the step.
 - A spec is in progress and all implementation steps are checked -> `/check [id]` if

package/template/AGENTS.md

@@ -40,10 +40,10 @@ Unused adapter families can be removed. Codex, Antigravity, GitHub Copilot, and
 
 ### Universal Invocation & Agent Directives:
 
-1. **Canonical Command Names & AI Provider Invocation**: Each workflow stage and companion tool has exactly **one Canonical Name** (e.g. `feature`, `fix`, `implement`, `check`, `complete`, `continuous`, `discovery`, `idea`, `grill`, `brainstorm`, `devflow`, `doctor`, `overview`, `debug`, `onboard`, `adopt`, `try`, `rollback`, `ci`, `test`, `setup-tests`, `browser-tests`, `autopilot`, `prototype`, `report-html`, `brief`, `audit`, `release`, `convert-any-to-md`, `publish-devflow`). The way you invoke commands depends on your AI Provider / Tool:
-   - **Canonical Name (Plain text)**: Directly invoke or prompt the command by its standard name (e.g., `feature`, `implement`, `continuous`, `devflow`, `discovery`).
-   - **Slash Prefix (`/`)**: For tools supporting slash commands (Claude Code, Google Antigravity, Gemini CLI), e.g., `/feature`, `/fix`, `/implement`, `/continuous`, `/devflow`, `/discovery`.
-   - **Dollar Prefix (`$`)**: For OpenAI Codex CLI or skill-invocation tools, e.g., `$feature`, `$fix`, `$continuous`, `$devflow`, `$discovery`.
+1. **Canonical Command Names & AI Provider Invocation**: Each workflow stage and companion tool has exactly **one Canonical Name** (e.g. `feature`, `fix`, `implement`, `check`, `complete`, `continuous`, `analyze`, `discovery`, `idea`, `grill`, `brainstorm`, `bughunter`, `devflow`, `doctor`, `overview`, `debug`, `onboard`, `adopt`, `try`, `rollback`, `ci`, `test`, `setup-tests`, `browser-tests`, `autopilot`, `prototype`, `report-html`, `brief`, `audit`, `release`, `convert-any-to-md`, `publish-devflow`). The way you invoke commands depends on your AI Provider / Tool:
+   - **Canonical Name (Plain text)**: Directly invoke or prompt the command by its standard name (e.g., `feature`, `implement`, `continuous`, `devflow`, `discovery`, `analyze`).
+   - **Slash Prefix (`/`)**: For tools supporting slash commands (Claude Code, Google Antigravity, Gemini CLI), e.g., `/feature`, `/fix`, `/implement`, `/continuous`, `/devflow`, `/discovery`, `/analyze`.
+   - **Dollar Prefix (`$`)**: For OpenAI Codex CLI or skill-invocation tools, e.g., `$feature`, `$fix`, `$continuous`, `$devflow`, `$discovery`, `$analyze`.
 2. **OpenAI Codex & Non-Native CLI Tools**: In environments without automatic background skill discovery (such as OpenAI Codex CLI, Aider, or generic terminals), **you MUST use your file reading tool to inspect `.agents/skills/<skill>/SKILL.md` before executing the stage** to strictly follow its schema, artifact contract, and quality gates.
 3. **Google Antigravity & Claude Code**: Native skill engines automatically discover and surface `.agents/skills/` and `.claude/skills/`.
 4. **State-Aware Inspection**: When unsure what to do next, invoke `devflow` to automatically inspect active task directories in `devflow/context/{xxx-slug}/`, `devflow/discoveries/`, and `devflow/ideas.md`.
@@ -71,8 +71,9 @@ All development tasks execute through the 4-step progressive lifecycle:
 
 ---
 
-## 🔮 Pre-Flight Discovery & Architectural Alignment (Companions)
+## 🔮 Pre-Flight Discovery, SA & Architectural Alignment (Companions)
 
+- `analyze`: Unified SA requirement ingestion, multi-format doc parsing (PDF, Word, Excel, images, text), codebase impact scan (`devflow/inbox/`, `devflow/analysis/`).
 - `discovery`: Unified pre-delivery discovery & exploration (`devflow/discoveries/{DISC-ID}/discovery.md`).
 - `idea`: Quick idea capture and AI feasibility scoring (`devflow/ideas.md`).
 - `grill` (or `align`): Socratic alignment, domain modeling, and ADR recording (`devflow/decisions/`).
@@ -84,13 +85,20 @@ All development tasks execute through the 4-step progressive lifecycle:
 
 The dashboard and status reporting can show the active or most recent substantial DevFlow command from `devflow/.state/run.json`. This file is generated local state, ignored by Git, and never part of a feature commit.
 
-<<<<<<< HEAD
-Commands with meaningful progress or a durable handoff should write it when the state directory exists: `onboard`, `adopt`, `discovery`, `overview`, `feature`, `fix`, `rollback`, `implement`, `debug`, `check`, `audit`, `tests`, `browser-tests`, `ci`, `prototype`, `autopilot`, `continuous`, `complete`, and `release`. Short read-only orientation commands such as `brief`, `try`, `status`, and `doctor` do not need activity state.
-=======
-Commands with meaningful progress or a durable handoff should write it when the state directory exists: `onboard`, `adopt`, `discovery`, `overview`, `feature`, `fix`, `rollback`, `implement`, `debug`, `check`, `audit`, `setup-tests`, `ci`, `prototype`, `autopilot`, `continuous`, `complete`, and `release`. Short read-only orientation commands such as `brief`, `try`, `status`, and `doctor` do not need activity state.
->>>>>>> feature/064-bughunter-master-skill-and-sync-engine
+Commands with meaningful progress or a durable handoff should write it when the state directory exists: `onboard`, `adopt`, `analyze`, `discovery`, `overview`, `feature`, `fix`, `rollback`, `implement`, `debug`, `check`, `audit`, `bughunter`, `setup-tests`, `browser-tests`, `test`, `ci`, `prototype`, `autopilot`, `continuous`, `complete`, and `release`. Short read-only orientation commands such as `brief`, `try`, `status`, and `doctor` do not need activity state. Doctor's optional approved reset removes malformed activity instead of recording another run.
 
-Writing the initial activity record is the first action of a tracked command, before project inspection, preflight, or other tool calls. This one generated state write does not authorize product changes or bypass any safety check. Set status to `running`, use the command name and a truthful initial summary, then replace the record at meaningful milestones. On a preflight stop or another blocker, set it to `blocked` with the exact recovery command. Leave the final state in place for the next session; the next tracked command replaces it. Use this schema:
+Writing the initial activity record is the first action of a tracked command, before project inspection, preflight, or other tool calls. This one generated state write does not authorize product changes or bypass any safety check.
+
+Never create or edit `run.json` directly. From the project root, use the first helper that exists:
+
+```text
+node .agents/skills/doctor/scripts/run-state.mjs <action> <options>
+node .claude/skills/doctor/scripts/run-state.mjs <action> <options>
+```
+
+Start with `start --command <skill> --summary <truthful-summary> --boundary <boundary>`. Use `update` at meaningful milestones or for a blocker, with `--status blocked` and `--resume <exact-command>` when recovery is needed. End with `finish --status ready|completed --summary <truthful-summary>`. The helper validates every field before atomically replacing the generated file. If it is missing or fails, report the activity warning and continue the workflow without writing a manual fallback.
+
+The helper writes this schema:
 
 ```json
 {

package/template/devflow/analysis/REQ-20260903-001-sync-upstream-ai-blueprint/codebase-impact.md

@@ -0,0 +1,46 @@
+# Codebase Impact & Blast Radius Analysis
+
+> **Requirement ID**: `REQ-20260903-001-sync-upstream-ai-blueprint`  
+> **Date**: 2026-09-03  
+> **Complexity Score**: `Low-to-Medium (Controlled Enhancement)`  
+> **Risk Level**: `Low (No Breaking Changes, Backward-Compatible)`  
+
+---
+
+## 1. Blast Radius Map (ขอบเขตผลกระทบ)
+
+```mermaid
+graph TD
+    Upstream["Upstream AI Blueprint v1.5.2"] --> Onboard[".agents & .claude /skills/onboard/SKILL.md"]
+    Upstream --> Overview[".agents & .claude /skills/overview/SKILL.md"]
+    Upstream --> Context["devflow/context/ai-interaction.md"]
+    Upstream --> E2E["scripts/e2e/scenarios/unborn-onboarding.ts"]
+    Upstream --> Validator["scripts/validate-framework.ts"]
+    
+    Onboard --> TemplateOnboard["packages/create-nexus-devflow template"]
+    Overview --> TemplateOverview["packages/create-nexus-devflow template"]
+    Context --> TemplateContext["packages/create-nexus-devflow template"]
+```
+
+---
+
+## 2. Affected Files & Modules (รายการไฟล์ที่ได้รับผลกระทบ)
+
+| File Path | Action | Description |
+| :--- | :--- | :--- |
+| `.agents/skills/onboard/SKILL.md` | `MODIFY` | เพิ่ม Step 0 ตรวจจับ Unborn repository และเสนอกระบวนการ Root scaffold commit |
+| `.claude/skills/onboard/SKILL.md` | `MODIFY` | ปรับปรุงพฤติกรรมให้ตรงกับ `.agents/` |
+| `.agents/skills/overview/SKILL.md` | `MODIFY` | เพิ่มความสามารถ Setup branch baseline finalization (`git merge --ff-only`) |
+| `.claude/skills/overview/SKILL.md` | `MODIFY` | ปรับปรุงพฤติกรรมให้ตรงกับ `.agents/` |
+| `devflow/context/ai-interaction.md` | `MODIFY` | อัปเดตระเบียบการ baseline commit บน setup branch |
+| `scripts/e2e/scenarios/unborn-onboarding.ts` | `NEW` | เพิ่มชุดทดสอบ E2E scenario ตัวที่ 9 สำหรับ unborn repo & fast-forward baseline |
+| `scripts/validate-framework.ts` | `MODIFY` | เพิ่ม verification contracts สำหรับ onboard unborn check และ overview finalization prompt |
+| `packages/create-nexus-devflow/template/` | `SYNC` | ซิงก์ template ผ่าน `npm run check` |
+
+---
+
+## 3. Risk & Breaking Change Assessment
+
+- **Contract Breaking Risk**: `None` — ไม่มีการเปลี่ยนแปลงโครงสร้างคำสั่งหรือโฟลเดอร์หลัก ทุกการเปลี่ยนแปลงเป็นส่วนขยายเพื่อรองรับ Edge Case ที่ยังไม่มี commit
+- **Git Safety Risk**: `Zero Remote Exposure` — มีการล็อกกฎความปลอดภัยไม่ให้มีการ push ไปยัง remote ในระหว่าง Onboard และ Overview อย่างเข้มงวด
+- **Test Coverage Impact**: เพิ่ม Coverage โดยมี scenario ใหม่ `unborn-onboarding.ts` ในชุด E2E Agent Runner

package/template/devflow/build-plan.md

@@ -174,11 +174,41 @@
 
 ---
 
-## 🧹 Phase 22: Reference Artifacts Housekeeping
+## 🎨 Phase 22: Visual Dashboard & Diagram Integration
 
-- [x] **22. Prune Studio Reference Artifacts (`069-prune-studio-reference-artifacts`)** `[Size: S]`
+- [x] **22. Standalone HTML Report Diagram Integration (`DISC-20260902-003`, `069-report-html-diagram-integration`)** `[Size: S]`
+  - *Dependencies*: Feature 17 (`055`), DISC-20260902-003
+  - *Scope*: ปรับปรุง `md2html-report.mjs` รองรับการเรนเดอร์ native Mermaid block (`.mermaid`), เพิ่มการสแกนและ embed ไฟล์ไดอะแกรมจาก `devflow/context/{xxx-slug}/diagrams/` (`.svg` และ `.html`), อัปเดต `report-html` skill ให้ตรวจจับและ auto-install `archify` / `diagram-design` ผ่าน `nexus-devflow skill add` และเขียนชุดทดสอบครอบคลุม
+
+---
+
+## 🧹 Phase 23: Reference Artifacts Housekeeping
+
+- [x] **23. Prune Studio Reference Artifacts (`069-prune-studio-reference-artifacts`)** `[Size: S]`
   - *Dependencies*: None
   - *Scope*: ลบไฟล์ Static HTML Snapshot ตกค้าง `devflow/reference/studio.html` และสคริปต์ `scripts/export-studio.ts` โดยยังคงรักษา Webview Studio Engine (`webview-studio.ts`), MCP tool (`devflow_get_studio_html`), CLI Command (`nexus-devflow studio`) และชุดทดสอบทั้งหมดให้ทำงานได้สมบูรณ์ 100%
 
+---
+
+## 📐 Phase 24: Role-Based Profiles & SA Command Suite Engine
+
+- [x] **24. Role-Based Profiles & SA Analyze Command Engine (`DISC-20260903-001`, `070-role-based-profile-and-sa-analyze-engine`)** `[Size: M]`
+  - *Dependencies*: None
+  - *Scope*: เพิ่มตัวเลือก `--role [sa|dev|full]` ใน CLI Installer (`create-nexus-devflow`), ระบบจำแนกชุด Skill Profiles ใน `skill-manager.ts`, โฟลเดอร์ Template สำหรับ SA (`devflow/inbox/`, `devflow/analysis/`, `devflow/blueprints/`), พัฒนาสคิล `/analyze` สำหรับสกัดเอกสารหลายรูปแบบ (PDF, Word, Excel, รูปภาพ, ข้อความ) และวิเคราะห์ Codebase Impact พร้อมชุดทดสอบ Automated Tests
+
+---
+
+## 🔄 Phase 25: Upstream AI Blueprint v1.5.0 – v1.5.1 Synchronization
+
+- [x] **25. Sync Upstream v1.5.0 & v1.5.1 (Hardened Run-State Engine & On-Demand Context Loading) (`DISC-20260903-001`, `070-sync-upstream-ai-blueprint-v150-v151`)** `[Size: M]`
+  - *Dependencies*: Feature 20, Feature 21, DISC-20260903-001
+  - *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%
+
+---
+
+## 🔄 Phase 26: Upstream AI Blueprint v1.5.2 Synchronization
 
+- [x] **26. Sync Upstream v1.5.2 (Unborn Repository Onboarding & Branch Baseline Finalization) (`REQ-20260903-001`, `071-sync-upstream-ai-blueprint-v152`)** `[Size: S]`
+  - *Dependencies*: Feature 25, REQ-20260903-001
+  - *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%
 

package/template/devflow/context/ai-interaction.md

@@ -52,6 +52,8 @@ devflow/
 ### ⚡ The Unified 4-Stage Task-Isolated Living Spec Lifecycle
 *ขับเคลื่อนการพัฒนาทุกระดับด้วย **Task-Isolated Living Spec (`devflow/context/{xxx-slug}/spec.md`)** ที่รวมความลึกระดับ Architect Mode เข้ากับความคล่องตัวระดับ Lean Velocity โดยแยก Workspace ของแต่ละงานออกจากกัน 100%:*
 
+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.
+
 ```text
 /feature (หรือ /fix) ──▶ /implement ──▶ /check ──▶ /complete
 ```

package/template/devflow/inbox/REQ-20260903-001-sync-upstream-ai-blueprint/clarifications.md

@@ -0,0 +1,34 @@
+# Socratic Clarification Checklist (REQ-20260903-001)
+
+> **Requirement ID**: `REQ-20260903-001-sync-upstream-ai-blueprint`  
+> **Audience**: System Analyst, Tech Lead, Framework Maintainer  
+> **Status**: `Ready for Review`  
+
+---
+
+## 🔍 Socratic Review & Alignment Questions
+
+### 1. Root Scaffold Commit Convention
+- [x] **Question**: รูปแบบ Commit Message สำหรับ Scaffold แรกใน Unborn Repo ควรใช้รูปแบบใด?
+  - **Proposed Decision**: `chore: scaffold application` (มาตรฐานเดียวกับ Upstream AI Blueprint และ Conventional Commits)
+  - **Safety Check**: ต้องไม่รวมโฟลเดอร์ `devflow/`, `AGENTS.md`, `CLAUDE.md`, `.agents/`, `.claude/` เข้าไปใน Root Commit นี้เด็ดขาด
+
+### 2. Setup-Branch Fast-Forward Merge Rule
+- [x] **Question**: ใน `/overview` หากผู้ใช้วางแผนบน dedicated branch (เช่น `feature/devflow-plans`) การรวมกลับเข้า `main` ต้องทำอย่างไร?
+  - **Proposed Decision**: บังคับใช้ `git merge --ff-only` เท่านั้นเพื่อรักษา Linear Git History หากมีการแตก branch ออกไปแบบ non-fast-forward จะต้องหยุดและรายงาน mismatch ทันที
+  - **Safety Check**: ยืนยันการลบ local setup branch หลัง merge สำเร็จ เพื่อไม่ให้มี branch ขยะค้าง
+
+### 3. Local-Only & Remote Push Guard
+- [x] **Question**: การทำ Finalize Baseline มีโอกาสหลุดรัน `git push` หรือไม่?
+  - **Proposed Decision**: ล็อกกฎชัดเจนใน `SKILL.md` ว่าทุกคำสั่งใน Onboard และ Overview ทำงานในระดับ Local Git เท่านั้น (No Push)
+
+---
+
+## 📋 Actionable Checklist for Implementation
+
+- [ ] ปรับปรุง `.agents/skills/onboard/SKILL.md` และ `.claude/skills/onboard/SKILL.md` เพื่อตรวจจับ Unborn `HEAD` และเสนอ Scaffold Root Commit
+- [ ] ปรับปรุง `.agents/skills/overview/SKILL.md` และ `.claude/skills/overview/SKILL.md` สำหรับ Setup-Branch Baseline Finalization (`git merge --ff-only`)
+- [ ] อัปเดต `devflow/context/ai-interaction.md` ให้ระบุสิทธิการทำ Baseline Finalization บน Setup Branch
+- [ ] พอร์ต E2E Scenario `scripts/e2e/scenarios/unborn-onboarding.ts` ให้เข้ากับโครงสร้างและชื่อคำสั่งของ Nexus-DevFlow
+- [ ] เพิ่ม static verification contract ใน `scripts/validate-framework.ts`
+- [ ] รันการตรวจสอบความถูกต้องของระบบครบทุก Lane (`npm run check:static`, `npm test`, `npm run check`)