all-hands-cli 0.1.0

package/.allhands/flows/harness/WRITING_HARNESS_VALIDATION_TOOLING.md

@@ -0,0 +1,27 @@
+<goal>
+Guide agents through validation suite creation. Per **Agentic Validation Tooling**, every validation domain has stochastic (exploratory) and deterministic (pass/fail) dimensions that compound through the crystallization lifecycle.
+</goal>
+
+<inputs>
+- Validation domain and scope
+- Tooling requirements (stochastic exploration, deterministic gating, or both)
+</inputs>
+
+<outputs>
+- Validation suite following harness conventions with both stochastic and deterministic dimensions
+</outputs>
+
+<constraints>
+- MUST include meaningful stochastic dimension — deterministic-only tools are test commands, not suites
+- MUST follow crystallization lifecycle: stochastic discovers, deterministic entrenches
+- NEVER create suites without clear validation domain justification
+</constraints>
+
+## Execution
+
+- Read `.allhands/principles.md` for first principle context
+- Run `ah skills list` to discover the `harness-maintenance` skill
+- Read the skill's `references/validation-tooling.md` for suite philosophy and crystallization patterns
+- Design the suite with both stochastic and deterministic sections
+- Validate suite existence threshold — ensure meaningful stochastic dimension exists
+- Test deterministic checks produce binary pass/fail results

package/.allhands/flows/shared/CODEBASE_UNDERSTANDING.md

@@ -0,0 +1,72 @@
+<goal>
+Enable context-efficient codebase exploration using intentional tooling. Per **Context is Precious**, minimize context window consumption while maximizing understanding.
+</goal>
+
+<constraints>
+
+- MUST use `ah knowledge docs search` FIRST for ANY DISCOVERY TASKS
+- MUST use `tldr` or LSP tool to get context from code files!
+- NEVER use the Read tool - unless absolutely necessary
+
+</constraints>
+
+## Search Tool Selection
+
+Choose the right tool for the query type:
+
+| Need | Tool | When |
+|------|------|------|
+| **Great codebase navigation tool AND documented knowledge!!** | `ah knowledge docs search` | "How does X work?", "Why is Y designed this way?" |
+| **Find relevant codebase patterns when knowledge search is not enough** | `tldr semantic search` or grep | Known string, error message, literal pattern |
+| **Find symbol definition - usually from symbols given by knowledge search** | LSP | Class, function, type by name |
+| **Past solutions** | `ah solutions search` | Similar problem solved before |
+| **Past learnings** | `ah memories search` | Engineer preferences, validation gaps, prior insights |
+| **Grep but better** | `ast-grep` | Known string, error message, literal pattern |
+
+### Search Flow
+
+```
+Engineer Task → Knowledge Docs Search → LSP on Referenced Symbols → Grep/ast-grep if needed
+```
+
+## Query Formatting
+
+Queries should be **complete sentences** with full context, not minimal keywords:
+
+```bash
+# GOOD - complete question with context
+ah knowledge docs search "how does the retry mechanism handle rate limits when calling external APIs"
+
+# BAD - keyword soup
+ah knowledge docs search "retry rate limit api"
+```
+
+## Response Interpretation
+
+Knowledge search returns:
+- `insight`: Engineering / Product knowledge with the "why"
+- `lsp_entry_points`: Key file references with exploration rationale and LSP symbols
+- `design_notes`: Relevant architectural decisions
+- `[ref:...]`: Contains file references and LSP symbols. Only returned if the full docs document is returned.
+
+## Decision Tree
+
+```
+Need codebase context?
+├─ Get relevant codebase direction with knowledge? → ah knowledge docs search
+    ├─ Aggregated result? → Follow lsp_entry_points (why field = priority)
+    └─ Direct result? → relevant_files + [ref:...] blocks → LSP on symbols
+├─ Know exact symbol? → LSP directly
+├─ Know semantic idea? → tldr semantic search / grep
+├─ Suspect a similar problem faced before? → ah solutions search + ah memories search first
+└─ ast-grep if still struggling
+```
+
+### Failure Recovery
+
+| Situation | Next Step |
+|-----------|-----------|
+| Knowledge docs search returns nothing | Try different semantic phrasing |
+| grep returns nothing | Try alternative names (error/exception/failure) |
+| LSP can't find symbol | Check import statements, search file contents |
+| Pattern not found | Widen search directory, check file extensions |

