agent-engineer

Agent Engineer

Act as a meta-orchestrator with an approval gate. Assume that per-task session information and request information are managed by the base agent, and have this skill handle only pattern selection, architecture documentation, state storage, verification, and execution runner generation.

Core Workflow

1. Interpret the request and confirm only the missing facts.
2. Read only the necessary reference documents listed below to decide the pattern combination.
   • references/pattern-catalog.md
   • references/architecture-selection.md
   • references/domain-routing.md
   • references/source-index.md
3. command -v codex, command -v claude, command -v opencodeCheck whether it is installed.
4. In the current working directory, .codex/agent-engineer/architecture.mdwrite the approval proposal to.
5. scripts/render_architecture.pyRender the Mermaid and approval summary table with.
6. Present the approval proposal to the user.
7. Do not create or execute an execution script before explicit approval.
8. After approval, scripts/build_runner.pygenerate the runner with.
9. After approval, scripts/run_architecture.pyexecute the runner with.

Non-Negotiables

• Do not store session information and the full request text separately.
• The architecture must be .codex/agent-engineer/architecture.mdrecorded only in.
• Before approval, build_runner.py or run_architecture.pydo not execute.
• Do not modify the state JSON directly; scripts/agent_state.pyuse only.
• Do not improvise new state manipulation scripts.
• If the required functionality is not in the bundled scripts, separate it into a skill revision task after approval.

Path Contract

• Architecture: .codex/agent-engineer/architecture.md
• State store: .codex/agent-engineer/store/
• State file: .codex/agent-engineer/store/events.jsonl, .codex/agent-engineer/store/snapshot.json
• Execution artifact: .codex/agent-engineer/runs/<run-id>/

Architecture Authoring

architecture.mdis the single source of truth for human approval. Always place a machine-readable JSON code fence at the end of the document, and assume that the execution script parses only that JSON block.

The approval proposal must include the following.

• Selected base pattern and combination method
• Step-by-step execution order
• CLI used per step or role
• Model per step or role
• Degree of parallelism
• Verification policy
• Retry policy
• Delegation points

The JSON block must include the fields below.

• version
• approval_status
• composition
• selected_patterns
• engines
• steps
• parallel_policy
• retry_policy
• validation_policy
• delegation_policy

If the selected CLI is not installed, render_architecture.py display a warning in the output. In the current environment, codex와 claudeis usually a candidate, and opencodeselect only if installed.

Execution Discipline

After approval, the runner must enforce the invariants below.

• State changes are agent_state.pyperformed only with.
• Before and after each step, verify_store.pycall.
• Before verification passes, no task may donetransition to.
• retry_policy.max_attemptsIf it exceeds, blockedtransition to and request user intervention.
• Start parallel tasks only when there is no scope conflict.
• CLI or model combinations not in the approval are rejected by invoke_agent.py.

Script Map

• scripts/agent_state.py
  • The sole CRUD entry point of the state store
• scripts/verify_store.py
  • Validates the event hash chain, snapshot regeneration, enums, referential integrity, approval gates, and completion transition rules
• scripts/render_architecture.py
  • Generates Mermaid diagrams and summary tables for approval
• scripts/build_runner.py
  • Creates the runner directory from the approved architecture
• scripts/run_architecture.py
  • Runs the generated runner and validates the store before and after each step
• scripts/invoke_agent.py
  • Using only approved CLI and model combinations, standardizes codex exec, claude -p, opencode calls

Domain Notes

Coding, research, documentation work, and operational analysis should all use the same storage structure but differ only in routing. Read only references/domain-routing.mdto decide the recommended patterns, worker roles, and validation methods per domain. For pattern selection criteria, prioritize references/architecture-selection.md.

Minimal Operating Procedure

When creating an architecture draft, follow this order.

1. Classify the nature of the task.
2. Select only the necessary patterns.
3. Assign CLIs and models step by step.
4. Determine the degree of parallelism and retry policy.
5. Specify validation commands or how to prepare for validation.
6. render_architecture.py After checking the results, request approval.

When executing, follow this order.

1. verify_store.py Check whether it passed.
2. Check whether the approval status is approved.
3. build_runner.pyto generate the runner.
4. After preparing the validation command, run run_architecture.py.
5. Retry failed tasks only with the approved policy.