@jakkrichm/create-nexus-devflow 2.0.12 → 2.0.13

package/template/.claude/skills/debug/SKILL.md

@@ -3,129 +3,68 @@ name: debug
 description: "[Devflow] Root cause investigation and diagnostic loop before or during implementation without editing code. Use when encountering broken behavior, test failures, or bugs."
 ---
 
----
-description: Root cause analysis and debugging. Transitional compatibility path for the Debug companion command in DevFlow 2.0.
----
-
-# Debug - Root Cause Analysis
-
-## Issue: $ARGUMENTS
-
-This file keeps its old numeric path for migration compatibility.
-
-In DevFlow 2.0, `Debug` is a companion command, not a numbered mainline workflow. Its investigative depth should remain comparable to the original debug workflow.
-
-## Purpose
-
-Use `Debug` to find the actual origin of an issue, not just the visible symptom.
-
-Use it when:
-
-- implementation work is blocked by a defect
-- verification reveals a failure that needs root-cause analysis
-- the team needs RCA before deciding the next implementation step
+# Debug & Root Cause Analysis (RCA)
 
-Preferred DevFlow 2.0 pairing:
+## Overview
 
-- from `00-discover` when a new request begins with a failure whose root cause is unknown
-- from `40-implement`
-- from `50-verify`
+This is the comprehensive debugging master skill for Nexus-DevFlow. It guides systematic root-cause investigation without blindly editing code. The goal is to find the actual origin of an issue, not merely suppress visible symptoms.
 
-When invoked with a Discovery ID, link the RCA report to that discovery and return to `00-discover {discovery_id}` for the delivery decision. Do not allocate a Running ID for an unapproved fix during Debug.
-
-## Source Discipline
-
-Apply the local skill pack at `.agents/skills/9arm-skills/debug-mantra/SKILL.md`.
-
-- Source pack: `9arm-skills`
-- Credit: `thananon/9arm-skills`
-- Upstream: https://github.com/thananon/9arm-skills
-- Mantra: `Reproduce -> Trace fail path -> Falsify hypothesis -> Cross-reference breadcrumbs`
+**The Debug Mantra (9arm Pattern)**:
+```text
+Reproduce ➔ Trace Fail Path ➔ Falsify Hypotheses ➔ Cross-reference Breadcrumbs ➔ RCA Proof
+```
 
 ---
 
-## Internal Process
-
-You are doing Root Cause Analysis, not just symptom triage. Keep the richer original debugging discipline and map the next step back into DevFlow 2.0.
-
-### Phase 1: Reproduce And Classify
-
-- restate the symptom clearly
-- capture expected vs actual behavior
-- determine whether the issue is reproducible
-- do not recommend a fix before the reproduction story is credible
+## 1. The 4-Phase Diagnostic Loop
 
-### Phase 2: Isolate And Hypothesize
+### Phase 1: Reproduce & Classify
+- Restate the observed symptom vs. expected behavior with exact steps.
+- Create a minimal reproduction script, test case, or curl command.
+- Rule: **Do not propose a code fix before the reproduction story is verified.**
 
-- identify likely components, recent changes, or conditions
-- generate 2-4 hypotheses ordered by likelihood
-- define what evidence would falsify each hypothesis
+### Phase 2: Isolate & Hypothesize
+- Generate 2–4 distinct hypotheses ranked by probability.
+- Formulate specific criteria and evidence that would *falsify* each hypothesis.
 
-### Phase 3: Investigate With Evidence
+### Phase 3: Non-Destructive Investigation
+- Trace code execution paths end-to-end (stack traces, logs, variable states, async boundaries).
+- Inspect recent commits or configuration changes that touch the affected boundary.
+- Test hypotheses methodically using tests and logging without altering business logic.
 
-- trace the real fail path end-to-end
-- test hypotheses methodically
-- record evidence with file:line or command output
-- maintain a breadcrumb trail of observations and conclusions
+### Phase 4: Root Cause Conclusion (RCA)
+- State precisely *why* the bug occurred (underlying invariant violation).
+- Define the minimal, robust architectural fix direction.
+- Propose regression prevention measures (unit test, type guard, linter rule).
 
-### Phase 4: Conclude With RCA
-
-- name the root cause
-- explain why it is the root cause
-- describe the fix direction
-- capture prevention or follow-up measures
-
-This command supports the active stage. It does not replace the mainline stage itself.
-
-## Output Format
-
-Save the RCA report to `devflow/debug/rca-{slug}.md`.
-
-Before generating the report:
+---
 
-1. Inspect `.agent/resources/schemas/rca.template.md`
-2. Preserve its required headings and structure
-3. Replace placeholder text with concrete evidence
-4. Re-check the output against `rca.template.md`, ensure required headings remain, and remove all placeholders before completion
+## 2. Output Format (RCA Report)
 
