hierarchical-agent-files

Hierarchical Agent Files Scaffold

Trigger

• Use when a workspace needs a parent-plus-children agent-file hierarchy where each nested folder carries its own four-file contract and the parent carries the canonical progress-scope rule.
• Use when the single-workspace agent-files skill is not enough because two or more sibling nested workspaces must share a common parent mission and a common harness.
• Do not use for a flat, single-folder contract; route to agent-files.
• Do not use for trees deeper than parent + direct children; grandchildren are out of scope in this version.
• Do not use to retrofit hierarchy onto an existing hand-edited parent that already has non-trivial content in its four files unless overwrite=true.

Inputs

• parent_dir: directory where the parent four-file contract is scaffolded
• parent_mission: one- or two-sentence long-term mission statement written into the parent AGENT_GOAL.md; required so the contract is internally consistent on first read. It must not include reusable workflow rules, current state, next steps, or transient objectives.
• parent_objective: optional transient in-flight objective for the parent AGENT_PROGRESS.md; it must not define permanent mission, scope, policy, or success criteria
• parent_name: short name used in child cross-references; defaults to basename(parent_dir) with trailing slash stripped
• children: non-empty list of direct-child workspaces, each with:
  • relative_dir: single path segment (no /, no .., not absolute)
  • mission: child's one- or two-sentence long-term mission statement; it must stay within the parent mission and avoid reusable workflow/current-state details
  • objective: optional transient child in-flight objective
• overwrite: when true, existing files are replaced through an explicit scaffold overwrite; otherwise compatible existing parent and child files are recorded in files_skipped per node, immutable AGENT.md files are verified rather than patched, and hierarchy changes or verifications run only after upstream and hierarchy compatibility checks pass