@nforma.ai/nforma 0.2.1

package/commands/qgsd/add-phase.md

@@ -0,0 +1,43 @@
+---
+name: qgsd:add-phase
+description: Add phase to end of current milestone in roadmap
+argument-hint: <description>
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+---
+
+<objective>
+Add a new integer phase to the end of the current milestone in the roadmap.
+
+Routes to the add-phase workflow which handles:
+- Phase number calculation (next sequential integer)
+- Directory creation with slug generation
+- Roadmap structure updates
+- STATE.md roadmap evolution tracking
+</objective>
+
+<execution_context>
+@~/.claude/qgsd/workflows/add-phase.md
+</execution_context>
+
+<context>
+Arguments: $ARGUMENTS (phase description)
+
+Roadmap and state are resolved in-workflow via `init phase-op` and targeted tool calls.
+</context>
+
+<process>
+**Follow the add-phase workflow** from `@~/.claude/qgsd/workflows/add-phase.md`.
+
+The workflow handles all logic including:
+1. Argument parsing and validation
+2. Roadmap existence checking
+3. Current milestone identification
+4. Next phase number calculation (ignoring decimals)
+5. Slug generation from description
+6. Phase directory creation
+7. Roadmap entry insertion
+8. STATE.md updates
+</process>

package/commands/qgsd/add-requirement.md

@@ -0,0 +1,24 @@
+---
+name: qgsd:add-requirement
+description: Add a single requirement to .planning/formal/requirements.json with duplicate and conflict checks
+argument-hint: [--id=PREFIX-NN] [--text="..."] [--category="..."] [--phase=vX.XX-NN] [--dry-run]
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Agent
+  - AskUserQuestion
+---
+<objective>
+Add a single requirement to the formal requirements envelope (`.planning/formal/requirements.json`). Validates the ID format, checks for duplicate IDs, runs Haiku semantic conflict detection against same-prefix requirements, and elevates conflicts to the user before writing. Handles envelope freeze/unfreeze lifecycle automatically.
+</objective>
+
+<execution_context>
+@~/.claude/qgsd/workflows/add-requirement.md
+</execution_context>
+
+<process>
+Execute the add-requirement workflow from @~/.claude/qgsd/workflows/add-requirement.md end-to-end.
+Pass through all --flags from arguments. If required fields (id, text, category, phase) are not provided as arguments, prompt the user interactively.
+</process>

package/commands/qgsd/add-todo.md

@@ -0,0 +1,47 @@
+---
+name: qgsd:add-todo
+description: Capture idea or task as todo from current conversation context
+argument-hint: [optional description]
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - AskUserQuestion
+---
+
+<objective>
+Capture an idea, task, or issue that surfaces during a GSD session as a structured todo for later work.
+
+Routes to the add-todo workflow which handles:
+- Directory structure creation
+- Content extraction from arguments or conversation
+- Area inference from file paths
+- Duplicate detection and resolution
+- Todo file creation with frontmatter
+- STATE.md updates
+- Git commits
+</objective>
+
+<execution_context>
+@~/.claude/qgsd/workflows/add-todo.md
+</execution_context>
+
+<context>
+Arguments: $ARGUMENTS (optional todo description)
+
+State is resolved in-workflow via `init todos` and targeted reads.
+</context>
+
+<process>
+**Follow the add-todo workflow** from `@~/.claude/qgsd/workflows/add-todo.md`.
+
+The workflow handles all logic including:
+1. Directory ensuring
+2. Existing area checking
+3. Content extraction (arguments or conversation)
+4. Area inference
+5. Duplicate checking
+6. File creation with slug generation
+7. STATE.md updates
+8. Git commits
+</process>

package/commands/qgsd/audit-milestone.md

