discovery

name	discovery
description	Run discovery.

$discovery - Dense Discovery Phase Adapter

YOU MUST EXECUTE THIS WORKFLOW. Do not just describe it.

Discovery turns a goal plus delegated child artifacts into one dense execution packet for $crank and $validate.

Strict Delegation Contract

Discovery runs brainstorm and design as internal modes (absorbed, ag-s43tg) and delegates to $research, $plan, and $pre-mortem as separate skill invocations. Strict delegation is the default.

Reject these compression moves:

• inlining $research work;
• collapsing $plan into an inline decomposition;
• skipping $pre-mortem;
• replacing child skills with direct Codex sub-agent work.

See ../shared/references/strict-delegation-contract.md.

Codex Lifecycle Guard

When this skill runs in Codex hookless mode (CODEX_THREAD_ID is set or CODEX_INTERNAL_ORIGINATOR_OVERRIDE is Codex Desktop), ensure startup context before entering the discovery DAG:

ao codex ensure-start 2>/dev/null || true

Leave ao codex ensure-stop to closeout skills; discovery owns startup only.

Narrow Waist

Discovery does not carry raw child-skill output forward. It records artifact paths, verdicts, the hexagon: boundary block from docs/architecture/intent-to-loop-hexagon.md, and the six Context Density Rule fields:

Field	Meaning
intent	Behavior or capability to produce
boundary	Bounded context, non-goals, write scope
evidence	Acceptance examples, tests, gates, verdicts
decision	Why this plan shape was chosen
constraint	Safety, runtime, token, and process limits
next_action	Exact $crank or follow-up command

Everything else stays in child artifacts and is linked by path.

Discovery To Plan Port

Use the Skill Ports and Adapters vocabulary and the Intent-to-Loop Hexagon for the boundary between Discovery and Plan:

Boundary piece	Discovery contract
Inbound port	shape_intent from operator goal or BDD intent
Outbound port	plan_slices into $plan
Driving adapter	$discovery skill invocation
Driven adapter	$plan skill invocation plus br/file persistence
Context packet	density block, artifact links, acceptance examples, non-goals, constraints
Guard adapter	$pre-mortem verdict before packet handoff

Feature: Discovery hands dense intent to planning
  Scenario: Discovery delegates to Plan
    Given Discovery has a goal, research path, and design or brainstorm evidence
    When it crosses the `plan_slices` port
    Then it sends density fields and artifact links
    And it does not inline the Plan decomposition in Discovery prose

Codex Fanout Approval Gate

For open-ended or high-risk Codex discovery, insert this gate before $plan creates beads. The contract is docs/contracts/codex-fanout-approval-packet.md.

Required sequence:

1. Write at least three independent PerspectivePlan artifacts with different lenses: product/user value, architecture/gate integrity, and operations/migration risk.
2. Winnow those plans into one SynthesisPacket with selected plan, rejected alternatives, rationale, open questions, and risks.
3. Invoke $codex-approval so an idle Fable/Claude-family ATM/NTM pane reviews the SynthesisPacket and every PerspectivePlan path directly.
4. Persist an ApprovalEdge with the validator pane, tmux capture, normalized Fable verdict artifact, verdict, required changes, and accepted risks.

PASS permits bead creation. WARN is not a silent pass: update the packet and rerun approval, or record an explicit accepted-risk note in the ApprovalEdge. FAIL blocks bead creation and returns Discovery to fanout/synthesis, up to three approval attempts.

Open-Ended Path (generate-winnow → operationalize → refine)

Additive to the default flow — it does not replace the strict-delegation contract or the artifact-first DAG. This path activates for open-ended "improve the project"-style goals ("improve the project", "what should we build next", "make X more robust") OR when --ideate is passed. For a specific goal, the default flow (brainstorm-clarify → research → plan → pre-mortem) is unchanged.

On the open-ended path, Discovery prepends the generate-winnow methodology before research/plan and adds two steps after planning:

1. Ideate (delegate to brainstorm --ideate). Invoke brainstorm in ideation mode as a separate skill invocation — strict delegation still applies; do NOT inline the 30-idea generation. It returns a ranked portfolio of 15 ideas (top 5 + next 10) with how/perceive/implement notes, rubric scores, and red-team findings.
2. Research + fanout approval + Plan + Pre-mortem. Run research over the selected portfolio. For Codex-led open-ended/high-risk work, produce PerspectivePlan artifacts, a SynthesisPacket, and a Fable ApprovalEdge before $plan creates tracker rows. Then run the normal artifact-first DAG over the approved packet rather than a single goal.
3. Operationalize. Turn the ranked portfolio into a comprehensive, granular set of self-documenting br beads — tasks, subtasks, dependency structure (br dep add), and explicit test tasks (unit + e2e with detailed logging). Each bead carries what/why/how/risks/success so the original plan markdown never needs to be consulted again. Overlap-check against existing beads (br list --json) before creating — merge, don't duplicate.
4. Refine in plan space (4-5 passes). Before handing the packet to $crank, run 4-5 refinement passes over the bead set. Each pass: re-read AGENTS.md (especially after compaction), check every bead for sense and optimality, and DO NOT OVERSIMPLIFY / DO NOT LOSE FEATURES OR FUNCTIONALITY. Validate between passes (no dependency cycles; every leaf actionable via br ready).

Tracking is br with bv triage — this is AgentOps.

Execution

Run the artifact-first DAG in references/dag.md. That file owns the executable workflow, state shape, gate detail, per-step detail, and the acceptance-criteria YAML contract.

Flags

Flag	Default	Description
--auto	on	Fully autonomous; inverse of --interactive. Passed through to $research and $plan.
--interactive	off	Human gates in research and plan. Does not affect pre-mortem.
--skip-brainstorm	auto	Skip brainstorm when the goal is already specific.
--ideate	auto	Force the open-ended generate-winnow path: delegate to brainstorm --ideate (30→5→15), then operationalize into self-documenting br beads and refine 4-5x in plan space. Auto-on for open-ended goals.
--complexity=<level>	auto	Force fast, standard, or full.
--no-budget	off	Disable phase time budgets.
--no-scaffold	off	Skip scaffold auto-invocation.
--no-lifecycle	off	Deprecated alias for --no-scaffold.

Output Specification

Format: compact markdown phase summary to stdout plus JSON execution packet on disk.

Files written:

• .agents/research/<topic-slug>.md - research artifact path only
• .agents/plans/YYYY-MM-DD-<goal-slug>.md - plan document path only
• .agents/council/YYYY-MM-DD-pre-mortem-<topic>.md - pre-mortem verdict path only
• .agents/rpi/execution-packet.json - latest dense packet
• .agents/rpi/runs/<run-id>/execution-packet.json - per-run archive when run_id is set
• .agents/rpi/phase-1-summary-YYYY-MM-DD-<goal-slug>.md - compact discovery summary

Completion Markers

<promise>DONE</promise>      # Discovery complete, packet ready
<promise>BLOCKED</promise>   # Design or pre-mortem gate blocked

References

• references/dag.md
• references/output-templates.md
• references/phase-data-contracts.md
• references/isolation-contract.md
• references/complexity-auto-detect.md
• references/idempotency-and-resume.md
• references/phase-budgets.md
• references/troubleshooting.md