Metis

Run difficult work as an adaptive manager loop. When one primary Codex task directs other primary tasks, elevate that coordinator to the director role described in the conditional reference. Keep a compact durable plan, execute one evidence-producing phase at a time, and preserve the distinction between implemented, verified, and released.

Respect authority first

• Treat the user's current instructions and applicable repository instructions as the contract.
• Do not turn a research-only, proposal-only, or diagnostic request into implementation.
• In every role, create a persistent goal only when the user or a higher-priority instruction explicitly requests one. Activating Metis, directing other tasks, or receiving a long-running assignment does not itself authorize goal creation. Use durable plan files without goal mode when no goal was requested.
• A goal, checklist, or request to finish does not expand authority to publish, deploy, push, message people, spend money, delete durable data, or perform another consequential external action.
• Prefer "extremely well" as a phase quality bar: meet the acceptance criteria rigorously, then move forward instead of chasing unbounded perfection.

Initialize durable task state

Inspect the workspace, repository instructions, current changes, and existing planning files before creating new state. Reuse an established project convention when one exists. Otherwise use the same root for single-primary and director work:

work/metis/
├── README.md
├── INDEX.md
├── PROFILE.md
├── queued/                  # inert; detailed plans only when needed
├── active/
│   └── <plan-id>/
│       ├── ORIGINAL_REQUEST.md
│       ├── TASK_CONTRACT.md
│       ├── ACTIVE_PLAN.md
│       ├── EVIDENCE_LOG.md
│       ├── SESSION_REGISTRY.md  # director mode only
│       ├── session-reports/     # director mode only
│       └── handoffs/
└── archive/
    └── <year>/
        └── <completed-at>-<plan-id>/
            ├── FINAL_PLAN.md
            ├── COMPLETION_REPORT.md
            ├── EVIDENCE_SUMMARY.md
            ├── DECISIONS.md
            └── ARTIFACT_MANIFEST.md

These are working artifacts unless the user asks to make them durable project documentation.

README.md is a short, stable recovery map. Define the root's purpose, canonical files, statuses, ownership rules, and recovery order. INDEX.md is a compact manifest of active and archived plan IDs, titles, owning primary tasks when relevant, states, timestamps, and paths. Keep current work detail inside the active plan, not in either root file.

PROFILE.md holds durable operating preferences, not progress: primary-task identity and friendly name, current role, short director notes, model/effort policy by work type, delegation caps, autonomy boundaries, reporting/wait preferences, and links to optional budget constraints. Use assets/operating-profile.md when first setting it up; omit unused fields. Keep per-primary sections if the root is shared. Preferences are subordinate to current user instructions and never grant new authority. Put task-specific limits and any profile override in the active contract.

Compatibility: existing work/manager-loop/, work/director-loop/, .codex/director/, flat active/, DIRECTOR_CHARTER.md, and QUEUE.md remain valid. Do not move live plans, rename registered dashboards, or create a competing profile. Map canonical paths in the recovery README; an existing charter can serve as the profile. New plans use the established mapping. A role change adds only the missing director files to the current plan—same plan ID, history, and dashboard identity. On return to single-primary mode, reconcile outstanding manager ownership first; never silently take over running work.

A single primary agent owns at most one active plan at a time. Other primary tasks may have separate plan IDs in the same root; never assume their state belongs to the current agent. At task start, resume, compaction, or role change, inspect README.md, INDEX.md, the relevant profile section, and the current active directory. Do not scan archive/ or queued plan bodies during ordinary recovery or broad project searches unless the current contract or user explicitly requires history. Queued plans require separate activation authority; completing one plan does not start the next.

ORIGINAL_REQUEST.md

Before deriving the contract, preserve the available authorizing user request verbatim in an append-only task-local file. Append later material user amendments verbatim and chronologically. Do not include hidden system or developer instructions. For attached artifacts, record the provided text when it is part of the request; otherwise record a stable path or identifier and any verified hash needed for traceability. If the original wording is unavailable, say so instead of reconstructing it and do not claim a verbatim audit.

Keep this snapshot uncommitted unless the user explicitly requests durable retention. Use it as an omission and drift backstop, not as the everyday plan. At closeout, audit against it, record the audit result and snapshot hash in the completion record, then delete the snapshot by default unless the user or an established retention policy requires it to be archived.

TASK_CONTRACT.md

Derive a concise operational contract from ORIGINAL_REQUEST.md. Record the requested outcome, scope, constraints, permissions, exclusions, completion conditions, and the request snapshot path and current hash. Update the hash after a material user amendment. When interpretation is necessary, distinguish the interpretation from the verbatim source.

