@nforma.ai/nforma 0.2.1

package/commands/qgsd/execute-phase.md

@@ -0,0 +1,117 @@
+---
+name: qgsd:execute-phase
+description: Execute all plans in a phase with wave parallelization and automated checkpoint:verify gates via quorum-test.
+argument-hint: "<phase-number>"
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Glob
+  - Grep
+  - Bash
+  - Task
+  - TodoWrite
+  - AskUserQuestion
+---
+
+<objective>
+Execute all plans in a phase. Delegates to the gsd:execute-phase workflow for wave-based plan execution. Extends the workflow with automated verification gates: when a plan step has type checkpoint:verify, the executor runs /qgsd:quorum-test instead of waiting for human input. Escalates to checkpoint:human-verify only on failure.
+</objective>
+
+<execution_context>
+@~/.claude/qgsd/workflows/execute-phase.md
+</execution_context>
+
+<context>
+Phase: $ARGUMENTS
+
+**Flags:**
+- `--gaps-only` — Execute only gap closure plans (plans with `gap_closure: true` in frontmatter). Use after verify-work creates fix plans.
+</context>
+
+<process>
+
+Execute the execute-phase workflow from @~/.claude/qgsd/workflows/execute-phase.md end-to-end, applying the checkpoint type handling rules below at every plan step.
+
+## Agent Substitution (QGSD override)
+
+The GSD workflow uses GSD-specific agent types. When following that workflow, substitute:
+
+| GSD agent type (in workflow) | Use instead (QGSD) |
+|------------------------------|---------------------|
+| `gsd-executor` | `qgsd-executor` |
+| `gsd-verifier` | `qgsd-verifier` |
+
+This applies everywhere the workflow calls `Task(subagent_type="gsd-executor", ...)` or `Task(subagent_type="gsd-verifier", ...)`. All other agent types pass through unchanged.
+
+## Checkpoint Type Handling Rules
+
+These rules are applied during plan step execution. Each plan step carries a `type` attribute. Handle checkpoint types as follows:
+
+---
+
+### Rule 1 — checkpoint:verify (automated quorum gate)
+
+When the executor reads a plan step whose type is `checkpoint:verify`, it MUST:
+
+a. NOT pause for human input.
+b. Identify the test scope from the step's verify section (test file paths or test command).
+c. Call `/qgsd:quorum-test` with that scope.
+d. Evaluate the consensus verdict:
+   - **PASS:** log `checkpoint:verify PASSED — quorum consensus` and continue execution.
+   - **BLOCK or REVIEW-NEEDED:** enter the debug loop (see Rule 3).
+   - **ALL models UNAVAILABLE:** escalate immediately to `checkpoint:human-verify` (see Rule 4).
+
+---
+
+### Rule 2 — checkpoint:human-verify (human gate)
+
+When the executor reads a plan step whose type is `checkpoint:human-verify`, it MUST pause and request human confirmation before continuing. This is the standard behavior and the escalation target for Rule 3.
+
+---
+
+### Rule 3 — Debug loop (3 rounds max)
+
+Triggered when `/qgsd:quorum-test` returns BLOCK or REVIEW-NEEDED on a `checkpoint:verify` step.
+
+Round N (N = 1, 2, 3):
+
+1. Call `/qgsd:debug` with the quorum-test failure context as `$ARGUMENTS`.
+2. Apply the consensus next step from `/qgsd:debug` (code fix, test correction, or config update as directed by the consensus).
+3. Re-run `/qgsd:quorum-test` with the same scope.
+4. If result is PASS: log `checkpoint:verify PASSED after N debug round(s)` and continue.
+5. If result is still BLOCK/REVIEW-NEEDED and N < 3: increment round, repeat.
+
+After 3 rounds with no PASS: escalate to `checkpoint:human-verify` (Rule 4).
+
+---
+
+### Rule 4 — Escalation to checkpoint:human-verify
+
+Display a failure summary:
+- The `checkpoint:verify` step that failed
+- Number of `/qgsd:debug` rounds attempted
+- Final quorum-test verdict and concerns from each model
+
+Then pause: request human review and corrective action before resuming.
+
+---
+
+## Checkpoint Type Reference Table
+
+| Task Type               | Who handles it    | Escalates to            | When used                           |
+|-------------------------|-------------------|-------------------------|-------------------------------------|
+| `checkpoint:verify`     | Executor auto     | `checkpoint:human-verify` | Test-suite gates (quorum-testable) |
+| `checkpoint:human-verify` | Human           | N/A                     | Live session / escalation only      |
+
+---
+
+## Completion
+
+After all plans in the phase complete, display:
+
+```
+All plans complete. Run /qgsd:verify-work to confirm goal achievement.
+```
+
+</process>

