Agents

Specifications for evolving multi-agent orchestration systems across Pantheon generations.

---

TL;DR — 60-Second Start

If you are new here, do this in order:

1. Read the workspace instructions/policies provided by your tooling (for example: editor instructions, harness prompt, or run manifest).
2. Pick the version you are changing:
   • Pantheon-v1/
   • Pantheon-v2/
   • Pantheon-v3/agents/
3. Decide your change type:
   • Clarification (wording only, no behavior change)
   • Behavior change (contract/flow/ownership changes)
4. Edit only the smallest relevant files.
5. Run the checklist in Contribution Quality Checklist.
6. Open a PR with explicit compatibility notes.

Quick branch start:

git checkout -b docs/<short-change-name>

---

Choose Your Workflow

1) Clarification-only update (fast path)

Use this when intent stays the same and wording gets clearer.

Typical scope

• One or a few *.agent.md files in a single version
• Optional small README/docs wording improvements

Required in PR

• State explicitly: "clarification-only, no behavior change"
• Note any terms you normalized

2) Behavior change (contract-aware path)

Use this when you change authority, delegation, artifact ownership, or execution flow.

Typical scope

• Agent spec(s) plus corresponding version contracts/docs
• In Pantheon-v2, usually includes one or more of:
  • Pantheon-v2/.pantheon/guides/pantheon-system.md
  • Pantheon-v2/.pantheon/guides/ARCHITECTURE.md

Required in PR

• Before vs after behavior summary
• Migration notes across affected versions
• Any sequencing constraints (for example: parallel-ready vs sequential-blocked from v2 contract language)

---

Harness Quickstarts

VS Code + GitHub Copilot (visible quickstart)

1. Open core context:

code README.md Pantheon-v2/.pantheon/guides/pantheon-system.md

2. Open your target files (example):

code Pantheon-v3/agents/bragi.agent.md Pantheon-v2/agents/bragi.agent.md

3. Use a focused prompt:

Read the workspace instructions/policies provided by your tooling and the target version contract files.
Draft a minimal patch that [clarifies behavior / changes behavior] for <target-file>.
Return: (1) patch, (2) compatibility note, (3) migration note if behavior changed.

4. Apply the patch, run the checklist below, then commit.

OpenCode CLI (template)

<opencode-cli> session start --workspace .
<opencode-cli> ask "Compare target role behavior across Pantheon-v1, Pantheon-v2, Pantheon-v3"
<opencode-cli> ask "Generate minimal patch for <target-file> with compatibility note"

Generic CLI harness (template)

agent-cli run --repo . --task "Load workspace instructions/policies + target version files"
agent-cli run --repo . --task "Propose minimal docs/spec patch"
agent-cli run --repo . --task "Summarize compatibility + migration impact"

Generic API/SDK harness (template)

1) Send your workspace instructions/policies + target version contracts/spec files.
2) Request output as unified diff + migration summary.
3) Validate touched paths are in-scope and real.

---

Visual Map

Decision flow (Mermaid)

flowchart TD
    A[Start change] --> B{Clarification only?}
    B -->|Yes| C[Edit smallest set of files in one version]
    B -->|No| D[Update spec + related contract docs]
    C --> E[Run quality checklist]
    D --> F[Write migration notes across versions]
    E --> G[Open PR]
    F --> G

Loading

Repository map (ASCII)

Agents/
├── README.md
├── CONTRIBUTING.md
├── CODE_OF_CONDUCT.md
├── SECURITY.md
├── LICENSE
├── Pantheon-v1/
│   ├── .pantheon/
│   │   └── guides/
│   │       ├── ARCHITECTURE.md
│   │       ├── pantheon-system.md
│   │       └── diagrams/
│   └── agents/
│       └── *.agent.md
├── Pantheon-v2/
│   ├── .pantheon/
│   │   └── guides/
│   │       ├── pantheon-system.md
│   │       ├── ARCHITECTURE.md
│   │       └── diagrams/
│   └── agents/
│       └── *.agent.md (+ worker specs)
├── Pantheon-v3/
│   ├── .pantheon/
│   └── agents/
│       └── *.agent.md
└── .pantheon/
    └── runs/<run-id>/

---

Version Map and Migration Guide

Version quick map

