@jakkrichm/create-nexus-devflow 2.0.12 → 2.0.14

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

@@ -0,0 +1,105 @@
+---
+name: spec
+description: "[Devflow] Fast-Track Spec stage in DevFlow (Blueprint Mode) - define, spec, plan, and create the single living spec.md contract."
+argument-hint: "{feature title, bug description, IDEA-xxx, or running-id}"
+---
+
+# Fast-Track: Spec (Blueprint Mode)
+
+$ARGUMENTS
+
+Fast-Track entry point combining Discovery, Definition, Specification, and Implementation Planning into one streamlined, review-gated step. Creates and maintains the **Single Living Spec (`spec.md`)** for the run. Supports intake from Idea Inbox (`IDEA-xxx`).
+
+## Invocations & Aliases
+
+- `/spec <title>` or `spec <title>`: Standard Fast-Track specification
+- `/spec IDEA-xxx`: Intake and promote a pending idea from `devflow/ideas.md`
+- `/feature <title>` or `feature <title>`: Fast-Track feature workflow
+- `/fix <bug-description>` or `fix <bug-description>`: Fast-Track ad-hoc bugfix workflow
+- `$spec`, `$feature`, `$fix`: Codex CLI invocation
+
+## Fast-Track Mainline Workflow
+
+```text
+/spec ──▶ /implement ──▶ /check ──▶ /complete
+```
+
+## Behavior & Contract
+
+When invoked:
+
+### 1. Work Identity & Idea Intake
+1. Inspect `devflow/context/current-stage.md` and `devflow/runs/`.
+2. **Idea Inbox Intake**: If the argument is an idea identifier (e.g. `IDEA-001`):
+   - Read `devflow/ideas.md` and extract the idea's title, raw problem statement, AI Feasibility notes, and Quick Seed points.
+   - Use these details as the primary input for Specification & Scope.
+   - In `devflow/ideas.md`, update the item's status to `[x] Claimed ({RUNNING_ID})` and move it under `## 📦 Archived / Shipped Ideas`.
+3. Determine or allocate the sequential Running ID (e.g. `RUN-016-{slug}`).
+4. Identify Git branch naming:
+   - For features: `feature/{slug}-{RUNNING_ID}`
+   - For bug fixes: `fix/{slug}-{RUNNING_ID}`
+5. Create directory `devflow/runs/{RUNNING_ID}/`.
+
+### 2. Generate the Single Living Spec (`spec.md`)
+Write `devflow/runs/{RUNNING_ID}/spec.md` using the structured template below in **Thai (`th`)**:
+
+```markdown
+# 📐 [{RUNNING_ID}] {Title} (Living Spec)
+
+> **Status**: In-Progress  
+> **Track**: Fast-Track (Blueprint Mode)  
+> **Branch**: `{branch_name}`  
+> **Created Date**: {YYYY-MM-DD}  
+> **Owner**: {Contributor or Team}  
+
+---
+
+## 1. Specification & Scope
+- **Problem Statement**: {ปัญหาหรือที่มาที่ต้องทำ}
+- **In-Scope**:
+  - {ขอบเขตสิ่งที่ต้องทำ}
+- **Out-of-Scope**:
+  - {สิ่งที่ไม่ทำในรอบนี้}
+- **Acceptance Criteria**:
+  - [ ] AC-1: {เงื่อนไขการตรวจรับข้อที่ 1}
+  - [ ] AC-2: {เงื่อนไขการตรวจรับข้อที่ 2}
+
+## 2. Plan & Test Strategy
+- **Files to Modify / Create**:
+  - `{path/to/file1}`: {หน้าที่ที่ต้องแก้ไข}
+  - `{path/to/file2}`: {หน้าที่ที่ต้องแก้ไข}
+- **Test Decision**: `Required (TDD)` | `Manual/Command Only` | `Not Required`
+  - *Rationale*: {เหตุผลความจำเป็นในการเขียนเทสต์}
+  - *Planned Cases*: {กรณีทดสอบหลักตาม AAA Pattern}
+- **Impact & Rollback Strategy**:
+  - *Impact*: {ผลกระทบต่อโมดูลอื่น}
+  - *Rollback*: {วิธีย้อนคืนการทำงานกรณีเกิดปัญหา}
+
+## 3. Implementation Checklist
+- [ ] Task 1.1: {งานย่อยข้อที่ 1}
+- [ ] Task 1.2: {งานย่อยข้อที่ 2}
+- [ ] Task 1.3: {งานย่อยข้อที่ 3}
+
+## 4. Implementation Record
+- *(จะถูกบันทึกเมื่อรัน /implement)*
+
+## 5. Verification Evidence
+- *(จะถูกบันทึกเมื่อรัน /check)*
+
+## 6. Release & Handoff
+- *(จะถูกบันทึกเมื่อรัน /complete)*
+```
+
+### 3. Update Workspace Status
+Update `devflow/context/current-stage.md`:
+- `Active Running ID`: `{RUNNING_ID}`
+- `Current Stage`: `spec (Fast-Track -> Ready for /implement)`
+- `Last Updated`: `{YYYY-MM-DD}`
+
+### 4. Output Summary & Next Step
+Report to the user:
+- Running ID and allocated branch
+- Summary of Scope and Acceptance Criteria
+- Living Spec path: `devflow/runs/{RUNNING_ID}/spec.md`
+- If promoted from `IDEA-xxx`, confirm status update in `devflow/ideas.md`
+- **Next Command**: `/implement` (or `/implement {RUNNING_ID}`)

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

