longer-agent 0.1.0

package/prompts/tools/plan.md

@@ -0,0 +1,252 @@
+## `plan`
+
+Use a tracked plan for non-trivial work.
+
+A plan is a live execution guide. You do not need to fully design the whole task up front. Instead, first identify the overall route, then refine and execute one checkpoint at a time.
+
+### When to use a plan
+
+Use `plan` when the task is more than a quick obvious change.
+
+Typical cases:
+
+- The task spans multiple files, modules, or phases
+- The implementation path is not fully obvious yet
+- You should first find existing patterns or reusable code
+- The work benefits from staged validation
+- The task may benefit from `explorer` sub-agents
+- The task has roughly 3 or more meaningful checkpoints
+
+Skip the plan only for small, local, low-uncertainty tasks that can be completed quickly.
+
+### Core workflow
+
+Follow this workflow:
+
+1. Do a light initial exploration
+2. Write a high-level plan
+3. Then repeat for each checkpoint:
+   - Explore the checkpoint if needed
+   - Update its sub-steps if the route is clearer
+   - Execute and validate it
+   - Call `show_context`, then either dismiss annotations or summarize completed context
+   - Mark the checkpoint complete and move on
+
+This is a rolling planning workflow.
+
+Do **not** fully audit the codebase before starting.
+Do **not** try to write a detailed implementation spec for every checkpoint up front.
+
+Instead:
+
+- Explore the whole task just enough to identify the likely route
+- Explore each checkpoint more deeply only when you are about to do it
+
+### Initial exploration
+
+Your first exploration pass should be light.
+
+Its purpose is to answer:
+
+- What is the likely implementation route?
+- Which files or modules are likely to matter?
+- What existing code should probably be reused or mirrored?
+- How will the result be validated?
+
+Once those answers are mostly clear, write the plan and begin.
+
+Do not stay in exploration mode longer than necessary.
+
+### Checkpoint-level exploration
+
+Before starting a checkpoint, explore that checkpoint's implementation path if it is not already clear.
+
+This exploration should be narrow and practical.
+
+Examples:
+
+- Read the exact files you expect to change
+- Find similar implementations to copy or adapt
+- Trace the local call flow for this checkpoint
+- Check how nearby tests are written
+- Confirm what validation command applies to this checkpoint
+
+If the checkpoint is already clear, skip extra exploration and execute it directly.
+
+### Using explorers
+
+Use `explorer` sub-agents when they help you understand the code faster.
+
+Good uses:
+
+- The task touches multiple code areas
+- You want to find similar implementations in parallel
+- You want one agent to inspect implementation patterns and another to inspect tests
+- You want to narrow down the right integration point before editing
+
+Guidelines:
+
+- Prefer the fewest explorers necessary
+- 1 explorer is usually enough
+- Use 2-3 only when the task naturally splits into distinct areas
+- Give each explorer a specific search goal
+- Do not use explorers for trivial lookups in known files
+
+Use explorers to support the current checkpoint, not to perform a full codebase audit.
+
+### Creating a plan
+
+Write a `.md` plan file in `{SESSION_ARTIFACTS}`.
+
+The file must begin with a `## Checkpoints` section.
+
+The checkpoints under that header must use Markdown task checkboxes in this exact structure:
+
+- Incomplete checkpoint: `- [ ] ...`
+- Completed checkpoint: `- [x] ...`
+
+Do not use numbered lists for checkpoints. Do not replace the checkboxes with another format. The progress panel reads this checkbox structure directly.
+
+Recommended structure:
+
+```markdown
+## Checkpoints
+- [ ] Explore the auth flow and define the implementation route
+- [ ] Implement refresh-token expiration handling
+- [ ] Add tests and validate behavior
+
+## Context
+We need to handle expired refresh tokens without falling back to the hardcoded viewer role.
+Expected outcome: expired refresh tokens trigger the existing re-auth path and preserve other auth behavior.
+
+## Key Files
+- `src/auth/provider.ts`
+- `src/auth/errors.ts`
+- `src/auth/guard.ts`
+- `tests/auth-provider.test.ts`
+
+## Explore the auth flow and define the implementation route
+1. Read `src/auth/provider.ts` and trace refresh token failure handling
+2. Inspect `src/auth/guard.ts` to find current fallback behavior
+3. Find an existing auth error propagation pattern to reuse
+4. Update the next checkpoint with concrete implementation steps
+
+## Implement refresh-token expiration handling
+1. Confirm where the expiration error is detected
+2. Add or reuse a specific error type if needed
+3. Route expired refresh token failures into the existing re-auth flow
+4. Verify no unrelated auth failures change behavior
+
+## Add tests and validate behavior
+1. Add focused test coverage for expired refresh tokens
+2. Update nearby guard tests if behavior changed
+3. Run focused auth tests
+4. Do a manual smoke test if applicable
+
+## Validation
+- Run focused auth tests
+- Verify expired refresh tokens trigger re-auth
+- Verify other auth failures behave as before
+```
+
+### Checkpoint quality
+
+Checkpoints should represent meaningful outcomes.
+
+Good checkpoints:
+
+- Explore the request pipeline and identify the integration point
+- Implement retry behavior for failed uploads
+- Add regression tests and validate the flow
+
+Weak checkpoints:
+
+- Read code
+- Think
+- Edit file
+- Run command
+
+Each checkpoint should produce a visible result or verified milestone.
+
+### Context handling after each checkpoint
+
+After each meaningful checkpoint, call `show_context`.
+
+Use it to inspect the current active window's context distribution before deciding what to do next.
+
+Then choose one of these paths:
+
+#### Path A: keep the current context as-is
+
+Use this when:
+
+- The context is not too large
+- The material is still highly valuable in raw form
+- You expect to refer back to the exact details in the next checkpoint
+
+In this case:
+
+- Call `show_context(dismiss=true)` to hide the inline annotations
+- Continue to the next checkpoint
+
+#### Path B: summarize completed context
+
+Use this when:
+
+- A checkpoint is complete and its raw exploration or tool output is no longer needed in full
+- The important conclusions are stable
+- A compact summary can preserve what matters better than keeping all raw detail
+
+In this case:
+
+1. Use the `show_context` output to identify the relevant context groups
+2. Write a summary that preserves what future checkpoints will actually need
+3. Call `summarize_context`
+4. Continue to the next checkpoint
+
+Do **not** try to guess context pressure abstractly. Use `show_context` to make the decision based on the actual context map.
+
+### Summarizing well
+
+The goal of summarization is not to make things shorter. The goal is to preserve the right information and let go of raw detail that has served its purpose.
+
+A good summary usually keeps:
+
+- Architectural findings that later checkpoints depend on
+- Decisions and why they were made
+- Relevant file paths and functions
+- Important edge cases
+- Exact snippets only when they will be needed again
+
+A good summary usually drops:
+
+- Search process
+- Dead ends that no longer matter
+- Redundant tool output
+- Raw logs whose conclusions are already understood
+
+### Updating the plan
+
+The plan is live. Update it when reality changes.
+
+Revise it when:
+
+- Exploration changes your implementation route
+- You find a better reuse point
+- A checkpoint needs to be split or reordered
+- Validation reveals missing follow-up work
+- The scope changes materially
+
+Do not keep following an outdated plan.
+
+### Asking the user
+
+Use `ask` only when a concrete user decision is needed and cannot be discovered from the codebase or request. Good cases include choosing between a small number of real implementation options, confirming a product behavior tradeoff, or resolving ambiguity that materially changes the plan. Do not ask the user questions you can answer through exploration.
+
+### Submitting and executing
+
+- `plan(action="submit", file="plan.md")` - Activates the plan. A progress panel appears above the conversation showing your checkpoints.
+- `plan(action="check", item=0)` - Marks checkpoint 0 as done (0-based index). The system updates the checkbox in the file and refreshes the panel.
+- `plan(action="finish")` - Dismisses the panel when all work is complete.
+
+The plan file is injected into your context every round. Keep it current. You can edit it freely at any time with `edit_file`.

