commit edd8a633c57a93f33a8f028a6baeedb888bf1009
Author: Ben Sima <ben@bensima.com>
Date: Thu Jan 1 19:28:26 2026
Omni/Agentd: Add spec format documentation and examples
SPEC.md defines the agentd workflow format:
- YAML frontmatter for container config (toolchain, workspace, limits)
- Markdown body is the task passed to agent
- Stdin injection for piping data (e.g., task JSON)
- Automatic mounts: workspace (rw), repo (ro), auth (ro)
Examples:
- Implement.md - Feature implementation workflow
- Review.md - Code review workflow
- Research.md - Research task workflow
Task-Id: t-320.1
diff --git a/Omni/Agentd/Examples/Implement.md b/Omni/Agentd/Examples/Implement.md
new file mode 100644
index 00000000..87c1f0ef
--- /dev/null
+++ b/Omni/Agentd/Examples/Implement.md
@@ -0,0 +1,29 @@
+---
+toolchain: haskell
+workspace: .
+max_cost_cents: 200
+max_iterations: 100
+---
+
+Implement the task described in the input JSON.
+
+## Instructions
+
+1. Read AGENTS.md for project context and skill index
+2. Load the Coder skill from Omni/Ide/Coder.md
+3. Understand the task requirements from the input
+4. Make the necessary code changes
+5. Build with `bild` to verify
+6. Run tests if applicable
+7. Commit with a descriptive message (use --no-gpg-sign)
+
+## Input Format
+
+The input is JSON from `task show <id> --json` containing:
+- taskTitle: What to implement
+- taskDescription: Detailed requirements
+- taskNamespace: Where in the codebase
+
+## Output
+
+Summarize what was done and any issues encountered.
diff --git a/Omni/Agentd/Examples/Research.md b/Omni/Agentd/Examples/Research.md
new file mode 100644
index 00000000..37dcbf68
--- /dev/null
+++ b/Omni/Agentd/Examples/Research.md
@@ -0,0 +1,23 @@
+---
+toolchain: base
+workspace: .
+max_cost_cents: 100
+max_iterations: 50
+---
+
+Research the topic described in the input.
+
+## Instructions
+
+1. Read AGENTS.md for context
+2. Load the Research skill from Omni/Agent/Research.md
+3. Use web_search for current information
+4. Synthesize findings into a clear report
+
+## Output
+
+A structured report with:
+- Executive summary
+- Key findings
+- Sources
+- Recommendations (if applicable)
diff --git a/Omni/Agentd/Examples/Review.md b/Omni/Agentd/Examples/Review.md
new file mode 100644
index 00000000..32e26b7d
--- /dev/null
+++ b/Omni/Agentd/Examples/Review.md
@@ -0,0 +1,28 @@
+---
+toolchain: git
+workspace: .
+max_cost_cents: 50
+max_iterations: 30
+---
+
+Review the code changes in this branch.
+
+## Instructions
+
+1. Read AGENTS.md for project conventions
+2. Load the Reviewer skill from Omni/Ide/Reviewer.md
+3. Run `git diff main` to see changes
+4. Check for:
+ - Correctness
+ - Style/conventions
+ - Potential bugs
+ - Missing tests
+ - Documentation
+
+## Output
+
+Provide structured feedback:
+- Summary of changes
+- Issues found (if any)
+- Suggestions for improvement
+- Approval status: APPROVE / REQUEST_CHANGES / COMMENT
diff --git a/Omni/Agentd/SPEC.md b/Omni/Agentd/SPEC.md
new file mode 100644
index 00000000..a466818c
--- /dev/null
+++ b/Omni/Agentd/SPEC.md
@@ -0,0 +1,149 @@
+# Agentd Spec Format
+
+Agentd runs agent workflows in isolated OCI containers. Specs are markdown files with YAML frontmatter.
+
+## Format
+
+```markdown
+---
+toolchain: haskell
+workspace: .
+---
+
+Your task goes here.
+```
+
+The frontmatter configures the container. The body is the task passed to `agent`.
+
+## Frontmatter Fields
+
+| Field | Type | Required | Default | Description |
+|-------|------|----------|---------|-------------|
+| `toolchain` | string | yes | - | OCI image to use (see Toolchains) |
+| `workspace` | path | yes | - | Host path mounted at `/workspace` (writable) |
+| `model` | string | no | `claude-sonnet-4` | Model override |
+| `provider` | string | no | `claude-code` | Auth provider |
+| `max_cost_cents` | int | no | `100` | Cost limit in cents |
+| `max_iterations` | int | no | `50` | Agent iteration limit |
+
+### Toolchains
+
+| Name | Contents |
+|------|----------|
+| `base` | agent + busybox |
+| `git` | base + git |
+| `haskell` | git + ghc + cabal + bild |
+
+## Container Mounts
+
+Agentd automatically mounts:
+
+| Host | Container | Mode | Purpose |
+|------|-----------|------|---------|
+| `<workspace>` | `/workspace` | rw | Agent's working directory |
+| `<repo-root>` | `/repo` | ro | Access to AGENTS.md, skills, code |
+| `~/.config/agent/` | `/root/.config/agent/` | ro | OAuth tokens |
+
+The agent's CWD is `/workspace`.
+
+## Body (Task)
+
+Everything after the closing `---` is the task. This is passed to `agent` as the prompt.
+
+### Stdin Injection
+
+If stdin is provided to `agentd run`, it's appended to the task:
+
+```
+<task body>
+
+---
+Input:
+<stdin content>
+```
+
+This enables piping data into workflows:
+
+```bash
+task show t-123 --json | agentd run implement.md
+```
+
+## Skill Loading
+
+The agent reads `/repo/AGENTS.md` which contains the skill index. It loads skills on demand via `read_file` (e.g., `/repo/Omni/Ide/Coder.md`).
+
+No special skill injection - the agent decides what to load based on the task.
+
+## Environment Variables
+
+The container inherits these from the host:
+
+- `ANTHROPIC_API_KEY`
+- `OPENROUTER_API_KEY`
+- `KAGI_API_KEY`
+
+OAuth tokens are accessed via the mounted config directory.
+
+## Examples
+
+### Simple task
+
+```markdown
+---
+toolchain: git
+workspace: .
+---
+
+List all TODO comments in the codebase.
+```
+
+### Implementation workflow
+
+```markdown
+---
+toolchain: haskell
+workspace: .
+max_cost_cents: 200
+max_iterations: 100
+---
+
+Implement the feature described in the input.
+Read AGENTS.md for context, load the Coder skill, then:
+1. Understand the requirements
+2. Make changes
+3. Build with bild
+4. Commit if successful
+```
+
+Usage:
+```bash
+task show t-123 --json | agentd run implement.md
+```
+
+### Code review
+
+```markdown
+---
+toolchain: git
+workspace: .
+max_cost_cents: 50
+---
+
+Review the changes in the current branch.
+Load the Reviewer skill and provide feedback.
+```
+
+## Run IDs
+
+Each run gets a unique ID: `<timestamp>-<spec-name>-<hash>`
+
+Example: `20250130-152300-implement-a1b2c3`
+
+## Logging
+
+Logs are written to `_/logs/agentd/<run-id>/`:
+
+| File | Contents |
+|------|----------|
+| `output.log` | Combined stdout/stderr stream |
+| `meta.json` | Run metadata (spec, timing, exit code) |