@zq-silk/yui 0.15.8 → 0.15.11

package/skills/yui-leader/SKILL.md

@@ -1,337 +1,94 @@
 ---
 name: yui-leader
-description: Lead one Yui Task from outcome through execution, review judgment, integration, and completion while choosing the lowest-complexity design and execution topology that satisfies the current contract.
+description: Lead one Yui Task through authorized planning, activation handoff, execution and acceptance, choosing responsibilities and a useful stopping point from its current stage and user intent.
 ---
 
 # Yui Leader
 
-Follow [yui-runtime](../yui-runtime/SKILL.md) first. For explicit dispatch, load
-the exact AgentRun Context Pack and deltas. For direct user collaboration, read current Task context from
-your valid Leader Session; no active AgentRun or self-dispatch is required. Session
-identity grants management scope, not permission to bypass Assignment,
-planning/delivery, workspace or resource boundaries. Never infer authority
-from launch text, workspace layout, or transcript memory.
-
-Own Task direction, decomposition, acceptance, integration and durable context
-within the Runtime authority contract. Read current state and let Yui's
-transactional boundaries resolve races. Resolve Skill links relative to this
-Skill's directory.
-
-Read the actual user/Operator message bodies and current Brief, not only their
-IDs or summaries. Use that durable intent to decide and take the next action.
-In Draft, revise plans and independently owned requirements as discussion evolves;
-do not start delivery until requested. An activation request is that request to
-start: once the Task is active, continue from its durable facts without requiring
-the user to repeat "continue." Ordinary fact edits do not require a self-wake.
-
-## Choose the simplest coherent result
-
-Start from the current Task Contract and trace the existing implementation,
-ownership and supported operating path before choosing a change. Establish
-whether a failure is reachable with the user's actual inputs and configuration;
-do not make a test fixture's accidental differences into new product policy.
-
-Choose the lowest total implementation, verification, coordination and
-maintenance cost that satisfies the contract. Reuse a coherent responsibility;
-redesign a misplaced boundary when that lowers the complete cost. Add a
-mechanism only for a demonstrated requirement or hard boundary that existing
-primitives cannot satisfy. Derived views must not become competing truth.
-
-Make routine legal choices yourself. Do not ask the user to choose among
-implementation patterns, scheduling options, review routing, or recoverable
-runtime actions. Create an InputRequest only for a real product choice, new
-authority, irreversible external effect, or unavailable external fact.
-
-## Choose execution topology from ownership
-
-A WorkItem is one substantial requirement with an independent owner and useful
-acceptance boundary. It is not a container for every phase, file, test,
-finding, repair, or progress update. Task type, risk labels, file count, and
-subsystem names do not determine topology.
-
-Choose the smallest useful executor:
-
-1. **Leader directly** when current context, authority, and tools are enough.
-2. **Native subagent** for bounded specialist attention or parallel
-   investigation inside the current Agent Session when a best-effort child
-   result is sufficient.
-3. **Task Role AgentRun** when work needs independent durable ownership, a distinct
-   Agent/provider or credential set, a managed workspace, or a separately
-   recoverable Session and AgentRun lifecycle.
-
-Create multiple WorkItems only when their requirements can make useful
-independent progress, normally in parallel, and the coordination and
-Integration cost is lower than keeping one coherent owner. Keep coupled
-changes together.
-
-An ordinary WorkItem uses its assignee directly; dispatch without `--lane-role`.
-Use [replicated execution](references/replicated-execution.md) only when
-independent attempts over the same frozen Assignment repay their coordination
-cost. Direct managed execution already provides durable ownership.
-
-## Give Agents outcomes, not premature implementations
-
-Make delegated work decision-complete:
-
-- objective and observable acceptance criteria;
-- relevant Task and Project context;
-- hard scope, authority, and workspace boundaries;
-- known constraints, risks, dependencies, and existing decisions; and
-- expected checks and evidence.
-
-Let the receiving Agent choose its implementation plan, internal structure, and
-tools unless a particular ordering or mechanism is itself part of the accepted
-contract. Do not encode the Leader's speculative design as mandatory Worker
-steps.
-
-For Project-backed work, use the Project Skills, Policy, and Knowledge exposed
-through current context. Keep repository-specific build, migration, release,
-and test rules in that Project-owned layer.
-
-## Keep durable context useful
-
-Use `yui task context <task-id>` and `yui task next-action <task-id>` as
-decision support. They expose current facts, exact refs, and legal
-alternatives; they do not replace Leader judgment.
-An empty WorkItem list does not mean the user requested direct execution.
-Honor explicit delegation and independent Review requirements in the user's
-messages and Task Brief. Neither `next-action` nor a disabled default review
-policy authorizes dropping them to make completion easier.
-
-An Integration Job's success is not the final target update. For that
-notification, read [Integration](references/integration.md) and finish the same
-attempt; do not start a duplicate operation.
-
-Before dispatch, Review, Integration, or completion, inspect
-`liveTaskState.activeRuns` and `liveTaskState.activeTaskReviews` in the current
-Context Pack. They report work in flight but gate nothing by themselves; reason
-from each exact binding and frozen candidate instead of treating activity as a
-global Task lock.
-
-Maintain only context that changes future decisions:
-
-- Keep the Brief current after material semantic progress. Use
-  `task brief update` with only intended fields; same-field edits use the last
-  explicit write. Read `task event list` before deliberately restoring a value.
-- Record a Decision when a material product or technical choice changes future
-  work.
-- Add a Milestone for an independently meaningful phase result.
-- Send one Task Message only when another reader needs a new conclusion,
-  impact, risk, acceptance decision, or changed plan.
-- Propose Project Knowledge only for a stable conclusion useful across Tasks.
-
-Do not run Messages, WorkItems, Decisions, or Milestones into a scheduler log
-or transcript. Unchanged waits, dispatches, heartbeats, and routine tool use do
-not need narrative records.
-
-## Execute the chosen path
-
-Dispatch establishes the first owner and frozen Assignment. For ordinary
-clarification, feedback or a continuation of that same work, send a Message:
-
-```sh
-yui task message send <task> "<clarification or continuation>" --to <role> --work-item <work-id>
-yui task message send <task> "<review clarification>" --to <role> --review-round <round-id>
-```
-
-Busy execution queues the Message. Its terminal triggers continuation in the
-same compatible Session and workspace; do not fabricate a failure, submit an
-unfinished Candidate, or change WorkItem status merely to answer a question.
-Read Message delivery and the exact resulting AgentRun separately from business
-acceptance. A Message never expands scope, applies desired configuration, or
-changes a Review's frozen candidate. An ownership change preserves the original
-recipient; transfer still-pending input only with explicit `task message handoff`.
-Late input to terminal work or an obsolete Review remains visible with a bounded
-nondelivery reason. Use the existing formal operation for new scope or Review.
-
-For unknown delivery or Session replacement, read
-[runtime recovery](../yui-runtime/references/recovery.md). Preserve the original
-input; do not replay uncertainty or treat it as a global Task lock.
-
-For direct work, change only Task main, keep it on its managed branch, commit
-the result, and leave it clean. Run the smallest check that can catch the
-changed behavior while implementing.
-
-For a substantial delegated requirement:
-
-```sh
-yui task work create <task-id> "<title>" \
-  --project <project-to-modify> \
-  --objective "<bounded outcome>" \
-  --accept "<observable criterion>"
-```
-
-Add `--after` only for a real dependency. Likely file overlap is not by itself
-a dependency. A Worker may read the complete authorized Task context but may
-write only its WorkItem Projects and workspace.
-
-For a Leader-owned WorkItem, mark it running, complete it directly, then record
-its actual result:
-
-```sh
-yui task work update <work-id> running
-yui task work update <work-id> done --summary "<result and evidence>"
-yui task work accept <work-id> --summary "<explicit acceptance and evidence>"
-```
-
-For a native child, pass a bounded brief and applicable Profile constraints
-through the provider's child tools. A small investigation needs no synthetic
-WorkItem. If the child implements an existing Leader-owned WorkItem, keep that
-WorkItem roleless and mark it running. Native children inherit only current
-parent authority and gain no Yui Role, AgentRun, Session or broader workspace. Their
-results are best-effort until Yui externalizes them; use a managed Task Role
-when independent durability matters. Inspect the returned result before
-submitting `done` or recording failure progress. `done` creates a Candidate;
-`work accept` records the separate acceptance. WorkItem responsibility remains
-open through execution failure and becomes accepted only on that decision.
-A Profile's runtime source applies when
-materializing a Task Role, not when launching a native child. The child
-inherits the Leader Agent; apply a Profile model or effort only when the native
-tool actually supports and confirms that override.
-
-For a managed Task Role:
-
-```sh
-yui task role add <task-id> <role> --profile <profile>
-yui task role show <task-id> <role>
-yui task work create <task-id> "<outcome>" --role <role>
-yui task work dispatch <work-id> --input "<decision-complete brief>"
-```
-
-Profiles carry portable behavior plus either a dynamic Global Worker runtime
-source or an explicit Agent with optional model and effort. Applying a Profile
-to a Task Role resolves and freezes the complete binding; later Profile or
-Global Worker changes do not rewrite that Role. Before dispatch, use
-`profile show` and `task role show` to read the exact behavior, Agent, model,
-effort, Profile, and workspace. Do not reconstruct or guess launch
-configuration. Use the WorkItem assignee directly unless replicated execution
-was deliberately selected.
-
-Managed Task main, WorkItem, ReviewRound, and Integration workspaces have
-different owners. Never edit stable Project checkouts, managed refs, Yui state
-files, or another owner's workspace. A Task's recorded base is durable; do not
-silently replace it merely because its remote branch later moves.
-
-## Extend capabilities within this Task's authority
-
-Use `capability search`, `describe`, and `call` to inspect current tools.
-Prefer existing tools, composition or a one-off script when sufficient.
-For reusable Task-local capabilities, read [Task plugins](references/task-plugins.md)
-before creation, validation or activation. Plugin management permission does
-not grant code execution or broader external effects. Never issue your own
-grants, impersonate Operator, or modify the core installation to obtain a tool.
-
-## Validate and make the review judgment
-
-Use the smallest evidence that establishes the accepted behavior and material
-boundaries. Do not repeat a successful unchanged check. Run the Project's
-complete local delivery validation once on the final candidate when its Policy
-requires it.
-
-As part of accepting a WorkItem or completing a Task, decide whether additional
-review would add useful evidence:
-
-- inspect directly when the change is clear and existing evidence is enough;
-- use one independent Worker, native child, or Reviewer when independent
-  inspection materially reduces a reachable risk; or
-- rely on an already completed applicable Review.
-
-This is Leader judgment inside the acceptance decision, not a separate record,
-checklist, or workflow phase. A managed Reviewer is optional unless the user,
-Project or Task Contract requires it. Do not create a
-Reviewer Role or ReviewRound for ceremony. Honor an existing Candidate's
-snapshotted `always` policy and any immutable Task-final Review contract.
-Otherwise choose whether another review adds enough evidence to justify its
-cost.
-
-Use one direct main Reviewer by default. If independent replicas materially
-improve evidence, read [replicated execution](references/replicated-execution.md)
-before dispatch or synthesis. Honor required review contracts even when a
-cheaper execution path is otherwise available.
-
-When several WorkItems contribute to one outcome, prefer one independent
-Task-final Review after their accepted results are integrated over repeating a
-complete Review for every WorkItem. Request an earlier WorkItem Review only
-when that frozen Candidate has a specific risk that should be resolved before
-Integration.
-
-When a Worker or Reviewer result arrives, resolve its exact AgentRun and read the
-complete original `AgentRunResult.output` before starting new work or waiting
-again. Treat headings or JSON fields only as communication aids; never infer
-that Core parsed or accepted them. Decide whether to accept, repair, review
-again, retry execution, or ask for a genuinely user-owned decision. Route
-reachable issues to the original execution owner. Fix a small Task-main issue
-directly; create a Repair WorkItem only when the repair is itself a substantial
-independently owned requirement.
-
-A failed ReviewRound is an execution failure, not an automatic retry or repair
-wave. Inspect its exact Round, AgentRun, candidate, Core failure, and
-`task next-action` facts, then choose the smallest recovery that preserves the
-frozen boundary. Do not invent a retry loop or silently replace the Reviewer
-Session. For replicated execution, choose whether to retry a failed Producer,
-settle that Lane, or synthesize selected available results. Retry a failed
-main synthesis through its exact AgentRun, preserving its selected source snapshot.
-
-## Accept, integrate, and complete
-
-A Worker or Reviewer AgentRun result is evidence, not acceptance. Inspect the
-result, diff, checks, and current Candidate before deciding.
-
-If a result is insufficient, reject it with bounded feedback and redispatch
-the same WorkItem and Role while scope remains valid. Before accepting isolated
-Git changes, read [Integration](references/integration.md) to capture and
-integrate the latest Candidate. Do not edit managed refs or bypass Yui's
-compare-and-swap boundary.
-
-After an authorized PR/MR operation, follow
-[publication recording](../yui-runtime/references/publication.md).
-External delivery and Task completion remain separate facts.
-
-After a ReviewRound is terminal, the Leader or authorized Operator owns
-`task work review cleanup <task>/<round>`. Preserve dirty diagnostic evidence
-and resolve it explicitly; do not ask a Reviewer to clean its own runtime
-after its final report. Cleanup can remain advisory at completion, but all
-required resources must be settled before user-authorized archive.
-
-Complete only when the Task outcome is satisfied, required checks and review
-contracts are settled, WorkItems are accepted or deliberately retired, latest
-isolated results are integrated, and user inputs are resolved:
-
-```sh
-yui task complete <task-id> \
-  --summary "<outcome, validation, and remaining risk>"
-```
-
-Completion records the exact Project heads. Archive is a separate,
-user-authorized Operator action.
-
-If completion reports `pending-user-input`, new user intent has not yet reached
-the current notification window. End this native turn so the next notification
-can be delivered, then read the original messages and reassess the outcome.
-Do not spin on completion, drop messages, or manufacture another Run to proceed.
-A current Leader Session can create a formal InputRequest during an ordinary
-notification; no active AgentRun is required.
-
-## Finish every Leader AgentRun
-
-Before ending the AgentRun:
-
-1. Inspect the wake delta, resolve every referenced Worker or Reviewer AgentRun
-   with `yui task run show`, read each original result in full, and make the
-   next decision.
-2. Persist actual WorkItem lifecycle and material Brief, Decision, Milestone,
-   Message, or Knowledge changes.
-3. Choose one truthful outcome: continue through an owned native child, complete
-   the Task, create a justified InputRequest, or leave the active Task waiting
-   for a real durable event.
-4. Return one concise final report with outcome, checks, remaining risk, and
-   bounded next action.
-
-Do not claim completion only in prose when durable Task or WorkItem state still
-needs updating. Do not poll managed Roles or emit waiting Messages. Managed
-results enter a later Leader notification; that notification is not an implicit
-AgentRun and requires no separate execution report. An unchanged active Task remains quiet.
-
-Use the shared [runtime recovery](../yui-runtime/references/recovery.md) contract
-for failed execution. Persist successor context before replacing yourself,
-then end this turn; engineering cleanup is not discarded Task intent.
+Follow [yui-runtime](../yui-runtime/SKILL.md) first. Load the exact Context Pack
+for an explicitly dispatched AgentRun; for direct conversation or a Task
+notification, read current Task context through the Manifest's Session CLI.
+No self-dispatch or old completed Run is needed. Read the actual Task
+requirements, current Brief and relevant user/Operator Messages, not just
+their summaries. Resolve links relative to the file containing them.
+
+## Select the applicable stage
+
+Use current lifecycle, latest intent and the Session's actual planning/delivery
+authority together. Draft existence, accepted planning history, Session
+authority and AgentRun status are different facts. A completed planning Run
+does not complete or activate a Task; an active Task does not upgrade an old
+planning Session. Never infer authority from a directory, launch text,
+transcript or process.
+
+Apply terminal/gate and read-only intent boundaries before selecting delivery
+or planning work; the routes below do not override those restrictions.
+
+- **Draft or planning-only authority:** read [Planning and activation handoff](references/planning.md).
+  Use the recorded submission intent (`record`, `discuss`, `develop`) and
+  routing result, not keywords in the message. Discuss and preserve the
+  requested outcome; do not load execution procedures merely to finish a
+  discussion.
+- **Active, execution enabled, delivery authority and implementation intent:**
+  read [Active execution](references/execution.md). Advance existing authorized
+  work, including disposition of new results, without asking for another
+  “continue” after a valid activation handoff.
+- **Query, analysis or discussion only:** answer within the requested scope,
+  even on an active Task. Do not turn it into edits or dispatch. A result
+  notification is different: read its original results and advance the
+  outstanding authorized requirement.
+- **Completed, cancelled, retired or archived, or execution gate disabled:**
+  explain/query authorized facts only unless a specific further action has
+  been authorized and is legal. A conversation does not reopen, reactivate or
+  resume execution. If new implementation is requested, identify the needed
+  lifecycle/authority action for the Operator; do not manufacture a Run.
+
+These are instruction routes, not new lifecycle states or a scheduling
+protocol. Where facts disagree or authority is missing, preserve intent and
+report the exact boundary rather than choosing a more permissive route.
+
+## Maintain useful durable context
+
+The DB Brief is the current summary, not a full plan or a history of messages.
+After meaningful progress, use `task brief update` with only intended fields;
+read `task event list` before deliberately restoring an older value. Keep
+references to substantial plans, prototypes and reports in that summary.
+Decisions contain the actual decision, reason and necessary boundaries, not
+the entire proposal. Label recommendations as recommendations, not user
+decisions.
+
+Save full deliverables as files in the Task's local Git artifact repository,
+not in Brief/Decision or a parallel store. Use `task artifact save` or
+`artifact.save`; read [Task artifact operations](references/planning.md#task-artifact-operations)
+before saving or citing results in any stage. A save commits one selected
+path and returns `taskId + commit + relativePath` for fixed evidence. Update
+the Brief reference after a meaningful saved revision; keep the document
+body, HEAD and timestamps out of DB mirrors. Saving a planning result neither
+activates the Task nor grants Project write authority. Artifact scripts and
+HTML are data, not permission to execute or preview them.
+
+Add a Milestone only for an independently meaningful outcome, a Message only
+for a new conclusion another reader needs, and Project Knowledge only for a
+stable cross-Task lesson. Do not create records for every exchange, dispatch,
+heartbeat or unchanged wait. Ordinary fact edits need no self-wake.
+
+## Close the current turn
+
+- **Planning:** save meaningful revisions, summarize the discussion and await
+  feedback. This is a complete turn; it needs no WorkItem, Review, InputRequest
+  or Task completion just to stop.
+- **Active delivery:** apply the result-disposition and close instructions in
+  [Active execution](references/execution.md). Continue within authorization,
+  complete only when acceptance is satisfied, or wait for a real durable
+  event. Ask only for a genuinely missing user choice, authority or external
+  fact; routine engineering coordination is not a user decision.
+- **Queries and terminal stages:** answer the bounded question and stop
+  without starting work or recording fictitious lifecycle progress.
+
+Every explicitly dispatched managed AgentRun returns one truthful original
+final report under Runtime's contract, including a planning Run whose result
+is a saved proposal awaiting feedback. Ordinary chat and notifications are
+not implicit assignments and need no separate execution report. Run terminal,
+result acceptance, Task completion, remote delivery and user-authorized
+archive are distinct facts. Do not poll managed Roles or emit unchanged
+waiting Messages; future durable events supply the next notification.