@jakkrichm/create-nexus-devflow 2.2.0 → 2.2.1

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

@@ -1,166 +1,91 @@
 ---
 name: discovery
-description: "[devflow][B] Optional deep, multi-turn project discovery that helps the user develop detailed Blueprint project-plan.md and build-plan.md files through an adaptive conversation, then drafts them only after the user says they are ready. Use when the user explicitly runs /discovery or $discovery, asks for a guided planning interview, wants to think through a new product before writing the plans, or wants help deepening existing plans. Do not use merely because planning files are empty, after /onboard, or before /overview; users may always write the plans directly or create them through any conversation they prefer."
+description: "[devflow][D] Unified discovery and exploration stage in DevFlow 2.0 - conducts project-level roadmap discovery (project-plan.md/build-plan.md) or feature-level exploration (Stage 00) before delivery commitment."
+argument-hint: "[{title, request, IDEA-xxx, or discovery-id}]"
 ---
 
-# discovery - develop the plans through a deep conversation
+# discovery - Unified Discovery & Pre-Delivery Exploration
 
-Where this can sit in the workflow:
+$ARGUMENTS
 
-    /onboard  ->  write the plans directly  ->  /overview
-              \
-               ->  [discovery]  ->  review and approve plan drafts  ->  /overview
+`/discovery` is the central discovery entry point in Nexus-DevFlow. It operates in two adaptive modes based on input scope:
+1. **🗺️ Macro Project Discovery**: Develops high-level product and build roadmap plans (`devflow/project-plan.md` & `devflow/build-plan.md`) through an adaptive conversation before `/overview`.
+2. **🔍 Micro Feature Exploration (Stage 00)**: Explores a specific feature, request, or idea before committing to delivery, routes through supporting lenses, and finishes with a visible `Proceed`, `Defer`, or `Reject` decision before `10-define`.
 
-`/discovery` is an optional planning partner, not a required workflow gate and
-not a quick questionnaire. It can span as many turns as the project needs. Its
-job is to help the user think through the product, preserve the depth and nuance
-of that conversation, and draft the two user-owned planning files only when the
-user asks for drafts.
+---
+
+## Invocations & Usage
 
-Running `/onboard` never starts this skill. Empty plans never require it. A user
-who writes detailed plans manually, has another AI conversation, or arrives with
-finished plans continues directly to `/overview` exactly as before.
+```text
+# 1. Macro Project Planning Mode (No arguments or project scope)
+/discovery
+/discovery --project
 
-## Step 1 - establish the starting point
+# 2. Micro Feature Exploration Mode (Stage 00 of Deep-Track)
+/discovery {title or request}
+/discovery IDEA-xxx
+/discovery {discovery-id}
+```
 
-Read only the planning and project facts needed for the conversation:
+---
 
-- `devflow/project-plan.md`
-- `devflow/build-plan.md`
-- the root project manifest, README, and framework configuration when they
-  already contain relevant facts
-- `devflow/context/project-overview.md` only when the user is revisiting an
-  established project's direction
+## Mode 1: Macro Project Discovery (Roadmap & System Planning)
 
-Classify each planning file as a template, partial draft, or substantive plan.
-Never treat existing user content as disposable. When either plan has real
-content, summarize what it already establishes and ask whether the user wants to
-deepen it, revise a specific direction, or use it unchanged as conversation
-context. Do not replace it with a fresh generic plan.
+Use when:
+- Starting a new product or shaping high-level architecture across the entire repository.
+- Revisiting the overall project vision, major milestones, or tech stack before generating `/overview`.
 
-Start with a short working hypothesis about the project and name the most
-important unknown. Then ask one focused question. Do not draft either plan yet.
+### Process:
+1. **Establish Baseline**: Read `devflow/project-plan.md` and `devflow/build-plan.md` (if present).
+2. **Adaptive Conversation**: Ask 1-2 focused questions at a time covering problem space, user workflows, MVP boundaries, non-goals, data models, and stack constraints.
+3. **Periodic Snapshots**: Provide compact summaries of confirmed decisions, working assumptions, and open TODOs.
+4. **Draft Plans Behind Approval Gate**: Draft proposed `project-plan.md` and `build-plan.md` only when the user explicitly requests drafts.
+5. **Write on Approval**: Write approved files and recommend `/overview` as the next step.
 