@@ -0,0 +1,37 @@
+---
+name: qgsd:audit-milestone
+description: Audit milestone completion against original intent before archiving
+argument-hint: "[version] [--auto]"
+allowed-tools:
+  - Read
+  - Glob
+  - Grep
+  - Bash
+  - Task
+  - Write
+  - AskUserQuestion
+---
+<objective>
+Verify milestone achieved its definition of done. Check requirements coverage, cross-phase integration, and end-to-end flows.
+
+**This command IS the orchestrator.** Reads existing VERIFICATION.md files (phases already verified during execute-phase), aggregates tech debt and deferred gaps, then spawns integration checker for cross-phase wiring.
+</objective>
+
+<execution_context>
+@~/.claude/qgsd/workflows/audit-milestone.md
+</execution_context>
+
+<context>
+Version: $ARGUMENTS (optional — defaults to current milestone)
+
+Core planning files are resolved in-workflow (`init milestone-op`) and loaded only as needed.
+
+**Completed Work:**
+Glob: .planning/phases/*/*-SUMMARY.md
+Glob: .planning/phases/*/*-VERIFICATION.md
+</context>
+
+<process>
+Execute the audit-milestone workflow from @~/.claude/qgsd/workflows/audit-milestone.md end-to-end.
+Preserve all workflow gates (scope determination, verification reading, integration check, requirements coverage, routing).
+</process>

package/commands/qgsd/check-todos.md

@@ -0,0 +1,45 @@
+---
+name: qgsd:check-todos
+description: List pending todos and select one to work on
+argument-hint: [area filter]
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - AskUserQuestion
+---
+
+<objective>
+List all pending todos, allow selection, load full context for the selected todo, and route to appropriate action.
+
+Routes to the check-todos workflow which handles:
+- Todo counting and listing with area filtering
+- Interactive selection with full context loading
+- Roadmap correlation checking
+- Action routing (work now, add to phase, brainstorm, create phase)
+- STATE.md updates and git commits
+</objective>
+
+<execution_context>
+@~/.claude/qgsd/workflows/check-todos.md
+</execution_context>
+
+<context>
+Arguments: $ARGUMENTS (optional area filter)
+
+Todo state and roadmap correlation are loaded in-workflow using `init todos` and targeted reads.
+</context>
+
+<process>
+**Follow the check-todos workflow** from `@~/.claude/qgsd/workflows/check-todos.md`.
+
+The workflow handles all logic including:
+1. Todo existence checking
+2. Area filtering
+3. Interactive listing and selection
+4. Full context loading with file summaries
+5. Roadmap correlation checking
+6. Action offering and execution
+7. STATE.md updates
+8. Git commits
+</process>

package/commands/qgsd/cleanup.md

@@ -0,0 +1,18 @@
+---
+name: qgsd:cleanup
+description: Archive accumulated phase directories from completed milestones
+---
+<objective>
+Archive phase directories from completed milestones into `.planning/milestones/v{X.Y}-phases/`.
+
+Use when `.planning/phases/` has accumulated directories from past milestones.
+</objective>
+
+<execution_context>
+@~/.claude/qgsd/workflows/cleanup.md
+</execution_context>
+
+<process>
+Follow the cleanup workflow at @~/.claude/qgsd/workflows/cleanup.md.
+Identify completed milestones, show a dry-run summary, and archive on confirmation.
+</process>

package/commands/qgsd/close-formal-gaps.md