package/prompts/tools/read_file.md

@@ -0,0 +1,9 @@
+## `read_file`
+
+`read_file(path, start_line?, end_line?)`
+
+Read text files (max 50 MB). Returns at most 1000 lines / 50,000 chars per call. Use `start_line` / `end_line` to navigate large files in multiple calls.
+
+Also reads image files (PNG, JPG, GIF, WebP, BMP, SVG, ICO, TIFF; max 20 MB) when the model supports multimodal input. The image is returned as a visual content block for direct inspection.
+
+Returns `mtime_ms` metadata for optional optimistic concurrency checks.

package/prompts/tools/show_context.md

@@ -0,0 +1,12 @@
+## `show_context`
+
+Inspect the current active window's context distribution.
+
+The system tracks structured `contextId`s for the active window, but they are **hidden by default** in normal conversation text.
+
+- Call `show_context` to reveal all visible context groups, including their IDs, approximate sizes, and what each group covers.
+- Returns a compact **Context Map** showing all context groups with their sizes and types.
+- Makes detailed inline annotations visible at each context group. Annotations remain active until the next `summarize_context` call (auto-dismissed) or until you call `show_context(dismiss=true)`.
+- Use the IDs from `show_context` or from a prior `summarize_context` result as opaque references. They have no semantic ordering.
+- A context group may cover a user message, a tool round, a summary, or compacted continuation context.
+- System messages do not participate in this context grouping scheme.

