@jakkrichm/create-nexus-devflow 2.0.12 → 2.0.14

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

@@ -5,104 +5,113 @@ description: "[Devflow] Flagship interactive guide, state inspector, and intent
 
 # devflow - Interactive Workflow Guide & Intent Router for Nexus-DevFlow
 
-Use this skill to guide the user on what to do next, inspect current workspace state, map their natural language intent to the right Nexus-DevFlow stage or companion command, or display a sitemap of available DevFlow skills.
+Use this skill to guide the user on what to do next, inspect current workspace state, map their natural language intent to the right Nexus-DevFlow track (Fast-Track or Deep-Track) or companion command, or display a sitemap of available DevFlow skills.
 
 ## Input
 
-- **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.
+- **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/`, pending ideas in `devflow/ideas.md`, 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 workflow track or companion command path.
+
+## Dual-Track Architecture
+
+Nexus-DevFlow supports two seamless workflow tracks:
+1. **🏎️ Fast-Track (Blueprint Mode - 4 Steps)**: `/spec` ➔ `/implement` ➔ `/check` ➔ `/complete`  
+   *Driven by a **Single Living Spec (`spec.md`)** for fast, high-velocity daily development and bugfixes (85% of tasks).*
+2. **🏗️ Deep-Track (Architect Mode - 8 Steps)**: `00-discover` ➔ `10-define` ➔ `20-spec` ➔ `30-plan` ➔ `40-implement` ➔ `50-verify` ➔ `60-report` ➔ `70-release`  
+   *Driven by modular separate stage files for large, high-stakes architectural epics and multi-agent coordination.*
+
+---
 
 ## Workspace State Inspection
 
 When invoked without an argument (or when determining the next step), inspect:
 
-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`).
+1. **Project Setup Baseline**: Read `devflow/context/project-overview.md` and `devflow/context/coding-standards.md`. If 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}/`.
+   - **If Fast-Track (`spec.md` or `blueprint.md` present)**:
+     - If `spec.md` has incomplete checklist items -> Recommend `/implement` (or `implement {RUNNING_ID}`).
+     - If all tasks done but no passing verification evidence -> Recommend `/check` (or `check {RUNNING_ID}`).
+     - If verification evidence passed -> Recommend `/complete` (or `complete {RUNNING_ID}`).
+   - **If Deep-Track (numbered stage files present)**:
+     - If at `10-define.md` -> Recommend `20-spec {RUNNING_ID}`.
+     - If at `20-spec.md` -> Recommend `30-plan {RUNNING_ID}`.
+     - If at `30-plan.md` -> Recommend `40-implement {RUNNING_ID}`.
+     - If at `40-implement.md` with all tasks done -> Recommend `50-verify {RUNNING_ID}`.
+     - If passed `50-verify.md` -> Recommend `60-report {RUNNING_ID}` then `70-release {RUNNING_ID}`.
 3. **Active Discovery**: Check `devflow/discoveries/` for open discovery notes.
-4. **Audit Findings Ledger**: Check `devflow/context/findings.md` for open high-severity findings.
+4. **Pending Ideas Inbox**: Check `devflow/ideas.md`. If items exist under `## 📌 Pending Ideas`, summarize them in a **💡 Pending Ideas (Inbox)** list with their IDs (`[IDEA-xxx]`), feasibility, and mention that they can be started with `/spec IDEA-xxx`.
+5. **Audit Findings Ledger**: Check `devflow/context/findings.md` for open high-severity findings.
 
-### State-Based Recommendation Rules
+### Default State Recommendations
+- If no run is active and user wants to start a feature -> Recommend `/spec <name>` (or `/feature <name>`).
+- If no run is active and user wants to fix a bug -> Recommend `/fix <bug>`.
+- If no run is active and user has pending ideas in `devflow/ideas.md` -> Highlight `/spec IDEA-xxx`.
+- If no run is active and user wants deep architectural exploration -> Recommend `00-discover`.
+- If user asks to check system health -> Recommend `doctor`.
 
