@jakkrichm/create-nexus-devflow 2.2.0 → 2.2.2

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

@@ -58,11 +58,12 @@
 
 ```text
 nexus-devflow/
-├── .agents/skills/             # Codex & Google Antigravity skill definitions
+├── .agents/skills/             # Codex, Google Antigravity & Copilot skill definitions
 ├── .claude/skills/             # Claude Code mirrored skill adapters
 ├── .nexus/                     # Metadata tracking & upstream baseline ledger
 ├── devflow/                    # Framework workspace context, history, and discoveries
 │   ├── context/                # Living source-of-truth context files
+│   ├── decisions/              # Architecture Decision Records (ADRs)
 │   ├── discoveries/            # Pre-delivery discovery records (00-explore.md)
 │   ├── history/                # Master delivery archive (features/, fixes/, rollbacks/, HISTORY.md)
 │   └── ideas.md                # Idea Inbox and backlog
@@ -90,22 +91,33 @@ nexus-devflow/
 
 ---
 
-## 7. Testing & Empirical Proof Standards
+## 7. Testing & Empirical Proof Standards (Strict TDD & Two-Stage Review)
 
 Testing is a core quality gate in Nexus-DevFlow, not an afterthought:
 
 - **Unit Test Mandate**: Any new feature, modified logic, parser improvement, or bug fix **MUST ship with automated unit tests** in the same diff.
+- **Strict TDD (Red-Green-Refactor) Protocol**:
+  1. **🔴 RED (Test First)**: Always write automated tests *before* writing or modifying functional logic. Run the test command and verify that it fails for the expected reason.
+  2. **🟢 GREEN (Minimal Code)**: Write only the minimal production code necessary to make the failing test pass. Run the test command and verify 100% green pass.
+  3. **🔵 REFACTOR (Clean & Robust)**: Refactor code for readability, performance, and DRY/YAGNI discipline while ensuring all tests stay green.
+  - *Code Deletion / Reversion Rule*: If functional code is created without a prior failing test for behavior changes, it must be reverted or immediately backed by tests before continuing.
 - **Test Framework**: Use Node.js native test runner executed via `tsx --test test/*.test.ts` under `packages/create-nexus-devflow/`.
 - **Test Design (AAA Pattern)**:
   - Structure each test case cleanly: **Arrange** (setup fixtures/mock directories), **Act** (execute function), **Assert** (verify invariants).
   - Use isolated temporary directories (`fs.mkdtemp` in `os.tmpdir()`) and ensure cleanup in `finally` blocks.
 - **Empirical Proof Contract**:
   - Never claim a task is "working", "tested", or "verified" without providing concrete empirical proof (exact command executed, terminal output, pass/fail counts, exit code).
-- **Multi-Lane Verification Matrix**:
-  - **Lane 1 (Type & Syntax Safety)**: `tsc --noEmit` (0 type errors).
-  - **Lane 2 (Automated Test Suites & Evals)**: `npm test` (Unit tests 100% pass) + `npm run test:routing` (Skill routing accuracy).
-  - **Lane 3 (Scrutinize & Security Audit)**: Edge cases, null-safety, 0 secrets, safe inputs.
-  - **Lane 4 (Manual / Scenario Proof)**: Concrete walkthrough steps ("Where to go", "What to run", "What to expect").
+- **Two-Stage Review Pattern (Verification Gate)**:
+  - **Stage 1: Spec Fidelity & Acceptance Gate**:
+    - Verify 100% conformance against the living spec (`current-feature.md` or `20-spec.md`).
+    - Validate all Acceptance Criteria (ACs) and "Done When" observables without missing requirements or scope creep.
+    - Test edge cases and boundary conditions defined in the specification.
+  - **Stage 2: Code Quality, Security & Architecture Gate**:
+    - **Lane 1 (Type & Syntax Safety)**: `tsc --noEmit` (0 type errors).
+    - **Lane 2 (Automated Test Suites & Evals)**: `npm test` (Unit tests 100% pass) + `npm run test:routing` (Skill routing accuracy).
+    - **Lane 3 (Scrutinize & Security Audit)**: Edge cases, null-safety, 0 secrets, safe inputs.
+    - **Lane 4 (Manual / Scenario Proof)**: Concrete walkthrough steps ("Where to go", "What to run", "What to expect").
+    - **Findings Ledger State**: 0 blockers (P0/P1) in `devflow/context/findings.md`.
 
 ---
 
@@ -140,3 +152,16 @@ Testing is a core quality gate in Nexus-DevFlow, not an afterthought:
   - `Major`: Breaking architectural change
   - `Minor`: New feature addition
   - `Patch`: Bug fix or documentation update
+
+---
+
+## 11. Architecture Decision Records (ADRs) & Domain Glossary
+
+- **Domain Glossary (`devflow/context/glossary.md`)**:
+  - Keep domain terms concise, precise, and unambiguous.
+  - Define entity boundaries, invariants, and lifecycle rules.
+  - Do NOT store implementation specs or ephemeral task lists in the glossary.
+- **Architecture Decision Records (`devflow/decisions/ADR-xxx-{slug}.md`)**:
+  - Store durable, high-impact, hard-to-reverse architectural decisions in `devflow/decisions/`.
+  - Number sequentially (`ADR-001`, `ADR-002`, ...).
+  - Must include: Context, Decision, Alternatives Considered (with trade-offs), and Consequences (positive gains and accepted risks).

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

@@ -2,7 +2,7 @@
 
 - **Active Discovery ID**: `None`
 - **Active Running ID**: `None`
-- **Current Stage**: `Idle (Ready for new /feature, /fix, /00-explore, or /10-define)`
+- **Current Stage**: `Idle (Ready for new /feature, /fix, /discovery, or /10-define)`
 - **Living Spec**: `None`
 - **Last Completed Run**: `None`
 - **Last Updated**: `None`

package/template/devflow/decisions/README.md

@@ -0,0 +1,24 @@
+# 🏛️ Architecture Decision Records (ADRs)
+
+This directory stores durable Architecture Decision Records (ADRs) produced during `/grill`, `00-explore`, or high-stakes architectural design sessions.
+
+---
+
+## 📋 ADR Format & Standards
+
+Each ADR is named `ADR-xxx-{slug}.md` (e.g. `ADR-001-database-schema-migration.md`) and follows this structure:
+
+```markdown
+# ADR-xxx: {Title}
+
+- **Status**: Accepted | Proposed | Deprecated | Superseded by ADR-yyy
+- **Date**: YYYY-MM-DD
+- **Context**: Problem statement, background, and why this decision was needed.
+- **Decision**: The selected architectural approach or invariant.
+- **Alternatives Considered**:
+  - *Option 1*: Pros / Cons
+  - *Option 2*: Pros / Cons
+- **Consequences**:
+  - *Positive*: Benefits and capabilities unlocked
+  - *Trade-offs / Risks*: Costs, complexity, or constraints
+```

package/template/devflow/history/HISTORY.md

@@ -8,7 +8,7 @@ This master ledger tracks all released delivery runs, milestones, and rollbacks
 
 | Completed Date | Run ID | Category | Title | Git Commit | Status | Archive Link |
 | :--- | :--- | :--- | :--- | :--- | :--- | :--- |
-| _No shipped runs yet_ | - | - | Run `/feature` or `/00-explore` to start your first delivery run | - | - | - |
+| _No shipped runs yet_ | - | - | Run `/feature` or `/discovery` to start your first delivery run | - | - | - |
 
 ---
 

package/template/.agents/skills/00-explore/SKILL.md

@@ -1,84 +0,0 @@
----
-name: 00-explore
-description: "[devflow][D] Explore stage in DevFlow 2.0 - explore a request, route supporting inquiry, and decide whether delivery work should begin without allocating a running ID."
-argument-hint: "{title, request, or discovery-id}"
----
-
-# Phase 00: Explore
-
-$ARGUMENTS
-
-Explore a request before delivery commitment. Create or resume a Discovery ID, choose only the supporting route that the uncertainty requires, and finish with a visible `Proceed`, `Defer`, or `Reject` decision. Do not create a Running ID in this stage.
-
-## Usage
-
-```text
-00-explore {title or request}
-00-explore IDEA-xxx
-00-explore {discovery-id}
-```
-
-Use this when:
-
-- a new request needs discussion before the team commits to delivery
-- exploring a pending idea from `devflow/ideas.md` (`00-explore IDEA-xxx`)
-- the best route may be `Brainstorm`, `PRD`, `Research`, or `Debug`
-- supporting findings need to be synthesized into a go/no-go decision
-
-## Markdown-First Contract
-
-Write the primary discovery artifact to:
-
-```text
-devflow/discoveries/{DISCOVERY_ID}-{slug}/00-explore.md
-```
-
-A Discovery ID uses a separate namespace such as `DISC-YYYYMMDD-NNN`. It is not a Running ID and must not reserve a numeric delivery run.
-
-## Process
-
-### Loop Contract
-
-Run discovery as a decision-and-routing loop, not as task initialization.
-
-- **Intent**: understand the request, select proportionate supporting inquiry, and decide whether the idea should enter delivery definition.
-- **Context**: read the request, discovery artifact when resuming, project context, constraints, and available evidence.
-- **Action**: restate the problem, identify the decision-blocking uncertainty, select `Brainstorm`, `PRD`, `Research`, `Debug`, or direct decision, then synthesize returned findings.
-- **Observation**: use concrete evidence such as option tradeoffs, product framing, research results, root cause, stakeholder constraints, open questions, and visible risk.
-- **Stop Condition**: stop when the selected route and evidence are recorded, open questions are visible, and the decision is `Proceed`, `Defer`, or `Reject`.
-- **Handoff**: only an approved `Proceed` discovery may hand off to `10-define {discovery_id}`.
-
-### 1. Supporting Routes & Built-in Lenses
-
-1. **Brainstorming Lens (Divergent & Convergent)**:
-   - Formulate 2-3 viable options.
-   - Construct a **Trade-off Comparison Table**:
-     | Option | Pros | Cons | Recommendation |
-     | :--- | :--- | :--- | :--- |
-2. **Research & Empirical Proof Lens**:
-   - Inspect existing codebase patterns with search tools (`grep_search`, `rg`).
-   - Conduct external web search if library feasibility or API contracts are uncertain.
-   - Record verifiable empirical facts.
-3. **PRD & Scoping Lens**:
-   - Problem Statement & Target User Persona.
-   - Core User Stories (`As a... I want to... So that...`).
-   - In-Scope vs. Out-of-Scope boundaries.
-4. **Issue & Bug Triage Lens**:
-   - Classify severity (`Critical/Blocker`, `Major`, `Minor`).
-   - Determine whether root-cause analysis (`debug`) is required before spec.
-
-### 2. Decision & Approval Gate
-
-Set one decision:
-- `Proceed`: enough value and evidence exist to define delivery work
-- `Defer`: the idea remains relevant but timing, evidence, or ownership is not ready
-- `Reject`: the idea should not proceed under the current framing
-
-### 3. Write `00-explore.md`
-
-Record selected routes, returned findings, open questions, decision, and rationale.
-
-## Next Workflow Recommendation
-
-- **Primary**: `10-define {discovery_id}` only after approved Proceed
-- **Defer/Reject**: No next command needed

package/template/.claude/skills/00-explore/SKILL.md

@@ -1,84 +0,0 @@
----
-name: 00-explore
-description: "[devflow][D] Explore stage in DevFlow 2.0 - explore a request, route supporting inquiry, and decide whether delivery work should begin without allocating a running ID."
-argument-hint: "{title, request, or discovery-id}"
----
-
-# Phase 00: Explore
-
-$ARGUMENTS
-
-Explore a request before delivery commitment. Create or resume a Discovery ID, choose only the supporting route that the uncertainty requires, and finish with a visible `Proceed`, `Defer`, or `Reject` decision. Do not create a Running ID in this stage.
-
-## Usage
-
-```text
-00-explore {title or request}
-00-explore IDEA-xxx
-00-explore {discovery-id}
-```
-
-Use this when:
-
-- a new request needs discussion before the team commits to delivery
-- exploring a pending idea from `devflow/ideas.md` (`00-explore IDEA-xxx`)
-- the best route may be `Brainstorm`, `PRD`, `Research`, or `Debug`
-- supporting findings need to be synthesized into a go/no-go decision
-
-## Markdown-First Contract
-
-Write the primary discovery artifact to:
-
-```text
-devflow/discoveries/{DISCOVERY_ID}-{slug}/00-explore.md
-```
-
-A Discovery ID uses a separate namespace such as `DISC-YYYYMMDD-NNN`. It is not a Running ID and must not reserve a numeric delivery run.
-
-## Process
-
-### Loop Contract
-
-Run discovery as a decision-and-routing loop, not as task initialization.
-
-- **Intent**: understand the request, select proportionate supporting inquiry, and decide whether the idea should enter delivery definition.
-- **Context**: read the request, discovery artifact when resuming, project context, constraints, and available evidence.
-- **Action**: restate the problem, identify the decision-blocking uncertainty, select `Brainstorm`, `PRD`, `Research`, `Debug`, or direct decision, then synthesize returned findings.
-- **Observation**: use concrete evidence such as option tradeoffs, product framing, research results, root cause, stakeholder constraints, open questions, and visible risk.
-- **Stop Condition**: stop when the selected route and evidence are recorded, open questions are visible, and the decision is `Proceed`, `Defer`, or `Reject`.
-- **Handoff**: only an approved `Proceed` discovery may hand off to `10-define {discovery_id}`.
-
-### 1. Supporting Routes & Built-in Lenses
-
-1. **Brainstorming Lens (Divergent & Convergent)**:
-   - Formulate 2-3 viable options.
-   - Construct a **Trade-off Comparison Table**:
-     | Option | Pros | Cons | Recommendation |
-     | :--- | :--- | :--- | :--- |
-2. **Research & Empirical Proof Lens**:
-   - Inspect existing codebase patterns with search tools (`grep_search`, `rg`).
-   - Conduct external web search if library feasibility or API contracts are uncertain.
-   - Record verifiable empirical facts.
-3. **PRD & Scoping Lens**:
-   - Problem Statement & Target User Persona.
-   - Core User Stories (`As a... I want to... So that...`).
-   - In-Scope vs. Out-of-Scope boundaries.
-4. **Issue & Bug Triage Lens**:
-   - Classify severity (`Critical/Blocker`, `Major`, `Minor`).
-   - Determine whether root-cause analysis (`debug`) is required before spec.
-
-### 2. Decision & Approval Gate
-
-Set one decision:
-- `Proceed`: enough value and evidence exist to define delivery work
-- `Defer`: the idea remains relevant but timing, evidence, or ownership is not ready
-- `Reject`: the idea should not proceed under the current framing
-
-### 3. Write `00-explore.md`
-
-Record selected routes, returned findings, open questions, decision, and rationale.
-
-## Next Workflow Recommendation
-
-- **Primary**: `10-define {discovery_id}` only after approved Proceed
-- **Defer/Reject**: No next command needed