scope

name

scope

description

Use at the START of any task, before defining or building anything, to decide how the work should be carried out (one live session, a task contract, or a full agent team), how sharply it needs specifying, and whether it genuinely needs file-backed continuity. Session work is ticketless by default. Use when unsure whether a task needs a contract or just a session, or when a raw idea needs to become a well-defined task.

Scope: the front-door router

The first move for any non-trivial task. The recurring frictions of working with agents are all decided here: one live session, or a heavier vehicle?, can one agent do this?, does it need a human in the loop?, and how do I keep the agent from filling in the gaps I left?.

scope does four things and nothing else. It is a thin router, not an implementer. It sizes the task, picks the container, sets the clarification budget, decides whether durable task state is justified, then hands off. All the heavy work lives in the skills it routes to, and they only load once chosen, so context stays flat.

Do NOT start implementing, defining a contract, or spinning up anything until the container, clarification budget, and persistence decision are made. Sizing first, always. A ticket is a possible outcome, not a prerequisite.

Step 1: size it

Ask the minimum questions to resolve size. Do not run a full grill here. Judge on:

• Files / layers touched. One file vs many; one layer vs end-to-end.
• Blast radius. A reversible local edit vs prod / staging / auth / payments / migrations / deploy / integration config. High blast radius pulls toward a contract regardless of size.
• Parallelizable slices. Is this one thread of work, or several independent ones that could run at once?
• How specified it already is. Can you state the target in a sentence, or is it fuzzy?

Step 2: pick the container, then the lane

The container is the vehicle the work runs in. The lane is where that vehicle runs. They are two decisions, both made in this step, and the second one is the one that gets skipped.

Container	What it means	Pick when
session	One agent and the user, turn by turn, with the user watching	One reversible slice, the user wants eyes on it
contract	This session, gated by a written task contract first	Medium or large, or real blast radius (prod, auth, migrations, deploy)
team	A full multi-agent team, each agent on its own slice	Many parallel slices, multi-day, or high risk needing division of labor. Conditional: read the note below before picking this

The team container is optional and is not shipped with this workspace. It requires an attached team layer (see docs/team-layer.md). If you have not attached one, do not stall here: route to contract instead and split the work into sequential slices, one contract per slice. That is the honest trade. You lose parallelism, you keep the gate.

A container says how the work runs, never where. Where is a second question with one answer: launch location decides the lane (CLAUDE.md, house rules). A session is therefore not automatically this session.

• This workspace's own docs, configs, skills, and tasks/ files: proceed here. Maintaining the workspace is the workspace's job, and it is not project work.
• Changes to any file a project repo owns: route the execution to a session rooted in that repo. Size it here, hand it over there. Carry the container and the clarification budget with it; they are the output of this skill, and they travel.
• The same split applies to contract. The contract can be written here; the session that executes it runs where the code lives.

The reason is ownership, not configuration. A repo owns its files and its history from the day it is created, before it has any agent guidance, any tooling, or any tests. That ownership is what makes the work its work, and it is why the rule holds for a bare repo that has no CLAUDE.md at all. Booting into the project's own contract and tools is what the lane rule earns once that project has them: a dividend, not the foundation. A rule that fired only for configured repos would have to be re-argued for every repo, and would flip its answer the week one gained a config file.

One line of judgment: if the work changes files this workspace owns, it is workspace work. If it changes files a project repo owns, it is that repo's, however small the edit and whether or not it is code. Honoring that costs one session opened in the directory the files already live in, which is a directory change, not a ceremony.

Step 3: set the clarification budget

The lever against "the agent built something I didn't specify":

• sharp. The target is clear; the agent runs freely and only stops at real stop conditions.
• fuzzy. The target has unresolved forks; the agent must stop and ask at every unspecified decision rather than guessing. Route genuinely fuzzy work through grill-me before any building, or through a throwaway prototype when the fork is best resolved by building something rather than by talking about it.

Step 4: apply the persistence gate, then hand off

Do not write a task file for work that can be completed and verified in the current session. Code, diffs, commits, authoritative docs, and the conversation already preserve the result.

Create a task file only when at least one persistence condition is true:

• the work will continue in a later session;
• another agent or person needs a handoff;
• unresolved decisions, blockers, or substantial working context would otherwise be lost; or
• the user explicitly wants to keep the task as a record.

Do not create a task file merely because work is non-trivial, touches multiple files, was routed by a skill, needs a commit, or requires a confirmation during the current conversation. If it can be completed and verified in this session, keep it in the session.

Use an existing authoritative project doc, or an issue in your tracker if you use one, when it already owns the context. Do not duplicate it into tasks/. Then hand off:

Container	Hands off to
session (sharp)	Proceed in the lane step 2 picked: here for workspace work, or a session rooted in the project repo for project code. Normally without a task file.
session (fuzzy)	grill-me or a throwaway prototype first, then proceed in that lane. Normally without a task file, unless the work must pause or be handed off.
contract	define-task. Create or reuse a task file: work routed here has enough risk or complexity to require a durable contract. If no durable contract is needed, route it to session instead.
team (with a team layer attached)	The team layer's own setup workflow, per docs/team-layer.md. The team layer owns execution state, so avoid a duplicate task file.
team (no team layer attached)	Fall back to contract, sliced sequentially, and do write the task file. The continuity has nowhere else to live.

Notes

• tasks/ is the user's to curate. An agent working a slice does not read tasks/ on its own. If a task file is meant for one, hand over the path explicitly.
• Delete a completed task file by default once it no longer provides continuity. Keep a done record only when the user explicitly wants it, or when its durable context has no better home.
• Keep scope cheap. It is the 60-second habit at intake, not a ceremony. The depth lives downstream.