Stack + Your First Session

A situation you may recognize

A teammate asks the AI to “refactor the payment helper and open a PR.” One chat. Forty minutes. A huge diff appears, tests added, files renamed, a dependency bumped “while we were in there.”

Review feels impossible. Something smells wrong, but CI is green.

One clear prompt feels like enough. The tool keeps producing output, and stopping feels like leaving work on the table. One long session often mixes planning, implementation, and review. The model ends up making decisions that belong to you, and the diff becomes too large to verify.

That is not a failure of discipline. Chat-shaped tools trained us for one thread, one answer, keep going. Agent-shaped tools can still feel like that, until you look at the diff. Session 2 is about naming the pieces so you can split the work on purpose, not by accident.

Another word from job listings

Job posts throw nouns at you: harness, agent, orchestrator. They read like product names, something to install beside Cursor or Copilot. That reading is so common that vendors sometimes lean into it in marketing.

In most posts, the orchestrator is you: the person splitting work, setting direction, and checking results across focused sessions. The harness and agent are real software. The orchestrator is a role in the workflow, and it is the role listings assume you already have, even when they never say “you” out loud.

The stack: four pieces, slowly

One analogy many teams find helpful before the table:

Picture a kitchen. You decide what to cook and taste as you go. A recipe is instructions for one dish. The stove and knives actually change the food. The cook’s skill shapes how the recipe turns out.

Nothing here is about cooking for real. It is about who decides, who executes, and who checks, because those three jobs get blurred when a chat window keeps producing text.

AI-assisted work has a similar split:

Word	Plain meaning
LLM	The model that proposes text and plans (Claude, GPT, Gemini, …)
Harness	Machinery around the model, reads files, runs commands, holds session state
Agent	Harness + instructions for one job (“map this module,” “review this diff”)
Orchestrator	You: several focused sessions toward one goal

• The LLM proposes. It does not safely run your tests or respect git rules by itself.
• The harness executes: terminal, file edits, APIs. Different products package this differently.
• An agent is a job, not a coworker with memory of last week.
• The orchestrator splits work and checks results.

Read the table once, then try mapping your last AI session onto it. Where did you stop and redirect? Where did the harness run a command you did not expect? Where did the agent (the job brief) blur planning and implementation? That mapping is more useful than memorizing definitions.

The model proposes; the harness executes. Building safe harnesses is real engineering, which is why open-source projects around sandboxed CLI exist. When a listing says “harness experience,” they often mean comfort with tools that run commands on your repo, and with the habits that keep that power bounded.

Same ideas, different products

Products change names and layouts faster than this guide can track. The ideas below stay stable. Use the table to translate your team’s stack, not to pick a winner.

Idea	Cursor (example)	Claude Code (example)	Copilot-style (example)
Harness	IDE agent + terminal	CLI agent	Editor chat + extensions
Repo behavior rules	AGENTS.md, project rules	CLAUDE.md, settings	.github/copilot-instructions.md
Fresh focused session	New agent chat	New session, clear scope	New chat with scoped context
Reusable task steps	Skills	Skills / commands	Custom instructions
You coordinating	Split tasks; verify between steps	Same	Same

If your team uses one column, fine. If everyone uses something different, Session 3’s repo rules matter even more, they become the shared floor beneath every product.

Three gentle analogies

The tabs below offer three ways to feel the stack before you rely on the table alone. Pick whichever clicks; discard whichever fights you.

If an analogy fights you, return to the table. The table is the precise version.

Who does what: one turn in the loop

A single “turn” in an agent session looks mechanical on a diagram. In practice it is where most of the judgment hides; you decide whether to accept a file edit, rerun a test, or stop the loop because scope is creeping.

Watch the sequence below once, then imagine the payment-helper refactor: who should say “stop” before files change?

You set the goal. The agent asks the model what to do next. The harness runs a tool. The result returns. The loop repeats until the job is done, or until you stop, redirect, or check more carefully.

Notice what is not on the diagram: memory of last week’s chat, your team’s unwritten test conventions, or product judgment about what should ship. Those stay with the orchestrator, you, or with files in the repo that Session 3 covers next.

Your first session (when you are ready)

We suggest plan-only: the AI may read and think, but must not edit files yet.

That constraint can feel artificial if you are used to “just fix it.” It is deliberate. Plan-only forces the model to show its understanding before it touches code. The same way a good design review happens before implementation. You are not wasting time; you are buying a smaller, reviewable diff later.

Use the payment-helper task or any small refactor you have permission to touch. If you skip the live try, read the brief below as a template you can paste when you are ready.

Step 1: Start fresh

New agent chat or task. Avoid yesterday’s thread.

Step 2: Give a bounded brief

I want to refactor the payment helper, but do not edit any files yet.

Read the relevant files and tests. Map dependencies and call sites.

Propose the safest refactor plan. Include trade-offs and what you would test afterward.

Stop when the plan is ready for my review. No implementation.

That brief is orchestration in miniature: goal, allowed actions, limits, done. If you change one line before trying it, change the limits: that is usually what separates a plan session from a runaway diff.

Step 3: Ask one careful follow-up

When a plan arrives, ask something like:

• “What breaks if we change this part first?”
• “What test would fail if this plan is wrong?”
• “What should session two not touch?”

Step 4: Stop while it is still plan-only

If the tool starts editing, say stop, start fresh, repeat “do not edit files yet.” Session 3 shows how repo rules reduce how often that happens.

What three sessions look like

One prompt, “Refactor the payment helper and open a PR”, sounds efficient. Sometimes it works on a tiny codebase with forgiving tests. Often it reproduces the situation at the top of this session: a large diff, shallow tests, review fatigue, and a nagging sense that something slipped in “while we were in there.”

Three sessions with boundaries usually verify better than one long chat because each session has one job. The table below is a pattern to discover on your next task, not a law. Count the sessions after the fact: if you cannot name what each session was allowed to do, they were probably still one session wearing three hats.

Session	The AI’s job	Done when…
1	Map dependencies; propose a plan	You agree with the plan
2	Implement the plan + tests	Tests pass in the right package
3	Review the diff; draft the PR	Verification matches the risk

Session 3 introduces skills: saved, reviewed instructions for repeated jobs like implementation and review, so you are not inventing the brief from scratch each time.

Before Session 3

Session 3 opens with a story many teams know: the same correction typed in chat every week, and what changes when that rule lives in the repository.

Next: Session 3: Teach the Repo