@@ -0,0 +1,33 @@
+---
+name: close-formal-gaps
+description: Analyze and close formal model coverage gaps — clusters uncovered requirements, selects formalism (TLA+/Alloy/PRISM/Petri), generates specs, runs checkers, and updates the model registry
+argument-hint: [--batch] [--category="Category Name"] [--ids=REQ-01,REQ-02] [--all] [--formalism=tla|alloy|prism|petri] [--dry-run]
+allowed_tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Glob
+  - Grep
+  - Agent
+execution_context: workflow
+---
+
+<objective>
+Close formal model coverage gaps by generating new formal specifications for uncovered requirements.
+</objective>
+
+<execution_context>
+@/Users/jonathanborduas/.claude/qgsd/workflows/close-formal-gaps.md
+</execution_context>
+
+<process>
+Execute the close-formal-gaps workflow from @/Users/jonathanborduas/.claude/qgsd/workflows/close-formal-gaps.md end-to-end.
+Pass through all --flags from arguments:
+  --batch                     Fully autonomous mode — skip all user prompts, auto-approve clusters
+  --category="Category Name"  Focus on a specific category
+  --ids=REQ-01,REQ-02         Focus on specific requirement IDs
+  --all                       Process all uncovered requirements
+  --formalism=tla|alloy|prism|petri  Override formalism selection
+  --dry-run                   Show what would be generated without writing
+</process>

package/commands/qgsd/complete-milestone.md

@@ -0,0 +1,136 @@
+---
+type: prompt
+name: qgsd:complete-milestone
+description: Archive completed milestone and prepare for next version
+argument-hint: <version>
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+---
+
+<objective>
+Mark milestone {{version}} complete, archive to milestones/, and update ROADMAP.md and REQUIREMENTS.md.
+
+Purpose: Create historical record of shipped version, archive milestone artifacts (roadmap + requirements), and prepare for next milestone.
+Output: Milestone archived (roadmap + requirements), PROJECT.md evolved, git tagged.
+</objective>
+
+<execution_context>
+**Load these files NOW (before proceeding):**
+
+- @~/.claude/qgsd/workflows/complete-milestone.md (main workflow)
+- @~/.claude/qgsd/templates/milestone-archive.md (archive template)
+  </execution_context>
+
+<context>
+**Project files:**
+- `.planning/ROADMAP.md`
+- `.planning/REQUIREMENTS.md`
+- `.planning/STATE.md`
+- `.planning/PROJECT.md`
+
+**User input:**
+
+- Version: {{version}} (e.g., "1.0", "1.1", "2.0")
+  </context>
+
+<process>
+
+**Follow complete-milestone.md workflow:**
+
+0. **Check for audit:**
+
+   - Look for `.planning/milestones/v{{version}}-MILESTONE-AUDIT.md` (or legacy `.planning/v{{version}}-MILESTONE-AUDIT.md`)
+   - If missing or stale: recommend `/qgsd:audit-milestone` first
+   - If audit status is `gaps_found`: recommend `/qgsd:plan-milestone-gaps` first
+   - If audit status is `passed`: proceed to step 1
+
+   ```markdown
+   ## Pre-flight Check
+
+   {If no v{{version}}-MILESTONE-AUDIT.md in milestones/ or root:}
+   ⚠ No milestone audit found. Run `/qgsd:audit-milestone` first to verify
+   requirements coverage, cross-phase integration, and E2E flows.
+
+   {If audit has gaps:}
+   ⚠ Milestone audit found gaps. Run `/qgsd:plan-milestone-gaps` to create
+   phases that close the gaps, or proceed anyway to accept as tech debt.
+
+   {If audit passed:}
+   ✓ Milestone audit passed. Proceeding with completion.
+   ```
+
+1. **Verify readiness:**
+
+   - Check all phases in milestone have completed plans (SUMMARY.md exists)
+   - Present milestone scope and stats
+   - Wait for confirmation
+
+2. **Gather stats:**
+
+   - Count phases, plans, tasks
+   - Calculate git range, file changes, LOC
+   - Extract timeline from git log
+   - Present summary, confirm
+
+3. **Extract accomplishments:**
+
+   - Read all phase SUMMARY.md files in milestone range
+   - Extract 4-6 key accomplishments
+   - Present for approval
+
+4. **Archive milestone:**
+
+   - Create `.planning/milestones/v{{version}}-ROADMAP.md`
+   - Extract full phase details from ROADMAP.md
+   - Fill milestone-archive.md template
+   - Update ROADMAP.md to one-line summary with link
+
+5. **Archive requirements:**
+
+   - Create `.planning/milestones/v{{version}}-REQUIREMENTS.md`
+   - Mark all v1 requirements as complete (checkboxes checked)
+   - Note requirement outcomes (validated, adjusted, dropped)
+   - Delete `.planning/REQUIREMENTS.md` (fresh one created for next milestone)
+
+6. **Update PROJECT.md:**
+
+   - Add "Current State" section with shipped version
+   - Add "Next Milestone Goals" section
+   - Archive previous content in `<details>` (if v1.1+)
+
+7. **Commit and tag:**
+
+   - Stage: MILESTONES.md, PROJECT.md, ROADMAP.md, STATE.md, archive files
+   - Commit: `chore: archive v{{version}} milestone`
+   - Tag: `git tag -a v{{version}} -m "[milestone summary]"`
+   - Ask about pushing tag
+
+8. **Offer next steps:**
+   - `/qgsd:new-milestone` — start next milestone (questioning → research → requirements → roadmap)
+
+</process>
+
+<success_criteria>
+
+- Milestone archived to `.planning/milestones/v{{version}}-ROADMAP.md`
+- Requirements archived to `.planning/milestones/v{{version}}-REQUIREMENTS.md`
+- `.planning/REQUIREMENTS.md` deleted (fresh for next milestone)
+- ROADMAP.md collapsed to one-line entry
+- PROJECT.md updated with current state
+- Git tag v{{version}} created
+- Commit successful
+- User knows next steps (including need for fresh requirements)
+  </success_criteria>
+
+<critical_rules>
+
+- **Load workflow first:** Read complete-milestone.md before executing
+- **Verify completion:** All phases must have SUMMARY.md files
+- **User confirmation:** Wait for approval at verification gates
+- **Archive before deleting:** Always create archive files before updating/deleting originals
+- **One-line summary:** Collapsed milestone in ROADMAP.md should be single line with link
+- **Context efficiency:** Archive keeps ROADMAP.md and REQUIREMENTS.md constant size per milestone
+- **Fresh requirements:** Next milestone starts with `/qgsd:new-milestone` which includes requirements definition
+  </critical_rules>

