@ktpartners/dgs-platform 2.6.2

package/deliver-great-systems/workflows/run-job.md

@@ -0,0 +1,498 @@
+<purpose>
+Execute a milestone build job end-to-end. Reads the job file, loops through pending steps, spawns an isolated subagent per step, updates the job file in real-time, handles failures with immediate halt, manages dynamic gap-fix cycles at both milestone level (GapFixCycle, max 3) and phase level (PhaseFixCycle, max 2), and moves completed jobs to the completed/ directory. Supports --dry-run mode for step preview without execution. Auto-generates job summaries on completion and failure.
+
+The orchestrator stays lean: it reads only the job file and MILESTONE-AUDIT.md (plus phase UAT status via CLI for phase-level audits). All actual work is delegated to subagents via Task tool. Each subagent gets a fresh context window with no shared state beyond what is on disk.
+</purpose>
+
+<context_tier>execution</context_tier>
+
+<required_reading>
+Read all files referenced by the invoking prompt's execution_context before starting.
+</required_reading>
+
+<process>
+
+<step name="initialize" priority="first">
+Load planning context:
+
+```bash
+INIT=$(node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs init milestone-op)
+```
+
+Extract: `project_root`, `jobs_root` as needed by the workflow.
+
+**Load execution tier context:**
+
+```bash
+TIER_FILES=$(node "$HOME/.claude/deliver-great-systems/bin/dgs-tools.cjs" context load-tier execution --raw 2>/dev/null)
+```
+
+Note: No `--phase` flag here at init time since the job orchestrator spans multiple phases. Each step's sub-agent loads its own phase-scoped context via its command shim.
+</step>
+
+<step name="parse_arguments">
+Parse `$ARGUMENTS` to extract the version and flags.
+
+- **VERSION:** First positional argument (e.g., `v6`, `v6.0`). Required.
+- **DRY_RUN:** Check if `--dry-run` flag is present in $ARGUMENTS. Store as boolean.
+
+If no version is provided, error immediately:
+```
+Error: Version argument required. Usage: /dgs:run-job <version> [--dry-run]
+```
+
+If `DRY_RUN` is true, proceed to `dry_run_preview` step instead of normal execution flow.
+</step>
+
+<step name="dry_run_preview">
+**Execute only if `DRY_RUN` is true.** If `DRY_RUN` is false, skip this step entirely.
+
+Run the dry-run preview CLI command:
+
+```bash
+RESULT=$(node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs jobs dry-run "$VERSION")
+```
+
+Parse the JSON result.
+
+**If `found: false`:**
+```
+Error: No job found for version {VERSION}.
+```
+
+**Display formatted step list:**
+
+Header:
+```
+=== Dry Run: milestone-{version} ({status}) ===
+```
+
+For each step, display based on status:
+- Completed: `[x] {command} {args}`
+- Pending: `[ ] {command} {args}`
+- Failed: `[!] {command} {args}`
+- In-progress: `[>] {command} {args}`
+
+Show resume point:
+```
+Resume from step {resume_from + 1}: {command} {args}
+```
+
+Show step name + command/skill each step would invoke.
+
+Show warnings if any precondition issues found (e.g., missing planning root, ROADMAP.md, STATE.md).
+
+**HALT -- do not proceed to execution.**
+```
+Dry run complete. Run without --dry-run to execute.
+```
+</step>
+
+<step name="locate_job">
+Find the job file for the given version:
+
+```bash
+RESULT=$(node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs jobs find-job "$VERSION")
+```
+
+Parse the JSON result.
+
+**If `found: false`:**
+```
+Error: No job found for version {VERSION}. Create one with /dgs:create-milestone-job {VERSION}
+```
+
+**If found in `completed/` directory:**
+```
+Error: Job {VERSION} is already completed.
+```
+
+Store `JOB_PATH` from the result for all subsequent operations.
+</step>
+
+<step name="move_to_in_progress">
+Transition the job to in-progress state if needed.
+
+**If job is in `pending/`:**
+
+1. Move the file to `in-progress/`:
+   ```bash
+   node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs jobs move "$JOB_PATH" "${jobs_root}/in-progress"
+   ```
+
+2. Update `JOB_PATH` to reflect the new location under `in-progress/`.
+
+3. Update the header Status field (using the updated `$JOB_PATH`):
+   ```bash
+   node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs jobs update-header "$JOB_PATH" Status in-progress
+   ```
+
+**If already in `in-progress/`:** Skip the move. The job is being resumed.
+
+**Record starting commit SHAs:**
+
+After the job moves to in-progress (or is confirmed already there), record starting SHAs if not already present:
+
+```bash
+# Check if StartShas already recorded (skip on resume)
+if ! grep -q '^\*\*StartShas:\*\*' "$JOB_PATH"; then
+  node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs jobs record-start-shas "$JOB_PATH"
+fi
+```
+
+This captures the current HEAD of every registered code repo and the planning repo before any execution begins. The SHAs are written into the job file header as `**StartShas:**` and used by `/dgs:rollback-job` to reset repos if the job produces unwanted results.
+</step>
+
+<step name="parse_job_state">
+Parse the current job state:
+
+```bash
+JOB=$(node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs jobs parse "$JOB_PATH")
+```
+
+Extract from JSON:
+- `stepCount` -- total number of steps
+- `completedCount` -- how many steps are already completed
+- `failedCount` -- how many steps have failed status
+- `nextStepIndex` -- zero-based index of next step to execute (null if all done)
+- `steps` -- array of step objects with command, args, status, timestamp, error
+- `check` -- whether audit/complete steps are included
+- `version` -- the milestone version
+- `gapFixCycle` -- current gap-fix cycle number (0 if no gap-fix has occurred)
+- `phaseFixCycle` -- current phase-level fix cycle number (0 if no phase fix has occurred)
+- `phaseFixCyclePhase` -- which phase the PhaseFixCycle counter applies to (null if none)
+
+Initialize `GAP_FIX_CYCLE` to the `gapFixCycle` value from the parsed result (not 0). This enables mid-cycle resume -- if the orchestrator restarts mid gap-fix, it knows which cycle it was on.
+
+Initialize `PHASE_GAP_FIX_CYCLE` to the `phaseFixCycle` value from the parsed result.
+Initialize `PHASE_FIX_CYCLE_PHASE` to the `phaseFixCyclePhase` value from the parsed result.
+
+**If `nextStepIndex` is null** (all steps already done): Go directly to `complete_job`.
+
+**If a step has `status: failed`:** Reset it to pending before resuming:
+```bash
+node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs jobs update-step "$JOB_PATH" $FAILED_INDEX pending
+```
+
+**If `completedCount > 0`** (this is a resume): Display skip summary:
+```
+Skipping {completedCount} completed steps, resuming from step {nextStepIndex + 1}: {step.command} {step.args}
+```
+</step>
+
+<step name="execute_steps">
+Initialize tracking variables:
+- `START_TIME` = current timestamp (for elapsed time calculation)
+- `AUTO_RESOLVE_COUNT` = 0 (tracks auto-resolved prompts across all steps)
+- `GAP_FIX_CYCLE` is loaded from the job file header in `parse_job_state` (not initialized here)
+- `PHASE_GAP_FIX_CYCLE` is loaded from the job file header in `parse_job_state` (not initialized here)
+- `PHASE_FIX_CYCLE_PHASE` tracks which phase the counter applies to
+
+Loop through steps starting from `nextStepIndex`.
+
+**Phase counter reset:** Before executing any step, check if the step's command is `plan-phase` or `map-codebase`. If so, reset `PHASE_GAP_FIX_CYCLE = 0` and `PHASE_FIX_CYCLE_PHASE = null` (a new phase is starting, so the previous phase's fix counter no longer applies).
+
+**For each step:**
+
+1. **Display start banner:**
+   ```
+   Step {index+1}/{stepCount} [{elapsed}] > {command} {args_without_auto_flag}
+   ```
+   Where `{elapsed}` is formatted as `Xm Ys` since job start. Strip `--auto` flags from display but preserve them in the actual subagent invocation.
+
+2. **Mark step in-progress** with timestamp:
+   ```bash
+   node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs jobs update-step "$JOB_PATH" $INDEX in-progress --timestamp "$(date -u +%Y-%m-%dT%H:%M:%SZ)"
+   ```
+
+3. **Spawn subagent** via Task tool:
+   ```
+   Task(
+     prompt="Execute /dgs:{command} {args}.
+       <job-mode>silent</job-mode>
+       Read the command file at ~/.claude/commands/dgs/{command}.md
+       and follow its workflow end-to-end.
+       You are running inside a job -- do NOT prompt the user for input.
+       Auto-resolve all interactive prompts per silent mode rules.
+       Report your result as a single line: SUCCESS or FAILED: <reason>"
+   )
+   ```
+   The `{command}` and `{args}` come directly from the step's parsed data.
+
+4. **On success:** Mark step completed with timestamp:
+   ```bash
+   node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs jobs update-step "$JOB_PATH" $INDEX completed --timestamp "$(date -u +%Y-%m-%dT%H:%M:%SZ)"
+   ```
+   Display one-line result:
+   ```
+   OK {command} {args_display} ({duration})
+   ```
+
+5. **On failure:** Mark step failed with timestamp and error:
+   ```bash
+   node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs jobs update-step "$JOB_PATH" $INDEX failed --timestamp "$(date -u +%Y-%m-%dT%H:%M:%SZ)" --error "{error_summary}"
+   ```
+   Update header Status to `failed`:
+   ```bash
+   node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs jobs update-header "$JOB_PATH" Status failed
+   ```
+   Display error summary and restart hint:
+   ```
+   FAILED {command} {args_display} ({duration})
+   Error: {error_summary}
+
+   Fix the issue, then run /dgs:run-job {version} to resume from step {index+1}
+   ```
+
+   **Generate job summary on failure:**
+   ```bash
+   SUMMARY=$(node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs jobs generate-summary "$VERSION")
+   ```
+   Parse the result. If `found: true`, write the `content` field to `${jobs_root}/in-progress/job-{version}-SUMMARY.md` using the Write tool (job stays in in-progress/ on failure).
+   Display: `Job summary written to ${jobs_root}/in-progress/job-{version}-SUMMARY.md`
+
+   **HALT immediately.** Do not proceed to the next step.
+
+6. **After an audit-milestone step completes successfully:** Execute the `handle_audit_result` logic (see below).
+
+6b. **After an audit-phase step completes successfully:** Execute the `handle_phase_audit_result` logic (see below). Detection is based on the step's `command` field: if `command === 'audit-milestone'` use `handle_audit_result`, if `command === 'audit-phase'` use `handle_phase_audit_result`.
+
+7. **Re-parse the job file** after each step to get updated state (stepCount may change after gap-fix insertion):
+   ```bash
+   JOB=$(node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs jobs parse "$JOB_PATH")
+   ```
+   Update `stepCount` and the steps array from the fresh parse.
+</step>
+
+<step name="handle_audit_result">
+After an `audit-milestone` step completes successfully, check the audit outcome.
+
+Note: --no-check jobs never trigger this code path because they have no audit-milestone step. The `check: false` header means no `audit-milestone` step is generated by `generateMilestoneSteps`, so handle_audit_result is never reached.
+
+Note: The original complete-milestone step (if present) remains at its position after the original
+audit step. Gap-fix steps (including re-audit) are inserted between the original audit step and
+complete-milestone. When the re-audit passes, the loop naturally reaches complete-milestone.
+If the re-audit finds MORE gaps, another cycle inserts steps after THAT re-audit, further
+deferring complete-milestone. This is correct -- complete-milestone only runs after a clean audit.
+
+1. **Read audit status:**
+   ```bash
+   AUDIT_STATUS=$(grep -m1 '^status:' ${project_root}/*MILESTONE-AUDIT.md 2>/dev/null | cut -d: -f2 | tr -d ' ' || echo "not_found")
+   ```
+
+2. **If `passed`:**
+
+   - If `GAP_FIX_CYCLE > 0` (audit passed AFTER gap-fix cycles): Display success banner:
+     ```
+     === AUDIT PASSED after {GAP_FIX_CYCLE} gap-fix cycle(s) ===
+     ```
+   - If `GAP_FIX_CYCLE == 0` (audit passed first time): Display clean banner:
+     ```
+     Audit passed -- no gaps found. Proceeding to complete milestone.
+     ```
+   - Continue to the next step (should be `complete-milestone`).
+
+3. **If `gaps_found`:**
+
+   Increment `GAP_FIX_CYCLE`.
+
+   **3a. Check cycle limit (AUDT-03):**
+   If `GAP_FIX_CYCLE > 3`:
+   - Read remaining gap details from MILESTONE-AUDIT.md for the halt message:
+     ```bash
+     GAPS_SUMMARY=$(grep -A 5 'gaps:' ${project_root}/*MILESTONE-AUDIT.md 2>/dev/null | head -10)
+     ```
+   - Display halt message:
+     ```
+     Gap closure cycle limit reached (3/3). Remaining gaps require manual investigation.
+
+     Remaining gaps:
+     {GAPS_SUMMARY}
+
+     Suggested next steps:
+     1. Review: cat ${project_root}/*MILESTONE-AUDIT.md
+     2. Fix manually or run: /dgs:plan-milestone-gaps
+     3. Resume: /dgs:run-job {VERSION}
+     ```
+   - Update header Status to `failed`:
+     ```bash
+     node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs jobs update-header "$JOB_PATH" Status failed
+     ```
+   - **HALT immediately.**
+
+   **3b. Auto-approve gap-fix insertion:**
+   The 3-cycle limit in 3a is the safety net. No user prompt needed.
+
+   Display:
+   ```
+   Auto-approving gap-fix insertion (cycle {GAP_FIX_CYCLE}/3)
+   ```
+
+   **3c. Display cycle start banner:**
+   ```
+   === Gap-Fix Cycle {GAP_FIX_CYCLE}/3 ===
+   ```
+
+   **3d. Insert plan-milestone-gaps step and execute it:**
+   - Spawn subagent for `plan-milestone-gaps {VERSION} --auto`:
+     ```
+     Task(
+       prompt="Execute /dgs:plan-milestone-gaps {VERSION} --auto.
+         <job-mode>silent</job-mode>
+         Read the command file and follow its workflow end-to-end.
+         Auto-resolve all interactive prompts.
+         Report: SUCCESS or FAILED: <reason>"
+     )
+     ```
+   - On failure: Update header Status to `failed`, display error message with restart hint, and **HALT immediately.**
+
+   **3e. Discover new phases from ROADMAP.md:**
+   - Briefly read ROADMAP.md to find new phases created by plan-milestone-gaps. Look for phases in the milestone range that were not present before the gap planner ran. The simplest approach: look for phase directories that have `discussed` or `researched` disk status (the gap planner creates phase directories with CONTEXT/RESEARCH but no PLANs yet), OR check for phases where `disk_status` changed since the last parse.
+   - Build an array of `{number, name}` objects for the new phases.
+
+   **3f. Insert gap-fix section into job file (AUDT-01, AUDT-04):**
+   - Use the CLI command to insert the section marker + gap-fix steps + re-audit step, and update the GapFixCycle header:
+     ```bash
+     node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs jobs insert-gap-fix-section "$JOB_PATH" $AUDIT_STEP_INDEX $GAP_FIX_CYCLE "$VERSION" '$PHASES_JSON'
+     ```
+     Where `$AUDIT_STEP_INDEX` is the zero-based index of the audit-milestone step that just completed, `$GAP_FIX_CYCLE` is the current cycle number, and `$PHASES_JSON` is a JSON array of `[{number, name}]` objects for the new phases.
+
+   **3g. Re-parse the job file** and continue the execution loop with the newly inserted steps:
+   ```bash
+   JOB=$(node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs jobs parse "$JOB_PATH")
+   ```
+   Update `stepCount` and steps array. The execution loop will pick up the new plan+execute+audit steps.
+</step>
+
+<step name="handle_phase_audit_result">
+After an `audit-phase` step completes successfully, check the phase audit outcome.
+
+**Key differences from milestone-level handle_audit_result:**
+- Uses `phase-uat-status` CLI (not grep of MILESTONE-AUDIT.md)
+- Checks for `diagnosed` status (not `gaps_found` -- audit-phase transitions through gaps_found to diagnosed)
+- Inserts 2 steps (not N steps with plan-milestone-gaps)
+- Limit of 2 cycles (not 3)
+- Does NOT spawn plan-milestone-gaps (uses execute-phase --gaps-only which runs existing gap closure plans)
+- Uses independent PhaseFixCycle counter/header (not GapFixCycle)
+
+1. **Extract phase number** from the completed step's args:
+   Parse the first positional argument from the step's args field (e.g., `args: "41"` or `args: "41 --rerun-failed"` both yield phase number `41`).
+
+2. **Read phase UAT status:**
+   ```bash
+   UAT_JSON=$(node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs phase-uat-status "${PHASE_NUMBER}" --raw 2>/dev/null)
+   ```
+   Parse the `status` field from the JSON result.
+
+3. **If `passed` or `complete`:**
+   Display:
+   ```
+   Phase {N} audit passed. Continuing to next step.
+   ```
+   Continue to the next step (no gap-fix needed).
+
+4. **If `diagnosed`:**
+
+   Increment `PHASE_GAP_FIX_CYCLE`.
+
+   **4a. Check cycle limit:**
+   If `PHASE_GAP_FIX_CYCLE > 2`:
+   - Display halt message:
+     ```
+     Phase {N} gap closure cycle limit reached (2/2). Gap(s) remain after 2 fix attempts.
+     Manual intervention required.
+
+     Suggested next steps:
+     1. Review UAT file for remaining gaps
+     2. Fix manually
+     3. Resume: /dgs:run-job {VERSION}
+     ```
+   - Update header Status to `failed`:
+     ```bash
+     node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs jobs update-header "$JOB_PATH" Status failed
+     ```
+   - **HALT immediately.**
+
+   **4b. Insert gap-fix steps:**
+   Display:
+   ```
+   Phase {N} audit diagnosed -- inserting gap-fix steps (cycle {PHASE_GAP_FIX_CYCLE}/2)
+   ```
+
+   ```bash
+   node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs jobs insert-phase-gap-fix "$JOB_PATH" $AUDIT_STEP_INDEX $PHASE_GAP_FIX_CYCLE "$PHASE_NUMBER"
+   ```
+
+   Where `$AUDIT_STEP_INDEX` is the zero-based index of the audit-phase step that just completed.
+
+   **4c. Re-parse the job file** and continue the execution loop:
+   ```bash
+   JOB=$(node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs jobs parse "$JOB_PATH")
+   ```
+   Update `stepCount` and steps array. The loop picks up the new execute-phase --gaps-only and audit-phase --rerun-failed steps.
+
+5. **If status is anything else** (e.g., `testing`, `gaps_found`, or `not_found`):
+   Log a warning but do not halt -- the audit may still be in progress or the UAT file may not exist yet. Continue to the next step.
+</step>
+
+<step name="complete_job">
+When all steps are completed (`nextStepIndex` is null after the loop):
+
+1. **Update header Status to `completed`:**
+   ```bash
+   node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs jobs update-header "$JOB_PATH" Status completed
+   ```
+
+2. **Move job to `completed/`:**
+   ```bash
+   node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs jobs move "$JOB_PATH" "${jobs_root}/completed"
+   ```
+
+3. **Generate job summary:**
+   ```bash
+   SUMMARY=$(node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs jobs generate-summary "$VERSION")
+   ```
+   Parse the result. If `found: true`, write the `content` field to `${jobs_root}/completed/job-{version}-SUMMARY.md` using the Write tool.
+   Display: `Job summary written to ${jobs_root}/completed/job-{version}-SUMMARY.md`
+
+4. **Display completion banner:**
+
+   If `AUTO_RESOLVE_COUNT` is 0:
+   ```
+   === JOB COMPLETE: {version} -- {stepCount}/{stepCount} steps in {total_elapsed} ===
+   ```
+
+   If `AUTO_RESOLVE_COUNT > 0`:
+   ```
+   === JOB COMPLETE: {version} -- {stepCount}/{stepCount} steps, {total_elapsed} total. {AUTO_RESOLVE_COUNT} auto-resolved prompts (see job file) ===
+   ```
+</step>
+
+</process>
+
+<orchestrator_constraints>
+The orchestrator MUST stay lean per EXEC-07:
+- Do NOT read any files beyond the job file and MILESTONE-AUDIT.md (phase UAT status is read via CLI, not file access)
+- Do NOT parse PLAN.md files, SUMMARY.md files, or codebase files
+- Do NOT load STATE.md or ROADMAP.md (except briefly after plan-milestone-gaps to discover new phases)
+- Do NOT read MILESTONE-AUDIT.md except in handle_audit_result after an audit-milestone step completes
+- Phase UAT status is read via `phase-uat-status` CLI in handle_phase_audit_result -- no direct file access
+- Each subagent gets ALL context it needs via its own command shim -- the orchestrator just passes the command name and args
+- Keep orchestrator context usage minimal regardless of job length
+</orchestrator_constraints>
+
+<success_criteria>
+- [ ] Job file located and moved to in-progress (or resumed if already there)
+- [ ] Each step spawns an isolated subagent with fresh context
+- [ ] Job file updated in real-time with step status and timestamps
+- [ ] Failed steps halt execution immediately with error + restart hint
+- [ ] Resume skips completed steps with skip summary
+- [ ] Milestone audit gap-fix cycle auto-approved with 3-cycle safety limit
+- [ ] Phase audit gap-fix cycle auto-approved with 2-cycle safety limit
+- [ ] PhaseFixCycle counter resets on plan-phase/map-codebase steps
+- [ ] Completed jobs moved to completed/ directory with banner
+- [ ] Orchestrator reads only job file and MILESTONE-AUDIT.md (phase UAT via CLI)
+- [ ] --dry-run flag displays step preview without executing
+- [ ] Job summary auto-generated on completion (written to completed/)
+- [ ] Job summary auto-generated on failure (written to in-progress/)
+</success_criteria>