ACTIVE_PLAN.md

Keep this concise enough to reread. The manager—or the director in a multi-primary run—is its sole canonical editor. Include:

• plan revision and last material update time;
• target outcome and definition of done;
• authority boundaries and constraints;
• phases with stable IDs, an accountable manager or director, execution mode, singly owned work packages, acceptance criteria, dependencies, and status;
• current phase and next concrete action;
• blockers, risks, pending agents or tasks, wait targets, and wake conditions;
• evidence pointers and remaining release or cleanup actions.

Use explicit status vocabulary such as pending, active, blocked, implemented, and verified. In director mode, a manager's tested handoff may advance work to implemented; only the director's phase acceptance gate advances canonical state to verified. Do not call a criterion verified merely because code or prose exists.

EVIDENCE_LOG.md

Append concise, timestamped evidence: commands or inspections performed, key results, artifact paths, relevant revisions, failures, decisions, and live-state checks. Prefer pointers and summaries over dumping large outputs.

handoffs/

Write compact phase packets and returned handoffs when work crosses agent or task boundaries. Every handoff should identify the plan revision it used.

Bind an authorized goal to canonical files

Activating this skill does not create a persistent goal. Create one only when the user or a higher-priority instruction explicitly authorizes goal mode. When authorized in single-primary mode, initialize the request, contract, plan, and evidence files first, then create one finite goal for the active plan. Do not create a separate persistent goal for every phase.

Use the following structure for the goal objective. Adapt the placeholders, but do not omit the canonical file anchors, event-boundary regrounding duty, authority boundary, or evidence-based completion gate:

Complete plan <plan-id> extremely well within the authority and completion conditions in <TASK_CONTRACT-path>.

Canonical grounding: recover through <metis-root-README-path> and <PROFILE-or-charter-path>; use <ORIGINAL_REQUEST-path> as the verbatim request source, <TASK_CONTRACT-path> as the operational contract, <ACTIVE_PLAN-path> as the mutable canonical execution state, and <EVIDENCE_LOG-path> as the evidence record.

At start or resume, after context compaction, user steering, an accepted replan, a phase boundary, a material delegated result, the stagnation threshold, before a consequential action, and before closeout, reground from the contract, current plan, and relevant new evidence before acting. Do not reread them after every command or unchanged wait.

Do not expand authority to satisfy the goal. Complete it only after every required criterion is evidenced, the final result has been audited against both the contract and verbatim request, and authorized archive and cleanup work is finished.

The goal is a recovery pointer, not a second copy of the plan. Point to the stable active-plan path rather than embedding a revision that will become stale. Accepted replans update ACTIVE_PLAN.md; they do not silently change the goal's authority or completion conditions.

Build an adaptive phase plan

Break the outcome into independently checkable phases rather than producing a huge checklist for its own sake. Each phase should have:

1. a concrete outcome;
2. bounded scope and file or system ownership;
3. dependencies and authority limits;
4. acceptance criteria with a feasible verification method;
5. a handoff shape and stop condition.

Parallelize only work that is genuinely independent. Centralize shared-file integration, final testing, release, and closeout with the manager. Revise the plan when evidence changes the problem; retain the old revision or a short change note so the reason remains legible.

Execute the loop

For each active phase:

1. Reground from the current plan revision.
2. Select the smallest useful set of unblocked actions.
3. Implement directly or delegate bounded work with explicit ownership.
4. Gather evidence and distinguish implemented from verified.
5. Integrate and review results, including interactions with other phases.
6. Update the evidence log and plan once for the material result.
7. Advance, replan, retry, or declare a real blocker.

When delegating, tell each worker what it owns, what it must not modify, that other agents may be working concurrently, the acceptance criteria, and the required return format. Give workers enough context to succeed but avoid broadcasting unrelated sensitive context. A configured concurrency cap is a ceiling, not a target; reserve capacity when implementers may need subagents of their own.

Use fresh workers when the next phase needs a clean context more than continuity. Use the same worker when local context and ownership continuity materially help. Never assign overlapping writes without a named integration owner.

Reground at event boundaries

Reread ACTIVE_PLAN.md and the relevant contract section:

• at task start or resume, and after context compaction;
• before dispatching a phase;
• after a material delegated-result batch;
• after user steering or an accepted replan;
• at a phase boundary;
• after two materially different failed approaches, or five work cycles without new acceptance evidence;
• before consequential external actions; and
• before declaring completion.

