@jakkrichm/create-nexus-devflow 2.0.0

package/template/.claude/skills/workflow-documentation-sync/SKILL.md

@@ -0,0 +1,87 @@
+---
+name: workflow-documentation-sync
+description: Enforces the synchronization and comprehensive update of documentation, manuals, usage guides, and examples whenever a new workflow is introduced or modified in the project. Use when introducing new workflows or changing existing ones.
+---
+
+# Workflow Documentation Sync
+
+## Overview
+This skill ensures that whenever a DevFlow 2.0 workflow or companion command is introduced or modified, all associated documents, user guides, manuals, and usage examples are thoroughly and systematically updated. This prevents outdated context and ensures humans and AI agents have an accurate, uniform understanding of the available tools.
+
+## When to Use
+- When creating a new workflow file under `.agents/skills/*.md`.
+- When modifying the inputs, outputs, processes, or rules of an existing workflow.
+- When deprecating or removing a workflow.
+
+Do NOT use when modifying source code logic that doesn't impact workflow interface, arguments, or overall process.
+
+---
+
+## 🏗️ Core Process
+
+### Step 1: Identify Documentation Targets
+Whenever a workflow is added or modified, compile the list of documents that must be synchronized:
+1. **User Guide / Manual**: [**`USAGE.md`**](file:///d:/nexus-devflow/USAGE.md) (The main IDE user manual).
+2. **Workflow Index**: `.agents/skills/README.md` (if present) or any registry that lists command interfaces.
+3. **Template/Example files**: Any scratch templates, templates, or example files that demonstrate workflow inputs.
+
+### Step 2: Extract Workflow Metadata
+Identify the exact interface changes:
+- What is the **Command trigger**? (e.g., `/70-Release` or `Brainstorm`)
+- What are the **Arguments**? (e.g., Target Branch, default main)
+- What is the **Process flow**? (Pre-flight -> Execution -> Cleanup)
+- What are the **Mandatory Rules**? (e.g., Enforced branch checks)
+
+### Step 3: Comprehensive Updates
+Update all target files systematically:
+1. **Update USAGE.md**: Locate the quick command index and detail sections. Inject the new workflow command, its purpose, argument syntax, full execution steps, and real-world examples.
+2. **Update Workflow Index**: Add the new workflow to the lists of available command surfaces.
+3. **Create Examples**: If the workflow uses complex parameters or stage artifacts, ensure clean, tested examples are placed in the task workspace or referenced guides.
+
+### Step 4: Verify Alignment
+Ensure that:
+- The command prefix is consistent across all documents.
+- Any manual steps described in the guide match the automation logic of the workflow file.
+- Outdated versions or deleted arguments are removed from all documents.
+
+---
+
+## 🛠️ Documentation Template for USAGE.md
+
+When injecting a new workflow into `USAGE.md`, use the following structure:
+
+```markdown
+### 🔀 /{Workflow-Name} - {Workflow-Title}
+- **วัตถุประสงค์**: {Brief description of what it does in Thai}
+- **วิธีใช้งาน**:
+  ```powershell
+  /{Workflow-Name} [Arguments]
+  ```
+- **ขั้นตอนการทำงาน (Process)**:
+  1. {Step 1}
+  2. {Step 2}
+- **กฎเกณฑ์และ Gotchas (Rules & Gotchas)**:
+  - {Mandatory rules or things to watch out for}
+- **ตัวอย่างการใช้งาน (Example)**:
+  - `/{Workflow-Name} {Example-Arguments}`
+```
+
+---
+
+## 🚫 Common Rationalizations
+
+| Rationalization | Reality |
+|:---|:---|
+| "I'll update USAGE.md in the next task." | Undocumented workflows are forgotten workflows. Doc drift starts with a single missed update. |
+| "The prompt in the workflow file is self-documenting." | Workflow prompts are optimized for AI. Humans need clean, Thai-friendly usage instructions with clear examples. |
+| "The workflow is too simple to need examples." | Even simple workflows (like Merge or PR) have edge cases (e.g., force delete warnings) that must be documented. |
+
+---
+
+## ✅ Verification Checklist
+
+- [ ] Every new/modified workflow has been mapped to `USAGE.md`.
+- [ ] Argument parameters in the markdown guide perfectly match the actual `.md` workflow trigger.
+- [ ] Real-world, copy-pasteable execution examples are provided.
+- [ ] Deprecated or old workflow definitions have been removed or clearly marked as legacy to prevent hallucination.
+- [ ] Verification command output or terminal execution proof is recorded.

package/template/.claude/skills/writing-great-skills/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: writing-great-skills
+description: Maintainer reference for writing predictable DevFlow skills. Use when creating, importing, pruning, or refactoring .agent/skills content.
+disable-model-invocation: true
+---
+
+# Writing Great Skills
+
+Use this maintainer support skill when editing `.agent/skills`.
+
+A skill exists to make a process predictable. It should make the agent take the same kind of action in the same kind of situation, without bloating context or competing with workflow ownership.
+
+## Invocation
+
+Choose the lowest-load invocation mode:
+
+- Model-invoked skill: use when the agent must discover and apply the skill on its own.
+- User-invoked skill: use when only humans or another explicit router should call it.
+- Router skill: use when many user-invoked skills create cognitive load.
+
+In DevFlow, public workflow surface should stay stable. New skills usually start as support skills, not public companion commands.
+
+## Description Rules
+
+- Front-load the leading word.
+- Include only distinct trigger branches.
+- Remove synonyms that repeat the same trigger.
+- Keep stage ownership out of the description; put lifecycle placement in the body.
+
+## Information Hierarchy
+
+Put material where it belongs:
+
+1. In-skill steps: actions every invocation needs.
+2. In-skill reference: rules frequently needed during execution.
+3. External reference files: details only some branches need.
+
+Use progressive disclosure for long reference material.
+
+## Splitting Rules
+
+Split a skill only when:
+
+- it needs independent model invocation
+- a long step sequence causes premature completion
+- branches are different enough that one file causes confusion
+
+Do not split only because a file is aesthetically long.
+
+## Pruning Rules
+
+- Keep one source of truth for each rule.
+- Delete no-op advice that does not change behavior.
+- Delete stale upstream assumptions when importing.
+- Prefer DevFlow stage names and artifact paths.
+
+## Import Checklist
+
+- [ ] Fits `docs/skill-selection-policy.md`.
+- [ ] Does not create a new mainline stage.
+- [ ] Does not expand public companion commands by accident.
+- [ ] Names owning DevFlow stages.
+- [ ] Describes output location.
+- [ ] Routes contradictions back to the owning stage.
+- [ ] Passes `npm run validate`.

package/template/.nexus/nexus-devflow.json

@@ -0,0 +1,44 @@
+{
+  "schemaVersion": 1,
+  "name": "nexus-devflow",
+  "package": "@jakkrichm/create-nexus-devflow",
+  "version": "2.0.0",
+  "repository": "https://github.com/Jakkrich/nexus-devflow",
+  "artifactLanguage": "th",
+  "adapters": [
+    "claude",
+    "codex"
+  ],
+  "workspace": {
+    "contextDir": "devflow/context",
+    "historyDir": "devflow/history",
+    "referenceDir": "devflow/reference",
+    "runsDir": "devflow/runs",
+    "discoveriesDir": "devflow/discoveries"
+  },
+  "lifecycle": {
+    "mainlineStages": [
+      "00-discover",
+      "10-define",
+      "20-spec",
+      "30-plan",
+      "40-implement",
+      "50-verify",
+      "60-report",
+      "70-release"
+    ],
+    "companionCommands": [
+      "goal",
+      "brainstorm",
+      "research",
+      "debug",
+      "prd",
+      "issue-triage",
+      "security-review",
+      "wiki",
+      "check-for-updates",
+      "help"
+    ]
+  },
+  "installedAt": "2026-08-17T00:00:00.000Z"
+}

package/template/AGENTS.md

@@ -0,0 +1,58 @@
+# Nexus-DevFlow 2.0 (Blueprint-Style 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.
+
+## Tool-Specific Adapters
+
+The workflow and skills are exposed through tool-specific adapters:
+
+- **Codex & Google Antigravity**: `.agents/skills/<skill>/SKILL.md`
+- **Claude Code**: `.claude/skills/<skill>/SKILL.md`
+
+Unused adapter families can be removed. Codex and Antigravity projects keep `.agents/` and `AGENTS.md`. Claude Code projects keep `.claude/` and `AGENTS.md` (via `CLAUDE.md`).
+
+## Timeline Workflow
+
+```text
+/00-Discover -> /10-Define -> /20-Spec -> /30-Plan -> /40-Implement -> /50-Verify -> /60-Report -> /70-Release
+```
+
+### Mainline Stages:
+1. `/00-Discover` - Explore a request before delivery commitment. Creates a Discovery ID (`.workspaces/discoveries/...`).
+2. `/10-Define` - Turn an approved discovery into one or more bounded delivery runs (`.workspaces/specs/{running-id}/10-define.md`).
+3. `/20-Spec` - Formalize markdown-first specifications (`20-spec.md`).
+4. `/30-Plan` - Transform spec into executable steps (`30-plan.md`).
+5. `/40-Implement` - Execute planned tasks incrementally (`40-implement.md`).
+6. `/50-Verify` - Run Senior QA review and validation check (`50-verify.md`).
+7. `/60-Report` - Produce markdown and HTML summary report (`60-report.md`, `60-report.html`).
+8. `/70-Release` - Package verified work for merge, PR, or deployment (`70-release.md`).
+
+### Public Companion Commands:
+- `Goal`: Route broad goals before Discovery
+- `Brainstorm`: Brainstorm ideas without creating running IDs
+- `Research`: Conduct codebase or web research
+- `Debug`: Root cause investigation before/during implementation
+- `PRD`: Product framing before delivery commitment
+- `Issue-Triage`: Intaking and triaging incoming reports
+- `Security-Review`: High-severity security review
+- `Wiki`: Knowledge base management under `.workspaces/wiki/`
+- `Check-For-Updates`: Verify or upgrade DevFlow setup
+- `Help`: Routing and process assistance
+
+## 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.
+
+## Verification & Commands
+
+- Verify framework integrity: `npm run check`
+- Static contract check: `npm run check:static`
+- Test installer package: `npm test`
+- Package smoke test: `npm run test:package`

package/template/CLAUDE.md

@@ -0,0 +1,5 @@
+# CLAUDE.md
+
+@AGENTS.md
+
+Instructions for Claude Code. This file imports `AGENTS.md` as the single source of truth for Nexus-DevFlow operating rules, stage lifecycles, and tool capabilities.

package/template/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nexus-DevFlow contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

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

@@ -0,0 +1,34 @@
+# 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.

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

@@ -0,0 +1,19 @@
+# Coding Standards & Guidelines
+
+General engineering standards for code, tests, and documentation.
+
+## Code Quality
+
+- Write clear, self-documenting code.
+- Avoid unnecessary complexity (prefer simple solutions over indirect abstractions).
+- Maintain type safety and static validation across module boundaries.
+
+## Testing & Verification
+
+- Every change in `/40-Implement` must be verified in `/50-Verify`.
+- Prefer test-driven evidence and automated scripts where applicable.
+
+## Git & Commits
+
+- Commit messages follow imperative summary format.
+- Create small, reviewed, and self-contained commits.

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

@@ -0,0 +1,6 @@
+# Current DevFlow Run Status
+
+- **Active Discovery ID**: None
+- **Active Running ID**: None
+- **Current Stage**: Idle
+- **Last Updated**: 2026-08-17

package/template/devflow/context/findings.md

@@ -0,0 +1,13 @@
+# Audit Findings Ledger
+
+Summary of audit findings, quality checks, security bugs, and debt tracked across DevFlow runs.
+
+## Open Findings
+
+| ID | Severity | Category | Title | Discovered Run | Status |
+| :- | :--- | :--- | :--- | :--- | :--- |
+
+## Resolved Findings
+
+| ID | Severity | Category | Title | Resolved Run | Date |
+| :- | :--- | :--- | :--- | :--- | :--- |

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

@@ -0,0 +1,20 @@
+# Project Overview
+
+Primary source of truth for the project context, architecture, tech stack, and active DevFlow stage status.
+
+## Application Summary
+
+- **Project Name**: [Project Name]
+- **Goal**: [Project Goal Description]
+- **Target Audience**: [Target Users]
+
+## Tech Stack
+
+- **Frontend**: [Framework / Language]
+- **Backend**: [Framework / Database]
+- **Deployment**: [Platform / Infrastructure]
+
+## DevFlow Workspaces
+
+- **Active Discovery ID**: None
+- **Active Running ID**: None

package/template/devflow/reference/running-id-contract.md

@@ -0,0 +1,39 @@
+# DevFlow 2.0 Running ID & Workspace Contract Reference
+
+## DevFlow Workspace Directory Structure
+
+All DevFlow framework context, active runs, templates, and history are consolidated under `devflow/`:
+
+- **Context (`devflow/context/`)**:
+  - `project-overview.md` - Primary source of truth for project architecture and stack.
+  - `coding-standards.md` - Development, code quality, and testing standards.
+  - `ai-interaction.md` - AI agent interaction rules and Thai artifact defaults.
+  - `current-stage.md` - Active stage run state.
+  - `findings.md` - Open and resolved audit findings ledger.
+
+- **Active Delivery Runs (`devflow/runs/{RUNNING_ID}/`)**:
+  - `10-define.md`
+  - `20-spec.md`
+  - `30-plan.md`
+  - `40-implement.md`
+  - `50-verify.md`
+  - `60-report.md` (and `60-report.html`)
+  - `70-release.md`
+
+- **Active Discoveries (`devflow/discoveries/{DISCOVERY_ID}-{slug}/`)**:
+  - `00-discover.md`
+
+- **History Archive (`devflow/history/`)**:
+  - `discoveries/` - Completed discovery archives.
+  - `runs/` - Completed delivery run archives.
+  - `reports/` - Completed stage reports.
+
+- **Reference Contracts (`devflow/reference/`)**:
+  - `running-id-contract.md`
+  - `stage-lifecycle-contract.md`
+
+## Mainline Lifecycle Rules
+
+1. Mainline stages move linearly: `/00-Discover` ➔ `/10-Define` ➔ `/20-Spec` ➔ `/30-Plan` ➔ `/40-Implement` ➔ `/50-Verify` ➔ `/60-Report` ➔ `/70-Release`.
+2. Companion commands (`Goal`, `Brainstorm`, `Research`, `Debug`, `PRD`, `Issue-Triage`, `Security-Review`, `Wiki`, `Check-For-Updates`, `Help`) provide supporting context without replacing mainline stage numbers.
+3. Every stage produces markdown-first evidence in `devflow/runs/` before passing verification gates.