package/.allhands/flows/shared/CREATE_HARNESS_SPEC.md

@@ -0,0 +1,48 @@
+<goal>
+Create a harness improvement spec when compounding identifies systemic issues. Per **Prompt Files as Units of Work**, harness improvements go through the full loop.
+</goal>
+
+<inputs>
+- Engineer-selected improvement issues from compounding (one or more)
+- Problems encountered, fixes proposed
+- Per-tool impact map from compounding signal analysis (evidence for spec motivation)
+</inputs>
+
+<outputs>
+- Spec at `specs/roadmap/harness-<name>.spec.md`
+</outputs>
+
+<constraints>
+- MUST create spec, NOT implement directly
+- MUST get engineer confirmation
+- MUST scope to engineer-selected improvements from a single compounding session
+- Harness specs do NOT block feature specs
+</constraints>
+
+## Context & Impact
+
+Receive from compounding: improvement identified, problem it solves, evidence.
+
+Assess: affected flows/commands/hooks, new capability vs fix, risk level.
+
+## Engineer Interview
+
+Present: problem, proposed solution, impact scope, effort, urgency.
+
+If engineer declines: document in `docs/memories.md`, exit flow.
+
+## Spec Creation
+
+Use `name: harness-{name}` and `domain_name: harness` (triggers `harness-maintenance` skill during planning).
+
+Body sections: Problem Statement, Proposed Solution, Affected Components, Testing Strategy (brief - how to verify the improvement works).
+
+Follow `.allhands/flows/shared/CREATE_SPEC.md`.
+
+## Handoff
+
+Ask engineer: "This harness improvement spec is ready. Would you like to start working on it now?"
+
+If yes: checkout the branch and run `ah planning ensure`
+
+If no: inform engineer spec is saved in `specs/roadmap/` for later activation via TUI

package/.allhands/flows/shared/CREATE_SPEC.md

@@ -0,0 +1,41 @@
+<goal>
+Write a spec file with proper schema, persist to base branch. Single source of truth for spec creation.
+</goal>
+
+## Write Spec
+
+Run `ah schema spec` for the schema format. Write `specs/roadmap/{name}.spec.md` following the schema.
+
+## Branch Prefix Convention
+
+Per **Frontier Models are Capable**, derive the default branch prefix from the spec `type` field:
+
+| Spec Type | Branch Prefix |
+|-----------|---------------|
+| `milestone` (or missing) | `feature/` |
+| `investigation` | `fix/` |
+| `optimization` | `optimize/` |
+| `refactor` | `refactor/` |
+| `documentation` | `docs/` |
+| `triage` | `triage/` |
+
+The `branch` field on the spec is always the source of truth — this convention applies to the default suggestion when the spec doesn't specify one.
+
+## Create
+
+Run: `ah specs create specs/roadmap/{name}.spec.md --json`
+
+This assigns the branch name (using type-based prefix convention with collision handling), commits the spec file to the base branch, and pushes to origin. Parse `branch` from response for the final branch name. No branch is created at this step — branch creation happens at activation time.
+
+Run: `ah knowledge roadmap reindex`
+
+## Confirm
+
+Report spec name and branch to engineer.
+
+Ask: "Would you like to start working on this now?"
+
+If yes, activate the spec (which creates the branch and sets up planning):
+```bash
+ah specs activate {name}
+```

package/.allhands/flows/shared/CREATE_VALIDATION_TOOLING_SPEC.md

