[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M6X4DHMJB0W0HZDV1EXEWH5F":3,"skill-same:01M6X4DHMJB0W0HZDV1EXEWH5F":90},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":28,"publishedAt":49,"linkOnly":50,"markdownContent":51,"markdownBody":52,"frontMatter":53,"refName":63,"commitSha":64,"skillDirectory":65,"forksCount":14,"repositoryHtmlUrl":66,"repositoryHomepageUrl":67,"ownerHtmlUrl":68,"ownerBlogUrl":6,"ownerDescription":6,"updatedAt":69,"install":70,"resources":83},"01M6X4DHMJB0W0HZDV1EXEWH5F","agent-management",null,"Multi-agent workflow coordination — task decomposition, role assignment, context sharing, handoff protocols, quality gates, and per-session context budgeting. Use when orchestrating multiple AI agents on a shared task, designing an agent pipeline, defining handoff protocols, or planning how a session should load context within a budget.","projectious-work\u002Fprocesskit","projectious-work","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F263889726?v=4","01M6N97TJJ118WQ35CHRV8RD0E","projectious.work","01M6N97TPWJPF0BMKYQ4PBY5W8",0,"MIT","https:\u002F\u002Fgithub.com\u002Fprojectious-work\u002Fprocesskit\u002Fblob\u002Fmain\u002Farchive\u002Fprocesskit-install-20261101\u002Fcontext\u002Ftemplates\u002Fprocesskit\u002Fv0.8.0\u002Fcontext\u002Fskills\u002Fagent-management\u002FSKILL.md",[18,23],{"categoryNo":19,"categoryName":20,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000023","Skill与智能体开发","SCENARIO","使用场景",{"categoryNo":24,"categoryName":25,"taxonomyType":26,"taxonomyTypeDesc":27},"01JBSEEDCAT000000000000040","财务","PROFESSION","适用职业",[29,30,31,32,33,34,35,36,37,38,39,40,41,42,43,44,45,46,47,48],"agent management","management","context","task decomposition","when","agent pipeline","context budgeting","role assignment","decomposition","shared","budgeting","handoff","work","multi-agent","coordination","how","Budget","pipeline","workflow","ai agents","2026-11-10 10:12:30",false,"---\nname: agent-management\ndescription: |\n  Multi-agent workflow coordination — task decomposition, role assignment, context sharing, handoff protocols, quality gates, and per-session context budgeting. Use when orchestrating multiple AI agents on a shared task, designing an agent pipeline, defining handoff protocols, or planning how a session should load context within a budget.\nmetadata:\n  processkit:\n    apiVersion: processkit.projectious.work\u002Fv1\n    id: SKILL-agent-management\n    version: \"1.1.0\"\n    created: 2026-04-06T00:00:00Z\n    category: process\n    layer: 4\n---\n\n# Agent Management\n\n## Intro\n\nMulti-agent workflows are decomposed tasks with explicit roles,\nstructured handoffs, and quality gates between stages. The agent\nalso has to manage its own session — loading context lazily\nagainst a declared budget rather than slurping everything at start.\n\n## Overview\n\n### Task decomposition\n\nBreak work into agent-sized units. Each subtask must have:\n\n1. **Clear scope** — one well-defined outcome, not \"do everything\"\n2. **Input specification** — exactly what files, context, or\n   prior outputs the agent needs\n3. **Output specification** — what artifact the agent produces\n   (file, diff, structured answer)\n4. **Success criteria** — how to verify the subtask is correct\n5. **Estimated complexity** — small (single file), medium\n   (module), large (cross-cutting)\n\nRules of thumb:\n\n- If a subtask requires more than 3 files of context, split it.\n- If a subtask has no verifiable output, redefine it.\n- Prefer depth-first (finish one subtask fully) over breadth-first\n  (start many in parallel).\n\n### Agent role definitions\n\nAssign roles based on the task, not on agent identity:\n\n| Role | Responsibility | Input | Output |\n|---|---|---|---|\n| **Planner** | Decomposes the task, defines order and dependencies | User request, codebase overview | Task plan with ordered subtasks |\n| **Researcher** | Gathers information, reads code, finds patterns | Specific questions, file paths | Structured findings with citations |\n| **Coder** | Implements changes, writes code | Task spec, relevant files, findings | Code changes (diff or files) |\n| **Reviewer** | Validates correctness, style, completeness | Code changes, task spec, success criteria | Approval or rejection with reasons |\n\nA single agent can fill multiple roles sequentially (plan, then\ncode, then self-review). Never skip the reviewer role — even\nself-review catches errors. The planner role is mandatory for\ntasks touching more than 2 files.\n\n### Context sharing\n\nAgents lose context between sessions. Use explicit transfer:\n\n- **File-based (preferred for Claude Code)** — write findings to\n  a scratch file (e.g. `_agent_notes.md`) that the next agent\n  reads. Use structured formats: headings, bullets, file paths\n  with line numbers. Delete scratch files when the workflow ends.\n- **Structured handoff messages** — summarize what was done,\n  what remains, and what blockers exist. Include exact paths and\n  line numbers. List assumptions and decisions.\n- **Shared memory (project files)** — use `DECISIONS.md` or\n  `HANDOVER.md` for persistent cross-session context. Keep\n  entries timestamped and concise. Reference specific commits.\n\n### Handoff protocol\n\nEvery handoff between roles must include:\n\n1. **Status** — what is complete and what is not\n2. **Artifacts** — list of files created or modified, with paths\n3. **Verification** — what was checked and how (tests run, lint,\n   manual review)\n4. **Blockers** — anything preventing the next step\n5. **Next action** — explicit instruction for the receiving agent\n\nFormat:\n\n```\n## Handoff: [Role] -> [Role]\n**Status:** [complete | partial | blocked]\n**Changes:** [list of file paths]\n**Verified:** [tests passed | linted | reviewed]\n**Blockers:** [none | description]\n**Next:** [specific instruction]\n```\n\n### Quality gates\n\nInsert verification checkpoints between stages:\n\n- **After planning** — does the plan cover all requirements? Are\n  subtasks independent?\n- **After research** — are findings specific (paths, line numbers)\n  not vague?\n- **After coding** — do tests pass? Linter clean? Does the change\n  match the spec?\n- **After review** — are all must-fix items addressed? Reviewer\n  satisfied?\n\nA quality gate fails the workflow forward — do not proceed until\nthe gate passes. If a gate fails twice on the same issue,\nescalate to the user.\n\n### Error recovery and fallbacks\n\nWhen an agent step fails:\n\n1. **Capture the failure** — save error output, not just \"it\n   failed\"\n2. **Diagnose** — context issue (missing info), capability issue\n   (wrong approach), or environment issue (tool error)?\n3. **Retry with adjustment** — provide missing context, try a\n   different approach, or fix the environment\n4. **Escalate** — if two retries fail, stop and report to the\n   user with full context\n\nFallbacks:\n\n- Coder stuck → switch to researcher role to gather more context\n- Review finds fundamental issues → return to planner to re-scope\n- Context too large → split the task into smaller independent\n  pieces\n\n### Progress tracking\n\nFor multi-step workflows, maintain a checklist that doubles as\nhandoff context:\n\n```\n## Agent Workflow: [Task Name]\n- [x] Plan: decomposed into N subtasks\n- [x] Research: gathered context for subtask 1\n- [ ] Code: implement subtask 1\n- [ ] Review: verify subtask 1\n- [ ] Code: implement subtask 2\n...\n```\n\nUpdate the checklist after each step.\n\n### Encode corrections immediately\n\nWhen the user corrects agent behavior mid-session, encode the\ncorrection before continuing:\n\n1. **Classify** — what kind of failure was it? (deferred action,\n   wrong tool, skipped step, scope creep, …)\n2. **Check** — does a skill or AGENTS.md already cover this failure\n   mode? Search the relevant skill's Gotchas and Anti-patterns.\n3. **Encode** — if not covered: edit the relevant file in the same\n   turn. A correction that is only remembered is lost at session end.\n4. **Log** — add a one-liner to `behavioral_retrospective` in the\n   session handover so the session record reflects what was learned.\n\nThe same rule applies as for entity creation: do it in the same turn,\nnot later.\n\n### Context budget and lazy loading\n\nprocesskit projects can grow to dozens of skills, hundreds of\nworkitems, and many years of decision history. Loading all of\nthis every session is wasteful — most files have no relevance\nto the current request. The agent must load context\n**selectively**.\n\n#### Read INDEX files first, not full directories\n\nEvery directory under `context\u002F` should have an `INDEX.md`\n(Level 0 per the three-level principle). At session start, the\nagent reads:\n\n1. `AGENTS.md` (root) — the canonical agent entry point\n2. `context\u002FHANDOVER.md` — current state and recent changes\n3. `context\u002Fowner\u002Fidentity.md` and `context\u002Fowner\u002Fworking-style.md`\n   (the highest-leverage owner files, if the project uses\n   owner-profiling)\n4. `context\u002FINDEX.md` and any `context\u002F*\u002FINDEX.md` files\n5. `context\u002Fmigrations\u002FINDEX.md` (always loaded — the migration\n   state summary)\n\nProvider-specific harness files (e.g. `CLAUDE.md`, `CODEX.md`)\nare thin pointers to `AGENTS.md` and do not need to be in the\nalways-load set.\n\nThese files are short, dense, and tell the agent what exists.\nThe agent does NOT slurp `context\u002Fskills\u002F`, `context\u002Fworkitems\u002F`,\netc. on session start.\n\n#### Use the index MCP server, not filesystem walks\n\nThe `index-management` MCP server is the right way to discover\nentities. Instead of `ls context\u002Fskills\u002F`, the agent calls\n`query_entities(kind=\"Skill\", category=\"process\")` and gets back\na list of just the skills that match. Same for workitems,\ndecisions, bindings, events. Filesystem walking is the slow,\ncontext-expensive fallback.\n\n#### Load skills on demand, not upfront\n\nWhen the agent needs a specific skill (e.g. `code-review`), it\nreads `context\u002Fskills\u002Fcode-review\u002FSKILL.md` at that moment — not\nat session start. If the SKILL.md references a deeper file\n(`references\u002F...`), only read that when the agent's task actually\nneeds it. This is the three-level principle in action: start at\nLevel 1, drop to Level 2 when the request is more specific, drop\nto Level 3 only for edge cases.\n\n## Gotchas\n\nAgent-specific failure modes — provider-neutral pause-and-self-check items:\n\n- **Context overload — passing the entire codebase or conversation to every agent.** Each agent should receive only the files and context it needs for its specific subtask. Passing everything to every agent balloons token usage, produces vague responses, and hits context limits. Reference specific file paths and line ranges in handoffs rather than dumping full file contents.\n- **Circular delegation with no forward progress.** Agent A asks Agent B for help, which asks Agent A. The hallmark is growing context with repeated handoffs and no new artifacts. Enforce a strict pipeline direction: every handoff moves the task forward. If an agent cannot proceed, escalate to the user with full context — not back to the previous agent.\n- **Premature fan-out before confirming task independence.** Starting parallel agents before the planner has verified that subtasks touch different files and modules leads to merge conflicts and duplicated work. Always run a planning stage first and confirm independence; limit fan-out to 3-4 parallel subtasks.\n- **Skipping the reviewer role because the coder \"did a good job.\"** Self-confidence bias is highest immediately after writing code. The reviewer role exists precisely because authors miss their own errors. Even a self-review pass — running tests, linting, reading the diff against the spec — catches errors that accumulate into bugs when skipped.\n- **Vague handoffs without specific artifacts, paths, or line numbers.** \"I made some changes, please review\" tells the receiving agent almost nothing. Use the structured handoff format every time: status, list of file paths changed, what was verified, any blockers, and the exact next action. Include absolute paths and line numbers for all referenced code.\n- **Loading all context at session start instead of selectively.** A project with 100 skills, 5 years of decisions, and hundreds of backlog items contains far more context than any session needs. Read INDEX files to understand what exists, then load on demand when the specific task requires it. The three-level principle applies: start at the overview, drill down only when needed.\n- **Leaving scratch files (`_agent_notes.md`, `_blackboard.md`) in the repository.** Temporary agent collaboration files are not part of the project's permanent record. Every multi-agent workflow that creates scratch files must clean them up when the workflow completes. Committed scratch files confuse future agents and humans about what is authoritative context.\n- **Skipping the skill catalog for domain tasks.** Before starting\n  any domain-specific task (writing a PRD, drafting a release,\n  creating a schema), search for a matching processkit skill via\n  `search_entities` or `skill-finder`. Proceeding from general\n  knowledge when a skill exists produces output that misses\n  processkit-specific conventions and entity storage paths.\n\n## Full reference\n\n### Worked examples\n\n**\"Add authentication to this API — use multiple agents to plan,\nimplement, and review.\"** (1) Researcher reads existing route\nhandlers and middleware patterns, writes findings to\n`_auth_notes.md`. (2) Coder implements auth middleware, JWT\nvalidation, and protected route decorators based on findings.\n(3) Reviewer checks against OWASP guidelines, verifies tests\npass, confirms no hardcoded secrets. Each handoff includes the\nstructured handoff block.\n\n**\"Set up a code review pipeline for incoming changes.\"** A\nthree-stage pipeline: (1) Researcher reads the diff and gathers\ncontext about affected modules. (2) Reviewer evaluates\ncorrectness, security, performance, style using the code-review\nchecklist. (3) Planner summarizes findings into must-fix,\nshould-fix, and nit categories with line references. Quality\ngate: all must-fix items require a re-review cycle before\napproval.\n\n**\"Research the best caching strategy, then implement it.\"**\nResearch-then-implement workflow: (1) Researcher examines current\ndata access patterns, identifies hot paths, checks existing\ncaching, writes structured findings with measured or estimated\nlatencies. (2) Planner reviews findings and selects an approach,\ndocumenting the decision. (3) Coder implements the cache layer\nfollowing the plan. (4) Reviewer verifies cache invalidation,\nchecks for stale data risks, confirms tests cover hit\u002Fmiss\npaths. Handoff between research and planning includes specific\nfile paths and quantified findings.\n\n### Coordination patterns\n\nSee `references\u002Fcoordination-patterns.md` for the full pattern\ncatalog. Summary:\n\n- **Pipeline** — agents execute sequentially\n  (Researcher → Planner → Coder → Reviewer). Default choice;\n  simplest, lowest risk.\n- **Fan-out \u002F Fan-in** — planner decomposes into independent\n  subtasks, multiple agents run in parallel, a coordinator merges\n  results. Use only when the planner confirms subtasks are\n  independent (different files, different modules). Limit to 3-4\n  parallel subtasks.\n- **Supervisor** — one agent monitors and directs others,\n  reassigning work as findings shift the plan. Use for large\n  refactors and exploratory tasks where the path is unclear\n  upfront.\n- **Consensus** — multiple agents independently solve the same\n  problem; an evaluator selects or merges. Expensive — reserve\n  for high-stakes decisions (architecture, security review).\n- **Blackboard** — agents share a common workspace file, picking\n  up work items and posting results. Use section-based ownership\n  to prevent overwrites.\n\n### Pattern decision matrix\n\n| Characteristic | Pipeline | Fan-Out | Supervisor | Consensus | Blackboard |\n|---|---|---|---|---|---|\n| Sequential dependencies | Yes | No | Partial | No | Partial |\n| Independent subtasks | No | Yes | Yes | Yes | Yes |\n| Uncertain requirements | No | No | Yes | Partial | Partial |\n| Multiple valid solutions | No | No | No | Yes | No |\n| Shared evolving state | No | No | No | No | Yes |\n| Low token budget | Yes | No | Yes | No | Yes |\n| High-stakes decision | No | No | Partial | Yes | No |\n\nDefault to Pipeline. Escalate to Supervisor if scope shifts\nduring execution. Use Fan-Out only when subtasks are provably\nindependent. Reserve Consensus for decisions with significant\nlong-term impact.\n\n### Anti-patterns\n\n- **Context overload** — passing the entire codebase or\n  conversation history to every agent. Symptom: vague responses,\n  token limits hit. Fix: give each agent only the files it needs\n  for its specific subtask; use file paths and line ranges, not\n  full file contents, in handoffs.\n- **Circular delegation** — Agent A asks Agent B, which asks\n  Agent A. Symptom: no progress, repeated handoffs, growing\n  context with no new artifacts. Fix: enforce a strict pipeline\n  direction. Every handoff moves the task forward; if an agent\n  cannot proceed, escalate to the user, not back to the previous\n  agent.\n- **No verification** — skipping review because \"the coder is\n  good enough.\" Fix: always include a review gate. At minimum,\n  run tests, run lint, check the output against the spec.\n- **Premature parallelism** — fan-out before understanding\n  dependencies, causing merge conflicts or duplicated work. Fix:\n  always run a planning stage first.\n- **Vague handoffs** — \"I made some changes, please review\"\n  without specifics. Fix: use the structured handoff format\n  every time.\n- **Deferred entity creation** — saying \"I'll track that\" or\n  \"I'll file a workitem\" without immediately calling the tool.\n  Deferred commitments are routinely dropped across turn\n  boundaries, leaving the entity layer out of sync with what\n  was agreed. Fix: call `create_workitem`, `record_decision`,\n  or the relevant MCP tool in the same turn as the commitment.\n- **Skipping the skill catalog for domain tasks.** When a\n  domain-specific task arrives (writing a PRD, creating a\n  release, reviewing a skill), the agent goes to general\n  knowledge instead of checking `skill-finder` or\n  `search_entities`. The skill catalog exists precisely because\n  processkit has conventions (entity storage paths, output\n  formats, workitem linking) that general knowledge does not\n  know. Fix: run `search_entities(text=\"\u003Ctask keyword>\")` or\n  consult `skill-finder` before starting any domain task.\n\n### Practical tips for Claude Code\n\n1. **One agent session = one role at a time.** Switch roles\n   explicitly (\"Now acting as Reviewer\").\n2. **Use files for context, not memory.** Write `_handoff.md` or\n   `_findings.md`; read them in the next step.\n3. **Keep scratch files temporary.** Clean up `_agent_notes.md`,\n   `_blackboard.md` after the workflow completes.\n4. **Verify with tools, not judgment.** Run `cargo test`,\n   `npm test`, or the appropriate linter rather than \"I think\n   this looks right.\"\n5. **Time-box research.** Researchers answer specific questions,\n   not \"tell me everything about X.\"\n6. **Limit fan-out to 3-4 parallel subtasks.** More than that and\n   coordination overhead exceeds the benefit.\n7. **Always include file paths.** Every handoff and finding\n   should reference absolute paths and line numbers.\n\n### Respect the configured context budget\n\nProjects can declare a budget in their processkit configuration\nfile (the location depends on how processkit was installed — for\nexample `aibox.toml` if the project uses aibox, or a standalone\n`processkit.toml` for unmanaged installs):\n\n```toml\n[context.budget]\ntarget_tokens = 8000          # aim NOT to exceed this on initial load\nmax_tokens = 16000            # hard ceiling — must use lazy loading above this\n\n[context.budget.always_load]\nfiles = [\n  \"AGENTS.md\",\n  \"context\u002FHANDOVER.md\",\n  \"context\u002Fowner\u002Fidentity.md\",\n  \"context\u002Fowner\u002Fworking-style.md\",\n  \"context\u002FINDEX.md\",\n  \"context\u002Fmigrations\u002FINDEX.md\",\n]\n\n[context.budget.on_demand]\npatterns = [\n  \"context\u002Fskills\u002F**\",\n  \"context\u002Fworkitems\u002F**\",\n  \"context\u002Flogs\u002F**\",\n  \"context\u002Fdecisions\u002F**\",\n]\n```\n\nThe agent reads `[context.budget]` at session start (it's part\nof the `always_load` set if not overridden) and follows the rules:\n\n- `always_load.files` are loaded into the first turn\n  unconditionally\n- `on_demand.patterns` are loaded only when needed, via the index\n  MCP server or direct file reads\n- The agent estimates the total token count of `always_load` and\n  warns the user if it exceeds `target_tokens`\n\nThe values are advisory — there is no runtime enforcement. The\nagent honors them as instructions.\n\n### When context is still too big\n\nIf even the always-load set is too large, the agent should:\n\n1. Surface this to the user: \"Loading 24k tokens of context,\n   target is 8k. Want me to run `context-grooming`?\"\n2. Suggest specific candidates for archival or summarization\n   based on the `context-grooming` ruleset\n3. Offer to update the `[context.budget]` config to a higher\n   target if the project genuinely needs more\n4. Never silently truncate or drop files\n\n### Relationship to context-grooming\n\n`agent-management` says HOW to load context efficiently per\nsession. `context-grooming` runs periodically to make the corpus\nsmaller. Both work together: grooming reduces the live size;\nlazy loading reduces what gets loaded from that smaller corpus.\n","# Agent Management\n\n## Intro\n\nMulti-agent workflows are decomposed tasks with explicit roles,\nstructured handoffs, and quality gates between stages. The agent\nalso has to manage its own session — loading context lazily\nagainst a declared budget rather than slurping everything at start.\n\n## Overview\n\n### Task decomposition\n\nBreak work into agent-sized units. Each subtask must have:\n\n1. **Clear scope** — one well-defined outcome, not \"do everything\"\n2. **Input specification** — exactly what files, context, or\n   prior outputs the agent needs\n3. **Output specification** — what artifact the agent produces\n   (file, diff, structured answer)\n4. **Success criteria** — how to verify the subtask is correct\n5. **Estimated complexity** — small (single file), medium\n   (module), large (cross-cutting)\n\nRules of thumb:\n\n- If a subtask requires more than 3 files of context, split it.\n- If a subtask has no verifiable output, redefine it.\n- Prefer depth-first (finish one subtask fully) over breadth-first\n  (start many in parallel).\n\n### Agent role definitions\n\nAssign roles based on the task, not on agent identity:\n\n| Role | Responsibility | Input | Output |\n|---|---|---|---|\n| **Planner** | Decomposes the task, defines order and dependencies | User request, codebase overview | Task plan with ordered subtasks |\n| **Researcher** | Gathers information, reads code, finds patterns | Specific questions, file paths | Structured findings with citations |\n| **Coder** | Implements changes, writes code | Task spec, relevant files, findings | Code changes (diff or files) |\n| **Reviewer** | Validates correctness, style, completeness | Code changes, task spec, success criteria | Approval or rejection with reasons |\n\nA single agent can fill multiple roles sequentially (plan, then\ncode, then self-review). Never skip the reviewer role — even\nself-review catches errors. The planner role is mandatory for\ntasks touching more than 2 files.\n\n### Context sharing\n\nAgents lose context between sessions. Use explicit transfer:\n\n- **File-based (preferred for Claude Code)** — write findings to\n  a scratch file (e.g. `_agent_notes.md`) that the next agent\n  reads. Use structured formats: headings, bullets, file paths\n  with line numbers. Delete scratch files when the workflow ends.\n- **Structured handoff messages** — summarize what was done,\n  what remains, and what blockers exist. Include exact paths and\n  line numbers. List assumptions and decisions.\n- **Shared memory (project files)** — use `DECISIONS.md` or\n  `HANDOVER.md` for persistent cross-session context. Keep\n  entries timestamped and concise. Reference specific commits.\n\n### Handoff protocol\n\nEvery handoff between roles must include:\n\n1. **Status** — what is complete and what is not\n2. **Artifacts** — list of files created or modified, with paths\n3. **Verification** — what was checked and how (tests run, lint,\n   manual review)\n4. **Blockers** — anything preventing the next step\n5. **Next action** — explicit instruction for the receiving agent\n\nFormat:\n\n```\n## Handoff: [Role] -> [Role]\n**Status:** [complete | partial | blocked]\n**Changes:** [list of file paths]\n**Verified:** [tests passed | linted | reviewed]\n**Blockers:** [none | description]\n**Next:** [specific instruction]\n```\n\n### Quality gates\n\nInsert verification checkpoints between stages:\n\n- **After planning** — does the plan cover all requirements? Are\n  subtasks independent?\n- **After research** — are findings specific (paths, line numbers)\n  not vague?\n- **After coding** — do tests pass? Linter clean? Does the change\n  match the spec?\n- **After review** — are all must-fix items addressed? Reviewer\n  satisfied?\n\nA quality gate fails the workflow forward — do not proceed until\nthe gate passes. If a gate fails twice on the same issue,\nescalate to the user.\n\n### Error recovery and fallbacks\n\nWhen an agent step fails:\n\n1. **Capture the failure** — save error output, not just \"it\n   failed\"\n2. **Diagnose** — context issue (missing info), capability issue\n   (wrong approach), or environment issue (tool error)?\n3. **Retry with adjustment** — provide missing context, try a\n   different approach, or fix the environment\n4. **Escalate** — if two retries fail, stop and report to the\n   user with full context\n\nFallbacks:\n\n- Coder stuck → switch to researcher role to gather more context\n- Review finds fundamental issues → return to planner to re-scope\n- Context too large → split the task into smaller independent\n  pieces\n\n### Progress tracking\n\nFor multi-step workflows, maintain a checklist that doubles as\nhandoff context:\n\n```\n## Agent Workflow: [Task Name]\n- [x] Plan: decomposed into N subtasks\n- [x] Research: gathered context for subtask 1\n- [ ] Code: implement subtask 1\n- [ ] Review: verify subtask 1\n- [ ] Code: implement subtask 2\n...\n```\n\nUpdate the checklist after each step.\n\n### Encode corrections immediately\n\nWhen the user corrects agent behavior mid-session, encode the\ncorrection before continuing:\n\n1. **Classify** — what kind of failure was it? (deferred action,\n   wrong tool, skipped step, scope creep, …)\n2. **Check** — does a skill or AGENTS.md already cover this failure\n   mode? Search the relevant skill's Gotchas and Anti-patterns.\n3. **Encode** — if not covered: edit the relevant file in the same\n   turn. A correction that is only remembered is lost at session end.\n4. **Log** — add a one-liner to `behavioral_retrospective` in the\n   session handover so the session record reflects what was learned.\n\nThe same rule applies as for entity creation: do it in the same turn,\nnot later.\n\n### Context budget and lazy loading\n\nprocesskit projects can grow to dozens of skills, hundreds of\nworkitems, and many years of decision history. Loading all of\nthis every session is wasteful — most files have no relevance\nto the current request. The agent must load context\n**selectively**.\n\n#### Read INDEX files first, not full directories\n\nEvery directory under `context\u002F` should have an `INDEX.md`\n(Level 0 per the three-level principle). At session start, the\nagent reads:\n\n1. `AGENTS.md` (root) — the canonical agent entry point\n2. `context\u002FHANDOVER.md` — current state and recent changes\n3. `context\u002Fowner\u002Fidentity.md` and `context\u002Fowner\u002Fworking-style.md`\n   (the highest-leverage owner files, if the project uses\n   owner-profiling)\n4. `context\u002FINDEX.md` and any `context\u002F*\u002FINDEX.md` files\n5. `context\u002Fmigrations\u002FINDEX.md` (always loaded — the migration\n   state summary)\n\nProvider-specific harness files (e.g. `CLAUDE.md`, `CODEX.md`)\nare thin pointers to `AGENTS.md` and do not need to be in the\nalways-load set.\n\nThese files are short, dense, and tell the agent what exists.\nThe agent does NOT slurp `context\u002Fskills\u002F`, `context\u002Fworkitems\u002F`,\netc. on session start.\n\n#### Use the index MCP server, not filesystem walks\n\nThe `index-management` MCP server is the right way to discover\nentities. Instead of `ls context\u002Fskills\u002F`, the agent calls\n`query_entities(kind=\"Skill\", category=\"process\")` and gets back\na list of just the skills that match. Same for workitems,\ndecisions, bindings, events. Filesystem walking is the slow,\ncontext-expensive fallback.\n\n#### Load skills on demand, not upfront\n\nWhen the agent needs a specific skill (e.g. `code-review`), it\nreads `context\u002Fskills\u002Fcode-review\u002FSKILL.md` at that moment — not\nat session start. If the SKILL.md references a deeper file\n(`references\u002F...`), only read that when the agent's task actually\nneeds it. This is the three-level principle in action: start at\nLevel 1, drop to Level 2 when the request is more specific, drop\nto Level 3 only for edge cases.\n\n## Gotchas\n\nAgent-specific failure modes — provider-neutral pause-and-self-check items:\n\n- **Context overload — passing the entire codebase or conversation to every agent.** Each agent should receive only the files and context it needs for its specific subtask. Passing everything to every agent balloons token usage, produces vague responses, and hits context limits. Reference specific file paths and line ranges in handoffs rather than dumping full file contents.\n- **Circular delegation with no forward progress.** Agent A asks Agent B for help, which asks Agent A. The hallmark is growing context with repeated handoffs and no new artifacts. Enforce a strict pipeline direction: every handoff moves the task forward. If an agent cannot proceed, escalate to the user with full context — not back to the previous agent.\n- **Premature fan-out before confirming task independence.** Starting parallel agents before the planner has verified that subtasks touch different files and modules leads to merge conflicts and duplicated work. Always run a planning stage first and confirm independence; limit fan-out to 3-4 parallel subtasks.\n- **Skipping the reviewer role because the coder \"did a good job.\"** Self-confidence bias is highest immediately after writing code. The reviewer role exists precisely because authors miss their own errors. Even a self-review pass — running tests, linting, reading the diff against the spec — catches errors that accumulate into bugs when skipped.\n- **Vague handoffs without specific artifacts, paths, or line numbers.** \"I made some changes, please review\" tells the receiving agent almost nothing. Use the structured handoff format every time: status, list of file paths changed, what was verified, any blockers, and the exact next action. Include absolute paths and line numbers for all referenced code.\n- **Loading all context at session start instead of selectively.** A project with 100 skills, 5 years of decisions, and hundreds of backlog items contains far more context than any session needs. Read INDEX files to understand what exists, then load on demand when the specific task requires it. The three-level principle applies: start at the overview, drill down only when needed.\n- **Leaving scratch files (`_agent_notes.md`, `_blackboard.md`) in the repository.** Temporary agent collaboration files are not part of the project's permanent record. Every multi-agent workflow that creates scratch files must clean them up when the workflow completes. Committed scratch files confuse future agents and humans about what is authoritative context.\n- **Skipping the skill catalog for domain tasks.** Before starting\n  any domain-specific task (writing a PRD, drafting a release,\n  creating a schema), search for a matching processkit skill via\n  `search_entities` or `skill-finder`. Proceeding from general\n  knowledge when a skill exists produces output that misses\n  processkit-specific conventions and entity storage paths.\n\n## Full reference\n\n### Worked examples\n\n**\"Add authentication to this API — use multiple agents to plan,\nimplement, and review.\"** (1) Researcher reads existing route\nhandlers and middleware patterns, writes findings to\n`_auth_notes.md`. (2) Coder implements auth middleware, JWT\nvalidation, and protected route decorators based on findings.\n(3) Reviewer checks against OWASP guidelines, verifies tests\npass, confirms no hardcoded secrets. Each handoff includes the\nstructured handoff block.\n\n**\"Set up a code review pipeline for incoming changes.\"** A\nthree-stage pipeline: (1) Researcher reads the diff and gathers\ncontext about affected modules. (2) Reviewer evaluates\ncorrectness, security, performance, style using the code-review\nchecklist. (3) Planner summarizes findings into must-fix,\nshould-fix, and nit categories with line references. Quality\ngate: all must-fix items require a re-review cycle before\napproval.\n\n**\"Research the best caching strategy, then implement it.\"**\nResearch-then-implement workflow: (1) Researcher examines current\ndata access patterns, identifies hot paths, checks existing\ncaching, writes structured findings with measured or estimated\nlatencies. (2) Planner reviews findings and selects an approach,\ndocumenting the decision. (3) Coder implements the cache layer\nfollowing the plan. (4) Reviewer verifies cache invalidation,\nchecks for stale data risks, confirms tests cover hit\u002Fmiss\npaths. Handoff between research and planning includes specific\nfile paths and quantified findings.\n\n### Coordination patterns\n\nSee `references\u002Fcoordination-patterns.md` for the full pattern\ncatalog. Summary:\n\n- **Pipeline** — agents execute sequentially\n  (Researcher → Planner → Coder → Reviewer). Default choice;\n  simplest, lowest risk.\n- **Fan-out \u002F Fan-in** — planner decomposes into independent\n  subtasks, multiple agents run in parallel, a coordinator merges\n  results. Use only when the planner confirms subtasks are\n  independent (different files, different modules). Limit to 3-4\n  parallel subtasks.\n- **Supervisor** — one agent monitors and directs others,\n  reassigning work as findings shift the plan. Use for large\n  refactors and exploratory tasks where the path is unclear\n  upfront.\n- **Consensus** — multiple agents independently solve the same\n  problem; an evaluator selects or merges. Expensive — reserve\n  for high-stakes decisions (architecture, security review).\n- **Blackboard** — agents share a common workspace file, picking\n  up work items and posting results. Use section-based ownership\n  to prevent overwrites.\n\n### Pattern decision matrix\n\n| Characteristic | Pipeline | Fan-Out | Supervisor | Consensus | Blackboard |\n|---|---|---|---|---|---|\n| Sequential dependencies | Yes | No | Partial | No | Partial |\n| Independent subtasks | No | Yes | Yes | Yes | Yes |\n| Uncertain requirements | No | No | Yes | Partial | Partial |\n| Multiple valid solutions | No | No | No | Yes | No |\n| Shared evolving state | No | No | No | No | Yes |\n| Low token budget | Yes | No | Yes | No | Yes |\n| High-stakes decision | No | No | Partial | Yes | No |\n\nDefault to Pipeline. Escalate to Supervisor if scope shifts\nduring execution. Use Fan-Out only when subtasks are provably\nindependent. Reserve Consensus for decisions with significant\nlong-term impact.\n\n### Anti-patterns\n\n- **Context overload** — passing the entire codebase or\n  conversation history to every agent. Symptom: vague responses,\n  token limits hit. Fix: give each agent only the files it needs\n  for its specific subtask; use file paths and line ranges, not\n  full file contents, in handoffs.\n- **Circular delegation** — Agent A asks Agent B, which asks\n  Agent A. Symptom: no progress, repeated handoffs, growing\n  context with no new artifacts. Fix: enforce a strict pipeline\n  direction. Every handoff moves the task forward; if an agent\n  cannot proceed, escalate to the user, not back to the previous\n  agent.\n- **No verification** — skipping review because \"the coder is\n  good enough.\" Fix: always include a review gate. At minimum,\n  run tests, run lint, check the output against the spec.\n- **Premature parallelism** — fan-out before understanding\n  dependencies, causing merge conflicts or duplicated work. Fix:\n  always run a planning stage first.\n- **Vague handoffs** — \"I made some changes, please review\"\n  without specifics. Fix: use the structured handoff format\n  every time.\n- **Deferred entity creation** — saying \"I'll track that\" or\n  \"I'll file a workitem\" without immediately calling the tool.\n  Deferred commitments are routinely dropped across turn\n  boundaries, leaving the entity layer out of sync with what\n  was agreed. Fix: call `create_workitem`, `record_decision`,\n  or the relevant MCP tool in the same turn as the commitment.\n- **Skipping the skill catalog for domain tasks.** When a\n  domain-specific task arrives (writing a PRD, creating a\n  release, reviewing a skill), the agent goes to general\n  knowledge instead of checking `skill-finder` or\n  `search_entities`. The skill catalog exists precisely because\n  processkit has conventions (entity storage paths, output\n  formats, workitem linking) that general knowledge does not\n  know. Fix: run `search_entities(text=\"\u003Ctask keyword>\")` or\n  consult `skill-finder` before starting any domain task.\n\n### Practical tips for Claude Code\n\n1. **One agent session = one role at a time.** Switch roles\n   explicitly (\"Now acting as Reviewer\").\n2. **Use files for context, not memory.** Write `_handoff.md` or\n   `_findings.md`; read them in the next step.\n3. **Keep scratch files temporary.** Clean up `_agent_notes.md`,\n   `_blackboard.md` after the workflow completes.\n4. **Verify with tools, not judgment.** Run `cargo test`,\n   `npm test`, or the appropriate linter rather than \"I think\n   this looks right.\"\n5. **Time-box research.** Researchers answer specific questions,\n   not \"tell me everything about X.\"\n6. **Limit fan-out to 3-4 parallel subtasks.** More than that and\n   coordination overhead exceeds the benefit.\n7. **Always include file paths.** Every handoff and finding\n   should reference absolute paths and line numbers.\n\n### Respect the configured context budget\n\nProjects can declare a budget in their processkit configuration\nfile (the location depends on how processkit was installed — for\nexample `aibox.toml` if the project uses aibox, or a standalone\n`processkit.toml` for unmanaged installs):\n\n```toml\n[context.budget]\ntarget_tokens = 8000          # aim NOT to exceed this on initial load\nmax_tokens = 16000            # hard ceiling — must use lazy loading above this\n\n[context.budget.always_load]\nfiles = [\n  \"AGENTS.md\",\n  \"context\u002FHANDOVER.md\",\n  \"context\u002Fowner\u002Fidentity.md\",\n  \"context\u002Fowner\u002Fworking-style.md\",\n  \"context\u002FINDEX.md\",\n  \"context\u002Fmigrations\u002FINDEX.md\",\n]\n\n[context.budget.on_demand]\npatterns = [\n  \"context\u002Fskills\u002F**\",\n  \"context\u002Fworkitems\u002F**\",\n  \"context\u002Flogs\u002F**\",\n  \"context\u002Fdecisions\u002F**\",\n]\n```\n\nThe agent reads `[context.budget]` at session start (it's part\nof the `always_load` set if not overridden) and follows the rules:\n\n- `always_load.files` are loaded into the first turn\n  unconditionally\n- `on_demand.patterns` are loaded only when needed, via the index\n  MCP server or direct file reads\n- The agent estimates the total token count of `always_load` and\n  warns the user if it exceeds `target_tokens`\n\nThe values are advisory — there is no runtime enforcement. The\nagent honors them as instructions.\n\n### When context is still too big\n\nIf even the always-load set is too large, the agent should:\n\n1. Surface this to the user: \"Loading 24k tokens of context,\n   target is 8k. Want me to run `context-grooming`?\"\n2. Suggest specific candidates for archival or summarization\n   based on the `context-grooming` ruleset\n3. Offer to update the `[context.budget]` config to a higher\n   target if the project genuinely needs more\n4. Never silently truncate or drop files\n\n### Relationship to context-grooming\n\n`agent-management` says HOW to load context efficiently per\nsession. `context-grooming` runs periodically to make the corpus\nsmaller. Both work together: grooming reduces the live size;\nlazy loading reduces what gets loaded from that smaller corpus.\n",{"name":5,"metadata":54,"description":62},{"processkit":55},{"id":56,"layer":57,"created":58,"version":59,"category":60,"apiVersion":61},"SKILL-agent-management",4,1775433600000,"1.1.0","process","processkit.projectious.work\u002Fv1","Multi-agent workflow coordination — task decomposition, role assignment, context sharing, handoff protocols, quality gates, and per-session context budgeting. Use when orchestrating multiple AI agents on a shared task, designing an agent pipeline, defining handoff protocols, or planning how a session should load context within a budget.\n","main","4876a92620ee792aac2ac9a1a806322d8a572367","archive\u002Fprocesskit-install-20261101\u002Fcontext\u002Ftemplates\u002Fprocesskit\u002Fv0.8.0\u002Fcontext\u002Fskills\u002Fagent-management","https:\u002F\u002Fgithub.com\u002Fprojectious-work\u002Fprocesskit","https:\u002F\u002Fprojectious-work.github.io\u002Fprocesskit\u002F","https:\u002F\u002Fgithub.com\u002Fprojectious-work","2026-11-11 23:24:18",{"source":8,"skillName":5,"commands":71,"prompt":81,"zipAvailable":82},[72,75,78],{"tool":73,"command":74},"npx","npx skills add projectious-work\u002Fprocesskit --skill agent-management",{"tool":76,"command":77},"bunx","bunx skills add projectious-work\u002Fprocesskit --skill agent-management",{"tool":79,"command":80},"pnpm","pnpm dlx skills add projectious-work\u002Fprocesskit --skill agent-management","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fprojectious-work\u002Fprocesskit\u002Fblob\u002Fmain\u002Farchive\u002Fprocesskit-install-20261101\u002Fcontext\u002Ftemplates\u002Fprocesskit\u002Fv0.8.0\u002Fcontext\u002Fskills\u002Fagent-management\u002FSKILL.md",true,[84],{"path":85,"resourceType":86,"resourceTypeDesc":87,"sizeBytes":88,"sourceHtmlUrl":89},"references\u002Fcoordination-patterns.md","REFERENCE","参考文档",6957,"https:\u002F\u002Fgithub.com\u002Fprojectious-work\u002Fprocesskit\u002Fblob\u002Fmain\u002Farchive\u002Fprocesskit-install-20261101\u002Fcontext\u002Ftemplates\u002Fprocesskit\u002Fv0.8.0\u002Fcontext\u002Fskills\u002Fagent-management\u002Freferences\u002Fcoordination-patterns.md",[91,113,133,154,171,189],{"skillNo":92,"name":93,"nameZh":6,"description":94,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":95,"categories":96,"keywords":98,"publishedAt":49},"01M6X5MTC89B4ZGXW3JVSQCPF8","skill-management","Manage Skill package manifests as v1 ontology entities.","https:\u002F\u002Fgithub.com\u002Fprojectious-work\u002Fprocesskit\u002Fblob\u002Fmain\u002Fsrc\u002Fcontext\u002Fskills\u002Fprocesskit\u002Fskill-management\u002FSKILL.md",[97],{"categoryNo":19,"categoryName":20,"taxonomyType":21,"taxonomyTypeDesc":22},[30,99,100,101,102,103,41,104,105,106,93,107,108,109,110,111,112],"skill management","create","update","package","alpha","list","manage","ontology","get","as","manifests","v1","skill package","transition",{"skillNo":114,"name":115,"nameZh":6,"description":116,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":117,"categories":118,"keywords":120,"publishedAt":49},"01M6X5MCV74NHW5MEDNHZRF2C8","schema-management","Manage generated processkit schema contracts through deterministic MCP rebuild and inspection workflows.","https:\u002F\u002Fgithub.com\u002Fprojectious-work\u002Fprocesskit\u002Fblob\u002Fmain\u002Fsrc\u002Fcontext\u002Fskills\u002Fprocesskit\u002Fschema-management\u002FSKILL.md",[119],{"categoryNo":19,"categoryName":20,"taxonomyType":21,"taxonomyTypeDesc":22},[30,121,122,123,124,125,103,41,126,127,105,128,129,130,107,131,132],"schema","schema management","MCP","workflows","validation","generated","rebuild","contracts","wed","deterministic","contract","mode",{"skillNo":134,"name":135,"nameZh":6,"description":136,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":137,"categories":138,"keywords":139,"publishedAt":49},"01M6X5M5G6YJ96AMZGSCZJ1D13","proposition-management","Record claims, risks, beliefs, world facts, WSJF estimates, and assumptions through the Proposition interface.","https:\u002F\u002Fgithub.com\u002Fprojectious-work\u002Fprocesskit\u002Fblob\u002Fmain\u002Fsrc\u002Fcontext\u002Fskills\u002Fprocesskit\u002Fproposition-management\u002FSKILL.md",[],[30,140,141,100,101,142,103,41,143,144,145,146,107,147,148,149,150,151,152,153],"proposition","proposition management","index","log","world","record","query","creation","event","interface","updates","facts","claims","WSJF",{"skillNo":155,"name":156,"nameZh":6,"description":157,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":158,"categories":159,"keywords":160,"publishedAt":49},"01M6X5KMQ83QN9M6MPWZM7344F","ontology-management","Manage generated v1 ontology entities that do not require a dedicated domain server.","https:\u002F\u002Fgithub.com\u002Fprojectious-work\u002Fprocesskit\u002Fblob\u002Fmain\u002Fsrc\u002Fcontext\u002Fskills\u002Fprocesskit\u002Fontology-management\u002FSKILL.md",[],[30,106,161,100,103,162,163,126,164,143,105,165,166,107,167,168,148,169,110,170],"ontology management","lifecycle","archive","roadmap","do","domain","iteration","keep","measurement","generic",{"skillNo":172,"name":173,"nameZh":6,"description":174,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":175,"categories":176,"keywords":177,"publishedAt":49},"01M6X5KCY2DN3SM21RERSFNEBT","okf-compatibility","Import, export, and validate conformant Open Knowledge Format bundles.","https:\u002F\u002Fgithub.com\u002Fprojectious-work\u002Fprocesskit\u002Fblob\u002Fmain\u002Fsrc\u002Fcontext\u002Fskills\u002Fprocesskit\u002Fokf-compatibility\u002FSKILL.md",[],[178,179,180,181,103,182,183,184,41,185,186,187,188],"okf","compatibility","okf compatibility","validate","open","knowledge","format","export","bundles","bundle","import",{"skillNo":190,"name":191,"nameZh":6,"description":192,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":193,"categories":194,"keywords":195,"publishedAt":49},"01M6X5JA8S5PNGJVFW4EQY8T83","capability-management","Manage versioned Capability entities and their governed lifecycle.","https:\u002F\u002Fgithub.com\u002Fprojectious-work\u002Fprocesskit\u002Fblob\u002Fmain\u002Fsrc\u002Fcontext\u002Fskills\u002Fprocesskit\u002Fcapability-management\u002FSKILL.md",[],[30,196,197,100,101,142,103,162,41,104,143,198,105,145,107,168,148,149,199,112],"capability","capability management","queries","changes"]