@jakkrichm/create-nexus-devflow 2.0.20 → 2.0.22

package/template/.agents/skills/goal/SKILL.md

@@ -1,148 +0,0 @@
----
-name: goal
-description: "[Devflow] High-level goal routing and open-ended request intake before entering the 00-discover stage."
----
-
----
-description: Goal Router - Route a high-level goal into the correct DevFlow 2.0 path and record recommendation metrics.
----
-# Phase 05: Goal Router
-
-Route a high-level `/goal` request into the most appropriate DevFlow path.
-
-## Usage
-
-```text
-/goal {GOAL_DESCRIPTION}
-```
-
-Local CLI equivalent:
-
-```powershell
-npm run goal -- --goal "Implement goal command" --max-turns 30 --parallel
-npm run goal -- goal "Implement goal command" max-turns 30 parallel
-```
-
-## Purpose
-
-The goal router turns an open-ended request into a routed DevFlow recommendation plan.
-
-It should:
-
-- classify the goal into the right path
-- decompose large goals into worker-sized chunks
-- recommend the exact next command
-- record routing decisions, turn budget, and context notes in a session log
-
-The current goal runner is a routing and recommendation surface. It does not replace the mainline workflow or silently execute the full delivery lifecycle.
-
-## Boss-Worker Roles
-
-- `prp-core-boss` owns routing, decomposition, turn budgets, validation gates, and final synthesis.
-- `prp-core-worker` owns focused implementation or analysis subtasks assigned by the Boss.
-- Specialist agents may still be invoked with `Agent` when a task needs deeper domain expertise.
-
-## Flow Routing
-
-The Boss first classifies the request into one of these paths:
-
-| Flow | Use When | Typical Next Step |
-| :--- | :--- | :--- |
-| DevFlow Mainline | New feature, bug, test, docs, migration, or refactor requests. | `00-discover`, which owns the delivery decision |
-| PRD / Spec Orchestration | Product ideas or requirement-heavy planning before a Discovery ID exists. | `00-discover`, likely routing to `PRD` |
-| Brainstorm Flow | Early ambiguous ideas that need options and tradeoff analysis. | `00-discover`, likely routing to `Brainstorm` |
-| Research Flow | External facts, docs, codebase evidence, or feasibility proof are needed. | `00-discover`, likely routing to `Research` |
-| RCA / Debug Flow | Failures, errors, regressions, or investigation-heavy bug reports. | `00-discover`, likely routing to `Debug` |
-
-## Process
-
-1. Parse the goal text and runtime config.
-2. Select a flow path and record the reasoning.
-3. Estimate complexity and split large goals into worker-sized tasks.
-4. Recommend the relevant DevFlow commands in the correct order.
-5. Track turns by phase and stop when the configured `max-turns` budget is reached.
-6. Run validation gates appropriate to the selected flow.
-7. Add lightweight context usage notes when the runtime or operator can provide them.
-8. Save a structured session report.
-
-## Log Contract
-
-Session logs are written to:
-
-```text
-devflow/runs/goal-sessions/session-{goal_id}.json
-devflow/runs/goal_latest_session.json
-devflow/runs/goal_execution_log.json
-```
-
-Each log includes:
-
-- `goal_id`
-- `goal_description`
-- `status`
-- `execution_mode`
-- `config`
-- `metrics`
-- `context_usage`
-- `flow_selected`
-- `tasks_decomposed`
-- `execution_steps`
-- `recommended_commands`
-
-### Context Usage Notes
-
-`context_usage` is intentionally manual and optional until the runtime exposes exact token telemetry. Use it to capture:
-
-- `context_loaded`
-- `files_read`
-- `artifacts_read`
-- `token_usage`
-- `optimization_notes`
-
-## Validation
-
-After changing goal runner behavior, run:
-
-```powershell
-npm run validate
-node .agent/scripts/test-goal-runner.mjs
-npm run goal -- goal "Create a small test task" max-turns 15 dry-run
-```
-
-## Output
-
-Report:
-
-- selected flow
-- task decomposition summary
-- session log path
-- recommended next command
-- key assumptions or routing risks
-
-## Relationship To DevFlow 2.0
-
-- Classification: Companion command
-- Mainline status: Not a numbered stage
-- Typical entry points: broad goals before a Discovery ID exists
-- Typical handoff target: `00-discover`, with a likely companion route recorded as guidance rather than executed outside Discover
-
-## Sources
-
-- `AGENTS.md`
-- `.agent/scripts/goal-runner.mjs`
-- Related commands: `00-discover`, `Brainstorm`, `Research`, `PRD`, `Spec-Orchestrate`, `Debug`
-
-## Next Workflow Recommendation
-
-- **Primary**: the first command listed in `recommended_commands`
-- **Why**: `Goal` exists to route broad intent into the correct DevFlow 2.0 entry point
-- **Alternatives**:
-  - `00-discover "{goal}"` for all new work; Discover chooses Brainstorm, PRD, Research, Debug, or direct decision
-  - `10-define {discovery_id}` only after an approved Proceed decision
-  - `20-spec {running_id}` only for an existing approved delivery run
-
-## Wiki Update Recommendation
-
-- Update the wiki only when the goal-routing session reveals a durable pattern, intake heuristic, or onboarding note worth reusing.
-- If the output is only a one-off routing decision, do not create or update wiki pages.
-

