@jakkrichm/create-nexus-devflow 2.0.0

package/template/.agents/skills/10-define/SKILL.md

@@ -0,0 +1,170 @@
+---name: 10-define
+
+description: Define stage in DevFlow 2.0 - turn an approved discovery into one or more bounded delivery runs with stable scope.
+argument-hint: "{approved discovery-id, discovery path, running-id, or run path}"
+---
+
+# Phase 10: Define
+
+$ARGUMENTS
+
+Convert an approved `Proceed` discovery into bounded delivery slices. Allocate one Running ID per independently specifiable and reviewable slice, then write one `10-define.md` contract per generated run. This is the first stage that creates Running IDs.
+
+## Usage
+
+```text
+/10-Define {discovery-id or discovery path}
+/10-Define {running-id or run path}
+```
+
+Use a Discovery ID to materialize new delivery runs. Use an existing Running ID only to revise or split a definition that already exists.
+
+## Markdown-First Contract
+
+For every approved delivery slice, write:
+
+```text
+devflow/runs/{ID}-{slug}/10-define.md
+```
+
+using:
+
+```text
+.agent/resources/schemas/define.template.md
+```
+
+Before writing any `10-define.md`, read `artifact_language` from `define.template.md` and produce every generated artifact in that language.
+
+## Required Section Content
+
+Before completing any generated artifact:
+
+- preserve every heading required by the selected template
+- write concrete information under every heading
+- when no information exists or the section does not apply, write exactly `-`
+- never leave a heading immediately followed by another heading with no body content
+- remove template placeholders from the final artifact
+- do not invent facts merely to avoid using `-`
+- re-read the saved artifact and verify every heading satisfies this rule
+
+## Process
+
+### Loop Contract
+
+Run definition as a scope-stabilization and run-allocation loop.
+
+- **Intent**: turn an approved discovery into the smallest coherent set of delivery runs that can each be specified, planned, implemented, and verified without carrying the entire initiative context.
+- **Context**: read the approved `00-discover.md`, linked Brainstorm/PRD/Research/Debug outputs, project-wide rules, existing run IDs, and dependencies between candidate slices.
+- **Action**: lock initiative and scope boundaries, decompose delivery slices, review the run map, allocate collision-free Running IDs, and write one `10-define.md` per slice.
+- **Observation**: use independent acceptance boundaries, release boundaries, ownership, dependencies, context size, cross-domain coupling, and reviewability as evidence for splitting or combining slices.
+- **Adjustment**: merge slices that are only implementation tasks; split slices that require separate specs, releases, ownership, or large independent context; return to `/00-Discover` if the decision or product direction is still unstable.
+- **Stop Condition**: stop when the run map is approved, IDs are materialized without collision, each run has stable in/out scope, and every generated run can proceed independently to `/20-Spec {running_id}`.
+- **Handoff**: each `10-define.md` must identify its source Discovery ID, sibling runs, dependencies, scope, non-goals, and exact next command.
+
+### 1. Validate The Discovery Gate
+
+For new delivery work, require:
+
+- `Decision: Proceed`
+- `Approval Status: Approved`
+- a resolvable Discovery ID and `00-discover.md`
+
+If either gate is missing, do not create a Running ID. Return to `/00-Discover {discovery_id}`.
+
+### 2. Build The Delivery Run Map
+
+Define candidate slices around coherent delivery outcomes, not small tasks.
+
+Create separate runs when work has materially independent:
+
+- acceptance or verification boundaries
+- release or rollback boundaries
+- domain context or ownership
+- dependency sequencing
+- implementation context large enough to threaten reliable planning or review
+
+Keep ordinary subtasks inside `/30-Plan` and checklists.
+
+For every slice record:
+
+- title and slug
+- outcome and scope boundary
+- exclusions
+- dependencies
+- shared project constraints
+- reason it deserves one Running ID
+
+### 3. Review Before Allocation
+
+Present the proposed run map for human review before consuming numeric IDs when the split is large, disputed, or high risk. A single clear slice may proceed directly when approval is already explicit.
+
+### 4. Allocate Running IDs
+
+- inspect `devflow/runs/` immediately before allocation
+- choose sequential IDs after the highest existing numeric Running ID
+- never reuse a gap merely because it is available
+- create each target directory immediately to reserve it
+- recheck for collisions before writing artifacts
+- if any collision occurs, stop, rescan, and allocate a fresh contiguous range
+
+One invocation may create one or many Running IDs. Record the complete allocation back into the source discovery's `related_runs` and allocated-run section.
+
+### 5. Write One `10-define.md` Per Run
+
+- preserve template headings
+- set `source_discovery`
+- identify sibling runs and dependencies
+- carry forward only the project context needed by this slice
+- make scope, non-goals, assumptions, and success criteria explicit
+- keep implementation tasks out of Define
+
+### 6. Split An Existing Run When Necessary
+
+If an existing definition is too broad:
+
+- propose a replacement run map
+- preserve traceability to the original run and discovery
+- allocate new IDs only after approval
+- mark the old definition as `Superseded` and list its replacement runs
+- do not silently fork scope during `/20-Spec`
+
+### 7. Manual Review Gate
+
+Before recommending `/20-Spec`, confirm each generated definition independently. Approval of one run must not imply approval of every sibling run.
+
+## Output
+
+Report:
+
+- source Discovery ID
+- proposed and allocated run map
+- workspace path for every generated run
+- scope and dependency summary per run
+- any superseded run
+- exact `/20-Spec {running_id}` commands for approved runs
+
+## Relationship To DevFlow 2.0
+
+- Classification: Mainline workflow and Running ID creation boundary
+- Previous state: approved `/00-Discover`
+- Next state: `/20-Spec {running_id}` per generated run
+- Running ID lifecycle: starts here
+
+## Sources
+
+- `AGENTS.md`
+- `docs/workspace-artifacts.md`
+- `.agent/resources/schemas/define.template.md`
+
+## Next Workflow Recommendation
+
+- **Primary**: `/20-Spec {running_id}` for each approved run
+- **Alternatives**:
+  - `/00-Discover {discovery_id}` when the go/no-go decision or direction is unstable
+  - `Research {discovery_id}` when evidence still blocks a reliable split
+  - `grill-with-docs` when boundaries or terminology remain ambiguous
+
+## Nexus Event
+
+- Use `domain-modeling` when sibling runs need shared language or durable architectural decisions.
+- Use `planning-and-task-breakdown` only after the delivery boundary is stable; small tasks belong in `/30-Plan`, not separate Running IDs.

