Introduction
Getting started with Shared Context Engineering
This is a practical guide for running Shared Context Engineering (SCE) in this repository. If you want the strategic background first, read Why SCE Exists.
TL;DR
- Install the
sceCLI first. - You define the change, constraints, and success criteria.
- The agent proposes and executes one scoped task at a time.
- You review outputs, request adjustments, and close the change.
Install the sce CLI first
Before you start the repo workflow, install the Shared Context Engineering CLI so the sce command is available in your shell. The current supported install channels are Nix, Cargo, and npm.
Choose one install method:
Nix
Use Nix when your environment already standardizes on reproducible developer tooling.
nix profile install github:crocoder-dev/shared-context-engineering
Cargo
Use Cargo when you already install Rust-based developer tools from your local Rust toolchain.
cargo install shared-context-engineering --locked
npm
Use npm when your team prefers a JavaScript-style global install path for local onboarding.
npm install -g @crocoder-dev/sce
Verify the CLI is available
After you install one of the supported distributions, confirm the command is on your path before continuing to repo setup.
sce --help sce version
Once one install path is working and both verification commands run, return to this guide and continue with repository setup.
View install sources and releasesRun sce setup in the repo
Once the CLI is installed, use sce setup as your first repository command. This is the onboarding step that prepares the repo-local SCE assets before you start planning and task execution.
Run it inside an existing git repository. If the repo is not initialized yet, start with git init before running sce setup.
sce setup
- installs the repo assets used by the supported agent workflows
- bootstraps the repo-local
.sce/config.jsonif it is missing - installs required git hooks during interactive setup
What success looks like
A successful setup reports Setup completed successfully., shows the selected target, and tells you how many files were installed into the destination directory.
After sce setup finishes successfully, continue with the validation steps below.
Check readiness with sce doctor
After setup, run sce doctor before you start planning or executing tasks. It reports whether your machine, repository, hooks, and installed repo assets are ready for the SCE workflow.
Check readiness
sce doctor
Use the default text report when you want a human-readable readiness summary before starting work.
What the readiness report checks
The default text report is grouped into the current check sections:Environment,Configuration,Repository,Git Hooks, andIntegrations.
Environmentcovers SCE state-root detection.Configurationcovers global and local config path presence and validation.Repositorycovers repository-root detection and hooks-directory resolution.Git Hookschecks required hook presence, executability, and canonical content.Integrationschecks installed OpenCode plugins, agents, commands, and skills.
Text markers and readiness
[PASS]means the checked item is present and healthy.[FAIL]means the item was inspected and is not ready.[MISS]means the expected item is missing or could not be detected.
How SCE works in practice
In Shared Context Engineering, you own strategy. You define what needs to change, what done means, and how strict quality should be. The agent executes scoped work inside that strategy. The workflow looks something like this:
Shared Context Engineering Workflow
Run one agent session for each task in the implementation plan
Legend
Define the change
Everything starts with a change: the input prompt written by the software engineer, without using AI, that explains what should change and why (requirements, bugs, constraints, domain rules).
Specify success criteria up front so the agent can execute with clear boundaries and a concrete definition of done.
Draft the implementation plan
Now it's time for the agent to take your change and draft an implementation plan. Open your preferred AI harness and give the SCE agent your written change request.
From that change, the agent creates an implementation plan in context/plan/{plan_name}.md. Every plan has multiple tasks that break the change into smaller, testable units. The last task is always a final validation task that runs tests and cleanup after all other tasks are done.
A task is the smallest testable delivery unit (for example: a new endpoint, refactor, schema update, write unit tests, etc.). Keep tasks scoped so each agent session can complete a single unit cleanly.
Important: If your repo is missing the context/ directory, the SCE agent will ask whether you want to bootstrap context. The context/ directory is where the agent stores implementation plans, tasks, and test results. It also serves as the shared context for the agent's work. It's important to commit this shared context every time the agent updates it.
Review and refine the plan
Before implementation, review the agent-created plan and refine it. Often if your change is missing details or constraints, the agent will prompt you with questions to clarify the plan. This is your chance to improve ambiguous steps, add missing constraints, and confirm task ordering.
This is the quality gate that keeps implementation aligned with your intent before code changes begin.
Run one task session
Now open a new session, and prompt the SCE agent to implement the next task in the plan. The SCE agent will pull in relevant context from the repo and potentially prompt you back to clarify some issues that relate to the next task. After that, the agent will ask you to start implementing the task. Don't forget to review the code the SCE agent produced.
Repeat this loop for each task created in the implementation plan. Multi-task sessions are possible, but one task per session usually gives better control and traceability.
Validate and close
After all tasks are complete, the agent runs tests and cleanup tasks for final validation of the full change.
Then perform a manual review of the final change and test results before you close out the change.
Congratulations, you just ran Shared Context Engineering! Now you are ready for the next change request.