init
This commit is contained in:
140
.opencode/skills/scout/references/external-scouting.md
Normal file
140
.opencode/skills/scout/references/external-scouting.md
Normal file
@@ -0,0 +1,140 @@
|
||||
# External Scouting with Gemini/OpenCode
|
||||
|
||||
Use external agentic tools for faster searches with large context windows (1M+ tokens).
|
||||
|
||||
## Tool Selection
|
||||
|
||||
```
|
||||
SCALE <= 3 → gemini CLI
|
||||
SCALE 4-5 → opencode CLI
|
||||
SCALE >= 6 → Use internal scouting instead
|
||||
```
|
||||
|
||||
## Configuration
|
||||
|
||||
Read from `.opencode/.ck.json`:
|
||||
```json
|
||||
{
|
||||
"gemini": {
|
||||
"model": "gemini-3-flash-preview"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Default model: `gemini-3-flash-preview`
|
||||
|
||||
## Gemini CLI (SCALE <= 3)
|
||||
|
||||
### Command
|
||||
```bash
|
||||
gemini -y -m <model> "[prompt]"
|
||||
```
|
||||
|
||||
### Example
|
||||
```bash
|
||||
gemini -y -m gemini-3-flash-preview "Search src/ for authentication files. List paths with brief descriptions."
|
||||
```
|
||||
|
||||
## OpenCode CLI (SCALE 4-5)
|
||||
|
||||
### Command
|
||||
```bash
|
||||
opencode run "[prompt]" --model opencode/grok-code
|
||||
```
|
||||
|
||||
### Example
|
||||
```bash
|
||||
opencode run "Find all payment-related files in lib/ and api/" --model opencode/grok-code
|
||||
```
|
||||
|
||||
## Installation Check
|
||||
|
||||
Before using, verify tools installed:
|
||||
```bash
|
||||
which gemini
|
||||
which opencode
|
||||
```
|
||||
|
||||
If not installed, ask user:
|
||||
1. **Yes** - Provide installation instructions (may need manual auth steps)
|
||||
2. **No** - Fall back to Explore subagents (`internal-scouting.md`)
|
||||
|
||||
## Spawning Parallel Bash Agents
|
||||
|
||||
Use `Task` tool with `subagent_type: "Bash"` to spawn parallel agents:
|
||||
|
||||
```
|
||||
Task 1: subagent_type="Bash", prompt="Run: gemini -y -m gemini-3-flash-preview '[prompt1]'"
|
||||
Task 2: subagent_type="Bash", prompt="Run: gemini -y -m gemini-3-flash-preview '[prompt2]'"
|
||||
Task 3: subagent_type="Bash", prompt="Run: gemini -y -m gemini-3-flash-preview '[prompt3]'"
|
||||
```
|
||||
|
||||
Spawn all in single message for parallel execution.
|
||||
|
||||
## Prompt Guidelines
|
||||
|
||||
- Be specific about directories to search
|
||||
- Request file paths with descriptions
|
||||
- Set clear scope boundaries
|
||||
- Ask for patterns/relationships if relevant
|
||||
|
||||
## Example Workflow
|
||||
|
||||
User: "Find database migration files"
|
||||
|
||||
Spawn 3 parallel Bash agents via Task tool:
|
||||
```
|
||||
Task 1 (Bash): "Run: gemini -y -m gemini-3-flash-preview 'Search db/, migrations/ for migration files'"
|
||||
Task 2 (Bash): "Run: gemini -y -m gemini-3-flash-preview 'Search lib/, src/ for database schema files'"
|
||||
Task 3 (Bash): "Run: gemini -y -m gemini-3-flash-preview 'Search config/ for database configuration'"
|
||||
```
|
||||
|
||||
## Reading File Content
|
||||
|
||||
When needing to read file content, use chunking to stay within context limits (<150K tokens safe zone).
|
||||
|
||||
### Step 1: Get Line Counts
|
||||
```bash
|
||||
wc -l path/to/file1.ts path/to/file2.ts path/to/file3.ts
|
||||
```
|
||||
|
||||
### Step 2: Calculate Chunks
|
||||
- **Target:** ~500 lines per chunk (safe for most files)
|
||||
- **Max files per agent:** 3-5 small files OR 1 large file chunked
|
||||
|
||||
**Chunking formula:**
|
||||
```
|
||||
chunks = ceil(total_lines / 500)
|
||||
lines_per_chunk = ceil(total_lines / chunks)
|
||||
```
|
||||
|
||||
### Step 3: Spawn Parallel Bash Agents
|
||||
|
||||
**Small files (<500 lines each):**
|
||||
```
|
||||
Task 1: subagent_type="Bash", prompt="cat file1.ts file2.ts"
|
||||
Task 2: subagent_type="Bash", prompt="cat file3.ts file4.ts"
|
||||
```
|
||||
|
||||
**Large file (>500 lines) - use sed for ranges:**
|
||||
```
|
||||
Task 1: subagent_type="Bash", prompt="sed -n '1,500p' large-file.ts"
|
||||
Task 2: subagent_type="Bash", prompt="sed -n '501,1000p' large-file.ts"
|
||||
Task 3: subagent_type="Bash", prompt="sed -n '1001,1500p' large-file.ts"
|
||||
```
|
||||
|
||||
### Chunking Decision Tree
|
||||
```
|
||||
File < 500 lines → Read entire file
|
||||
File 500-1500 lines → Split into 2-3 chunks
|
||||
File > 1500 lines → Split into ceil(lines/500) chunks
|
||||
```
|
||||
|
||||
Spawn all in single message for parallel execution.
|
||||
|
||||
## Timeout and Error Handling
|
||||
|
||||
- Set 3-minute timeout per bash call
|
||||
- Skip timed-out agents
|
||||
- Don't restart failed agents
|
||||
- On persistent failures, fall back to internal scouting
|
||||
119
.opencode/skills/scout/references/internal-scouting.md
Normal file
119
.opencode/skills/scout/references/internal-scouting.md
Normal file
@@ -0,0 +1,119 @@
|
||||
# Internal Scouting with Explore Subagents
|
||||
|
||||
Use Explore subagents when SCALE >= 6 or external tools unavailable.
|
||||
|
||||
## How It Works
|
||||
|
||||
Spawn multiple `Explore` subagents via `Task` tool to search codebase in parallel.
|
||||
|
||||
## Task Tool Configuration
|
||||
|
||||
```
|
||||
subagent_type: "Explore"
|
||||
```
|
||||
|
||||
## Prompt Template
|
||||
|
||||
```
|
||||
Quickly scout {DIRECTORY} for files related to: {USER_PROMPT}
|
||||
|
||||
Instructions:
|
||||
- Search for relevant files matching the task
|
||||
- Use Glob/Grep for file discovery
|
||||
- List files with brief descriptions
|
||||
- Timeout: 3 minutes max
|
||||
- Skip if timeout reached
|
||||
|
||||
Report format:
|
||||
## Found Files
|
||||
- `path/file.ext` - description
|
||||
|
||||
## Patterns
|
||||
- Key patterns observed
|
||||
```
|
||||
|
||||
## Spawning Strategy
|
||||
|
||||
### Directory Division
|
||||
Split codebase logically:
|
||||
- `src/` - Source code
|
||||
- `lib/` - Libraries
|
||||
- `tests/` - Test files
|
||||
- `config/` - Configuration
|
||||
- `api/` - API routes
|
||||
|
||||
### Parallel Execution
|
||||
- Spawn all agents in single `Task` tool call
|
||||
- Each agent gets distinct directory scope
|
||||
- No overlap between agents
|
||||
|
||||
## Example
|
||||
|
||||
User prompt: "Find authentication-related files"
|
||||
|
||||
```
|
||||
Agent 1: Scout src/auth/, src/middleware/ for auth files
|
||||
Agent 2: Scout src/api/, src/routes/ for auth endpoints
|
||||
Agent 3: Scout tests/ for auth tests
|
||||
Agent 4: Scout lib/, utils/ for auth utilities
|
||||
Agent 5: Scout config/ for auth configuration
|
||||
Agent 6: Scout types/, interfaces/ for auth types
|
||||
```
|
||||
|
||||
## Timeout Handling
|
||||
|
||||
- Set 3-minute timeout per agent
|
||||
- Skip non-responding agents
|
||||
- Don't restart timed-out agents
|
||||
- Aggregate available results
|
||||
|
||||
## Reading File Content
|
||||
|
||||
When needing to read file content, use chunking to stay within context limits (<150K tokens safe zone).
|
||||
|
||||
### Step 1: Get Line Counts
|
||||
```bash
|
||||
wc -l path/to/file1.ts path/to/file2.ts path/to/file3.ts
|
||||
```
|
||||
|
||||
### Step 2: Calculate Chunks
|
||||
- **Target:** ~500 lines per chunk (safe for most files)
|
||||
- **Max files per agent:** 3-5 small files OR 1 large file chunked
|
||||
|
||||
**Chunking formula:**
|
||||
```
|
||||
chunks = ceil(total_lines / 500)
|
||||
lines_per_chunk = ceil(total_lines / chunks)
|
||||
```
|
||||
|
||||
### Step 3: Spawn Parallel Bash Agents
|
||||
|
||||
**Small files (<500 lines each):**
|
||||
```
|
||||
Task 1: subagent_type="Bash", prompt="cat file1.ts file2.ts"
|
||||
Task 2: subagent_type="Bash", prompt="cat file3.ts file4.ts"
|
||||
```
|
||||
|
||||
**Large file (>500 lines) - use sed for ranges:**
|
||||
```
|
||||
Task 1: subagent_type="Bash", prompt="sed -n '1,500p' large-file.ts"
|
||||
Task 2: subagent_type="Bash", prompt="sed -n '501,1000p' large-file.ts"
|
||||
Task 3: subagent_type="Bash", prompt="sed -n '1001,1500p' large-file.ts"
|
||||
```
|
||||
|
||||
### Chunking Decision Tree
|
||||
```
|
||||
File < 500 lines → Read entire file
|
||||
File 500-1500 lines → Split into 2-3 chunks
|
||||
File > 1500 lines → Split into ceil(lines/500) chunks
|
||||
```
|
||||
|
||||
Spawn all in single message for parallel execution.
|
||||
|
||||
## Result Aggregation
|
||||
|
||||
Combine results from all agents:
|
||||
1. Deduplicate file paths
|
||||
2. Merge descriptions
|
||||
3. Note any gaps/timeouts
|
||||
4. List unresolved questions
|
||||
125
.opencode/skills/scout/references/task-management-scouting.md
Normal file
125
.opencode/skills/scout/references/task-management-scouting.md
Normal file
@@ -0,0 +1,125 @@
|
||||
# Scout Task Management Patterns
|
||||
|
||||
Track parallel scout agent execution via Claude Native Tasks (TaskCreate, TaskUpdate, TaskList).
|
||||
|
||||
## When to Create Tasks
|
||||
|
||||
| Agents | Create Tasks? | Rationale |
|
||||
|--------|--------------|-----------|
|
||||
| ≤ 2 | No | Overhead exceeds benefit, finishes quickly |
|
||||
| ≥ 3 | Yes | Meaningful coordination, progress monitoring |
|
||||
|
||||
## Task Registration Flow
|
||||
|
||||
```
|
||||
TaskList() // Check for existing scout tasks
|
||||
→ Found tasks? → Skip creation, reuse existing
|
||||
→ Empty? → TaskCreate per agent (see schema below)
|
||||
```
|
||||
|
||||
## Metadata Schema
|
||||
|
||||
```
|
||||
TaskCreate(
|
||||
subject: "Scout {directory} for {target}",
|
||||
activeForm: "Scouting {directory}",
|
||||
description: "Search {directories} for {patterns}",
|
||||
metadata: {
|
||||
agentType: "Explore", // "Explore" (internal) or "Bash" (external)
|
||||
scope: "src/auth/,src/middleware/",
|
||||
scale: 6,
|
||||
agentIndex: 1, // 1-indexed position
|
||||
totalAgents: 6,
|
||||
toolMode: "internal", // "internal" or "external"
|
||||
priority: "P2", // Always P2 for scout coordination
|
||||
effort: "3m" // Fixed timeout per agent
|
||||
}
|
||||
)
|
||||
```
|
||||
|
||||
### Required Fields
|
||||
|
||||
- `agentType` — Subagent type: `"Explore"` for internal, `"Bash"` for external
|
||||
- `scope` — Comma-separated directory boundaries for this agent
|
||||
- `scale` — Total SCALE value determined in Step 1
|
||||
- `agentIndex` / `totalAgents` — Position tracking (e.g., 3 of 6)
|
||||
- `toolMode` — `"internal"` or `"external"`
|
||||
- `priority` — Always `"P2"` (scout = coordination, not primary work)
|
||||
- `effort` — Always `"3m"` (fixed timeout)
|
||||
|
||||
### Optional Fields
|
||||
|
||||
- `searchPatterns` — Key patterns searched (aids debugging)
|
||||
- `externalTool` — If external: `"gemini"` or `"opencode"`
|
||||
|
||||
## Task Lifecycle
|
||||
|
||||
```
|
||||
Step 3: TaskCreate per agent → status: pending
|
||||
Step 4: Before spawning agent → TaskUpdate → status: in_progress
|
||||
Step 5: Agent returns report → TaskUpdate → status: completed
|
||||
Step 5: Agent times out (3m) → Keep in_progress, add error metadata
|
||||
```
|
||||
|
||||
### Timeout Handling
|
||||
|
||||
```
|
||||
TaskUpdate(taskId, {
|
||||
metadata: { ...existing, error: "timeout" }
|
||||
})
|
||||
// Task stays in_progress — distinguishes timeout from incomplete
|
||||
// Log in final report's "Unresolved Questions" section
|
||||
```
|
||||
|
||||
## Examples
|
||||
|
||||
### Internal Scouting (SCALE=6)
|
||||
|
||||
```
|
||||
// Step 3: Register 6 tasks
|
||||
TaskCreate(subject: "Scout src/auth/ for auth files",
|
||||
activeForm: "Scouting src/auth/",
|
||||
metadata: { agentType: "Explore", scope: "src/auth/", scale: 6,
|
||||
agentIndex: 1, totalAgents: 6, toolMode: "internal",
|
||||
priority: "P2", effort: "3m" }) // → taskId1
|
||||
|
||||
// Repeat for agents 2-6 with different scopes
|
||||
|
||||
// Step 4: Spawn agents
|
||||
TaskUpdate(taskId1, { status: "in_progress" })
|
||||
// ... spawn all Explore subagents in single Task tool call
|
||||
|
||||
// Step 5: Collect
|
||||
TaskUpdate(taskId1, { status: "completed" }) // report received
|
||||
TaskUpdate(taskId3, { metadata: { error: "timeout" } }) // timed out
|
||||
```
|
||||
|
||||
### External Scouting (SCALE=3, gemini)
|
||||
|
||||
```
|
||||
TaskCreate(subject: "Scout db/ for migrations via gemini",
|
||||
activeForm: "Scouting db/ via gemini",
|
||||
metadata: { agentType: "Bash", scope: "db/,migrations/", scale: 3,
|
||||
agentIndex: 1, totalAgents: 3, toolMode: "external",
|
||||
externalTool: "gemini", priority: "P2", effort: "3m" })
|
||||
```
|
||||
|
||||
## Integration with Cook/Planning
|
||||
|
||||
Scout tasks are **independent** from cook/planning phase tasks — NOT parent-child.
|
||||
|
||||
**Rationale:** Different lifecycle. Scout completes before cook continues. Mixing creates confusion in TaskList.
|
||||
|
||||
**Sequence when cook spawns scout:**
|
||||
1. Cook Step 2 → spawns planner → planner spawns scout
|
||||
2. Scout registers its own tasks (Step 3), executes (Step 4-5)
|
||||
3. Scout returns aggregated report → planner continues
|
||||
4. Cook Step 3 hydrates phase tasks (separate from scout tasks)
|
||||
|
||||
## Quality Check Output
|
||||
|
||||
After registration: `✓ Registered [N] scout tasks ([internal|external] mode, SCALE={scale})`
|
||||
|
||||
## Error Handling
|
||||
|
||||
If `TaskCreate` fails: log warning, continue without task tracking. Scout remains fully functional — tasks add observability, not functionality.
|
||||
Reference in New Issue
Block a user