chore: track agent-CLI note + ignore prompts/

2 files changed, 66 insertions, 1 deletions

diff --git a/.gitignore b/.gitignore
index fcdac3a..786e3e2 100644
--- a/.gitignore
+++ b/.gitignore
@@ -6,7 +6,8 @@ build/
 # Local test credentials — never commit.
 .env
 
-# Agent work reports — local only.
+# Agent prompts (orchestrator→subagent) and work reports — local only.
+prompts/
 reports/
 
 # OS / editor noise
diff --git a/notes/opencode-agents.md b/notes/opencode-agents.md
new file mode 100644
index 0000000..5a8e489
--- /dev/null
+++ b/notes/opencode-agents.md
@@ -0,0 +1,64 @@
+# Spawning OpenCode Agents via CLI
+
+## Non-interactive (headless) run
+
+`opencode run` streams output to stdout and exits — no TUI opens.
+
+```bash
+opencode run "your prompt here"
+```
+
+## Key flags
+
+| Flag | Short | Purpose |
+|------|-------|---------|
+| `--dir` | | Working directory for the agent |
+| `-m provider/model` | `--model` | Which model to use |
+| `-f path/to/file` | `--file` | Attach a file to the message |
+| `--agent` | | Which agent profile to use |
+| `--format json` | | Raw JSON events instead of formatted text |
+| `--dangerously-skip-permissions` | | Auto-approve all permissions (dangerous!) |
+
+## Examples
+
+### Run with a specific model and CWD
+
+```bash
+opencode run --dir /path/to/project -m opencode-go/qwen3.7-max "your prompt"
+```
+
+### Attach a file as context
+
+```bash
+opencode run --dir /path/to/project -m opencode-go/qwen3.7-max -f prompt.md "follow the instructions in the attached file"
+```
+
+### Pipe file content as the prompt itself
+
+```bash
+opencode run --dir /path/to/project -m opencode-go/qwen3.7-max "$(cat prompt.md)"
+```
+
+### Use a specific agent profile
+
+```bash
+opencode run --dir /path/to/project --agent my-agent -f prompt.md "do it"
+```
+
+### JSON output for scripting
+
+```bash
+opencode run --dir /path/to/project -m opencode-go/qwen3.7-max -f prompt.md "do it" --format json
+```
+
+## API key configuration
+
+- **Env var:** `ANTHROPIC_API_KEY=sk-... opencode run ...` (provider-specific)
+- **Persisted:** `opencode auth login --provider anthropic`
+- **Project `.env`:** opencode reads `.env` on startup
+
+## Listing available agents
+
+```bash
+opencode agent list
+```