package/commands/qgsd/fix-tests.md

@@ -0,0 +1,27 @@
+---
+name: qgsd:fix-tests
+description: Autonomously discover, batch, run, categorize, and fix test failures across large suites
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Glob
+  - Grep
+  - Task
+---
+
+<objective>
+Discover all test failures in the project, batch them, run each with flakiness detection,
+stub-categorize each confirmed failure, and iterate until a terminal state is reached.
+
+This command is execution-only — it does NOT invoke quorum workers (R2.1 / INTG-03).
+</objective>
+
+<execution_context>
+@~/.claude/qgsd/workflows/fix-tests.md
+</execution_context>
+
+<process>
+Follow the fix-tests workflow from @~/.claude/qgsd/workflows/fix-tests.md end-to-end.
+</process>

package/commands/qgsd/formal-test-sync.md

@@ -0,0 +1,32 @@
+---
+name: qgsd:formal-test-sync
+description: Cross-reference formal model invariants with unit test coverage, validate constants, and generate test stubs
+argument-hint: [--report-only] [--dry-run] [--json] [--stubs-dir=<path>]
+allowed-tools:
+  - Read
+  - Bash
+  - Glob
+  - Grep
+---
+
+<objective>
+Cross-reference formal model invariants with unit test coverage. Reports gaps where invariants lack test backing, validates formal model constants against runtime config defaults, generates test stubs for uncovered requirements, and updates the traceability matrix with unit test coverage data.
+</objective>
+
+<execution_context>
+None required — self-contained script.
+</execution_context>
+
+<process>
+Run `node bin/formal-test-sync.cjs $ARGUMENTS` and display results.
+
+If no flags are passed, the full sync runs (coverage report + constants validation + stub generation + sidecar update).
+
+Use `--report-only` for read-only analysis without generating stubs or updating sidecar files.
+
+Use `--json` for machine-readable output.
+
+Use `--dry-run` to show what stubs would be generated without writing them.
+
+Use `--stubs-dir=<path>` to override the default stub output directory (.planning/formal/generated-stubs/).
+</process>

package/commands/qgsd/health.md

@@ -0,0 +1,22 @@
+---
+name: qgsd:health
+description: Diagnose planning directory health and optionally repair issues
+argument-hint: [--repair] [--force]
+allowed-tools:
+  - Read
+  - Bash
+  - Write
+  - AskUserQuestion
+---
+<objective>
+Validate `.planning/` directory integrity and report actionable issues. Checks for missing files, invalid configurations, inconsistent state, and orphaned plans.
+</objective>
+
+<execution_context>
+@~/.claude/qgsd/workflows/health.md
+</execution_context>
+
+<process>
+Execute the health workflow from @~/.claude/qgsd/workflows/health.md end-to-end.
+Parse --repair flag from arguments and pass to workflow.
+</process>

package/commands/qgsd/help.md

@@ -0,0 +1,22 @@
+---
+name: qgsd:help
+description: Show available GSD commands and usage guide
+---
+<objective>
+Display the complete GSD command reference.
+
+Output ONLY the reference content below. Do NOT add:
+- Project-specific analysis
+- Git status or file context
+- Next-step suggestions
+- Any commentary beyond the reference
+</objective>
+
+<execution_context>
+@~/.claude/qgsd/workflows/help.md
+</execution_context>
+
+<process>
+Output the complete GSD command reference from @~/.claude/qgsd/workflows/help.md.
+Display the reference content directly — no additions or modifications.
+</process>

package/commands/qgsd/insert-phase.md

