Introduction
SCE workflow tutorial
Shared Context Engineering (SCE) keeps AI-assisted changes predictable: maintain durable project context, turn requests into scoped plans, implement one task at a time, and sync context after code changes.
1. Prepare the repository
Work from the correct branch, understand the working tree, ensurecontext/exists and reflects the project, and confirm your AI environment has the SCE commands, agents, and skills installed. Know the change goal, constraints, and success criteria before planning begins.
You can check whether SCE is ready by running:
sce doctor
This reports whether your machine, repository, config, hooks, and installed harness assets are ready for the SCE workflow. Ifsceis not installed yet, start with thegetting started guidebefore continuing.
If setup or context is missing, expect the agent to ask before bootstrapping or repairing it. The human remains responsible for architecture, risk, and final decisions.
Starting SCE in an existing codebase
Most teams do not start from an empty repository. They start with a codebase that already has architecture decisions, implicit conventions, old tradeoffs, and half-documented workflows.
For an existing codebase, do not begin by asking the agent to change code. First ask it to inspect the repository and draft the initial project context. Review that context like production documentation before using it to guide agent work.
Use the SCE workflow to bootstrap initial project context for this existing codebase. Do not change production code. Inspect the repository structure, build/test tooling, major modules, architecture boundaries, data flow, conventions, and existing documentation. Read git history for at least the last quarter to understand recent changes, recurring patterns, and active areas of the codebase. Create or update the initial SCE context files with: - project overview - architecture summary - key modules and responsibilities - build, test, lint, and validation commands - coding conventions - known risks and sharp edges - integration points - current agent workflow recommendations Where you are uncertain, mark the section as "needs human review" instead of guessing. After writing context, summarize what you found and list the highest-priority questions for the team.
2. Turn your change request into a plan
Start by describing the change in plain language.
Claude Code and OpenCode
Both harnesses expose SCE planning through slash commands. Use:
/change-to-plan [your change request]
Harness-neutral fallback
If your harness does not expose the SCE planning command directly, paste this into your AI coding assistant:
Use the SCE workflow. Read the repository context, clarify missing requirements, and create an implementation plan for this change. Write the plan to the canonical SCE plan directory. Break the work into small task IDs with goal, scope boundaries, done criteria, and verification notes. Do not start implementation yet.
The planning agent should read context, use skills, ask clarification questions when needed, and invite you to clarify or change anything through conversation until the plan is correct. It will then create or update a plan incontext/plans/, and break the work into stable task IDs such asT01,T02, andT03. Each task should capture its goal, boundaries, done criteria, and verification notes.
3. Run one task at a time
Continue with an approved task using the plan name or path and, when known, the task ID:
/next-task onboarding-flow T01
Don't worry if you are unsure what to run next. SCE will prompt you with the next step command.
The execution agent should review readiness first: resolve the plan, confirm the selected task, check for blockers, and keep the session to one task unless you explicitly approve more.
Best practice: start a new agent session for each task.
This keeps the agent focused, reduces context contamination from previous implementation details, makes review easier, and gives agent trace cleaner session boundaries. A task should be small enough that a reviewer can understand what changed, why it changed, and which checks prove it worked.
4. Confirm before implementation
Before editing files, the agent should stop and restate the task goal, scope boundaries, expected files, done checks, approach, trade-offs, and risks. Only continue after you confirm.
5. Implement, check, and capture evidence
During implementation, the agent should make the smallest in-scope change that satisfies the task. If out-of-scope work is required, it should stop and ask before expanding scope.
Each task should report evidence of what changed, which checks ran, and how the result was validated. Checks may include content inspection, targeted tests, linting, type checks, or a fast build.
You are invited to clarify or change anything through conversation so the task result is correct before moving on.
6. Sync context after each task
After an accepted implementation task, the agent should compare the changed behavior withcontext/and update current-state context files when needed. Code is the source of truth if context and code disagree.
7. Run the next task
If more tasks remain, start a new session for the next task:
/next-task onboarding-flow T02
Don't worry if you are unsure what to run next. SCE will prompt you with the next step command.
Each task repeats the same review, confirmation, implementation, checks, and context-sync cycle.
Repeat steps 3 through 7 until all planned tasks are complete.
8. Finish with validation and cleanup
The last step in an SCE plan is always a validation step. When the final task is complete, the agent should review the work against the plan success criteria, run applicable checks, confirm context accuracy, and perform allowed cleanup.
You are invited to clarify or change anything through conversation so the final task is correct before the workflow is considered complete.
After the workflow finishes, use sce trace to query what happened during the agent sessions. The Agent Traceability guide explains how to inspect prompts, tasks, evidence, and session handoff.