docs: agent on-disk anatomy concept

[diberry]

Summary

Developer-oriented concept doc explaining what it means on disk to be a Squad agent.

What's Covered

• Directory structure — .squad/agents/{name}/ layout
• charter.md — agent DNA, who writes it, who reads it, what it contains
• history.md — append-only learnings, what goes in, what doesn't
• Casting system — registry.json, policy.json, history.json, name allocation
• SDK relationship — how .squad/ runtime state maps to packages/squad-sdk/src/ code
• Agent lifecycle — how an agent exists (charter + roster + routing)
• Alumni pattern — what happens when an agent retires
• Context propagation — how agents share knowledge via team.md, routing.md, decisions.md

Format

• Developer-focused (not end-user)
• Real examples from the repo
• Code blocks for file structures
• Under 2000 words
• Follows team conventions (and not ampersands)

Context

Requested by Brady via Dina. Brady wanted a short doc explaining the on-disk anatomy of a Squad agent — this should help developers understand exactly what files exist, what they contain, and how they relate.

---

Working as: Flight (Lead)
Requested by: Dina (Brady asked for this)

[diberry]

EECOM Review — ✅ Approve with Notes

Excellent developer-focused concept doc. The distributed identity model is clearly explained (runtime state, SDK infrastructure, config overrides). Charter-as-DNA metaphor works well. Alumni pattern and casting system are well-documented.

Technical accuracy: Solid. Charter compiler flow is correct, history shadow feature properly described, SDK boundaries are accurate.

Scope assessment: 394 lines is substantial for a concept doc. Brady prefers small, strategic docs — this is on the larger end but justified given it's a foundational concept that developers will reference repeatedly. The structure and examples make it scannable.

Minor: Some sections could be tightened (e.g., "Key Takeaways" could be a bulleted summary rather than prose), but overall the length serves the complexity of the topic. Recommend merge.

[diberry]

Rewrite complete — agent-on-disk.md compressed and enhanced.

Changes:

• Trimmed: 298 lines → 152 lines (~49% reduction)
• Added: Human Team Members (👤) — Short section (~13 lines) covering:
  • No charter/history
  • Not spawnable (coordinator presents work, waits for input)
  • Participate in routing and reviews
• Added: @copilot Coding Agent (🤖) — Short section (~12 lines) covering:
  • No charter (uses copilot-instructions.md)
  • Not spawnable (works via issue assignment)
  • Creates copilot/* branches, opens draft PRs
  • Capability profile (🟢/🟡/🔴) in team.md

What was cut:

• Verbose who-writes-it/who-reads-it sections
• Redundant code examples
• Over-explained flows (kept the essentials)

Doc now hits Brady's preference for small, strategic docs while covering the full roster spectrum (AI agents, humans, @copilot).

—Flight

[diberry]

✅ APPROVE — Doc rewrite is technically sound and meets Brady's small+strategic preference.

Key findings:

• 298→152 line compression well-executed
• Charter, history, casting, SDK relationship all accurate
• Human members section conceptually sound
• @copilot section accurate (capability profile, copilot-instructions.md, issue-driven)
• No ampersands (meets style preference)

Minor: Line 13 typo 'spawnables agents' should be 'spawnable agents'. Consider it optional.

Ship it.

[diberry]

Closing — content pulled to local for reclassification. Agent-on-disk concept doc (with human member and @copilot sections) preserved at ../pr-435-agent-on-disk/ for future use as extension or re-submission.