-Present the summary in this shape:
+Save substantial RCA investigations under:
+```text
+devflow/debug/rca-{slug}.md
+```
 
+Structure:
 ```markdown
 ## Debug Summary
 
-1. **Symptom**: [What is happening]
-2. **Evidence**: [error log, file, line, failing command]
-3. **Investigation Path**: [what was tested and what happened]
-4. **Root Cause**: [why this happened]
-5. **Fix Direction**: [what should be changed]
-6. **Prevention**: [how to avoid recurrence]
+1. **Symptom**: [What is happening vs expected]
+2. **Evidence**: [Error logs, stack trace, file:line references]
+3. **Investigation Path**: [Hypotheses tested and falsification proof]
+4. **Root Cause**: [The exact mechanism causing the failure]
+5. **Fix Direction**: [Recommended scoped change]
+6. **Regression Guard**: [Reproduction test to add before fixing]
 ```
 
-## Examples
-
-```text
-Debug flaky login redirect
-Debug failing migration in CI
-Debug why webhook verification breaks in staging
-Debug unexpected duplicate records
-```
+---
 
 ## Relationship To DevFlow 2.0
 
-- Classification: Companion command
-- Mainline status: Not a numbered stage
-- Typical entry points: `00-discover`, `40-implement`, `50-verify`, `Issue-Triage`, production failure analysis
-- Typical handoff targets: `00-discover {discovery_id}` for discovery-owned RCA, `40-implement`, `50-verify`, `Insight`, `Wiki`
-
-## Sources
-
-- `AGENTS.md`
-- `.agent/resources/schemas/rca.template.md`
-- Related commands: `40-implement`, `50-verify`, `Test`, `Insight`, `Wiki`, `Agent`
-
-## Next Workflow Recommendation
-
-- Default: return to `00-discover {discovery_id}` when the failure entered through discovery; otherwise return to `40-implement` when a tracked fix already exists
-- Alternate: `30-plan` if the fix needs planning changes
-- Alternate: `50-verify` when the issue is resolved and needs re-checking
-
+- **Classification**: Companion command & Investigation lane
+- **Mainline integration**:
+  - During `00-discover`: Unclear failure intake before allocation
+  - During `40-implement`: Hard test failure or unexpected runtime exception
+  - During `50-verify`: Defect found during QA inspection
+- **Handoff**: `test` (write repro test), `40-implement` (execute fix), `50-verify` (re-check)

package/template/.claude/skills/deploy/SKILL.md

@@ -1,91 +1,63 @@
----name: deploy
-
-description: "[Devflow] Production deployment pre-flight checks, smoke validation, and deployment execution."
 ---
-# ๐Ÿš€ Phase 52: Production Deployment (Auto-Deploy)
+name: deploy
+description: "[Devflow] Production deployment pre-flight checks, launch readiness, smoke validation, and deployment execution."
+---
 
-## Usage: `Deploy [subcommand]`
+# Production Deployment & Launch Readiness
 
-Perform pre-flight checks, deployment execution, and verification for production releases.
+## Overview
 
-Primary behavior now lives in:
+This is the comprehensive deployment master skill for Nexus-DevFlow. It handles pre-flight validation, multi-platform deployment execution (Vercel, Render, Railway, Fly.io, Docker), health checks, smoke verification, and safe rollback readiness.
 
 ```text
-.agents/skills/release-git-operations/SKILL.md
+Pre-Flight Checks ➔ Build & Smoke Test ➔ Deployment Execution ➔ Health Verification ➔ Release Logging
 ```
 
-Treat this workflow file as a compatibility wrapper around that skill in `deploy` mode.
-
 ---
 
-## ๐Ÿ› ๏ธ Sub-commands
+## 1. Pre-Flight Verification Checklist
 
-- `Deploy`            - Interactive deployment wizard
-- `Deploy check`      - Run pre-deployment checks only
-- `Deploy preview`    - Deploy to preview/staging
-- `Deploy production` - Deploy to production
-- `Deploy rollback`   - Rollback to previous version
+Before initiating any deployment, verify:
+1. **Code & Quality**: Zero syntax/type errors, linters clean, unit & integration tests passing (`npm test`).
+2. **Security**: No secrets in source code, environment variables documented in `.env.example`, `npm audit` checked.
+3. **Database & Migrations**: Schema migrations verified backwards-compatible and applied.
+4. **Performance & Assets**: Production bundles compiled, assets compressed, Core Web Vitals considered.
+5. **Observability**: Healthcheck endpoint (`/api/health`) responsive, error tracking configured.
 
 ---
 
