Five Layers for a Replicable AI-Assisted Build Session

What made the session smooth

Pattern: dense context plus clear signals plus disciplined discipline plus a bias toward committing artifacts to git over keeping state in conversation.

Layer 1 — The three context tiers

Knowing where each piece of information lives is the highest-leverage decision for session smoothness.

Rule of thumb: if the same statement will be true across three future sessions, it belongs in the user or project tier. Session-tier content dies with the phase and should be allowed to die.

Layer 2 — The bootstrap protocol

The first 30 minutes of a new project is where most collaboration quality is decided.

What the human must provide

Eight items, minimum viable kickoff kit:

1. One-sentence project intent. Every other decision threads through this.
2. Primary user profile. Drives UX tradeoffs and voice.
3. Source material. Documents, links, reference projects to read.
4. Hard stack commitments. Things that will not be relitigated.
5. Collaboration preferences. Phase discipline, writing style, authority to capture.
6. Time horizon. A twelve-month goal is not a four-hour block and should not be treated as one.
7. Anti-patterns. Where previous projects went wrong.
8. Success definition. What "this worked" looks like — measurable and qualitative.

What the AI finds for itself

Nothing below should cost the human a keystroke:

• Current file state via ls and glob.
• Key symbols and interfaces via targeted search.
• Git state: branch, recent commits, open branches.
• Test suite state and smoke-trace output.
• Latest session retro or startup document if present.

What the AI asks about (with rec and reason)

Only when inference would be risky:

• Ambiguous scope (this phase versus next).
• Policy decisions (naming, privacy posture).
• Unknown integrations (provider choice, toolkit).
• Phase transitions.
• Irreversible actions (force-push, delete, rename with references).

Everything findable in memory, docs, code, or git is the AI's job. Not the human's.

The decision flowchart

if user-provided OR memory-covered         →  proceed autonomously
elif researchable via tools                →  research, report, proceed
elif reversible and low-risk               →  propose with rec, execute unless stopped
elif ambiguous OR irreversible             →  ask with rec and reason
elif in-flight collaboration               →  status file; re-read before commit
elif violates a frozen item                →  STOP, ask
elif touches another stream's territory    →  STOP, status file, wait

This flowchart runs on every turn. Externalizing it as durable guidance keeps it stable across sessions.

Layer 3 — The collaboration loop

Who talks to whom

┌─────────────┐
│   HUMAN     │  ← decisions, green lights, corrections, new intent
└──────┬──────┘
       │ chat
       ▼
┌────────────────────────────────────────┐
│  ORCHESTRATOR (main session)           │
│  planning, research, merge authority   │
└──┬──────┬──────┬──────┬────────────────┘
   │      │      │      │    (status files = async comms channel)
   ▼      ▼      ▼      ▼
 ┌────┐┌────┐┌────┐┌────┐
 │ A  ││ B  ││ C  ││ D  │  ← builders, one stream each, each in a worktree
 └────┘└────┘└────┘└────┘

The gate-signal alphabet

A durable vocabulary every builder and orchestrator inherits:

Cadence

• Human to orchestrator: every message, no scheduling needed.
• Orchestrator to builders: poll on human ping, or on a scheduled interval.
• Builders to orchestrator: push to status file and branch, asynchronously.
• Orchestrator to human: on explicit request, plus proactively on gate escalation.

Ambient awareness — when the desktop helps

The redesigned Claude Code desktop (parallel sessions in a sidebar, auto-worktree per session, integrated terminal and editor) provides ambient awareness of every active stream's live state without polling. This complements — does not replace — status files. Status files remain the durable, git-tracked audit trail; the sidebar is the live ambient view. Both layers are needed: durability and immediacy serve different purposes, and only the durable layer survives a session restart.

Layer 4 — The automation boundary

Not everything should be automated. Routine administrative work is a good candidate. Judgment about transitions, merges, and scope is not.

Four surfaces, not one

Cowork sessions are the closest layer to the human — they are amplification, not automation. Skills are interactive but procedural. Routines are headless and scheduled. Scripts are deterministic and synchronous. Each layer has a different latency, a different audience, and a different recovery posture when something goes wrong.

The boundary that matters: Routines run in the cloud against the repository and connectors, so they cannot touch the local desktop's filesystem or start a native app. Skills, scripts, and Cowork sessions all stay local for everything that does.

First three Routines worth shipping

1. Status digest. Scheduled every 20 minutes during active build. Reads every stream's status file and its branch tip, builds a color-coded state table, posts it as a comment on a pinned issue. Replaces the human poll-and-ask loop with ambient awareness.
2. Design-note review. Triggered on push to a stream branch when the status file flips to [DESIGN-READY]. Reads the design note against the kickoff prompt and relevant memory, produces a clean [DESIGN-ACK] commit or opens a review PR when changes are needed.
3. Merge-ready check. Scheduled nightly or triggered by an issue comment. Walks each stream branch for a [COMPLETE] marker, verifies build and tests, opens a merge PR with the standard merge-message template. Merge stays a human click.

First three Skills worth shipping

1. Setup new project. Interview-driven scaffold that writes the starter CLAUDE.md, MEMORY.md, first ADR, and initial implementation plan.
2. Scaffold parallel streams. Creates worktrees, generates kickoff prompts from a template, seeds status files, outputs the tab-open commands.
3. Local pre-event prep. Wraps shakedown, local launch, and pre-event backup as a single ritual.

Layer 5 — Where the human is always in the loop

Some decisions will never be delegated. Naming them explicitly prevents the automation layer from creeping into territory it shouldn't have.

What the AI does not ask the human again once memory captures it: stack preferences, writing style, phase-discipline interpretation, anti-pattern list, reference-project boundaries, transition language. Asking again is a memory failure, not a politeness.