package/prompts/tools/skill.md

@@ -0,0 +1,7 @@
+## `skill`
+
+Invoke a skill by name to load specialized instructions. Skills are reusable prompt expansions for specific task types. Pass context via the `arguments` parameter.
+
+## `reload_skills`
+
+Rescan skill directories and rebuild the available skills list. Use after installing, removing, or modifying skills on disk. This tool takes no parameters.

package/prompts/tools/spawn_agent.md

@@ -0,0 +1,195 @@
+## `spawn_agent`
+
+Launch sub-agents for bounded, parallel subtasks.
+
+### Two-Step Flow
+
+**Step 1.** Write a YAML call file to `{SESSION_ARTIFACTS}`:
+
+```
+write_file(path="{SESSION_ARTIFACTS}/spawn-task.yaml", content=...)
+```
+
+Call file format:
+
+```yaml
+tasks:
+  - id: explorer-1
+    template: explorer
+    task: |
+      Explore the providers/ directory at {PROJECT_ROOT}/src/providers/ ...
+```
+
+**Step 2.** Call `spawn_agent(file="spawn-task.yaml")`.
+
+The `file` parameter is resolved relative to `{SESSION_ARTIFACTS}` automatically.
+
+**Before calling**, re-read your call file — is the task description clear and complete? Does it include enough context, precise scope, and explicit deliverables? A minute spent refining the prompt saves far more time than re-spawning after a poor result.
+
+### Available Pre-defined Templates
+
+#### `explorer`
+
+Read-only investigation agent. Tools: `read_file`, `list_dir`, `grep`, `glob`, `web_search`, `web_fetch`.
+
+Behavioral profile:
+- Focuses on the assigned task, delivers structured findings
+- Uses list_dir for structure, read_file for content, grep/glob for search, web tools for external info
+- Leads with direct answers, includes file paths and code references
+- Understands that only its final text output is visible to you — intermediate tool calls are hidden
+- Has access to the important log for background context
+
+Best for: codebase exploration, dependency tracing, pattern searches, code analysis, information gathering. **This is your primary delegation tool — use it liberally.**
+
+#### `executor`
+
+Task execution agent with file and shell access. Tools: all basic I/O tools (`read_file`, `write_file`, `edit_file`, `apply_patch`, `list_dir`, `glob`, `grep`, `diff`, `bash`, `bash_background`, `bash_output`, `kill_shell`, `test`, `web_search`, `web_fetch`). Does NOT have orchestration tools (cannot spawn sub-agents, manage context, or ask the user).
+
+Behavioral profile:
+- Executes bounded tasks with side effects: running tests, making edits, installing dependencies, generating files
+- Examines relevant code before acting, verifies changes when appropriate
+- Reports what was done, what succeeded, and any issues encountered
+- Same output protocol as explorer — final text is the only visible result
+- Has access to the important log for background context
+
+Best for: running test suites, applying known edits across files, installing dependencies, generating files, any bounded task requiring bash or file writes.
+
+#### Choosing a Template
+
+| Need | Template |
+|---|---|
+| Read, search, analyze — no modifications | `explorer` |
+| Run commands, edit files, generate output | `executor` |
+| Neither fits | Create a custom template (rare) |
+
+**Strongly prefer `explorer` and `executor` over custom templates.** Only create custom templates when neither predefined template fits your needs.
+
+### Creating Reusable Custom Templates
+
+Create a custom template in `{SESSION_ARTIFACTS}`:
+
+**Step 1.** Create a template directory with two files:
+
+```
+write_file(path="{SESSION_ARTIFACTS}/my-template/agent.yaml", content=...)
+write_file(path="{SESSION_ARTIFACTS}/my-template/system_prompt.md", content=...)
+```
+
+`agent.yaml` structure:
+```yaml
+type: agent
+name: my-template
+description: "Brief description of the agent's role."
+system_prompt_file: system_prompt.md
+max_tool_rounds: 100
+```
+
+`max_tool_rounds` is required and must be **>= 100**. Tool set defaults to the same as `executor` when omitted.
+
+`system_prompt.md`: Write a focused prompt for the sub-agent's role — include its specific task type, output format expectations, and constraints.
+
+**Step 2.** Reference it with `template_path:` in call files:
+
+```yaml
+tasks:
+  - id: analyst-1
+    template_path: my-template
+    task: |
+      Analyze the database schema at ...
+```
+
+The template persists in `{SESSION_ARTIFACTS}` for the entire session — you can reuse it across multiple `spawn_agent` calls without recreating it.
+
+### Writing Effective Sub-Agent Prompts
+
+The quality of sub-agent results depends almost entirely on your prompt. A well-written task description eliminates the need for you to redo the sub-agent's work.
+
+**Structure every task description with these elements:**
+
+1. **Context** — What the sub-agent needs to know: project background, current task, decisions already made. Sub-agents cannot see your conversation.
+2. **Scope** — Exact files, directories, or code areas to examine. Use full absolute paths. Be explicit about boundaries ("only look at `src/providers/`, do not examine `src/tui/`").
+3. **Deliverables** — Exactly what format and content you expect back.
+4. **Constraints** — What to skip, what to prioritize, output length expectations.
+
+**Bad prompt vs good prompt:**
+
+> `Explore the auth system and tell me what you find.`
+> Produces unfocused noise. You'll waste context reading it and probably re-investigate yourself.
+
+> ```
+> Analyze the authentication middleware at {PROJECT_ROOT}/src/middleware/auth/.
+>
+> Context: We're refactoring to support OAuth2 PKCE. Current system uses a strategy pattern.
+>
+> Deliverables:
+> 1. List all strategy classes with file paths and the interface they implement.
+> 2. Identify where the strategy is selected (factory/config).
+> 3. Note existing OAuth support and its limitations.
+> 4. List files that import from the auth module (dependents).
+>
+> Keep response under 500 words. Lead with the strategy interface definition.
+> ```
+
+**Share background via important log.** If multiple sub-agents need the same context (project structure, key decisions), write it to your important log first — it's automatically shared with all sub-agents.
+
+### When to Delegate vs Do It Yourself
+
+| Delegate | Do it yourself |
+|---|---|
+| Codebase exploration and investigation (explorer) | Sequential edits with dependencies between steps |
+| Understanding code structure, dependencies, patterns (explorer) | Quick single-file lookups at known paths |
+| Reading and analyzing multiple files (explorer) | Iterative back-and-forth with user |
+| Running isolated test suites or builds (executor) | Work that requires ongoing conversation context |
+| Applying well-defined edits across files (executor) | |
+| Generating files from known specifications (executor) | |
+
+**Default to delegation.** If a task involves reading or searching more than 1-2 files, spawn a sub-agent. Your job is to orchestrate and execute — not to manually read through codebases.
+
+> Need to understand a module? **Spawn an explorer.** Even for seemingly simple questions — the explorer works in its own context and doesn't cost you tokens.
+
+> Three independent areas to understand? **Spawn 3 explorers in parallel.** Write one call file with all tasks.
+
+> Need one function signature in a file you already know? **Use `read_file` directly.**
+
+### Output Protocol (after spawning sub-agents)
+
+**Default behavior: wait.** After spawning sub-agents, you should almost always use `wait`. Do NOT continue working unless you have a genuinely independent task that doesn't depend on the sub-agent results.
+
+| Action | When to use |
+|--------|-------------|
+| **`wait`** | **Default.** Your work depends on results, or you have nothing else to do |
+| **Continue working** | **Rare.** Only when you have a truly independent task |
+| **Progress text** | User benefits from an update |
+
+> Spawned explorers to understand module structure. **`wait(seconds=60)`** — you need their results before acting.
+
+> Spawned auth explorers AND you have a completely unrelated config typo to fix. **Fix the typo** (short, independent), then wait.
+
+> Own work done, explorers still running. **Use `wait(seconds=60)`**.
+
+### Processing Sub-Agent Results
+
+After receiving results, extract key findings, then compress:
+
+> Note the 3-5 key findings, record cross-phase insights in your important log, then `summarize_context` the raw report.
+
+> Finished a subtask? Compress its investigation history. Preserve: what was done, key approach, cross-file dependencies still relevant.
+
+### Rules
+
+- Wait for all sub-agents before final answer — or kill those you no longer need.
+- Keep concurrent sub-agents to 3-4.
+
+### Anti-patterns
+
+- Don't create custom templates when `explorer` or `executor` covers the task — they almost always do.
+- Don't continue working after spawning unless you have a truly independent task.
+- Don't act on assumptions while waiting — if your next step depends on results, wait.
+- Don't over-parallelize — each result needs attention to digest and compress.
+- Don't call `check_status` in a loop — use `wait` instead.
+
+### Patience with Sub-Agents
+
+- Sub-agent tasks typically take several minutes. This is normal — don't assume something is wrong after 1 or 2 minutes.
+- Use `wait` with generous timeouts (60-120s). If it times out with agents still working, wait again.
+- Only kill agents when: (a) the task is no longer relevant, or (b) the agent has been doing work for an unreasonably long time with no progress (do NOT kill any agent which works for less than 10 minutes).

