@jakkrichm/create-nexus-devflow 2.0.6 → 2.0.8

package/lib/starter-templates.js

@@ -0,0 +1,111 @@
+const starterTemplates = {
+  projectOverview: `# Project Overview
+
+> **DevFlow Context Source of Truth.**
+> Single AI-facing source of truth for project architecture, stack, and shipped capabilities.
+> Run \`/onboard\` (for fresh projects) or \`/adopt\` (for existing codebases) to populate this file automatically.
+
+## 1. Project Summary
+
+- **Name**: [Project Name]
+- **Description**: [One-line summary of project purpose]
+- **Primary Stack**: [Framework / Language / Runtime]
+
+## 2. Architecture & Modules
+
+- \`src/\` - Core application source code
+
+## 3. Shipped Capabilities
+
+- None recorded yet. Run \`/onboard\` or \`/adopt\` to initialize.
+`,
+
+  codingStandards: `# Coding Standards
+
+> Project conventions and rules to follow during development.
+> Run \`/onboard\` (or \`/adopt\` for existing codebases) to tune these standards to your specific stack.
+
+## Architecture and Conventions
+
+- Write clean, modular, and maintainable code with clear single responsibilities.
+- Prefer TypeScript and explicit interfaces where available.
+- Keep dependencies lean and justified.
+
+## Code Organization & Style
+
+- Structure source code following framework-native conventions.
+- Keep functions focused and avoid deeply nested logic.
+- Use consistent naming conventions (camelCase for functions/variables, PascalCase for components/types).
+
+## Error Handling & Security
+
+- Handle errors explicitly and provide meaningful error messages.
+- Never hardcode credentials, secrets, or API keys in source code.
+- Sanitize and validate all user inputs.
+
+## Testing & Quality
+
+- Follow the TDD workflow for behavior-changing code units.
+- Run tests and linting before completing features or fixes.
+`,
+
+  currentStage: `# Current DevFlow Run Status
+
+- **Active Discovery ID**: None
+- **Active Running ID**: None
+- **Current Stage**: Idle
+- **Last Completed Run**: None
+- **Last Updated**: -
+`,
+
+  findings: `# Findings Ledger
+
+> Review findings raised by \`/security-review\` or QA audits.
+> Resolved findings are tracked with durable IDs.
+
+- **Total Open P0/P1**: 0
+- **Total Tracked**: 0
+
+_No findings recorded._
+`,
+
+  aiInteraction: `# AI Interaction Guidelines for DevFlow
+
+> **DevFlow is an agentic workflow layer**, overlaying on top of scaffolded or existing codebases.
+
+## Communication & Interaction
+
+- Be concise and direct in communication.
+- Explain technical trade-offs and non-obvious design decisions briefly.
+- Always confirm before performing major refactors or destructive operations.
+- Maintain markdown-first evidence for all stage activities.
+
+## Artifact Language
+
+- Default language for user-facing artifacts and summaries is Thai (\`th\`), while code, paths, and identifiers remain in English.
+- Use exact schema headings when validators check for specific contract sections.
+
+## Output Formatting
+
+- Use GitHub-style markdown for clean scanning.
+- Use lists for steps, options, and findings.
+- Use tables for comparative matrices or stage summaries.
+- Use backticks for paths, filenames, identifiers, and CLI commands.
+
+## DevFlow Timeline Lifecycle
+
+\`\`\`text
+/00-Discover -> /10-Define -> /20-Spec -> /30-Plan -> /40-Implement -> /50-Verify -> /60-Report -> /70-Release
+\`\`\`
+
+- Run \`/00-Discover\` to explore requests under a Discovery ID.
+- Run \`/10-Define\` to set delivery boundaries and allocate Running IDs.
+- Run \`/20-Spec\` and \`/30-Plan\` to establish formal delivery specifications and execution plans.
+- Run \`/40-Implement\` for step-by-step code implementation with evidence.
+- Run \`/50-Verify\`, \`/60-Report\`, and \`/70-Release\` for quality verification, reporting, and release packaging.
+`
+};
+
+module.exports = {
+  starterTemplates
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jakkrichm/create-nexus-devflow",
-  "version": "2.0.6",
+  "version": "2.0.8",
   "description": "Install or update the agent-ready DevFlow 2.0 workflow layer into a scaffolded or existing project.",
   "license": "MIT",
   "author": "Jakkrich",

package/template/.agents/skills/adopt/SKILL.md

@@ -0,0 +1,95 @@
+---
+name: adopt
+description: Bootstrap Nexus-DevFlow into an existing (brownfield) codebase. Surveys the real repository (read-only), interviews the user for intent, generates project-overview.md and coding-standards.md from existing code, tunes AGENTS.md commands, and seeds the initial Discovery or Run map. Use when the user runs adopt, /adopt, $adopt, is overlaying DevFlow onto an app that already has meaningful code, or asks to adopt DevFlow into an existing project. For freshly scaffolded or early projects, use onboard instead.
+---
+
+# adopt - Bootstrap Nexus-DevFlow from an Existing Codebase
+
+Where this sits in the workflow:
+
+```text
+existing codebase  ->  [adopt]  ->  project-overview + coding-standards  ->  /00-discover or /10-define
+(already has code)     (survey +    (seeded from the real code;               (first feature / refactoring
+                        interview)   shipped architecture documented)          delivery lifecycle)
+```
+
+Standard onboarding assumes a freshly scaffolded, near-empty app. That does not fit a codebase that already has thousands of lines of working code.
+
+`/adopt` is the brownfield on-ramp for Nexus-DevFlow: it reads what is already there, asks only for what the code cannot reveal (the *intent*, the *why*, and the *upcoming roadmap*), and produces the exact context files the rest of the DevFlow lifecycle expects (`project-overview.md`, `coding-standards.md`, `AGENTS.md` commands).
+
+---
+
+## Input
+
+A description of what the project is, if provided. Otherwise, inspect the repository directly. No argument is required.
+
+---
+
+## Step 0 - Confirm Brownfield Safety
+
+Inspect `devflow/context/project-overview.md` and `devflow/context/coding-standards.md`:
+
+- If they contain default placeholders or empty templates, proceed.
+- If they already hold rich, user-owned content, stop and inform the user; offer to refresh specific sections rather than overwriting existing context without confirmation.
+
+Never run a framework scaffolder (DevFlow is an overlay, never a generator).
+
+---
+
+## Step 1 - Survey the Codebase (Read-Only)
+
+Read the repository to establish the facts. Change nothing in this step:
+
+- **Stack & Tooling**: Languages, frameworks, and versions from manifest files (`package.json`, `requirements.txt`, `pyproject.toml`, `go.mod`, `Cargo.toml`, etc.). Note the active package manager from lockfiles.
+- **Commands**: Real dev, build, test, lint, and verify scripts.
+- **Conventions in Practice**: Directory layout, component naming, state management, styling, data-fetching, error handling, validation. Read what the code *actually does*.
+- **Testing Reality**: Inspect existing test suites, runners, and coverage. Be honest about test status.
+- **Shipped Capabilities & Architecture**: Inferred from routes, pages, controllers, database schemas, and entry points.
+
+Keep structured notes for generation in Step 3.
+
+---
+
+## Step 2 - Interview for Intent
+
+The code reveals *what* and *how*, but not *why* or *what next*. Ask a short set of 3-4 questions to fill the gaps:
+
+1. **Purpose & Users**: What is the core problem this project solves, and who are the target users?
+2. **Architecture Status**: Is the current structure and stack intentional, or are there legacy parts/technical debt the team wants to change or refactor?
+3. **Upcoming Roadmap**: What are the top priorities to build, fix, or refactor next?
+4. **Clarifications**: Anything the survey got wrong or missed?
+
+*(If the user already provided this context in the prompt, skip questions that are already answered).*
+
+---
+
+## Step 3 - Generate the Context Artifacts
+
+Write the baseline context files drawn from the survey (facts) and interview (intent):
+
+1. **`devflow/context/project-overview.md`**:
+   - Project Name, Purpose, and Target Users
+   - Architecture summary and directory layout
+   - Shipped capabilities and existing major modules
+   - Key technical stack components and verified commands
+   - Known technical debt or architectural focus areas
+
+2. **`devflow/context/coding-standards.md`**:
+   - Rewrite defaults to reflect the project's *actual* conventions discovered in Step 1
+   - Framework patterns, state management, error handling, styling, and test rules based on real code
+
+3. **`AGENTS.md` Commands Section**:
+   - Fill in the real dev, build, test, lint, and verify commands found during survey.
+
+---
+
+## Step 4 - Review Gate and Handoff
+
+Present the adoption summary for review:
+
+- Shipped features and architectural baseline recorded
+- Inferred conventions and coding standards
+- Available verified commands in `AGENTS.md`
+- Recommended next step:
+  - Run `00-discover` (or `/00-discover`, `$00-discover`) to explore the next major initiative or feature
+  - Run `10-define` (or `/10-define`, `$10-define`) to immediately scope a delivery run for known roadmap items

package/template/.agents/skills/devflow/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: devflow
-description: Flagship interactive guide, intent router, workspace state inspector, and sitemap for Nexus-DevFlow workflows. Inspects current workspace state, maps natural language requests to matching stages/commands, and provides a cheat sheet of all available DevFlow skills. Use when the user runs /devflow, asks how to use devflow, asks what command to run next, or needs guidance on DevFlow lifecycle paths.
+description: Flagship interactive guide, intent router, workspace state inspector, and sitemap for Nexus-DevFlow workflows. Inspects current workspace state, maps natural language requests to matching stages/commands, and provides a cheat sheet of all available DevFlow skills. Use when the user runs devflow, /devflow, $devflow, status, asks how to use devflow, asks what command to run next, or needs guidance on DevFlow lifecycle paths.
 ---
 
 # devflow - Interactive Workflow Guide & Intent Router for Nexus-DevFlow
@@ -9,78 +9,87 @@ Use this skill to guide the user on what to do next, inspect current workspace s
 
 ## Input
 
-- **No argument (`/devflow`)**: Inspect current workspace state (active run in `devflow/runs/` or `devflow/context/current-stage.md`, active discovery in `devflow/discoveries/`, open findings in `devflow/context/findings.md`, and project overview in `devflow/context/project-overview.md`) and recommend the exact next action.
-- **With user request (`/devflow "<request>"`)**: Classify the user's intent and guide them to the matching DevFlow 2.0 stage or companion command path.
+- **No argument (`devflow`, `/devflow`, `$devflow`, or `status`)**: Inspect current workspace state (active run in `devflow/runs/` or `devflow/context/current-stage.md`, active discovery in `devflow/discoveries/`, open findings in `devflow/context/findings.md`, and project overview in `devflow/context/project-overview.md`) and recommend the exact next action.
+- **With user request (`devflow "<request>"`)**: Classify the user's intent and guide them to the matching DevFlow 2.0 stage or companion command path.
 
 ## Workspace State Inspection
 
 When invoked without an argument (or when determining the next step), inspect:
 
-1. **Active Delivery Run**: Read `devflow/context/current-stage.md` and check `devflow/runs/{RUNNING_ID}/` for active artifacts (`10-define.md`, `20-spec.md`, `30-plan.md`, `40-implement.md`, `50-verify.md`, `60-report.md`, `70-release.md`).
-2. **Active Discovery**: Check `devflow/discoveries/` for open discovery notes.
-3. **Audit Findings Ledger**: Check `devflow/context/findings.md` for open high-severity findings.
-4. **Project Overview**: Read `devflow/context/project-overview.md` for overall stack and context.
+1. **Project Setup Baseline**: Read `devflow/context/project-overview.md` and `devflow/context/coding-standards.md`. If they are empty or default placeholders, recommend `/onboard` (for fresh projects) or `/adopt` (for existing codebases).
+2. **Active Delivery Run**: Read `devflow/context/current-stage.md` and check `devflow/runs/{RUNNING_ID}/` for active artifacts (`10-define.md`, `20-spec.md`, `30-plan.md`, `40-implement.md`, `50-verify.md`, `60-report.md`, `70-release.md`).
+3. **Active Discovery**: Check `devflow/discoveries/` for open discovery notes.
+4. **Audit Findings Ledger**: Check `devflow/context/findings.md` for open high-severity findings.
 
 ### State-Based Recommendation Rules
 
-- If a run is at `10-define.md` -> Recommend `/20-spec {RUNNING_ID}`.
-- If a run is at `20-spec.md` -> Recommend `/30-plan {RUNNING_ID}`.
-- If a run is at `30-plan.md` -> Recommend `/40-implement {RUNNING_ID}`.
-- If a run is at `40-implement.md` with incomplete tasks -> Recommend `/40-implement {RUNNING_ID}`.
-- If a run is at `40-implement.md` with all tasks done -> Recommend `/50-verify {RUNNING_ID}`.
-- If a run passed `50-verify.md` -> Recommend `/60-report {RUNNING_ID}` then `/70-release {RUNNING_ID}`.
-- If no run is active and user wants to explore an idea -> Recommend `/00-discover` or `Brainstorm`.
-- If no run is active and open P0/P1 findings exist -> Recommend `Security-Review` or `Debug`.
+- If context is empty/unconfigured -> Recommend `onboard` (for fresh project) or `adopt` (for brownfield codebase).
+- If a run is at `10-define.md` -> Recommend `20-spec {RUNNING_ID}` (or `/20-spec`, `$20-spec`, `spec`).
+- If a run is at `20-spec.md` -> Recommend `30-plan {RUNNING_ID}` (or `/30-plan`, `$30-plan`, `plan`).
+- If a run is at `30-plan.md` -> Recommend `40-implement {RUNNING_ID}` (or `/40-implement`, `$40-implement`, `implement`).
+- If a run is at `40-implement.md` with incomplete tasks -> Recommend `40-implement {RUNNING_ID}`.
+- If a run is at `40-implement.md` with all tasks done -> Recommend `50-verify {RUNNING_ID}` (or `/50-verify`, `$50-verify`, `verify`).
+- If a run passed `50-verify.md` -> Recommend `60-report {RUNNING_ID}` then `70-release {RUNNING_ID}`.
+- If no run is active and user wants to explore an idea -> Recommend `00-discover` (or `discover`, `Brainstorm`).
+- If no run is active and open P0/P1 findings exist -> Recommend `security-review` or `debug`.
+- If user asks to check system health or configuration -> Recommend `doctor` (or `/doctor`, `$doctor`).
 
 ## Intent Classification & Skill Routing
 
 When the user specifies a request, map it to the matching DevFlow 2.0 stage or companion command:
 
-| User Intent / Request Type | Recommended Skill | Lifecycle Path |
-| --- | --- | --- |
-| "Explore a new request / idea" | `/00-discover` | `/00-discover` -> `/10-define` -> `/20-spec` -> ... |
-| "Define delivery boundaries and ID" | `/10-define` | `/10-define` -> `/20-spec` -> `/30-plan` |
-| "Write formal markdown specification" | `/20-spec` | `/20-spec` -> `/30-plan` -> `/40-implement` |
-| "Break down spec into actionable plan" | `/30-plan` | `/30-plan` -> `/40-implement` -> `/50-verify` |
-| "Execute code implementation" | `/40-implement` | `/40-implement` -> `/50-verify` |
-| "Verify code quality & QA review" | `/50-verify` | `/50-verify` -> `/60-report` -> `/70-release` |
-| "Generate summary HTML/MD report" | `/60-report` | `/60-report` -> `/70-release` |
-| "Package for PR merge or deployment" | `/70-release` | `/70-release` |
-| "High-level goal or long-running task" | `Goal` | `Goal` -> `/00-discover` |
-| "Brainstorm ideas without allocating ID" | `Brainstorm` | `Brainstorm` -> `/00-discover` |
-| "Deep codebase or web research" | `Research` | `Research` |
-| "Investigate failure or root cause" | `Debug` | `Debug` -> `/40-implement` or `/10-define` |
-| "Product framing & PRD creation" | `PRD` | `PRD` -> `/00-discover` |
-| "Intake and triage incoming bugs" | `Issue-Triage` | `Issue-Triage` -> `Debug` or `/10-define` |
-| "High-severity security audit" | `Security-Review` | `Security-Review` |
-| "Manage project knowledge base" | `Wiki` | `Wiki` |
-| "Verify or update DevFlow setup" | `Check-For-Updates` | `Check-For-Updates` |
+| User Intent / Request Type | Recommended Skill | Normal Name / Alias | Lifecycle Path |
+| :--- | :--- | :--- | :--- |
+| "Setup DevFlow on fresh/new project" | `onboard` | `onboard` / `setup` | `onboard` -> `00-discover` or `10-define` |
+| "Adopt DevFlow on existing codebase" | `adopt` | `adopt` / `bootstrap` | `adopt` -> `00-discover` or `10-define` |
+| "Check setup health & diagnostics" | `doctor` | `doctor` / `health` | `doctor` |
+| "Explore a new request / idea" | `00-discover` | `discover` | `00-discover` -> `10-define` -> `20-spec` -> ... |
+| "Define delivery boundaries and ID" | `10-define` | `define` | `10-define` -> `20-spec` -> `30-plan` |
+| "Write formal markdown specification" | `20-spec` | `spec` | `20-spec` -> `30-plan` -> `40-implement` |
+| "Break down spec into actionable plan" | `30-plan` | `plan` | `30-plan` -> `40-implement` -> `50-verify` |
+| "Execute code implementation" | `40-implement` | `implement` | `40-implement` -> `50-verify` |
+| "Verify code quality & QA review" | `50-verify` | `verify` | `50-verify` -> `60-report` -> `70-release` |
+| "Generate summary HTML/MD report" | `60-report` | `report` | `60-report` -> `70-release` |
+| "Package for PR merge or deployment" | `70-release` | `release` | `70-release` |
+| "High-level goal or long-running task" | `goal` | `goal` | `goal` -> `00-discover` |
+| "Brainstorm ideas without allocating ID" | `brainstorm` | `brainstorm` | `brainstorm` -> `00-discover` |
+| "Deep codebase or web research" | `research` | `research` | `research` |
+| "Investigate failure or root cause" | `debug` | `debug` | `debug` -> `40-implement` or `10-define` |
+| "Product framing & PRD creation" | `prd` | `prd` | `prd` -> `00-discover` |
+| "Intake and triage incoming bugs" | `issue-triage` | `issue-triage` | `issue-triage` -> `debug` or `10-define` |
+| "High-severity security audit" | `security-review` | `security-review` | `security-review` |
+| "Manage project knowledge base" | `wiki` | `wiki` | `wiki` |
+| "Verify or update DevFlow setup" | `check-for-updates` | `check-for-updates` | `check-for-updates` |
 
 ## Available Skills Sitemap
 
 Always provide a clean summary of available Nexus-DevFlow skills grouped by lifecycle stage:
 
 ### 1. Mainline Lifecycle Stages (Linear Order)
-- `/00-discover` - Explore request, route inquiries, go/no-go under Discovery ID
-- `/10-define` - Lock delivery boundaries and allocate Running ID (`devflow/runs/{ID}`)
-- `/20-spec` - Formalize markdown-first specifications and acceptance criteria
-- `/30-plan` - Transform spec into executable task breakdown
-- `/40-implement` - Execute planned tasks incrementally with evidence
-- `/50-verify` - Senior QA review, validation checks, and pass/fail gate
-- `/60-report` - Generate standardized markdown and HTML summary report
-- `/70-release` - Package verified work for PR merge or deployment
+- `00-discover` (`discover`, `/00-discover`, `$00-discover`) - Explore request, route inquiries, go/no-go under Discovery ID
+- `10-define` (`define`, `/10-define`, `$10-define`) - Lock delivery boundaries and allocate Running ID (`devflow/runs/{ID}`)
+- `20-spec` (`spec`, `/20-spec`, `$20-spec`) - Formalize markdown-first specifications and acceptance criteria
+- `30-plan` (`plan`, `/30-plan`, `$30-plan`) - Transform spec into executable task breakdown with test decisions
+- `40-implement` (`implement`, `/40-implement`, `$40-implement`) - Execute planned tasks incrementally with evidence
+- `50-verify` (`verify`, `/50-verify`, `$50-verify`) - Senior QA review, validation checks, and pass/fail gate
+- `60-report` (`report`, `/60-report`, `$60-report`) - Generate standardized markdown and HTML summary report
+- `70-release` (`release`, `/70-release`, `$70-release`) - Package verified work for PR merge or deployment
 
 ### 2. Public Companion Commands
-- `Goal` - Route broad goals before Discovery
-- `Brainstorm` - Ideate without allocating running IDs
-- `Research` - Conduct codebase or web research
-- `Debug` - Root cause investigation before or during implementation
-- `PRD` - Product framing before delivery commitment
-- `Issue-Triage` - Intake and triage incoming bug reports
-- `Security-Review` - High-severity security review
-- `Wiki` - Knowledge base management under `devflow/wiki/`
-- `Check-For-Updates` - Verify or upgrade DevFlow setup
-- `Help` - Process assistance and stage routing
+- `devflow` (`status`, `/devflow`, `$devflow`) - Guide, state inspector, and intent router
+- `onboard` (`/onboard`, `$onboard`) - Baseline stack setup for freshly scaffolded projects
+- `adopt` (`/adopt`, `$adopt`) - Survey and bootstrap DevFlow into existing brownfield projects
+- `doctor` (`/doctor`, `$doctor`) - Read-only health check for setup, scripts, and workflow drift
+- `goal` - Route broad goals before Discovery
+- `brainstorm` - Ideate without allocating running IDs
+- `research` - Conduct codebase or web research
+- `debug` - Root cause investigation before or during implementation
+- `prd` - Product framing before delivery commitment
+- `issue-triage` - Intake and triage incoming bug reports
+- `security-review` - High-severity security review
+- `wiki` - Knowledge base management under `devflow/wiki/`
+- `check-for-updates` - Verify or upgrade DevFlow setup
+- `help` - Process assistance and stage routing
 
 ### 3. Engineering & Specialist Skills
 - **Frontend & UI**: `frontend-ui-engineering`, `nextjs-react-expert`, `tailwind-patterns`, `ui-ux-pro-max`, `mobile-design`

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

@@ -0,0 +1,84 @@
+---
+name: doctor
+description: Read-only DevFlow health check and diagnostics. Inspects DevFlow setup, tool adapters, context files integrity, AGENTS.md commands validity, active runs in devflow/runs/, checklist completeness, and detects workflow drift. Use when the user runs doctor, /doctor, $doctor, asks to diagnose DevFlow, or wants to check project workflow health.
+---
+
+# doctor - Read-Only DevFlow Health Check & Diagnostics
+
+Where this sits in the workflow:
+
+```text
+Any time during development -> [doctor] -> Health Report & Actionable Fixes
+(read-only inspection)          (diagnostics)    (remediation recommendations)
+```
+
+`/doctor` is a safe, read-only diagnostic skill that verifies whether your repository's Nexus-DevFlow configuration, context files, tool adapters, commands, and active runs are healthy and aligned.
+
+---
+
+## Input
+
+No argument is required.
+
+---
+
+## Diagnostics Checklist
+
+Run through these 5 health checks:
+
+### Check 1: Core Framework & Context Files Integrity
+- Check if [AGENTS.md](AGENTS.md) and [CLAUDE.md](CLAUDE.md) exist and are populated.
+- Check required context files under `devflow/context/`:
+  - `project-overview.md` (Check if still empty/placeholder -> recommend `/onboard` or `/adopt`)
+  - `coding-standards.md` (Check if customized for stack)
+  - `ai-interaction.md` (Check if rules are configured)
+  - `current-stage.md` (Check if active run matches filesystem)
+  - `findings.md` (Check if ledger exists)
+
+### Check 2: Tool Adapters Parity
+- Check if `.agents/skills/` exists and contains core lifecycle skills (`00-discover` through `70-release`, `devflow`, `onboard`, `adopt`, `doctor`).
+- Check if `.claude/skills/` is in sync with `.agents/skills/`.
+
+### Check 3: Commands & Script Verification
+- Inspect the Commands section in `AGENTS.md`.
+- Cross-reference with project manifest (`package.json`, `pyproject.toml`, `Cargo.toml`, etc.):
+  - Does the `Dev` command exist in scripts?
+  - Does the `Build` command exist in scripts?
+  - Does the `Test` command exist in scripts?
+  - Does the `Verify` command exist in scripts?
+
+### Check 4: Active Runs & Workflow Drift Detection
+- Inspect `devflow/runs/`:
+  - Are there active runs?
+  - Is `current-stage.md` consistent with the latest stage artifact in the active run?
+  - Are checklists (`checklists/implementation-checklist.md`, `checklists/verification-checklist.md`) properly tracked?
+  - Detect stage skips or workflow drift (e.g. jumping from `10-define` directly to `40-implement` without `20-spec` and `30-plan`).
+
+### Check 5: Findings Ledger Inspection
+- Inspect `devflow/context/findings.md`:
+  - Are there open P0 or P1 findings that block release?
+  - Are resolved findings properly closed?
+
+---
+
+## Output Format
+
+Present a clean, scannable diagnostic report:
+
+```markdown
+# 🩺 Nexus-DevFlow Health Report
+
+## Overall Status: [HEALTHY | WARNING | ACTION REQUIRED]
+
+| Component | Status | Details |
+| :--- | :--- | :--- |
+| **Context Files** | [PASS / WARN] | project-overview.md, coding-standards.md status |
+| **Tool Adapters** | [PASS / WARN] | .agents and .claude parity |
+| **Configured Commands**| [PASS / WARN] | dev, build, test, verify alignment |
+| **Active Runs & Drift**| [PASS / WARN] | active run status, stage progression |
+| **Findings Ledger** | [PASS / WARN] | open P0/P1 issues count |
+
+### Recommended Remediation Actions:
+1. [Action item if any warning or failure detected]
+2. [Suggested next command, e.g. /devflow, /onboard, /adopt, etc.]
+```

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

@@ -0,0 +1,129 @@
+---
+name: onboard
+description: Set up Nexus-DevFlow after overlaying it onto a freshly scaffolded or early project. Detects the stack, tunes AGENTS.md commands and conventions, customizes coding-standards.md, checks .gitignore and tool adapters, initializes project-overview.md, and guides the user to /00-discover or /10-define. Use when the user runs onboard, /onboard, $onboard, just installed DevFlow into a new project, or asks what to do after installation. For an existing app with meaningful shipped features, use adopt instead.
+---
+
+# onboard - Finish the Nexus-DevFlow Setup for Fresh Projects
+
+Where this sits in the workflow:
+
+```text
+scaffold app  ->  overlay DevFlow  ->  [onboard]  ->  /00-discover or /10-define  ->  Mainline Loop
+(user/tool)       (create-nexus)       (tune setup)   (discovery / run scoping)      (20-spec -> 70-release)
+```
+
+`/onboard` is the fresh-project on-ramp for Nexus-DevFlow. It assumes the application was scaffolded first (e.g. via `create-next-app`, `create-vite`, `cargo new`, etc.) and DevFlow was overlaid after.
+
+Run `/onboard` before starting discovery or delivery runs. Its job is to make DevFlow fit the real project from day one: detecting commands, project name, coding conventions, ignore rules, and tool adapters.
+
+Use `/adopt` instead when the app already has substantial shipped code, working routes, and existing business logic.
+
+---
+
+## Input
+
+No argument is required. If the user provides context about the stack, database, authentication, or preferred tooling, use it as a hint and verify against files.
+
+---
+
+## Step 0 - Confirm Onboarding vs Adoption
+
+Inspect the repository and context files:
+
+- If the project is freshly scaffolded with minimal boilerplate, proceed.
+- If `devflow/context/project-overview.md` and `devflow/context/coding-standards.md` already contain rich, user-customized content, do not overwrite them without explicit confirmation.
+- If the repository already has substantial existing routes, controllers, or database models, stop and recommend `/adopt` instead.
+
+Never run a framework scaffolder. DevFlow is already overlaid.
+
+---
+
+## Step 1 - Survey the Project Facts
+
+Read only enough to identify the setup:
+
+- **Package Manager & Lockfile**: `pnpm-lock.yaml`, `package-lock.json`, `yarn.lock`, `bun.lockb`, `Cargo.lock`, `poetry.lock`, `go.sum`, etc.
+- **Manifest Scripts**: `package.json`, `pyproject.toml`, `go.mod`, `Cargo.toml`, etc.
+- **Framework & Configs**: `tsconfig.json`, `next.config.*`, `vite.config.*`, `astro.config.*`, `tailwind.config.*`, database configs, test configs.
+- **Source Layout**: `src/`, `app/`, `pages/`, `components/`, `lib/`, etc.
+- **Existing Git & Ignore Rules**: `.gitignore`, git branches.
+- **Project Name**: Extracted from manifest, root directory, or user.
+
+---
+
+## Step 2 - Update Entry Files (AGENTS.md & CLAUDE.md)
+
+1. **Update `AGENTS.md` Commands**:
+   - Fill in the actual commands found in the project:
+     - `Dev`: dev server command (e.g. `npm run dev`)
+     - `Build`: production build command (e.g. `npm run build`)
+     - `Test`: test runner command (e.g. `npm test`, `vitest`, `pytest`)
+     - `Lint / Typecheck`: linting and typechecking commands
+     - `Verify`: combined verification command if present (e.g. `npm run check` or `npm run typecheck && npm test && npm run build`)
+   - If no test command exists, state explicitly that testing is opt-in and not yet configured.
+
+2. **Update `CLAUDE.md`**:
+   - Replace any `# Project Name` placeholder with the real detected project name.
+   - Keep `@AGENTS.md` and `@devflow/context/...` imports intact.
+
+---
+
+## Step 3 - Tune Coding Standards
+
+Update `devflow/context/coding-standards.md` to match the detected stack:
+
+- Framework, rendering model, and component architecture
+- Package manager and runtime
+- Project directory conventions
+- Styling approach (Tailwind CSS, Vanilla CSS, CSS Modules)
+- Data fetching, state management, and API boundaries
+- Validation and error handling expectations
+- Testing expectations
+
+Keep core general rules (functional style, small focused functions, clear naming) and replace template placeholders with real patterns.
+
+---
+
+## Step 4 - Check AI Interaction Rules
+
+Review `devflow/context/ai-interaction.md` and adjust if needed:
+- Language preferences (`artifact_language: "th"` or `"en"`)
+- Branching conventions
+- Review checkpoint expectations
+
+---
+
+## Step 5 - Check Ignore Files, Visibility & Tool Adapters
+
+1. **Update `.gitignore`**: Ensure common build artifacts, dependencies, and environment files are ignored.
+2. **DevFlow Visibility**:
+   - By default, keep DevFlow files tracked in git for team collaboration.
+   - If local-only mode is requested, add `devflow/`, `.agents/`, `.claude/`, `CLAUDE.md` to `.gitignore` while keeping `AGENTS.md` public.
+3. **Tool Adapters**:
+   - Codex & Antigravity use `.agents/skills/`.
+   - Claude Code uses `.claude/skills/`.
+   - Both can coexist cleanly.
+
+---
+
+## Step 6 - Initialize Project Overview
+
+Populate `devflow/context/project-overview.md` with baseline information:
+- Project Name and One-line Summary
+- Tech Stack & Tooling Architecture
+- Initial Repository Structure
+- Available Verified Commands
+
+---
+
+## Step 7 - Handoff to Planning
+
+Present a concise onboarding summary report:
+
+- Stack, framework, and package manager detected
+- Commands configured in `AGENTS.md`
+- Files tuned during onboarding
+- Adapter status (`.agents/`, `.claude/`)
+- Recommended next step:
+  - Run `00-discover` (or `/00-discover`, `$00-discover`) to explore the first feature or product direction
+  - Run `10-define` (or `/10-define`, `$10-define`) if the initial delivery slice is already clear and ready for execution