Version	Primary shape	How to use it safely
Pantheon-v1	Early-generation agent specs	Treat as baseline history. Avoid retrofitting modern assumptions without clear notes.
Pantheon-v2	Most explicit system contract and architecture docs	Use pantheon-system.md as authoritative for v2 ownership/delegation/run-root behavior.
Pantheon-v3	Current agent catalog under Pantheon-v3/agents/	Keep role language consistent and document non-equivalent behavior vs v2 when relevant.

Practical migration playbook

1. Identify source and target version(s).
2. Compare role boundary and delegation semantics first.
3. Separate wording differences from real behavior differences.
4. Port intent into the target version’s structure (do not copy blindly).
5. If behavior differs, write explicit migration notes.
6. Keep older versions stable unless intentional backport is required.
7. Prefer explicit "not equivalent across versions" over silent approximation.

---

Contribution Quality Checklist

Use this before every PR:

• I followed the workspace instructions/policies provided by my tooling.
• My changes are scoped to the minimum necessary files.
• Every referenced path/link exists in this repository.
• I did not edit root .github/ or .opencode/.
• For behavior changes, I updated related contracts/docs.
• I included compatibility/migration notes when semantics changed.
• Terminology is consistent across touched versions/files.

Suggested reviewer spot-check:

• One-pass scan: can a new contributor understand what changed and why in under five minutes?

---

Deep References (when you need full context)

• v2 system contract: Pantheon-v2/.pantheon/guides/pantheon-system.md
• v2 architecture companion: Pantheon-v2/.pantheon/guides/ARCHITECTURE.md

---

Governance

• Contribution process: CONTRIBUTING.md
• Code of Conduct: CODE_OF_CONDUCT.md
• Security policy: SECURITY.md
• License: LICENSE Best used for repeatable, scriptable review pipelines.

Generic API/SDK harness (template)

1) Send context set: AGENTS.md + target version contract files.
2) Request output format: unified diff + compatibility summary.
3) Validate response by checking:
   - touched files are in scope
   - no cross-version drift
   - migration note exists when behavior changes

Best used when integrating documentation checks into internal automation.

---

How to add or evolve an agent spec safely

Use this procedure for both new specs and behavioral updates.

A. Before editing

• Locate nearest system contract for the target version.
• Identify the agent’s current role boundary and dependencies.
• Decide whether this is additive, clarifying, or behavior-changing.

B. During editing

• Keep the agent’s objective, inputs, outputs, and escalation conditions explicit.
• Preserve established section structure unless the version standard changed.
• If introducing a new dependency/delegation path, update the corresponding architecture/system docs.

C. After editing

• Re-read changed files as a first-time contributor (scanability + correctness).
• Verify naming consistency for agent names, artifact paths, and version labels.
• Add migration notes in PR description if semantics changed.

Safe-change rule of thumb:

• Clarification-only change: same behavior, clearer wording.
• Behavior change: update related contracts/architecture docs and call out migration impact.

---

Quality and review expectations

Reviewers should be able to validate the change quickly.

Minimum quality bar:

• Clear, testable statements (avoid vague wording like “usually” without conditions).
• No contradiction with higher-priority contracts in the same version.
• Consistent terminology across touched files.
• Explicit migration notes for behavior changes.

PR checklist:

• Change is scoped and atomic.
• Paths and links are valid.
• Related docs were updated (if behavior/contracts changed).
• Compatibility impact is documented.

---

Compatibility and migration guidance across Pantheon versions

Use this map when porting ideas or normalizing behavior.

Version	Primary shape	Contributor implication
Pantheon-v1	Early role set and conventions	Treat as historical baseline; avoid introducing modern assumptions without explicit note.
Pantheon-v2	Formal orchestration contract + architecture docs	Use as the most explicit reference for run-scoped artifacts, ownership, and delegation rules.
Pantheon-v3	Agent catalog under Pantheon-v3/agents/	Keep naming and structure consistent with v3 layout; document deltas vs v2 when behavior differs.

Migration playbook:

1. Identify source and target version(s).
2. Compare role boundaries and delegation rules first.
3. Port intent, then adapt wording to target version structure.
4. Record non-equivalent behavior as a migration note (do not hide it in wording).

When uncertain, prefer explicit “not equivalent across versions” notes over silent approximation.

---

Governance and project policies

• Contribution process: CONTRIBUTING.md
• Code of Conduct: CODE_OF_CONDUCT.md
• Security policy: SECURITY.md
• License: LICENSE