@@ -1,82 +1,94 @@
 ---
 name: test
-description: "[Devflow] Test execution, missing test generation, and coverage analysis across unit, integration, and smoke test suites."
+description: "[Devflow] Test-driven development, test generation, test execution, and coverage analysis across unit, integration, and smoke test suites."
 ---
 
----
-description: Test Generation and Execution - Generates missing tests, runs existing test suites, or checks test coverage for the project.
----
-# ๐Ÿงช Test Generation and Execution
-
-## Usage: `/13-Test [target]`
+# Test-Driven Development, Generation & Execution
 
-Generates missing tests, runs existing test suites, or checks test coverage for the project.
+## Overview
 
-Primary behavior now lives in:
+This is the comprehensive testing master skill for Nexus-DevFlow. It drives development with tests (TDD), handles test generation, execution, coverage analysis, and bug reproduction. Tests are proof — "seems right" is not done.
 
 ```text
-.agents/skills/test-execution-and-coverage/SKILL.md
+    RED                GREEN              REFACTOR
+ Write a test    Write minimal code    Clean up the
+ that fails  ──→  to make it pass  ──→  implementation  ──→  (repeat)
+      │                  │                    │
+      ▼                  ▼                    ▼
+   Test FAILS        Test PASSES         Tests still PASS
 ```
 
-Treat this workflow file as a compatibility wrapper around that skill.
+## Usage & Sub-Commands
+
+- `/test`                - Run all project test suites
+- `/test [file/feature]` - Generate tests for a specific target
+- `/test coverage`       - Show test coverage report
+- `/test watch`          - Run tests in watch mode
 
 ---
 
-## ๐Ÿ› ๏ธ Sub-commands
+## 1. The TDD Cycle
+
+### Step 1: RED — Write a Failing Test
+Write the test first. It must fail. A test that passes immediately proves nothing.
+
+### Step 2: GREEN — Make It Pass
+Write the minimum code to make the test pass. Avoid premature over-engineering.
 
-- `/13-Test`                - Run all tests
-- `/13-Test [file/feature]` - Generate tests for a specific target
-- `/13-Test coverage`       - Show test coverage report
-- `/13-Test watch`          - Run tests in watch mode
+### Step 3: REFACTOR — Clean Up
+Improve code readability, naming, structure, and eliminate duplication while keeping tests green.
 
 ---
 
-## ๐Ÿšฆ Internal Process
+## 2. The Prove-It Pattern (Bug Reproduction)
 
-### Scenario A: Generate Tests
-If the user requests tests for a target:
-1. **Analyze**: Identify functions, edge cases, and external dependencies.
-2. **Template Verification**: **MANDATORY:** Before generating the test plan, inspect `.agent/resources/schemas/test_report.template.md`, preserve its required layout, and replace placeholder text with concrete coverage, command output, failures, and gaps.
-3. **Generate Cases**: Develop Happy path, Error cases, Edge cases.
-4. **Write**: Implement the tests using the project's testing framework (Pytest, Jest, Vitest, etc.). Follow the `Arrange-Act-Assert` pattern and mock external dependencies.
-5. **Save Test Report**: Save the test plan and results to `devflow/reports/{date}-test-report-{target}.md` (where `{date}` is today's date in `YYYY-MM-DD` format and `{target}` is a slugified version of the file or feature name).
+When fixing any defect, **do not attempt a fix without proving the bug exists first**:
 
-### Scenario B: Execute Tests
-Use the project's native command (e.g., `npm test`, `pytest`) to run the tests and format the output clearly for the user. Highlight any failed tests with expected vs received values. Save the execution summary report matching the template to `devflow/reports/{date}-test-report-run.md` (where `{date}` is today's date in `YYYY-MM-DD` format).
+```text
+Bug report arrives ➔ Write reproduction test (FAILS) ➔ Implement fix ➔ Test PASSES ➔ Guard regression
+```
 
 ---
 