package/template/.agents/skills/20-spec/SKILL.md

@@ -0,0 +1,156 @@
+---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.
+
+## Required Section Content
+
+Before completing any generated artifact:
+
+- preserve every heading required by the selected template
+- write concrete information under every heading
+- when no information exists or the section does not apply, write exactly `-`
+- never leave a heading immediately followed by another heading with no body content
+- remove template placeholders from the final artifact
+- do not invent facts merely to avoid using `-`
+- 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.
+- **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.
+- **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`
+- 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
+
+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.
+

package/template/.agents/skills/30-plan/SKILL.md

@@ -0,0 +1,221 @@
+---name: 30-plan
+
+description: Plan implementation in DevFlow 2.0 - transform `20-spec.md` into a markdown-first executable plan.
+---
+# Phase 30: Plan Implementation
+
+**Strict mode: planning only. Do not edit source code in this phase.**
+
+Create a codebase-informed implementation plan using `30-plan.md` as the primary artifact in DevFlow 2.0.
+
+## Usage
+
+```text
+/30-Plan {ID}
+```
+
+## Markdown-First Contract
+
+Use `30-plan.md` as the main planning artifact.
+
+Use controlled task-engine commands when plan status or subtask tracking must be synchronized:
+
+Record complexity, context, phases, subtasks, and validation notes directly in the stage markdown files for this running ID. Treat `30-plan.md` as the source of truth.
+
+**MANDATORY RULE:** If you create temporary script files (e.g. `.ps1`, `.sh`) to execute multiple compatibility commands in batch, save them inside the task workspace, never in the central `scripts/` directory.
+
+## Required Section Content
+
+Before completing any generated artifact:
+
+- preserve every heading required by the selected template
+- write concrete information under every heading
+- when no information exists or the section does not apply, write exactly `-`
+- never leave a heading immediately followed by another heading with no body content
+- remove template placeholders from the final artifact
+- do not invent facts merely to avoid using `-`
+- re-read the saved artifact and verify every heading satisfies this rule
+
+## Process
+
+### Loop Contract
+
+Run planning as an evidence loop, not as a one-shot outline.
+
+- **Intent**: produce a plan that lets implementation proceed without guessing scope, files, risks, or verification.
+- **Context**: read the spec, prior stage artifacts, relevant code/docs, existing commands, and any research that constrains execution.
+- **Action**: draft the smallest useful plan, then inspect whether every phase has files, dependencies, risks, verification, and a test decision.
+- **Observation**: use concrete evidence such as file paths, existing patterns, package scripts, validation commands, and unresolved assumptions.
+- **Adjustment**: if evidence is missing, search/read more, recommend `Research` or `Agent codebase-explorer`, split the work, or route back to `/20-Spec` when the contract is not plan-ready.
+- **Stop Condition**: stop only when phases are ordered, subtasks are scoped, verification is explicit, test decisions are recorded, and any blockers are visible.
+- **Handoff**: `30-plan.md` must give `/40-Implement` enough context to select one scoped unit and execute it without inventing intent.
+
+### 1. Read Task Artifacts
+
+Read:
+
+- `devflow/runs/{ID}-*/20-spec.md`
+- `10-define.md` and the shared `00-discover.md` referenced by `source_discovery` when they help clarify intent
+
+### 2. Assess Complexity
+
+Use the old planning discipline:
+
+- `simple`: 1 phase, 1-3 subtasks
+- `standard`: multiple ordered phases with clear verification
+- `complex`: deeper codebase exploration, possibly specialist help
+
+If architecture or data flow is still unclear, recommend `Research` or `Agent codebase-explorer` before pretending the plan is stable.
+If domain terms, boundaries, or hard-to-reverse design choices are still questionable, use `grill-with-docs` before locking the plan.
+Use `codebase-design` when phases depend on seam placement or module interfaces. Use `tdd` when behavior-change subtasks need red-green-refactor test cases.
+
+### 3. Explore Codebase Patterns
+
+Use fast searches (`rg`, file reads) to find:
+
+- similar implementations
+- entry points
+- config and test commands
+- files likely to change
+- patterns that implementation should mirror
+
+Record important findings in `30-plan.md`. Use legacy context updates only when compatibility tooling still needs them.
+
+### 4. Build The Plan
+
+Use the old planner discipline, but keep `30-plan.md` as the main contract:
+
+- record the planning loop evidence: context read, observations, adjustments made, stop condition, and handoff notes
+- add phases in dependency order
+- add subtasks that are small, verifiable units
+- include explicit files to modify or create
+- include patterns to follow
+- include verification command or manual check
+- include a test decision for every subtask
+- record assumptions, scope boundaries, and risks explicitly
+
+Each subtask should answer:
+
+- what to change
+- where to change it
+- which pattern to follow
+- how to verify it
+- whether automated tests are required, manual, or not required
+
+### 4.1 Test Decision Gate
+
+**STRICT MANDATE (กฎเหล็ก Unit Test)**: สำหรับทุก subtask ที่มีการเพิ่ม แก้ไข หรือเปลี่ยนแปลงการทำงานของโค้ด (Behavior Change) **ต้องระบุเป็น `Required` เสมอ** ห้ามละเว้นเด็ดขาด ยกเว้นงานประเภทเอกสารหรือแก้ไข Configuration เท่านั้น
+
+For every subtask, decide one of:
+
+- `Required`: automated tests must be created or updated (Mandatory for all behavior changes)
+- `Manual/Command Only`: verification is non-test but still explicit (Only for configuration/infrastructure tasks)
+- `Not Required`: no new automated test is needed because there is no meaningful behavior surface (Only for documentation/comments)
+
+Record:
+
+- reason
+- planned cases when tests are required (using AAA pattern: Arrange-Act-Assert)
+- verification command or manual check
+- expected result
+
+Do not use "too simple" as the only reason for skipping tests.
+
+### 5. Create Human-Readable Plan
+
+Create `30-plan.md` in the task workspace and base its structure on:
+
+```text
+.agent/resources/schemas/plan.template.md
+```
+
+Before writing `30-plan.md`, read `artifact_language` from `plan.template.md` and produce the artifact in that language.
+
+Before reporting completion:
+
+Review `{plan_md_path}` against `plan.template.md`, keep the required headings, and remove placeholder text before completion.
+
+Replace every placeholder with concrete phases, files, commands, dependencies, and verification evidence.
+Follow the `artifact_language` configured in `plan.template.md` for all plan narrative text.
+
+Create the checklist directory when detailed execution tracking is needed:
+
+```text
+devflow/runs/{ID}-*/checklists/
+```
+
+Seed at least:
+
+- `implementation-checklist.md`
+- `verification-checklist.md`
+
+Use the schema templates under `.agent/resources/schemas/` and turn approved phases/subtasks into live markdown checklist items using task markers such as `- [ ]`, `- [/]`, `- [!]`, and `- [-]` so humans can follow the run without reading the full planning narrative.
+
+### 6. Validate And Close Planning
+
+Run:
+
+Run `npm run validate` after changing the framework, templates, or shared references. For task work, manually verify that `30-plan.md` still matches the required template contract.
+
+If validation fails, repair only what is necessary and keep `30-plan.md` aligned with the corrected state.
+
+### 7. Manual Review Soft Gate
+
+Before recommending `/40-Implement`, check whether the plan still shows pending review.
+If `Approval Status` is still pending or major dependencies remain unresolved:
+
+- warn that implementation should wait for review
+- recommend human confirmation of sequencing, scope, and verification strategy
+- keep `/40-Implement` as a soft recommendation only
+
+## Output Checklist
+
+- complexity is clear
+- loop evidence is recorded: intent, context, observation, adjustment, stop condition, and handoff
+- phases are ordered by dependency
+- every subtask is scoped and verifiable
+- every subtask has a test decision
+- `30-plan.md` is written and reviewable
+- validation passes
+- manual review warning is explicit when approval is still pending
+- next command is ready
+
+## Relationship To DevFlow 2.0
+
+- Classification: Mainline workflow
+- Previous state: `/20-Spec`
+- Next state: `/40-Implement` when execution steps and verification are clear
+- Common companion commands: `Research` or `Agent` when architecture, data flow, or external constraints still need investigation; support skills: `grill-with-docs`, `domain-modeling`, `codebase-design`, `tdd`, and `to-issues` for final design stress-testing, durable terminology capture, test planning, and issue packaging
+
+## Sources
+
+- `AGENTS.md`
+- `docs/workspace-artifacts.md`
+- `.agent/resources/schemas/plan.template.md`
+- Related commands: `/20-Spec`, `Research`, `Agent`, `/40-Implement`
+
+## Next Workflow Recommendation
+
+- **Primary**: `/40-Implement {ID}`
+- **Why**: Approved planning is the gate before implementation in DevFlow 2.0.
+- **Alternatives**:
+  - `Research` - choose this when the plan still depends on missing evidence.
+  - `Agent codebase-explorer devflow/runs/{ID}-*/` - choose this when architecture or data flow is unclear.
+  - `grill-with-docs` - choose this when plan assumptions or design boundaries need one last adversarial pass.
+  - `codebase-design` - choose this when a plan needs clearer seams, interfaces, or test surfaces.
+  - `/20-Spec {ID}` - choose this when the spec itself is not strong enough for planning.
+
+## Nexus Event
+
+- Use `Research` when architecture, sequencing, or rollout decisions still depend on missing evidence.
+- Use `Agent codebase-explorer` or another specialist lane when the codebase shape or integration boundary is still unclear.
+- Use `grill-with-docs` when available if a short clarification pass could materially change sequencing, dependency order, rollout risk, or verification strategy.
+
+## Wiki Update Recommendation
+
+- **Needed**: `yes` when planning records a reusable architecture decision, project pattern, or context-loading lesson.
+- **Scope**: `project` unless the planning lesson changes DevFlow framework behavior.
+- **Reason**: Plans often discover stable patterns that future sessions should reuse.
+- **Suggested Command**: `Wiki project ingest devflow/runs/{ID}-*/30-plan.md`
+
+