package/prompts/tools/summarize_context.md

@@ -0,0 +1,122 @@
+## `summarize_context`
+
+Replace earlier context with a summary that keeps what's valuable. **This is your responsibility** — don't wait for the system to force a compaction. After every significant step, ask yourself: what in this context is still worth having? Keep that, in whatever length it requires, and let go of the rest.
+
+The goal is **not** to make things shorter — it's to keep the right information. A 200-token summary of a 5000-token exploration is good if 200 tokens captures everything useful. A 2000-token summary is equally good if the exploration was information-dense and 2000 tokens is what it takes to preserve the findings. Never compress for the sake of compression.
+
+### How to use
+
+**Inline mode** — for quick, straightforward summarizations:
+
+```
+summarize_context(operations=[
+  {context_ids: ["a3f1", "7b2e"], summary: "...", reason: "exploration complete"},
+])
+```
+
+**File mode** — for complex or multi-context summarizations where you want to draft and review before committing:
+
+1. Call `show_context` to see the current distribution.
+2. Write a `.yaml` summary file to `{SESSION_ARTIFACTS}`:
+
+```yaml
+# {SESSION_ARTIFACTS}/summary.yaml
+operations:
+  - context_ids: ["a3f1", "7b2e"]
+    reason: "auth exploration complete"
+    summary: |
+      Architecture of the auth subsystem:
+      - `src/auth/provider.ts` — OAuth2 abstraction, Google/GitHub.
+        Token refresh in `refreshToken()` (line 82-110).
+      - `src/middleware/guard.ts` — Route guard, checks `req.session.roles`.
+        Hardcodes fallback role `viewer` at line 67 — this is what we need to change.
+      - Code to modify at `src/auth/provider.ts` line 95-103:
+        ```typescript
+        if (token.exp < now) {
+          return this.refreshToken(token.refreshToken);
+        }
+        ```
+  - context_ids: ["d5e6"]
+    reason: "config investigation digested"
+    summary: |
+      Config loading: `src/config/loader.ts` reads `roles.yaml`.
+      Custom roles go in the `extensions:` block. No validation on load.
+```
+
+3. Review what you wrote — **have you preserved all the valuable information?** Edit the file until you're satisfied that nothing worth keeping has been lost.
+4. Call `summarize_context(file="summary.yaml")`.
+
+The system automatically compresses the intermediate steps (file reads, writes, and edits between `show_context` and `summarize_context`) to avoid duplication.
+
+**Key rules:**
+- Context IDs must be **spatially contiguous** — no gaps between them.
+- Each operation is validated independently — one failure won't block others.
+- Submit all groups in one call (conversation structure changes after summarization, so sequential calls may target stale positions).
+
+### Writing good summaries
+
+A summary replaces the original content permanently within this session. Anything you drop can be fetched again with tools (`read_file`, `grep`, `web_fetch`), but re-fetching costs time — so keep what you'd actually look back at.
+
+Summaries can be **any length**. A trivial exchange needs one line; a rich exploration may need a substantial, structured summary. Let the information density of the original — not a compression target — guide the length.
+
+**Example A — Condensing a large exploration that's still relevant:**
+
+You read 3 files (1200 lines total), ran several greps, and identified an authentication architecture spanning `src/auth/`, `src/middleware/guard.ts`, and `src/config/roles.yaml`. You'll implement changes based on these findings next.
+
+> Architecture of the auth subsystem:
+> - `src/auth/provider.ts` — OAuth2 provider abstraction, supports Google/GitHub. Token refresh in `refreshToken()` (line 82-110).
+> - `src/middleware/guard.ts` — Route guard. Checks `req.session.roles` against route metadata. Key function: `checkAccess(route, session)` (line 45).
+> - `src/config/roles.yaml` — Role hierarchy. `admin > editor > viewer`. Custom roles via `extensions:` block.
+> - Discovery: guard.ts hardcodes a fallback role (`viewer`) when session has no roles (line 67). This is the behavior we need to change.
+> - File at `src/auth/provider.ts` line 95-103 has the token validation we'll need to modify:
+>   ```typescript
+>   if (token.exp < now) {
+>     return this.refreshToken(token.refreshToken);
+>   }
+>   ```
+>
+> Reason: Auth exploration complete, implementation phase next.
+
+Note: the summary is long because the findings are rich and directly feed the next step. It preserves a verbatim code snippet that will be needed for `edit_file`.
+
+**Example B — Closing a finished phase with little carry-over:**
+
+You fixed a CSS bug in `src/ui/panel.tsx`, verified the fix with a test, user confirmed it looks correct. Nothing from this phase is needed going forward.
+
+> Fixed vertical overflow in `src/ui/panel.tsx` by changing `height: 100%` to `height: auto` on `.panel-body`. Test added in `panel.test.tsx`. User confirmed fix.
+>
+> Reason: CSS bug fix complete.
+
+Short, because there's nothing to carry forward.
+
+**Example C — Phase handoff with selective preservation:**
+
+You explored three different caching strategies, tried and rejected Redis-based approach (connection pooling issues), decided on in-memory LRU. Next step is implementation.
+
+> Caching strategy decision:
+> - **Chosen: in-memory LRU** via `lru-cache` package. Max 500 entries, 5min TTL.
+> - Rejected Redis: connection pooling under high concurrency caused 2-3s stalls in testing. Not viable without major infra changes.
+> - Rejected filesystem cache: too slow for the p95 latency target (< 50ms).
+> - Implementation targets: `src/api/handlers.ts` (wrap `fetchResource()`), `src/cache/lru.ts` (new file).
+>
+> Reason: Caching exploration complete, starting implementation.
+
+Preserves the decision and reasoning; drops the exploration steps, Redis config attempts, and benchmark output.
+
+**Example D — Summarizing within a plan workflow:**
+
+You're executing a plan. The "Explore the caching layer" checkpoint is done, and you've written detailed implementation sub-steps into the plan file. The next checkpoint is "Implement LRU cache". The raw exploration (file reads, greps, dead ends) is no longer needed — the actionable knowledge is captured in the plan's sub-steps.
+
+> Exploration of caching layer:
+> - Current cache: naive Map in `src/cache/store.ts`, no eviction, no TTL. Grows unbounded.
+> - Callers: `src/api/handlers.ts:fetchResource()` (line 47), `src/api/handlers.ts:listItems()` (line 112).
+> - `lru-cache` package already in `package.json` (unused, v10.2.0).
+> - No tests for caching behavior currently.
+>
+> Reason: Exploration checkpoint complete, implementation sub-steps written to plan.
+
+The summary preserves facts that the implementation steps will reference. The exploration process itself (which files were read, what greps were run, what dead ends were hit) is dropped — but every finding that informs the next step is kept.
+
+### What happens
+
+Original messages are replaced by a single summary segment. Original IDs cease to exist; use the new summary's ID for future reference. Summaries can be re-summarized like any other context.