package/template/.agents/skills/handoff/SKILL.md

@@ -1,46 +0,0 @@
----
-name: handoff
-description: "[Devflow] Compact active context into a handoff note. Use when a DevFlow run must continue in another session, agent, or report without duplicating existing artifacts."
-disable-model-invocation: true
----
-
-# Handoff
-
-Use this support skill when work needs to move to another session or agent.
-
-DevFlow stage artifacts remain the source of truth. This skill should reference them instead of duplicating them.
-
-## Process
-
-1. Identify the continuation purpose.
-   - next stage
-   - specialist agent
-   - interrupted implementation
-   - verification follow-up
-   - release/report handoff
-
-2. Collect existing durable artifacts.
-   - stage markdown files
-   - checklists
-   - ADRs
-   - issues or PR links
-   - commits and diffs
-
-3. Write only the missing bridge context.
-   - current state
-   - decisions already made
-   - open blockers
-   - files or commands the next agent should inspect first
-   - suggested skills
-
-4. Redact secrets and sensitive data.
-
-## Output Location
-
-Prefer the active task workspace when the handoff belongs to the work item:
-
-```text
-devflow/runs/{ID}-{slug}/handoff-{date}.md
-```
-
-Use the OS temp directory only for throwaway cross-session transfer that should not become project history.

package/template/.agents/skills/help/SKILL.md