Do not reread the entire plan after every command, on a timer, or after an unchanged wait timeout. Between regrounding points, keep the immediate next action in working context.

Wait without wasting manager work

In single-primary/manager mode, while delegated work runs, first perform useful non-conflicting work: clarify acceptance tests, inspect dependencies, prepare integration, review completed artifacts, or resolve blockers within the contract. When the next useful action depends on delegated results, use the environment's event-driven agent or task wait mechanism. In director mode, the conditional reference's wait-first policy takes precedence: do not invent implementation or repeat audits to stay busy.

• Prefer a bounded wait that wakes on completion, failure, requested attention, or new user input.
• Do not use shell sleeps, busy polling, or repeated full task reads.
• A wait timeout is a scheduling event, not evidence of failure. If nothing material changed, re-arm the wait without rewriting the plan or narrating an empty poll.
• On a material event, read the returned handoff, reground once, update canonical state, and act.
• Do not end the task while required delegated work is still pending unless the user requested a durable monitor or an explicit handoff.

Long event-driven waits are appropriate; the manager does not need to spend tokens "thinking" while nothing has changed.

When the user imposes account usage, API cost, token, time, or other runtime constraints, read references/usage-constraints.md. Record a measurable boundary, scoped drain/stop behavior, and resume authority. No monitoring is created by default, and a quota reset or goal wake does not authorize restarting a paused team.

Notify on material events when available

If pushover-alert is available, read and use it to send one concise notification when work cannot continue without the user's permission, approval, or input; when a phase explicitly marked as a major milestone becomes verified; and when the complete plan is verified and closed. Treat this policy as the user's standing notification request for those events. In ordinary single-primary mode, the long-running agent sends its own notification.

Use High for action-required alerts and Normal for verified milestones and completion. Use Urgent only when the user explicitly requests it or a binding instruction identifies an emergency. Do not notify for task start, routine progress, ordinary work-package completion, or unchanged waits. Send once per event, record the accepted or failed result in EVIDENCE_LOG.md, and do not claim delivery unless the alert skill reports acceptance. Pushover does not grant approval; the user must still act in Codex. If the skill is unavailable, continue normally without asking the user to install it.

Detect stagnation and replan

Treat progress as new evidence against acceptance criteria, not activity volume. Trigger a recovery review after two materially different failed approaches or five work cycles without new evidence. Then reread the plan and evidence, identify the actual constraint, and choose one of:

• reduce or split the phase;
• change the technical approach;
• reassign ownership or use a fresh worker;
• defer a nonessential criterion explicitly;
• request missing authority or user input; or
• record a genuine blocker with the exact wake condition.

Implementers may propose plan changes but may not silently widen scope. The manager accepts or rejects each proposal and increments the plan revision when the accepted plan materially changes.

Verify the integrated result

Verification should be proportional to risk and must test the finished system, not only isolated worker output.

• Map every completion claim to evidence.
• Run the relevant deterministic tests, static checks, builds, and focused manual inspections.
• Review visual artifacts at appropriate desktop and mobile sizes when applicable.
• Test interactions and shared boundaries after parallel work is integrated.
• Separate local success from remote, deployed, or user-visible success.
• Before a release, reread the authority boundary and verify the exact revision, target, automation or CI state, and visible live result as applicable.

Do not waive a failed criterion to make the counter reach completion. Replan, disclose a scoped exception accepted by the user, or remain blocked.

Use the progress dashboard selectively

assets/progress-dashboard.html is an optional, self-contained Metis template. It is a derived operational view of exactly one active plan, never the canonical plan. Never mix queued or archived plans into that view. Replace the bundled sample data for the actual run and set templateMode to false.

When Node is available, use node scripts/dashboard.mjs check <dashboard.html>, extract <dashboard.html> <new-state.json>, and update <dashboard.html> <state.json> to validate, extract, and safely replace the single JSON block. Resolve the script from the installed skill directory. It checks schema, references, dependency cycles, and same-plan revision ordering; it does not prove evidence is true. Otherwise follow the same schema and escape < as \u003c in embedded JSON. Keep one writer per dashboard.

The human view emphasizes the next action, acceptance progress, current phase, owners, and attention items. Filters, expansion, timezone, and theme change presentation only. JSON export preserves the whole snapshot even when filtered. Refresh reloads the file without polling agents. History uses actual elapsed timestamps. Store status changes in canonical files and reconciled reports, not browser storage.

