plan-forge aci-design.instructions.md

ACI Design Instructions

ACI = Agent-Computer Interface. Empirically validated against the SWE-agent ACI principle: the agent only performs as well as the surface lets it. Plan Forge ships 100+ forge_* tools — a single sloppy tool can degrade every agent that calls it.

---

The reference standard

When you add a new tool, pattern-match against forge_search — it is the gold-standard ACI surface in this repo. Read its handler in pforge-mcp/server.mjs, its description in pforge-mcp/capabilities.mjs, and its tests in pforge-mcp/tests/. If your new tool diverges from forge_search's shape, you need a reason.

What forge_search gets right:

• Bounded snippets — 80 chars each, never raw file contents
• Sparse fields — { source, recordRef, snippet, score, timestamp } (5 fields, no _internal leakage)
• Pagination metadata — total + truncated + hasMore + cursor
• Friendly empty path — { hits: [], total: 0, message: "Searched plans for 'X'; no matches. Try …" }
• Documented contract — every response field appears in description, inputSchema, and TOOL_METADATA.example.output

---

The 5 Rules

Rule 1 — Bound the happy-path payload to ~10 KB

Unbounded payloads (30 KB+ snapshots, 10K-event captures, full activity logs) blow the calling agent's context budget. The agent then skips later tool calls or hallucinates to fit. Both failure modes are silent.

Fix: return summary counts/status by default; offer a drill / verbose opt-in for details.

// ✅ default response under 1 KB; verbose opt-in for the rest
{
  ok: true,
  count: 47,
  recent: ['slice-3', 'slice-4', 'slice-5'],
  message: 'Pass verbose: true to drill into each event'
}

// ❌ unbounded
{ events: [/* 4,712 entries × ~80 fields */] }

If the default response would still exceed ~10 KB without losing essential context, paginate (Rule 3).

Rule 2 — Describe empty states explicitly

A bare { hits: [], total: 0 } reads as "the tool failed" to most agents. The agent then retries, re-formulates the query, or gives up.