-## ๐Ÿ›ก๏ธ Key Principles
-- **Test behavior, not implementation.**
-- **One assertion per test** (when practical).
-- **Descriptive test names.**
-- **Arrange-Act-Assert pattern.**
-- **Save Report**: Always save the test plan or results to disk for persistent logging.
+## 3. The Test Pyramid & Resource Sizes
 
-## ๐Ÿ“ Output Formats
+| Level | Size | Target % | Scope & Characteristics |
+| :--- | :--- | :--- | :--- |
+| **Unit** | Small | ~80% | Pure logic, in-memory, single process, milliseconds each |
+| **Integration** | Medium | ~15% | API boundaries, database interaction, component seams |
+| **E2E** | Large | ~5% | Critical user journeys, full workflows, browser automation |
 
-### For Test Generation
-Generate a summary indicating:
-- **Test Plan**: Table of Test Case, Type, Coverage (Happy path, error case, validation)
-- **Generated Tests**: File path and the code block
-- **Report Location**: Confirm the report has been written to the specified workspace path.
-- **Run command**: e.g. `npm test`
+---
 
-### For Test Execution
-Display an organized output listing Passed/Failed files, and explicitly show the expectation vs received outcome for failed assertions.
+## 4. Key Testing Principles & Best Practices
 
-## Relationship To DevFlow 2.0
+1. **Test behavior, not implementation details**: Assert on output and state changes, not private method call sequences.
+2. **DAMP over DRY in tests**: Descriptive and meaningful test setup beats overly abstract shared helpers.
+3. **Arrange-Act-Assert**: Distinct setup, action, and verification phases in every test case.
+4. **Prefer real implementations & fakes over heavy mocks**: Mock only at boundaries where real dependencies are slow or non-deterministic.
+5. **One assertion concept per test**: Isolate test failure reasons clearly.
 
-- Classification: Companion command
-- Mainline status: Verification support command, not a numbered stage
-- Typical entry points: `40-implement`, `50-verify`, `Debug`
-- Typical handoff targets: `50-verify`, `Debug`, `QA-Orchestrate`
+---
+
+## 5. Browser Testing & Runtime Verification
+
+For browser and UI features, unit tests alone are insufficient:
+- **Console**: Zero errors and unhandled exceptions in production code.
+- **Network**: Accurate status codes, payload shapes, and CORS handling.
+- **DOM & Styles**: Verified layout rendering, accessibility tree, and responsive behaviors.
+
+---
+
+## 6. Test Generation & Persistent Execution Reports
 
-## Sources
+When generating or logging test runs during `40-implement` or `50-verify`:
+- Save summary reports to `devflow/reports/{date}-test-report-{slug}.md`
+- Include: Target, Test Cases (Happy Path, Error, Edge Cases), Pass/Fail statistics, and gaps/risks.
 
-- `AGENTS.md`
-- `.agents/skills/test-execution-and-coverage/SKILL.md`
-- `.agent/resources/schemas/test_report.template.md`
-- Related commands: `40-implement`, `50-verify`, `Debug`, `QA-Orchestrate`
+---
 
+## Relationship To DevFlow 2.0
 
+- **Classification**: Companion command & Engineering standard
+- **Mainline stages**: `30-plan` (TDD decisions), `40-implement` (TDD execution), `50-verify` (QA gate)
+- **Handoff**: `50-verify`, `Debug`, `autopilot`

package/template/AGENTS.md

@@ -1,10 +1,14 @@
-# Nexus-DevFlow 2.0 (Blueprint-Style Model)
+# Nexus-DevFlow 2.0 (Dual-Track Blueprint & Architect Model)
 
 Instructions for AI coding agents working in this project. This is the cross-tool entry point: Codex, Google Antigravity, Cursor, GitHub Copilot, Gemini CLI, Aider, Zed, Windsurf, and others read `AGENTS.md`. Claude Code reads `CLAUDE.md`, which imports this file (`@AGENTS.md`), so there is a single source of truth.
 
 ## What this is
 
-This project uses **Nexus-DevFlow**, an agentic stage-based workflow layer. To start a new project, scaffold the application first in an empty folder, then run `npx @jakkrichm/create-nexus-devflow` to overlay DevFlow onto your codebase.
+This project uses **Nexus-DevFlow**, an agentic workflow layer supporting **Dual-Track Delivery**:
+1. **🏎️ Fast-Track (Blueprint Mode - 4 Steps)**: High-velocity spec-driven loop driven by a **Single Living Spec (`spec.md`)**.
+2. **🏗️ Deep-Track (Architect Mode - 8 Steps)**: Full-lifecycle delivery pipeline with modular stage artifacts (`00-70`).
+
+To start a new project, scaffold the application first in an empty folder, then run `npx @jakkrichm/create-nexus-devflow` to overlay DevFlow onto your codebase.
 
 ## Read these for full context
 