-- 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 | Normal Name / Alias | Lifecycle Path |
+| User Intent / Request Type | Recommended Skill | Normal Name / Alias | Track / 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` |
+| **"Spec new feature / lean workflow"** | `spec` | `/spec` / `/feature` | **Fast-Track**: `/spec` -> `/implement` -> `/check` -> `/complete` |
+| **"Quick bugfix / ad-hoc change"** | `spec` | `/fix` | **Fast-Track**: `/fix` -> `/implement` -> `/check` -> `/complete` |
+| **"Capture quick idea / thought"** | `idea` | `/idea` | **Companion**: Enriches & saves to `devflow/ideas.md` |
+| **"Execute implementation tasks"** | `implement` | `/implement` | **Fast-Track**: `/implement` -> `/check` |
+| **"Run QA verification & check"** | `check` | `/check` | **Fast-Track**: `/check` -> `/complete` |
+| **"Complete run & git merge"** | `complete` | `/complete` | **Fast-Track**: `/complete` |
+| **"Generate HTML dashboard report"**| `report-html` | `/report:html` | **Standalone**: Converts `spec.md` / `60-report.md` to HTML |
+| "Setup DevFlow on fresh/new project" | `onboard` | `onboard` / `setup` | `onboard` -> `/spec` or `10-define` |
+| "Adopt DevFlow on existing codebase" | `adopt` | `adopt` / `bootstrap` | `adopt` -> `/spec` 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` |
-| "Human manual QA walkthrough guide" | `try` | `try` | `try` (after implement or verify) |
-| "Safely plan feature or run reversal" | `rollback` | `rollback` | `rollback` -> `40-implement` |
-| "Set up automatic GitHub Actions CI" | `ci` | `ci` | `ci` (after onboard or adopt) |
-| "Pre-check scope & risks before spec" | `brief` | `brief` | `brief` -> `20-spec` |
-| "Run autonomous bounded delivery loop"| `autopilot` | `autopilot` | `autopilot` -> `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` |
+| "Explore a new request / deep idea" | `00-discover` | `discover` | **Deep-Track**: `00` -> `10` -> `20` -> ... |
+| "Define delivery boundaries and ID" | `10-define` | `define` | **Deep-Track**: `10` -> `20` -> `30` |
+| "Break down spec into plan (Deep)" | `30-plan` | `plan` | **Deep-Track**: `30` -> `40` -> `50` |
+| "Deep code implementation" | `40-implement` | `implement` | **Deep-Track**: `40` -> `50` |
+| "Deep QA verification" | `50-verify` | `verify` | **Deep-Track**: `50` -> `60` -> `70` |
+| "Deep markdown digest report" | `60-report` | `report` | **Deep-Track**: `60` -> `70` |
+| "Deep release packaging & merge" | `70-release` | `release` | **Deep-Track**: `70-release` |
+| "Human manual QA walkthrough guide" | `try` | `try` | Companion (after implement or check) |
+| "Safely plan feature or run reversal" | `rollback` | `rollback` | Companion |
+| "Set up automatic GitHub Actions CI" | `ci` | `ci` | Companion |
+| "Pre-check scope & risks before spec" | `brief` | `brief` | Companion |
+| "Run autonomous bounded delivery loop"| `autopilot` | `autopilot` | Companion |
+| "Brainstorm ideas without ID" | `brainstorm` | `brainstorm` | Companion |
+| "Investigate failure or root cause" | `debug` | `debug` | Companion |
+
+---
 
 ## 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` (`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