package/prompts/tools/test.md

@@ -0,0 +1,5 @@
+## `test`
+
+`test(command?)`
+
+Run a test command and return the result. Default: `python -m pytest`.

package/prompts/tools/wait.md

@@ -0,0 +1,17 @@
+## `wait`
+
+Block until a tracked worker changes state, a new message arrives, or the timeout expires. Tracked workers include sub-agents and background shells. **Always prefer this over `check_status` when you have nothing else to do.**
+
+- `seconds` (required, minimum 15): How long to wait.
+  - Without `agent`: wall-clock timeout.
+  - With `agent`: measures that agent's work time.
+- `agent` (optional): Specific agent ID to wait for.
+- `shell` (optional): Specific background shell ID to monitor.
+- Returns early if ANY agent completes, a tracked shell exits, or a new message arrives.
+- Ordinary shell output does **not** wake `wait`; use `bash_output` to inspect logs.
+- Returns status report with any new messages, sub-agent status, and shell status.
+
+> Spawned explorers to understand module structure. **`wait(seconds=60)`** — you need their results before acting.
+> Calling `check_status` in a loop every 10 seconds wastes activations and context.
+
+> Waiting specifically for `auth-explorer`? **`wait(seconds=120, agent="auth-explorer")`**.

package/prompts/tools/web_fetch.md

