Seed

/ouroboros:seed

Generate validated Seed specifications from interview results.

Required Skill Capabilities

• ask_user — ask human-judgment questions through the active runtime's user-question surface.
• inspect_code — read repo-local agent roles and recover exact context from local files before guessing.
• call_mcp — use available Ouroboros MCP tools directly, including runtime tool discovery when a deferred MCP surface must be loaded.
• run_shell — run bounded local commands for audit-trail writes and setup steps.
• refine_answer — confirm free-form user decisions before treating them as accepted seed revisions.
• maintain_ledger — keep QA scores, candidate decisions, rejected proposals, and audit trail keys visible.

Usage

ooo seed [session_id]
/ouroboros:seed [session_id]

Trigger keywords: "crystallize", "generate seed"

Instructions

When the user invokes this skill:

Python Runtime (Required)

Before running any shell snippet below, define this resolver in the same shell. It accepts only Python 3.12 or newer, prefers python3 and then python, and uses uv as the final fallback. Call ouroboros_python directly and quote every argument passed to it; the function preserves arguments and heredoc/stdin input. Only the probe and child interpreter discard inherited CPython path-selection overrides; the caller shell keeps its environment unchanged.

<!-- ouroboros-python-resolver:start -->

ouroboros_python() {
  if command -v python3 >/dev/null 2>&1 &&
    (unset PYTHONHOME PYTHONPATH PYTHONPLATLIBDIR PYTHONEXECUTABLE __PYVENV_LAUNCHER__; command python3 -c 'import sys; raise SystemExit(sys.version_info < (3, 12))') >/dev/null 2>&1
  then
    (unset PYTHONHOME PYTHONPATH PYTHONPLATLIBDIR PYTHONEXECUTABLE __PYVENV_LAUNCHER__; command python3 "$@")
    return
  fi
  if command -v python >/dev/null 2>&1 &&
    (unset PYTHONHOME PYTHONPATH PYTHONPLATLIBDIR PYTHONEXECUTABLE __PYVENV_LAUNCHER__; command python -c 'import sys; raise SystemExit(sys.version_info < (3, 12))') >/dev/null 2>&1
  then
    (unset PYTHONHOME PYTHONPATH PYTHONPLATLIBDIR PYTHONEXECUTABLE __PYVENV_LAUNCHER__; command python "$@")
    return
  fi
  if command -v uv >/dev/null 2>&1; then
    (unset PYTHONHOME PYTHONPATH PYTHONPLATLIBDIR PYTHONEXECUTABLE __PYVENV_LAUNCHER__; command uv run --no-project --quiet --python '>=3.12' python "$@")
    return
  fi
  printf '%s\n' 'Ouroboros skills require Python >= 3.12 or uv on PATH.' >&2
  return 127
}

<!-- ouroboros-python-resolver:end -->

Load MCP Tools (Required before Path A/B decision)

The Ouroboros MCP tools are often registered as deferred tools that must be explicitly loaded before use. You MUST perform this step before deciding between Path A and Path B.

1. Use the active runtime's call_mcp capability to find and load the seed generation MCP tool through runtime tool discovery when needed:

   tool discovery query: "+ouroboros seed"

2. The tool will typically be named mcp__plugin_ouroboros_ouroboros__ouroboros_generate_seed (with a plugin prefix). After runtime tool discovery returns, the tool becomes callable through the active runtime's call_mcp capability.
3. If the tool is callable — already exposed, or loaded by discovery — proceed to Path A. An empty discovery result for an already-exposed tool is expected, not a failure. Proceed to Path B only if the tool is genuinely absent (no Ouroboros MCP server).

IMPORTANT: Do NOT skip this step. Do NOT assume MCP tools are unavailable just because they don't appear in your immediate tool list. They are almost always available as deferred tools that need to be loaded first.

CRITICAL — deferred-schema guard (prevents "Invalid tool parameters"): This skill makes ouroboros_* MCP calls across multiple turns, and each turn runs in a fresh tool context. A deferred tool's schema loaded on one turn is NOT guaranteed to still be loaded on the next. If you call any ouroboros_* MCP tool while its schema is not loaded in the current turn, the runtime rejects the call with "Invalid tool parameters" before it ever reaches the server. Therefore: immediately before EVERY ouroboros_* MCP call in this skill, re-run the tool-discovery load query for the specific MCP tool you are about to call (idempotent — a no-op when the schema is already loaded) so the correct schema is guaranteed present for that call. Use "+ouroboros seed" before ouroboros_generate_seed, "+ouroboros qa" before ouroboros_qa, and "+ouroboros lateral" before ouroboros_lateral_think. If a load ever returns no matching tool (and the tool is not already callable — an empty load for an already-exposed tool is an expected no-op, not absence), switch to the documented fallback / Path B instead of retrying the failing call.