-- `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
-- `try` (`try`, `$try`) - Step-by-step human manual QA review guide (where to go, what to click, what to expect)
-- `rollback` (`rollback`, `$rollback`) - Safe feature/run reversal planner with dependency risk analysis
-- `ci` (`ci`, `$ci`) - Automatic GitHub Actions workflow (`.github/workflows/verify.yml`) setup
-- `brief` (`brief`, `$brief`) - Read-only scope, dependency, and size pre-briefing before speccing
-- `autopilot` (`autopilot`, `$autopilot`) - Optional bounded autonomous loop (spec -> plan -> implement -> verify -> report)
-- `goal` - Route broad goals before Discovery
+### 1. Fast-Track (Blueprint Mode - 4 Steps)
+- `spec` (`/spec`, `/feature`, `/fix`, `$spec`) - Define, spec, plan, and create `spec.md`
+- `implement` (`/implement`, `$implement`) - Execute planned checklist tasks with TDD
+- `check` (`/check`, `$check`) - Senior QA review, multi-lane verification, record evidence
+- `complete` (`/complete`, `$complete`) - Safety pass, release digest, git merge, close run
+
+### 2. Deep-Track (Architect Mode - 8 Steps)
+- `00-discover` - Explore request and decide Proceed/Defer/Reject
+- `10-define` - Lock delivery boundaries and allocate Running ID
+- `20-spec` - Formalize markdown delivery contract
+- `30-plan` - Breakdown spec into phased tasks with test decisions
+- `40-implement` - Incremental task implementation
+- `50-verify` - Senior QA review and multi-lane validation
+- `60-report` - Generate standardized markdown digest report
+- `70-release` - Release packaging, release notes, and merge
+
+### 3. Public Companion Commands
+- `devflow` (`status`, `/devflow`) - Interactive guide, state inspector, and 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` - Baseline stack setup for freshly scaffolded projects
+- `adopt` - Bootstrap DevFlow into existing brownfield projects
+- `doctor` - Read-only health check for setup and drift
+- `try` - Step-by-step human manual QA review guide
+- `rollback` - Safe feature/run reversal planner
+- `ci` - Automatic GitHub Actions workflow setup
+- `brief` - Read-only scope and risk pre-briefing
+- `autopilot` - Autonomous bounded delivery loop
 - `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`
-- **Quality & Security**: `code-review-and-quality`, `security-and-hardening`, `test-driven-development`, `vulnerability-scanner`, `performance-optimization`
-- **Architecture & System**: `architecture`, `database-design`, `domain-modeling`, `codebase-design`, `api-and-interface-design`
-- **Tools & Productivity**: `md2html`, `obsidian-markdown`, `git-workflow-and-versioning`, `parallel-agents`, `context-engineering`
+- `overview` - Living context synchronization into project-overview.md

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