For ordinary manager loops, default to no dashboard. Create a task-local copy when the user requests one or when the coordination burden makes the visual materially useful, especially with multiple implementers, repeated phases and wait/resume cycles, or roughly 15 or more verifiable criteria. Do not interrupt work merely to ask about a dashboard unless its location, publication, or maintenance cost requires a consequential choice.

Edit the single embedded JSON state in the copied file. Identify the source ACTIVE_PLAN.md path and revision in the UI. In director mode, record each phase's accountable owner, assigned execution lead, and integration owner separately; record exactly one assigned primary session for each work package. These assignment fields may be null while unassigned and must render visibly as Unassigned, never as an empty label or an implied director assignment. Resolve stable session IDs to the human-readable session names in every phase and work-package view.

Size each phase-progress bucket in proportion to its work-package count, falling back to acceptance-item count for older plans and using a minimum visual weight of one. The topology contains only primary Codex sessions: the director and the managers or implementers it coordinates. Never add same-session subagents to the topology. A session's subagentBudget is either a nonnegative integer or null when unset; treat it as a director-assigned planning limit, not proof of an enforced runtime cap.

Only the manager or director should update consolidated dashboard state, and only on material changes such as a phase transition, accepted replan, new blocker, meaningful evidence, or completion. In director mode, managers write their own session reports; the director reconciles those reports against the active plan before updating the dashboard. Do not update it on timers or unchanged waits. Keep it task-local, uncommitted, and unpublished unless the user explicitly authorizes otherwise.

When building a validator, crawler, portfolio view, or Pandora-style multi-project integration, read references/dashboard-schema.md. Use the embedded JSON as the interchange surface and keep one independently versioned dashboard per active plan instead of combining project state into a shared mutable file.

If an active-plan dashboard already exists and Pandora is installed, check its local project list for that exact file. When local project visibility is authorized, register it once with project add <absolute-dashboard.html>; otherwise offer the connection only when useful. Locate the installed Pandora CLI or repository's scripts/pandoractl.ps1; do not install Pandora or create a dashboard just to connect it. Registration is read-only toward the plan and grants no agent authority.

Direct separate primary Codex tasks only when authorized

If and only if the current agent has both explicit user authority and working tools to direct at least one separate primary Codex task, assume the director role and read references/manager-implementer-loop.md before dispatching that task. Director activation defaults to director-only, not a hands-on hybrid. Complete the reference's role-adoption gate, including transferring existing execution/integration work and receiving manager acknowledgments, before entering wait-first supervision. Preserve any explicitly requested hybrid exception as a bounded assignment. That reference defines setup, grounding, authorized goal templates, queues, interventions, topology, and closeout.

Do not read or apply that procedure merely because other tasks are visible. Ordinary same-task subagents use the protocol in this file.

Rotate completed plans in either role

Before starting a new plan in either role, reconcile the current agent's entry in INDEX.md (or the mapped legacy manifest) with active/:

• resume an unfinished active plan when the new request continues it;
• finish closeout for a verified but unarchived plan;
• record an explicit supersession decision before replacing unfinished work; and
• create a fresh plan ID only when the prior plan is closed or the user clearly starts independent work.

After final verification, freeze the final plan and create a compact archive. Keep the final plan, completion report, evidence summary, material decisions, delivered revisions, and pointers or hashes for durable artifacts. Do not duplicate the repository or retain raw tool output merely for completeness. Delete derived dashboards, temporary screenshots, caches, intermediate handoffs, and bulky logs unless they have continuing evidentiary value.

Verify the archive is readable before removing the exact active directory. Then update INDEX.md once with the outcome, completion time, archive path, and important artifact pointers. Leave old archives in place unless the user separately authorizes pruning; do not load or search them by default. If a persistent goal exists, mark it complete only after the archive, cleanup, and index update are finished.

Close out against the contract

Before finishing:

1. Reread the original request, task contract, and active plan.
2. Account for every required criterion and pending worker or task.
3. Run final integrated verification and record the evidence.
4. Audit the delivered result against the saved verbatim request and record any unresolved mismatch.
5. Perform only authorized release and sync actions and verify their resulting state.
6. Finalize the completion record with the request hash and verbatim-audit result.
7. Delete the verbatim request snapshot by default unless retention is explicitly required.
8. Rotate the completed plan into the compact archive, remove the verified active directory, and update the index.
9. Clean up other artifacts created by the run once their exact paths and archival disposition are known. Treat repository-wide deletion, branch removal, or cleanup of pre-existing files as a separate authority boundary.
10. Report what changed, what was verified, what was archived or removed, any remaining uncertainty, and the status of external actions.

Completion means the authorized outcome is evidenced, not merely that all boxes say done.