Path A: MCP Mode (Preferred)

If the ouroboros_generate_seed MCP tool is available (loaded via runtime tool discovery above):

1. Determine the interview session:

   • If session_id provided: Use it directly
   • If no session_id: Check conversation for a recent ouroboros_interview session ID
   • If none found but THIS conversation already settled the goal, the constraints, and verifiable success criteria (a lateral decision, a brownfield scan, or plain discussion that converged): take the interview-less path below. Do not send the user to ooo interview just to repeat what they already told you.
   • If none found and the material is not settled: Ask the user

   Interview-less path (session_context):

   Tool: ouroboros_generate_seed
   Arguments:
     session_context:
       goal: <the user's own settled wording — verbatim, never your paraphrase>
       acceptance_criteria: [<verifiable checks: a command, a visible behaviour, a measurable state>]
       constraints: [<optional>]
       decisions: [<optional; each becomes a constraint>]
       project_type: greenfield | brownfield

   Every value enters the Seed byte-for-byte, so shell chains in an AC (ruff check && pytest) are expected and allowed.

   • If the response has status: "gap_questions_required", it lists the exact 1-5 questions the Seed still needs. Ask the user those questions only, merge the answers into session_context, and call again. That is the whole interview: it shrinks to the gaps the session left open.
   • If the response contains Seed YAML, continue at step 3 with that YAML.

2. Call the MCP tool through the active runtime's call_mcp capability:

   Tool: ouroboros_generate_seed
   Arguments:
     session_id: <interview session ID>

3. The tool extracts requirements from persisted interview state, calculates ambiguity score, and generates the Seed YAML.

   Seed generation response shapes: Branch only after an actual Seed YAML artifact is available.

   • If the response has status: "delegated_to_subagent" and dispatch_mode: "plugin", keep the returned session_id, wait for the plugin-managed subagent result, then extract the Seed YAML from that result. Do not run the advisory QA check using the delegation envelope as the artifact.
   • If the response directly contains Seed YAML, extract that YAML directly.
   • If neither shape yields Seed YAML, stop and ask the user to resume generation or provide the missing artifact; do not fabricate a seed just to satisfy the advisory QA check.

4. Run the single-pass Advisory QA Check below, then present the seed as final and proceed to "After Seed Generation". Do not enter any refinement iteration unless the user explicitly opts in.

Advantages of MCP mode: Automated ambiguity scoring (must be <= 0.2), structured extraction from persisted interview state, reproducible.

Path B: Plugin Fallback (No MCP Server)

If the MCP tool is NOT available, fall back to agent-based generation:

1. Read src/ouroboros/agents/seed-architect.md and adopt that role.
2. Recover the interview requirements before drafting; do not invent missing context:
   • If session_id was provided, first identify context for that same session: use current-thread interview Q&A only when it clearly belongs to that session_id, and use current-thread corrections only when they explicitly amend that same interview or seed request.
   • If same-session conversation context is incomplete, use the active runtime's inspect_code / run_shell capabilities to look for persisted interview artifacts under the Ouroboros data directory (for example ~/.ouroboros/data/), exported session artifacts, or other exact local records for that ID.
   • If both same-session conversation context and a persisted artifact are available, merge them conservatively: keep the persisted transcript as evidence, but let explicit same-thread user corrections or clarifications supersede older persisted wording.
   • If no session_id was provided, use current-thread interview Q&A only when it is complete enough to identify one coherent interview; otherwise ask which interview or requirements summary should be seeded.
   • If no matching artifact is found, or if local artifacts plus matching conversation history still do not provide enough requirements, ask the user for the missing interview transcript / concise requirement summary, or ask them to run or resume ooo interview. Do not generate a seed from an absent or mismatched transcript.
3. Generate a Seed YAML specification from the recovered requirements.
4. Run the single-pass Advisory QA Check below, then present the seed as final and proceed to "After Seed Generation". Do not enter any refinement iteration unless the user explicitly opts in.

Advisory QA Check (single pass, non-blocking)

