# Commands

`/seed` is the canonical entry point.

```text
/seed "<task>"
```

The public professor-facing command surface is intentionally small:

```text
/seed-status
/seed-lab-meeting
```

`/seed <task>` starts a tracked run. `/seed-status` is a read-only status board.
`/seed-lab-meeting` is the only public command that intentionally pauses the
runtime for professor feedback. SEED no longer registers report, trace,
intervene, stop, resume, or meeting subcommands as public slash commands.

Only `/seed` is registered in OpenCode's server command config. `/seed-status`
and `/seed-lab-meeting` are registered by the SEED TUI plugin, so selecting them
from the slash palette runs framework code directly instead of sending a prompt
to Lab-Representative.

The command file lives at `.opencode/command/seed.md`. The plugin also injects
the `/seed` command through the config hook so installed users do not need to
copy the markdown file manually.

The `command.execute.before` hook creates the run directory, starts a primary
`Complete professor goal` task, and injects compact command context into the
OpenCode prompt. `lab-representative` should update that primary task and create
additional tasks only for real subtasks or delegated work.

The TUI-local `/seed-status` reports the active run, run mode, task counts, compact team
runtime status, dynamic agent-thread role ids, concrete OpenCode sessions and
background ids, helper child-session counts, sub-plan counts, active sub-plans,
recent trace events, run budget, context-ledger counts, background checkpoints,
prompt/conversation refs, and activity journal paths so long-running lab work is
visible without interrupting it. It also prints a short reassurance block: current phase,
active roles, latest safe observation, blocker summary, next action, and the
latest briefing path. `/seed-status` must not create a default team runtime,
checkpoint background workers, send follow-ups, transition sub-plans, write
progress/report files, or acquire workspace leases.

`seed_team_spec_validate` is the contract gate for dynamic teams. It validates
an inline team spec with generated role ids, capability profiles, tool/MCP/skill
policy, prompt budgets, evidence obligations, and write paths. With
`accept: true`, valid specs are persisted under `team/specs/`, indexed in
`artifacts/index.json`, and recorded in the activity journal before any later
team-launch tool starts child sessions.

`seed_team_create` requires `inline_spec`. It accepts and persists the spec,
creates `team/runtime.json` with status
`creating`, resolves each member to the Lab-Representative OpenCode runner,
sends a durable handoff message, and queues member background sessions within
`team_mode.max_parallel_members`. If a launch fails, the runtime remains with
partial member records, failed launch metadata, and cleanup instructions instead
of silently discarding state.
The core does not build task-specific workflow templates. Lab-Representative
may include metadata such as `workflow_template.name` inside the inline spec for
traceability, but member roles, policies, paths, evidence obligations, and stop
conditions must be explicit in that spec.
`seed_team_member_followup` is the preferred way to continue an existing member
session by role id; it preserves the child session context and falls back to the
member mailbox when the worker is busy. Live follow-ups include the member's
current OpenCode `tools` map in the prompt body and record the same
`session_tools` metadata in `team/conversation.jsonl`. `seed_team_member_add` lets
Lab-Representative add a missing capability mid-run by validating and launching
a single new member spec against the active dynamic team.

The TUI-local `/seed-lab-meeting` manually opens a Lab Meeting for the active
run. It writes a durable background-completion request, tells already-running
background workers to finish their assigned background sessions, and blocks new
delegation, team creation, member addition, and write/append workspace leases
while the meeting is wrapping up or awaiting feedback. There is no forced
meeting timer: SEED waits for the active background sessions to become terminal
and surfaces stale workers in `/seed-status` instead of finalizing over them.
Once SEED reaches `awaiting_feedback`, the professor resumes the run by sending
a normal chat message to Lab-Representative. That message is recorded as Lab
Meeting feedback, persisted as professor memory under `.seed-agent/memory/`,
and injected only into root Lab-Representative turns.

The plugin server still registers a per-workspace supervisor, but it no longer
opens Lab Meetings on a one-hour timer. The supervisor only performs background
stale-worker marking and bounded message-delivery ticks while the run is not
awaiting feedback.

`seed_team_send` is the durable mailbox and message-envelope path for internal
lab communication. The tool records the message under `team/inbox/<member>/`,
adds the canonical envelope to `messages/envelopes.json`, appends delivery
attempts to `messages/delivery.jsonl`, appends the chronological team
conversation record to `team/conversation.jsonl`, and reports a delivery mode:

- `live_prompt_async`: the recipient had an idle agent-thread session and SEED
  woke it with a message prompt.
- `mailbox_only`: the recipient is busy, missing a child session, or otherwise
  should read the message on a later model turn.
- `failed`: SEED wrote the mailbox message, but the live wake attempt failed.

Unread mailbox messages are injected only into the intended member session by
the message-transform hook. Compact team context is injected into both the
Lab-Representative/root session and member sessions when an active team runtime
exists. `seed_team_ack` marks handled inbox messages and appends an `ack` entry
to the same conversation log. Use `seed_team_conversation` to read the ordered
conversation audit from inside OpenCode; it returns explicit `from`/`to`
entries for launch requests, queued child sessions, prompt refs, deliveries,
peer messages, acknowledgements, and task-board updates.

Use `seed_agent_thread_status` for the current durable thread roster and
`seed_agent_thread_trace` for one thread's launches, messages, deliveries, and
helper calls. Use `seed_message_queue`, `seed_message_read`, and
`seed_message_deliver` to inspect or run a bounded message delivery tick when
Lab-Representative needs to debug delivery state.
Use `seed_context_bundle_list`, `seed_context_bundle_read`, and
`seed_context_metrics` to inspect the cache-aware context ledger that backs
root/member chat turns, message delivery, launch prompts, and compaction
bridges. These are read-only debug tools.

Use `seed_team_broadcast` when the same announcement should reach several
members. Use `seed_team_meeting_create` for a shared thread with participants
and agenda, `seed_team_meeting_post` for messages, decisions, and action items,
`seed_team_meeting_status` to inspect the thread, and
`seed_team_meeting_close` to preserve the final summary. Open meeting summaries
are injected into participant turns and continuation context.

`seed_document_extract` extracts local PDF text for optional document/PDF
analysis. It preserves provenance and writes:

- `artifacts/documents/<document_id>/metadata.json`
- `artifacts/documents/<document_id>/extractor.json`
- `artifacts/documents/<document_id>/text.txt`
- `artifacts/documents/<document_id>/pages.jsonl`
- `artifacts/documents/<document_id>/chunks.jsonl`
- `artifacts/documents/<document_id>/extraction-report.md`

The extractor uses `pdftotext`. Set `SEED_PDFTOTEXT_BIN` when Poppler/Xpdf is
installed outside PATH; `PDFTOTEXT_BIN` is accepted as a compatibility alias.
When `pdftotext` is missing, Lab-Representative should inspect the Linux
environment and package candidates before proposing any install command; SEED
does not hard-code a package manager or package name. Side-effecting installs
must go through the normal SEED/OpenCode policy gate. Extracted text is
untrusted evidence, not operator instruction.

Workspace coordination tools prevent team members from silently colliding on the
same files:

- `seed_workspace_intent`
- `seed_workspace_lease_acquire`
- `seed_workspace_lease_refresh`
- `seed_workspace_lease_release`
- `seed_workspace_conflict_resolve`
- `seed_workspace_diff_record`
- `seed_workspace_worktree_merge_record`
- `seed_workspace_status`

Shared reads can coexist. Exclusive writes block overlapping read/write leases
until the verifier or professor resolves the conflict. Stale base hashes also
create conflicts. Pass `subplan_id` to `seed_workspace_lease_acquire` to bind a
granted lease to a write sub-plan before it enters `executing`, then call
`seed_workspace_diff_record` after the native OpenCode write path has produced a
verified changed-file summary. For `workspace_strategy: "worktree"` sub-plans,
the isolated worker records the worktree diff first; Lab-Representative or the
designated merge owner must then acquire a main-workspace write lease, apply the
accepted changes, record the main diff, and call
`seed_workspace_worktree_merge_record`. `seed_report_write status=completed`
refuses to complete a run while workspace conflicts are unresolved, accepted
required write sub-plans lack in-scope diff refs, or required worktree work has
not been merged back under those gates.

Headless smoke run after configuring an OpenCode provider:

```bash
opencode run --command seed --model anthropic/claude-sonnet-4-5 --variant high "Create a short SEED trace smoke test and stop after reporting the run directory."
```

The matching provider must be configured in OpenCode with
`opencode providers login -p <provider>` or a provider-specific environment
variable such as `OPENAI_API_KEY` or `ANTHROPIC_API_KEY`. SEED-agent inherits
OpenCode's chosen provider/model and does not store model API keys.