package/deliver-great-systems/workflows/search.md

@@ -0,0 +1,130 @@
+<purpose>
+Search across ideas, specs, docs, and projects with fuzzy keyword matching. Display results grouped by type with context snippets, titles, and file paths. Read-only operation.
+</purpose>
+
+<context_tier>lite</context_tier>
+
+<required_reading>
+Read all files referenced by the invoking prompt's execution_context before starting.
+</required_reading>
+
+<process>
+
+<step name="load_context" priority="first">
+Load project context via tier system:
+
+```bash
+TIER_FILES=$(node "$HOME/.claude/deliver-great-systems/bin/dgs-tools.cjs" context load-tier lite --raw 2>/dev/null)
+```
+
+Use `TIER_FILES` JSON `files` array for project context (PROJECT.md, STATE.md, config.json).
+</step>
+
+<step name="parse_arguments">
+Extract the query string and filter flags from `$ARGUMENTS`.
+
+**Query extraction:**
+- The query is the first positional argument (may be quoted or unquoted)
+- Examples: `/dgs:search "auth tokens"`, `/dgs:search authentication --ideas-only`
+
+**Filter flags:**
+- `--ideas-only` — search only ideas
+- `--specs-only` — search only specs
+- `--docs-only` — search only docs
+- `--include-rejected` — include rejected ideas in results
+- `--tags TAG1,TAG2` — filter by tags (comma-separated, OR logic)
+
+Multiple type filters combine with OR: `--ideas-only --specs-only` shows both ideas and specs.
+
+**If no query found in arguments:**
+Use AskUserQuestion: "What would you like to search for?"
+Use the response as the query string.
+</step>
+
+<step name="run_search">
+Execute search via dgs-tools:
+
+```bash
+node ~/.claude/deliver-great-systems/bin/dgs-tools.cjs search "QUERY" [--ideas-only] [--specs-only] [--docs-only] [--include-rejected] [--tags TAGS] --raw
+```
+
+Build the command with applicable flags from step 1. Always include `--raw` for JSON output.
+
+Parse the JSON result. Expected structure:
+```json
+{
+  "query": "search terms",
+  "groups": [
+    {
+      "type": "ideas",
+      "results": [
+        { "title": "...", "path": "...", "snippet": "...", "id": 1, "state": "pending", "tags": [] }
+      ],
+      "total": 3,
+      "shown": 3,
+      "overflow": 0
+    }
+  ],
+  "total_matches": 3
+}
+```
+
+Each result contains: `title`, `path`, `snippet` (plus type-specific fields like `id`, `state`, `tags` for ideas; `id`, `status` for specs; `scope` for docs).
+</step>
+
+<step name="display_results">
+Format and display the search results.
+
+**If `total_matches === 0`:**
+
+Display:
+```
+No results found for "QUERY".
+
+Try broadening your search with fewer or different keywords, or remove scope filters to search all content types.
+```
+Exit.
+
+**Otherwise, iterate the `groups` array in order.** Each group has `type`, `results[]`, `total`, `shown`, and `overflow`. Display sections in the order groups appear (ideas, specs, docs, projects). Only show groups that have results.
+
+For each group:
+
+```
+### {type (title-cased)}
+
+**{title}**
+_{path}_
+> {snippet}
+
+**{title}**
+_{path}_
+> {snippet}
+
+_... and {overflow} more in {type}_
+```
+
+Display rules:
+- **Type headers** derived from group `type` field: `### Ideas`, `### Specs`, `### Documents`, `### Projects`
+- **Title** in bold on its own line
+- **Path** in italics on the next line (from `path` field, not `filePath`)
+- **Snippet** as a blockquote (indented with `>`)
+- **Overflow line** only shown if `overflow > 0` for that group
+- Skip groups entirely if `results` array is empty
+
+**Total count at bottom:**
+
+```
+Found {total_matches} results for "{query}"
+```
+</step>
+
+</process>
+
+<success_criteria>
+- [ ] Query extracted from arguments or prompted via AskUserQuestion
+- [ ] Filter flags parsed and passed to dgs-tools.cjs
+- [ ] Results displayed grouped by type in fixed order
+- [ ] Each result shows title, path, and context snippet
+- [ ] Overflow indicator shown when more results exist
+- [ ] Empty state shows helpful message with suggestions
+</success_criteria>