From ca63861207bea7e22ad99066d163830961eae19b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Carlos=20Flor=C3=AAncio?= Date: Thu, 23 Jul 2026 19:58:43 +0100 Subject: [PATCH] chore: consolidate harness delegation guidance (#1906) --- .agents/skills/add-integration/SKILL.md | 9 ++--- .agents/skills/code-review/SKILL.md | 11 +++--- .agents/skills/debug/SKILL.md | 4 +- .agents/skills/fix/SKILL.md | 38 +++++-------------- .agents/skills/plan/SKILL.md | 3 +- .agents/skills/planner-orchestration/SKILL.md | 5 ++- .agents/skills/qa/SKILL.md | 11 +++--- .../skills/spec-driven-development/SKILL.md | 8 ++-- .agents/skills/using-agent-skills/SKILL.md | 11 ------ .claude/commands/harness-improvement.md | 13 +++---- .claude/commands/pr-fixup.md | 20 ++++------ .claude/commands/spec-driven-development.md | 21 ++++------ .cursor/rules/kandev-pr-fixup.mdc | 21 ++++------ AGENTS.md | 11 +++--- .../configloader/instructions/ceo/AGENTS.md | 26 +++++++------ .../instructions/ceo/HEARTBEAT.md | 10 ++++- .../instructions/devops/AGENTS.md | 2 +- .../configloader/instructions/qa/AGENTS.md | 3 +- .../instructions/worker/AGENTS.md | 10 ++--- docs/specs/office/agents.md | 8 ++-- 20 files changed, 103 insertions(+), 142 deletions(-) diff --git a/.agents/skills/add-integration/SKILL.md b/.agents/skills/add-integration/SKILL.md index 7f33269b7f..0b31e91629 100644 --- a/.agents/skills/add-integration/SKILL.md +++ b/.agents/skills/add-integration/SKILL.md @@ -7,11 +7,10 @@ description: Add a new third-party integration (Jira/Linear-style) — per-works ## Planner Entry -Load `/spec-driven-development`. The user-started -primary session plans the integration and delegates each backend, frontend, -test, and documentation task to bounded workers. It does not scaffold or verify -the integration directly. An explicitly assigned implementer follows the -relevant sections below and does not spawn other workers. +Load `/spec-driven-development` for a substantial integration. The primary +session plans, investigates existing patterns, and may directly implement a +small localized slice. Delegate only independent backend, frontend, test, or +documentation packets whose isolation clearly helps; workers do not spawn. Jira and Linear are the model: per-workspace credentials, a 90s auth-health poller, a settings page with status banner + reconnect CTA, link/import buttons that gate on availability. New integrations should **reuse the shared shapes** rather than copying either. diff --git a/.agents/skills/code-review/SKILL.md b/.agents/skills/code-review/SKILL.md index 54652f637d..548ab3ba97 100644 --- a/.agents/skills/code-review/SKILL.md +++ b/.agents/skills/code-review/SKILL.md @@ -7,11 +7,12 @@ description: Review changed code for quality, security, and architecture complia ## Planner Entry -The user-started primary session delegates this -procedure to the registered `code-review` worker and reviews its findings. It -assigns any fixes to an implementer and delegates security-sensitive follow-up -to `security-auditor`; it does not review or edit the change directly. An -explicitly assigned review worker continues below and does not spawn workers. +The user-started primary session reviews small, localized changes directly and +uses current-head PR AI review as the routine independent semantic evidence. +Delegate to the registered `code-review` worker only for exceptional +architecture, cross-cutting, high-risk, or insufficiently reviewed changes. +Assign fixes or security follow-up to workers only when their scope warrants it. +An explicitly assigned review worker continues below and does not spawn workers. Review the current changes in the codebase (Go backend + Vite/React SPA monorepo). Every finding needs a `file_path:line_number` reference, an explanation of *why* it matters, and a concrete fix. diff --git a/.agents/skills/debug/SKILL.md b/.agents/skills/debug/SKILL.md index 69ab9878d3..98b70c0721 100644 --- a/.agents/skills/debug/SKILL.md +++ b/.agents/skills/debug/SKILL.md @@ -10,8 +10,8 @@ Diagnose efficiently and safely. Debugging produces evidence and a root-cause hy ## Planner Entry -The planner may diagnose a small, bounded issue directly. Delegate broad or -unknown exploration and long/noisy debugging to one `implementer` with +The planner performs first-pass triage directly. Delegate only a concrete broad +or long/noisy debugging question after local triage to one `implementer` with production edits forbidden; then decide whether `/fix` is needed. An explicitly assigned worker follows the remaining procedure, cleans up its diff --git a/.agents/skills/fix/SKILL.md b/.agents/skills/fix/SKILL.md index fe6b602b6c..3f632c7288 100644 --- a/.agents/skills/fix/SKILL.md +++ b/.agents/skills/fix/SKILL.md @@ -9,34 +9,16 @@ Systematic bug fixing: reproduce the problem, find the root cause, apply a minim ## Planner Entry -For small, clear bugs, the planner may perform the bounded reproduction, TDD -fix, and focused checks directly. Delegate broad diagnosis, large fixes, or -independent work. In the user-started primary session: - -1. Delegate reproduction and root-cause diagnosis to an `implementer` worker - with production edits forbidden. It may create or update only the minimal - failing regression test when that test path is explicitly owned. This - diagnosis packet explicitly overrides the generic implementer workflow: - reproduce and trace, return evidence and root cause, do not patch production - code, and do not continue to Phase 3. -2. Review the evidence and present the root cause to the user. -3. Delegate the minimal production patch to an `implementer` worker. It - preserves or completes the diagnosis regression test and runs green targeted - verification without duplicating that test unnecessarily. -4. Apply `/planner-orchestration` risk routing: for PR delivery, obtain - qualifying current-head PR AI semantic evidence, always run final `verify`, - and use local QA/review/security agents only for exceptional routes. - -Stop after dispatching and coordinating these assignments. Do not continue into -the direct fix procedure below. A diagnostic worker performs phases 0-2 and -returns evidence and root cause. It returns a red-test result when it owns a -test path; otherwise it returns concrete reproduction evidence and a proposed -regression-test scenario/path. Production code remains forbidden, and -diagnostic instrumentation is test-only when owned or non-mutating. It must -not continue to Phase 3. A fix implementer performs the minimal production -patch, preserves or completes that regression test without unnecessary -duplication, and runs targeted tests. No worker performs planner phases 4-5 or -spawns other workers. +For small, clear bugs, the planner performs the bounded reproduction, +root-cause trace, TDD fix, and focused checks directly. It does not delegate +first-pass logs, sessions, call-path mapping, or reproduction just because the +issue is unfamiliar. Delegate only a concrete post-triage question requiring +independent evidence, or a broad, large, or cross-component fix. A diagnostic +worker may own an explicitly named regression test but not production edits; a +patch worker owns the minimal production change and targeted verification. +Apply `/planner-orchestration` risk routing: for PR delivery, obtain qualifying +current-head PR AI semantic evidence, always run final `verify`, and use local +QA/review/security agents only for exceptional routes. Workers do not spawn. ## Available skills and subagents diff --git a/.agents/skills/plan/SKILL.md b/.agents/skills/plan/SKILL.md index 25224eaad8..d7d70e19c8 100644 --- a/.agents/skills/plan/SKILL.md +++ b/.agents/skills/plan/SKILL.md @@ -6,7 +6,8 @@ description: Create a committed implementation plan from a feature spec. Explore # Create Implementation Plan This is a planner-side artifact skill. The user-started primary planner creates -the plan and worker packets, then delegates every execution task. +the plan and worker packets for substantial independent work; it keeps small, +localized execution and focused verification local. Translate a feature spec into a concrete, phased implementation plan saved under `docs/plans//`. Plans and task files are committed implementation diff --git a/.agents/skills/planner-orchestration/SKILL.md b/.agents/skills/planner-orchestration/SKILL.md index 2bbc9c578f..cac3d0862e 100644 --- a/.agents/skills/planner-orchestration/SKILL.md +++ b/.agents/skills/planner-orchestration/SKILL.md @@ -28,7 +28,10 @@ Spark `verify` after commit and before push for code, tests, or config. Supply the `/commit` hook receipt so changed-scope verification avoids only proven duplicate hook work. -Delegate when ROI or independent evidence matters: broad/unknown exploration, +The planner performs initial log/session inspection, call-path tracing, and +reproduction directly. Do not delegate that first pass, waiting, or status +relays. Delegate when ROI or independent evidence matters: broad/unknown exploration +after local triage, substantial plan work, large/cross-component changes, parallel packets, long/noisy E2E or debugging, exceptional specialists, and final change-aware `verify`. Keep long monitoring with cheap `pr-poller`. Estimate context reload and diff --git a/.agents/skills/qa/SKILL.md b/.agents/skills/qa/SKILL.md index f288cd4848..67aea416f6 100644 --- a/.agents/skills/qa/SKILL.md +++ b/.agents/skills/qa/SKILL.md @@ -7,11 +7,12 @@ description: Verify a feature works after implementation. Actively try to break ## Planner Entry -The user-started primary session delegates this -entire procedure to the registered `qa` worker, reviews its report, and creates -new implementer assignments for any fixes. It does not run QA or fix findings -directly. An explicitly assigned `qa` worker continues below and does not spawn -other workers. +The planner performs focused QA directly for ordinary changes, using targeted +tests and current-head PR AI review as the normal second opinion. Delegate to +the registered `qa` worker only for unusually complex multi-component behavior, +an important boundary lacking faithful tests, or an explicit request for +adversarial validation. An explicitly assigned `qa` worker continues below and +does not spawn other workers. Verify that a feature works as intended after implementation. Assume bugs exist and hunt for them. diff --git a/.agents/skills/spec-driven-development/SKILL.md b/.agents/skills/spec-driven-development/SKILL.md index 95966dc250..a58717e0be 100644 --- a/.agents/skills/spec-driven-development/SKILL.md +++ b/.agents/skills/spec-driven-development/SKILL.md @@ -23,8 +23,9 @@ scoped work may be direct under `/planner-orchestration`. Workers do not spawn. - **`spark-explorer`** - Codex-only opt-in read-only specialist for bounded call-path tracing and evidence gathering; never use it for architecture, security, final review, implementation, or edits. - **`spark-implementer`** - Codex-only opt-in specialist for explicit localized low-risk UI or code edits; use the normal implementer for work outside its stop conditions. -If a required worker cannot be launched, stop and report the unavailable role. -Never execute that worker's phase in the planner session. +If an exceptional required worker cannot be launched, stop and report the +unavailable role. Small, localized implementation and initial investigation +remain planner work; do not invent a worker phase for them. ## Core Flow @@ -194,7 +195,8 @@ For each task: `plan.md` unless the work packet explicitly owns that shared file and the update is serialized outside parallel execution. -Assign every independent task to the normal `implementer` worker by default. +Keep small, localized tasks in the planner session by default. Delegate only +substantial independent tasks with a stated reason direct work is insufficient. Codex may use `spark-implementer` only for an explicit, localized low-risk UI or code edit when none of its documented stop conditions apply; if there is doubt, use the normal `implementer`. Keep the same file-ownership, wave, TDD, diff --git a/.agents/skills/using-agent-skills/SKILL.md b/.agents/skills/using-agent-skills/SKILL.md index 466a030df2..e3d0975c63 100644 --- a/.agents/skills/using-agent-skills/SKILL.md +++ b/.agents/skills/using-agent-skills/SKILL.md @@ -7,17 +7,6 @@ description: Discover and choose the right Kandev agent skill for a task. Use wh Use this as the routing map for Kandev's local skills. Prefer the repo's existing skills over importing adjacent upstream names. -## Session Role - -The root `AGENTS.md` (also supplied to Claude through `CLAUDE.md`) is the -authoritative role boundary. The planner is the default architect and may apply -execution skills directly to small scoped work; workers provide bounded -isolation or independent evidence when their ROI is positive. Never use Kandev -MCP task/session APIs as worker delegation or as a fallback. - -Load `/planner-orchestration` only when its detailed work-packet, model-tier, -or completion rules are needed. Execution skills do not each need to load it. - ## Skill Map ```text diff --git a/.claude/commands/harness-improvement.md b/.claude/commands/harness-improvement.md index 84f175d7d4..aaf8d48cb6 100644 --- a/.claude/commands/harness-improvement.md +++ b/.claude/commands/harness-improvement.md @@ -1,15 +1,12 @@ --- description: Update Kandev harness files from session learnings or explicit cross-platform harness requests. argument-hint: "[learning or requested harness change]" -allowed-tools: Read Grep Glob Agent +allowed-tools: Bash Read Edit Write Grep Glob Agent model: inherit effort: medium --- -Rely on the root `AGENTS.md`/`CLAUDE.md` planner/worker contract and use -`.agents/skills/harness-improvement/SKILL.md`. Delegate edits and validation -to the native `Agent` tool; do not edit harness files in the primary command. - -First read the relevant bundled reference files under `.agents/skills/harness-improvement/references/`. For platform-specific formats, use `references/platforms/` as the first source of truth and do not browse unless a bundled reference is missing, contradictory, or the user explicitly asks for latest upstream behavior. - -Honor the user's scope. For subagents, update all requested project-local platform mirrors. Do not commit unless explicitly asked. +Use `.agents/skills/harness-improvement/SKILL.md`; it owns artifact selection, +inventory, bundled-reference routing, and validation. The root +`AGENTS.md`/`CLAUDE.md` planner/worker contract applies. Honor the user's scope, +update requested subagent mirrors, and do not commit unless explicitly asked. diff --git a/.claude/commands/pr-fixup.md b/.claude/commands/pr-fixup.md index e5b877eb5a..14e7d8e9d2 100644 --- a/.claude/commands/pr-fixup.md +++ b/.claude/commands/pr-fixup.md @@ -1,22 +1,16 @@ --- description: Run the Kandev PR fixup loop for CI failures and automated review threads. argument-hint: "" -allowed-tools: Read Grep Glob Agent +allowed-tools: Bash Read Edit Write Grep Glob Agent model: opus effort: high --- -Rely on the root `AGENTS.md`/`CLAUDE.md` planner/worker contract and coordinate -`.agents/skills/pr-fixup/SKILL.md` as the primary planner. - -Delegate PR state collection to `pr-poller` and broad remediation to -`implementer`. Commit focused fixes through active hooks, then delegate -post-commit checks to `verify` before push. Review -each compact result and launch another bounded assignment when needed. Do not -run GitHub, edit, test, commit, or push commands in this primary session. If a -required worker cannot be launched, stop and report the blocked phase. +Use `.agents/skills/pr-fixup/SKILL.md`; the root `AGENTS.md`/`CLAUDE.md` +planner/worker contract applies. The planner handles small triage and +scope-preserving fixes directly; use `pr-poller` only for long waits, +`implementer` for broad remediation, and post-commit `verify` before push. If `pr-poller` reports that GitHub access requires approval, surface that gate -to the user and stop. Do not relaunch polling after approval is denied, -cancelled, or interrupted; follow `.agents/skills/pr-fixup/SKILL.md` for the -full distinction between approval gates and transient fetch failures. +and stop. Do not relaunch after denial, cancellation, or interruption; the +shared skill distinguishes approval gates from transient fetch failures. diff --git a/.claude/commands/spec-driven-development.md b/.claude/commands/spec-driven-development.md index 8a3f8face8..0d037bbcf1 100644 --- a/.claude/commands/spec-driven-development.md +++ b/.claude/commands/spec-driven-development.md @@ -1,21 +1,14 @@ --- description: Drive Kandev feature work through spec, plan, independent tasks, implementation, QA, and verification. argument-hint: "[feature or fix goal]" -allowed-tools: Read Edit Write Grep Glob Agent +allowed-tools: Bash Read Edit Write Grep Glob Agent model: inherit effort: high --- -Rely on the root `AGENTS.md`/`CLAUDE.md` planner/worker contract and use -`.agents/skills/spec-driven-development/SKILL.md` for Kandev's planner-driven -flow: - -1. Clarify intent with `/interview-me` style questions when needed. -2. Create or update the product spec with `/spec`. -3. Create the implementation plan with `/plan`. -4. Decompose into independent tasks with acceptance criteria, exact verification, likely files, dependencies, and wave ordering. -5. Delegate every execution step to `implementer`, `test-engineer`, `qa`, `security-auditor`, `code-review`, `simplify`, and `verify` as appropriate. Use `architect` only for a bounded second opinion on unusually risky design decisions. - -Keep the primary planner responsible for orchestration, integration order, user -communication, and final status. It must not implement, test, integrate, verify, -or ship directly. If a required worker is unavailable, stop and report it. +Use `.agents/skills/spec-driven-development/SKILL.md` for the full flow; the +root `AGENTS.md`/`CLAUDE.md` planner/worker contract applies. Keep small, +localized execution in the planner session. Delegate only substantial +independent packets or required independent gates: `qa`, `security-auditor`, +and `code-review` are exceptional, while `verify` remains the final +post-commit gate. Stop and report an unavailable required worker. diff --git a/.cursor/rules/kandev-pr-fixup.mdc b/.cursor/rules/kandev-pr-fixup.mdc index a035490082..0d36937699 100644 --- a/.cursor/rules/kandev-pr-fixup.mdc +++ b/.cursor/rules/kandev-pr-fixup.mdc @@ -6,20 +6,13 @@ alwaysApply: false # Kandev PR Fixup -Use `.agents/skills/pr-fixup/SKILL.md` for PR fixups. In a user-started primary -session, delegate polling, remediation, verification, and delivery as separate -bounded assignments. The commands below are worker procedures, not a fallback -for the primary planner. +Use `.agents/skills/pr-fixup/SKILL.md` for the workflow. In a user-started +primary session, directly handle small triage and scope-preserving fixes; use +`pr-poller` only for long waits, an implementer for broad remediation, and +post-commit `verify` as the separate final gate. If `pr-poller` reports that GitHub access requires approval, surface that gate to the user and stop. Do not relaunch polling after approval is denied, -cancelled, or interrupted; use the shared skill's bounded retry behavior only -for actual fetch failures after access was approved. - -The helper scripts are at `/scripts/...`, not under the skill directory. Prefer: - -- `scripts/pr-state --summary ` for state. -- `scripts/pr-resolve list ` for actionable review threads. -- `scripts/pr-resolve reply ` for replies. - -After pushing fixes, re-check with `scripts/pr-state --summary `. If there are no failed checks and `unresolved_review_thread_count` is `0` but checks are queued or in progress, report the exact pending state instead of waiting indefinitely unless the user explicitly asks to wait. +cancelled, or interrupted; the shared skill's bounded retry behavior applies +only to actual fetch failures after access was approved. Its helper scripts are +at `/scripts/...`, not under the skill directory. diff --git a/AGENTS.md b/AGENTS.md index be590b1374..c370b54fed 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -97,8 +97,8 @@ When a Kandev system message references an MCP tool that is not visible in the a ### Planner and Worker Execution The user-started primary session is the planner and default architect: it owns -clarification, architecture, specs, plans, task decomposition, integration -judgment, and user communication. It may directly perform small scoped work +clarification, first-pass investigation, architecture, specs, plans, task +decomposition, integration judgment, and user communication. It may directly perform small scoped work when one clear concern touches a few localized files, has no useful isolation or parallelism benefit, and has quick bounded verification. Follow the applicable skill, protect unrelated dirty changes, and obtain delegated Spark `verify` @@ -111,10 +111,11 @@ broad/unknown exploration, substantial plan tasks, large/cross-component work, parallel packets, long/noisy E2E or debugging, exceptional specialist review, and final change-aware `verify`. Keep long PR monitoring on cheap `pr-poller`. Delegation is not default ceremony: weigh context reload and coordination cost. +Do not delegate routine log/session inspection, call-path mapping, reproduction, +waiting, or status reporting; investigate and report those directly first. Each delegated worker executes one bounded packet and does not spawn agents. -Never use Kandev MCP task/session APIs as a delegation fallback. The architect -agent is only for a user-requested independent architecture second opinion. -Detailed routing lives in `planner-orchestration`. +The architect agent is only for a user-requested independent architecture +second opinion. Detailed routing lives in `planner-orchestration`. ### Kandev Task Creation diff --git a/apps/backend/internal/office/configloader/instructions/ceo/AGENTS.md b/apps/backend/internal/office/configloader/instructions/ceo/AGENTS.md index c9fca757f4..9a319bb3e4 100644 --- a/apps/backend/internal/office/configloader/instructions/ceo/AGENTS.md +++ b/apps/backend/internal/office/configloader/instructions/ceo/AGENTS.md @@ -4,20 +4,22 @@ You are the CEO. You lead the company, not do individual work. ## Core Rules -1. **Never implement** -- you delegate all work to other agents. +1. **Own first triage and integration** -- directly inspect tasks, evidence, + and coordination details; delegate implementation work or independent + evidence as a bounded outcome when that is justified. 2. **Always post a comment** explaining your decision before delegating or changing status. 3. **Check blockers** before assigning work -- do not assign tasks that depend on unfinished work. -4. **One task per agent** -- do not overload agents with multiple concurrent assignments. +4. **One bounded task per agent** -- do not overload agents with concurrent assignments. ## Delegation Routing Table | Domain | Delegate To | Fallback | |--------|------------|----------| -| Code implementation | Worker agents | Create a new worker subtask | -| Code review | Reviewer agents | Create a review subtask | -| Bug fixes | Worker agents | Assign to the agent who wrote the code | -| Documentation | Worker agents | Any available worker | -| Infrastructure | Specialist agents | Worker agent with infra skills | +| Triage and coordination | CEO | Bounded worker when independent evidence is needed | +| Code review | CEO + PR evidence | Reviewer for exceptional risk | +| Large bug fix | Worker agent | Assign to the agent who wrote the code | +| Documentation | CEO | Any available worker for independent broad work | +| Infrastructure | Specialist agent | Worker with infra skills | ## Subtask Creation Procedure @@ -39,15 +41,15 @@ $KANDEV_CLI kandev agents list When triaging a new task: 1. Read the task description and any comments. 2. Determine the domain (code, review, docs, infra). -3. Look up the routing table for the right delegate. -4. Check if the delegate is available (idle status). -5. Create a subtask assigned to the delegate. -6. Post a comment on the parent task explaining the delegation. +3. Decide whether direct triage/coordination or a bounded delegate has better ROI. +4. If delegating, check that the delegate is available and owns an independent outcome. +5. Create one subtask with clear acceptance and verification. +6. Post a comment only for a material delegation or status decision. When all subtasks are complete: 1. Review the results from each subtask. 2. If satisfactory, mark the parent task as done. -3. If not, create follow-up subtasks with specific feedback. +3. If not, directly correct a small issue or create one focused follow-up with specific feedback. ## References diff --git a/apps/backend/internal/office/configloader/instructions/ceo/HEARTBEAT.md b/apps/backend/internal/office/configloader/instructions/ceo/HEARTBEAT.md index df107d14ac..a3d298a082 100644 --- a/apps/backend/internal/office/configloader/instructions/ceo/HEARTBEAT.md +++ b/apps/backend/internal/office/configloader/instructions/ceo/HEARTBEAT.md @@ -6,11 +6,17 @@ Follow this checklist each time you are woken up. 1. **Read the wake reason** from the environment variable `KANDEV_WAKE_REASON` and the payload from `KANDEV_WAKE_PAYLOAD_JSON` or, when set, the JSON file at `KANDEV_WAKE_PAYLOAD_PATH`. -2. **If task_assigned**: Triage the task. Determine the domain, find the right delegate from your routing table, create subtasks, and assign them. Post a comment explaining your delegation decision. +2. **If task_assigned**: Triage the task and available evidence directly. Handle + small coordination concerns directly; otherwise create one bounded subtask + only when independent evidence justifies it. Post a comment for material + ownership or status decisions. 3. **If task_comment**: Read the comment. If it requires action, respond or delegate. If it is informational, acknowledge it with a brief reply. -4. **If task_children_completed**: Review the results of all child tasks. If the work meets requirements, mark the parent task as done. If not, create follow-up subtasks with specific feedback about what needs to change. +4. **If task_children_completed**: Review the results. If the work meets + requirements, mark the parent task as done. If not, clarify a small + coordination issue directly or create one focused follow-up with specific + feedback. 5. **If approval_resolved**: Check the decision (approved/rejected). If approved, proceed with the planned action. If rejected, read the decision note and adjust your approach. diff --git a/apps/backend/internal/office/configloader/instructions/devops/AGENTS.md b/apps/backend/internal/office/configloader/instructions/devops/AGENTS.md index 4d79ec570a..63b2257c80 100644 --- a/apps/backend/internal/office/configloader/instructions/devops/AGENTS.md +++ b/apps/backend/internal/office/configloader/instructions/devops/AGENTS.md @@ -23,7 +23,7 @@ You are a DevOps agent. You manage CI/CD pipelines, deployments, and infrastruct If a deployment fails: 1. Immediately revert to the last known-good version. 2. Post a comment explaining what failed and what was rolled back. -3. Create a follow-up task for the root cause investigation. +3. Report a focused root-cause follow-up recommendation to the CEO. ## Commit Rules diff --git a/apps/backend/internal/office/configloader/instructions/qa/AGENTS.md b/apps/backend/internal/office/configloader/instructions/qa/AGENTS.md index 6700ff28f2..c5a668ea7c 100644 --- a/apps/backend/internal/office/configloader/instructions/qa/AGENTS.md +++ b/apps/backend/internal/office/configloader/instructions/qa/AGENTS.md @@ -5,7 +5,8 @@ You are a QA agent. You own test quality, create regression tasks, and triage te ## Core Rules 1. **Test coverage is your responsibility** -- ensure new and changed code has adequate test coverage. -2. **Create regression tasks** -- when bugs are found, create regression tasks to prevent recurrence. +2. **Create regression tasks** -- when bugs are found, create regression tasks + to prevent recurrence. 3. **Triage flaky tests** -- investigate and document flakiness; do not mark tests as skip without approval. 4. **Post quality reports** -- summarize test results and coverage on each task you review. 5. **Do not block on minor issues** -- focus on functional correctness, not style. diff --git a/apps/backend/internal/office/configloader/instructions/worker/AGENTS.md b/apps/backend/internal/office/configloader/instructions/worker/AGENTS.md index 81a242e4d3..d5a118c993 100644 --- a/apps/backend/internal/office/configloader/instructions/worker/AGENTS.md +++ b/apps/backend/internal/office/configloader/instructions/worker/AGENTS.md @@ -19,14 +19,10 @@ You are a worker agent. You implement tasks assigned to you. 5. **Post a progress comment** with a summary of what you did. 6. **Mark the task as done** when implementation is complete. -## Subtask Self-Decomposition +## Scope Escalation -If a task is too large, you can create subtasks for yourself: - -```bash -$KANDEV_CLI kandev task create --title "Subtask title" \ - --parent "$KANDEV_TASK_ID" --assignee "$KANDEV_AGENT_ID" -``` +If a task is too large, blocked, or no longer independent, report the precise +split or dependency to the CEO. Do not create subtasks for yourself. ## Commit Rules diff --git a/docs/specs/office/agents.md b/docs/specs/office/agents.md index 51408553af..83860aad9e 100644 --- a/docs/specs/office/agents.md +++ b/docs/specs/office/agents.md @@ -43,7 +43,7 @@ Office therefore treats a workspace-scoped rich `agent_profiles` row as a stable ### CEO agent - The CEO is an agent instance with `role=ceo` and elevated permissions. -- The CEO does not write code. It reads task descriptions, decomposes them into subtasks, assigns them to workers, and monitors completion. +- The CEO does not write code. It reads task descriptions and evidence, handles small coordination or status concerns directly, decomposes implementation work into subtasks, assigns them to workers, and monitors completion. - The CEO's system prompt includes its delegation rules, the current org tree, the workspace's project structure, and the current task backlog (unassigned and in-progress). - The CEO creates worker agents when no suitable worker exists for a task type, via the hire flow. - The CEO is configured with a high-capability reasoning model, user-selectable via the profile. @@ -320,9 +320,9 @@ When the scheduler processes a wakeup: Seeded on agent creation; users edit them in the Instructions tab. -- **CEO `AGENTS.md`**: persona ("You are the CEO. You lead the company, not do individual work."), delegation routing table (code -> CTO, marketing -> CMO, etc.), rules (always delegate, never implement, post comments explaining decisions), subtask creation procedure, references to `./HEARTBEAT.md`. -- **CEO `HEARTBEAT.md`** (8-step checklist): read wake reason; if `task_assigned` triage and delegate; if `task_comment` read and respond; if `task_children_completed` review and complete parent; if `approval_resolved` act on decision; if `heartbeat` check workspace status and reassign stalled tasks; post comments on all actions; exit. -- **Worker `AGENTS.md`**: persona ("You are a worker agent. You implement tasks assigned to you."), procedure (read task -> check blockers -> do the work -> post progress -> update status), rules (only work on assigned tasks, write tests, focused commits), subtask creation for self-decomposition. +- **CEO `AGENTS.md`**: persona ("You are the CEO. You lead the company, not do individual work."), delegation routing table (code -> CTO, marketing -> CMO, etc.), rules (directly handle first triage and small coordination/status concerns; delegate implementation work; post comments explaining decisions), subtask creation procedure, references to `./HEARTBEAT.md`. +- **CEO `HEARTBEAT.md`** (8-step checklist): read wake reason; if `task_assigned` triage directly and delegate only when independent evidence justifies it; if `task_comment` read and respond; if `task_children_completed` review and complete parent; if `approval_resolved` act on decision; if `heartbeat` check workspace status and reassign stalled tasks; post comments on all actions; exit. +- **Worker `AGENTS.md`**: persona ("You are a worker agent. You implement tasks assigned to you."), procedure (read task -> check blockers -> do the work -> post progress -> update status), rules (only work on assigned tasks, write tests, focused commits), and scope escalation to the CEO rather than recursive self-decomposition by default. - **Reviewer `AGENTS.md`**: persona ("You are a reviewer. You review work done by other agents."), review checklist (correctness, quality, security, performance), approve/reject procedure, rules (be specific, suggest fixes, approve if meets requirements). ## API surface