@@ -1,253 +0,0 @@
----name: help
-
-description: "[Devflow] DevFlow 2.0 help, routing guide, workflow sitemap, and process navigation."
-argument-hint: [optional: question, running id, stage, or issue]
----
-
-# Help
-
-This file is a transitional compatibility entry for DevFlow 2.0.
-
-In DevFlow 2.0, `Help` is a companion command, not a numbered mainline workflow.
-
-## Mission
-
-Act as a senior architect, project mentor, and Q&A assistant.
-
-Help should:
-
-- explain the current DevFlow 2.0 model
-- route the user to the correct mainline stage
-- recommend companion commands when the task is still unclear
-- warn when a prior stage still needs manual review
-- summarize current project or framework state
-- stay read-only
-
-Help must not:
-
-- act like a mainline stage
-- create or mutate stage artifacts directly
-- send the user into deprecated JSON-first flow unless the question is specifically about legacy migration
-
-## Read-Only Rule
-
-Help remains read-only.
-
-If the user asks Help to edit files directly, Help should instead:
-
-- explain the best next command
-- suggest the correct workflow or specialist agent
-- point to the correct stage artifact
-
-## Help Startup Routine
-
-When invoked, Help should verify system health first before summarizing task status.
-
-### Phase A: Environment Health Check
-
-Check system readiness step by step:
-
-1. verify `.agents/skills/` exists
-2. verify `devflow/discoveries/` and `devflow/runs/` exist
-3. verify the mainline workflow files exist
-4. verify schema resources exist under `.agent/resources/schemas/`
-
-If the framework is in mixed legacy/2.0 state, Help should say so explicitly.
-
-If core pieces are missing, stop and recommend the underlying fix first.
-
-### Phase B: Running Status Scan
-
-1. scan `devflow/discoveries/` for pending discovery decisions and `devflow/runs/` for active Running IDs
-2. prefer reading discovery and stage markdown files over legacy JSON
-3. summarize discovery decisions, run state, blockers, and likely next action
-4. treat `Approval Status` and `Next Allowed Command` as soft routing signals when they are present
-
-When available, Help may use the internal helper below to build a faster first-pass summary before reading individual stage files:
-
-```text
-node scripts/summarize-run-status.mjs
-node scripts/summarize-run-status.mjs --json
-```
-
-Typical summary shape:
-
-```text
-Help Summary:
-Environment: All OK
-
-Active Runs:
-- 010-auth-refactor: stage=40-execute | approval=Pending | next=50-verify 010 | warnings: manual review open
-- 011-billing-phase-1: stage=20-spec | approval=Approved | next=30-plan 011
-- 012-admin-console: stage=50-verify | approval=Approved | next=60-report 012 | warnings: not ready for release
-
-Recommended Next Action:
-- 010 -> 50-verify 010
-- 011 -> 20-spec 011
-- 012 -> 40-execute 012
-```
-
-### Phase C: Manual Review Soft Gate
-
-Help should not hard-block stage progression.
-Help should warn when a stage artifact still shows:
-
-- `Approval Status: Pending`
-- `Approval Status: Needs Revision`
-- missing `Next Allowed Command`
-
-When one of those conditions exists, Help should:
-
-1. say that manual review still appears open
-2. recommend the reviewer inspect the current stage artifact first
-3. suggest the next command only as a soft recommendation, not as an automatic jump
-4. prefer checklist approval gates and stage `Next Allowed Command` when both exist, and call out disagreements explicitly
-
-Typical warning shape:
-
-```text
-Manual Review Warning:
-- 014 -> 20-spec.md still shows Approval Status: Pending
-- Recommended action: review 20-spec.md and confirm the next allowed command before moving to 30-plan 014
-```
-
-## DevFlow 2.0 Mainline
-
-```text
-00-discover -> 10-define -> 20-spec -> 30-plan -> 40-execute -> 50-verify -> 60-report -> 70-release
-```
-
-## Public Companion Commands
-
-These are not numbered stages and may be called directly by users:
-
-- `Goal`
-- `Brainstorm`
-- `Research`
-- `Debug`
-- `PRD`
-- `Issue-Triage`
-- `Security-Review`
-- `Wiki`
-- `Check-For-Updates`
-- `Help`
-
-## Internal Companion Surfaces
-
-These files still exist because their prompt bodies contain useful behavior, but they are not the preferred public entry points:
-
-- `Preview`
-- `Simplify`
-- `Spec-Research`
-- `Competitor`
-- `Roadmap`
-- `Spec-Orchestrate`
-- `Test`
-- `QA-Orchestrate`
-- `Followup`
-- `Human-Approve`
-- `Human-Feedback`
-- `Human-ReCheck`
-- `Human-Reject`
-- `Commit`
-- `PR`
-- `PR-Review`
-- `PR-Followup`
-- `Merge`
-- `Deploy`
-- `Changelog`
-- `Insight`
-- `Agent`
-
-## Routing Rules
-
-### 1. If the user is just starting
-
-Recommend `00-discover`. Discover selects `Brainstorm`, `PRD`, `Research`, `Debug`, or direct decision and owns the return synthesis.
-If the request is large, high-risk, multi-phase, or requirement-heavy, explain that the run should use the manual review flow with explicit human approval at each stage.
-
-### 2. If an approved discovery needs delivery boundaries
-
-Recommend `10-define {discovery_id}` so Define can create one or more Running IDs.
-
-If the go/no-go decision is not approved, return to `00-discover {discovery_id}` instead.
-
-### 3. If the task is already defined and needs requirements
-
-Recommend `20-spec`.
-
-### 4. If requirements already exist and implementation planning is next
-
-Recommend `30-plan`.
-
-### 5. If planning is done and work should begin
-
-Recommend `40-execute`.
-
-### 6. If implementation exists and needs checking
-
-Recommend `50-verify`.
-
-### 7. If work is done and needs a final human-friendly summary before release
-
-Recommend `60-report`.
-
-### 8. If the work needs packaging or release handling after the report is aligned
-
-Recommend `70-release`.
-
-## General Q And A Role
-
-Help should:
-
-- answer questions about the project, framework, commands, agents, and prompts
-- recommend which public workflow, public companion command, or agent should be used next
-- clarify the current 2.0 stage model and companion-command model
-- explain when the manual review flow is the safer choice
-- provide example prompts for other workflows or agents
-
-When the user lacks context or the problem is unclear, Help may recommend `Research`, `Brainstorm`, or `Debug` instead of pretending the route is obvious.
-
-## Legacy Transition Notes
-
-The following are legacy concepts in DevFlow 2.0:
-
-- dashboard-first task flow
-- JSON-first task contracts
-- numbered utility workflows that are not true stage states
-
-Legacy aliases are no longer part of the active command surface.
-
-If a user mentions a removed legacy command, Help should:
-
-1. state that the legacy alias has been retired
-2. recommend the current 2.0 stage or companion command
-3. continue the conversation using only the current command name
-
-If a user mentions an internal companion surface, Help should:
-
-1. explain that it is an internal support surface in DevFlow 2.0
-2. recommend the public command or mainline stage that should normally be used instead
-3. mention the internal surface only when the user is intentionally doing framework-level or advanced workflow work
-
-## Relationship To DevFlow 2.0
-
-- Classification: Companion command
-- Mainline status: Routing and explanation command, not a numbered stage
-- Typical entry points: whenever the next step is unclear
-- Typical handoff targets: any mainline stage or companion command that best matches the current state
-
-## Sources
-
-- `AGENTS.md`
-- `docs/workspace-artifacts.md`
-- Related commands: all mainline stages, `Brainstorm`, `Research`, `Debug`, `Wiki`, `Agent`, `Goal`
-
-## Next Workflow Recommendation
-
-- **Primary**: the workflow or companion command that best matches the user's current state
-- **Why**: `Help` is the routing and coaching entry point for people and agents
-- **Alternatives**:
-  - `Goal "{goal}"` for broad goals that need decomposition and routing
-  - `Wiki query {framework|project|all} "{question}"` when the user needs accumulated knowledge
-

