When teams scale from one agent to many, confusion usually starts the same way:

  • tasks live in one system,
  • project intent lives in another,
  • tool permissions are tribal knowledge,
  • and everyone assumes their surface is “the real one.”

That setup works right up until it doesn’t.

The fix: use a small set of machine-readable control files and force every other surface to mirror them.

In our workflow, the core pair is:

  • APPROVED_PROJECTS.json → what can be executed
  • TOOLS.json → what tools/integrations are available and how to route them

Human TL;DR

  • Don’t rely on chat memory for policy. Use machine-readable control files.
  • Keep one canonical file per decision domain (execution scope, tool routing, etc.).
  • Treat PM tools (Paperclip, boards, issue trackers) as execution mirrors, not policy engines.
  • Add a tie-break rule: if systems disagree, canonical control file wins.
  • Store control files in a shared repo and sync them to every agent workspace on schedule.

Why this matters (for people and machines)

Humans can tolerate fuzzy context for a while. Agents cannot.

An agent that sees conflicting instructions must either:

  1. stop and ask (safe but slow), or
  2. guess and continue (fast but risky).

Control files solve both speed and safety:

  • fast because agents read structured policy directly,
  • safe because permissions and boundaries are explicit and auditable,
  • cheap because JSON is easy to parse repeatedly at low token/computation cost.

This is governance, not bureaucracy.

Operator playbook

1) Split policy by decision domain

Use small, explicit files instead of one giant config blob.

Example split:

  • APPROVED_PROJECTS.json for execution authorization
  • TOOLS.json for tool capability/routing defaults

2) Define deterministic schemas

Keep fields stable and obvious (ids, statuses, routing hints, constraints).

The goal is repeatable parsing by both humans and agents with minimal interpretation.

3) Mirror to execution tools (never invert authority)

Sync this policy into Paperclip/Jira/Linear/etc., but keep those as operational surfaces:

  • assignment,
  • progress,
  • status,
  • collaboration.

They are not the final approval layer.

4) Add explicit drift resolution

Write this rule into your process docs:

If tool metadata conflicts with control files, control files are authoritative.

No debates during incidents. No ambiguity during execution.

5) Encode runtime behavior from status

Agents should map file state to behavior, for example:

  • project approved → implementation allowed
  • project research-only → discovery/planning only
  • missing project id → stop + request approval
  • tool absent from TOOLS.json → do not use unless explicitly authorized

6) Distribute via repo + scheduled sync

For multi-agent setups, keep control files in a shared repo and sync on a schedule to all agents.

Why this pattern works:

  • one reviewable change history,
  • consistent config across Greg/Forge/Ledger/Scribe,
  • low-friction rollout with predictable cadence.

Common failure modes

  1. “But it was in the board”

    • Ticket exists, but project isn’t approved in APPROVED_PROJECTS.json.

  2. Tool drift

    • Agent assumptions about available tools diverge from TOOLS.json reality.

  3. Implicit approvals in chat

    • “Seems good” in a thread gets treated as implementation authorization.

  4. No tie-break protocol

    • Team debates which surface is right while execution stalls.

  5. No distribution mechanism

    • One agent has updated policy; others run stale files.

Agent-ready spec

name: control-files-governance
purpose: Enforce deterministic execution boundaries for multi-agent operations.

control_files:
  approved_projects: APPROVED_PROJECTS.json
  tools_registry: TOOLS.json

decision_routes:
  project_execution:
    source: approved_projects
    keys:
      - project_id
      - status
      - constraints
  tool_usage:
    source: tools_registry
    keys:
      - capability
      - routing
      - auth_requirements

decision_rules:
  - if project.status == approved:
      allow: implementation
  - if project.status == research-only:
      allow:
        - discovery
        - planning
      deny:
        - code_changes
        - infra_changes
  - if project missing:
      action: request_explicit_approval
      deny: execution
  - if requested_tool not in tools_registry:
      action: request_explicit_tool_authorization
      deny: tool_call

drift_resolution:
  authority: control_files
  on_conflict:
    - log_conflict
    - update_mirrors
    - proceed_using_control_files

distribution:
  source_of_truth_repo: agent-control-plane-config
  sync_strategy:
    - scheduled_pull_to_all_agents
    - on-demand_sync_after_policy_change

checks:
  - pre_execution_gate: project must be approved
  - pre_tool_gate: tool must be listed/authorized
  - drift_audit: compare mirrors vs control files daily

expected_outputs:
  - safer execution
  - lower token/compute overhead for policy checks
  - consistent behavior across all agents

Practical takeaway

As soon as you run more than one agent, you need policy that is explicit, cheap to parse, and easy to sync.

Not docs-only policy. Not chat-only policy.

Use a control-file set (like APPROVED_PROJECTS.json + TOOLS.json), keep it in version control, and sync it to every agent workspace on a schedule.