-## ๐Ÿšฆ Internal Process
+## 2. Platform Deployment Matrix
 
-### Phase 1: Pre-Flight Checks
-Before any deployment, the AI MUST verify the following Checklist:
-1. **Code Quality**: No syntax errors, Linters passing, Tests passing.
-2. **Security**: No hardcoded secrets, Environment variables documented, Dependencies audited.
-3. **Performance**: Bundle size acceptable, Images optimized, No N+1 queries.
-4. **Accessibility**: Keyboard nav works, screen reader compatible, contrast adequate.
-5. **Infrastructure**: Env vars set, migrations ready, monitoring configured.
-6. **Documentation**: README / ADRs / CHANGELOG updated.
+| Target Platform | Deploy Method / Command | Verification Method |
+| :--- | :--- | :--- |
+| **Vercel** | `vercel --prod` or Git push | Inspect deployment URL & build logs |
+| **Render / Railway** | `railway up` or Git integration | Check service status & container logs |
+| **Fly.io** | `fly deploy` | Check `fly status` and HTTP response |
+| **Docker / VPS** | `docker compose up -d --build` | Check container health & PM2 logs |
 
-*You MUST run appropriate validation commands to systematically audit the codebase before giving the green light.*
+---
 
-### Phase 2: Deployment Execution
-Determine the project's platform (Vercel, Railway, Docker, Fly.io, etc.) and execute the appropriate build & deploy commands.
-- Vercel: `vercel --prod`
-- Railway: `railway up`
-- Docker: `docker compose up -d`
-- Fly.io: `fly deploy`
+## 3. Post-Deployment Smoke Verification & Health Check
 