package/commands/qgsd/debug.md

@@ -0,0 +1,166 @@
+---
+name: qgsd:debug
+description: Debug loop with quorum consensus on next step. Feed failure context to 4 quorum workers — each identifies the single most likely root cause and next debugging step. Renders a NEXT STEP table. Call repeatedly: run test → fail → /qgsd:debug → apply step → run test again.
+argument-hint: "[failure context: test output, error trace, or symptom description]"
+allowed-tools:
+  - Task
+---
+
+<objective>
+Dispatch the full quorum debug process to a subagent. The main command stays clean — only the dispatch header and the final NEXT STEP table surface to the conversation context. All bundle assembly, quorum worker dispatch, result collection, artifact writing, and execution happen inside the subagent.
+</objective>
+
+<process>
+
+**Step 1: Show dispatch header**
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ QGSD ► QUORUM-DEBUG: Dispatching debug subagent...
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+**Step 2: Spawn the quorum debug subagent**
+
+Spawn ONE Task with the full failure context and process instructions embedded:
+
+```
+Task(
+  subagent_type="general-purpose",
+  description="Quorum debug orchestration",
+  prompt="""
+You are the QGSD quorum debug orchestrator. Run the full process below for this failure.
+
+ARGUMENTS: $ARGUMENTS
+
+---
+
+## PROCESS
+
+### Step A: Collect failure context
+
+If ARGUMENTS is non-empty, use it as the initial failure description.
+
+Discover test files:
+  find . ( -name "*.test.js" -o -name "*.test.cjs" ) -not -path "*/node_modules/*" -not -path "*/.git/*"
+
+If test files exist, run them:
+  node --test $TEST_FILES 2>&1; echo "EXIT:$?"
+
+Store as $TEST_OUTPUT and $EXIT_CODE. If exit code is 0 and ARGUMENTS is empty, stop and return:
+
+  QUORUM-DEBUG: No failure detected — tests pass (exit 0).
+  If you have a symptom not captured by tests, run: /qgsd:debug [describe the symptom]
+
+### Step B: Assemble bundle
+
+Compose $BUNDLE:
+  FAILURE CONTEXT: $ARGUMENTS
+  EXIT CODE: $EXIT_CODE (or "N/A — symptom only" if no test run)
+  === TEST OUTPUT ===
+  $TEST_OUTPUT (or "N/A" if not a test failure)
+
+### Step C: Dispatch 4 parallel quorum workers
+
+Worker prompt template (inline $BUNDLE verbatim in each):
+
+  You are a debugging advisor for the QGSD project.
+
+  <bundle>
+  $BUNDLE
+  </bundle>
+
+  Given this failure, answer ONLY:
+
+  root_cause: <the single most likely root cause in one sentence>
+  next_step: <the single best next debugging action — be specific: what file to check, what to log, what to run>
+  confidence: HIGH | MEDIUM | LOW
+
+  Rules:
+  - Do NOT suggest a fix. Suggest the next investigative step only.
+  - Be specific: name the file, function, line range, or command to run.
+  - If the bundle lacks enough context to diagnose, say so in root_cause and set confidence: LOW.
+
+Dispatch all 4 workers as parallel Task calls:
+- Task(subagent_type="general-purpose", prompt="Call mcp__gemini-cli__gemini with: [worker prompt with $BUNDLE inlined verbatim]")
+- Task(subagent_type="general-purpose", prompt="Call mcp__opencode__opencode with: [worker prompt with $BUNDLE inlined verbatim]")
+- Task(subagent_type="general-purpose", prompt="Call mcp__copilot-cli__ask with: [worker prompt with $BUNDLE inlined verbatim]")
+- Task(subagent_type="general-purpose", prompt="Call mcp__codex-cli__codex with: [worker prompt with $BUNDLE inlined verbatim]")
+
+### Step D: Collect and parse responses
+
+Parse each worker response for root_cause:, next_step:, confidence: lines.
+If a worker errored or returned unparseable output, mark as UNAVAIL.
+
+Consensus rules:
+- 3+ workers agree on same root cause area → consensus root cause
+- 3+ workers recommend same next step → consensus step
+- Otherwise → list all unique recommendations; note lack of consensus
+
+### Step E: Render NEXT STEP table
+
+Return this output:
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ QGSD ► QUORUM-DEBUG RESULTS
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+┌──────────────┬──────────────┬─────────────────────────────────────────────┐
+│ Model        │ Confidence   │ Next Step                                   │
+├──────────────┼──────────────┼─────────────────────────────────────────────┤
+│ Gemini       │ [confidence] │ [next_step]                                 │
+│ OpenCode     │ [confidence] │ [next_step]                                 │
+│ Copilot      │ [confidence] │ [next_step]                                 │
+│ Codex        │ [confidence] │ [next_step]                                 │
+├──────────────┼──────────────┼─────────────────────────────────────────────┤
+│ CONSENSUS    │ [HIGH/MED/—] │ [consensus step or "No consensus — see above"]│
+└──────────────┴──────────────┴─────────────────────────────────────────────┘
+
+Root Cause Hypothesis (consensus): [one-sentence summary or "No consensus"]
+
+If models give different next steps, list them all below the table with their root cause hypotheses.
+
+### Step F: Save artifact
+
+Write .planning/quick/quorum-debug-latest.md:
+
+  # quorum-debug artifact
+  date: [ISO timestamp]
+  failure_context: $ARGUMENTS
+  exit_code: $EXIT_CODE
+
+  ## consensus
+  root_cause: [consensus root cause or "no consensus"]
+  next_step: [consensus next step or "no consensus"]
+
+  ## worker responses
+  [table as text]
+
+  ## bundle
+  [full $BUNDLE]
+
+### Step G: Execute or escalate
+
+IF consensus was reached:
+  Execute the consensus next step using available tools (Bash, Read, Grep, etc.)
+  Report what was done.
+  Then return:
+    ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+    Consensus step executed. Run /qgsd:debug again to continue.
+    ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+IF no consensus:
+  Return:
+    ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+    No consensus — review recommendations above and apply the most relevant step.
+    Then run /qgsd:debug again with updated output.
+    ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+"""
+)
+```
+
+**Step 3: Report result**
+
+Return the subagent's NEXT STEP table and conclusion to the user.
+
+</process>

