跳至正文
OpenAgentSkill
浏览已开放 · 目录记录日期 2026-11-21 · 自动更新和账户服务暂时关闭。
开发与测试

agent-role-boundary-preflight

Check an agent's role, lifecycle ownership, target scope, and authorization immediately before any side effect. Use in multi-agent or role-separated workflows before writing code, specifications, configuration, tests, documentation, runtime artifacts, version control, or external systems, and whenever a task shifts from analysis, planning, or review into execution.

HsienW · 已有静态检查记录

安装与使用

运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。

npx skills add HsienW/ai-agent-engineering-playbook --skill agent-role-boundary-preflight

技能说明


name: agent-role-boundary-preflight description: Check an agent's role, lifecycle ownership, target scope, and authorization immediately before any side effect. Use in multi-agent or role-separated workflows before writing code, specifications, configuration, tests, documentation, runtime artifacts, version control, or external systems, and whenever a task shifts from analysis, planning, or review into execution.

Agent Role Boundary Preflight

Tool access is capability, not authority. Run this preflight immediately before every side effect. Repeat it when the task mode, role, phase, owner, target, or requested effect changes.

Required Inputs

Resolve these values from authoritative project rules and current workflow state. Do not infer missing values from the model name, host, available tools, or earlier conversation momentum.

  • role: the actor role assigned for the current phase.
  • phase: the current lifecycle phase, if the workflow has one.
  • owner: the role allowed to act in that phase.
  • action: the exact operation and its side effects.
  • target: the file, resource, repository, branch, runtime artifact, or external system that would change.
  • authoritySource: the rule, state record, or explicit role reassignment that grants the action.
  • handoff: the active handoff and its permitted scope, when applicable.

Preflight Procedure

  1. Classify the next tool call as read-only or side-effecting. Treat writes, edits, shell commands, version-control mutations, generated artifacts, messages, deployments, and external API mutations as side effects.
  2. Resolve the actual role. A coordinator, planner, reviewer, implementer, and verifier may run in the same host while holding different permissions.
  3. Resolve phase and owner from the workflow's canonical state. If no lifecycle state exists, use the closest authoritative role and scope rules.
  4. Compare the exact action and target with the role's positive write scope and explicit prohibitions.
  5. Check the user's message precisely. Approval of a decision, finding, plan, or desired outcome does not reassign execution. Treat reassignment as valid only when it is explicit and allowed by higher-priority project policy.
  6. Apply the decision table below. Missing, stale, malformed, contradictory, or unverifiable authority fails closed.
  7. Record a compact decision before invoking the tool. Re-run this procedure instead of reusing an earlier decision when anything relevant changes.

Decision Table

ConditionDecisionRequired response
Action is read-only and within the role's read scopeALLOW_READContinue without mutation
Role, phase, owner, target, and action all match authoritative scopeALLOW_WRITEExecute only the checked action
Another role owns the actionHANDOFFProduce a structured handoff; change nothing
Authority data is missing, invalid, stale, or contradictoryHANDOFFRoute to the coordinator or authority owner; change nothing
Tool side effects cannot be bounded or classifiedHANDOFFDo not invoke the tool
User approved a direction but did not validly reassign executionHANDOFFPreserve the decision in the handoff; change nothing

Edit size never changes the result. A one-line change requires the same role authorization as a large change.

Compact Check Record

Use this internal or chat-visible record when the host supports it:

roleBoundaryCheck:
  role: reviewer
  phase: implementation_review
  owner: implementer
  action: edit
  target: src/api/users.ts
  authoritySource: workflow-state
  decision: HANDOFF
  reason: implementation is owned by another role

Do not treat this record as authority. It only explains how authority was evaluated.

Structured Handoff

When the decision is HANDOFF, return enough information for the owning role to continue without repeating the analysis:

handoff:
  fromRole: reviewer
  toRole: implementer
  task: Correct the validated response mapping.
  reason: The reviewer found the issue but does not own implementation.
  scope:
    - src/api/users.ts
    - src/api/users.test.ts
  evidence:
    - Finding F-2
    - Failing case: unknown response field is discarded
  constraints:
    - Preserve the public response schema
    - Do not change unrelated modules
  acceptance:
    - Regression test passes
    - Existing package checks pass

After producing the handoff, do not make a temporary, convenient, or partial edit.

Enforcement Guidance

Prompt instructions are necessary but cannot be the only control. When the host supports pre-tool hooks or policy middleware, mirror the same decision at the tool boundary:

if authority evidence is missing or invalid:
    deny and require handoff
if role != owner for this action and target:
    deny and require handoff
if the tool's side effects cannot be bounded:
    deny and require handoff
allow only the action and target that were checked

Prefer a narrow allowlist for side-effecting tools. Cover alternate write paths such as shell commands, batch edits, notebooks, version-control commands, MCP tools, and external APIs. A newly added tool is untrusted until its effects are classified.

Verification

Test the policy as executable behavior, not only as prose. Include:

  • a one-line out-of-role edit;
  • a valid role with the wrong phase or owner;
  • missing, malformed, stale, and terminal workflow state;
  • valid in-role writes to the exact permitted target;
  • shell, batch-edit, notebook, MCP, and external-action bypass attempts;
  • a user decision that does not reassign execution;
  • task drift from read-only analysis into implementation;
  • hook or policy-engine failure, which must deny rather than silently allow.

The check is successful only when denied operations leave the target unchanged and produce a usable handoff.

For the incident pattern behind this guidance, read the

阅读完整来源 ↗