@jakkrichm/create-nexus-devflow 2.13.0 → 2.15.0

package/template/devflow/docs/quickstart.md

@@ -0,0 +1,119 @@
+# Quickstart Guide
+
+Getting started with **Nexus-DevFlow 2.13.0** — an enterprise agentic workflow layer supporting **The 3-Pillars Workspace Architecture & Pure Task-Isolated Living Spec Model** for Google Antigravity, OpenAI Codex, Claude Code, Cursor, GitHub Copilot, and other AI IDEs.
+
+---
+
+## 1. Client Installation
+
+In your terminal, navigate to your target project folder (either a fresh scaffold or an existing codebase):
+
+```bash
+# Automated install (Recommended)
+npx -y @jakkrichm/create-nexus-devflow@latest -y
+
+# Interactive install (Select specific tool adapters)
+npx @jakkrichm/create-nexus-devflow@latest
+```
+
+This overlays the `.agents/`, `.claude/`, and `devflow/` workflow structures into your repository without modifying your existing application source code.
+
+---
+
+## 2. Project Baseline Setup
+
+Open your AI IDE (Antigravity, Claude Code, Codex, or Cursor) and run the appropriate starting command in the chat:
+
+| Situation | Starting Command | Purpose |
+| :--- | :--- | :--- |
+| **Existing Codebase (Brownfield)** | `/adopt` *(or `$adopt`)* | Surveys your codebase, creates baseline planning docs, coding standards, and registers project context. |
+| **Fresh Project (Scaffolded)** | `/onboard` *(or `$onboard`)* | Configures project metadata, stack commands, coding standards, and tool adapters. |
+| **Health & Setup Check** | `/doctor` *(or `$doctor`)* | Read-only diagnostic checking adapters, config files, commands, and workflow integrity. |
+| **Interactive Navigation** | `/devflow` *(or `$devflow`)* | Flagship guide that analyzes workspace state and recommends the exact next action. |
+
+---
+
+## 3. The Unified 4-Stage Task-Isolated Living Spec Lifecycle
+
+All development tasks (from small UI fixes to deep architectural features) execute through the 4-stage task-isolated living spec lifecycle:
+
+```text
+/feature (or /fix) ──▶ /implement ──▶ /check ──▶ /complete
+```
+
+1. **`/feature {title}`** (or **`/fix {bug}`**): Allocates sequential ID (`xxx-slug`) and initializes the Task-Isolated Living Spec in `devflow/context/{xxx-slug}/spec.md`, stage pointer (`stage.md`), and dedicated audit ledger (`findings.md`).
+2. **`/implement [id]`**: Incrementally executes checklist tasks in `devflow/context/{xxx-slug}/spec.md` with strict TDD discipline (Red-Green-Refactor).
+3. **`/check [id]`**: Senior QA multi-lane verification (Typecheck, Lint, Test suites, and behavioral manual proof), records empirical proof into `spec.md` and findings into `findings.md`.
+4. **`/complete [id]`**: Final safety audit, records Release Digest, auto-archives to `devflow/history/{features|fixes|rollbacks}/{xxx-slug}.md`, cleanly removes `devflow/context/{xxx-slug}/`, updates `HISTORY.md` and `build-plan.md`, and manages git squash-merge.
+
+---
+
+## 4. Pre-Flight Discovery, SA & Architectural Alignment
+
+Before committing to delivery, use specialized companion skills to refine complex requirements:
+
+```text
+/analyze ──▶ /idea (Inbox) ──▶ /grill (Socratic ADR) ──▶ /discovery (Explore) ──▶ /feature (Deliver)
+```
+
+- **`/analyze`**: Multi-format requirement ingestion (PDF, Word, Excel, Images) and codebase impact scan.
+- **`/idea`**: Quick idea capture in `devflow/ideas.md` with instant AI feasibility scoring.
+- **`/grill`** (or **`/align`**): Socratic alignment & domain modeling; records Architecture Decision Records (`devflow/decisions/ADR-xxx.md`).
+- **`/brainstorm`**: Structured ideation with trade-off analysis.
+- **`/discovery`**: Deep inception and exploratory discovery (`devflow/discoveries/DISC-xxx.md`).
+
+---
+
+## 5. The 3-Pillars Workspace Architecture
+
+```text
+devflow/
+├── ideas.md                    # 🔮 Future (Backlog): Idea Inbox with AI scoring
+├── project-plan.md             # 🔮 Future (Backlog): Product Vision & Architectural Roadmap
+├── build-plan.md               # 🔮 Future (Backlog): Master Feature Delivery Sequence
+├── context/                    # ⚡ Present (Active Context): Global Truth & Task Workspaces
+│   ├── project-overview.md     # Single Source of Truth
+│   ├── coding-standards.md     # Engineering standards & conventions
+│   ├── ai-interaction.md       # AI interaction guidelines
+│   ├── glossary.md             # Domain glossary & architecture terms
+│   └── {xxx-slug}/             # Active Task-Isolated Workspace
+│       ├── spec.md             # Living Spec & Task Breakdown
+│       ├── stage.md            # Stage pointer & status
+│       └── findings.md         # Dedicated audit & quality ledger
+├── decisions/                  # 🏛️ Decisions: Architecture Decision Records (ADR-xxx.md)
+├── history/                    # 📦 Past (History Archive): Categorized delivery archives
+│   ├── features/               # Shipped features ({xxx-slug}.md)
+│   ├── fixes/                  # Resolved bug fixes ({xxx-slug}.md)
+│   ├── rollbacks/              # Reversal audit logs (YYYY-MM-DD-{xxx-slug}.md)
+│   └── HISTORY.md              # Master release ledger
+└── discoveries/                # 🔍 Discoveries: Pre-delivery discovery records (DISC-xxx.md)
+```
+
+---
+
+## 6. Maintenance & CLI Commands
+
+```bash
+# Launch interactive Real-Time Local Dashboard (0ms SSR Hydration & Git Cache)
+npx @jakkrichm/create-nexus-devflow dashboard
+
+# Check active project status across 3-Pillars
+npx @jakkrichm/create-nexus-devflow status
+
+# Automated Quality Gatekeeper
+npx @jakkrichm/create-nexus-devflow gate [--strict]
+
+# Model Context Protocol (MCP) Server Hub
+npx @jakkrichm/create-nexus-devflow mcp
+
+# Multi-Agent Swarm & Code Graph RAG
+npx @jakkrichm/create-nexus-devflow swarm
+npx @jakkrichm/create-nexus-devflow graph --file src/index.ts
+
+# JIT Context Slicing Engine
+npx @jakkrichm/create-nexus-devflow slice --stage implement
+
+# Manage vendor skills (e.g. bughunter, matt-pocock)
+npx @jakkrichm/create-nexus-devflow skill list
+npx @jakkrichm/create-nexus-devflow skill restore
+```