@@ -0,0 +1,57 @@
+---
+name: idea
+description: "[Devflow] Quick idea capture and AI enrichment - analyze feasibility, value, key points, and record into devflow/ideas.md inbox."
+argument-hint: "\"<idea text or description>\""
+---
+
+# idea - Quick Idea Capture & AI Enrichment
+
+$ARGUMENTS
+
+Use this skill to quickly capture feature ideas, improvements, or architectural thoughts before they are forgotten. The AI immediately enriches the idea with **Feasibility Assessment**, **Value & Impact Analysis**, and **Quick Seed Key Points** (to prevent forgetting the nuance), then stores it in the central idea inbox at `devflow/ideas.md`.
+
+## Invocations & Aliases
+
+- `/idea "<idea text>"`: Standard slash command in Claude Code / Antigravity
+- `idea "<idea text>"`: Plain text invocation
+- `$idea "<idea text>"`: Codex CLI invocation
+
+## Behavior & Contract
+
+When invoked:
+
+### 1. Load Idea Inbox Hub
+1. Check if `devflow/ideas.md` exists. If not, create it with the standard DevFlow Ideas template.
+2. Read `devflow/ideas.md` and find the highest existing `IDEA-xxx` number.
+3. Allocate the next sequential ID (e.g. `IDEA-001`, `IDEA-002`).
+
+### 2. AI Feasibility & Value Analysis
+Evaluate the user's raw idea and generate an enriched summary in **Thai (`th`)**:
+- **ไอเดียตั้งต้น (Raw Idea)**: ข้อความที่ผู้ใช้ระบุ
+- **AI Feasibility & Tech**: ประเมินความเป็นไปได้ (ง่าย / ปานกลาง / ซับซ้อน) พร้อมแนะนำ Library, API, หรือแนวทางเทคนิคเบื้องต้น
+- **Value & Potential**: คุณค่า ประโยชน์ และความน่าสนใจของฟีเจอร์นี้
+- **Quick Seed (สรุปประเด็นกันลืม)**: 2-3 ประเด็นทางเทคนิคหรือแนวทางการต่อยอด เพื่อให้กลับมาอ่านทีหลังแล้วจำบริบทได้ทันที
+
+### 3. Append to `devflow/ideas.md`
+Insert the new idea block directly under `## 📌 Pending Ideas` in `devflow/ideas.md`:
+
+```markdown
+### [IDEA-001] {หัวข้อไอเดียสั้นๆ}
+- **บันทึกเมื่อ**: {YYYY-MM-DD}
+- **ไอเดียตั้งต้น**: {ข้อความที่ผู้ใช้ป้อน}
+- **AI Feasibility & Tech**: {บทวิเคราะห์ความเป็นไปได้และเครื่องมือ}
+- **Value & Potential**: {บทวิเคราะห์คุณค่าและความน่าสนใจ}
+- **Quick Seed (กันลืม)**:
+  1. {ประเด็นสำคัญที่ 1}
+  2. {ประเด็นสำคัญที่ 2}
+- **สถานะ**: `Pending` (หยิบไปทำได้ด้วย `/spec IDEA-001` หรือ `/00-discover IDEA-001`)
+```
+
+*(หากมีข้อความ `*(ยังไม่มีไอเดียค้างอยู่...)*` ให้ลบออกเมื่อมีไอเดียแรก)*
+
+### 4. Output Summary
+Report to the user:
+- Allocated Idea ID: `[IDEA-xxx]`
+- Summary of Feasibility & Value analysis
+- Seed points saved
+- Instructions for promotion: "เมื่อพร้อมลงมือทำ สามารถพิมพ์ `/spec IDEA-xxx` หรือ `/00-discover IDEA-xxx` ได้ทันที"

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

@@ -0,0 +1,64 @@
+---
+name: implement
+description: "[Devflow] Fast-Track Implement stage in DevFlow (Blueprint Mode) - execute checklist tasks incrementally with TDD and update spec.md."
+argument-hint: "{running-id or workspace path}"
+---
+
+# Fast-Track: Implement (Blueprint Mode)
+
+$ARGUMENTS
+
+Incremental code execution stage in Fast-Track. Reads the Single Living Spec (`spec.md`), executes checklist tasks, implements tests (TDD), and updates the implementation record.
+
+## Invocations & Aliases
+
+- `/implement`: Run implementation on current active run
+- `/implement {running-id}`: Run implementation on specified running ID
+- `$implement`: Codex CLI invocation
+
+## Fast-Track Mainline Workflow
+
+```text
+/spec ──▶ /implement ──▶ /check ──▶ /complete
+```
+
+## Behavior & Contract
+
+When invoked:
+
+### 1. Load Active Context
+1. Identify active Running ID from `devflow/context/current-stage.md` or argument.
+2. Read `devflow/runs/{RUNNING_ID}/spec.md`.
+3. Locate `## 2. Plan & Test Strategy` and `## 3. Implementation Checklist`.
+
+### 2. Incremental Execution with TDD
+1. Select unchecked items `- [ ]` from the checklist in order.
+2. For each task:
+   - **TDD (Red-Green-Refactor)**: When `Test Decision: Required`, create or update unit tests first.
+   - Implement the minimal, clean code change satisfying the task.
+   - Run localized verification (e.g. `npm test`, linter).
+   - Mark the item as `- [x]` in `spec.md`.
+
+### 3. Update Living Spec (`spec.md`)
+Append or update `## 4. Implementation Record` in `spec.md` with:
+- Summary of completed tasks and modified files
+- Key architectural observations or notes
+- Status of checklist items
+
+Example:
+```markdown
+## 4. Implementation Record
+- **[Task 1.1]**: Implemented JWT auth middleware in `src/middleware/auth.ts`
+- **[Task 1.2]**: Added unit tests in `test/auth.test.ts` (All 6 tests passing)
+- **[Task 1.3]**: Registered auth route in `src/server.ts`
+```
+
+### 4. Update Workspace Status
+Update `devflow/context/current-stage.md`:
+- `Current Stage`: `implement (Fast-Track -> Checklist Completed -> Ready for /check)`
+
+### 5. Output Summary & Next Step
+Report to the user:
+- Completed checklist items and modified files
+- Local verification results
+- **Next Command**: `/check` (or `/check {RUNNING_ID}`)

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

