---
name: develop-yui
description: Implement, diagnose, review, and validate changes to the Yui repository itself using its control-plane boundaries, isolated checkout workflow, and lean regression policy. Not for ordinary Tasks in other Projects managed by Yui.
---

# Develop Yui

Use this Skill whenever Yui itself is the Project being changed, independent
of the developer or orchestrator. Read the repository's
[AGENTS.md](../../../AGENTS.md) for standing authority, architecture and isolation
constraints. This Skill owns Yui-specific development methods, not generic
Leader, Worker or Reviewer scheduling. Resolve links relative to this directory.

## Match the requested work

- For diagnosis or review, inspect the bounded behavior and report evidence;
  do not change code, configuration or runtime state unless requested.
- For implementation or fixes, complete the requested change and proportionate
  verification. Ask only when a material product choice or new authority is
  needed, not for routine engineering choices.
- For simplification, preserve supported outputs, authority and recovery
  behavior; lower total lifecycle complexity rather than just line count.

## Locate the existing authority before adding a mechanism

Trace the actual entry point, current CLI/context reads, configuration sources
and owning runtime component. Establish a reachable violation of the intended
contract before fixing it. Compare equivalent inputs, native configuration and
initialization conditions when a provider or isolated fixture behaves differently.
Do not turn a fixture difference into a new product authentication or recovery
policy.

Keep durable Task intent separate from engineering execution data. Session
replacement must preserve requirements, results and managed workspaces without
making an old Run or conversation a prerequisite. Prefer existing atomic
operations and exact diagnostics; redesign a misplaced responsibility only
when that is simpler than another patch.

Before adding persistent state, a fallback, retry protocol or policy branch,
identify the current product path or hard boundary and why observable failure
plus an authorized Agent action is insufficient. Keep project-specific
judgment out of the generic CLI and Role Skills.

## Exercise this checkout in isolation

Follow the exact local-launcher procedure in AGENTS.md: `make install-local`,
then the absolute `<checkout>/output/dev/bin/yui` path. It selects this checkout
and its isolated default data home; initialize it with `setup` when needed.
Rebuild after code updates, and restart only this isolated Controller when an
older build is running. Development tools never replace the global command;
do not assume bare `yui` selects the current checkout. Additional fixtures need
their own explicit `YUI_HOME`.

## Keep Yui validation lean

Git operations support 2.29.0 and newer, including 2.30.2. Prefer common older
primitives over version branches. Resolve Git-relative paths against the actual
invocation directory; preserve whitespace and per-worktree/common-dir identity.
Do not use old line-oriented worktree porcelain as lock or deletion authority.
Use the shared read-only inventory and retain unverifiable resources. Keep
fetch's `FETCH_HEAD`, tracking-ref and maintenance isolation, and atomic
compare-and-swap batches. Never retry a failed mutating command with older flags.
The minimum version is bounded by `fetch --no-write-fetch-head`; 2.20 was
evaluated but is not supported. A version check is not a transport or repository
health check. Compatibility changes require real old binaries, not spoofed
version output; isolated local fixtures do not prove remote server behavior.

Read [verification policy](../../../docs/testing/verification-levels.md) when
selecting checks. Use a focused test-first reproduction for costly behavioral
regressions; use an existing narrow check for a small low-risk edit.
Retain deterministic regressions for high-impact, easily changed boundaries,
not wording, implementation layout or every incident. Do not remove useful
coverage merely to meet a line-count or runtime target.

Run `npm run build` and the smallest relevant check during implementation.
The permanent delivery gate is `npm test` / `npm run test:core`, plus the
package-start check for runtime packaging changes. Keep its test phase
seconds-scale and measure incremental cost when adding coverage.
Broaden checks for a new change, failure or unresolved risk, not unchanged success.

The complete gate builds and includes both `test/core` (business contracts)
and `test/platform` (actual OS/Node/native boundaries). After an explicit build,
`npm run test:business` and `npm run test:platform` do not build again. Keep
cheap branch-value checks; consolidate duplicate process setup only with a
named surviving behavioral assertion. Do not move authority/state-machine
cases into the compatibility matrix just because they use SQLite.