@@ -25,66 +29,70 @@ Unused adapter families can be removed. Codex and Antigravity projects keep `.ag
 
 ### Universal Invocation & Agent Directives:
 
-1. **Canonical Command Names & AI Provider Invocation**: Each workflow stage and companion tool has exactly **one Canonical Name** (e.g. `00-discover`, `10-define`, `20-spec`, `30-plan`, `40-implement`, `50-verify`, `60-report`, `70-release`, `devflow`, `onboard`, `adopt`, `doctor`, `try`, `rollback`, `ci`, `brief`, `autopilot`). 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., `00-discover`, `devflow`).
-   - **Slash Prefix (`/`)**: For tools supporting slash commands (Claude Code, Google Antigravity, Gemini CLI), e.g., `/00-discover`, `/devflow`.
-   - **Dollar Prefix (`$`)**: For OpenAI Codex CLI or skill-invocation tools, e.g., `$00-discover`, `$devflow`.
+1. **Canonical Command Names & AI Provider Invocation**: Each workflow stage and companion tool has exactly **one Canonical Name** (e.g. `spec`, `implement`, `check`, `complete`, `00-discover`, `10-define`, `20-spec`, `30-plan`, `40-implement`, `50-verify`, `60-report`, `70-release`, `report-html`, `devflow`, `onboard`, `adopt`, `doctor`, `try`, `rollback`, `ci`, `brief`, `autopilot`). 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., `spec`, `devflow`).
+   - **Slash Prefix (`/`)**: For tools supporting slash commands (Claude Code, Google Antigravity, Gemini CLI), e.g., `/spec`, `/feature`, `/fix`, `/devflow`.
+   - **Dollar Prefix (`$`)**: For OpenAI Codex CLI or skill-invocation tools, e.g., `$spec`, `$devflow`.
 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 `devflow/context/current-stage.md` and active runs in `devflow/runs/`.
-5. **Default Artifact & Communication Language (Thai)**: All generated markdown stage artifacts (`00-discover.md`, `10-define.md`, `20-spec.md`, `30-plan.md`, `40-implement.md`, `50-verify.md`, `60-report.md`, `70-release.md`) and user communication MUST default to **Thai (`th`)**, while code, technical terms, file paths, and identifiers remain in English.
+5. **Default Artifact & Communication Language (Thai)**: All generated markdown stage artifacts (`spec.md`, `00-discover.md`...`70-release.md`) and user communication MUST default to **Thai (`th`)**, while code, technical terms, file paths, and identifiers remain in English.
+
+---
+
+## 🏎️ Track 1: Fast-Track (Blueprint Mode - 4 Steps)
 
-## Timeline Workflow
+Recommended for 85% of daily work (features, bug fixes, UI improvements, iterative tasks):
 
 ```text
