@jakkrichm/create-nexus-devflow 2.11.0 → 2.12.0

package/template/.agents/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/.agents/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/.agents/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/.agents/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/.agents/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/.claude/skills/analyze/SKILL.md

@@ -0,0 +1,113 @@
+---
+name: analyze
+description: "[devflow] Unified SA requirement ingestion, multi-format doc parsing (PDF, Word, Excel, images, text), codebase impact scan, and Socratic clarification checklist."
+argument-hint: "[{file-path, raw requirement text, or REQ-ID}]"
+---
+
+# analyze - SA Requirement Ingestion & Codebase Impact Analysis
+
+$ARGUMENTS
+
+**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`.
+
+`/analyze` is the flagship System Analyst (SA) entry point in Nexus-DevFlow. It ingests messy, multi-format requirements, auto-allocates an isolated Request Workspace, normalizes raw content into structured Markdown, scans codebase impact (for existing systems), and generates a Socratic clarification checklist before system design.
+
+---
+
+## Invocations & Usage
+
+```text
+# 1. Ingest specific file from any path (PDF, DOCX, XLSX, Image, CSV, Text)
+/analyze C:\Users\...\Downloads\customer-spec.pdf
+/analyze ./mockup.png ./schema.xlsx "ระบบสะสมแต้มสมาชิก"
+
+# 2. Ingest raw text or requirement from chat
+/analyze "ลูกค้าต้องการระบบผ่อนชำระ 0% เชื่อมกับ KBank Payment Gateway..."
+
+# 3. Scan pending unassigned files in devflow/inbox/
+/analyze
+
+# 4. Resume analysis on an existing Request ID
+/analyze REQ-20260903-001
+```
+
+---
+
+## 4-Step Analysis Execution Pipeline
+
+```text
+[Multi-format Input] ──▶ 1. Auto-Allocate & Ingest ──▶ 2. Parse & Normalize 
+                                                              │
+                                                              ▼
+[Clarification Checklist] ◀── 4. Socratic Gap Scan ◀── 3. Codebase Impact Scan
+```
+
+---
+
+### Step 1: Auto-Allocate Workspace & Ingestion (Frictionless Ingest)
+1. **Allocate REQ-ID**: Generate sequential ID format `REQ-YYYYMMDD-NNN` (e.g. `REQ-20260903-001-point-system`).
+2. **Create Request Workspace**:
+   ```text
+   devflow/inbox/{REQ-ID}/
+   ├── raw/                # เก็บไฟล์ต้นฉบับ (PDF, Word, Excel, Images, Email)
+   ├── parsed.md           # ข้อความ/ตารางที่สกัดออกมาแล้ว (Clean Markdown)
+   └── clarifications.md   # รายการคำถามที่ต้องไปถาม Stakeholder เพิ่ม
+   ```
+3. Copy or save incoming files into `devflow/inbox/{REQ-ID}/raw/`.
+
+---
+
+### Step 2: Parse & Normalize Requirement (`parsed.md`)
+1. Extract text and tables from all raw files:
+   - For Office/PDF docs: Invoke `convert-any-to-md` or document extractor.
+   - For Web URLs / Confluence / Notion: Invoke `defuddle`.
+   - For Images / Wireframes / Screenshots: Conduct Multimodal Vision OCR and describe layout and fields.
+2. Structure into `devflow/inbox/{REQ-ID}/parsed.md`:
+   - **Executive Summary**: วัตถุประสงค์หลักของ Requirement
+   - **Target Persona & User Stories**: ใครทำอะไร เพื่ออะไร
+   - **Functional Requirements (FR)**: รายการฟังก์ชันและ Business Rules
+   - **Non-Functional Requirements (NFR)**: Performance, Security, PDPA, Retention
+   - **Data Entities & Fields**: ฟิลด์ข้อมูลและชนิดข้อมูลเบื้องต้น
+
+---
+
+### Step 3: Codebase Impact & Blast Radius Analysis (`codebase-impact.md`)
+*(ดำเนินการเมื่อเป็นระบบเดิม / Brownfield Codebase)*
+
+1. Search codebase patterns using `grep_search`, `rg`, and AST analysis for affected models, controllers, APIs, and routes.
+2. Calculate **Blast Radius & Complexity Score**:
+   - **Affected Files & Modules**: รายการไฟล์ที่ต้องแก้ไขหรือสร้างใหม่
+   - **API & Contract Breaking Risk**: ตรวจสอบว่ากระทบกับ API เดิมหรือ Third-Party หรือไม่
+   - **Complexity Rating**: `Low` | `Medium` | `High` | `Extreme` พร้อมเหตุผล
+3. Save analysis report to `devflow/analysis/{REQ-ID}/codebase-impact.md`.
+
+---
+
+### Step 4: Socratic Gap Detection & Clarification Checklist (`clarifications.md`)
+1. Apply `grilling` and `domain-modeling` lenses to detect gaps:
+   - **Missing Edge Cases**: เงื่อนไขขอบ, กรณีข้อมูลผิดพลาด, เน็ตหลุด, Concurrent Requests
+   - **Ambiguous Business Rules**: กฎที่ยังคลุมเครือ ไม่ระบุ SLA หรือขั้นตอนที่ชัดเจน
+   - **Security & Authorization**: การกำหนด Role, สิทธิ์การเข้าถึงข้อมูล, ข้อมูลส่วนบุคคล (PII)
+2. Generate an actionable checklist in `devflow/inbox/{REQ-ID}/clarifications.md` for the SA to take directly into stakeholder meetings.
+
+---
+
+## Output Artifacts Summary
+
+| Artifact | Location | Purpose |
+| :--- | :--- | :--- |
+| **Raw Files** | `devflow/inbox/{REQ-ID}/raw/` | Archived original files |
+| **Parsed Spec** | `devflow/inbox/{REQ-ID}/parsed.md` | Clean structured Markdown requirements |
+| **Impact Report** | `devflow/analysis/{REQ-ID}/codebase-impact.md` | Codebase blast radius & complexity score |
+| **Clarifications** | `devflow/inbox/{REQ-ID}/clarifications.md` | Socratic questions for stakeholders |
+
+---
+
+## Next Workflow Step
+
+Once analysis is reviewed and gaps are aligned, proceed to **System Design & Acceptance Test Matrix**:
+```bash
+/design {REQ-ID}
+```

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

@@ -1,20 +1,23 @@
 ---
 name: doctor
-description: "[devflow] Run a read-only DevFlow health and context check covering setup, adapters, commands, visibility, plans, overview freshness, configuration, and workflow drift. Use for /doctor, setup problems, context overhead, or health checks."
+description: "[devflow] Run a DevFlow health and context check covering setup, adapters, commands, visibility, plans, overview freshness, configuration, dashboard state, and workflow drift. May offer to reset malformed generated dashboard state after approval. Use for /doctor, setup problems, context overhead, or health checks."
 ---
 
-# doctor - Blueprint health check
+# doctor - DevFlow health check
+
+**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  ->  [doctor]  ->  reads setup + plans + workflow state + git
-                  (read-only)   prints health, warnings, and repair order
+                  (diagnostic)  prints health, warnings, and repair order
 
-This skill answers one question: *is this Blueprint project ready to use?* It is
+This skill answers one question: *is this DevFlow project ready to use?* It is
 the diagnostic pass for setup drift, incomplete onboarding, missing files,
-placeholder plans, stale generated context, Blueprint visibility, and confusing
+placeholder plans, stale generated context, DevFlow visibility, and confusing
 workflow state. It never changes anything: no edits, no commits, no installs, no
-builds, no branch changes.
+builds, no branch changes. Its only repair is an approved reset of a malformed
+generated `devflow/.state/run.json` file.
 
 Use `/status` when the user mainly wants progress and the next build action. Use
 `/doctor` when the user wants to know whether the workflow itself is healthy.
@@ -66,6 +69,10 @@ Gather these, then summarize. Do not dump file contents.
      logical adapters: Codex, Claude Code, GitHub Copilot, Antigravity, and OpenCode.
    - Confirm at least one compatible skill tree exists. Codex, Antigravity, and
      GitHub Copilot use `.agents/skills/`. Claude Code uses `.claude/skills/`.
+   - Confirm each installed adapter tree contains
+     `doctor/scripts/run-state.mjs`. This managed helper validates and atomically
+     writes dashboard activity. A missing helper needs a DevFlow update before
+     tracked commands can record activity safely.
    - If both skill trees are present, say that is healthy when the selected
      tools require both. Compare their skill folder names and warn about missing
      skills on either side.
@@ -105,39 +112,41 @@ Gather these, then summarize. Do not dump file contents.
    - A missing `Verify` command or GitHub workflow is informational. It means the
      optional automatic-check setup was not selected, not that DevFlow is
      unhealthy.
-4. **Ignore rules**
-   - Check obvious ignore patterns for the detected stack. For Node or Astro,
-     look for `node_modules`, `.env`, `dist`, and framework cache folders such as
-     `.astro` or `.next` when relevant.
-   - Detect local-only DevFlow mode if `.gitignore` ignores `.agents/`,
-     `.claude/`, `devflow/`, or `CLAUDE.md`. Report it as a visibility choice,
-     not a failure, when the local files exist.
-   - In local-only mode, check whether tracked `AGENTS.md` still describes the
-     Blueprint workflow, lists hidden adapter paths, or exposes the core skill
-     list. If so, warn that `/onboard` should make `AGENTS.md` public-safe.
-   - If local-only mode is active but those paths are already tracked by git,
-     warn that `.gitignore` does not hide tracked files and the user must approve
-     any `git rm --cached` cleanup separately.
-   - Keep this conservative. If uncertain, report "review" instead of failure.
-5. **Planning readiness**
-   - Check whether `devflow/project-plan.md` and `devflow/build-plan.md` look
-     filled in or still template-like. Treat obvious TODO, TBD, example-only text,
-     or empty required sections as not ready.
-   - Check whether `devflow/build-plan.md` is a numbered checkbox list. Raw
-     bullets are allowed as a first draft, but they should be normalized by
-     `/overview` before the build loop starts.
-   - Count checked and unchecked leaf items in `devflow/build-plan.md`.
-6. **Overview freshness**
-   - Check whether `devflow/context/project-overview.md` exists and looks
-     generated from the current plans.
+4. **Visibility and context loading**
+   - Confirm whether DevFlow files are public in git or listed in `.gitignore`
+     as local-only.
+   - When Claude Code is installed, report its startup-context shape. Confirm
+     `CLAUDE.md` imports `AGENTS.md` and lets skills load planning context on demand.
+5. **Project and build plans**
+   - Read `devflow/project-plan.md` and `devflow/build-plan.md`.
+   - Report total features in the build plan, how many are checked off (`- [x]`),
+     and which feature is next.
+   - Flag placeholder text (e.g. `[Your project name]`, `Feature 1 description`).
+6. **Project overview freshness**
+   - Read `devflow/context/project-overview.md` if it exists.
    - Report its byte size. At or above 20,000 bytes, call it oversized and say
      `/feature` should stop until `/overview` regenerates a compact
      consolidation.
    - If either planning file appears newer than the overview by filesystem time,
      call the overview possibly stale and suggest `/overview` before feature work.
 7. **Current workflow state**
-   - Scan `devflow/context/{xxx-slug}/` for active task directories and specs.
-   - If a spec is active, report checked and unchecked implementation steps.
+   - Inspect `devflow/.state/run.json` when it exists. Missing means no recorded
+     activity and is healthy. Require a regular non-symbolic-link JSON file that
+     matches dashboard schema version 1 from `AGENTS.md`.
+   - If the path is a symbolic link or not a regular file, do not read, replace,
+     or remove it. Report the exact path for manual review.
+   - If the regular file is invalid JSON or does not match the schema, report it
+     as malformed generated state. Explain that resetting it removes only the
+     dashboard's last-command record, not project work, and that the next tracked
+     DevFlow command recreates it.
+   - Offer this exact repair question: `Reset the malformed dashboard state now?`
+     On approval, use the installed dashboard activity helper's `reset` action.
+     It confirms the exact path is a regular non-symbolic-link file and removes
+     only `devflow/.state/run.json`. Verify the file is absent and report the
+     dashboard state as reset. Never remove `devflow/.state/`, its manifest,
+     backups, or any project file. Without approval, leave it unchanged and
+     include the reset in `Repair order:`.
+   - If a spec is active in `devflow/context/{xxx-slug}/`, report checked and unchecked implementation steps.
    - If no active task directory exists in `devflow/context/` but git has source or workflow
      changes, warn that work is happening without an active spec.
    - Flag active spec on `main`, all spec steps checked but no completion, or a
@@ -168,28 +177,20 @@ steps, in order. Keep it short and practical.
 
 Choose the repair order in this priority:
 
-- Required Blueprint files missing -> overlay the Blueprint again, or use
-  `/adopt` for a brownfield app.
+- Required DevFlow files missing -> overlay DevFlow again, or use `/adopt` for a brownfield app.
 - No git repo -> initialize git before using the build loop.
 - No tool adapter -> restore `.agents/skills/` or `.claude/skills/` for the
   selected tool. OpenCode can use either compatible tree.
+- Installed adapter is missing `doctor/scripts/run-state.mjs` -> update
+  DevFlow before relying on dashboard activity.
 - Onboarding incomplete -> run `/onboard`.
-- Root README is still the Blueprint workflow doc -> run `/onboard` to replace
+- Root README is still the DevFlow workflow doc -> run `/onboard` to replace
   it with a project README before publishing.
-- Local-only visibility selected but ignored Blueprint files are missing ->
-  reinstall or restore the Blueprint files locally.
-- Local-only visibility selected but Blueprint paths are tracked -> ask whether
-  to untrack them with `git rm --cached` while keeping local files.
-- Local-only visibility selected but `AGENTS.md` still exposes the workflow ->
-  run `/onboard` to make `AGENTS.md` a lightweight public project guide.
-- A documented `Verify` command, project script, and GitHub workflow disagree ->
-  run `/ci` to review and align them. Missing optional CI alone does not need
-  repair.
-- Commands or ignore rules need review -> update the files or run `/onboard` if
-  this is an early project.
 - Plans are placeholders -> fill `devflow/project-plan.md` and
   `devflow/build-plan.md`.
 - Overview missing or stale -> run `/overview`.
+- Malformed regular `devflow/.state/run.json` -> offer to reset that exact
+  generated file, then rerun `/doctor` or refresh the dashboard.
 - Active spec has unchecked steps -> run `/status` or `/implement`, depending on
   whether the user wants orientation or action.
 - A P0 or P1 finding is `open` -> repair it through `/implement` while a spec
@@ -201,8 +202,10 @@ Choose the repair order in this priority:
 
 ## Rules
 
-- **Read-only, always.** This skill never writes files, never commits, never runs
-  installs, never runs builds or tests, and never switches branches.
+- **Diagnostic by default.** This skill never edits project files, commits, runs
+  installs, runs builds or tests, or switches branches. It may remove only a
+  malformed regular `devflow/.state/run.json` through the installed helper
+  after the user approves the exact reset described above.
 - **Diagnose, then order repairs.** Do not just list problems. End with the
   smallest ordered sequence that gets the project back to a healthy state.
 - **Do not over-police adapters.** Extra adapters are optional clutter, not a