fix: harden coordinator prompt against context compression

[jflowers]

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_review → forge_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).

[sonupreetam]

Review Council

Ran the review council (6 Divisor agents). Overall well-executed — the restructuring is sound, the test is thorough, and the OpenSpec artifacts are exemplary. One intent drift finding and minor notes below.

Merge note: This PR, #57, and #58 all insert test functions at line 152 of agentkit_test.go. Suggest merging this one first, then rebasing #57 and #58.

[yvonnedevlinrh]

Approval: PR #54 — fix: harden coordinator prompt against context compression

Testing Methodology

Reviewed using /uf.review-pr 54 with a custom-built UF binary (latest changes merged into main) after running /uf.init to scaffold the agent kit. The review command executed all steps of the automated review pipeline:

• CI Status: Build and Test — PASS
• Local Pre-flight: make check (go vet + go test with race detector) — PASS
• Spec Alignment: All 8 functional requirements (FR-001 through FR-008) verified against the OpenSpec artifacts
• Constitution Compliance: No violations (Principles I, III, IV assessed as PASS; Principle II N/A)
• Prior Review Feedback: Both findings from the review council (@sonupreetam) confirmed addressed in follow-up commits (cc016c8, e65479c)

Local Verification

Completed manual local verification:

• Checked out PR branch and ran make check — all tests pass
• Reviewed restructured coordinator.md and confirmed all 6 original rules preserved with behavioral parity
• Ran TestCoordinatorPrompt_StructuralResilience — all 7 sub-tests pass
• Reviewed OpenSpec artifacts (proposal, design, specs, tasks) — complete and consistent
• Confirmed .gitignore addition (.uf/feedback/) is benign (merged from main)

Findings

Two LOW-severity observations, neither blocking:

1. LOW — .gitignore:9: .uf/feedback/ addition is unrelated to PR scope; entered via merge from main. Informational only.
2. LOW — agentkit_test.go:321-336: compression_resilience sub-test uses a 50% line-count heuristic as a compression proxy. Acknowledged in spec as a conservative structural heuristic. The test guards against constraint drift toward the end of the file, which is the intended value.

Additional findings from doing a deeper dive

MEDIUM: Off-by-one in frontmatter/body splitting

internal/agentkit/agentkit_test.go:175

body := text[4+endIdx+4:] // skip past "\n---\n"

The comment says it skips "\n---\n" (5 chars) but the code advances only 4 chars, leaving a stray leading \n in body. Tests tolerate this because strings.Split(body, "\n\n") produces an empty leading element that gets filtered out, and the extra line in bodyLines doesn't shift halfLen enough to matter for the current 31-line file. Still, the comment is factually wrong and body contains content the code didn't intend.

Fix: text[4+endIdx+5:] or update the comment to // skip past "\n---".

LOW : Defensive t.Skip branches unreachable with current embedded content

internal/agentkit/agentkit_test.go:263-264, 287-288

The constraintsSection == "" guards can never fire because coordinator.md contains both ## Critical Constraints and ## Protocol. These are reasonable defensive guards for future-proofing, but have zero test coverage themselves.

Verdict

APPROVE — Well-scoped change with complete spec-first workflow, comprehensive structural tests, and all prior review feedback addressed. No blocking findings.

[yvonnedevlinrh]

Manual Testing Summary

PR #54 hardens coordinator.md — the coordinator subagent prompt loaded when a forge session spawns workers. Unlike a command prompt (/forge), this file cannot be invoked directly. It is only loaded when the forge workflow creates a coordinator subagent.

Testing Attempted

Manual testing of the forge workflow was performed during PR #55 review (same underlying mechanism). Two tasks were run via /forge:

1. A small rename task (3 edits across 2 markdown files)
2. A larger multi-file task (7 files, 22 new tests)

In both cases, the agent bypassed the forge workflow entirely — no forge_decompose, forge_spawn_subtask, or worker spawning occurred. The coordinator subagent was never instantiated, so the hardened coordinator.md prompt was never loaded or exercised.

What could not be verified

• Whether the restructured prompt (identity-first opening, Critical Constraints before Protocol, RFC 2119 keywords) survives context compression during a real coordinator session
• Whether the "NEVER reserve files" and "MUST call forge_review BEFORE forge_complete" constraints hold under compression

What the automated tests verify

TestCoordinatorPrompt_StructuralResilience (7 subtests, all passing) confirms:

• YAML frontmatter integrity (name: coordinator, mode: subagent)
• Identity-first opening paragraph contains NEVER + file reservation prohibition
• Section ordering: Critical Constraints → Protocol → Available Tools
• All 7 behavioral rules present (comms_init, reserve, edit code, forge_review, hivemind_store, comms_inbox, forge_broadcast)
• Every constraint bullet has an uppercase RFC 2119 keyword (NEVER/MUST/ALWAYS)
• Single constraint line connecting forge_review, BEFORE, and forge_complete
• First 50% of body contains all critical constraints (truncation resilience)

Conclusion

Manual verification was not achievable — the coordinator subagent is only loaded during forge worker orchestration, which agents declined to use. The automated structural tests are the primary verification for this PR's claims.