-00-discover -> 10-define -> 20-spec -> 30-plan -> 40-implement -> 50-verify -> 60-report -> 70-release
+/spec (or /feature, /fix) ──▶ /implement ──▶ /check ──▶ /complete
 ```
 
-### Mainline Stages:
+1. **`spec` (`/spec`, `/feature`, `/fix`)**:
+   - **Purpose**: Combines Discover, Define, Spec, and Plan into one unified step. Allocates sequential Running ID (`RUN-xxx`) and creates the **Single Living Spec (`spec.md`)**.
+   - **Artifact**: `devflow/runs/{running-id}-{slug}/spec.md`
+2. **`implement` (`/implement`)**:
+   - **Purpose**: Incrementally executes checklist tasks with TDD discipline and appends progress to `spec.md`.
+3. **`check` (`/check`)**:
+   - **Purpose**: Senior QA review, multi-lane verification matrix (Typecheck, Lint, Test suites, manual proof), and records evidence into `spec.md`.
+4. **`complete` (`/complete`)**:
+   - **Purpose**: Final safety pass, records Release Digest in `spec.md`, performs git merge, and closes the run without auto HTML generation.
 
-1. `00-discover`
-   - **Purpose**: Explore a request before delivery commitment without allocating a running ID.
-   - **Artifact**: `devflow/discoveries/{discovery-id}-{slug}/00-discover.md`
-   - **Gate**: Produces `Proceed`, `Defer`, or `Reject` decision.
+---
 
-2. `10-define`
-   - **Purpose**: Turn an approved discovery into one or more bounded delivery runs with stable scope and sequential Running IDs.
-   - **Artifact**: `devflow/runs/{running-id}-{slug}/10-define.md`
-   - **Gate**: Approved run map and explicit in-scope / out-of-scope boundaries.
+## 🏗️ Track 2: Deep-Track (Architect Mode - 8 Steps)
 
-3. `20-spec`
-   - **Purpose**: Formalize markdown-first delivery contract and testable acceptance criteria from a stable definition.
-   - **Artifact**: `devflow/runs/{running-id}-{slug}/20-spec.md`
-   - **Gate**: Unambiguous acceptance criteria and hard constraints.
+Recommended for large architectural epics, database migrations, and multi-agent coordination:
+
+```text
+00-discover ──▶ 10-define ──▶ 20-spec ──▶ 30-plan ──▶ 40-implement ──▶ 50-verify ──▶ 60-report ──▶ 70-release
+```
 
-4. `30-plan`
-   - **Purpose**: Transform `20-spec.md` into phased executable tasks with explicit test decisions (Required / Manual / Not Required).
-   - **Artifacts**: `30-plan.md`, `checklists/implementation-checklist.md`, `checklists/verification-checklist.md`
-   - **Gate**: Ordered dependencies, scoped subtasks, and TDD decisions.
+1. `00-discover`: Explore request before delivery commitment without allocating running ID (`00-discover.md`).
+2. `10-define`: Turn approved discovery into bounded delivery run(s) with sequential Running IDs (`10-define.md`).
+3. `20-spec`: Formalize markdown-first delivery contract & acceptance criteria (`20-spec.md`).
+4. `30-plan`: Breakdown spec into executable tasks with test decisions (`30-plan.md` + checklists).
+5. `40-implement`: Incremental task implementation behind review gates (`40-implement.md`).
+6. `50-verify`: Senior QA review & multi-lane verification checks (`50-verify.md`).
+7. `60-report`: Standardized markdown delivery digest (`60-report.md`).
+8. `70-release`: Release packaging, release notes, git merge, and deployment (`70-release.md`).
 
-5. `40-implement`
-   - **Purpose**: Execute planned tasks incrementally one scoped unit at a time behind review gates.
-   - **Artifact**: `40-implement.md` (and updated checklists)
-   - **Gate**: Code changes tested, verification recorded, deviations documented.
+---
 
-6. `50-verify`
-   - **Purpose**: Senior QA review and multi-lane validation check across functionality, regressions, and quality standards.
-   - **Artifact**: `50-verify.md` (optional `50-verify-impact.md`)
-   - **Gate**: Pass or return-to-implement decision with evidence.
+## 🌐 Standalone HTML Reporting Policy
 
-7. `60-report`
-   - **Purpose**: Produce the standardized final markdown and self-contained HTML summary report for the completed run.
-   - **Artifacts**: `60-report.md`, `60-report.html`
-   - **Gate**: Completed delivery digest ready for stakeholder review.
+> [!IMPORTANT]
+> **No Auto-Generated HTML**: Mainline flows (`/complete` and `60-report`) strictly output Markdown only.
+> When an interactive web dashboard is desired for presentation or sharing, invoke the standalone companion command:
+> `/report:html` (or `npm run report:html -- {RUNNING_ID}`).
 
-8. `70-release`
-   - **Purpose**: Package verified work for delivery, git merge, pull request, changelog update, or deployment.
-   - **Artifact**: `70-release.md`
-   - **Gate**: Safe handoff, release notes, and deployment readiness.
+---
 
-### Public Companion Commands:
+## Public Companion Commands
 
 - `devflow`: Flagship interactive guide, state inspector, and intent router.
+- `idea` (`/idea`): Quick idea capture and AI feasibility enrichment into `devflow/ideas.md`.
+- `report-html` (`/report:html`): Standalone interactive HTML report dashboard generator.
 - `onboard`: Initial stack detection and baseline setup for fresh/scaffolded projects.
 - `adopt`: Survey existing brownfield codebases and bootstrap DevFlow context.
 - `doctor`: Read-only health check for context files, adapters, commands, and workflow drift.
@@ -92,49 +100,38 @@ Unused adapter families can be removed. Codex and Antigravity projects keep `.ag
 - `rollback`: Safe feature/run reversal planner with dependency and commit risk analysis.
 - `ci`: Automatic GitHub Actions workflow (`.github/workflows/verify.yml`) setup and alignment.
 - `brief`: Read-only scope, dependency, and size pre-briefing before speccing a run.
-- `autopilot`: Optional explicit mode for one bounded spec/plan/implement/verify/report pass with checkpoint commits and review packet.
+- `autopilot`: Optional explicit mode for one bounded spec/plan/implement/verify/report pass.
 - `goal`: Route broad, open-ended goals before Discovery.
 - `brainstorm`: Structured divergent & convergent ideation without creating running IDs.
 - `research`: Conduct deep codebase or web research with source-backed citations.
 - `debug`: Root cause investigation before or during implementation without editing code.
