# Public builtin workflows and Yoi dogfood workflows

Yoi should split workflows into public builtin procedures and project-local dogfood procedures. The builtin set should teach the general Ticket/role lifecycle; this repository's Git worktree, branch, cargo, nix, merge, cleanup, and report conventions should stay project-local unless they are explicitly selected as an optional extension.

This document records the design/audit decision for Ticket `00001KTRKZ14C`. It does not implement the builtin workflow loader.

## Decision

- Add a typed builtin workflow source, conceptually `WorkflowSource::Builtin`, with clear provenance in any list/show/launch surface.
- Store public builtin workflow resources under `resources/workflows/<slug>.md`, not under `resources/prompts`.
  - Workflows are user-visible procedural artifacts selected by slug and source. They need source/provenance/listing semantics distinct from prompt fragments.
  - They are still embedded runtime resources, but prompt-fragment override rules should not silently become workflow authority.
- Source priority for workflow lookup should be:
  1. explicit path/file selector, if the CLI/config surface allows one;
  2. workspace `.yoi/workflow/<slug>.md`;
  3. user workflow directory, if/when one is added;
  4. builtin `resources/workflows/<slug>.md`;
  5. external skill/plugin workflow sources, only when explicitly enabled and named.
- Workspace workflows override builtin workflows by slug. Overrides must show provenance so a role launch can say whether it used workspace, user, builtin, or plugin workflow text.
- Keep role Profile policy separate from workflow prose. Profiles select role behavior/tool policy; workflows provide procedural flow; launch prompts provide concrete Ticket/action context.
- Public resident core should remain small: intake requirements sync and orchestrator routing. Multi-agent implementation/review is builtin-available but not necessarily resident in every profile. Git worktree mechanics are optional/project-local by default.

## Audit of current workspace workflows

| Current slug | Public builtin candidate | Dogfood/project-local material | Decision |
| --- | --- | --- | --- |
| `ticket-intake-workflow` | Yes. The core requirement-sync flow, existing-Ticket refinement, readiness, duplicate avoidance, and Ticket materialization are product-generic. | Mentions current local storage and Yoi-specific Ticket command examples. | Move cleaned generic version to builtin core. Keep storage-command specifics either bounded and product-generic or in project-local notes. |
| `ticket-orchestrator-routing` | Yes. The routing classifications, queued acceptance contract, relation/orchestration-plan checks, and planning-return rules are product-generic. | Contains Yoi dogfood examples, worktree/multi-agent handoff specifics, and merge-completion guidance tied to this repo's operating policy. | Move generic routing gate to builtin core. Split dogfood merge/worktree details into workspace override or separate dogfood workflow. |
| `ticket-preflight-workflow` | Compatibility candidate only. It now describes planning/requirements sync and legacy canonical id compatibility rather than a standalone lane. | Mostly project-history wording and deprecated-preflight vocabulary. | Do not make resident core. Keep as builtin compatibility alias only if existing configs still reference it; otherwise replace references with intake/planning sync. |
| `multi-agent-workflow` | Partly. The sibling coder/reviewer loop, intent packet, branch-local review, and merge-ready dossier are useful product concepts. | Heavy Yoi dogfood specifics: Git worktrees, commits, cargo/nix validation, branch cleanup, docs/report conventions, and parent/child policy. | Split into builtin `multi-agent-workflow` for role loop + dossier, and workspace dogfood extension for Git worktree/cargo/nix mechanics. |
| `worktree-workflow` | Not resident public core. | Almost entirely this repository's Git worktree mechanics and `.yoi` path exclusions. | Keep workspace-local dogfood workflow. Optionally create a non-resident builtin `git-worktree-isolation` later, disabled unless explicitly selected. |

## Slug and `.yoi/ticket.config.toml` migration decision

Use explicit dogfood slugs for workflows whose semantics differ from the public builtin workflow. Same-slug workspace overrides are allowed for local wording/policy tweaks of the same public contract, but they should not be used to hide Yoi repository Git/worktree/cargo/nix/merge semantics behind a public slug. This avoids accidental shadowing when a user expects `multi-agent-workflow` to mean the generic builtin role loop.

Planned selector mapping for this repository after builtin workflow loading exists:

| Role/config surface | Workflow selector | Source intent | Rationale |
| --- | --- | --- | --- |
| `[roles.intake].workflow` | `ticket-intake-workflow` | builtin core by default; workspace same-slug override only if this repo needs a true local refinement of the same intake contract | Intake is mostly product-generic; dogfood Git/worktree policy does not belong here. |
| `[roles.orchestrator].workflow` | `ticket-orchestrator-routing` | builtin core by default; dogfood merge/worktree instructions come from explicit launch context or a separate dogfood workflow, not a hidden same-slug override | Routing semantics should stay public/generic; repo-specific implementation mechanics should be opt-in and visible. |
| `[roles.coder].workflow` | `yoi-dogfood-multi-agent-workflow` | workspace-local dogfood workflow | Coder work in this repository is tied to the repo worktree/branch/validation contract and must not shadow generic builtin `multi-agent-workflow`. |
| `[roles.reviewer].workflow` | `yoi-dogfood-multi-agent-workflow` | workspace-local dogfood workflow | Reviewer evidence in this repository includes branch/worktree/cargo/nix/Ticket-doctor conventions; use an explicit dogfood slug. |
| compatibility references | `ticket-preflight-workflow` | builtin compatibility alias or workspace compatibility file, non-resident | Do not keep it as a role default. It should point to planning/requirements sync language only. |
| dogfood worktree helper | `yoi-dogfood-worktree-workflow` | workspace-local helper, not a role default by itself | Referenced from `yoi-dogfood-multi-agent-workflow`; keeps Git worktree mechanics out of generic builtin workflows. |