@@ -0,0 +1,32 @@
+---
+name: qgsd:insert-phase
+description: Insert urgent work as decimal phase (e.g., 72.1) between existing phases
+argument-hint: <after> <description>
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+---
+
+<objective>
+Insert a decimal phase for urgent work discovered mid-milestone that must be completed between existing integer phases.
+
+Uses decimal numbering (72.1, 72.2, etc.) to preserve the logical sequence of planned phases while accommodating urgent insertions.
+
+Purpose: Handle urgent work discovered during execution without renumbering entire roadmap.
+</objective>
+
+<execution_context>
+@~/.claude/qgsd/workflows/insert-phase.md
+</execution_context>
+
+<context>
+Arguments: $ARGUMENTS (format: <after-phase-number> <description>)
+
+Roadmap and state are resolved in-workflow via `init phase-op` and targeted tool calls.
+</context>
+
+<process>
+Execute the insert-phase workflow from @~/.claude/qgsd/workflows/insert-phase.md end-to-end.
+Preserve all validation gates (argument parsing, phase verification, decimal calculation, roadmap updates).
+</process>

package/commands/qgsd/join-discord.md

@@ -0,0 +1,18 @@
+---
+name: qgsd:join-discord
+description: Join the QGSD Discord community
+---
+
+<objective>
+Display the Discord invite link for the QGSD community server.
+</objective>
+
+<output>
+# Join the QGSD Discord
+
+Connect with other QGSD users, get help, share what you're building, and stay updated.
+
+**Server link:** https://discord.com/servers/1474810068636663886
+
+Click the link or paste it into your browser to join.
+</output>

package/commands/qgsd/list-phase-assumptions.md

@@ -0,0 +1,46 @@
+---
+name: qgsd:list-phase-assumptions
+description: Surface Claude's assumptions about a phase approach before planning
+argument-hint: "[phase]"
+allowed-tools:
+  - Read
+  - Bash
+  - Grep
+  - Glob
+---
+
+<objective>
+Analyze a phase and present Claude's assumptions about technical approach, implementation order, scope boundaries, risk areas, and dependencies.
+
+Purpose: Help users see what Claude thinks BEFORE planning begins - enabling course correction early when assumptions are wrong.
+Output: Conversational output only (no file creation) - ends with "What do you think?" prompt
+</objective>
+
+<execution_context>
+@~/.claude/qgsd/workflows/list-phase-assumptions.md
+</execution_context>
+
+<context>
+Phase number: $ARGUMENTS (required)
+
+Project state and roadmap are loaded in-workflow using targeted reads.
+</context>
+
+<process>
+1. Validate phase number argument (error if missing or invalid)
+2. Check if phase exists in roadmap
+3. Follow list-phase-assumptions.md workflow:
+   - Analyze roadmap description
+   - Surface assumptions about: technical approach, implementation order, scope, risks, dependencies
+   - Present assumptions clearly
+   - Prompt "What do you think?"
+4. Gather feedback and offer next steps
+</process>
+
+<success_criteria>
+
+- Phase validated against roadmap
+- Assumptions surfaced across five areas
+- User prompted for feedback
+- User knows next steps (discuss context, plan phase, or correct assumptions)
+  </success_criteria>

package/commands/qgsd/map-codebase.md

