@cleocode/cleo 2026.2.5 → 2026.2.6

package/packages/ct-skills/skills/ct-orchestrator/references/orchestrator-spawning.md

@@ -0,0 +1,271 @@
+# Orchestrator: Subagent Spawning
+
+> Referenced from: @skills/ct-orchestrator/SKILL.md
+> Load when: Need details on spawning subagents, skill dispatch, template selection, or programmatic spawning workflows
+
+## Subagent Spawning
+
+### Quick Spawn Workflow
+
+```bash
+# 1. Get next ready task
+cleo orchestrator next --epic T1575
+
+# 2. Generate spawn command with prompt
+cleo orchestrator spawn T1586
+
+# 3. Or specify a skill template
+cleo orchestrator spawn T1586 --template ct-research-agent
+cleo orchestrator spawn T1586 --template RESEARCH-AGENT  # aliases work
+```
+
+### Manual Spawn (when CLI spawn unavailable)
+
+Use Task tool with `subagent_type="general-purpose"` and include:
+1. Subagent protocol block (RFC 2119 requirements)
+2. Context from previous agents (manifest `key_findings` ONLY)
+3. Clear task definition and completion criteria
+
+### Spawn Output
+
+The `spawn` command returns:
+- `taskId`: Target task
+- `template`: Skill used
+- `topicSlug`: Slugified topic name
+- `outputFile`: Expected output filename
+- `prompt`: Complete prompt ready for Task tool
+
+---
+
+## Skill Dispatch Rules
+
+Use the appropriate skill for each task type. The `spawn` command accepts skill names in multiple formats.
+
+### Skill Selection Matrix
+
+| Task Type | Skill | Trigger Keywords |
+|-----------|-------|------------------|
+| Generic implementation | `ct-task-executor` | "implement", "execute task", "do the work", "build component" |
+| Research/investigation | `ct-research-agent` | "research", "investigate", "gather info", "explore options" |
+| Epic/project planning | `ct-epic-architect` | "create epic", "plan tasks", "decompose", "wave planning" |
+| Specification writing | `ct-spec-writer` | "write spec", "define protocol", "RFC", "specification" |
+| Test writing (BATS) | `ct-test-writer-bats` | "write tests", "BATS", "bash tests", "integration tests" |
+| Bash library creation | `ct-library-implementer-bash` | "create library", "bash functions", "lib/*.sh" |
+| Compliance validation | `ct-validator` | "validate", "verify", "check compliance", "audit" |
+| Documentation | `ct-documentor` | "write docs", "document", "update README" |
+
+### Skill Name Aliases
+
+The `spawn` command supports multiple name formats:
+
+| Format | Example |
+|--------|---------|
+| Full name | `ct-task-executor`, `ct-research-agent` |
+| Uppercase | `TASK-EXECUTOR`, `RESEARCH-AGENT` |
+| Lowercase | `task-executor`, `research-agent` |
+| Short aliases | `EXECUTOR`, `RESEARCH`, `BATS`, `SPEC` |
+
+### Skill Paths
+
+```
+skills/ct-epic-architect/SKILL.md
+skills/ct-spec-writer/SKILL.md
+skills/ct-research-agent/SKILL.md
+skills/ct-test-writer-bats/SKILL.md
+skills/ct-library-implementer-bash/SKILL.md
+skills/ct-task-executor/SKILL.md
+skills/ct-validator/SKILL.md
+skills/ct-documentor/SKILL.md
+```
+
+---
+
+## Complete Spawning Workflow
+
+### Automated Workflow (Recommended)
+
+```bash
+# Step 1: Get ready task
+cleo orchestrator next --epic T1575
+# Returns: { nextTask: { id: "T1586", title: "...", priority: "high" } }
+
+# Step 2: Generate spawn prompt (handles all token injection)
+spawn_result=$(cleo orchestrator spawn T1586)
+
+# Step 3: Extract prompt and use with Task tool
+prompt=$(echo "$spawn_result" | jq -r '.result.prompt')
+# Pass $prompt to Task tool
+```
+
+---
+
+## Programmatic Spawning with orchestrator_spawn_for_task()
+
+For advanced automation, use the `orchestrator_spawn_for_task()` function from `lib/orchestrator-spawn.sh`. This consolidates the manual 6-step workflow into a single function call.
+
+### Basic Usage
+
+```bash
+source lib/orchestrator-spawn.sh
+
+# Prepare complete subagent prompt for a task
+prompt=$(orchestrator_spawn_for_task "T1234")
+
+# With explicit skill override (bypasses auto-dispatch)
+prompt=$(orchestrator_spawn_for_task "T1234" "ct-research-agent")
+
+# With target model validation
+prompt=$(orchestrator_spawn_for_task "T1234" "" "sonnet")
+```
+
+### What orchestrator_spawn_for_task() Does
+
+The function performs these steps automatically:
+
+| Step | Action | Details |
+|------|--------|---------|
+| 1 | Read task from CLEO | `cleo show T1234 --format json` |
+| 2 | Select skill | Auto-dispatch from task type/labels or use override |
+| 3 | Validate skill | Check compatibility with target model |
+| 4 | Inject protocol | Load skill template + subagent protocol |
+| 5 | Set tokens | `{{TASK_ID}}`, `{{DATE}}`, `{{TOPIC_SLUG}}`, `{{EPIC_ID}}` |
+| 6 | **Validate protocol** | **MANDATORY check for SUBAGENT PROTOCOL marker** |
+| 7 | Return prompt | Complete JSON with prompt ready for Task tool |
+
+### Protocol Validation (MANDATORY)
+
+Step 6 validates that the generated prompt contains the `SUBAGENT PROTOCOL` marker. This is **mandatory** and will fail loudly if missing:
+
+- **Exit code**: `EXIT_PROTOCOL_MISSING` (60)
+- **Fix command**: `cleo research inject`
+- **Validation function**: `orchestrator_verify_protocol_injection()`
+
+If validation fails, the spawn is **blocked** and you must fix the skill template or manually inject the protocol block.
+
+### Return Value Structure
+
+```json
+{
+  "_meta": { "command": "orchestrator", "operation": "spawn_for_task" },
+  "success": true,
+  "result": {
+    "taskId": "T1234",
+    "skill": "ct-research-agent",
+    "topicSlug": "auth-implementation",
+    "date": "2026-01-20",
+    "epicId": "T1200",
+    "outputFile": "2026-01-20_auth-implementation.md",
+    "spawnTimestamp": "2026-01-20T15:30:00Z",
+    "targetModel": "auto",
+    "taskContext": {
+      "title": "Implement auth module",
+      "description": "Full task description..."
+    },
+    "instruction": "Use Task tool to spawn subagent with the following prompt:",
+    "prompt": "Complete injected prompt content..."
+  }
+}
+```
+
+### Helper Functions
+
+| Function | Purpose |
+|----------|---------|
+| `orchestrator_spawn_for_task()` | Main function - prepare single task spawn |
+| `orchestrator_spawn_batch()` | Prepare prompts for multiple tasks |
+| `orchestrator_spawn_preview()` | Preview skill selection without injection |
+
+### Complete Workflow Example
+
+```bash
+#!/usr/bin/env bash
+# Example: Spawn research subagent for task T1586
+
+source lib/orchestrator-spawn.sh
+
+# 1. Generate spawn result (includes all tokens and context)
+spawn_result=$(orchestrator_spawn_for_task "T1586")
+
+# 2. Check success
+if [[ $(echo "$spawn_result" | jq -r '.success') != "true" ]]; then
+    echo "Spawn failed: $(echo "$spawn_result" | jq -r '.error.message')" >&2
+    exit 1
+fi
+
+# 3. Extract prompt for Task tool
+prompt=$(echo "$spawn_result" | jq -r '.result.prompt')
+output_file=$(echo "$spawn_result" | jq -r '.result.outputFile')
+skill=$(echo "$spawn_result" | jq -r '.result.skill')
+
+# 4. Log spawn metadata
+echo "Spawning $skill for task T1586"
+echo "Expected output: $output_file"
+
+# 5. Pass $prompt to Task tool (in orchestrator context)
+# The Task tool invocation would include:
+#   - description: "Execute task T1586 with $skill"
+#   - prompt: $prompt
+```
+
+### Debug Mode
+
+Enable debug output for troubleshooting:
+
+```bash
+export ORCHESTRATOR_SPAWN_DEBUG=1
+prompt=$(orchestrator_spawn_for_task "T1234")
+# Logs to stderr: [orchestrator-spawn] DEBUG: ...
+```
+
+---
+
+### Manual Workflow
+
+#### Step 1: Identify Task Type
+
+```bash
+# Check task details
+cleo show T1234 | jq '{title, description, labels}'
+```
+
+#### Step 2: Select Skill
+
+Match task keywords to skill selection matrix above.
+
+#### Step 3: Prepare Context
+
+```bash
+source lib/token-inject.sh
+
+# Set required tokens
+ti_set_context "T1234" "$(date +%Y-%m-%d)" "auth-implementation"
+
+# Set defaults and get task context
+ti_set_defaults
+task_json=$(cleo show T1234 --format json)
+ti_set_task_context "$task_json"
+```
+
+#### Step 4: Load Skill Template
+
+```bash
+template=$(ti_load_template "skills/ct-task-executor/SKILL.md")
+```
+
+#### Step 5: Spawn Subagent
+
+Use Task tool with:
+1. Injected skill template
+2. Subagent protocol block
+3. Context from previous agents (manifest `key_findings` ONLY)
+4. Clear task definition and completion criteria
+
+#### Step 6: Monitor Completion
+
+```bash
+# Check manifest for completion
+{{RESEARCH_SHOW_CMD}} <research-id>
+
+# Or use jq
+jq -s '.[-1] | {id, status, key_findings}' {{MANIFEST_PATH}}
+```

