Hare/yoi
1
1
Fork 0
Code Actions Packages Releases Activity

docs: split public and dogfood workflows

Browse Source
This commit is contained in:
Keisuke Hirata 2026-06-11 11:27:00 +09:00
parent 50d826b11a
commit 21a25e127f
No known key found for this signature in database
2 changed files with 137 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

133
docs/design/workflows-public-dogfood-split.md Normal file
View File

@ -0,0 +1,133 @@
# 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.

4
docs/development/workflows.md
View File

@ -36,3 +36,7 @@ Notifications are hints to inspect state. They are not proof of completion.
Unless explicitly authorized otherwise, final merge, cleanup, design-boundary decisions, and ticket closure remain the orchestrator/human responsibility.
Child Pods may commit in delegated worktrees when the workflow allows it, but the merge-ready dossier should make the final decision auditable from repository records.
## Public and dogfood workflow split
Public builtin workflow candidates and this repository's dogfood-specific workflow mechanics are tracked in `docs/design/workflows-public-dogfood-split.md`.