-### Phase 3: Health Check, Verify & Report
-- **Template Verification**: **MANDATORY:** Before final deployment, inspect `.agent/resources/schemas/deploy_report.template.md`, preserve its required layout, and replace placeholder text with concrete environment, commands, checks, rollback notes, and deployment result.
-- Save the final deployment and pre-flight check report to `devflow/reports/{date}-deploy-report-{timestamp}.md` (where `{date}` is today's date in `YYYY-MM-DD` format and `{timestamp}` is a clean date/time slug).
-- Verify that the deployed application is responding (HTTP 200 OK) and all services (Database, API) are healthy.
+1. Send an HTTP request to the deployed domain: verify HTTP 200 OK.
+2. Test critical paths (Authentication, API endpoints, core database transactions).
+3. Confirm telemetry and error log stream are free of unhandled exceptions.
 
 ---
 
-## ๐Ÿ“ Output Formats
+## 4. Rollback Readiness
 
-### Successful Deploy
-Generate a summary indicating:
-- **Summary**: Version, Environment, Duration, Platform
-- **URLs**: Production, Dashboard
-- **Report Location**: Confirm the deploy checklist and validation report has been written to the specified workspace path.
-- **What Changed**: Bullet points of new features or fixes
-- **Health Check**: Status of API and Database
+Always have an immediate rollback plan before triggering production releases:
+- Pin the previous stable build artifact, Docker image tag, or Git commit hash.
+- If post-deployment smoke tests fail, trigger rollback immediately:
+  ```text
+  deploy rollback
+  ```
 
-### Failed Deploy
-Generate an Error summary detailing:
-- **Error**: Step where it failed (e.g., Build failed at TypeScript compilation)
-- **Details**: Exact error snippet
-- **Resolution**: Step-by-step fix recommendation
-- **Rollback Available**: Suggest running `Deploy rollback` if needed.
+---
 
 ## Relationship To DevFlow 2.0
 
-- Classification: Companion command
-- Mainline status: Release support command, not a numbered stage
-- Typical entry points: `70-release` after the report is aligned and packaging is ready to execute
-- Typical handoff targets: `60-report`, `Changelog`, `Wiki`
-
-## Sources
-
-- `AGENTS.md`
-- `.agents/skills/release-git-operations/SKILL.md`
-- `.agents/skills/shipping-and-launch/SKILL.md`
-- `.agents/skills/deployment-procedures/SKILL.md`
-- `.agent/resources/schemas/deploy_report.template.md`
-- Related commands: `70-release`, `Commit`, `PR`, `Changelog`, `60-report`
-
-
+- **Classification**: Companion command & Delivery support
+- **Mainline integration**: Invoked after `70-release` when ready to deploy.
+- **Handoff**: `60-report`, `changelog`, `rollback`

package/template/.claude/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/.claude/skills/preview/SKILL.md

@@ -3,119 +3,40 @@ name: preview
 description: "[Devflow] Local preview server management, smoke-check, and temporary runtime inspection before formal verification."
 ---
 
----
-description: Preview management and temporary runtime checks. Transitional compatibility path for the Preview companion command in DevFlow 2.0.
----
-
-# Preview Management
-
-## Usage
-
-```text
-Preview
-Preview start
-Preview stop
-Preview restart
-Preview check
-```
-
-This file keeps its old numeric path for migration compatibility.
-
-In DevFlow 2.0, `Preview` is a companion command, not a numbered mainline workflow.
-
-Primary behavior now lives in:
-
-```text
-.agents/skills/preview-local-check/SKILL.md
-```
+# Preview Management & Local Runtime Inspection
 
-Treat this workflow file as a compatibility wrapper around that skill.
+## Overview
 
-Manage the local preview development server or temporary runtime check.
+This is the preview master skill for Nexus-DevFlow. It manages local development/preview servers (`npm run dev`, `npm run preview`, `vite`, `next dev`), handles port conflicts, and executes smoke checks before formal verification.
 
-Use it when:
+## Usage & Sub-Commands
 
-- the team wants a quick visual or runtime check before formal verification
-- implementation needs a local smoke check
-- a temporary render helps clarify what changed
-- a human reviewer needs something concrete to inspect before giving feedback
-
-Preferred DevFlow 2.0 pairing:
-
-- from `40-implement`
-- from `50-verify`
+- `/preview`         - Inspect current preview status and health
+- `/preview start`   - Start the local preview/dev server
+- `/preview stop`    - Stop the running server process
+- `/preview restart` - Restart the preview server
+- `/preview check`   - Perform runtime smoke check against `http://localhost:<port>`
 
 ---
 
-## Sub-commands
+## 1. Process & Runtime Management
 
-- `Preview` - show current preview status
-- `Preview start` - start the server
-- `Preview stop` - stop the server
-- `Preview restart` - restart the server
-- `Preview check` - run a health check
+1. **Detect Framework & Command**: Identify the project runtime (`npm run dev`, `vite preview`, `pnpm start`, `python -m http.server`).
+2. **Handle Port Conflicts**: Check if the standard port (3000, 5173, 8080) is occupied; auto-select fallback port or terminate stale background processes.
+3. **Health & Smoke Check**: Query local endpoint via HTTP GET to verify HTTP 200 OK and asset loading.
+4. **Report Status**:
+   ```markdown
+   ## Preview Status
+   - **URL**: `http://localhost:3000`
+   - **App Type**: Next.js / Vite / Node.js
+   - **Health Status**: `OK` (200 OK)
+   - **Console / Network**: Zero fatal runtime errors
+   ```
 
 ---
 
-## Internal Process
-
-`Preview` manages the local preview workflow using the `preview-local-check` skill plus any available preview automation or equivalent project-local commands.
-
-When handling preview operations:
-
-1. detect the correct project or server command path
-2. report the current state clearly
-3. handle port conflicts gracefully
-4. keep the action scoped to preview management, not broader deployment
-5. distinguish between preview success and full verification success
-
-Commands should use the nearest equivalent project-local preview command for the project, such as `npm run dev`, `npm run preview`, framework-specific local servers, or other runtime helpers that already exist in the target project.
-
-### Resolving Port Conflicts
-
-If the port is in use, offer options:
-
-1. start on a different port
-2. terminate the process on the existing port
-3. specify a custom port
-
-### Status Format
-
-When displaying status, clearly state:
-
-- URL
-- project path
-- app type
-- health status
-- notes about blockers, missing dependencies, or startup warnings
-
-Example summary:
-
-```markdown
-## Preview Status
-
-- **URL**: `http://localhost:3000`
-- **Project Path**: `[absolute path]`
-- **App Type**: `Next.js | FastAPI | Odoo | PHP | Other`
-- **Health Status**: `OK | Warning | Failed`
-- **Notes**: [port conflict, startup issue, missing dependency, or none]
-```
-
 ## Relationship To DevFlow 2.0
 
-- Classification: Companion command
-- Mainline status: Not a numbered stage
-- Typical entry points: `40-implement`, `50-verify`, UI or runtime checking
-- Typical handoff targets: `50-verify`, `Debug`, `40-implement`
-
-## Sources
-
-- `AGENTS.md`
-- `.agents/skills/preview-local-check/SKILL.md`
-- Related commands: `40-implement`, `50-verify`, `Debug`
-
-## Next Workflow Recommendation
-
-- **Primary**: `50-verify` when preview confirms the change is ready for formal checks
-- **Alternative**: `40-implement` when preview exposed implementation work
-
+- **Classification**: Companion command & Runtime support
+- **Mainline stages**: `40-implement` (interactive visual check), `50-verify` (smoke test check)
+- **Handoff**: `50-verify`