package/packages/ct-skills/skills/ct-orchestrator/references/orchestrator-tokens.md

@@ -0,0 +1,180 @@
+# Orchestrator: Token Injection System
+
+> Referenced from: @skills/ct-orchestrator/SKILL.md
+> Load when: Need details on token injection, placeholder values, manual token setup, or helper functions for template processing
+
+## Token Injection System
+
+The `spawn` command handles token injection automatically. For manual injection, use `lib/token-inject.sh`.
+
+### Automatic (via spawn command)
+
+```bash
+# The spawn command automatically:
+# 1. Loads the skill template
+# 2. Sets required context tokens
+# 3. Gets task context from CLEO
+# 4. Extracts manifest summaries
+# 5. Injects all tokens
+cleo orchestrator spawn T1586 --template ct-research-agent
+```
+
+### Manual Token Injection
+
+```bash
+source lib/token-inject.sh
+
+# 1. Set required tokens
+export TI_TASK_ID="T1234"
+export TI_DATE="$(date +%Y-%m-%d)"
+export TI_TOPIC_SLUG="my-research-topic"
+
+# 2. Set CLEO defaults (task commands, output paths)
+ti_set_defaults
+
+# 3. Optional: Get task context from CLEO
+task_json=$(cleo show T1234 --format json)
+ti_set_task_context "$task_json"
+
+# 4. Load and inject skill template
+template=$(ti_load_template "skills/ct-research-agent/SKILL.md")
+```
+
+---
+
+## Token Reference
+
+**Source of Truth**: `skills/_shared/placeholders.json`
+
+### Required Tokens
+
+| Token | Description | Pattern | Example |
+|-------|-------------|---------|---------|
+| `{{TASK_ID}}` | CLEO task identifier | `^T[0-9]+$` | `T1234` |
+| `{{DATE}}` | ISO date | `YYYY-MM-DD` | `2026-01-20` |
+| `{{TOPIC_SLUG}}` | URL-safe topic name | `[a-zA-Z0-9_-]+` | `auth-research` |
+
+### Task Command Tokens (CLEO defaults)
+
+| Token | Default Value |
+|-------|---------------|
+| `{{TASK_SHOW_CMD}}` | `cleo show` |
+| `{{TASK_START_CMD}}` | `cleo start` |
+| `{{TASK_COMPLETE_CMD}}` | `cleo complete` |
+| `{{TASK_LINK_CMD}}` | `cleo research link` |
+| `{{TASK_LIST_CMD}}` | `cleo list` |
+| `{{TASK_FIND_CMD}}` | `cleo find` |
+| `{{TASK_ADD_CMD}}` | `cleo add` |
+
+### Output Tokens (CLEO defaults)
+
+| Token | Default Value |
+|-------|---------------|
+| `{{OUTPUT_DIR}}` | `claudedocs/agent-outputs` |
+| `{{MANIFEST_PATH}}` | `claudedocs/agent-outputs/MANIFEST.jsonl` |
+
+### Task Context Tokens (populated from CLEO task data)
+
+| Token | Source | Description |
+|-------|--------|-------------|
+| `{{TASK_NAME}}` | `task.title` | Task title |
+| `{{TASK_DESCRIPTION}}` | `task.description` | Full description |
+| `{{TASK_INSTRUCTIONS}}` | `task.description` | Execution instructions |
+| `{{DELIVERABLES_LIST}}` | `task.deliverables` | Expected outputs |
+| `{{ACCEPTANCE_CRITERIA}}` | Extracted | Completion criteria |
+| `{{DEPENDS_LIST}}` | `task.depends` | Completed dependencies |
+| `{{MANIFEST_SUMMARIES}}` | MANIFEST.jsonl | Key findings from previous agents |
+| `{{NEXT_TASK_IDS}}` | Dependency analysis | Tasks unblocked after completion |
+
+---
+
+## Helper Functions
+
+| Function | Purpose |
+|----------|---------|
+| `ti_set_defaults()` | Set CLEO defaults for unset tokens |
+| `ti_validate_required()` | Verify required tokens are set |
+| `ti_inject_tokens()` | Replace `{{TOKEN}}` patterns |
+| `ti_load_template()` | Load file and inject tokens |
+| `ti_set_context()` | Set TASK_ID, DATE, TOPIC_SLUG in one call |
+| `ti_set_task_context()` | Populate task context tokens from CLEO JSON |
+| `ti_extract_manifest_summaries()` | Get key_findings from recent manifest entries |
+| `ti_list_tokens()` | Show all tokens with current values |
+
+---
+
+## Token Injection with lib/token-inject.sh
+
+For fine-grained control over token injection, use `lib/token-inject.sh` directly.
+
+### Token Categories
+
+| Category | Tokens | Source |
+|----------|--------|--------|
+| **Required** | `{{TASK_ID}}`, `{{DATE}}`, `{{TOPIC_SLUG}}` | Must be set before injection |
+| **Task Commands** | `{{TASK_SHOW_CMD}}`, `{{TASK_START_CMD}}`, `{{TASK_COMPLETE_CMD}}`, etc. | CLEO defaults |
+| **Output Paths** | `{{OUTPUT_DIR}}`, `{{MANIFEST_PATH}}` | CLEO defaults |
+| **Task Context** | `{{TASK_TITLE}}`, `{{TASK_DESCRIPTION}}`, `{{DEPENDS_LIST}}`, etc. | From CLEO task data |
+| **Manifest Context** | `{{MANIFEST_SUMMARIES}}` | From recent MANIFEST.jsonl entries |
+
+### Manual Token Injection Example
+
+```bash
+source lib/token-inject.sh
+
+# 1. Set required tokens
+ti_set_context "T1234" "2026-01-20" "auth-research"
+
+# 2. Set CLEO defaults for task commands and paths
+ti_set_defaults
+
+# 3. Get task context from CLEO
+task_json=$(cleo show T1234 --format json)
+ti_set_task_context "$task_json"
+
+# 4. Load and inject skill template
+template=$(ti_load_template "skills/ct-research-agent/SKILL.md")
+
+# 5. Verify tokens were injected
+echo "$template" | grep -c '{{' && echo "WARNING: Uninjected tokens remain"
+```
+
+### Key Functions
+
+| Function | Purpose | Example |
+|----------|---------|---------|
+| `ti_set_context()` | Set required tokens | `ti_set_context "T1234" "" "topic"` |
+| `ti_set_defaults()` | Set CLEO command defaults | `ti_set_defaults` |
+| `ti_set_task_context()` | Populate from CLEO JSON | `ti_set_task_context "$task_json"` |
+| `ti_extract_manifest_summaries()` | Get recent findings | `ti_extract_manifest_summaries 5` |
+| `ti_load_template()` | Load and inject file | `ti_load_template "path/to/SKILL.md"` |
+| `ti_list_tokens()` | Debug token values | `ti_list_tokens` |
+
+---
+
+## Subagent Protocol Tokens
+
+Token defaults (from `skills/_shared/placeholders.json`):
+- `{{OUTPUT_DIR}}` -> `claudedocs/agent-outputs`
+- `{{MANIFEST_PATH}}` -> `claudedocs/agent-outputs/MANIFEST.jsonl`
+
+### Inline Protocol Block (when CLI unavailable)
+
+```markdown
+## SUBAGENT PROTOCOL (RFC 2119 - MANDATORY)
+
+OUTPUT REQUIREMENTS:
+1. MUST write findings to: {{OUTPUT_DIR}}/{{DATE}}_{{TOPIC_SLUG}}.md
+2. MUST append ONE line to: {{MANIFEST_PATH}}
+3. MUST return ONLY: "Research complete. See MANIFEST.jsonl for summary."
+4. MUST NOT return research content in response.
+
+CLEO INTEGRATION:
+1. MUST read task details: `{{TASK_SHOW_CMD}} {{TASK_ID}}`
+2. MUST start task: `{{TASK_START_CMD}} {{TASK_ID}}`
+3. MUST complete task when done: `{{TASK_COMPLETE_CMD}} {{TASK_ID}}`
+4. SHOULD link research: `{{TASK_LINK_CMD}} {{TASK_ID}} {{RESEARCH_ID}}`  <- RECOMMENDED
+
+**Research Linking Note**: If subagent fails to link research, orchestrator will link on verification.
+This ensures bidirectional traceability between tasks and their research artifacts.
+```

