initial commit: README and design doc

1 files changed, 90 insertions, 0 deletions

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..8c24c36
--- /dev/null
+++ b/README.md
@@ -0,0 +1,90 @@
+# panto-subagents
+
+Delegation and workflows for [Pantograph](https://github.com/travisp/pantograph).
+The `subagents` extension lets a primary agent start specialized child agents,
+run several at once, and continue their conversations later.
+
+## Install
+
+```toml
+[extensions]
+rocks = ["panto-subagents"]
+```
+
+For a local checkout, use `paths = ["/path/to/panto-subagents"]` instead.
+
+## Agent profiles
+
+Agents are Markdown files with YAML frontmatter:
+
+```markdown
+---
+name: reviewer
+description: Reviews changes for correctness and missing tests
+model: anthropic:sonnet
+reasoning: high
+---
+
+You are a focused code reviewer. Report only concrete findings.
+```
+
+Profiles are loaded recursively from:
+
+- `${XDG_CONFIG_HOME:-$HOME/.config}/panto/agents/`
+- `.panto/agents/` in the current project
+
+Project profiles override user profiles with the same name. `name` defaults to
+the filename. `model` and `reasoning` are optional; each value follows the same
+precedence: tool call, then profile, then the primary agent. Models use full
+`provider:model` names.
+
+## Delegation
+
+The primary uses `subagents.run` to start a child from a profile:
+
+```lua
+subagents.run {
+  agent = "reviewer",
+  prompt = "Review the authentication changes.",
+}
+```
+
+Every started child returns an ID. Passing it back resumes the same
+conversation, including after restarting Panto and resuming the primary:
+
+```lua
+subagents.run {
+  id = "0198...",
+  prompt = "Now focus on the missing tests.",
+}
+```
+
+Children receive the primary's system and project context plus their own
+profile prompt, but not the primary's conversation. They share its workspace
+and tools except for `subagents.*`.
+
+Multiple calls in one tool batch run concurrently. Their tagged assistant and
+tool activity is visible in the TUI while they work. Child conversations are
+stored as normal JSONL sessions beneath their owning primary session, so they
+remain resumable without appearing in the user's `/resume` picker. A child ID
+cannot be resumed from another primary conversation.
+
+`subagents.models` provides bounded search and validation for configured
+providers, models, and model-specific reasoning levels without placing the
+entire model catalog in every tool prompt.
+
+## Workflows
+
+TOML workflows define fixed dependency graphs. They are loaded from
+`${XDG_CONFIG_HOME:-$HOME/.config}/panto/workflows/` and
+`.panto/workflows/`, then exposed as `/workflow:<name>` commands. Ready steps
+run concurrently; each dependent step receives its predecessors' labeled
+outputs.
+
+The Lua workflow API handles dynamic branching and fan-out. It can await one
+job or a group, and supports one-turn workers whose validated tool input is
+their structured result. Panto extensions can use this API directly, while
+`subagents.lua` runs model-authored one-off workflows in a restricted Lua
+environment.
+
+See [DESIGN.md](DESIGN.md) for the runtime and persistence design.