package/template/devflow/docs/release-process.md

@@ -0,0 +1,52 @@
+# Release Process
+
+This guide is for framework maintainers preparing a Nexus-DevFlow release. Keep the flow manual-first, use only the commands that already exist in this repository, and treat validation evidence as the release gate.
+
+---
+
+## 1. Pre-Release Readiness
+
+- Confirm the intended release scope before changing version or release wording.
+- Confirm that maintainer-facing and user-facing docs (`README.md`, `README.th.md`, `devflow/docs/`) stay aligned.
+- Review `ROADMAP.md` only for a status refresh when the release changes roadmap milestones.
+- Decide whether the release is patch, minor, or major according to Semantic Versioning.
+
+---
+
+## 2. Validation Suite
+
+Run baseline checks from the framework root:
+
+```bash
+npm run check
+npm run check:static
+npm test
+npm run test:package
+```
+
+Release only after all validation steps pass with exit code 0.
+
+---
+
+## 3. Install & Upgrade Verification
+
+Verify that the overlay package builds and updates cleanly:
+
+```bash
+npx @jakkrichm/create-nexus-devflow update --dry-run
+```
+
+---
+
+## 4. Release Notes
+
+- Summarize user-facing changes separately from maintainer-only changes in `CHANGELOG.md`.
+- Call out changes to release, install, or upgrade guidance explicitly.
+- State whether the release is patch, minor, or major and why.
+
+---
+
+## 5. Tagging & Release Policy
+
+- **Commits to `main`**: Internal maintenance, documentation tweaks, or minor refactoring that does not affect the npm overlay package should be pushed directly to `main` without creating a git tag.
+- **Git Tag Releases (`v*`)**: Create and push git tags (`v2.5.x`) only when there is a functional update to `@jakkrichm/create-nexus-devflow` or a new release intended for npm publishing and GitHub Releases.

package/template/devflow/docs/skill-selection-policy.md