@@ -0,0 +1,71 @@
+---
+name: qgsd:map-codebase
+description: Analyze codebase with parallel mapper agents to produce .planning/codebase/ documents
+argument-hint: "[optional: specific area to map, e.g., 'api' or 'auth']"
+allowed-tools:
+  - Read
+  - Bash
+  - Glob
+  - Grep
+  - Write
+  - Task
+---
+
+<objective>
+Analyze existing codebase using parallel qgsd-codebase-mapper agents to produce structured codebase documents.
+
+Each mapper agent explores a focus area and **writes documents directly** to `.planning/codebase/`. The orchestrator only receives confirmations, keeping context usage minimal.
+
+Output: .planning/codebase/ folder with 7 structured documents about the codebase state.
+</objective>
+
+<execution_context>
+@~/.claude/qgsd/workflows/map-codebase.md
+</execution_context>
+
+<context>
+Focus area: $ARGUMENTS (optional - if provided, tells agents to focus on specific subsystem)
+
+**Load project state if exists:**
+Check for .planning/STATE.md - loads context if project already initialized
+
+**This command can run:**
+- Before /qgsd:new-project (brownfield codebases) - creates codebase map first
+- After /qgsd:new-project (greenfield codebases) - updates codebase map as code evolves
+- Anytime to refresh codebase understanding
+</context>
+
+<when_to_use>
+**Use map-codebase for:**
+- Brownfield projects before initialization (understand existing code first)
+- Refreshing codebase map after significant changes
+- Onboarding to an unfamiliar codebase
+- Before major refactoring (understand current state)
+- When STATE.md references outdated codebase info
+
+**Skip map-codebase for:**
+- Greenfield projects with no code yet (nothing to map)
+- Trivial codebases (<5 files)
+</when_to_use>
+
+<process>
+1. Check if .planning/codebase/ already exists (offer to refresh or skip)
+2. Create .planning/codebase/ directory structure
+3. Spawn 4 parallel qgsd-codebase-mapper agents:
+   - Agent 1: tech focus → writes STACK.md, INTEGRATIONS.md
+   - Agent 2: arch focus → writes ARCHITECTURE.md, STRUCTURE.md
+   - Agent 3: quality focus → writes CONVENTIONS.md, TESTING.md
+   - Agent 4: concerns focus → writes CONCERNS.md
+4. Wait for agents to complete, collect confirmations (NOT document contents)
+5. Verify all 7 documents exist with line counts
+6. Commit codebase map
+7. Offer next steps (typically: /qgsd:new-project or /qgsd:plan-phase)
+</process>
+
+<success_criteria>
+- [ ] .planning/codebase/ directory created
+- [ ] All 7 codebase documents written by mapper agents
+- [ ] Documents follow template structure
+- [ ] Parallel agents completed without errors
+- [ ] User knows next steps
+</success_criteria>

package/commands/qgsd/map-requirements.md

@@ -0,0 +1,20 @@
+---
+name: qgsd:map-requirements
+description: Map current and archived milestone requirements into .planning/formal/requirements.json
+argument-hint: [--dry-run] [--skip-archive] [--skip-validate]
+allowed-tools:
+  - Read
+  - Bash
+---
+<objective>
+Run the requirements mapping pipeline — merges current `.planning/REQUIREMENTS.md` with archived milestone requirements into `.planning/formal/requirements.json`. Shows a summary of requirement counts by source.
+</objective>
+
+<execution_context>
+@~/.claude/qgsd/workflows/map-requirements.md
+</execution_context>
+
+<process>
+Execute the map-requirements workflow from @~/.claude/qgsd/workflows/map-requirements.md end-to-end.
+Pass through --dry-run and --skip-archive flags from arguments.
+</process>

package/commands/qgsd/mcp-restart.md