-- `prd`: Product Requirements Document drafting before delivery commitment.
-- `issue-triage`: Intake, categorize, and prioritize incoming issues and bug reports.
-- `security-review`: High-severity vulnerability and security review.
-- `wiki`: Knowledge base management and ingestion under `devflow/wiki/`.
+- `overview`: Refresh `devflow/context/project-overview.md`.
+- `wiki`: Knowledge base management under `devflow/wiki/`.
 - `check-for-updates`: Verify or upgrade DevFlow setup.
 - `help`: Routing and process assistance across DevFlow workflows.
 
-## Invocation Reference
+---
 
-> **Note on AI Providers**: Commands use a single Canonical Name. Use the prefix appropriate for your tool (`/` for Claude/Antigravity, `$` for Codex, or plain text).
+## Invocation Reference
 
-| Stage / Category | Canonical Name | Claude / Antigravity (`/`) | OpenAI Codex (`$`) | Purpose / Action |
+| Track / Category | Canonical Name | Claude / Antigravity (`/`) | OpenAI Codex (`$`) | Purpose / Action |
 | :--- | :--- | :--- | :--- | :--- |
-| **Setup (Fresh)** | `onboard` | `/onboard` | `$onboard` | Detect tech stack and establish initial project baseline |
-| **Adopt (Exist)** | `adopt` | `/adopt` | `$adopt` | Adopt existing brownfield codebase into DevFlow |
-| **Diagnostics** | `doctor` | `/doctor` | `$doctor` | Read-only health check for configs, tools, and drift |
-| **Manual QA** | `try` | `/try` | `$try` | Step-by-step manual testing guide for human verification |
-| **Reversal** | `rollback` | `/rollback` | `$rollback` | Reversal planner with dependency & commit risk analysis |
-| **CI Setup** | `ci` | `/ci` | `$ci` | Generate GitHub Actions automated verify workflow |
-| **Pre-Check** | `brief` | `/brief` | `$brief` | Read-only scope, dependency, and size pre-briefing |
-| **Autopilot** | `autopilot` | `/autopilot` | `$autopilot` | Bounded autonomous spec/plan/implement/verify pass |
-| **Stage 00** | `00-discover` | `/00-discover` | `$00-discover` | Explore request and decide Proceed, Defer, or Reject |
-| **Stage 10** | `10-define` | `/10-define` | `$10-define` | Turn approved discovery into bounded delivery run(s) |
-| **Stage 20** | `20-spec` | `/20-spec` | `$20-spec` | Formal markdown delivery contract & acceptance criteria |
-| **Stage 30** | `30-plan` | `/30-plan` | `$30-plan` | Breakdown spec into executable tasks with test decisions |
-| **Stage 40** | `40-implement` | `/40-implement` | `$40-implement` | Implement tasks in small reviewable increments |
-| **Stage 50** | `50-verify` | `/50-verify` | `$50-verify` | Senior QA review & multi-lane verification checks |
-| **Stage 60** | `60-report` | `/60-report` | `$60-report` | Standalone markdown & HTML summary report |
-| **Stage 70** | `70-release` | `/70-release` | `$70-release` | Package for delivery, git merge, PR, or deployment |
+| **Fast: Spec** | `spec` | `/spec` / `/feature` / `/fix` | `$spec` / `$feature` / `$fix` | 4-step Fast-Track spec & living spec creation (supports `IDEA-xxx`) |
+| **Fast: Implement** | `implement` | `/implement` | `$implement` | Fast-Track incremental execution with TDD |
+| **Fast: Check** | `check` | `/check` | `$check` | Fast-Track QA review & multi-lane verification |
+| **Fast: Complete** | `complete` | `/complete` | `$complete` | Fast-Track safety pass, release digest & git merge |
+| **Idea Capture** | `idea` | `/idea` | `$idea` | Quick idea capture and AI feasibility enrichment |
+| **HTML Report** | `report-html` | `/report:html` | `$report:html` | Standalone interactive HTML dashboard generator |
+| **Deep: 00** | `00-discover` | `/00-discover` | `$00-discover` | Explore request and decide Proceed, Defer, or Reject |
+| **Deep: 10** | `10-define` | `/10-define` | `$10-define` | Turn approved discovery into bounded delivery run(s) |
+| **Deep: 20** | `20-spec` | `/20-spec` | `$20-spec` | Formal markdown delivery contract & acceptance criteria |
+| **Deep: 30** | `30-plan` | `/30-plan` | `$30-plan` | Breakdown spec into executable tasks with test decisions |
+| **Deep: 40** | `40-implement` | `/40-implement` | `$40-implement` | Implement tasks in small reviewable increments |
+| **Deep: 50** | `50-verify` | `/50-verify` | `$50-verify` | Senior QA review & multi-lane verification checks |
+| **Deep: 60** | `60-report` | `/60-report` | `$60-report` | Standalone markdown summary report |
+| **Deep: 70** | `70-release` | `/70-release` | `$70-release` | Package for delivery, git merge, PR, or deployment |
 | **Router** | `devflow` | `/devflow` | `$devflow` | Interactive guide, state inspector, and intent router |
 