package/packages/ct-skills/skills/ct-research-agent/SKILL.md

@@ -0,0 +1,226 @@
+---
+name: ct-research-agent
+description: Multi-source research and investigation combining web search, documentation lookup via Context7, and codebase analysis. Synthesizes findings into actionable recommendations with proper citation and task traceability. Use when conducting research, investigating best practices, gathering technical information, or analyzing existing implementations. Triggers on research tasks, investigation needs, or information discovery requests.
+version: 2.0.0
+tier: 2
+core: false
+category: recommended
+protocol: research
+dependencies: []
+sharedResources:
+  - subagent-protocol-base
+  - task-system-integration
+compatibility:
+  - claude-code
+  - cursor
+  - windsurf
+  - gemini-cli
+license: MIT
+---
+
+# Research Context Injection
+
+**Protocol**: @protocols/research.md
+**Type**: Context Injection (cleo-subagent)
+**Version**: 2.0.0
+
+---
+
+## Purpose
+
+Context injection for research and investigation tasks spawned via cleo-subagent. Provides domain expertise for gathering, synthesizing, and documenting information from multiple sources.
+
+---
+
+## Capabilities
+
+1. **Web Research** - Search for current practices, standards, and solutions
+2. **Documentation Lookup** - Query official docs via Context7
+3. **Codebase Analysis** - Analyze existing code via grep/tools
+4. **Synthesis** - Combine findings into actionable recommendations
+
+---
+
+## Parameters (Orchestrator-Provided)
+
+| Parameter | Description | Required |
+|-----------|-------------|----------|
+| `{{TOPIC}}` | Research subject | Yes |
+| `{{TOPIC_SLUG}}` | URL-safe topic name | Yes |
+| `{{RESEARCH_QUESTIONS}}` | Specific questions to answer | Yes |
+| `{{RESEARCH_TITLE}}` | Human-readable title for output | Yes |
+| `{{TASK_ID}}` | Current task identifier | Yes |
+| `{{EPIC_ID}}` | Parent epic identifier | No |
+| `{{SESSION_ID}}` | Session identifier | No |
+| `{{DATE}}` | Current date (YYYY-MM-DD) | Yes |
+| `{{TOPICS_JSON}}` | JSON array of categorization tags | Yes |
+
+---
+
+## Task System Integration
+
+@skills/_shared/task-system-integration.md
+
+### Execution Sequence
+
+1. Read task: `{{TASK_SHOW_CMD}} {{TASK_ID}}`
+2. Focus already set by orchestrator (skip if working standalone, set if needed)
+3. Conduct research (see Methodology below)
+4. Write output: `{{OUTPUT_DIR}}/{{DATE}}_{{TOPIC_SLUG}}.md`
+5. Append manifest: `{{MANIFEST_PATH}}`
+6. Complete task: `{{TASK_COMPLETE_CMD}} {{TASK_ID}}`
+7. Return summary message
+
+---
+
+## Methodology
+
+### Research Sources
+
+1. **Web Search** - Current practices, recent developments
+   - Use web search for up-to-date information
+   - Prioritize authoritative sources
+
+2. **Documentation Lookup** - Official APIs, libraries
+   - Use Context7 for framework/library documentation
+   - Verify version compatibility
+
+3. **Codebase Analysis** - Existing patterns, implementations
+   - Use grep/tools for code search
+   - Identify existing patterns to follow or avoid
+
+### Research Process
+
+1. **Understand scope** - Review research questions
+2. **Gather raw data** - Collect information from sources
+3. **Synthesize findings** - Identify patterns and insights
+4. **Form recommendations** - Actionable next steps
+5. **Document sources** - Cite all references
+
+---
+
+## Subagent Protocol
+
+@skills/_shared/subagent-protocol-base.md
+
+### Output Requirements
+
+1. MUST write findings to: `{{OUTPUT_DIR}}/{{DATE}}_{{TOPIC_SLUG}}.md`
+2. MUST append ONE line to: `{{MANIFEST_PATH}}`
+3. MUST return ONLY: "Research complete. See MANIFEST.jsonl for summary."
+4. MUST NOT return research content in response
+
+---
+
+## Output File Format
+
+Write to `{{OUTPUT_DIR}}/{{DATE}}_{{TOPIC_SLUG}}.md`:
+
+```markdown
+# {{RESEARCH_TITLE}}
+
+## Summary
+
+{{2-3 sentence overview of key findings}}
+
+## Findings
+
+### {{Finding Category 1}}
+
+{{Details with evidence and citations}}
+
+### {{Finding Category 2}}
+
+{{Details with evidence and citations}}
+
+## Recommendations
+
+1. {{Actionable recommendation 1}}
+2. {{Actionable recommendation 2}}
+3. {{Actionable recommendation 3}}
+
+## Sources
+
+- {{Source 1 with link if available}}
+- {{Source 2 with link if available}}
+- {{Source 3 with link if available}}
+
+## Linked Tasks
+
+- Epic: {{EPIC_ID}}
+- Task: {{TASK_ID}}
+```
+
+---
+
+## Manifest Entry Format
+
+Append ONE line (no pretty-printing) to `{{MANIFEST_PATH}}`:
+
+```json
+{"id":"{{TOPIC_SLUG}}-{{DATE}}","file":"{{DATE}}_{{TOPIC_SLUG}}.md","title":"{{RESEARCH_TITLE}}","date":"{{DATE}}","status":"complete","agent_type":"research","topics":{{TOPICS_JSON}},"key_findings":["Finding 1","Finding 2","Finding 3"],"actionable":true,"needs_followup":[],"linked_tasks":["{{EPIC_ID}}","{{TASK_ID}}"]}
+```
+
+### Field Guidelines
+
+| Field | Guideline |
+|-------|-----------|
+| `key_findings` | 3-7 one-sentence findings, action-oriented |
+| `actionable` | `true` if findings require implementation work |
+| `needs_followup` | Task IDs requiring attention based on findings |
+| `topics` | 2-5 categorization tags for discoverability |
+
+---
+
+## Completion Checklist
+
+- [ ] Task details read via `{{TASK_SHOW_CMD}}`
+- [ ] Research conducted across multiple sources
+- [ ] Findings synthesized with recommendations
+- [ ] Output file written to `{{OUTPUT_DIR}}/`
+- [ ] Manifest entry appended (single line, valid JSON)
+- [ ] Task completed via `{{TASK_COMPLETE_CMD}}`
+- [ ] Response is ONLY the summary message
+
+---
+
+## Error Handling
+
+### Partial Research
+
+If complete answers cannot be found:
+
+1. Document what was found
+2. Note gaps and why they exist
+3. Set manifest `"status": "partial"`
+4. Add suggestions for followup to `needs_followup`
+5. Complete task
+6. Return: "Research partial. See MANIFEST.jsonl for details."
+
+### Blocked Research
+
+If research cannot proceed (access denied, topic too broad, etc.):
+
+1. Document blocking reason
+2. Set manifest `"status": "blocked"`
+3. Add blocker details to `needs_followup`
+4. Do NOT complete task
+5. Return: "Research blocked. See MANIFEST.jsonl for blocker details."
+
+---
+
+## Quality Standards
+
+### Findings Quality
+
+- **Evidence-based** - Every claim has a source
+- **Current** - Prefer recent sources (within 1-2 years)
+- **Relevant** - Directly addresses research questions
+- **Actionable** - Clear path from finding to action
+
+### Recommendation Quality
+
+- **Specific** - Concrete actions, not vague suggestions
+- **Prioritized** - Most important first
+- **Justified** - Tied to specific findings
+- **Feasible** - Achievable within project constraints