archyl-harness

Archyl Harness — Work Session Protocol

You are working under the Archyl Harness: every unit of work is declared, visible to other agents, and closed with an outcome. This is what stops two agents from silently rewriting the same service, and what keeps the architecture model in sync with what was actually built.

The loop

plan_work → start_work_session → work → (heartbeat) → finish_work_session

0. Plan — for non-trivial tasks

plan_work(projectId: <uuid>, task: "<the feature or change>")

Returns an implementation plan grounded in the documented architecture: ordered steps referencing real C4 elements, the constraints (guardrails and ADRs) that bind them, and risks from work in progress. Follow it, or explain in your finish summary why you deviated. Skip this step for trivial edits.

1. Start — BEFORE touching any file

start_work_session(
  projectId: <uuid>,
  task: "<what you are about to do, one or two sentences>",
  agentName: "claude-code/<user or CI job>",
)

Returns a briefing you MUST read before coding:

• Session ID — keep it, every later call needs it.
• Gate — allow: proceed. warn: proceed, but address every listed reason (a guardrail that applies, or another agent on the same elements). If the start is rejected (deny, only with exclusive: true): do not work around it — report the conflict to the user.
• Leased elements — the C4 elements you are now the announced worker on.
• Conflicts — elements someone else is actively working on. Coordinate or avoid changing them.
• Context — the relevant elements, ADRs, guardrails, and owners for the task. Prefer this over re-deriving architecture from the repo.

Use exclusive: true when your change must not race with anyone (schema migrations, contract changes).

2. While working

• Long task (> ~20 minutes)? Call heartbeat_work_session(sessionId) — sessions expire after 30 minutes without a heartbeat and lose their leases.
• Unsure of blast radius before an edit? impact_of(projectId, element).
• Check who else is active: list_work_sessions(projectId, activeOnly: true).
• Learned something the code cannot show — a deployment quirk, a fragile spot, a historical reason? remember(projectId, title, content, element?, kind: note|convention|pitfall). One memory per fact, pinned to the element it is about. Give it a title, and weave the knowledge graph: [[Other Memory Title]], [[ElementName]] and [[ADR-3]] in the content become navigable links (a link to a not-yet-existing title attaches when that memory is created). Re-stating a fact that already exists does not create a duplicate: it confirms the existing memory, and the response says so (deduplicated: true). A near-but-not-identical memory is stored and reported in similarTo — read it, and supersede rather than contradict.
• Working somewhere unfamiliar? recall(projectId, query, sessionId) first — previous agents may have left exactly the warning you need. Ranking blends meaning with words, so ask in your own vocabulary: a memory about "throttling" surfaces for a query about "rate limiting". Pass your sessionId: it is what lets you credit those memories when you finish.
• Memory has a lifecycle — keep it TRUE, not just full:
  • a recalled memory proved accurate? confirm_memory(projectId, memory) — resets its freshness so it keeps outranking stale information.
  • a fact changed? remember(..., supersedes: "Old title") — never leave two contradictory versions live; the old one keeps its place in history.
  • unconfirmed memories decay in ranking (45-day half-life); pitfalls outrank notes. Write pitfalls when you hit one.