@@ -0,0 +1,176 @@
+---
+name: qgsd:mcp-restart
+description: Restart a quorum agent's MCP server process — kills the running process and waits for Claude Code to reconnect automatically
+argument-hint: "<agent>"
+allowed-tools:
+  - Bash
+  - mcp__codex-cli-1__identity
+  - mcp__gemini-cli-1__identity
+  - mcp__opencode-1__identity
+  - mcp__copilot-1__identity
+  - mcp__claude-1__identity
+  - mcp__claude-2__identity
+  - mcp__claude-3__identity
+  - mcp__claude-4__identity
+  - mcp__claude-5__identity
+  - mcp__claude-6__identity
+---
+
+<objective>
+Restart a named quorum agent's MCP server process. Reads `~/.claude.json` to identify the running process, kills it, and waits for Claude Code to automatically reconnect. Claude Code manages MCP server lifecycles — when a child process dies, Claude Code restarts it automatically. After killing the process, this command waits 2 seconds and calls the agent's identity tool to confirm reconnection.
+</objective>
+
+<process>
+
+## Step 1 — Parse arguments
+
+Parse `$ARGUMENTS` as one token: `$AGENT`.
+
+If `$AGENT` is missing, print usage and stop:
+```
+Usage: /qgsd:mcp-restart <agent>
+
+Valid agents:
+  codex-cli-1, gemini-cli-1, opencode-1, copilot-1,
+  claude-1, claude-2, claude-3, claude-4, claude-5, claude-6
+```
+
+## Step 2 — Validate agent name
+
+Check `$AGENT` against the known agent list:
+```
+codex-cli-1, gemini-cli-1, opencode-1, copilot-1,
+claude-1, claude-2, claude-3, claude-4, claude-5, claude-6
+```
+
+If not in the list, print an error and stop:
+```
+Error: Unknown agent "$AGENT"
+
+Valid agents:
+  codex-cli-1   gemini-cli-1   opencode-1   copilot-1
+  claude-1      claude-2       claude-3     claude-4
+  claude-5      claude-6
+```
+
+## Step 3 — Read process identity from ~/.claude.json
+
+Run this inline node script via Bash:
+
+```bash
+node -e "
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+const claudeJsonPath = path.join(os.homedir(), '.claude.json');
+let claudeJson;
+try {
+  claudeJson = JSON.parse(fs.readFileSync(claudeJsonPath, 'utf8'));
+} catch (e) {
+  console.error('Error: Cannot read ~/.claude.json: ' + e.message);
+  process.exit(1);
+}
+
+const servers = claudeJson.mcpServers || {};
+const agent = process.env.AGENT;
+const serverConfig = servers[agent];
+
+if (!serverConfig) {
+  console.error('Error: Agent \"' + agent + '\" is not configured in ~/.claude.json mcpServers');
+  process.exit(2);
+}
+
+const command = serverConfig.command;
+const args = serverConfig.args || [];
+
+let result;
+if (command === 'node' && args.length > 0) {
+  // local node path: kill by matching argv path
+  result = { type: 'local', processPath: args[0] };
+} else if (command === 'npx' || command === 'npm') {
+  // npx-based: kill by package name (matches both npm exec and node child)
+  const packageName = args[args.length - 1];
+  result = { type: 'npx', packageName };
+} else {
+  result = { type: 'unknown', command };
+}
+
+process.stdout.write(JSON.stringify(result) + '\n');
+" AGENT="$AGENT"
+```
+
+Store output as `$PROCESS_INFO`.
+
+If exit code 1 or 2: print the error message and stop.
+If exit code 0: parse `$PROCESS_INFO` JSON.
+
+## Step 4 — Kill the MCP server process
+
+Based on the `type` field from `$PROCESS_INFO`:
+
+**type = "local":**
+
+Kill all node processes whose argv path matches the server path:
+```bash
+pkill -f "$PROCESS_PATH" 2>/dev/null || true
+```
+where `$PROCESS_PATH` is `process_info.processPath`.
+
+Print: `Sending SIGTERM to processes matching: $PROCESS_PATH`
+
+**type = "npx":**
+
+Kill both the npm exec parent and the node child subprocess:
+```bash
+pkill -f "npm exec $PACKAGE_NAME" 2>/dev/null || true
+sleep 0.5
+pkill -f "$PACKAGE_NAME" 2>/dev/null || true
+```
+where `$PACKAGE_NAME` is `process_info.packageName`.
+
+Print: `Sending SIGTERM to npm exec + node processes for: $PACKAGE_NAME`
+
+**type = "unknown":**
+Print:
+```
+Warning: Cannot determine process pattern for $AGENT (command: <command>).
+Cannot restart automatically. Restart Claude Code session to reload this agent.
+```
+Stop.
+
+## Step 5 — Wait for reconnection
+
+Wait 2 seconds:
+```bash
+sleep 2
+```
+
+Print: `Waiting for Claude Code to reconnect...`
+
+## Step 6 — Verify reconnection via identity tool
+
+Call the identity tool for `$AGENT` — one sequential call:
+
+`mcp__<$AGENT>__identity`
+
+(Replace hyphens in the agent name with hyphens as-is: `codex-cli-1` → `mcp__codex-cli-1__identity`)
+
+**If identity tool returns successfully:**
+Parse response. Print:
+```
+Agent $AGENT restarted and responding
+
+  Name:    <name from identity>
+  Version: <version from identity>
+  Model:   <model from identity>
+```
+
+**If identity tool errors or times out:**
+Print:
+```
+Processes killed. Claude Code is reconnecting to $AGENT.
+Check status in a few seconds: /qgsd:mcp-status
+```
+
+</process>