Skip to content

fix: harden coordinator prompt against context compression - #54

Open
jflowers wants to merge 1 commit into
unbound-force:mainfrom
jflowers:opsx/coordinator-prompt-hardening
Open

fix: harden coordinator prompt against context compression#54
jflowers wants to merge 1 commit into
unbound-force:mainfrom
jflowers:opsx/coordinator-prompt-hardening

Conversation

@jflowers

@jflowers jflowers commented Aug 2, 2026

Copy link
Copy Markdown
Contributor

Summary

Fixes #46 — the coordinator agent prompt (internal/agentkit/content/agents/coordinator.md) was compression-fragile. Its 6 behavioral constraints were expressed as unordered bullet points in a single "Rules" section, where critical constraints like "Never reserve files" and "Review every worker completion" would be lost under DCP context compression.

This restructures the prompt using patterns proven in the project's other agent files and the forge coordination skill:

  • Identity-first opening embedding key constraints ("NEVER reserve files or edit code directly") in the first sentence
  • Dedicated Critical Constraints section with uppercase MUST/NEVER keywords, positioned before the workflow
  • Numbered 8-step Protocol replacing the flat bullet list, with explicit forge_reviewforge_complete ordering
  • Structural regression test (TestCoordinatorPrompt_StructuralResilience) verifying 7 compression-resilience properties

How to Test

# Build with restructured prompt
make build

# Run all tests (including new structural test)
make check

# Run just the structural test
go test ./internal/agentkit/ -run TestCoordinatorPrompt_StructuralResilience -v

The structural test verifies:

  1. YAML frontmatter preserved (name, description, mode)
  2. Identity-first opening contains "NEVER" + "reserve"
  3. Section ordering: Critical Constraints < Protocol < Available Tools
  4. All 6 behavioral rule markers present (comms_init, reserve, forge_review, hivemind_store, comms_inbox, forge_broadcast)
  5. Every constraint line has uppercase RFC 2119 keyword
  6. Explicit forge_review BEFORE forge_complete ordering
  7. First 50% of body lines contain all critical constraints

How to Demo

Read the restructured internal/agentkit/content/agents/coordinator.md — the identity-first opening, Critical Constraints section, and numbered Protocol are self-evident. Compare against the previous version (flat bullet list) to see the structural improvement.

Key Files Changed

File Change
internal/agentkit/content/agents/coordinator.md Restructured from 22-line flat rules to 31-line compression-resilient format
internal/agentkit/agentkit_test.go Added TestCoordinatorPrompt_StructuralResilience (151 lines)
openspec/changes/coordinator-prompt-hardening/ OpenSpec artifacts (proposal, design, specs, tasks)

This PR was generated by /uf.finale (AI-assisted).

Restructure coordinator.md to survive DCP context compression:
- Add identity-first opening embedding key constraints (NEVER reserve files)
- Create dedicated Critical Constraints section before Protocol
- Add explicit forge_review BEFORE forge_complete ordering
- Use uppercase MUST/NEVER keywords for compression-resistant severity signaling
- Convert flat rules list to numbered 8-step Protocol

Add TestCoordinatorPrompt_StructuralResilience verifying 7 properties:
frontmatter, identity paragraph, section ordering, behavioral rule
markers, per-line RFC 2119 keywords, ordering semantics, and
compression resilience (first 50% of lines contain all critical
constraints).

Fixes unbound-force#46

Assisted-by: claude-opus-4
Generated with AI assistance (claude-opus-4)
@jflowers
jflowers requested a review from a team as a code owner August 2, 2026 18:44
@jflowers
jflowers requested a review from yvonnedevlinrh August 2, 2026 20:50
@jflowers jflowers self-assigned this Aug 2, 2026
@jflowers jflowers moved this to In Review 👀 in Unbound Force Planning Aug 2, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

Status: In Review 👀

Development

Successfully merging this pull request may close these issues.

bug: coordinator.md agent prompt is compression-fragile — critical constraints likely lost under DCP

1 participant