all-hands-cli 0.1.5 → 0.1.7

package/.allhands/harness/src/lib/opencode/prompts/solutions-aggregator.md

@@ -0,0 +1,97 @@
+# Solutions Aggregator
+
+You synthesize documented solutions and project memories into task-relevant guidance. The caller needs actionable knowledge from past learnings -- not a catalog of files.
+
+## Core Principle
+
+Extract what matters for the task. Every piece of guidance must be grounded in solution content or memory entries:
+- BAD: "Consider checking for similar issues in the codebase..."
+- GOOD: "The solution `unix-socket-path-length-hooks-20250115.md` documents that socket paths exceeding 104 chars cause ENOENT -- use path hashing as described in `docs/solutions/infrastructure/unix-socket-path-length-hooks-20250115.md`"
+
+## Input Format
+
+You receive JSON with:
+1. `query`: The user's task description or question
+2. `solutions`: Array of matched solutions, each containing:
+   - `title`: Solution title from frontmatter
+   - `path`: Relative file path
+   - `severity`: Issue severity
+   - `problem_type`: Category of problem
+   - `component`: Affected component
+   - `tags`: Search tags
+   - `content`: Full solution body (without frontmatter)
+3. `memories`: Array of all memory entries from `docs/memories.md`, each containing:
+   - `name`: Memory identifier
+   - `domain`: One of planning, validation, implementation, harness-tooling, ideation
+   - `source`: user-steering or agent-inferred
+   - `description`: Learning description
+
+## Expansion Protocol
+
+Need content from a referenced file (e.g., a linked spec or solution)? Output:
+```
+EXPAND: <file_path>
+```
+
+You'll receive the content. Max 3 expansions. Only expand if the file path suggests direct relevance to the query.
+
+## Output Format
+
+Return ONLY valid JSON:
+
+```json
+{
+  "guidance": "Task-relevant synthesis: what patterns to follow, what to avoid, key learnings. Ground every statement in solution content or memory entries. 3-6 sentences max.",
+  "relevant_solutions": [
+    {
+      "title": "Solution title",
+      "file": "docs/solutions/category/filename.md",
+      "relevance": "Why this solution matters for the query",
+      "key_excerpts": ["Specific actionable insights extracted from the solution"],
+      "related_memories": ["Memory names that relate to this solution"]
+    }
+  ],
+  "memory_insights": [
+    {
+      "name": "Memory name",
+      "domain": "domain",
+      "source": "source",
+      "relevance": "Why this memory matters for the query"
+    }
+  ],
+  "design_notes": ["Architectural constraints or patterns from solutions that affect the task"]
+}
+```
+
+## Field Guidelines
+
+**guidance**:
+- Synthesize across matched solutions and relevant memories into coherent task guidance
+- Include specific patterns, workarounds, and constraints
+- Mention file paths and memory names for attribution
+- If solutions encode anti-patterns, state them as warnings
+
+**relevant_solutions** (ranked by relevance to query):
+- `title`: Solution title from frontmatter
+- `file`: Path to solution file
+- `relevance`: One sentence -- why does this solution matter for the task?
+- `key_excerpts`: 1-4 specific, actionable insights extracted verbatim or closely paraphrased from the solution
+- `related_memories`: Memory names that provide additional context for this solution (may be empty)
+
+**memory_insights** (only include relevant memories):
+- `name`: Memory identifier
+- `domain`: Memory domain
+- `source`: user-steering or agent-inferred
+- `relevance`: One sentence -- why does this memory matter for the query?
+
+**design_notes** (optional, max 3):
+- Only include if solutions or memories explicitly discuss design rationale or constraints
+- Format: "[Constraint]: [Detail]" e.g. "Socket path limit: Unix domain sockets have a 104-char path limit on macOS"
+
+## Anti-patterns
+
+- Generic advice not grounded in solution or memory content
+- Copying entire solution files instead of extracting task-relevant parts
+- Including solutions or memories that aren't relevant to the query
+- Restating the query as guidance
+- Listing every memory entry regardless of relevance

package/.allhands/harness/src/lib/opencode/runner.ts

@@ -7,6 +7,7 @@ import { createOpencode } from "@opencode-ai/sdk";
 import { existsSync, readFileSync, statSync } from "fs";
 import { join } from "path";
 import { logCommandStart, logCommandSuccess, logCommandError } from "../trace-store.js";