@@ -0,0 +1,64 @@
+# Skill Selection Policy
+
+Use this policy when deciding which skill or companion tool to activate for a given task in **Nexus-DevFlow 2.13.0**.
+
+---
+
+## 1. Lifecycle Selection Policy
+
+Nexus-DevFlow 2.13.0 uses the **Task-Isolated Living Spec Lifecycle** for all development work:
+
+```text
+/feature (or /fix) ──▶ /implement ──▶ /check ──▶ /complete
+```
+
+- **Choose `/feature`**: For all planned features, new capabilities, refactorings, or architecture upgrades. Supports intake from Idea Inbox (`/feature IDEA-xxx`) or Discovery (`/feature DISC-xxx`).
+- **Choose `/fix`**: For ad-hoc bug repairs, regressions, or hotfixes.
+- **Choose `/implement`**: To execute checklist tasks with strict TDD discipline (Red-Green-Refactor).
+- **Choose `/check`**: For Dual-Axis verification before delivery: observable spec fidelity plus independent standards, architecture, security, and quality gates.
+- **Choose `/complete`**: For final safety audit, Release Digest, archiving, and branch delivery gate.
+
+---
+
+## 2. Pre-Flight Discovery & Architectural Alignment Policy
+
+Use pre-flight skills before committing to delivery when exploring new ideas or resolving ambiguity:
+
+```text
+/idea (Inbox) ──▶ /grill (Socratic ADR) ──▶ /discovery (Explore) ──▶ /feature (Deliver)
+```
+
+- **Choose `/idea`**: When capturing raw thoughts or feature proposals with AI feasibility scoring.
+- **Choose `/grill`** (or **`/align`**): When complex domain concepts need pressure-testing and Architecture Decision Records (ADRs).
+- **Choose `/brainstorm`**: When exploring 2–3 viable approaches with trade-off matrices.
+- **Choose `/discovery`**: For deep multi-turn inception research and exploration before speccing.
+
+---
+
+## 3. Companion Tools & Quality Gates Mapping
+
+| Need | Recommended Command | Behavior |
+| :--- | :--- | :--- |
+| **System Diagnostics** | `/doctor` | Read-only check of adapters, configs, and workflow drift. |
+| **Workspace Navigation** | `/devflow` | Flagship state inspector and next action router. |
+| **Root-Cause Analysis** | `/debug` | Scientific six-phase diagnosis using a deterministic red-capable feedback loop without modifying source. |
+| **Architecture & Spec Verification** | `/check` | Reviews Deep Modules, documented standards, and behavioral acceptance as independent axes. |
+| **Manual QA Guide** | `/try` | Generates click-by-click human manual test guide. |
+| **Code & Security Audit** | `/audit` | Branch-aware or full-project code and security audit. |
+| **Feature Reversal** | `/rollback` | Analyzes dependency risks and drafts safe rollback spec. |
+| **CI Setup** | `/ci` | Configures `.github/workflows/verify.yml` with detected package manager. |
+| **Unit Test Setup** | `/setup-tests` / `/test` | Runs test suites or scaffolds missing unit tests. |
+| **Autonomous Pass** | `/autopilot` | Bounded Single Living Spec execution loop (`feature`/`fix` -> `implement` -> `check`) stopping before merge. |
+| **Visual Mockup** | `/prototype` | Throwaway HTML/CSS mockups sharing design tokens. |
+| **Cloud Readiness** | `/release` | Deployment readiness check (Render / Vercel). |
+| **Interactive Report** | `/report-html` | Generates standalone HTML dashboard on demand. |
+
+---
+
+## 4. Selection Boundaries & References
+
+- The **32 bundled Core Skills** are the names in `agent-bundle.manifest.json#core_skills`; Local or Personal Skills are workspace extensions, not automatic public commands.
+- Prefer an existing Core Skill before adding a new public surface. Follow [governance rules](governance-rules.md) for promotion and placement decisions.
+- Generated artifacts follow the [Markdown metadata contract](markdown-metadata-contract.md).
+- Human review responsibilities are defined in the [manual review workflow](manual-review-workflow-spec.md).
+- Use [Living Spec examples](examples/living-spec/) as structural references, not as copy-paste requirements.

package/template/devflow/docs/workflow-surface-map.md

