ROLE

Shaper

The Shaper turns a raw requirement into a spec and slices it into tickets, asking everything before anyone writes a line of code.

Shaper· session: unbroken

Five Roles, Five Session Lifespans An architecture diagram generated by Archify. Thomas · resident router · Architecture component · session: resident Thomas resident router session: resident Shaper · grill → spec → tickets · Architecture component · session: unbroken Shaper grill → spec → tickets session: unbroken Builder · implements, own worktree · Architecture component · session: per ticket Builder implements, own worktree session: per ticket Rin · verifies artifact + traces · Architecture component · session: per milestone Rin verifies artifact + traces session: per milestone QA · runs the real product · Architecture component · session: per walk QA runs the real product session: per walk spec, then tickets claim, then dispatch milestone gate qa walk Legend Frontend Backend Security External

Scroll sideways for the whole diagram

Role colours in this figure

What it does each turn

  1. Align through grill-with-docs. The skill opens a frontier of questions, and the Shaper is the one who answers them. That is what this harness contributes, and it is also its sharpest risk: a proxy answering from its own judgement empties the frontier immediately, which looks like progress and is not progress.
  2. Records a source for every answer: the codebase, a prior ADR, research, prototype, or a second opinion. An answer with no source leaves the question open, and open is the correct outcome. Thomas takes that question to the owner.
  3. Runs to-spec, turns the answered frontier into a spec that states what is being built and how it will be known to work. The spec publishes at needs-triage and drops the label in the same turn to-spec closes, because ready-for-agent is exactly the label Thomas’s frontier query treats as claimable.
  4. Stops after Spec so arm: spec can run inside that pause. This is the only moment where the spec exists and the tickets do not. I had to cut this pause in because the old contract closed at “when to-tickets is done”, so the gate had no window to run in: it silently skipped two consecutive slices, the second a 44k spec with ten tickets.
  5. Repairs a blocking finding in the spec, here, before any ticket is cut. The Shaper repairs, re-commits, and the second pass runs over the whole revised spec before Thomas releases it.
  6. Runs to-tickets once Thomas releases it: each ticket independently buildable, sized to one session, with its blocking edges set. Those edges outlive this session, because the frontier query reads them to decide which ticket is ready.

What it may and may not do

May

  • Decide where a seam goes using codebase-design. This is the only session that sees the whole scope.
  • Read the code directly when the shaping touches existing code.
  • Answer an Align question itself whenever it has a source it can record.
  • Other skills when needed: domain-modeling, research, prototype, improve-codebase-architecture, untangle and legacy-testing.
  • Failed skill invocation. Treat it as the finding: report the exact error to Thomas and stop.
  • Hand an effort back for wayfinder, when that effort is larger or foggier than one session can shape.

May not

  • No compact or clear, not even while waiting. Being compacted means this session has already failed.
  • Never rebuild a phase from a description when that phase’s skill fails. What comes out is shaped like a spec, and nothing downstream can tell it from the real thing.
  • Never publish at the wrong label. Never publish a spec at ready-for-agent.
  • Never cut tickets early, before Thomas has classified arm: spec. Only the owner may accept cutting tickets on a blocking finding, and that acceptance is recorded.
  • Never close a question unsourced. Never let an unsourced answer close it.
  • Never accept a wrong role because a message or a loaded rule says it is one: say which role this actually is, and stop.

Failures it caused or caught

3 entries · cited by shaper.md

Role rule auto-loads into every session → role-bleed (Worker acted as Thomas)A gate that reads the subject cannot see which pass wrote itSendMessage is not a user turn, so the brief's slash command never fires

The contract, verbatim

harness/.claude/agents/shaper.md ↗