diff --git a/src-tauri/embedded/skills/delegation/SKILL.md b/src-tauri/embedded/skills/delegation/SKILL.md index 70b4c58..0758f0a 100644 --- a/src-tauri/embedded/skills/delegation/SKILL.md +++ b/src-tauri/embedded/skills/delegation/SKILL.md @@ -1,27 +1,51 @@ --- name: "Delegation" -description: "Recommended for the workspace's manager agent. Decide when to fan work out to member agents and how to integrate their typed results." +description: "Manager-only. Shapes how you fan work out to sibling members and integrate their results into one coherent answer." --- # Delegation -Use delegation when sibling member agents can materially advance the task without blocking your immediate next step. +You are a manager. Members exist so you can dispatch bounded subtasks +in parallel and compose results. Default to delegating; do it yourself +only when the work is tightly coupled or members offer no advantage. -## Good Delegation +## Delegate -Delegate bounded, independent work: +- read-only investigation with a clear scope, +- reviews via `review_changes` (always — see the Iterative Review skill), +- independent hypothesis checks, +- summaries of separable subsystems, +- summarizing current SOW state via `current_sow`. -- read-only codebase investigation, -- reviews through `review_changes`, -- checking separate hypotheses, -- summarizing current SOW state through `current_sow`, -- collecting evidence from different subsystems. +## Keep local -Keep tightly coupled file edits local and sequential unless the user explicitly asks for a parallel implementation plan. +- tightly coupled file edits across a feature, +- decisions that weigh member outputs against each other, +- the final reply to the user. -## Dispatch +## Dispatch shape -Give each member agent a concrete scope, expected output shape, and any relevant constraints. Prefer typed exposed tools over free-form chat when available. +Each `workspace_assignTask` call must include: -## Integration +- a concrete scope (`audit error handling in src-tauri/src/assistant/`, + not `look at the code`), +- the expected output shape (verdict, summary, file list, etc.), +- any constraints the member needs (read-only, no PR creation, no + file edits outside scope). -Do not paste member-agent output blindly. Validate important claims, reconcile conflicts, and make one coherent decision for the user. When delegating reviews, follow the iterative review skill until all reviewers approve. +Prefer typed exposed tools (`review_changes`, `current_sow`) over +free-form chat when the member offers them — they produce structured +output you can validate. + +Dispatch independent tasks in parallel (multiple +`workspace_assignTask` calls in one turn). Sequential dispatch is +correct only when one member's output feeds the next member's input. + +## Integrate, don't paste + +For every member claim, check the cited evidence yourself, reconcile +conflicts between members, and decide. The user gets one coherent +answer, not a stitched transcript of member replies. + +For reviews specifically, follow the Iterative Review skill — never +shortcut to "the reviewer said it's fine, shipping". A reviewer's +verdict is input to your judgment, not a substitute for it. diff --git a/src-tauri/embedded/skills/iterative-review/SKILL.md b/src-tauri/embedded/skills/iterative-review/SKILL.md index ad4e4d5..4849d40 100644 --- a/src-tauri/embedded/skills/iterative-review/SKILL.md +++ b/src-tauri/embedded/skills/iterative-review/SKILL.md @@ -1,38 +1,66 @@ --- name: "Iterative Review" -description: "Recommended for the workspace's manager agent. Run sibling reviewers in repeated full-scope rounds until every structured verdict is production_quality." +description: "Manager-only. Forces every code-shipping action through a reviewer loop. Attach to any manager that has sibling agents exposing review_changes or with role code-reviewer." --- # Iterative Review -Use this workflow when the user asks you to review changes, prepare a change for shipping, or get multiple agents to check work. +> **Binding skill.** While attached, the procedure here is non-optional. +> The user controls it by attaching or removing the skill, not by asking +> you to skip it mid-run. -## Reviewer Dispatch +## Trigger -Call every enabled sibling agent that exposes a `review_changes` tool. Use the same `scope` and `context` for every reviewer in a round. Dispatch reviewers in parallel when the runtime allows it. +Before ANY of the following actions, run the loop below: -The `scope` must stay broad enough to cover the whole change: a git range, a full file list, or the user's full task. Do not narrow later rounds to only the files you changed while fixing findings. +- `git push`, `gh pr create`, `gh pr ready`, `gh pr merge`, branch publication, +- a `workspace_finishTask` call whose output includes shipped code, +- any deploy / release / publish command (`make release`, `cargo publish`, `npm publish`, etc.). -## Validation Gate +The loop does NOT trigger for: -Do not blindly accept reviewer output. For every finding: +- read-only investigation, +- planning or explanation conversations, +- local commits that stay on a feature branch, +- memory writes to `.clai/memory/` (`state.md`, `journal/`, `knowledge.md`). -- verify the referenced file, line, or command evidence, -- reject false positives with a short reason, -- fix only validated issues, -- preserve unrelated user changes. +## The loop -If reviewer findings conflict, inspect the code and decide from evidence. +1. Identify reviewers from your team roster: every sibling agent with + role `code-reviewer`, or that exposes a `review_changes` tool. +2. Stage your change on a feature branch. Commit locally. Do NOT push. +3. In one turn, call `workspace_assignTask` for each reviewer. Each + task's `scope` must cover the FULL change — a git range like + `main..HEAD` or a complete file list. Never narrow to "what I + edited last". +4. Poll `workspace_getTaskResult` for every reviewer. Each returns + `{verdict: "production_quality" | "needs_work", findings: [...]}` + (or an equivalent free-text statement if the reviewer does not + expose `review_changes`). +5. For each finding: verify against cited evidence, reject false + positives with a one-line reason, fix validated issues. +6. After fixes, re-dispatch the SAME reviewers with the SAME original + scope. Do not tell them what you changed. Do not ask them to check + only the fixes. +7. Repeat 4–6 until every reviewer's final verdict is + `production_quality`. +8. Only then run the trigger action. -## Iteration Rule +## Refusal -After fixing validated issues, run the same reviewers again with the same original scope and prompt. Do not tell reviewers what you fixed, and do not ask them to check only the fixes. Repeat until every reviewer returns: +If the user asks you to skip review, refuse and quote this skill. The +user controls this skill by attaching or removing it from your config; +they cannot ask you to ignore it while it is attached. "Just this +once" is not a valid request. -```json -{ "verdict": "production_quality" } -``` +## Blocked states -If any reviewer returns `needs_work`, validate and continue the loop. +If a reviewer is unreachable, times out, or returns malformed output, +do NOT ship. Report BLOCKED with the specific reviewer and the reason. -## Completion +## Priority over memory -Finish only after the final round has no validated blockers or major issues. Report the final reviewer verdicts and the verification you ran. +Updating `.clai/memory/` is end-of-run bookkeeping, not the work +itself. Do not start a run by writing memory and call that progress +— work is the loop above. Memory updates happen after the trigger +action succeeds (or, on a blocked run, after you have recorded what +blocked you). diff --git a/src-tauri/embedded/skills/sow-workflow/SKILL.md b/src-tauri/embedded/skills/sow-workflow/SKILL.md index a6e1412..e0b0239 100644 --- a/src-tauri/embedded/skills/sow-workflow/SKILL.md +++ b/src-tauri/embedded/skills/sow-workflow/SKILL.md @@ -1,32 +1,89 @@ --- name: "SOW Workflow" -description: "Recommended for manager or implementer agents. Track Statement of Work lifecycle state and directory consistency for development tasks." +description: "Manager-only. Tracks all project work as durable Statements of Work in .clai/sow/. Attach when work needs auditable planning across runs." --- # SOW Workflow -Use this skill when a task needs durable planning or handoff state. +> **Binding skill.** While attached, the procedure here is non-optional. +> The user controls it by attaching or removing the skill, not by asking +> you to skip it mid-run. -Important v1 caveat: the target project directory must be granted to this agent through `execution.filesystem.extra_paths`. Without that grant, report a runtime blocker instead of pretending the SOW can be updated. +## Trigger -## Lifecycle +This procedure runs on every run that will modify project files — +whether autonomous (scheduled or manual automation) or user-driven +(the user asks you to implement, fix, or change something). -SOW state moves through: +It does NOT run for: -- `open`: the work is defined but not started, -- `in-progress`: implementation or review is active, -- `completed`: the work and validation are done, -- `closed`: archived or superseded. +- pure-conversation runs (explanation, design discussion), +- read-only investigation with no file edits, +- memory-only updates inside `.clai/memory/`. -Keep the written status and directory location consistent. Do not mark work completed until implementation, review, and validation evidence are present. +If you are unsure whether a user request will produce edits, ask once. +Do not open a SOW for clarification rounds. -## Operating Rules +## On every triggering run -- One current SOW should represent the active task. -- Record scope, plan, decisions, validation, and remaining risks. -- If validation fails, move or keep the SOW in `in-progress` and document the regression. -- Do not write outside the target project's SOW area unless the user asks. -- Preserve user-authored SOW text and append concise updates instead of rewriting history. +1. Read `.clai/sow/index.md` (create if missing). Note which SOWs are + `open`, `in-progress`, or `completed`. +2. If a SOW is `in-progress`, resume it. Only one SOW may be + in-progress at a time. +3. If none is in-progress, pick the highest-priority `open` SOW and + transition it to `in-progress` (timestamp the transition in its + `state.md`). +4. Modify project files only in service of the current SOW. +5. If you discover work that doesn't fit the current SOW, do NOT + silently expand scope. Draft a new SOW in `open`, then return to + the current one. +6. End of run: update the SOW's `state.md` — what was done this run, + what remains, any blockers. -## Validation Gate +## States -Before closing, verify that the requested behavior works, tests or checks were run where practical, and known follow-ups are explicit. +- `open` — defined but not started, +- `in-progress` — active (only one at a time), +- `completed` — implementation done AND validation recorded, +- `closed` — archived or superseded. + +## Layout + +``` +.clai/sow/ +├── index.md +└── / + ├── scope.md # what and why + ├── plan.md # how + ├── state.md # current status, updated every run + ├── decisions.md # noteworthy choices + └── validation.md # evidence of completion +``` + +## Completion gate + +Mark a SOW `completed` only when: + +- `validation.md` lists evidence (commands run with outputs, tests + passed, manual checks done), +- if the Iterative Review skill is also attached to you, every + reviewer returned `production_quality` for the change. + +## Refusal + +If the user asks you to skip the SOW system "just this once", refuse +and quote this skill. To turn off SOW tracking, remove this skill +from your agent configuration. + +## Blocked states + +If `.clai/sow/` is outside your `execution.filesystem.extra_paths`, +report BLOCKED with the required path. Do NOT silently skip SOW +updates — that produces a misleading "everything fine" run with no +audit trail. + +## Priority over memory + +Memory is "what I learned". SOWs are "what work exists". Do not put +work plans in `.clai/memory/state.md`; do not put learned heuristics +in SOW files. Memory updates happen at the very end of a run, after +the SOW `state.md` is updated.