agent-files

Agent Files Scaffold

Trigger

• Use when a workspace needs the four-file AGENT contract (AGENT.md, AGENT_GOAL.md, AGENT_HARNESS.md, AGENT_PROGRESS.md) scaffolded from scratch with strict, non-overlapping functional boundaries.
• Use when preparing a workspace to survive handoff between agents, where the caller wants a disciplined, recoverable contract on first read.
• Do not use to curate or revise an existing AGENT_GOAL.md; goal curation is outside this scaffold's write surface.
• Do not use when the caller explicitly asks for a domain-specific AGENT-file scaffolder or sidecar-aware workflow; this generic scaffold owns only the base four-file contract.
• Do not use when only a task checklist is needed and no durable four-file contract is wanted.

Inputs

• target_dir: directory where the four AGENT files will be scaffolded
• mission: one- or two-sentence long-term mission statement written into AGENT_GOAL.md; required so the scaffolded contract is internally consistent on first read. It must not include reusable workflow rules, formatting preferences, current task state, next steps, or transient objectives.
• objective: optional concrete in-flight objective written into AGENT_PROGRESS.md; it must be transient current work, not a second mission statement or permanent scope rule. When omitted, the ## Current Objective section is removed rather than left as a literal placeholder.
• overwrite: when true, existing files in target_dir are replaced as an explicit control-contract overwrite; otherwise only compatible existing files are recorded in files_skipped

Workflow

1. Receive target_dir and mission. Confirm the directory exists or create it. mission is required so the scaffolded contract is internally consistent the moment a later agent reads it; AGENT.md and AGENT_GOAL.md are agent-immutable after scaffold and cannot be filled in autonomously later.
2. Classify the supplied mission and optional objective before writing:
   • mission-level purpose belongs in mission
   • transient current work belongs in objective
   • reusable workflow rules and preferences belong in future AGENT_HARNESS.md updates, not in mission
   • current repository state, blockers, and next steps belong in future AGENT_PROGRESS.md updates, not in mission
3. Before partial adoption, inspect any existing AGENT.md, AGENT_GOAL.md, AGENT_HARNESS.md, or AGENT_PROGRESS.md in target_dir. If any of these files already exist and overwrite is false, proceed only when every existing file passes the hardened compatibility checklist below; otherwise stop and ask whether to use overwrite=true or choose a clean target directory. Do not mix boundary-aware files with incompatible older files.
   • AGENT.md must start with # Agent Control and contain the phrases agent-immutable control contract, control-contract replacement, migration, or scaffold overwrite, and Child skills and sidecars shall not patch this file; the higher-precedence caveat including venue; ## Boundary Audit Checklist; a precedence section; an update-routing or update-dispatcher section; and the dispatcher-maintenance terminal condition.
   • AGENT_GOAL.md must start with # Mission, contain the phrase agent-immutable, and preserve neutral scaffold entries such as Not yet specified by user rather than instructional placeholders.
   • AGENT_HARNESS.md must start with # Workspace Harness, contain the phrase reusable playbook, use ## Stable Operating Context, include ## Reusable Preferences, and preserve the neutral reusable-preference placeholder or real durable rules.
   • AGENT_PROGRESS.md must start with # Progress, contain the phrase live-state record, include the neutral completed-changes entry No completed changes recorded yet. or real factual progress, and contain no literal {{ objective }} placeholder.
4. For each of AGENT.md, AGENT_GOAL.md, AGENT_HARNESS.md, AGENT_PROGRESS.md:
   • If the file already exists and overwrite is false, skip it and record the path in files_skipped.
   • Otherwise copy the corresponding template from examples/ into target_dir. Substitute mission for the {{ mission }} placeholder in AGENT_GOAL.md; the remaining goal sections render as explicit "not yet specified by user" entries rather than instructional placeholders, so they are not mistaken for user-approved scope. If objective is provided, substitute it for the {{ objective }} placeholder in AGENT_PROGRESS.md; if objective is omitted, remove the entire ## Current Objective section from AGENT_PROGRESS.md rather than leaving a literal placeholder, so the file remains internally consistent.
5. Return target_dir, files_created, and files_skipped.