@jakkrichm/create-nexus-devflow 2.0.0 → 2.0.2

package/README.md

@@ -1,81 +1,127 @@
 # @jakkrichm/create-nexus-devflow
 
-> **Nexus-DevFlow 2.0 Scaffolder & Overlay Tool** — Safely overlay the stage-based agentic workflow layer onto any scaffolded or existing codebase.
+Install Nexus-DevFlow into an already scaffolded app or existing repository.
 
-[![npm version](https://img.shields.io/npm/v/@jakkrichm/create-nexus-devflow.svg)](https://www.npmjs.com/package/@jakkrichm/create-nexus-devflow)
-[![license](https://img.shields.io/npm/l/@jakkrichm/create-nexus-devflow.svg)](https://github.com/Jakkrich/nexus-devflow/blob/main/LICENSE)
+[![npm version](https://img.shields.io/npm/v/@jakkrichm/create-nexus-devflow?style=flat-square&color=155eef)](https://www.npmjs.com/package/@jakkrichm/create-nexus-devflow)
+[![Validate DevFlow](https://github.com/Jakkrich/nexus-devflow/actions/workflows/validate.yml/badge.svg)](https://github.com/Jakkrich/nexus-devflow/actions/workflows/validate.yml)
+[![MIT license](https://img.shields.io/npm/l/@jakkrichm/create-nexus-devflow?style=flat-square&color=155eef)](LICENSE)
 
----
+[Repository](https://github.com/Jakkrich/nexus-devflow) |
+[Documentation](https://github.com/Jakkrich/nexus-devflow#readme) |
+[Changelog](https://github.com/Jakkrich/nexus-devflow/blob/main/CHANGELOG.md)
 
-## Quick Start
+Requires Node.js 18 or newer. Run the installer from an application that has
+already been scaffolded and initialized as a Git repository.
 
-### 1. Overlay into Current Project
 ```bash
-npx @jakkrichm/create-nexus-devflow
+npx @jakkrichm/create-nexus-devflow@latest
 ```
 
-### 2. Overlay into Specific Directory
-```bash
-npx @jakkrichm/create-nexus-devflow ./my-project
-```
+The installer copies the shared DevFlow workflow files into the current
+directory:
 
-### 3. Specify Tool Adapters
-```bash
-# Install both OpenAI Codex / Antigravity (.agents) and Claude Code (.claude)
-npx @jakkrichm/create-nexus-devflow --adapter both
+- `AGENTS.md`
+- `CLAUDE.md`
+- `.nexus/nexus-devflow.json`
+- `devflow/context/`
+- `devflow/reference/`
 
-# Install Codex & Google Antigravity adapter only
-npx @jakkrichm/create-nexus-devflow --adapter codex
+It adds `.agents/skills/` for Codex and Google Antigravity. Claude Code uses `CLAUDE.md` plus
+`.claude/skills/`. The `--both` option (default) installs both adapter families.
 
-# Install Claude Code adapter only
-npx @jakkrichm/create-nexus-devflow --adapter claude
+It keeps the app's root `README.md` alone and installs the DevFlow framework context under
+`devflow/context/` and `devflow/reference/`.
+
+The installed workflow guides AI assistants through an explicit 8-stage lifecycle:
+
+```text
+/00-Discover -> /10-Define -> /20-Spec -> /30-Plan -> /40-Implement -> /50-Verify -> /60-Report -> /70-Release
 ```
 
-### 4. Update Existing DevFlow Installation
+It also includes public companion commands (`Goal`, `Brainstorm`, `Research`, `Debug`, `PRD`, `Issue-Triage`, `Security-Review`, `Wiki`, `Check-For-Updates`, `Help`) and the flagship guide command `/devflow`.
+
+If you install Nexus-DevFlow while Claude Code is already open in the project,
+restart Claude Code in that folder so the newly added project skills appear.
+For Google Antigravity, start a new conversation or reopen the workspace after
+installing so the new slash commands are discovered.
+
+## Tool support
+
+| Tool | Installed adapter | Invocation |
+| --- | --- | --- |
+| Codex | `.agents/skills/` | `$devflow`, `$00-discover`, `$40-implement`, or plain language |
+| Google Antigravity | Shared `.agents/skills/` project skills | `/devflow`, `/00-discover`, `/40-implement`, and other slash commands after restarting Antigravity |
+| Claude Code | `.claude/skills/` | `/devflow`, `/00-discover`, `/40-implement`, and other slash commands |
+| Other tools | `AGENTS.md` plus readable skill files | Ask the agent to follow the matching `SKILL.md` |
+
+Codex and Antigravity share `.agents/skills`. The `--antigravity` or `--codex` option installs
+that shared adapter.
+
+## Options
+
 ```bash
-npx @jakkrichm/create-nexus-devflow update
+npx @jakkrichm/create-nexus-devflow@latest -- --codex
+npx @jakkrichm/create-nexus-devflow@latest -- --antigravity
+npx @jakkrichm/create-nexus-devflow@latest -- --claude
+npx @jakkrichm/create-nexus-devflow@latest -- --both
+npx @jakkrichm/create-nexus-devflow@latest -- --force
+npx @jakkrichm/create-nexus-devflow@latest -- --target ./my-app
 ```
 
----
+Use `--force` to overwrite existing DevFlow files. Without `--force`, the
+installer asks before overwriting in an interactive terminal and exits in
+non-interactive runs.
 
-## CLI Options
+## Updating an existing installation
 
-| Flag | Shortcut | Description | Default |
-| :--- | :--- | :--- | :--- |
-| `--adapter <name>` | | Select AI tool adapters (`codex`, `antigravity`, `claude`, `both`) | `both` |
-| `--force` | `-f` | Overwrite conflicting files without prompting | `false` |
-| `--dry-run` | | Preview changes without modifying disk | `false` |
-| `--yes` | `-y` | Automatically confirm interactive prompts | `false` |
-| `--version` | `-v` | Display package version | |
-| `--help` | `-h` | Display help screen | |
+Preview the update plan:
 
----
+```bash
+npx @jakkrichm/create-nexus-devflow@latest update --dry-run
+```
 
-## Workflow Timeline & Stage Lifecycle
+Apply the update:
 
-```text
-/00-Discover -> /10-Define -> /20-Spec -> /30-Plan -> /40-Implement -> /50-Verify -> /60-Report -> /70-Release
+```bash
+npx @jakkrichm/create-nexus-devflow@latest update
 ```
 
-1. **`/00-Discover`**: Explore requests before delivery commitment under a Discovery ID.
-2. **`/10-Define`**: Lock delivery boundaries and allocate Running IDs (`.workspaces/specs/{RUNNING_ID}`).
-3. **`/20-Spec`**: Formalize markdown-first specification contracts and done-when criteria.
-4. **`/30-Plan`**: Transform specs into executable task breakdowns.
-5. **`/40-Implement`**: Execute planned tasks incrementally with implementation evidence.
-6. **`/50-Verify`**: Senior QA review and runtime validation check.
-7. **`/60-Report`**: Generate standardized markdown and HTML stage reports.
-8. **`/70-Release`**: Package verified work for PR merge or production deployment.
+The updater detects the installed adapters and manages only these paths:
+
+- `.agents/skills/`
+- `.claude/skills/`
+- `devflow/reference/`
+
+It preserves `AGENTS.md`, `CLAUDE.md`, `devflow/context/`, `devflow/history/`,
+`devflow/runs/`, and `devflow/discoveries/`. The `.nexus/nexus-devflow.json` file records the
+installed version and hashes of managed files.
+
+Locally modified managed files are reported as conflicts. Interactive updates
+ask before replacing them. Non-interactive updates exit unless you pass
+`--force`, which backs up the conflicting files before replacement.
+
+## Artifact language
 
----
+New installations default user-facing artifacts and explanations to Thai via
+`artifact_language: "th"` in `devflow/context/ai-interaction.md`. Technical
+names, code, paths, commands, schema keys, quoted errors, and required template
+headings remain unchanged for compatibility. Because the updater preserves this
+project-owned file, the language choice remains in place across updates.
 
-## Tool Adapters Architecture
+For an older installation, add the same setting and guidance to its local
+`devflow/context/ai-interaction.md` once.
 
-- **`AGENTS.md`**: Universal cross-tool entry point and source of truth for Codex, Antigravity, Cursor, Gemini CLI, Aider, and Zed.
-- **`CLAUDE.md`**: Imports `@AGENTS.md` for Claude Code.
-- **`.agents/skills/`**: Stores stage workflows and discipline skills for Codex & Google Antigravity.
-- **`.claude/skills/`**: Stores synced stage workflows and skills for Claude Code.
+## Help and contributing
 
----
+- Read the [full documentation](https://github.com/Jakkrich/nexus-devflow#readme).
+- Report reproducible problems through the repository's
+  [issue forms](https://github.com/Jakkrich/nexus-devflow/issues/new/choose).
+- Follow the repository's
+  [security policy](https://github.com/Jakkrich/nexus-devflow/security/policy)
+  for private vulnerability reports.
+- Read the
+  [contribution guide](https://github.com/Jakkrich/nexus-devflow/blob/main/CONTRIBUTING.md)
+  before opening a pull request.
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jakkrichm/create-nexus-devflow",
-  "version": "2.0.0",
+  "version": "2.0.2",
   "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/20-spec/SKILL.md

@@ -1,43 +1,43 @@
 ---name: 20-spec
-
-description: Spec stage in DevFlow 2.0 - write the formal markdown-first specification from a stable definition.
-argument-hint: "{running-id or workspace path}"
----
-
-# Phase 20: Spec
-
-$ARGUMENTS
-
-Turn the defined work into a specification that is concrete enough for planning and explicit enough to serve as the delivery contract.
-
-## Usage
-
-```text
-/20-Spec {running-id or workspace path}
-```
-
-Use this when:
-
-- the goal and scope are stable
-- the team needs testable or reviewable requirements
-- planning should not start until the contract is explicit
-
-## Markdown-First Contract
-
-Write the primary stage artifact to:
-
-```text
-devflow/runs/{ID}-{slug}/20-spec.md
-```
-
-using:
-
-```text
-.agent/resources/schemas/spec.template.md
-```
-
-Before writing `20-spec.md`, read `artifact_language` from `spec.template.md` and produce the artifact in that language.
-
+
+description: Spec stage in DevFlow 2.0 - write the formal markdown-first specification from a stable definition.
+argument-hint: "{running-id or workspace path}"
+---
+
+# Phase 20: Spec
+
+$ARGUMENTS
+
+Turn the defined work into a specification that is concrete enough for planning and explicit enough to serve as the delivery contract.
+
+## Usage
+
+```text
+/20-Spec {running-id or workspace path}
+```
+
+Use this when:
+
+- the goal and scope are stable
+- the team needs testable or reviewable requirements
+- planning should not start until the contract is explicit
+
+## Markdown-First Contract
+
+Write the primary stage artifact to:
+
+```text
+devflow/runs/{ID}-{slug}/20-spec.md
+```
+
+using:
+
+```text
+.agent/resources/schemas/spec.template.md
+```
+
+Before writing `20-spec.md`, read `artifact_language` from `spec.template.md` and produce the artifact in that language.
+
 ## Required Section Content
 
 Before completing any generated artifact:
@@ -51,106 +51,106 @@ Before completing any generated artifact:
 - re-read the saved artifact and verify every heading satisfies this rule
 
 ## Process
-
-### Loop Contract
-
-Run specification as a contract-hardening loop, not as a prose expansion of the definition.
-
-- **Intent**: produce requirements and acceptance criteria that are concrete enough for planning and review.
+
+### Loop Contract
+
+Run specification as a contract-hardening loop, not as a prose expansion of the definition.
+
+- **Intent**: produce requirements and acceptance criteria that are concrete enough for planning and review.
 - **Context**: read the run's `10-define.md`, follow its `source_discovery` link when original framing matters, and read relevant research, hard constraints, and domain or codebase decisions that shape this run's delivery contract.
-- **Action**: write requirements, acceptance criteria, constraints, and out-of-scope items, then inspect whether each requirement is testable and unambiguous.
-- **Observation**: use concrete evidence such as ambiguous wording, unchecked assumptions, edge cases, missing acceptance criteria, conflicting constraints, and implementation details that are not true constraints.
+- **Action**: write requirements, acceptance criteria, constraints, and out-of-scope items, then inspect whether each requirement is testable and unambiguous.
+- **Observation**: use concrete evidence such as ambiguous wording, unchecked assumptions, edge cases, missing acceptance criteria, conflicting constraints, and implementation details that are not true constraints.
 - **Adjustment**: if facts are missing, route to `Research`; if requirements need stress-testing, use `grill-with-docs`; if module or interface boundaries affect the contract, use `codebase-design`; if scope is unstable or still contains multiple independently deliverable contracts, return to `/10-Define` and split the run before continuing.
-- **Stop Condition**: stop when every requirement has checkable acceptance criteria, hard constraints are explicit, out-of-scope items are visible, and `/30-Plan` can break the work down without inventing intent.
-- **Handoff**: `20-spec.md` must tell `/30-Plan` what must be delivered, how success will be checked, what constraints cannot move, and what is intentionally excluded.
-
-### 1. Read Definition Artifacts
-
-Read:
-
-- `10-define.md`
+- **Stop Condition**: stop when every requirement has checkable acceptance criteria, hard constraints are explicit, out-of-scope items are visible, and `/30-Plan` can break the work down without inventing intent.
+- **Handoff**: `20-spec.md` must tell `/30-Plan` what must be delivered, how success will be checked, what constraints cannot move, and what is intentionally excluded.
+
+### 1. Read Definition Artifacts
+
+Read:
+
+- `10-define.md`
 - the shared `00-discover.md` referenced by `source_discovery` when the original framing still matters
-- research notes if they impose real constraints
-
-### 2. Write The Specification
-
-Define:
-
-- core requirements
-- acceptance criteria
-- hard constraints
-- explicit out-of-scope items
-
-The spec should be strong enough that planning can break it into executable units without guessing intent.
-
-### 3. Handle Missing Certainty
-
-If the spec cannot be written confidently:
-
-- call `Research` when facts are missing
-- use `grill-with-docs` when requirements, acceptance criteria, constraints, or out-of-scope items need to be stress-tested against scenarios and domain language
-- use `codebase-design` when requirements imply module boundaries, interface contracts, seams, or testability constraints
-- record assumptions explicitly when they are unavoidable
-
+- research notes if they impose real constraints
+
+### 2. Write The Specification
+
+Define:
+
+- core requirements
+- acceptance criteria
+- hard constraints
+- explicit out-of-scope items
+
+The spec should be strong enough that planning can break it into executable units without guessing intent.
+
+### 3. Handle Missing Certainty
+
+If the spec cannot be written confidently:
+
+- call `Research` when facts are missing
+- use `grill-with-docs` when requirements, acceptance criteria, constraints, or out-of-scope items need to be stress-tested against scenarios and domain language
+- use `codebase-design` when requirements imply module boundaries, interface contracts, seams, or testability constraints
+- record assumptions explicitly when they are unavoidable
+
 Do not hide uncertainty inside vague requirement text.
 
 Do not combine sibling Running IDs into one spec. If this run still contains multiple independent acceptance, release, ownership, or context boundaries, stop and return to `/10-Define {running_id}` for an explicit split.
-
-### 4. Finalize `20-spec.md`
-
-- preserve the template headings
-- follow the `artifact_language` configured in `spec.template.md`
-- replace all placeholders
-- keep implementation details out unless they are true constraints
-- make sure the acceptance criteria can actually be checked
-
-### 5. Manual Review Soft Gate
-
-Before recommending `/30-Plan`, check whether the delivery contract has been human-reviewed.
-If `Approval Status` is not approved yet:
-
-- warn that planning may drift if the spec is still under review
-- recommend review of requirements, exclusions, and acceptance criteria first
-- keep `/30-Plan` as a soft recommendation only
-
-## Output
-
-Report:
-
-- core requirements
-- acceptance criteria
-- hard constraints
-- out-of-scope items
-- manual review warnings when the contract is still pending
-- recommended next step
-
-## Relationship To DevFlow 2.0
-
-- Classification: Mainline workflow
-- Previous state: `/10-Define`
-- Next state: `/30-Plan` when the contract is implementation-ready
-- Common companion commands: `PRD`, `Spec-Research`, `Competitor`, `Spec-Orchestrate` when product or integration context is still incomplete; support skills: `grill-with-docs`, `domain-modeling`, and `codebase-design` when the spec depends on precise domain language, durable decisions, or module/interface constraints
-
-## Sources
-
-- `AGENTS.md`
-- `docs/workspace-artifacts.md`
-- `.agent/resources/schemas/spec.template.md`
-- Related commands: `/10-Define`, `PRD`, `Spec-Research`, `Competitor`, `Spec-Orchestrate`, `/30-Plan`
-
-## Next Workflow Recommendation
-
-- **Primary**: `/30-Plan`
-- **Why**: The specification is now concrete enough to break into executable work.
-- **Alternatives**:
-  - `Research` - choose this when the spec still depends on missing facts.
-  - `grill-with-docs` - choose this when the spec is readable but not yet tough enough to plan from.
-  - `codebase-design` - choose this when interface shape or testability constraints must be settled before planning.
-  - `/10-Define` - choose this when the scope itself is still unstable.
-
-## Nexus Event
-
-- Use `Research` when a requirement, rule, or integration constraint still lacks evidence.
-- Use `Spec-Research`, `Competitor`, or `PRD` when the contract needs stronger external, product, or market framing before planning.
-- Use `grill-with-docs` when available if clarification could materially change acceptance criteria, edge cases, exclusions, or rules.
-
+
+### 4. Finalize `20-spec.md`
+
+- preserve the template headings
+- follow the `artifact_language` configured in `spec.template.md`
+- replace all placeholders
+- keep implementation details out unless they are true constraints
+- make sure the acceptance criteria can actually be checked
+
+### 5. Manual Review Soft Gate
+
+Before recommending `/30-Plan`, check whether the delivery contract has been human-reviewed.
+If `Approval Status` is not approved yet:
+
+- warn that planning may drift if the spec is still under review
+- recommend review of requirements, exclusions, and acceptance criteria first
+- keep `/30-Plan` as a soft recommendation only
+
+## Output
+
+Report:
+
+- core requirements
+- acceptance criteria
+- hard constraints
+- out-of-scope items
+- manual review warnings when the contract is still pending
+- recommended next step
+
+## Relationship To DevFlow 2.0
+
+- Classification: Mainline workflow
+- Previous state: `/10-Define`
+- Next state: `/30-Plan` when the contract is implementation-ready
+- Common companion commands: `PRD`, `Spec-Research`, `Competitor`, `Spec-Orchestrate` when product or integration context is still incomplete; support skills: `grill-with-docs`, `domain-modeling`, and `codebase-design` when the spec depends on precise domain language, durable decisions, or module/interface constraints
+
+## Sources
+
+- `AGENTS.md`
+- `docs/workspace-artifacts.md`
+- `.agent/resources/schemas/spec.template.md`
+- Related commands: `/10-Define`, `PRD`, `Spec-Research`, `Competitor`, `Spec-Orchestrate`, `/30-Plan`
+
+## Next Workflow Recommendation
+
+- **Primary**: `/30-Plan`
+- **Why**: The specification is now concrete enough to break into executable work.
+- **Alternatives**:
+  - `Research` - choose this when the spec still depends on missing facts.
+  - `grill-with-docs` - choose this when the spec is readable but not yet tough enough to plan from.
+  - `codebase-design` - choose this when interface shape or testability constraints must be settled before planning.
+  - `/10-Define` - choose this when the scope itself is still unstable.
+
+## Nexus Event
+
+- Use `Research` when a requirement, rule, or integration constraint still lacks evidence.
+- Use `Spec-Research`, `Competitor`, or `PRD` when the contract needs stronger external, product, or market framing before planning.
+- Use `grill-with-docs` when available if clarification could materially change acceptance criteria, edge cases, exclusions, or rules.
+