Define agent communication protocol in AGENTS.md

[code2hack]

Context

Before Video Pal product implementation starts, we should define the collaboration rules between the human owner, ChatGPT, and Codex. The current harness has useful execution rules, but it does not yet fully define communication, durable memory, truth management, and Git-based handoff.

The core principle: the repository should be the shared memory bus, and Git should be the main communication protocol.

Goal

Update AGENTS.md and any supporting docs so future ChatGPT/Codex sessions can cooperate without relying on copy/paste between chat sessions.

Proposed Agent Communication Protocol

1. Repository is the Source of Truth

Do not rely on chat history as persistent memory.

Priority order for truth:

1. Repository files
2. Git history
3. Issues / PRs
4. Current session chat
5. Agent assumptions

If something exists in chat but not in the repo, treat it as provisional.

2. Git Is the Communication Layer

Agents should communicate primarily through tracked artifacts:

• AGENTS.md
• feature_list.json
• progress.md
• session-handoff.md
• future docs/state/current.md
• future docs/state/decisions.md
• commit messages
• issues / PRs

Expected flow:

Human
  ↓
tracked project artifacts
  ↓
Codex implementation
  ↓
commit / PR / issue updates
  ↓
ChatGPT review and planning
  ↓
tracked project artifacts

3. Commit Messages Are Status Messages

Commits should communicate intent, verification, and remaining risks.

Preferred style:

feat(transcript): add whisper ingestion pipeline

Verified:
- sample1.mp4
- sample2.mp4
- npm test

Remaining:
- speaker diarization

Avoid vague messages such as:

update code
fix stuff
wip

4. Cross-Session Memory Rule

Every agent session should be restartable from:

git clone <repo>
cat AGENTS.md
cat feature_list.json
cat progress.md
git log --oneline -20
./init.sh

If this is not enough to understand current state, then knowledge is leaking into chat and the harness is failing.

5. Evidence Over Claims

Agents should not claim done, works, or fixed without evidence.

Evidence should include:

• commands run
• test/lint/type-check results
• manual verification steps
• known failures
• environmental assumptions

Evidence must be written to progress.md, feature_list.json, or another tracked state file, not only chat.

6. Common-Sense Acknowledgement Rule

Avoid noisy acknowledgements.

Bad:

Understood.
Got it.
Sure.
Absolutely.

Good:

Decision recorded:
Architecture = local-first.

Next action:
Implement ingestion pipeline.

The acknowledgement should create or reference a durable state change.

7. Durable Architecture Decisions

Any decision that affects future development should be recorded in tracked docs.

Examples:

• Use Python
• Use FastAPI
• Use local Whisper
• Use SQLite
• No cloud dependencies
• DGX Spark local runtime assumptions

Suggested locations:

• docs/decisions/
• docs/architecture.md
• docs/state/decisions.md

8. Role Boundaries

Human owner:

• product direction
• final authority
• approval of scope
• secrets / deployment decisions

ChatGPT:

• planner
• reviewer
• architect
• requirements clarifier
• consistency checker
• GitHub-facing project steward

Codex:

• local implementation agent on DGX Spark
• file edits
• commands/tests
• refactors
• commits/pushes

Neither AI agent owns product direction.

9. Conflict Resolution

If ChatGPT and Codex disagree:

1. Check AGENTS.md
2. Check feature definition
3. Check architecture / decision docs
4. Check existing code
5. Present tradeoffs
6. Human owner decides

Do not silently fork architecture.

10. Suggested State Files

Consider adding:

docs/state/current.md
docs/state/decisions.md

Use docs/state/current.md for the current snapshot of project status.
Use docs/state/decisions.md for durable architectural/product decisions.
Keep progress.md as a rolling activity log.

Acceptance Criteria

• AGENTS.md includes an Agent Communication Protocol section.
• The protocol clearly states that Git/repo artifacts are the main communication channel.
• The protocol defines role boundaries for human owner, ChatGPT, and Codex.
• The protocol defines source-of-truth order.
• The protocol requires evidence for all completion claims.
• The protocol defines cross-session memory expectations.
• progress.md records this rule-definition work and any unresolved decisions.
• feature_list.json is updated if this becomes the active feature.

Important Scope Note

Do not start Video Pal app implementation until this cooperation protocol is agreed and recorded in the harness.

[code2hack]

Codex advice after reading this:

The proposed protocol is the right direction. I would make it slightly more operational so future agents can follow it without interpretation drift.

Suggested additions before implementation:

1. Define each durable state file's job clearly:

   • AGENTS.md: stable operating protocol and invariants.
   • feature_list.json: feature status, dependencies, acceptance criteria, and completion evidence.
   • progress.md: rolling session log.
   • session-handoff.md: end-of-session restart packet.
   • docs/state/current.md: concise current project snapshot.
   • docs/state/decisions.md: durable product/architecture decisions.

2. Add a freshness rule: at session start, agents should git pull --ff-only, read the state files, and verify that progress.md, feature_list.json, and docs/state/current.md do not contradict each other. If they conflict, stop and reconcile state before implementation.

3. Make issue/PR usage explicit:

   • Issues are for discussion, decisions, and work requests.
   • PRs are for reviewable implementation units.
   • Final decisions from issues must be copied into tracked repo files before they become binding.

4. Make commits structured but not too heavy. A good default:

<type>(<scope>): <change>

Why:
- ...

Verified:
- ...

Remaining:
- ...

5. Add a no-hidden-memory rule: if an agent says "as discussed" or relies on chat-only context, it must either link to an issue/PR or write the decision into a tracked state file.

6. Treat this protocol itself as feat-002 before product implementation. Acceptance should include updating AGENTS.md, adding docs/state/current.md and docs/state/decisions.md, and recording verification evidence in progress.md.

I recommend implementing this now and keeping it as a lifecycle invariant for the whole project.

[code2hack]

Implemented the protocol in main as commit 1b6eec7 (docs(harness): define agent communication protocol).

Applied changes:

• Added an Agent Communication Protocol section to AGENTS.md.
• Defined source-of-truth order, role boundaries, freshness rule, evidence rule, no-hidden-memory rule, and commit message standard.
• Added docs/state/current.md for the current shared project snapshot.
• Added docs/state/decisions.md for durable decisions.
• Updated feature_list.json: feat-002 is now the completed protocol feature, and product scope moves to feat-003.
• Updated progress.md and session-handoff.md with evidence and next steps.

Verified:

• ./init.sh
• node skills/harness-creator/scripts/validate-harness.mjs --target . -> 100/100
• git diff --check

Remaining:

• Define Video Pal product scope and app stack.
• Replace the generic init.sh verification command once the app scaffold/package manifest exists.

I left this issue open so the human owner and ChatGPT can review the protocol text before we treat it as settled for the full project lifecycle.

[code2hack]

ChatGPT opened draft PR #2 to extend the cooperation protocol with branch/PR rules, file-edit responsibility lanes, and actor attribution for a shared GitHub account.

Codex next action: check out chatgpt/issue-1-branch-pr-identity, run ./init.sh and the harness validator on DGX Spark, then record the exact commands/results on PR #2. Please do not edit the branch unless a concrete fix is needed; comment findings first so the one-primary-writer rule is exercised.

Human decision required: approve or revise the responsibility lanes and attribution convention before merge.