package/commands/qgsd/discuss-phase.md

@@ -0,0 +1,83 @@
+---
+name: qgsd:discuss-phase
+description: Gather phase context through adaptive questioning before planning
+argument-hint: "<phase> [--auto]"
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - Glob
+  - Grep
+  - AskUserQuestion
+  - Task
+---
+
+<objective>
+Extract implementation decisions that downstream agents need — researcher and planner will use CONTEXT.md to know what to investigate and what choices are locked.
+
+**How it works:**
+1. Analyze the phase to identify gray areas (UI, UX, behavior, etc.)
+2. Present gray areas — user selects which to discuss
+3. Deep-dive each selected area until satisfied
+4. Create CONTEXT.md with decisions that guide research and planning
+
+**Output:** `{phase_num}-CONTEXT.md` — decisions clear enough that downstream agents can act without asking the user again
+</objective>
+
+<execution_context>
+@~/.claude/qgsd/workflows/discuss-phase.md
+@~/.claude/qgsd/templates/context.md
+</execution_context>
+
+<context>
+Phase number: $ARGUMENTS (required)
+
+Context files are resolved in-workflow using `init phase-op` and roadmap/state tool calls.
+</context>
+
+<process>
+1. Validate phase number (error if missing or not in roadmap)
+2. Check if CONTEXT.md exists (offer update/view/skip if yes)
+3. **Analyze phase** — Identify domain and generate phase-specific gray areas
+4. **Present gray areas** — Multi-select: which to discuss? (NO skip option)
+5. **Deep-dive each area** — 4 questions per area, then offer more/next
+6. **Write CONTEXT.md** — Sections match areas discussed
+7. Offer next steps (research or plan)
+
+**CRITICAL: Scope guardrail**
+- Phase boundary from ROADMAP.md is FIXED
+- Discussion clarifies HOW to implement, not WHETHER to add more
+- If user suggests new capabilities: "That's its own phase. I'll note it for later."
+- Capture deferred ideas — don't lose them, don't act on them
+
+**Domain-aware gray areas:**
+Gray areas depend on what's being built. Analyze the phase goal:
+- Something users SEE → layout, density, interactions, states
+- Something users CALL → responses, errors, auth, versioning
+- Something users RUN → output format, flags, modes, error handling
+- Something users READ → structure, tone, depth, flow
+- Something being ORGANIZED → criteria, grouping, naming, exceptions
+
+Generate 3-4 **phase-specific** gray areas, not generic categories.
+
+**Probing depth:**
+- Ask 4 questions per area before checking
+- "More questions about [area], or move to next?"
+- If more → ask 4 more, check again
+- After all areas → "Explore more gray areas" / "I'm ready for context" (loop-back or proceed)
+
+**Do NOT ask about (Claude handles these):**
+- Technical implementation
+- Architecture choices
+- Performance concerns
+- Scope expansion
+</process>
+
+<success_criteria>
+- Gray areas identified through intelligent analysis
+- User chose which areas to discuss
+- Each selected area explored until satisfied
+- Scope creep redirected to deferred ideas
+- CONTEXT.md captures decisions, not vague vision
+- User knows next steps
+</success_criteria>