package/template/.agents/skills/i18n-localization/SKILL.md

@@ -1,154 +0,0 @@
----
-name: i18n-localization
-description: "[Devflow] Internationalization and localization patterns. Detecting hardcoded strings, managing translations, locale files, RTL support."
-allowed-tools: Read, Glob, Grep
----
-
-# i18n & Localization
-
-> Internationalization (i18n) and Localization (L10n) best practices.
-
----
-
-## 1. Core Concepts
-
-| Term | Meaning |
-|------|---------|
-| **i18n** | Internationalization - making app translatable |
-| **L10n** | Localization - actual translations |
-| **Locale** | Language + Region (en-US, tr-TR) |
-| **RTL** | Right-to-left languages (Arabic, Hebrew) |
-
----
-
-## 2. When to Use i18n
-
-| Project Type | i18n Needed? |
-|--------------|--------------|
-| Public web app | ✅ Yes |
-| SaaS product | ✅ Yes |
-| Internal tool | ⚠️ Maybe |
-| Single-region app | ⚠️ Consider future |
-| Personal project | ❌ Optional |
-
----
-
-## 3. Implementation Patterns
-
-### React (react-i18next)
-
-```tsx
-import { useTranslation } from 'react-i18next';
-
-function Welcome() {
-  const { t } = useTranslation();
-  return <h1>{t('welcome.title')}</h1>;
-}
-```
-
-### Next.js (next-intl)
-
-```tsx
-import { useTranslations } from 'next-intl';
-
-export default function Page() {
-  const t = useTranslations('Home');
-  return <h1>{t('title')}</h1>;
-}
-```
-
-### Python (gettext)
-
-```python
-from gettext import gettext as _
-
-print(_("Welcome to our app"))
-```
-
----
-
-## 4. File Structure
-
-```
-locales/
-├── en/
-│   ├── common.json
-│   ├── auth.json
-│   └── errors.json
-├── tr/
-│   ├── common.json
-│   ├── auth.json
-│   └── errors.json
-└── ar/          # RTL
-    └── ...
-```
-
----
-
-## 5. Best Practices
-
-### DO ✅
-
-- Use translation keys, not raw text
-- Namespace translations by feature
-- Support pluralization
-- Handle date/number formats per locale
-- Plan for RTL from the start
-- Use ICU message format for complex strings
-
-### DON'T ❌
-
-- Hardcode strings in components
-- Concatenate translated strings
-- Assume text length (German is 30% longer)
-- Forget about RTL layout
-- Mix languages in same file
-
----
-
-## 6. Common Issues
-
-| Issue | Solution |
-|-------|----------|
-| Missing translation | Fallback to default language |
-| Hardcoded strings | Use linter/checker script |
-| Date format | Use Intl.DateTimeFormat |
-| Number format | Use Intl.NumberFormat |
-| Pluralization | Use ICU message format |
-
----
-
-## 7. RTL Support
-
-```css
-/* CSS Logical Properties */
-.container {
-  margin-inline-start: 1rem;  /* Not margin-left */
-  padding-inline-end: 1rem;   /* Not padding-right */
-}
-
-[dir="rtl"] .icon {
-  transform: scaleX(-1);
-}
-```
-
----
-
-## 8. Checklist
-
-Before shipping:
-
-- [ ] All user-facing strings use translation keys
-- [ ] Locale files exist for all supported languages
-- [ ] Date/number formatting uses Intl API
-- [ ] RTL layout tested (if applicable)
-- [ ] Fallback language configured
-- [ ] No hardcoded strings in components
-
----
-
-## Script
-
-| Script | Purpose | Command |
-|--------|---------|---------|
-| `scripts/i18n_checker.py` | Detect hardcoded strings & missing translations | `python scripts/i18n_checker.py <project_path>` |