The Perfect Agent Portal edition · open source

Governance / intent / evidence / learning

The smallest useful
agent framework.

Give capable agents clear authority, one current goal, bounded memory, accountable roles, and independent review—without making ordinary work feel like a board meeting.

See the system View source on GitHub
SYSTEM_STATEINSPECTABLE
01governing kernel
01active goal
01custom skill
08bounded personas

Solo by default. A workforce only when the consequence earns it.

Current intent beats memory Hard gates beat vibes Delivery is a separate lane Learning must expire

The control plane

Five surfaces.
No hidden hierarchy.

Stable governance stays small. Volatile state is replaced. Specialist roles and procedures load only when they have work to own.

01AGENTS.md

Authority, precedence, preservation, and the default solo operating model.

Always applicable
02PERCEPTION.md

One current goal, definition of success, evidence, constraints, signals, and next decision.

Replace in place
03MEMORY.md

Curated shared decisions and reusable lessons with provenance, caps, expiry, and deletion.

Bounded recall
04PERSONA-*.md

Accountability contracts and role-scoped memories loaded only for the people doing real work.

On demand
05the-perfect-agent

Right-sized coordination for explicit, cross-system, release-critical, high-consequence, or independent-acceptance work.

Progressive disclosure

A team only when needed

Accountability without theater.

  1. 01
    Frame

    Freeze the outcome, evidence, authority, and observable gates.

  2. 02
    Assign

    Activate only personas with an inspectable output or gate.

  3. 03
    Build

    Keep write ownership exclusive and changes small enough to inspect.

  4. 04
    Verify

    Exercise the real behavior on one exact artifact identity.

  5. 05
    Critique

    Use a fresh reviewer who never receives the builder’s rationale.

  6. 06
    Deliver

    Stop at the highest state that is both observed and authorized.

The important boundary

Build here.
Deliver deliberately.

IMPLEMENTATION

“Fix this.”

Scoped local edits and relevant verification. No automatic push, release, or account mutation.

PHONE DELIVERY

“Test this on my phone.”

A separate one-shot lane, pinned to an exact candidate and the app repository’s real release contract.

What stays out

Less context.
Fewer contradictions.

Development stacks

Swift, Unreal, web, Git, and release commands belong to the repository that can keep them true.

Private history

No raw chats, secrets, hidden reasoning, personal finance, or infrastructure identities become memory.

Unattended mutation

Recurring automations may observe and report, but they do not modify code or release builds.

Permanent lessons

Shared and persona memory have hard caps, review dates, expiry, and deletion triggers.

Portable by design

Copy the framework.
Keep the project specific.

Adopt the governing files and workforce skill, then let each repository define its own commands, architecture, verification, and delivery route.

AGENTS.md MEMORY.md PERCEPTION.md PERSONA-*.md memory/personas/ .agents/skills/the-perfect-agent/