+import { sendNotification } from "../notification.js";
 import type { AgentConfig, AgentResult } from "./index.js";
 import { loadProjectSettings } from "../../hooks/shared.js";
 
@@ -17,6 +18,7 @@ const DEFAULT_TIMEOUT_MS = 60000;
 // Model from settings, undefined means use opencode default
 const settings = loadProjectSettings();
 const SETTINGS_AGENT_MODEL = settings?.opencodeSdk?.model?.trim() || undefined;
+const SETTINGS_FALLBACK_MODEL = settings?.opencodeSdk?.fallbackModel?.trim() || undefined;
 
 export class AgentRunner {
   private readonly projectRoot: string;
@@ -27,12 +29,99 @@ export class AgentRunner {
 
   /**
    * Execute an agent with given config and user message.
-   * Spawns server, creates session, sends message, handles expansions, cleans up.
+   * Tries the primary model first, then falls back to the fallback model if configured.
    */
   async run<T>(config: AgentConfig, userMessage: string): Promise<AgentResult<T>> {
+    const runStart = Date.now();
+    const primaryModel = config.model ?? SETTINGS_AGENT_MODEL;
+    const fallbackModel = SETTINGS_FALLBACK_MODEL;
+
+    const primaryResult = await this.executeWithModel<T>(config, userMessage, primaryModel);
+
+    if (primaryResult.success) {
+      logCommandSuccess("opencode.agent.run.complete", {
+        agent: config.name,
+        model: primaryModel ?? "opencode-default",
+        outcome: "primary_success",
+        time_taken: Date.now() - runStart,
+      });
+      return primaryResult;
+    }
+
+    // Primary failed — attempt fallback
+    if (fallbackModel && fallbackModel !== primaryModel) {
+      sendNotification({
+        title: "Model Fallback",
+        message: `Primary model ${primaryModel ?? "opencode-default"} failed for ${config.name}: ${primaryResult.error}. Retrying with ${fallbackModel}...`,
+        type: "alert",
+      });
+
+      logCommandStart("opencode.agent.run.fallback", {
+        agent: config.name,
+        primaryModel: primaryModel ?? "opencode-default",
+        fallbackModel,
+        primaryError: primaryResult.error,
+      });
+
+      const fallbackResult = await this.executeWithModel<T>(config, userMessage, fallbackModel);
+
+      if (fallbackResult.success) {
+        const result = {
+          ...fallbackResult,
+          metadata: {
+            ...fallbackResult.metadata!,
+            fallback: true,
+            primary_error: primaryResult.error,
+          },
+        };
+        logCommandSuccess("opencode.agent.run.complete", {
+          agent: config.name,
+          model: fallbackModel,
+          outcome: "fallback_success",
+          time_taken: Date.now() - runStart,
+        });
+        return result;
+      }
+
+      // Both failed
+      sendNotification({
+        title: "Model Failure",
+        message: `Both ${primaryModel ?? "opencode-default"} and fallback ${fallbackModel} failed for ${config.name}.`,
+        type: "alert",
+        sound: "Basso",
+      });
+
+      logCommandError("opencode.agent.run.complete", fallbackResult.error ?? "unknown", {
+        agent: config.name,
+        model: fallbackModel,
+        outcome: "both_failed",
+        time_taken: Date.now() - runStart,
+      });
+      return fallbackResult;
+    }
+
+    // No fallback configured
+    sendNotification({
+      title: "Model Failure",
+      message: `Model ${primaryModel ?? "opencode-default"} failed for ${config.name}. No fallback configured.`,
+      type: "alert",
+      sound: "Basso",
+    });
+
+    logCommandError("opencode.agent.run.complete", primaryResult.error ?? "unknown", {
+      agent: config.name,
+      model: primaryModel ?? "opencode-default",
+      outcome: "no_fallback",
+      time_taken: Date.now() - runStart,
+    });
+    return primaryResult;
+  }
+
+  /**
+   * Core execution: spawn server, create session, send prompts, handle expansions, parse JSON.
+   */
+  private async executeWithModel<T>(config: AgentConfig, userMessage: string, model: string | undefined): Promise<AgentResult<T>> {
     const startTime = Date.now();
-    // Use config.model if specified, else settings AGENT_MODEL, else opencode default
-    const model = config.model ?? SETTINGS_AGENT_MODEL;
     logCommandStart("opencode.agent.run", {
       agent: config.name,
       model: model ?? "opencode-default",
@@ -126,12 +215,14 @@ export class AgentRunner {
           throw new Error("Failed to parse agent response as JSON");
         }
 
+        const retryDurationMs = Date.now() - startTime;
         logCommandSuccess("opencode.agent.run", {
           agent: config.name,
           expansions: expansionCount,
           retry: true,
           model: model ?? "opencode-default",
-          duration_ms: Date.now() - startTime,
+          duration_ms: retryDurationMs,
+          time_taken: retryDurationMs,
         });
 
         return {
@@ -139,7 +230,7 @@ export class AgentRunner {
           data: retryParsed,
           metadata: {
             model: model ?? "opencode-default",
-            duration_ms: Date.now() - startTime,
+            duration_ms: retryDurationMs,
           },
         };
       }
@@ -149,6 +240,7 @@ export class AgentRunner {
         expansions: expansionCount,
         model: model ?? "opencode-default",
         duration_ms: durationMs,
+        time_taken: durationMs,
       });
 
       return {
@@ -167,6 +259,7 @@ export class AgentRunner {
         agent: config.name,
         model: model ?? "opencode-default",
         duration_ms: durationMs,
+        time_taken: durationMs,
       });
 
       return {

package/.allhands/settings.json

@@ -36,7 +36,8 @@
     "compactionProvider": "gemini"
   },
   "opencodeSdk": {
-    "model": "opencode/gpt-5-nano",
+    "model": "opencode/minimax-m2.1-free",
+    "fallbackModel": "opencode/gpt-5-nano",
     "codesearchToolBudget": 12
   },
   "spawn": {

package/.allhands/skills/harness-maintenance/SKILL.md

@@ -335,7 +335,7 @@ Per **Context is Precious**, agents only see what they need when they need it.
 
 ### Flow Referencing
 ```markdown
-- Read `.allhands/flows/shared/SKILL_EXTRACTION.md` and follow its instructions
+- Read `.allhands/flows/shared/UTILIZE_VALIDATION_TOOLING.md` and follow its instructions
 ```
 
 ### Inputs/Outputs Pattern

package/.allhands/skills/harness-maintenance/references/harness-skills.md

@@ -35,7 +35,7 @@ Skills are discovered via glob matching against the files an agent is working on
 3. Matching skill(s) are surfaced to the agent
 4. Agent reads `SKILL.md` hub for routing context
 
-List all skills: `ah skills list`
+Search skills: `ah skills search "<query>" --paths <files>`
 
 ## Hub-and-Spoke Pattern
 

package/.allhands/skills/harness-maintenance/references/knowledge-compounding.md

@@ -20,17 +20,12 @@ Run `ah schema <type> body` to see the body format (not just frontmatter).
 
 ## Knowledge Indexes
 
-### Solutions (`docs/solutions/`)
-Reusable patterns discovered during work. Searchable by future agents:
-- `ah solutions search "<keywords>"` — Find relevant past solutions
+### Solutions (`docs/solutions/`) + Memories (`docs/memories.md`)
+Reusable patterns and lightweight learnings discovered during work. Searchable by future agents:
+- `ah solutions search "<keywords>"` — Find relevant past solutions with memory context
 - Solutions are created when an agent discovers a reusable pattern worth preserving
-- Per **Knowledge Compounding**, solutions prevent re-discovery of known patterns
-
-### Memories (`ah memories`)
-Agent learnings and engineer preferences that persist across sessions:
-- `ah memories search "<keywords>"` — Find relevant learnings
-- Captures: debugging insights, preference decisions, architectural rationale
-- Per **Knowledge Compounding**, memories prevent repeated mistakes
+- Memories capture debugging insights, preference decisions, architectural rationale
+- Per **Knowledge Compounding**, solutions and memories prevent re-discovery of known patterns
 
 ### Knowledge Docs
 Codebase knowledge indexed for semantic search:

package/.allhands/skills/harness-maintenance/references/validation-tooling.md

@@ -42,10 +42,19 @@ Per **Frontier Models are Capable** and **Context is Precious**:
 - **`--help` as prerequisite**: Suites MUST instruct agents to pull `<tool> --help` before any exploration — command vocabulary shapes exploration quality. The suite MUST NOT replicate full command docs.
 - **Inline command examples**: Weave brief examples into use-case motivations as calibration anchors — not exhaustive catalogs, not separated command reference sections.
 - **Motivation framing**: Frame around harness value: reducing human-in-loop supervision, verifying code quality, confirming implementation matches expectations.
-- **Exploration categories**: Describe with enough command specificity to orient, not prescriptive sequences that constrain.
+- **Exploration categories**: Describe with enough command specificity to orient. For untested territory, prefer motivations over prescriptive sequences — the agent extrapolates better from goals than rigid steps. For patterns verified through testing, state them authoritatively (see below).
 
 Formula: **motivations backed by inline command examples + `--help` as prerequisite and progressive disclosure**. Commands woven into use cases give direction; `--help` reveals depth.
 
+### Proven vs Untested Guidance
+
+Validation suites should be grounded in hands-on testing against the actual repo, not theoretical instructions. The level of authority in how guidance is written depends on whether it has been verified:
+
+- **Proven patterns** (verified via the Tool Validation Phase): State authoritatively within use-case motivations — the pattern is established fact, not a suggestion. These override generic tool documentation when they conflict. Example: "`xctrace` requires `--device '<UDID>'` for simulator" is a hard requirement discovered through testing, stated directly alongside the motivation (why: `xctrace` can't find simulator processes without it). The motivation formula still applies — proven patterns are *authoritative examples within motivations*, not raw command catalogs.
+- **Untested edge cases** (not yet exercised in this repo): Define the **motivation** (what the agent should achieve and why) and reference **analogous solved examples** from proven patterns. Do NOT write prescriptive step-by-step instructions for scenarios that haven't been verified — unverified prescriptions can mislead the agent into rigid sequences that don't match reality. Instead, trust that a frontier model given clear motivation and a reference example of how a similar problem was solved will extrapolate the correct approach through stochastic exploration.
+
+**Why this matters**: Frontier models produce emergent, adaptive behavior when given goals and reference points. Unverified prescriptive instructions constrain this emergence and risk encoding incorrect assumptions. Motivation + examples activate the model's reasoning about the problem space; rigid untested instructions bypass it. The Tool Validation Phase exists to convert untested guidance into proven patterns over time — the crystallization lifecycle in action.
+
 ### Evidence Capture
 
 Per **Quality Engineering**, two audiences require different artifacts:

package/.allhands/skills/harness-maintenance/references/writing-flows.md

@@ -48,7 +48,7 @@ Per **Knowledge Compounding**:
 
 ### Progressive Disclosure Pattern
 ```markdown
-- Read `.allhands/flows/shared/SKILL_EXTRACTION.md` and follow its instructions
+- Read `.allhands/flows/shared/UTILIZE_VALIDATION_TOOLING.md` and follow its instructions
 ```
 
 Sub-flows use `<inputs>` and `<outputs>` tags for execution-agnostic subtasks. This decouples the flow from its caller — any agent can execute it given the right inputs.

package/CLAUDE.md

@@ -2,5 +2,5 @@
 
 When debugging .allhands , use the ah trace --help command for the tools to investigate the trace entries.
 
-When modifying ANY `.allhands/` files, discover the `harness-maintenance` skill via `ah skills list` and follow its routing table for domain-specific guidance.
+When modifying ANY `.allhands/` files, discover the `harness-maintenance` skill via `ah skills search` and follow its routing table for domain-specific guidance.
 

package/docs/flows/compounding.md

@@ -79,7 +79,7 @@ The flow produces three distinct knowledge artifacts:
 
 | Artifact | Location | Purpose |
 |----------|----------|---------|
-| Memories | `docs/memories.md` | Lightweight learnings searchable via `ah memories search` |
+| Memories | `docs/memories.md` | Lightweight learnings searchable via `ah solutions search` |
 | Solutions | `docs/solutions/<category>/` | Detailed problem-solution documentation for non-trivial issues |
 | Spec Finalization | `.planning/<spec>/spec.md` | Historical record with implementation reality vs. original plan |
 
@@ -108,7 +108,7 @@ flowchart TD
     D -->|Defer| F
 ```
 
-Inline updates (skills, validation suites) require engineer approval. Structural changes always go through a spec. Deferred items are documented in `docs/memories.md` under "Deferred Harness Improvements."
+Inline updates (skills, validation suites) require engineer approval. Structural changes always go through a spec. Deferred items are documented in `docs/memories.md` under "Deferred Harness Improvements" (searchable via `ah solutions search`).
 
 ### Crystallization Promotion
 

package/docs/flows/plan-deepening-and-research.md

@@ -36,7 +36,7 @@ This flow governs how agents explore the codebase without consuming excessive co
 | 1st | `ah knowledge docs search` | Any discovery task -- returns engineered knowledge with "why" context |
 | 2nd | `tldr semantic search` / grep | Knowledge search insufficient, need code-level patterns |
 | 3rd | LSP | Known symbol name from knowledge search results |
-| 4th | `ah solutions search` / `ah memories search` | Similar problem solved before, or engineer preferences exist |
+| 4th | `ah solutions search` | Similar problem solved before, engineer preferences, or prior insights |
 | 5th | `ast-grep` | Structured code pattern matching as last resort |
 
 Knowledge search results include `insight` (engineering knowledge), `lsp_entry_points` (files with exploration rationale), and `design_notes` (architectural decisions). This is richer than raw file reads and costs fewer tokens.
@@ -86,7 +86,7 @@ flowchart LR
 Each axis runs in parallel:
 
 - **Skill application**: Matches available skills to plan domains, extracts patterns and gotchas
-- **Solutions search**: Checks `ah solutions search` and `ah memories search` for relevant past learnings
+- **Solutions search**: Checks `ah solutions search` for relevant past learnings (includes memory context)
 - **Codebase patterns**: Discovers existing implementations of similar patterns via `CODEBASE_UNDERSTANDING.md`
 - **External research**: For novel technologies or high-risk domains via `RESEARCH_GUIDANCE.md`
 

package/docs/flows/validation-and-skills-integration.md

@@ -88,17 +88,23 @@ Stochastic exploration during implementation is not ordered -- agents follow mod
 
 ## Skill Extraction
 
-[ref:.allhands/flows/shared/SKILL_EXTRACTION.md::03a6816]
-
-This flow finds and distills domain expertise from skill files into actionable prompt guidance. Per **Knowledge Compounding**, skills are "how to do it right" -- expertise that compounds across prompts.
+This is handled by `ah skills search`, which finds and distills domain expertise from skill files into actionable prompt guidance. Per **Knowledge Compounding**, skills are "how to do it right" -- expertise that compounds across prompts.
 
 ### Extraction Pipeline
 
-1. **Discover**: Run `ah skills list` to get available skills (name, description, globs, file path)
-2. **Match**: Same dual approach as validation -- glob patterns and semantic inference
-3. **Read**: Extract key patterns, best practices, and references from each `.allhands/skills/<name>/SKILL.md`
-4. **Synthesize**: Distill task-relevant knowledge (not full skill file copies)
-5. **Embed**: Add skill paths to `skills` frontmatter and embed guidance in prompt Tasks section
+```bash
+ah skills search "<task_description>" --paths <files_being_touched...>
+```
+
+Internally, the command performs:
+
+1. **Discover**: Lists all available skills from `.allhands/skills/*/SKILL.md`
+2. **Match**: Keyword scoring (name, description, globs) + path boosting via `--paths` glob matching
+3. **Read**: Reads SKILL.md body content and discovers reference docs for matched skills
+4. **Synthesize**: AI aggregator subagent distills task-relevant knowledge with source attribution
+5. **Return**: Structured JSON with `guidance`, `relevant_skills` (excerpts + references), and `design_notes`
+
+Add skill paths (from `relevant_skills[].file`) to `skills` frontmatter and embed `guidance` in prompt Tasks section.
 
 ### Key Distinction from Validation
 

package/docs/flows/wip/wip-flows.md

@@ -99,4 +99,4 @@ Memories are prioritized by domain match, keyword overlap, and source authority
 | Ideation Session | Similar initiatives, prior engineer preferences |
 | Compounding | Verify memory doesn't already exist before adding |
 
-For detailed technical solutions beyond lightweight memories, the recall flow also directs callers to `ah solutions search`.
+For detailed technical solutions beyond lightweight memories, the recall flow also directs callers to `ah solutions search` (which now includes memory context in its aggregation).

package/docs/harness/cli/search-commands.md

@@ -1,10 +1,10 @@
 ---
-description: "Knowledge retrieval commands for agents: local solution and memory search via keyword scoring, plus external web research through Perplexity, Tavily, and Context7 integrations."
+description: "Knowledge retrieval commands for agents: local solution search (with memory aggregation) via keyword scoring and AI synthesis, plus external web research through Perplexity, Tavily, and Context7 integrations."
 ---
 
 ## Intent
 
-Agents need to retrieve knowledge from two distinct sources: **local project knowledge** (solutions, memories) and **external web knowledge** (documentation, research). The search commands provide a unified CLI surface for both, with consistent JSON output that agents can parse. The local search commands use weighted keyword scoring against structured frontmatter rather than full-text search, trading recall for precision and avoiding embedding infrastructure.
+Agents need to retrieve knowledge from two distinct sources: **local project knowledge** (solutions + memories) and **external web knowledge** (documentation, research). The search commands provide a unified CLI surface for both, with consistent JSON output that agents can parse. The local search commands use weighted keyword scoring against structured frontmatter rather than full-text search, trading recall for precision and avoiding embedding infrastructure. Solutions search includes AI aggregation that synthesizes matched solutions with memory context from `docs/memories.md`.
 
 ## Local Knowledge Search
 
@@ -25,29 +25,19 @@ Scoring weights determine field importance:
 
 [ref:.allhands/harness/src/commands/solutions.ts:scoreSolution:19e47dd] computes a cumulative score per keyword across all fields. [ref:.allhands/harness/src/commands/solutions.ts:extractKeywords:19e47dd] handles quoted phrases and whitespace splitting, allowing queries like `"tmux session" timeout`.
 
-### Memories Search
+### Memory Integration
 
-[ref:.allhands/harness/src/commands/memories.ts:searchMemories:49c8ec9] searches project memories stored as markdown tables in `docs/memories.md`. Each table row has Name, Domain, Source, and Description columns grouped under section headers.
+Solutions search automatically loads all memory entries from `docs/memories.md` and includes them in the AI aggregation context. This means a single `ah solutions search` call returns synthesized guidance from both solution files and memory entries, with `memory_insights` in the output identifying relevant memories. Use `--no-aggregate` to get raw keyword matches without memory context.
 
-[ref:.allhands/harness/src/commands/memories.ts:scoreMemory:49c8ec9] applies similar weighted scoring:
+### Search Design
 
-| Field | Weight |
-|-------|--------|
-| name | 3 |
-| description | 2 |
-| domain | 2 |
-| source | 1 |
-
-Memories support additional filtering by `--domain` and `--source` before scoring, enabling queries like `ah memories search "hook" --domain planning`.
-
-### Shared Search Design
-
-Both local search commands share these characteristics:
+Solutions search has these characteristics:
 - Keyword extraction with quoted phrase support ([ref:.allhands/harness/src/commands/solutions.ts:extractKeywords:19e47dd])
 - Cumulative scoring across multiple fields
 - Results sorted by score descending, truncated to `--limit`
-- JSON output with `matchedFields` array explaining why each result matched
-- Zero external dependencies (pure filesystem reads + YAML parsing)
+- AI aggregation via solutions-aggregator agent (with graceful degradation to raw matches on failure)
+- JSON output with synthesized `guidance`, `relevant_solutions`, `memory_insights`, and `design_notes`
+- `--no-aggregate` flag for raw keyword matches with `matchedFields` array
 
 ## External Web Research
 

package/docs/memories.md

@@ -1,5 +1,5 @@
 ---
-description: "Lightweight learnings from past sessions, searchable via `ah memories search`. Captures technical patterns, engineer preferences, and harness behavior discoveries."
+description: "Lightweight learnings from past sessions, searchable via `ah solutions search` (included as memory context in aggregation). Captures technical patterns, engineer preferences, and harness behavior discoveries."
 ---
 
 # Memories

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "all-hands-cli",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "description": "Agentic harness for model-first software development",
   "type": "module",
   "bin": {

package/specs/workflow-domain-configuration.spec.md

@@ -63,7 +63,7 @@ Engineer expects the existing milestone workflow behavior to be fully preserved
 - Review options breakdown after jury with actionable options for engineer
 - Plan deepening option for complex/high-risk specs
 - Alignment doc decision recording: only deviations from recommendations (what was recommended, what was chosen, stated reasoning)
-- Solutions search and memories search during context gathering
+- Solutions search (includes memory context) during context gathering
 - Prompt output range: 5-15 coordinated prompts for milestone, 0-3 seed prompts for exploratory
 
 The milestone workflow domain config encodes the domain-specific knowledge (what to explore, what to consider, what to check). The unified flows preserve the orchestration logic (how to interview, how to spawn subtasks, how to sequence phases). The abstraction must not lose any of these practices — they are the result of iterative refinement and represent proven milestone development patterns.
@@ -114,7 +114,7 @@ For milestone domains, the spec planning flow must preserve the full planning pi
 - Plan verification self-check before jury (requirement coverage, task completeness, key links, scope sanity, validation coverage)
 - 4-member jury review (expectations fit, flow analysis, YAGNI, premortem) with review options breakdown
 - Plan deepening option for complex/high-risk specs
-- Solutions and memories search during context gathering
+- Solutions search (includes memory context) during context gathering
 - Decision recording: only deviations from recommendations
 
 The domain config determines which of these phases activate. Milestone activates all of them. Exploratory domains activate a subset (focused research, open question interview, seed prompt creation, no jury, no variants).

package/.allhands/flows/shared/SKILL_EXTRACTION.md

@@ -1,84 +0,0 @@
-<goal>
-Find and extract domain expertise from skills to embed in prompt instructions. Per **Knowledge Compounding**, skills are "how to do it right" - expertise that compounds across prompts.
-</goal>
-
-<inputs>
-- Files/domains involved in the implementation task
-- Nature of the changes (UI, native code, deployment, etc.)
-</inputs>
-
-<outputs>
-- Extracted knowledge distilled for prompt embedding
-- Sources consulted (skill file paths)
-</outputs>
-
-<constraints>
-- MUST run `ah skills list` to discover available skills
-- MUST match skills via both glob patterns AND description inference
-- MUST extract task-relevant knowledge, not copy entire skill files
-- MUST list sources consulted in output
-</constraints>
-
-## Step 1: Discover Available Skills
-
-- Run `ah skills list`
-- Returns JSON with: `name`, `description`, `globs`, `file` path
-
-## Step 2: Identify Relevant Skills
-
-Match skills using two approaches:
-
-**Glob pattern matching** (programmatic):
-- Compare files you're touching against each skill's `globs`
-- Skills with matching patterns are likely relevant
-
-**Description inference** (semantic):
-- Read skill descriptions
-- Match against task nature (UI, deployment, native modules, etc.)
-
-Select all skills that apply to implementation scope.
-
-## Step 3: Read Skill Documentation
-
-For each relevant skill, read the full file:
-- Read `.allhands/skills/<skill-name>/SKILL.md`
-
-Extract:
-- **Key patterns**: Code patterns, library preferences, common pitfalls
-- **Best practices**: Guidelines specific to this domain
-- **References**: Sub-documents within the skill folder
-
-## Step 4: Extract Knowledge for Prompt
-
-Synthesize skill content into actionable prompt guidance:
-- Distill key instructions
-- Include specific examples where relevant
-- Reference sources
-- Avoid duplication - extract what's task-relevant
-
-## Step 5: Output with Sources
-
-Provide:
-
-```
-## Skill-Derived Guidance
-
-### From building-expo-ui:
-- Use `<Link.Preview>` for context menus
-- Prefer `contentInsetAdjustmentBehavior="automatic"` over SafeAreaView
-
-### From react-native-best-practices:
-- Profile with React DevTools before optimizing
-- Use FlashList for lists with >50 items
-
-## Sources Consulted
-- .allhands/skills/building-expo-ui/SKILL.md
-- .allhands/skills/react-native-best-practices/SKILL.md
-```
-
-## For Prompt Curation
-
-When used via PROMPT_TASKS_CURATION:
-- Add skill file paths to prompt's `skills` frontmatter
-- Embed extracted guidance in prompt's Tasks section
-- Makes domain expertise explicit and immediately available to executors