-## Step 2 - run adaptive discovery
+---
+
+## Mode 2: Micro Feature Exploration (Stage 00 of Deep-Track)
+
+Use when:
+- Exploring a specific feature, complex architectural change, or pending idea (`/discovery IDEA-xxx`).
+- The team needs to evaluate feasibility, options, domain glossary, or root causes before locking delivery scope.
+
+### Markdown-First Contract:
+Write the primary discovery artifact to:
+```text
+devflow/discoveries/{DISCOVERY_ID}-{slug}/discovery.md
+```
+*(A Discovery ID uses the namespace `DISC-YYYYMMDD-NNN`. It is not a Running ID and does not reserve a numeric delivery run.)*
+
+### 5 Supporting Routes & Built-in Lenses:
+
+1. **Brainstorming Lens (Divergent & Convergent)**:
+   - Formulate 2-3 viable options with trade-offs.
+   - Construct a **Trade-off Comparison Table** (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.
+3. **PRD & Scoping Lens**:
+   - Problem Statement, Target Persona, Core User Stories, and In-Scope vs. Out-of-Scope boundaries.
+4. **Issue & Bug Triage Lens**:
+   - Classify severity (`Critical/Blocker`, `Major`, `Minor`) and determine whether root-cause analysis (`debug`) is required.
+5. **Socratic Grilling & Domain Alignment Lens (`grill`)**:
+   - Codebase-grounded interactive inquiry to clarify entity boundaries, data flows, and edge cases.
+   - Record agreed terminology in `devflow/context/glossary.md` and major architecture decisions in `devflow/decisions/ADR-xxx-{slug}.md`.
+
+### Decision & Approval Gate:
+Set one visible decision:
+- `Proceed`: Enough value and evidence exist to define delivery work:
+  - **🏎️ Fast-Track (Recommended for 85% of standard features/fixes)**: Handoff to `/feature {discovery_id}` or `/fix {discovery_id}` (writes `devflow/context/current-feature.md`).
+  - **🏗️ Deep-Track (For large architectural epics/migrations)**: Handoff to `10-define {discovery_id}` (writes `devflow/context/current-run/10-define.md`).
+- `Defer`: The idea remains relevant but timing or evidence is not ready.
+- `Reject`: The idea should not proceed under current framing.
+
+---
 
-Ask one meaningful question at a time and let each answer shape the next one.
-Prefer a likely interpretation the user can correct over a vague request for
-more detail. Explain a tradeoff when the answer would materially change scope,
-architecture, cost, or build order.
+## Next Workflow Recommendations
 
-Cover the areas that matter to this project, not a fixed questionnaire:
-
-- problem, desired outcome, and why the project should exist
-- target users, their context, and their primary workflows
-- MVP capabilities, explicit non-goals, and later possibilities
-- business rules, data, integrations, permissions, and important edge cases
-- stack choices, constraints, dependencies, and technical unknowns
-- UI/UX direction, accessibility needs, and useful references
-- monetization or business model when relevant
-- deployment shape, environments, background work, storage, and operations
-- risks, assumptions, unresolved decisions, and how success will be judged
-- feature boundaries, dependencies, and a sensible build order
-
-Depth is the goal. Follow a consequential answer until its implications are
-clear instead of racing to the next category. Do not ask the user to repeat facts
-already established in the conversation or repository. Do not force irrelevant
-topics merely to complete a checklist.
-
-Periodically return a compact discovery snapshot with:
-
-- confirmed decisions
-- working assumptions that still need confirmation
-- open questions or conflicts
-- ideas explicitly deferred or excluded
-
-The snapshot keeps a long conversation coherent. It is not permission to write
-the plans.
-
-## Step 3 - decide whether the plans are ready
-
-Do not end discovery because a preset number of questions has been reached. It
-is ready to draft when:
-
-- the problem, users, and core workflows are concrete
-- MVP scope and non-goals are distinguishable
-- data and technical choices are detailed enough to expose major dependencies
-- the build order can be expressed as feature-sized outcomes
-- important contradictions are resolved
-- remaining unknowns are either safe to defer or explicitly accepted as TODOs
-- the user says they are ready for the plans to be drafted
-
-If the user asks for drafts while a material gap remains, name the gap and ask
-whether to continue discovery or preserve it as an explicit TODO. Respect the
-choice. The user may also stop at any time and write the plans manually.
-
-## Step 4 - draft both planning files
-
-When the user asks for drafts, produce complete proposed contents for both files
-without writing them yet.
-
-For `devflow/project-plan.md`:
-
-- keep the template's main subject areas, adding useful sections when the
-  conversation requires them
-- preserve rationale, examples, tradeoffs, constraints, edge cases, and
-  exclusions that will matter during later feature work
-- be as detailed as the project needs; never compress a rich discovery into a
-  line or two per section
-- distinguish confirmed decisions from assumptions and TODOs
-
-For `devflow/build-plan.md`:
-
-- use numbered checkboxes and optional milestone headings
-- keep each item a high-level, feature-sized outcome with a concise description
-- order items by dependency and the earliest useful vertical slice
-- keep implementation detail in later `/feature` specs rather than turning the
-  roadmap into a task dump
-- include only agreed scope; place deferred ideas outside the MVP or omit them as
-  the user directed
-
-If substantive plans already exist, preserve their information and completed
-build-plan numbering. Clearly identify proposed additions, removals, or changed
-decisions.
-
-End by asking the user to review the full drafts. Do not write either file in the
-same response that first presents them.
-
-## Step 5 - write only after approval
-
-Write the approved drafts only after the user explicitly approves them. If the
-user requests changes, revise the drafts and show the affected sections again
-before writing.
-
-After writing:
-
-- report which files changed
-- list any retained TODOs or unresolved decisions
-- remind the user that both files remain theirs to edit and deepen directly
-- stop before generating `devflow/context/project-overview.md`
-- point to `/overview` or `$overview` as the next optional command when the user
-  is satisfied with the plans
-
-## Rules
-
-- This skill is always optional. Never make it a prerequisite for `/overview`,
-  `/feature`, or any other Blueprint command.
-- Never start it automatically from `/onboard`, because planning files are
-  empty, or because a project is new.
-- Never imply that plans created manually or through another conversation are
-  inferior or incomplete merely because this skill was not used.
-- Never overwrite substantive planning content without showing the replacement
-  and receiving explicit approval.
-- Never write plans during the interview or after a vague signal such as "looks
-  good." The user must explicitly approve the proposed file contents.
-- Never scaffold the app, edit product code, generate the overview, create a
-  feature spec, commit, merge, push, or deploy.
-- Preserve detailed project reasoning in `project-plan.md`, while keeping
-  `build-plan.md` high-level and trackable.
-- Keep the conversation adaptive. Depth comes from relevant follow-up questions,
-  not from mechanically asking every possible question.
-
-## Formatting
-
-Follow `devflow/context/ai-interaction.md`. During discovery, ask one focused
-question per turn. For snapshots and draft reviews, use concise headings and
-lists so confirmed decisions and remaining gaps are easy to inspect.
+- **From Macro Project Mode**: Run `/overview` to compile context into `devflow/context/project-overview.md`.
+- **From Micro Stage 00 (Approved Proceed ➔ Fast-Track)**: Run `/feature {discovery_id}` to start lean living spec.
+- **From Micro Stage 00 (Approved Proceed ➔ Deep-Track)**: Run `10-define {discovery_id}` to allocate a Running ID.
+- **From Micro Stage 00 (Defer / Reject)**: No next command needed.

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

@@ -32,6 +32,7 @@ big item has been split into sub-items, the next unchecked sub-item is the targe
 
 ## Step 1 - pick the target
 
+- Given a Discovery ID or Idea ID (e.g. `/feature DISC-20260824-001` or `/feature IDEA-001`) -> import problem context, research, trade-offs, and ADRs from `devflow/discoveries/{DISC-ID}/discovery.md` or `devflow/ideas.md` into the living spec.
 - Given a number or name that matches a build-plan item -> use it.
 - Given a request that clearly describes a new feature with no reasonable match
   in the build plan -> follow **New-feature intake** below.

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

@@ -0,0 +1,93 @@
+---
+name: grill
+description: "[devflow][B] Interactive Socratic alignment & domain modeling - stress-test plans, extract domain glossary, and record architecture decision records (ADRs) before delivery."
+argument-hint: "{topic, plan, or question}"
+---
+
+# grill - Socratic Alignment & Domain Modeling
+
+$ARGUMENTS
+
+Use this skill to conduct a codebase-grounded, interactive Socratic interview with the user. It clarifies domain vocabulary, resolves architectural ambiguities, and prevents misalignment before writing specifications or code.
+
+## Invocations & Aliases
+
+- `/grill {topic or plan}`: Standard slash command in Claude Code, Google Antigravity, and Gemini CLI
+- `grill {topic or plan}`: Plain text invocation
+- `$grill {topic or plan}`: Codex CLI invocation
+- `/align {topic}`: Alias for domain alignment
+
+## Core Philosophy: Align Before You Build
+
+1. **Codebase-Grounded**: Read existing code and context first. Never ask questions the codebase can already answer.
+2. **One Round at a Time**: Ask 1-2 focused, high-leverage questions per round with clear recommended defaults. Never dump a wall of 10 questions.
+3. **Lazy Inline Persistence**:
+   - Write agreed domain terminology to `devflow/context/glossary.md` the moment each term resolves.
+   - Record significant, hard-to-reverse technical decisions as ADRs in `devflow/decisions/ADR-xxx-{slug}.md`.
+4. **Zero Assumptions**: Challenge ambiguities, contradictory requirements, and naming inconsistencies upfront.
+
+---
+
+## Process & Execution Loop
+
+### 1. Grounding Phase (Silent Inspection)
+Before asking the first question:
+- Read `devflow/context/project-overview.md` and `devflow/context/coding-standards.md`.
+- Inspect existing domain terms in `devflow/context/glossary.md` (if present).
+- Search codebase patterns (`grep_search` / `rg`) related to the topic to ground technical reality.
+
+### 2. Interactive Socratic Interview Loop
+In each turn:
+- Identify the most critical unresolved branch in the design tree:
+  - **Domain Language & Boundaries**: "What exactly is an Entity X versus Entity Y in this context?"
+  - **Data Flow & Contracts**: "Who owns state X? Synchronous vs. asynchronous?"
+  - **Edge Cases & Failure Modes**: "What happens on network failure, concurrent mutation, or invalid input?"
+  - **Irreversible Trade-offs**: "Database schema change vs. application-layer adapter?"
+- Ask **1-2 questions maximum** per turn.
+- Always provide a recommended default with concise technical rationale.
+- Wait for the user's answer.
+
+### 3. Immediate State Persistence
+
+#### A. Domain Glossary (`devflow/context/glossary.md`)
+When a domain term or conceptual definition crystallizes, immediately create or append to `devflow/context/glossary.md`:
+
+```markdown
+### [Term / Concept]
+- **Definition**: Clear, unambiguous definition within this project.
+- **Constraints**: Invariants, boundaries, or lifecycle rules.
+- **Aliases / Related**: Related terms or common misnomers.
+```
+
+#### B. Architecture Decision Records (`devflow/decisions/ADR-xxx-{slug}.md`)
+When a decision meets the 3 ADR criteria:
+1. **Significant Impact**: Affects architecture, data schema, security, or public API.
+2. **Hard to Reverse**: Changing it later requires painful migration or refactoring.
+3. **Multiple Viable Alternatives**: There were real trade-offs between 2+ options.
+
+Allocate the next sequential ID (`ADR-001`, `ADR-002`, ...) and create `devflow/decisions/ADR-xxx-{slug}.md`:
+
+```markdown
+# ADR-xxx: {Title}
+
+- **Status**: Accepted
+- **Date**: {YYYY-MM-DD}
+- **Context**: {Why was this decision needed? What problem does it solve?}
+- **Decision**: {What did we decide to do?}
+- **Alternatives Considered**:
+  - *Option 1*: {Pros / Cons}
+  - *Option 2*: {Pros / Cons}
+- **Consequences**:
+  - *Positive*: {Benefits gained}
+  - *Trade-offs / Risks*: {Costs, constraints, or follow-ups}
+```
+
+---
+
+## 4. Closing & Handoff
+
+When all design branches are resolved:
+1. Summarize settled domain terms and created ADRs.
+2. Provide explicit next command recommendations:
+   - **Fast-Track (Standard Features/Fixes)**: Run `/feature {topic}` or `/fix {topic}` to immediately start the living spec.
+   - **Deep-Track (Large Architectural Epics)**: Run `10-define` or `/discovery` with the discovery context.

package/template/AGENTS.md

@@ -31,10 +31,10 @@ Unused adapter families can be removed. Codex, Antigravity, GitHub Copilot, and
 
 ### Universal Invocation & Agent Directives:
 
-1. **Canonical Command Names & AI Provider Invocation**: Each workflow stage and companion tool has exactly **one Canonical Name** (e.g. `feature`, `fix`, `implement`, `check`, `complete`, `00-explore`, `10-define`, `20-spec`, `30-plan`, `40-execute`, `50-verify`, `60-report`, `70-deliver`, `devflow`, `doctor`, `overview`, `debug`, `onboard`, `adopt`, `try`, `rollback`, `idea`, `ci`, `test`, `autopilot`, `prototype`, `report-html`, `brief`, `discovery`, `audit`, `release`). The way you invoke commands depends on your AI Provider / Tool:
-   - **Canonical Name (Plain text)**: Directly invoke or prompt the command by its standard name (e.g., `feature`, `40-execute`, `devflow`).
-   - **Slash Prefix (`/`)**: For tools supporting slash commands (Claude Code, Google Antigravity, Gemini CLI), e.g., `/feature`, `/fix`, `/implement`, `/40-execute`, `/devflow`.
-   - **Dollar Prefix (`$`)**: For OpenAI Codex CLI or skill-invocation tools, e.g., `$feature`, `$fix`, `$40-execute`, `$devflow`.
+1. **Canonical Command Names & AI Provider Invocation**: Each workflow stage and companion tool has exactly **one Canonical Name** (e.g. `feature`, `fix`, `implement`, `check`, `complete`, `discovery`, `10-define`, `20-spec`, `30-plan`, `40-execute`, `50-verify`, `60-report`, `70-deliver`, `devflow`, `doctor`, `overview`, `debug`, `onboard`, `adopt`, `try`, `rollback`, `idea`, `ci`, `test`, `autopilot`, `prototype`, `report-html`, `brief`, `audit`, `release`, `brainstorm`, `grill`). The way you invoke commands depends on your AI Provider / Tool:
+   - **Canonical Name (Plain text)**: Directly invoke or prompt the command by its standard name (e.g., `feature`, `40-execute`, `devflow`, `discovery`).
+   - **Slash Prefix (`/`)**: For tools supporting slash commands (Claude Code, Google Antigravity, Gemini CLI), e.g., `/feature`, `/fix`, `/implement`, `/40-execute`, `/devflow`, `/discovery`.
+   - **Dollar Prefix (`$`)**: For OpenAI Codex CLI or skill-invocation tools, e.g., `$feature`, `$fix`, `$40-execute`, `$devflow`, `$discovery`.
 2. **OpenAI Codex & Non-Native CLI Tools**: In environments without automatic background skill discovery (such as OpenAI Codex CLI, Aider, or generic terminals), **you MUST use your file reading tool to inspect `.agents/skills/<skill>/SKILL.md` before executing the stage** to strictly follow its schema, artifact contract, and quality gates.
 3. **Google Antigravity & Claude Code**: Native skill engines automatically discover and surface `.agents/skills/` and `.claude/skills/`.
 4. **State-Aware Inspection**: When unsure what to do next, invoke `devflow` to automatically inspect `devflow/context/current-stage.md` and active context in `devflow/context/`.
@@ -67,10 +67,10 @@ Recommended for 85% of daily work (features, bug fixes, UI improvements, iterati
 Recommended for large architectural epics, database migrations, and multi-agent coordination:
 
 ```text
-00-explore ──▶ 10-define ──▶ 20-spec ──▶ 30-plan ──▶ 40-execute ──▶ 50-verify ──▶ 60-report ──▶ 70-deliver
+discovery ──▶ 10-define ──▶ 20-spec ──▶ 30-plan ──▶ 40-execute ──▶ 50-verify ──▶ 60-report ──▶ 70-deliver
 ```
 
-1. `00-explore`: Explore request before delivery commitment without allocating running ID (`00-explore.md`).
+1. `discovery`: Unified pre-delivery discovery & exploration (project-level roadmap planning or feature-level exploration with 5 lenses: Brainstorm, Research, PRD, Bug Triage, Grill) before delivery commitment (`devflow/discoveries/{DISC-ID}/discovery.md`).
 2. `10-define`: Turn approved discovery into bounded delivery run in `devflow/context/current-run/10-define.md`.
 3. `20-spec`: Formalize markdown-first delivery contract & acceptance criteria (`20-spec.md`).
 4. `30-plan`: Breakdown spec into executable tasks with test decisions (`30-plan.md` + checklists).

package/template/devflow/context/ai-interaction.md

@@ -120,3 +120,14 @@ Progress lives in persistent files, not in transient chat history:
 - `autopilot` is an explicit opt-in command (`/autopilot`). Never suggest it as the default next action.
 - When invoked, it runs one bounded spec/plan/implement/verify pass.
 - Autopilot **MUST stop** before `/complete`, merge, push, deploy, or any destructive action.
+
+---
+
+## 9. Socratic Alignment & Grilling Discipline (`/grill`)
+
+- **Align Before You Build**: When plans, domain language, or architectural boundaries are fuzzy, invoke `/grill` (or use the Grilling Lens in `00-explore`) to conduct a structured interview before creating specifications.
+- **Codebase-Grounded Inquiry**: Inspect existing context and code before asking questions. Never ask questions the codebase already answers.
+- **Turn Discipline**: Ask only 1–2 high-leverage questions per turn with clear recommended defaults. Never dump a wall of questions.
+- **Lazy Inline Persistence**:
+  - Immediately append resolved terms to `devflow/context/glossary.md`.
+  - Immediately record major, hard-to-reverse architectural decisions as Architecture Decision Records in `devflow/decisions/ADR-xxx-{slug}.md`.

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
@@ -140,3 +141,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