@@ -1,131 +1,42 @@
----name: insight
-
-description: "[Devflow] Extract reusable lessons, patterns, file insights, and post-mortem learning from completed work."
+---
+name: insight
+description: "[Devflow] Extract reusable lessons, architectural patterns, post-mortem incident learning, and token optimizations from completed work."
 ---
 
-# Phase 54: Insight Extraction
-
-## Target: $ARGUMENTS
-
-Use this workflow after implementation, QA, human approval, PR review, or a debugging session to preserve useful knowledge for future work.
-
-Primary behavior now lives in the `insight-capture` skill. Keep this workflow as the compatibility wrapper and knowledge-capture entry point.
-
-## Prompt Source
-
-Adapted from:
-
-- `insight_extractor.md`
-
-Additional credited discipline when the source work is a bug, regression, or incident:
-
-- `.agents/skills/9arm-skills/post-mortem/SKILL.md`
-- Source pack: `9arm-skills`
-- Credit: `thananon/9arm-skills`
-- Upstream: https://github.com/thananon/9arm-skills
-- Adapted for: Antigravity IDE / Nexus-DevFlow
-
-## Process
-
-### 1. Load Evidence
-
-Inspect the available evidence:
-
-- git diff or recent commits
-- `40-implement.md`
-- `50-verify.md`
-- `70-release.md`
-- `60-report.md`
-- modified files
-- human feedback or PR comments
-
-### 2. Extract Reusable Knowledge
-
-Capture only actionable knowledge:
-
-- file purpose and important changes
-- reusable patterns
-- gotchas and triggers
-- approach outcome
-- alternatives tried
-- context or token usage notes that explain avoidable overhead
-- recommendations for future sessions
-
-Avoid generic notes that do not help future work.
-
-For bug, regression, or incident work, apply the `post-mortem` lens only after fix and validation evidence exist:
-
-- what broke
-- impact
-- reliable repro or timeline
-- root cause
-- fix
-- validation evidence
-- why it slipped through
-- prevention or follow-up
-
-### 3. Save Or Route Insights
-
-Use the smallest durable destination:
+# Insight Extraction & Post-Mortem Learning
 
-- stage artifacts when the lesson is specific to the current run
-- `devflow/lessons.md` for project-wide lessons
-- `60-report` for final narrative communication before release
-- `70-release` for release-facing notes and execution details
+## Overview
 
-For token/context learning, prefer the smallest concrete note:
+This is the insight and knowledge extraction master skill for Nexus-DevFlow. It captures reusable engineering lessons, architectural patterns, gotchas, post-mortem incident analyses, and token-efficiency notes from completed implementation and verification work.
 
-- what context was loaded unnecessarily
-- which file, artifact, or agent handoff caused repeated reading
-- what should be passed as minimal context next time
-- exact token counts only when they are available from the runtime or provider
+**9arm Post-Mortem Pattern**:
+```text
+What Broke ➔ Business Impact ➔ Root Cause ➔ Fix Evidence ➔ Prevention & Guardrails
+```
 
-When updating `devflow/lessons.md`, inspect `.agent/resources/schemas/lessons.template.md` first and replace any placeholder text with concrete incident facts, insight, prevention, and follow-up action.
+---
 
