# Proactive Skill Discovery

**BEFORE responding to ANY user request**, identify relevant capabilities and load skills using execute_code.

  MANDATORY FIRST STEP: Before ANY tool search, ALWAYS run discover_skill.sh
   with relevant keywords. Never use ToolSearch, Agent/Explore agents, or
  manual filesystem exploration to find tools. discover_skill.sh is the ONLY
   tool discovery mechanism.

## 1. CWD-Based Discovery

Check the current working directory and extract project keywords from the basename:

```bash
Tool: execute_code
code: basename "$PWD"
```

Strip fork suffixes (e.g., `-lneely`, `-fork`) and split on `-` to get candidate keywords. Run discover_skill on each:

```bash
Tool: execute_code
tool: discover_skill.sh
args: [<cwd-keyword>]
```

Example: cwd `pcloudcc-lneely` → try keywords `pcloudcc`, then `lneely` → finds `pcloudcc-testing`.

## 2. Activity-Based Discovery

Infer the activity type from the task context or user intent and discover matching skills:

| Activity | Keywords to try |
|---|---|
| Testing, verification, bug repro | `testing` |
| Debugging, browser, UI | `debugging`, `web` |
| Notes, docs, writing | `documentation`, `notes` |
| Task/project tracking | `tasks`, `workflow` |
| Agent coordination | `agents`, `sessions`, `messaging` |
| GitHub, PRs, commits | `github`, `vcs` |
| Web search, research | `search`, `web` |
| Knowledge, learning | `knowledge`, `learning` |

```bash
Tool: execute_code
tool: discover_skill.sh
args: [<activity-keyword>]
```

## 3. Load Relevant Skills

```bash
Tool: execute_code
tool: load_skill.sh
args: [skill-name]
```

## After Discovery

Follow the instructions in the loaded SKILL.md. If no skill found, fall back to shell via execute_code.

# Code Exploration

**For code search and exploration**, use `code_explorer.sh` instead of raw find/grep. This reduces token usage via preview-then-fetch workflow.

**CRITICAL: Always use `sandbox: default` with code_explorer.sh** - without it, the tool runs in the wrong directory and indexes nothing.

## Workflow

1. Initialize index (once per worktree):
```bash
Tool: execute_code
tool: code_explorer.sh
args: [init]
sandbox: default
```

2. Preview matches (cheap - counts only, use for initial search):
```bash
Tool: execute_code
tool: code_explorer.sh
args: [preview, "<pattern>"]
sandbox: default
```

3. Fetch specific files (with context):
```bash
Tool: execute_code
tool: code_explorer.sh
args: [fetch, "<pattern>", "<file>"]
sandbox: default
```

4. Search symbols (if ctags index exists):
```bash
Tool: execute_code
tool: code_explorer.sh
args: [symbols, "<pattern>"]
sandbox: default
```

## Fallback

If code_explorer.sh is unavailable or errors, fall back to standard tools (grep, find, etc.). Empty results are valid - do not retry with other tools just because no matches were found.

# Communication

## Tools

Discover agents:
```
Tool: execute_code
pipe: [
	{"tool": "list_sessions.sh"},
	{"code": "grep '<current-working-dir>'"}
]
```

Send message:
```
Tool: execute_code
tool: send_message.sh
args: ["--to", "<id|user>", "--type", "<type>", "--subject", "<subject>", "--body", "<body>"]
```

Check inbox:
```
Tool: execute_code
tool: check_inbox.sh
```

View message history:
```
Tool: execute_code
tool: mail_history.sh
args: ["--agent-id", "<agent-id|user>", "--date", "YYYYMMdd"]
```
`--date` is optional. Omit to see all history.

Search message history:
```
Tool: execute_code
tool: mail_search.sh
args: ["--agent-id", "<agent-id|user>", "--pattern", "<regex>", "--date", "YYYYMMdd"]
```
`--date` is optional.

## Rules

### Discovering Agents

1. You communicate only with "user", or other agents working in the same $(pwd) as yourself

### Sending Messages

1. FROM is taken automatically (do not pass it as an argument)
2. TO is the agent ID of the receiving bot, or "user". If the recipient does not exist, send_message.sh will error.
3. TYPE is the message type: [PROMPT_REQUEST, QUERY_REQUEST, REVIEW_REQUEST, APPROVAL_REQUEST]
3a. Response types mirror request types: PROMPT_REQUEST→PROMPT_RESPONSE, QUERY_REQUEST→QUERY_RESPONSE, REVIEW_REQUEST→REVIEW_RESPONSE, APPROVAL_REQUEST→APPROVAL_RESPONSE.
4. SUBJECT is a brief description of what you did
5. BODY is a detailed summary of what you did, including actions performed, files changed, diffs, etc.

### Receiving Messages

1. Check your inbox
2. Follow the instructions in the message
3. Always respond to the sender (the `from` field of the message), not to "user", unless the sender is "user"

# Sub-agent Discipline

Do NOT spawn sub-agents for:
- Checking or responding to inbox messages
- Reading beads or bead status
- Any single-tool operation

Spawn sub-agents only for genuinely parallel, multi-step, independent workstreams.

# File Addressing and Identifiers

Use Acme/sam address syntax for locations: `/path/to/file.go:123`, `/path/to/file.go:123,125`, `/path/to/file.go:/funcName/`. Wrap identifiers in backticks: `funcName()`, `--flag`, `TypeName`.