Chat-Native Workflow

What is chat-native mode?

In chat-native mode (the default), s2s handles all orchestration inside the binary — intent classification, routing, state management, quality assessment — without making any LLM calls. The active chat session is the AI. s2s directs it with a focused task package, the AI generates the artifact, and s2s records the result.

This means zero AI tokens are spent on “what should I do next?” The AI receives exactly what it needs to produce the artifact and nothing else.

Session start

At the start of every session, read .s2s/live.md. It always contains:

• The active project and feature
• Current stage and status
• The next action to take

If there is no active work, live.md shows status: none and you wait for the user to submit a request. If there is active work in progress, follow the nextAction field.

For command reference, read .s2s/protocol.md. It is generated by s2s init and s2s update and contains the full syntax for every active command.

Submitting a work request

s2s request "add rate limiting to the API"

The orchestrator classifies the intent, selects the minimum stage route, creates a Change and Spec, and updates live.md with the route and first stage. The output tells you exactly which command to run next.

Two-phase stage pattern

For every artifact-producing stage (pm, research, design, engineering):

Phase 1 — get the task

s2s stage pm

Output includes:

• OBJECTIVE — what artifact to produce and why
• CONTEXT — prior stage artifacts, user request, intent classification
• ARTIFACT SPECIFICATION — exact content requirements
• File path — where to write the artifact
• WHEN DONE — the exact --submit command to run

s2s updates live.md with status: context_delivered and the next action. No LLM call is made.

Phase 2 — generate and submit

1. Read the task output carefully — it contains all the context you need.
2. Generate the artifact content in the chat session.
3. Write the artifact to the exact path specified.
4. Run --submit:

s2s stage pm --submit

s2s reads the artifact, runs quality checks, advances the ledger, and outputs the next action. live.md is updated with the result.

After submit — follow the next action

Three possible outcomes:

Quality passes, no gate:

[s2s] pm submitted · quality 91% ✓ · next: s2s stage engineering

Run the next stage.

Quality fails:

[s2s] pm submitted · quality 62% ✗ · threshold 85%
Issues: missing success criteria, no scope boundary defined

Fix the issues in the artifact file and re-run --submit.

Review gate created:

[s2s] pm submitted · quality 88% ✓ · gate created (gate_abc123)

Wait for the user to run s2s approve gate_abc123 or s2s reject gate_abc123.

Approval gates

When a gate is pending, live.md shows status: gate_pending. Do not proceed to the next stage. The user must explicitly approve or reject via:

s2s approve gate_abc123   # advance to next stage
s2s reject gate_abc123    # stop; user provides new direction

After approval, live.md is updated and you can proceed.

Session recovery

If you lose track of where the project is — session restarted, context scrolled away — read live.md:

cat .s2s/live.md

It always reflects the current state and next action. You do not need to re-run s2s status or re-read prior commands.

Switching chat clients

s2s governance files are client-agnostic. If you switch from Claude Code to Codex (or vice versa), the new client reads the same .s2s/guardrails/ files and live.md. The session picks up exactly where it left off.

engineering_exec stage

s2s stage engineering_exec spawns a configured AI agent inside an isolated git worktree to implement the code. This stage is different from the others:

• It does not use the two-phase task/submit pattern.
• It spawns a subprocess using the active execution template.
• The worktree is a clean branch separate from your working directory.

After engineering_exec completes, s2s records the result and updates live.md.