Package smoke defaults to `--profile full`: one representative business wiring
run plus lifecycle and installation coverage. `--profile lifecycle` retains
real process/Host/Controller handover and cleanup on each OS/architecture;
`--profile compatibility` retains fresh setup, executable helpers, CLI/bin,
Doctor/PTY and selected-driver checks on every supported Node combination.
Release runs real SQL/GC tests separately against that same installed consumer.
Choose the layer from the behavior's actual dependency, not its incident origin.
Measure build, test, native installation, each smoke phase, and runner queue
separately; a successful local profile does not prove remote matrix timing.

Real-model, paid, shared or production validation needs explicit authorization
for that resource and effect boundary; do not solicit it through an InputRequest.
Use isolated deterministic evidence otherwise. Remove temporary harnesses
after preserving their reports; do not turn exploratory matrices into a second
permanent suite.

## Close the test resources you create

For tests that start a Controller or Agent Host, own a fresh fixture Home and
register teardown before the first CLI call (`setup` can start a Controller).
Use `finally` or the test runner's teardown hook on both success and failure.
Stop fixture work and its owned processes, stop its Controller, release only
its tmux namespace, then remove its temporary directories. Controller restart
replaces the Controller but intentionally keeps managed Sessions; it is not
fixture teardown.

Before handing off Yui development, the executing Agent checks that its test
resources were released and cleans its own attributable leftovers without
asking the user to do the mechanical work. A Leader checks the cleanup evidence
for delegated tests as well. Preserve useful reports before removing scratch
data; remove temporary release worktrees through Git only when clean.

If cleanup fails or a resource's owner is unclear, retain its Home and report
the exact paths/process identities for a separate Agent to inspect. Do not
claim cleanup succeeded, delete the ownership evidence, sweep shared `/tmp`,
or stop another Home. Hard-kill recovery and historical orphan cleanup are
separate work, not a reason to add a background protocol to the normal path.

## Read specialized guidance when it applies

- Before changing persistent schema/payloads or the updater, read
  [storage migrations](references/storage-migrations.md). Use the centralized
  version chain; never repair runtime state heuristically.
- For Role Skill changes, inspect the shared Runtime contract and affected
  Role instructions together. Keep Project-specific rules here. Check local
  references in the installed package as well as the source checkout.
  Each managed Runtime/Role Skill has a positive integer `VERSION` beside
  `SKILL.md`, independent of npm, Session and storage versions. Increment the
  owning Skill's version for substantive body or required-reference changes.
  Cross-Role references retain their own versions. Do not regenerate historical
  snapshots or introduce an Agent loading receipt.
- For release or package changes, read the relevant section of
  [release workflow](../../../docs/release-workflow.md); verification does not
  authorize publishing. Apply AGENTS.md's release boundary: no version release
  by default; an explicit release request uses minor for features or incompatible
  interface/behavior changes, and patch for compatible fixes. Incompatibility
  alone does not require major or another version-level approval. This Yui-specific
  convention is not a SemVer compatibility promise: document impacts and migration
  in release notes. Do not relax protocol/storage migration requirements or modify
  generic Role Skills to encode this Project policy.

## Hand off evidence

For authorized PR delivery, keep related code, tests, Skill/documentation changes
and CI repairs on the same open PR. Prepare them together before pushing instead
of creating avoidable CI rounds. A new commit still needs its relevant checks;
an unchanged successful result is not a reason to rerun. Once merged, a code
correction needs a follow-up PR rather than rewriting the accepted candidate.

When optimizing CI, record the exact candidate/run/attempt and separate queue,
installation, build, tests and smoke timings. Observe the existing change before
stacking another optimization; compare coverage and cache conditions as well as
elapsed time. Follow demonstrated bottlenecks, not a target test count.

Only when version release is explicitly authorized, prepare its version and
release notes in the same open PR when practical, then follow the exact merged
commit through CI and the existing publication checks. PR success does not prove
a different merge SHA, and merge authority does not authorize npm publication.
Report local validation, open PR, merge and verified package publication as
separate outcomes; recover uncertain effects from existing evidence, not replay.

Inspect the complete final change and affected contracts. Report the observable
result, validation actually performed, material gaps and remaining decisions.
Distinguish self-review, deterministic tests and real-Agent evidence; passing
format or package checks alone does not establish Agent behavior.