-## Mainline Rules
-
-1. Numbered workflows exist only for the linear mainline.
-2. Mainline numbers must move from lower to higher with no backward jump.
-3. If a command is not a true mainline state, do not give it a number.
-4. Companion commands may be suggested by a mainline workflow but do not replace that workflow.
-
 ## Commands
 
 - Dev Server: `npm run dev`

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

@@ -32,3 +32,4 @@
 - 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.
+- Use **Fast-Track / Quick-Fix mode** for minor hotfixes to skip heavy ceremony while keeping test evidence.

package/template/devflow/context/coding-standards.md

@@ -1,27 +1,40 @@
-# Coding Standards
+# Coding Standards & Guidelines
 
-> Project conventions and rules to follow during development.
-> Run `/onboard` (or `/adopt` for existing codebases) to tune these standards to your specific stack.
+General engineering standards for code, tests, and documentation in Nexus-DevFlow.
 
-## Architecture and Conventions
+## 1. Code Quality & Architecture
 
-- Write clean, modular, and maintainable code with clear single responsibilities.
-- Prefer TypeScript and explicit interfaces where available.
-- Keep dependencies lean and justified.
+- Write clear, self-documenting code with single-responsibility functions.
+- Avoid unnecessary complexity (prefer simple solutions over indirect abstractions).
+- Maintain type safety and static validation across module boundaries.
+- Treat `project-overview.md` as the single source of truth for concrete data models and entity definitions.
 
-## Code Organization & Style
+## 2. Testing & Empirical Proof Standards
 
-- 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).
+- **Unit Test Mandate**: Any logic modification or bug fix must be accompanied by new or updated unit tests.
+- **Empirical Proof Contract**: Never claim "passed", "verified", or "working" without citing exact command outputs, test run reports, route responses, logs, or screenshots.
+- **Manual Try Guide**: Every delivery run must provide a human-testable Try Guide ("Where to go", "What to click", "What to expect") for manual validation.
 
-## Error Handling & Security
+## 3. Findings Ledger & Quality Gates (`findings.md`)
 
-- Handle errors explicitly and provide meaningful error messages.
-- Never hardcode credentials, secrets, or API keys in source code.
-- Sanitize and validate all user inputs.
+- All audit, security, and verification issues must be tracked in `devflow/context/findings.md`.
+- **Finding State Machine**:
+  - `open`: Confirmed defect not yet repaired.
+  - `fixed`: Repaired in code, pending verification.
+  - `closed`: Verified in `50-verify` as completely resolved without regressions.
+  - `accepted`: Waived with recorded user rationale.
+  - `invalid`: Proven non-issue with concrete evidence.
+- **P0/P1 Blockers**: P0 and P1 findings in `open` or `fixed` status block `70-release` unconditionally. `fixed` status must be promoted to `closed` via `50-verify` re-examination.
 
-## Testing & Quality
+## 4. Git Workflow & Release Safety
+ 
+- Commit messages follow conventional/imperative format (e.g., `feat(RUN-007): ...`).
+- Feature branches follow `feature/{slug}-{running-id}` or `fix/{slug}-{running-id}`.
+- **2-Stage Release Approvals**: Explicit consent to merge into `main` is strictly separate from consent to `git push` to remote repositories or deploy to production.
 
-- Follow the TDD workflow for behavior-changing code units.
-- Run tests and linting before completing features or fixes.
+## 5. Fast-Track & Quick-Fix Guidelines (Lean Mode)
+
+- For trivial bug fixes, typo corrections, or single-file non-architectural changes, developers and agents may use the **Quick-Fix Fast-Track**:
+  - Consolidate Discovery, Define, and Spec into an inline fix brief (`devflow/runs/{fix-id}/fix-brief.md`).
+  - Jump directly to `40-implement` (with reproduction unit test) ➔ `50-verify` ➔ `70-release`.
+  - Avoid creating heavy redundant documentation for changes under 20 lines of code while preserving Empirical Proof and Unit Test requirements.

package/template/devflow/context/current-stage.md

@@ -2,6 +2,6 @@
 
 - **Active Discovery ID**: None
 - **Active Running ID**: None