-If task logs are appropriate:
+## 1. Types of Knowledge Extracted
 
-If this insight must be tied back to the running work item, record it in `50-verify.md`, `60-report.md`, `70-release.md`, or `devflow/lessons.md` rather than a legacy task log command.
+1. **Architectural Patterns**: Reusable structural patterns, data transformations, or component designs.
+2. **Gotchas & Hidden Invariants**: Subtle platform bugs, async timing issues, ORM quirks, or browser edge cases.
+3. **Incident Post-Mortems**: Rigorous root cause analysis and why tests/checks failed to catch the bug initially.
+4. **Context & Token Optimization**: Notes on avoidable context reading or redundant artifact parsing.
 
-## Output
+---
 
-Return:
+## 2. Process & Recording Destinations
 
-- file insights
-- patterns discovered
-- gotchas discovered
-- approach outcome
-- context usage notes
-- recommendations
-- where the insight was recorded or should be recorded
+1. **Load Evidence**: Review `git diff`, `40-implement.md`, `50-verify.md`, or test logs.
+2. **Distill Insights**: Formulate clear, actionable, non-generic takeaways.
+3. **Save to Persistent Memory**:
+   - Save project-wide engineering lessons to `devflow/context/lessons.md` (or `knowledge/lessons.md`).
+   - Feed run-specific learnings into `60-report.md` and `70-release.md`.
 
-If `post-mortem` was applied, include a short `Source Discipline` note crediting `9arm-skills/post-mortem`.
+---
 
 ## Relationship To DevFlow 2.0
 
-- Classification: Companion command
-- Mainline status: Knowledge capture command, not a numbered stage
-- Typical entry points: after `Debug`, `50-verify`, incident work, or review findings
-- Typical handoff targets: `Wiki`, `60-report`, `Help`
-
-## Sources
-
-- `AGENTS.md`
-- `.agent/resources/schemas/lessons.template.md`
-- Related commands: `Debug`, `50-verify`, `Wiki`, `60-report`, `Help`
-
-## Next Workflow Recommendation
-
-- **Primary**: `Wiki project ingest {source}` when the insight is reusable project knowledge.
-- **Why**: `Insight` extracts lessons; `Wiki` compiles selected lessons into navigable knowledge pages.
-- **Alternatives**:
-  - `60-report {ID}` - choose this when the insight should become the final communication summary before release.
-  - `70-release {ID}` - choose this when the insight should shape release packaging or execution details.
-  - `Help {ID}` - choose this when the next route is unclear.
-
-## Wiki Update Recommendation
-
-- **Needed**: `yes` for reusable lessons, gotchas, decisions, validated root causes, or token/context optimizations.
-- **Scope**: `project` for target-project lessons, `framework` for DevFlow workflow lessons.
-- **Reason**: Insight extraction is the safest handoff point for wiki compilation.
-- **Suggested Command**: `Wiki project ingest {source}`
-
+- **Classification**: Companion command & Continuous learning
+- **Mainline integration**: Invoked after `50-verify` or `60-report`.
+- **Handoff**: `60-report`, `70-release`

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

