Skip to content

Architecture constraints

Actionable CC 2.1 architecture constraints for skill and agent authors. For conceptual explanations, diagrams, and toolkit examples, see the full reference: plugins/core-standards/docs/agent-architecture-patterns.md

context: fork Rules

  1. NEVER use AskUserQuestion in a fork skill. The sub-agent has no channel back to the user. The call fails silently — the parent receives no output at all.
  2. ALWAYS include a concrete actionable task, not just guidelines. A fork skill with only principles produces empty output.
  3. ALWAYS define a structured output format with delimiters. The parent only sees the sub-agent's final output — make it parseable.
  4. Fork sub-agents CANNOT spawn their own sub-agents. No nesting.
  5. ALWAYS add an "Error Handling (context: fork)" section with three rules: no interactive questions, inline failure reporting, full formatted output.
  6. ALWAYS add a TL;DR summary step as the final output of the fork skill.

Hook Rules

  1. Hooks are ADDITIVE across all four levels (Global > Plugin > Skill > Agent). A lower-level hook cannot suppress a higher-level hook.
  2. Hooks at the same level execute in PARALLEL. Do not write hooks that depend on side effects from other hooks at the same level.
  3. Skill-scoped hooks (in SKILL.md frontmatter hooks: field) only fire while the skill is active. They are removed when the skill completes.
  4. Agent hooks are Level 4 (narrowest scope). They stack on top of all broader hooks, never replace them.
  5. Stop hooks declared in agent frontmatter are automatically converted to SubagentStop events — they fire when the sub-agent stops, not when the parent conversation stops.

Permission Rules

  1. bypassPermissions cascades DOWNWARD. If a parent uses it, ALL sub-agents inherit it. You cannot restrict below the parent's level via permissions.
  2. Enforce restrictions via hooks (e.g., block-writes.sh), not permissions. This is why the policy island pattern exists.
  3. Background sub-agents auto-deny any unapproved permission prompts. Either pre-approve tools or run the sub-agent in the foreground.

Orchestrator Rules

  1. Sub-agents cannot spawn their own sub-agents. Design orchestrators as FLAT dispatch points — chain from the orchestrator, not from within sub-agents.
  2. Gate failures must halt the pipeline. The orchestrator is responsible for this logic — there is no built-in gate mechanism.
  3. The orchestrator needs the Agent/Task tool. Specialist sub-agents typically should NOT have it.

Agent Isolation Rules

  1. Read-only agents (review, analysis) do NOT need isolation: worktree.
  2. Agents using context: fork already run in isolated context — skip worktree.
  3. Agents needing dirty-tree visibility CANNOT use worktree (it branches from the default remote, not the current working state).
  4. Apply the 4-question checklist in references/agent-frontmatter-fields.md.

Quick Anti-Pattern Check

When creating or auditing a skill/agent, verify: - [ ] No AskUserQuestion in any context: fork skill - [ ] No hook that depends on side effects from another hook at the same level - [ ] No sub-agent spawning its own sub-agents - [ ] No guidelines-only fork skill (must have actionable task) - [ ] bypassPermissions not granted without hook-level enforcement - [ ] Background sub-agents have all needed tools pre-approved - [ ] Fork skills have error handling section + TL;DR step