After Path A or Path B produces a seed, run QA exactly once and surface the verdict as advisory information. The verdict never blocks. The seed is presented as final regardless of score; the user decides whether any refinement is worth their time. Do not run QA-until-PASS iterations — that loop is retired because it front-loads heavy interaction the user did not ask for.

The generation (Path A ouroboros_generate_seed or Path B agent role) runs exactly once and establishes the seed's ontology. Any later revision is a direct YAML edit by you (main session) — do not call ouroboros_generate_seed again. It does not accept revision hints, and re-running it would discard the established ontology.

Advisory bar: pass_threshold: 0.90 (stricter than default 0.80 — seeds are structural specs). The bar labels the verdict; it does not gate anything.

Check:

1. Establish the QA evaluator for this run:

   • MCP QA mode: Load the QA tool via the active runtime's call_mcp capability using runtime tool discovery query "+ouroboros qa" if not already loaded.
   • Fallback QA mode: If MCP is unavailable, read src/ouroboros/agents/qa-judge.md, adopt that evaluator role, and return its exact JSON schema: lowercase verdict (pass/revise/fail), numeric score, dimensions, differences, suggestions, and reasoning. In this mode there is no MCP-owned qa_session_id; track iteration history in the audit block and local loop ledger instead.

2. Obtain a QA verdict using the available mode:

   MCP QA mode — call QA on the generated seed through the active runtime's call_mcp capability:

   Tool: ouroboros_qa
   Arguments:
     artifact: <the seed YAML>
     quality_bar: "Seed must be internally consistent, acceptance_criteria must be measurable and testable, constraints must be concrete (no vague terms), ontology_schema must cover all entities referenced in goal/criteria, and there must be no contradictions between fields. acceptance_criteria must also be parsimonious in the ontological sense: a criterion names a state of the finished work a user can see is true, while an implementation step names a means of reaching it, and only the first belongs in the list. Read each criterion beside its siblings — one intelligible only as a move toward a sibling is that sibling's means and belongs merged into the outcome it serves, and flagging that is as important as flagging a missing piece, since it commits the seed to an unverified path. How many criteria a goal has follows from that judgment, so weigh each criterion against its siblings."
     artifact_type: "document"
     pass_threshold: 0.90
     seed_content: <the seed YAML>
     qa_session_id: <reuse across passes>
     iteration_history: <accumulated across passes>

   Fallback QA mode — skip the tool call and evaluate the current seed text under the QA Judge role from step 1, using the same quality bar and threshold. Treat the locally produced verdict exactly like the MCP verdict for the advisory presentation below.

   QA response shapes: Branch only after a usable verdict is available.

   • In MCP QA mode, if the response has status: "delegated_to_subagent" and no verdict payload, keep the returned qa_session_id, wait for the plugin-managed subagent result, then parse that result as the QA verdict. Do not treat the delegation envelope itself as PASS/REVISE/FAIL.
   • In MCP QA mode, if the response already includes a scored verdict, parse that inline verdict directly.
   • In fallback QA mode, parse the exact QA Judge JSON. Normalize verdict to uppercase only for the labels below (pass→PASS, revise→REVISE, fail→FAIL). Treat differences and suggestions as advisory findings; do not add non-schema fields such as loop_action.
   • If the user later opts into a refinement pass, append the parsed verdict plus applied/rejected revision decisions to iteration_history before that next QA pass.

3. Present the advisory verdict and the final seed — always in this order, never gated on score:

   1. One advisory line: QA advisory: <PASS|REVISE|FAIL> — score X.XX (bar 0.90).
   2. If the verdict is below the bar, list the top 2–3 QA suggestions as short advisory bullets — findings, not tasks. Do not apply any of them automatically.
   3. Present the complete final Seed YAML in a fenced yaml block.
   4. If the verdict was REVISE or FAIL, offer exactly one opt-in line — e.g. Want a refinement pass on these findings? Otherwise the seed stands as-is. For FAIL (< 0.40) additionally mention that ooo interview (revisit requirements) or ooo unstuck (challenge assumptions) may serve better than YAML edits. Then proceed to "After Seed Generation" regardless of the answer being pending — the seed is final unless the user opts in.

4. Only if the user explicitly opts in, run one Wonder → Reflect → Refine → Restate pass (below), re-run the QA check once on the revised seed for an updated advisory line, and present the revised YAML. Each additional pass requires a fresh explicit opt-in; never chain passes autonomously.