@@ -0,0 +1,70 @@
+<goal>
+Create a validation tooling spec for a new domain. Per **Prompt Files as Units of Work**, validation tooling is infrastructure that goes through the full harness loop.
+</goal>
+
+<inputs>
+- Gap analysis from ASSESS_VALIDATION_TOOLING
+- Original spec blocked by this tooling need
+</inputs>
+
+<outputs>
+- Spec at `specs/roadmap/validation-<name>.spec.md`
+- Original spec updated with `dependencies: [validation-<name>]`
+</outputs>
+
+<constraints>
+- MUST create spec, NOT implement tooling
+- MUST get engineer confirmation
+- MUST include CICD + meta-testing in acceptance criteria
+- MUST verify the validation domain has a meaningful stochastic dimension before creating a suite spec. Per **Agentic Validation Tooling**, deterministic-only tools (type checking, linting, formatting) are test commands — NOT suites.
+</constraints>
+
+## Domain Knowledge
+
+- Run `ah skills list` to discover the `harness-maintenance` skill
+- Read the skill's `references/validation-tooling.md` for suite writing philosophy, crystallization lifecycle, evidence capture patterns, and tool validation guidance
+
+## Research
+
+Read `.allhands/flows/shared/RESEARCH_GUIDANCE.md` and investigate:
+- Best practices: `ah perplexity research "best practices <validation_type> testing <technology>"`
+- Available tools: `ah tavily search "<technology> testing tools"`, `ah tools --list`
+- CICD patterns: `ah perplexity research "<validation_type> CICD GitHub Actions"`
+- Determine whether the domain has exploratory patterns that benefit from agent intuition (stochastic dimension). If the validation is purely deterministic (binary command output), it does not justify a suite — document it as a test command reference instead.
+
+If valuable MCP not integrated, note as acceptance criterion.
+
+## Tool Validation
+
+Per **Agentic Validation Tooling**, research produces assumptions; running the tool produces ground truth. Per **Ideation First**, prevents encoding untested assumptions.
+
+- Install and verify the tool responds to `--help` — internalize the full command vocabulary before anything else
+- Create a minimal test target (temp directory, not committed)
+- Execute representative stochastic workflows — discover commands, chaining, and the observe-act-verify loop
+- Document divergences from researched documentation — informs spec and engineer interview
+
+## Engineer Interview
+
+Present: recommended approach, alternatives, CICD impact, effort, MCP availability. Include divergences discovered during Tool Validation.
+
+Confirm engineer agrees and understands this creates a blocking dependency.
+
+## Spec Creation
+
+Use `name: validation-{name}` and `domain_name: infrastructure`.
+
+New suites must articulate both their stochastic and deterministic dimensions. Per **Agentic Validation Tooling**, the stochastic dimension justifies the suite's existence; the deterministic dimension provides CI/CD gating.
+
+Body sections: Context, Acceptance Criteria (setup, coverage, meta-testing, CICD, documentation), Technical Constraints, Out of Scope.
+
+Follow `.allhands/flows/shared/CREATE_SPEC.md`.
+
+Update original spec with `dependencies: [validation-{name}]`.
+
+## Handoff
+
+Ask engineer: "This validation tooling spec is ready and blocks your original work. Would you like to switch focus to it now?"
+
+If yes: checkout the branch and run `ah planning ensure`
+
+If no: inform engineer spec is saved and original spec is blocked until this is complete

package/.allhands/flows/shared/DOCUMENTATION_DISCOVERY.md