-- **Current Stage**: Idle
-- **Last Completed Run**: None
-- **Last Updated**: -
+- **Current Stage**: Ready for new work (Fast-Track: `/spec`, `/feature`, `/fix`, or Deep-Track: `00-discover`, Idea: `/idea`)
+- **Last Completed Run**: RUN-016-idea-capture-inbox-and-status-integration (2026-08-20)
+- **Last Updated**: 2026-08-20

package/template/devflow/context/findings.md

@@ -1,9 +1,13 @@
-# Findings Ledger
+# Audit Findings Ledger
 
-> Review findings raised by `/security-review` or QA audits.
-> Resolved findings are tracked with durable IDs.
+Summary of audit findings, quality checks, security bugs, and debt tracked across DevFlow runs.
 
-- **Total Open P0/P1**: 0
-- **Total Tracked**: 0
+## Open Findings
 
-_No findings recorded._
+| ID | Severity | Category | Title | Discovered Run | Status |
+| :- | :--- | :--- | :--- | :--- | :--- |
+
+## Resolved Findings
+
+| ID | Severity | Category | Title | Resolved Run | Date |
+| :- | :--- | :--- | :--- | :--- | :--- |

package/template/devflow/context/project-overview.md

@@ -1,19 +1,37 @@
 # 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.
+Primary source of truth for the project context, architecture, tech stack, and active DevFlow stage status.
 
-## 1. Project Summary
+## Application Summary
 
-- **Name**: [Project Name]
-- **Description**: [One-line summary of project purpose]
-- **Primary Stack**: [Framework / Language / Runtime]
+- **Project Name**: Nexus-DevFlow
+- **Goal**: Agent-ready DevFlow 2.0 workflow layer framework with .agents and .claude adapter tooling, living context synchronization, and automated AI Blueprint upstream monitoring.
+- **Target Audience**: AI coding assistants (Google Antigravity, OpenAI Codex, Claude Code, Cursor) and software development teams building resilient agentic delivery workflows.
 
-## 2. Architecture & Modules
+## Tech Stack
 
-- `src/` - Core application source code
+- **Core & Runtime**: Node.js (>=18.17 / Node 22), TypeScript 5.7, Node Next ESM (`"type": "module"`)
+- **Execution & Tooling**: `tsx` (TypeScript execute/test runner), `tsc` (Typecheck & compilation)
+- **Installer Package**: `@jakkrichm/create-nexus-devflow` (with `dist/` compilation pipeline)
+- **Documentation**: VitePress / Astro website under `website/` (GitHub Pages)
+- **Upstream Integration**: Automated GitHub Actions monitor (`.github/workflows/check-upstream.yml`) tracking `aiblueprinthq/ai-blueprint`
+- **Verification Gate**: `npm run check` (TypeScript typechecking, static contract validation, TF-IDF skill routing evaluations, installer unit tests, packed smoke tests)
 
-## 3. Shipped Capabilities
+## Architecture & Key Modules
 
-- None recorded yet. Run `/onboard` or `/adopt` to initialize.
+- **`packages/create-nexus-devflow/`**: Distribution CLI package with TypeScript compilation (`dist/bin/create-nexus-devflow.js`), atomic update engine (`lib/update.ts`), and prepack template bundler (`scripts/prepare-template.ts`).
+- **`.agents/skills/` & `.claude/skills/`**: 72 synchronized AI agent skills covering Mainline stages (00-70) and companion tools (`devflow`, `try`, `doctor`, `overview`, `sync-upstream`, `ci`, `rollback`).
+- **`scripts/`**: Maintainer infrastructure (`check-devflow.ts`, `validate-framework.ts`, `smoke-package.ts`, `upstream-monitor.ts`, `evals/routing.ts`).
+- **`devflow/`**: Workspace state, discoveries, runs, context, reference contracts, and master release history ledger.
+
+## Shipped Capabilities (Recent Milestones)
+
+- **`RUN-014` (2026-08-20)**: Upgraded DevFlow to full TypeScript architecture (`tsconfig.json`, `tsx`, `tsc`, `dist/`), migrated AI Blueprint Upstream Monitor workflow to DevFlow, and established multi-lane verification matrix.
+- **`RUN-013` (2026-08-20)**: Added `/overview` skill for living context scanning and synchronization.
+- **`RUN-008` (2026-08-18)**: Lean & Clean DevFlow optimization, consolidated skill taxonomy, and safe rollback mechanisms.
+
+## DevFlow Workspace Status
+
+- **Active Discovery ID**: None (Idle)
+- **Active Running ID**: None (Idle)
+- **Last Completed Run**: `RUN-014-typescript-migration-and-upstream-monitor-for-devflow`