@@ -0,0 +1,85 @@
+# Workflow Surface Map (32 Core Skills)
+
+This document outlines the active workflow surfaces and command taxonomy in **Nexus-DevFlow 2.13.0**.
+
+The canonical surface contains **32 Core Skills** from
+`agent-bundle.manifest.json#core_skills`. Additional Local or Personal Skills
+may exist in a workspace, but are not bundled product commands until explicitly
+promoted into that inventory.
+
+---
+
+## 1. Universal Command Invocations
+
+Each command in DevFlow has exactly **one canonical name** and can be invoked across AI IDEs:
+- **Slash Prefix (`/`)**: For Google Antigravity, Claude Code, Gemini CLI (e.g. `/feature`, `/devflow`, `/discovery`).
+- **Dollar Prefix (`$`)**: For OpenAI Codex (e.g. `$feature`, `$devflow`, `$discovery`).
+- **Plain Canonical Name**: Direct tool/skill calling in generic terminals or non-native agents (e.g. `feature`, `implement`, `check`, `complete`).
+
+---
+
+## 2. Canonical Surface Taxonomy (32 Core Skills)
+
+### ⚡ 1. The 4-Stage Living Spec Lifecycle Skills (7 Skills)
+| Command | Category | Purpose | Primary Artifact |
+| :--- | :--- | :--- | :--- |
+| `feature` | Spec & Plan | Combines discovery, specification, and task breakdown for planned work. | `devflow/context/{xxx-slug}/spec.md` |
+| `fix` | Spec & Plan | Documents and specs ad-hoc bug repairs or small changes. | `devflow/context/{xxx-slug}/spec.md` |
+| `implement` | Execution | Incrementally executes checklist tasks with strict TDD discipline. | `devflow/context/{xxx-slug}/spec.md` |
+| `check` | Quality Gate | Dual-Axis review of empirical spec fidelity and independent standards/architecture quality. | `devflow/context/{xxx-slug}/spec.md` |
+| `complete` | Delivery | Final safety audit, records Release Digest, branch merge, and archiving. | `devflow/history/{features\|fixes\|rollbacks}/` |
+| `continuous` | Delivery | Autonomous serial multi-feature delivery loop with local branches, quality gates, and squash-merges. | `devflow/history/features/` |
+| `rollback` | Delivery | Safe feature reversal with dependency risk analysis preserving history. | `devflow/history/rollbacks/` |
+
+---
+
+### 🔮 2. Pre-Flight Discovery, SA & Alignment Suite (5 Skills)
+| Command | Category | Purpose | Primary Artifact |
+| :--- | :--- | :--- | :--- |
+| `analyze` | SA Ingestion | Multi-format requirement ingestion (PDF, Word, Excel, Images), Codebase Impact scan & Socratic Gap checklist. | `devflow/inbox/` & `devflow/analysis/` |
+| `idea` | Backlog | Idea inbox capture and AI feasibility scoring. | `devflow/ideas.md` |
+| `grill` / `align` | Alignment | Socratic alignment interview, domain glossary extraction, and ADR generation. | `devflow/decisions/` & `glossary.md` |
+| `brainstorm` | Ideation | Structured divergent & convergent ideation with trade-off matrices. | Interactive session |
+| `discovery` | Exploration | Deep multi-turn inception exploration and discovery records. | `devflow/discoveries/DISC-xxx.md` |
+
+---
+
+### 🧰 3. Workspace Governance & Operations (20 Skills)
+| Command | Category | Purpose |
+| :--- | :--- | :--- |
+| `devflow` | Navigation | Flagship interactive guide, state inspector, and intent router. |
+| `doctor` | Diagnostics | Read-only health check for setup, adapters, and workflow drift. |
+| `overview` | Context | Regenerate and validate `project-overview.md` from planning docs. |
+| `brief` | Planning | Scope and dependency briefing before speccing a feature. |
+| `debug` | Diagnostics | Scientific six-phase diagnosis using a deterministic red-capable feedback loop. |
+| `onboard` | Onboarding | Setup baseline context on fresh or scaffolded projects. |
+| `adopt` | Onboarding | Survey existing codebase and bootstrap DevFlow context into brownfield apps. |
+| `try` | Quality Gate | Generate step-by-step human manual QA review guide. |
+| `audit` | Quality Gate | Branch-aware or full-project code and security audit. |
+| `bughunter` | Security | Offensive security orchestrator, 83 vulnerability patterns & CVE payloads. |
+| `ci` | Automation | Configure GitHub Actions verify workflow (`.github/workflows/verify.yml`). |
+| `test` | Quality Gate | Test runner, missing test generation, and coverage check. |
+| `setup-tests` | Quality Gate | Add or normalize unit test suite. |
+| `browser-tests` | Quality Gate | Add or normalize Playwright browser test harness & connect with MCP browseros-neo. |
+| `autopilot` | Autonomous | Bounded Living Spec execution loop (`feature`/`fix` -> `implement` -> `check`) stopping before merge. |
+| `prototype` | Ideation | Throwaway pre-build static HTML/CSS mockups sharing design tokens. |
+| `release` | Deployment | Cloud deployment readiness check (Render / Vercel). |
+| `status` | State | Progress summary and next action inspector. |
+| `report-html` | Reporting | Generate interactive standalone HTML report dashboard. |
+| `convert-any-to-md` | Utility | Document conversion utility into markdown in `devflow/reference/`. |
+
+---
+
+## 3. Bundled Core vs Local Extensions
+
+- **Bundled Core Skill**: listed in `agent-bundle.manifest.json#core_skills`, mirrored across both adapters, validated, and included in the package template.
+- **Local/Personal Skill**: present in a maintainer workspace but absent from the canonical inventory; allowed locally and excluded from package output.
+- **Promotion rule**: adding a directory does not promote a command. Promotion requires an explicit inventory, documentation, adapter, test, and release decision.
+
+## 4. Review & Authoring References
+
+- [Skill selection policy](skill-selection-policy.md)
+- [Governance rules](governance-rules.md)
+- [Markdown metadata contract](markdown-metadata-contract.md)
+- [Manual review workflow](manual-review-workflow-spec.md)
+- [Living Spec examples](examples/living-spec/)