`multi-agent-workflow` should be reserved for the generic builtin sibling coder/reviewer loop. This repository should not keep a same-slug workspace override with dogfood semantics once the builtin exists. If a temporary same-slug override is needed during migration, it must be short-lived and the Ticket/config comment must say it shadows the builtin intentionally.

## Builtin workflow set

### Resident builtin core

These should be advertised by default when Ticket support is enabled:

- `ticket-intake-workflow`
  - generic Ticket requirements sync/materialization;
  - existing Ticket refinement with explicit user agreement;
  - readiness and duplicate handling;
  - no Yoi repository cargo/nix/worktree policy.
- `ticket-orchestrator-routing`
  - explicit routing gate;
  - queued acceptance before implementation side effects;
  - relation/orchestration-plan/context checks;
  - implementation-ready IntentPacket shape;
  - no repository-specific merge authority or Git cleanup policy.

### Builtin available but optional

These can be embedded and selectable, but should not be injected as resident core unless the active Profile/config opts in:

- `multi-agent-workflow`
  - generic sibling coder/reviewer loop;
  - intent packet, reviewer evidence, blocker/fix-loop, merge-ready dossier;
  - no mandatory Git worktree, cargo, nix, or `.yoi` cleanup rules.
- `ticket-preflight-workflow`
  - transitional alias for old configurations that still name preflight;
  - should route to planning/requirements sync language and avoid reintroducing preflight as a lifecycle state.

### Workspace-local dogfood workflows

These remain in this repository under `.yoi/workflow/` as overrides or dogfood-only slugs:

- `worktree-workflow`
  - mechanical Yoi project worktree setup;
  - tracked `.yoi` project records visible;
  - `.yoi/memory`, local/runtime/log/lock/secret-like paths excluded;
  - branch/worktree cleanup policy.
- A dogfood extension for multi-agent/merge-completion, if the generic builtin `multi-agent-workflow` is cleaned:
  - concrete `cargo fmt`, `cargo test`, `target/debug/yoi ticket doctor`, `nix build .#yoi` validation policy;
  - merge authority boundaries for this repository;
  - docs/report conventions.

## Stale vocabulary cleanup

Builtin workflows and active workspace workflows should remove or replace the following old wording:

- `Action required` / `Attention required` as storage or state concepts. Use explicit Ticket state, typed relation metadata, orchestration-plan waiting notes, or Ticket thread comments instead.
- `preflight` as a lifecycle lane/state. Use planning/requirements sync or compatibility alias language.
- `open` / `pending` / `closed bucket` authority. Current authority is `state` plus optional `resolution.md` for closed Tickets.
- Long-lived umbrella/progress-container Ticket terminology. Use concrete implementation Tickets and optional Objective context.

## Follow-up implementation boundaries

1. **Builtin workflow resource loader**
   - Add embedded `resources/workflows/*.md` resources.
   - Add `WorkflowSource::Builtin` / equivalent typed provenance.
   - Update workflow discovery/list/show/launch so workspace overrides builtin by slug and provenance is visible.
   - Include tests for source priority and override behavior.

2. **Public workflow text cleanup**
   - Create cleaned builtin versions of `ticket-intake-workflow` and `ticket-orchestrator-routing`.
   - Split generic `multi-agent-workflow` from Yoi dogfood Git/worktree/cargo/nix mechanics.
   - Keep `ticket-preflight-workflow` as compatibility-only or remove references if no longer needed.

3. **Dogfood workflow retention**
   - Keep or rename workspace-local dogfood workflows for this repository's implementation mechanics.
   - Ensure `.yoi/ticket.config.toml` role workflow selectors intentionally point to builtin generic workflows or workspace dogfood overrides, with no accidental slug shadowing.

4. **Vocabulary migration**
   - Sweep active workflow text, prompts, docs, and Ticket UI wording for `Action required`, `Attention required`, and old preflight lane language.
   - Replace with typed state/relation/orchestration-plan terminology.

5. **Panel/role launch provenance display**
   - When a role launches with a workflow, include the workflow source/provenance in diagnostic/launch context so builtin vs workspace override is debuggable.

## Non-goals for this Ticket

- Implementing the builtin workflow loader.
- Moving current workflow files into runtime resources in this branch.
- Changing Ticket lifecycle states.
- Changing role Profile policy.
- Changing scheduler/queue behavior.