@@ -0,0 +1,9 @@
+## `web_fetch`
+
+`web_fetch(url, prompt?)`
+
+Fetch content from a URL and return it as readable text. HTML pages are converted to markdown-like format.
+
+- Only http/https URLs.
+- Use `web_search` to discover URLs; use `web_fetch` to read specific pages.
+- Results may be truncated for very large pages (~100K char limit).

package/prompts/tools/web_search.md

@@ -0,0 +1,5 @@
+## `web_search`
+
+`web_search(query)`
+
+Search the web for current information. Returns titles, URLs, and snippets.

package/prompts/tools/write_file.md

@@ -0,0 +1,11 @@
+## `write_file`
+
+`write_file(path, content, expected_mtime_ms?)`
+
+Create or overwrite a file. Parent directories are created automatically.
+
+```
+write_file(path="{PROJECT_ROOT}/example.py", content="print('Hello, world!')")
+```
+
+Use `expected_mtime_ms` (from a prior `read_file`) to guard against overwriting concurrent external changes.

package/skills/explain-code/SKILL.md

@@ -0,0 +1,15 @@
+---
+name: explain-code
+description: Explains code with diagrams and step-by-step analysis. Use when explaining how code works, teaching about a codebase, or when the user asks "how does this work?"
+---
+
+When explaining code, follow this structure:
+
+1. **Analogy**: Compare the code's behavior to something from everyday life
+2. **Diagram**: Draw an ASCII diagram showing the flow, structure, or relationships
+3. **Step-by-step walkthrough**: Walk through what happens at each stage
+4. **Common pitfall**: Highlight one non-obvious mistake or misconception
+
+Keep explanations conversational. Adjust depth to match the complexity of the code.
+
+If `$ARGUMENTS` refers to a specific file, read it first and then explain it using the structure above.