@@ -0,0 +1,114 @@
+---
+name: overview
+description: "[Devflow] Scan codebase architecture, data models, and shipped history to synthesize or refresh devflow/context/project-overview.md as the living source of truth."
+---
+
+# overview - Living Context Synthesis & Sync
+
+Where this sits in the workflow:
+
+```text
+codebase + devflow/history/HISTORY.md  ->  [overview]  ->  devflow/context/project-overview.md  ->  00-discover / 10-define / 20-spec
+(reality & shipped runs)                    (sync &         (living source of truth)             (informed planning)
+                                             synthesize)
+```
+
+`overview` is the context synchronization and synthesis engine for Nexus-DevFlow. It inspects the actual codebase (manifest, dependencies, directory layout, models/schemas, entry points) along with the completed delivery history (`devflow/history/HISTORY.md` and `devflow/runs/`) to build or refresh `devflow/context/project-overview.md`.
+
+It ensures that `project-overview.md` remains a **Living Source of Truth** that evolves alongside your software, rather than a stale artifact left behind after onboarding.
+
+## Usage
+
+```text
+/overview
+$overview
+overview
+```
+
+Use this when:
+- Multiple delivery runs (`RUN-xxx`) have shipped and `project-overview.md` needs to reflect newly added capabilities.
+- New database schemas, ORM models, or API boundaries were introduced.
+- Major dependencies or architectural patterns were added or modified.
+- After completing `70-release` to keep project context perfectly aligned.
+- Preparing for a new initiative or discovery pass.
+
+---
+
+## Process
+
+### Step 1 - Scan Reality (Codebase Survey)
+
+Inspect the actual codebase to establish hard facts:
+
+1. **Manifest & Tooling**:
+   - Read `package.json`, `pyproject.toml`, `go.mod`, `Cargo.toml`, `pom.xml`, or `Gemfile`.
+   - Identify language versions, primary framework, state management, and build tools.
+2. **Directory Architecture**:
+   - Map high-level directory layout (`src/`, `app/`, `api/`, `lib/`, `components/`, etc.).
+   - Identify major modules, entry points, and routing conventions.
+3. **Concrete Data Models & Schemas**:
+   - Search for ORM schemas (`schema.prisma`, Drizzle schemas, TypeORM entities, SQLAlchemy models, Zod schemas, or core TypeScript types).
+   - Extract entity names, core fields, relationships, and invariants.
+4. **Verified Commands**:
+   - Inspect package scripts (`dev`, `build`, `test`, `lint`, `check`, `verify`).
+
+---
+
+### Step 2 - Scan History (Delivered Capabilities)
+
+Inspect DevFlow history records:
+
+1. Read `devflow/history/HISTORY.md` for completed and released milestones.
+2. Scan completed delivery runs in `devflow/runs/` to extract shipped user-visible capabilities and core system features.
+
+---
+
+### Step 3 - Synthesize `project-overview.md`
+
+Write or update `devflow/context/project-overview.md` following standard structure:
+
+```markdown
+# Project Overview & Source of Truth
+
+> Living context artifact automatically synchronized with codebase reality and DevFlow delivery history.
+
+## 1. Project Purpose & Target Users
+- High-level summary of what the system does, who it serves, and the core problem it solves.
+
+## 2. Architecture & Directory Layout
+- Visual directory layout tree with short descriptions for major modules and boundaries.
+
+## 3. Technology Stack & Key Tooling
+- Frontend, Backend, Database, ORM, Testing frameworks, CI/CD, and Package Manager.
+
+## 4. Concrete Data Models & Entities
+- Field-level definitions of major entities, types, and relationships.
+
+## 5. Shipped Capabilities & Key Modules
+- Consolidated list of active features and subsystems verified in the codebase.
+
+## 6. Verified Commands & Developer Workflow
+- Exact commands for Dev, Build, Test, Lint, and Verify.
+
+## 7. Known Architectural Focus Areas
+- Known technical debt, active migrations, or upcoming architectural focus points.
+```
+
+---
+
+### Step 4 - Review & Report
+
+Present a concise summary of the sync:
+- Models or entities detected and added
+- Shipped capabilities refreshed from history
+- Stack and tooling updates
+- Any inconsistencies or gaps found between code and documentation
+
+---
+
+## Rules & Guardrails
+
+1. **Grounded in Reality**: Never invent non-existent packages, fictional data models, or unverified endpoints. Everything in `project-overview.md` must be traceable to real code or recorded history.
+2. **Preserve User Intent**: Do not erase custom business rules or user-written notes. Integrate new facts smoothly around existing intent.
+3. **Concrete Over Vague**: Provide actual model names, field types, and route paths rather than vague one-line summaries.
+4. **Non-Destructive**: `overview` only writes to `devflow/context/project-overview.md`. It never modifies source code, runs migrations, or touches git history.