@@ -0,0 +1,123 @@
+<goal>
+Discover ALL documentable approaches/features within a domain. Per **Frontier Models are Capable**, identify engineering knowledge comprehensively - it's better to over-discover than under-discover.
+
+Engineering knowledge sources: prompts, commit messages, and alignment docs when provided (Incremental mode), otherwise infer decisions and intent from the code itself (Fill-the-Gaps mode).
+</goal>
+
+<inputs>
+- `domain`: Name of the domain to analyze
+- `source_paths`: Directories/files to scan
+- `exclude`: Glob patterns for files/directories to skip (from `.allhands/docs.json`)
+- `mode`: "fill-gaps" or "incremental"
+- `session_context`: (incremental only) Summary from alignment doc
+</inputs>
+
+<outputs>
+- List of approaches with associated files and symbols
+- Recommended documentation structure
+</outputs>
+
+<constraints>
+- MUST use `ah knowledge docs search` to check existing documentation coverage
+- MUST return structured approach list, not prose
+- MUST cover all significant features, grouping by feature to stay **under 20 approaches**
+- NEVER propose approaches already fully documented
+- NEVER split a single command/feature into multiple approaches
+</constraints>
+
+## Analysis Strategy
+
+Run `tldr structure <source_path>` to get full codemap, then identify **user-facing features and systems**.
+
+**Exclusion filtering**: If `exclude` patterns are provided, skip any files or directories matching those globs before analysis. Do not propose approaches for excluded paths and do not list excluded files in approach `files` arrays. Patterns are matched relative to project root.
+
+### What makes a good approach (= one doc file)?
+- A CLI command with all its implementation details
+- A subsystem that serves a clear purpose (e.g., "MCP integration", "TUI components")
+- A workflow or pattern used across the codebase
+- An integration with external services
+
+### What should NOT be separate approaches?
+- Helper functions (belong in parent feature's doc)
+- Internal utilities (group with related features)
+- Implementation details of a larger feature
+- Multiple files that serve the same purpose
+
+## Coverage Check
+
+- Run `ah knowledge docs search "<domain>"` to find existing docs
+- For each identified approach:
+  - Check if already documented
+  - If partial coverage, note gaps
+  - If no coverage, mark as new
+
+## Grouping Heuristics
+
+**One approach = one documentation file.** Group aggressively:
+
+| Pattern | Grouping |
+|---------|----------|
+| CLI command + all its helpers/implementation | **Single approach** |
+| Related utilities (even 5-10 functions) | **Single approach** |
+| Subsystem with multiple files serving one purpose | **Single approach** |
+| Large system with truly distinct user-facing parts | Multiple approaches |
+| Cross-cutting pattern used everywhere | Single pattern-focused approach |
+
+**Key principle**: Only create separate approaches when someone would realistically search for them as distinct topics. Most helper functions, internal utilities, and implementation details belong in their parent feature's doc.
+
+## Output Format
+
+Return structured YAML with **intelligent directory groupings**:
+
+```yaml
+domain: "<domain-name>"
+approaches:
+  - name: "<approach-name>"
+    description: "<one-line purpose>"
+    group: "<subdirectory-name>"  # e.g., "cli", "tui", "hooks", or null for flat
+    files:
+      - "<path/to/file.ts>"
+    symbols:
+      - "<FunctionName>"
+      - "<ClassName>"
+    existing_coverage: "none" | "partial" | "full"
+    notes: "<gaps or special considerations>"
+recommended_structure:
+  directories:
+    - name: "cli"
+      description: "Command-line interface commands"
+      approach_count: 16
+    - name: "tui"
+      description: "Terminal UI components"
+      approach_count: 4
+    # Groups with <3 approaches stay flat (group: null)
+  flat_files:
+    - "docs/<domain>/test-harness.md"  # Single approach, no subdirectory
+```
+
+### Directory Grouping Rules
+
+1. **Create subdirectory** when 3+ approaches share a logical category
+2. **Keep flat** when approaches don't group logically or group has <3 files
+3. **Name by concept**, not by source path (e.g., `cli/` not `commands/`)
+4. **Common groupings** to consider:
+   - `cli/` - Command implementations
+   - `tui/` - UI components
+   - `hooks/` - Hook categories
+   - `integrations/` - External service integrations
+   - `core/` - Core libraries (only if needed to disambiguate)
+
+## Completeness Check
+
+Before returning, verify:
+- Are major user-facing features covered?
+- Are key subsystems documented?
+- Have you grouped related functionality together?
+
+**Warning signs of over-discovery:**
+- More than 20 approaches for a domain
+- Multiple approaches for the same CLI command
+- Separate approaches for helper/utility functions
+- Approaches that would result in very short docs
+
+If you exceed 20 approaches, consolidate related ones until under the limit.

package/.allhands/flows/shared/DOCUMENTATION_WRITER.md

@@ -0,0 +1,101 @@
+<goal>
+Write documentation that exposes engineering knowledge via file references and LSP symbols. Per **Knowledge Compounding**, docs enable semantic discovery of code through compounded understanding of use cases, intent, and key decisions.
+
+Engineering knowledge sources: prompts, commit messages, and alignment docs when provided via `session_knowledge`, otherwise infer decisions and intent from the code itself.
+</goal>
+
+<inputs>
+- `domain`: Domain being documented
+- `approaches`: List of approaches with:
+  - `name`: Approach identifier
+  - `group`: Subdirectory name (or null for flat)
+  - `files`: Source files to document
+  - `symbols`: Key symbols to reference
+- `doc_directory`: Target directory for docs
+- `existing_docs`: Paths to edit (empty for new docs)
+- `session_knowledge`: (incremental only) Commit messages, alignment summary, prompt learnings
+</inputs>
+
+<outputs>
+- Documentation files with `[ref:file:Symbol]` placeholders
+- Created directories as needed
+</outputs>
+
+<constraints>
+- MUST follow `ah schema documentation` for frontmatter and file reference format
+- MUST use LSP symbols (function names, class names) in refs for searchability
+- MUST create directories before writing files
+- NEVER write command/installation guides - those belong in README.md
+- NEVER use a uniform template across docs - each doc's structure must be driven by its content type. Two docs about different topics should look different.
+</constraints>
+
+## Doc Quality Goals
+
+Per **Knowledge Compounding**, each doc should:
+
+1. **Expose engineering knowledge** - Use cases, intent, key decisions, trade-offs
+2. **Enable semantic discovery** - Descriptions that match how someone would search
+3. **Minimize token count** - Right-sized for indexing, not bloated
+
+## Format Selection
+
+Per **Frontier Models are Capable**, select the format that communicates the content best:
+
+| Content Type | Format |
+|---|---|
+| State transitions, lifecycles | Mermaid state diagram |
+| Multi-step processes, request flows | Mermaid sequence diagram |
+| Component relationships, data flow | Mermaid flowchart |
+| Feature comparisons, option matrices | Table |
+| Algorithm steps, retry/backoff logic | Numbered list with formula notation |
+| Conditional behavior, branching logic | Decision tree or nested bullets |
+
+Do NOT default to the same section pattern for every doc. A retry-backoff doc needs a delay formula table. An optimistic UI doc needs a state diagram. A CI pipeline doc needs a job dependency graph. Let the content drive the structure.
+
+## Writing Approach
+
+### For New Docs
+
+- Run `ah schema documentation` to get required frontmatter format
+- Read source files to understand the approach
+- Identify key entry points, core logic, and integration points
+- Structure freely - use whatever sections serve the content:
+  - Overview, Architecture, Patterns, Data Flow, Key Decisions
+  - Tables, diagrams (mermaid), lists - whatever communicates best
+- Embed refs throughout: `[ref:src/lib/semantic-search.ts:searchIndex]`
+
+### For Editing Existing Docs
+
+- Read existing doc and `existing_docs` paths
+- Read source files to understand changes
+- If `session_knowledge` provided, incorporate learnings:
+  - New patterns or approaches from implementation
+  - Key decisions documented in alignment
+  - Deviations or discoveries from prompts
+- Update refs to match current code
+- Add new sections for new functionality
+- Remove or update stale content
+
+### For Fixing Validation Issues
+
+If provided `stale_refs` or `invalid_refs`:
+- Read the doc and referenced files
+- For stale refs: update to current symbols/locations
+- For invalid refs: remove or fix (symbol may have been renamed/moved)
+- Verify all refs point to real implementations
+
+## Directory Structure
+
+Use the `group` field from approach input to determine file paths:
+
+- **If `group` is set**: `<doc_directory>/<group>/<approach-name>.md`
+  - Example: `docs/harness/cli/knowledge-command.md`
+- **If `group` is null**: `<doc_directory>/<approach-name>.md`
+  - Example: `docs/harness/test-harness.md`
+
+Create subdirectories as needed before writing files.
+
+## Completion
+
+- Ensure all docs are written to `doc_directory`
+- Report files created/modified

package/.allhands/flows/shared/EMERGENT_REFINEMENT_ANALYSIS.md

@@ -0,0 +1,76 @@
+<goal>
+Analyze emergent refinement prompts to determine which should be kept, improved, or eliminated. Per **Quality Engineering**, present options to the engineer for variant selection.
+</goal>
+
+<inputs>
+- Alignment doc path
+- Prompts file directory
+</inputs>
+
+<outputs>
+- User-patch prompts for improvements/eliminations
+- Updated alignment doc with engineer decisions
+</outputs>
+
+<constraints>
+- MUST analyze all prompts with `type: emergent` frontmatter
+- MUST document engineer decisions in alignment doc and prompt files
+- MUST use git hashes from prompts to identify file changes for reversion
+</constraints>
+
+## Context Gathering
+
+- Read the alignment doc for milestone goal and context
+- Read all prompts in the directory with `type: emergent` frontmatter
+- Extract git hashes from each prompt to identify affected files
+
+## Prompt Analysis
+
+For each emergent refinement prompt, evaluate:
+
+| Criterion | Question |
+|-----------|----------|
+| Hypothesis | What did it propose to accomplish? |
+| Approach | How did it attempt to solve the outcome? |
+| Effectiveness | Did validation results prove goal contribution? |
+| Alignment | Does it push toward alignment doc goals? |
+
+## Classification
+
+Categorize each emergent prompt:
+
+| Category | Criteria | Action |
+|----------|----------|--------|
+| **Keep** | Strong hypothesis, effective, aligned | No action needed |
+| **Improve** | Good hypothesis, but execution gaps | Create improvement patch prompt |
+| **Eliminate** | Hypothesis doesn't support goal | Create reversion patch prompt |
+
+For "Improve" prompts, document:
+- Why they aren't "Keep" status
+- What changes would elevate them
+
+## Engineer Decision
+
+Present findings holistically:
+- Compare emergent refinements against each other
+- Highlight patterns of effective vs ineffective hypotheses
+- Offer recommendations per prompt
+
+Allow engineer to:
+- Accept suggestions as-is
+- Provide custom adjustments
+- Decide eliminations
+
+## Prompt Creation
+
+For accepted changes:
+- Read `.allhands/flows/shared/PROMPT_TASKS_CURATION.md` for guidance
+- Create `type: user-patch` prompts for improvements
+- Create `type: user-patch` prompts for eliminations (include reversion steps using git hash file references)
+
+## Decision Documentation
+
+Per **Knowledge Compounding**, document engineer decisions:
+- Add rationale to alignment doc
+- Amend individual prompt files with engineer steering
+- Capture why prompts were kept/improved/eliminated

package/.allhands/flows/shared/EXTERNAL_TECH_GUIDANCE.md

@@ -0,0 +1,97 @@
+<goal>
+Acquire explicit documentation and implementation inspiration from external technologies. Per **Frontier Models are Capable**, this provides the specific implementation guidance needed to deduce "how" from "why".
+</goal>
+
+<inputs>
+- Query for context7 or open source repo exploration
+- Query type indication: open source GitHub project OR proprietary documentation only
+- Relevant codebase files to inject into query context (if applicable)
+</inputs>
+
+<outputs>
+- Summary of guidance provided
+- Strong implementation examples/suggestions inferred from tool responses
+</outputs>
+
+<constraints>
+- MUST use context7 for documentation references
+- MUST clone open source repos to `.reposearch/` for local exploration
+- MUST run both approaches in parallel when query benefits from dual perspective
+- MUST NOT USE OTHER TOOLING THAN DESCRIBED HERE UNLESS BOTH OPTIONS ARE FAILING TO PROVIDE RESULTS
+</constraints>
+
+## Tool Selection
+
+| Query Type | Tool | Purpose |
+|------------|------|---------|
+| Documentation lookup | `ah context7 search` | Official docs and API references |
+| Open source exploration | `gh search` + clone | Clone repo locally for full file navigation |
+| Both applicable | Run in parallel | Well-rounded perspective |
+
+## Usage Patterns
+
+### Documentation Only (context7)
+
+For proprietary domains with documentation pages:
+- Run `ah context7 search "<technology> <query>"`
+- Extract API patterns, configuration examples
+- Note version-specific behaviors
+
+### Open Source Inspiration (Clone & Browse)
+
+For exploring GitHub repositories locally:
+
+1. **Search for repositories**:
+   ```bash
+   gh search repos "<query>" --limit 5
+   ```
+
+2. **Clone to local research folder**:
+   ```bash
+   # Clone into .reposearch folder (gitignored)
+   mkdir -p .reposearch
+   git clone --depth 1 <repo-url> .reposearch/<repo-name>
+   ```
+
+   Note: Ensure `.reposearch/` is in the project's `.gitignore`.
+
+3. **Browse locally with standard tooling**:
+   - Use `Glob` to find files by pattern
+   - Use `Grep` to search code content
+   - Use `Read` to examine specific files
+   - Use `ls` to explore directory structure
+
+4. **Clean up when done** (optional):
+   ```bash
+   rm -rf .reposearch/<repo-name>
+   ```
+
+This approach leverages the agent's superior local file navigation capabilities:
+- Full regex search across the codebase
+- Fast pattern matching and file discovery
+- Direct file reading without API encoding issues
+- Study implementation patterns in similar projects
+- Extract architectural decisions
+- Note how libraries handle similar problems
+
+### Parallel Exploration
+
+Most cases benefit from both tools:
+- Documentation gives official guidance
+- Source code reveals actual implementation patterns
+- Cross-reference for comprehensive understanding
+
+## Query Formulation
+
+When injecting codebase context:
+- Include relevant file paths from this codebase
+- Explain how query relates to existing implementation
+- Ask specific questions about integration approach
+
+## Output Synthesis
+
+Provide:
+- Summary of what guidance was found
+- Specific implementation suggestions
+- Code patterns to follow
+- Gotchas or edge cases discovered