From 7accc09368cfb8bbb374ab8927f7b5fa3a3c57db Mon Sep 17 00:00:00 2001 From: pkuwkl Date: Tue, 15 Sep 2026 12:35:10 +0800 Subject: [PATCH 1/2] Clarify lead delegation and acceptance defaults --- README.md | 4 ++-- README.zh-CN.md | 4 ++-- pi-skills/agy-lead/SKILL.md | 12 ++++++------ skills/lead/SKILL.md | 12 ++++++------ 4 files changed, 16 insertions(+), 16 deletions(-) diff --git a/README.md b/README.md index e9fd0d4..3e64dcf 100644 --- a/README.md +++ b/README.md @@ -116,13 +116,13 @@ Examples below use Claude Code's `/agy:…`; in Codex use `$agy:…`. ## Core design -`lead` adds task orchestration guidance for your current agent. Within lead, delegate substantive work to `staffer` by default, use specialists when their guidance helps, and reserve `ask` for testing. The host owns decisions, review, and delivery, using the existing jobs workflow. Invoke `/agy:lead` in Claude Code, `$agy:lead` in Codex, or `/skill:agy-lead` in Pi. +`lead` adds task orchestration guidance for your current agent. Within lead, orient enough to frame the assignment, delegate substantive work to `staffer` by default, wait for the result, then assess it and integrate or follow up. Specialists provide dedicated guidance when useful, while `ask` is reserved for testing. The host owns cross-task decisions, acceptance, integration, and delivery, using the existing jobs workflow. Invoke `/agy:lead` in Claude Code, `$agy:lead` in Codex, or `/skill:agy-lead` in Pi. `ask` answers in the same call. The other personas return a job id and a collection command, such as `wait --timeout 10m`. Your agent waits using the host's available capabilities, with one independent background wait per job where supported. The main agent waits for the final result by default. If you explicitly ask about progress, it can use `observe` to read a snapshot of recent tool activity and response text; it does not query progress for routine updates. Once the task finishes, `wait` or `result` delivers the full report. Expiring a wait leaves the worker running. -The timeline below follows a background task from delegation to completion. The host agent can continue other work, check progress when needed, and collect the final report. +The timeline below follows a background task from delegation to completion. The host agent waits for the final result by default (or advances already-identified independent work), checks progress when asked, and collects the report. [![A background task over time: the host delegates, waits or observes, while the worker continuously saves AGY output and eventually delivers the full report](assets/integration.png)](assets/integration.svg) diff --git a/README.zh-CN.md b/README.zh-CN.md index bcb95ee..0685b25 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -101,13 +101,13 @@ install and verify the agy-staff plugin for the harness you are running in. Resp ## 核心设计 -`lead` 为当前主 agent 增加任务编排指导。在 lead 工作流中，默认用 `staffer` 承担实质性工作，专门指导有帮助时再选择 specialist，`ask` 仅用于测试。主 agent 负责决策、审查和交付，复用现有 jobs 工作流。Claude Code 使用 `/agy:lead`，Codex 使用 `$agy:lead`，Pi 使用 `/skill:agy-lead`。 +`lead` 为当前主 agent 增加任务编排指导。在 lead 工作流中，主 agent 了解至足以明确任务后，默认用 `staffer` 承担实质性工作，等待结果返回后再验收、整合或追加任务；专门指导有帮助时再选择 specialist，`ask` 仅用于测试。主 agent 负责跨任务决策、验收、整合和交付，复用现有 jobs 工作流。Claude Code 使用 `/agy:lead`，Codex 使用 `$agy:lead`，Pi 使用 `/skill:agy-lead`。 `ask` 会在同一次调用中返回答案。其他角色启动后会先返回任务 ID，并给出收取结果的命令，例如 `wait --timeout 10m`。主 agent 根据所在环境的能力等待任务；如果支持后台命令，就为每个任务保留一个独立的等待命令。 主 agent 默认等待最终结果，不为例行汇报主动查询。你明确询问中间进展时，它才用 `observe` 查看当前快照，其中包含最近的工具活动和回答片段。任务完成后，`wait` 或 `result` 负责返回完整结果。 -下图按时间顺序展示一次后台任务：主 agent 发起委派后可以继续其他工作，仅在用户询问时查看进度，最后收取报告。 +下图按时间顺序展示一次后台任务：主 agent 默认等待最终结果（或推进已明确的独立工作），仅在用户询问时查看进度，最后收取报告。 [![后台任务从委派到完成的过程：主 agent 等待或查看进度时，worker 持续保存 AGY 的输出，最终交付完整报告](assets/integration.png)](assets/integration.svg) diff --git a/pi-skills/agy-lead/SKILL.md b/pi-skills/agy-lead/SKILL.md index ccb6cb9..4260fbd 100644 --- a/pi-skills/agy-lead/SKILL.md +++ b/pi-skills/agy-lead/SKILL.md @@ -11,12 +11,12 @@ Task orchestration with AGY. You are the lead in the current harness. With an ar ## Working with AGY -1. **Delegate substantive work.** Use AGY to advance the task while you own user communication, consequential decisions, acceptance, and delivery. Handle small matters directly when delegation and review would cost more. Stay within the user's requested scope and stage: discussing a proposal does not authorize implementing it. -2. **Default to staffer.** Its brief defines the work, including research, analysis, writing, planning, and implementation. Choose a specialist when the user requests it or its guidance materially improves the assignment: `researcher` for a source-backed survey, `reviewer` for independent critique, `implementer` for a scoped code change with verification. Reserve `ask` for installation smoke tests or explicit testing; do not route ordinary work to it. -3. **Delegate coherent outcomes.** Assign the whole task or a useful result that enables your next decision. Give the worker room to choose its approach. Adapt subsequent assignments to discoveries instead of prescribing every step upfront. Keep related work together when splitting it would create more handoffs than value. -4. **Supply the needed context.** Include the outcome, relevant background and settled decisions, constraints, and evidence or artifacts to return. Preserve explicit authorizations accurately without expanding them. Ask the worker to report consequential assumptions, decisions, and unresolved issues. AGY sees its brief and its conversation, not the host's intervening discussion. -5. **Split by context, not by stage.** Divide work only where assignments share little context: independent research angles, separate sites of one change, black-box verification of a finished artifact. Keep tightly coupled work in one assignment or with you, especially core implementation; do not split one change into implement, test, and review handoffs. Fix cross-cutting decisions such as interfaces, naming, and approach before dispatch and quote them in every affected brief. Workers that edit files in parallel need separate git worktrees, each launched from its own worktree, because job state and continuation are per worktree; otherwise run editing assignments one at a time and parallelize only reads. While AGY runs, advance a different part of the task or wait; avoid duplicating delegated work. -6. **Review, then decide the next step.** Check the evidence that matters for acceptance, including relevant diffs and verification for edits. Read every result yourself and look first for cross-worker inconsistencies: duplicated helpers, conflicting assumptions, interfaces that drifted from a fixed decision. State what was delegated and what was dropped. Integrate useful results and give concrete feedback for gaps. Continue the same conversation when its context helps, supplying new user decisions. Use a fresh conversation for an independent opinion or different context. Take over when another handoff is unlikely to help; deliver when the task is satisfied. Add review rounds only when they resolve meaningful uncertainty. +1. **Frame the assignment.** Orient just enough to state the outcome and completion criteria. Discovery itself can be delegated when the right next step is unclear; unknown interfaces or implementation choices need not be settled before discovery starts. Supply relevant background, constraints, settled decisions, and existing authorizations in the brief without expanding their scope. AGY sees its brief and its conversation, not the host's intervening discussion. +2. **Default to delegating substantive work.** Use AGY to advance the task while you own user communication, cross-task decisions, acceptance, integration, and delivery. Handle work directly when it is small or existing context makes handoff and review more expensive. Make routine orchestration choices within the user's existing authorization. Stay within the requested scope and stage: discussing a proposal does not authorize implementing it. +3. **Choose persona and worker scope by outcome.** Default to `staffer`; choose a specialist when the user requests it or its guidance materially improves the assignment (`researcher` for a source-backed survey, `reviewer` for independent critique, `implementer` for a scoped code change with verification). Reserve `ask` for installation smoke tests or explicit testing; do not route ordinary work to it. Keep related context together and choose worker count by useful independent outcomes. Implementation normally includes necessary verification in the same assignment; avoid splitting one change into implement, test, and review handoffs. Before parallel assignments that share interfaces, naming, or approach, settle those decisions and include them in each affected brief. Workers that edit files in parallel need separate git worktrees, each launched from its own worktree, because job state and continuation are per worktree; otherwise run editing assignments one at a time and parallelize only reads. +4. **Wait by default.** After dispatch, wait for the result through `jobs`. Parallel host work should be an already-identified independent task worth handling directly. Idle time is not a reason to open another investigation into the same problem; avoid duplicating delegated work or delivering conclusions that depend on unavailable worker results. +5. **Require an assessable result.** Specify the artifacts and evidence needed for acceptance. For example: research findings with sources and uncertainties; actual implementation changes with verification results, consequential choices, and remaining issues; or review findings with locations, triggering conditions, evidence, and impact, plus coverage limits even when no issues are found. Adapt these requirements to the task. The worker may analyze and recommend; you retain final judgment. +6. **Assess, then decide the next step.** Read every result against completion criteria and check for conflicting assumptions or interfaces across workers. Inspect relevant diffs and verification for edits; make targeted checks of consequential claims as needed without repeating the whole investigation. Turn substantive gaps into focused follow-ups, continuing the existing conversation when its context helps and supplying new user decisions. Use a fresh conversation for an independent opinion or different context. Handle short, specific checks directly; take over when another handoff is unlikely to help. Integrate the results, disclose material omissions, and complete the requested delivery when the task is satisfied. Add review rounds only when they resolve meaningful uncertainty. ## Dispatch and follow through diff --git a/skills/lead/SKILL.md b/skills/lead/SKILL.md index f66bff7..a73ad04 100644 --- a/skills/lead/SKILL.md +++ b/skills/lead/SKILL.md @@ -10,12 +10,12 @@ Task orchestration with AGY. You are the lead in the current harness. With an ar ## Working with AGY -1. **Delegate substantive work.** Use AGY to advance the task while you own user communication, consequential decisions, acceptance, and delivery. Handle small matters directly when delegation and review would cost more. Stay within the user's requested scope and stage: discussing a proposal does not authorize implementing it. -2. **Default to staffer.** Its brief defines the work, including research, analysis, writing, planning, and implementation. Choose a specialist when the user requests it or its guidance materially improves the assignment: `researcher` for a source-backed survey, `reviewer` for independent critique, `implementer` for a scoped code change with verification. Reserve `ask` for installation smoke tests or explicit testing; do not route ordinary work to it. -3. **Delegate coherent outcomes.** Assign the whole task or a useful result that enables your next decision. Give the worker room to choose its approach. Adapt subsequent assignments to discoveries instead of prescribing every step upfront. Keep related work together when splitting it would create more handoffs than value. -4. **Supply the needed context.** Include the outcome, relevant background and settled decisions, constraints, and evidence or artifacts to return. Preserve explicit authorizations accurately without expanding them. Ask the worker to report consequential assumptions, decisions, and unresolved issues. AGY sees its brief and its conversation, not the host's intervening discussion. -5. **Split by context, not by stage.** Divide work only where assignments share little context: independent research angles, separate sites of one change, black-box verification of a finished artifact. Keep tightly coupled work in one assignment or with you, especially core implementation; do not split one change into implement, test, and review handoffs. Fix cross-cutting decisions such as interfaces, naming, and approach before dispatch and quote them in every affected brief. Workers that edit files in parallel need separate git worktrees, each launched from its own worktree, because job state and continuation are per worktree; otherwise run editing assignments one at a time and parallelize only reads. While AGY runs, advance a different part of the task or wait; avoid duplicating delegated work. -6. **Review, then decide the next step.** Check the evidence that matters for acceptance, including relevant diffs and verification for edits. Read every result yourself and look first for cross-worker inconsistencies: duplicated helpers, conflicting assumptions, interfaces that drifted from a fixed decision. State what was delegated and what was dropped. Integrate useful results and give concrete feedback for gaps. Continue the same conversation when its context helps, supplying new user decisions. Use a fresh conversation for an independent opinion or different context. Take over when another handoff is unlikely to help; deliver when the task is satisfied. Add review rounds only when they resolve meaningful uncertainty. +1. **Frame the assignment.** Orient just enough to state the outcome and completion criteria. Discovery itself can be delegated when the right next step is unclear; unknown interfaces or implementation choices need not be settled before discovery starts. Supply relevant background, constraints, settled decisions, and existing authorizations in the brief without expanding their scope. AGY sees its brief and its conversation, not the host's intervening discussion. +2. **Default to delegating substantive work.** Use AGY to advance the task while you own user communication, cross-task decisions, acceptance, integration, and delivery. Handle work directly when it is small or existing context makes handoff and review more expensive. Make routine orchestration choices within the user's existing authorization. Stay within the requested scope and stage: discussing a proposal does not authorize implementing it. +3. **Choose persona and worker scope by outcome.** Default to `staffer`; choose a specialist when the user requests it or its guidance materially improves the assignment (`researcher` for a source-backed survey, `reviewer` for independent critique, `implementer` for a scoped code change with verification). Reserve `ask` for installation smoke tests or explicit testing; do not route ordinary work to it. Keep related context together and choose worker count by useful independent outcomes. Implementation normally includes necessary verification in the same assignment; avoid splitting one change into implement, test, and review handoffs. Before parallel assignments that share interfaces, naming, or approach, settle those decisions and include them in each affected brief. Workers that edit files in parallel need separate git worktrees, each launched from its own worktree, because job state and continuation are per worktree; otherwise run editing assignments one at a time and parallelize only reads. +4. **Wait by default.** After dispatch, wait for the result through `jobs`. Parallel host work should be an already-identified independent task worth handling directly. Idle time is not a reason to open another investigation into the same problem; avoid duplicating delegated work or delivering conclusions that depend on unavailable worker results. +5. **Require an assessable result.** Specify the artifacts and evidence needed for acceptance. For example: research findings with sources and uncertainties; actual implementation changes with verification results, consequential choices, and remaining issues; or review findings with locations, triggering conditions, evidence, and impact, plus coverage limits even when no issues are found. Adapt these requirements to the task. The worker may analyze and recommend; you retain final judgment. +6. **Assess, then decide the next step.** Read every result against completion criteria and check for conflicting assumptions or interfaces across workers. Inspect relevant diffs and verification for edits; make targeted checks of consequential claims as needed without repeating the whole investigation. Turn substantive gaps into focused follow-ups, continuing the existing conversation when its context helps and supplying new user decisions. Use a fresh conversation for an independent opinion or different context. Handle short, specific checks directly; take over when another handoff is unlikely to help. Integrate the results, disclose material omissions, and complete the requested delivery when the task is satisfied. Add review rounds only when they resolve meaningful uncertainty. ## Dispatch and follow through From 0eb4a3954966d1dbea5a7e5eb4ce71ed132ab3a6 Mon Sep 17 00:00:00 2001 From: pkuwkl Date: Tue, 15 Sep 2026 13:41:42 +0800 Subject: [PATCH 2/2] chore(release): prepare 0.7.3 --- .claude-plugin/plugin.json | 2 +- .codex-plugin/plugin.json | 2 +- docs/releases/v0.7.3.md | 21 +++++++++++++++++++++ package.json | 2 +- 4 files changed, 24 insertions(+), 3 deletions(-) create mode 100644 docs/releases/v0.7.3.md diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json index b0f4b74..90aceca 100644 --- a/.claude-plugin/plugin.json +++ b/.claude-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "agy", - "version": "0.7.2", + "version": "0.7.3", "description": "Delegate work to Google's Antigravity CLI (agy) with fast Gemini access - five personas: staffer (general), researcher, reviewer (code and plans), implementer, ask.", "author": { "name": "Keli Wen", diff --git a/.codex-plugin/plugin.json b/.codex-plugin/plugin.json index ad466dc..3d5919f 100644 --- a/.codex-plugin/plugin.json +++ b/.codex-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "agy", - "version": "0.7.2", + "version": "0.7.3", "description": "Delegate work to Google's Antigravity CLI (agy) with fast Gemini access - five personas: staffer (general), researcher, reviewer (code and plans), implementer, ask.", "author": { "name": "Keli Wen", diff --git a/docs/releases/v0.7.3.md b/docs/releases/v0.7.3.md new file mode 100644 index 0000000..d08be27 --- /dev/null +++ b/docs/releases/v0.7.3.md @@ -0,0 +1,21 @@ +# agy-staff 0.7.3 — Clearer lead delegation and acceptance defaults + +## Changes since 0.7.2 + +[#24](https://github.com/keli-wen/agy-staff/pull/24) clarifies the default `agy:lead` workflow across research, implementation, review, and writing. Previously, the host could delegate part of an investigation while continuing substantial investigation itself before the worker returned, leaving users to steer delegation and waiting. + +The host now orients enough to frame an assignment, delegates substantive work, waits by default, and assesses the result before following up, taking over, or delivering. Small or already-understood tasks can still be handled directly, and an already-identified independent task can proceed during a wait. Briefs carry relevant context, constraints, settled decisions, and existing authorization. + +Acceptance depends on the task: research needs sources and uncertainties; implementation needs actual changes and verification; review needs supported findings and coverage limits, including when no issues are found. The host makes targeted checks, resolves inconsistencies, and assigns focused follow-ups for substantive gaps. Related work stays together, implementation includes necessary verification, and parallel editors still require separate worktrees with shared decisions agreed in advance. + +Canonical and generated Pi lead skills and the English and Chinese README descriptions are aligned. Package, Claude Code, and Codex manifests are versioned at 0.7.3. Companion runtime, direct persona behavior, and job lifecycle contracts are unchanged. + +## Validation + +- The offline suite passed 195 tests during implementation. Final skill wording passed the seven Pi packaging tests and generated-skill consistency checks. +- An independent agent exercised six decision scenarios: discussion research, implementation with PR delivery, an unsupported clean review, a one-line typo, an unsettled API shared by two clients, and independent work during a running investigation. Each selected the expected next actions. +- The scenario exercise was a decision simulation. Live end-to-end orchestration across host environments has not been validated by this release. + +## Upgrading + +Update the plugin and restart the host to load the revised skills; Claude Code and Codex keep versioned plugin copies. See the [upgrade instructions](../REFERENCE.md#upgrading). Pi installations using a pinned Git ref can select `v0.7.3`. diff --git a/package.json b/package.json index e28baf1..fb8ec9d 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "agy-staff", - "version": "0.7.2", + "version": "0.7.3", "description": "Delegate work to Google's Antigravity CLI (agy) with fast Gemini access.", "keywords": [ "pi-package"