| name | demo-5-sandbox-feature-pr |
| description | Demo skill for the meta "decode improves decode" flow — launch decode in a sandboxed clone of the course repo, plan and build one small feature inside the Workspace, let Hand-back push the Session Branch, then open a draft PR against the course repo. |
The meta demo: decode improves decode. Run decode inside an isolated sandbox Workspace that is
a clone of this very course repo, plan and implement one small self-contained feature there, and
let the harness ship the work back as a branch you turn into a draft PR.
Nothing the model does touches your host checkout — the Workspace is an isolated clone, and the
branch only lands on your host through Hand-back (ADR-0012 §8).
1. Launch decode against a sandboxed clone of the course repo (human step)
Sandbox mode is selected by the SANDBOX_MODE environment variable — it is an env var, not a
command-line flag; the repo to clone into the Workspace is the --repo flag. Launch the local
docker rung (Docker must be running):
SANDBOX_MODE=docker decode --repo git@github.com:decodingai-magazine/building-a-coding-agent-from-scratch-course.git
This clones the course repo into the isolated Workspace (/workspace ≡ host .decode/sandbox)
and drops you into the REPL, with bash and the file tools scoped to that clone.
To run the same demo on the remote rung instead, swap SANDBOX_MODE=docker for
SANDBOX_MODE=modal — everything else is identical (Modal credentials must be configured).
2. Plan the feature — in plan mode
If you are decode reading this inside the Workspace, start here — step 1 is the human's launch
command, already done; do NOT try to run decode yourself. Enter plan mode by calling
enter_plan_mode with no arguments (it takes none — you present the plan later, to
exit_plan_mode), explore the code read-only, then present a short plan before touching anything.
Pick ONE feature — small, self-contained, provable in a single session:
- A
decode --version flag that prints the installed package version, plus its unit test.
- One small pure helper (e.g. in
tools/ or entities/) with a focused unit test.
- A scoped docstring/README fix that resolves a real inaccuracy you found while exploring.
The plan should name the files to touch, the test that proves the feature, and nothing else.
Exit plan mode (exit_plan_mode) once the human approves it.
3. Build it inside the Workspace
Implement the plan: edit, then run the suite inside the Workspace (uv run pytest -q /
make unit-tests) until it is green. Keep the final green test output — it goes in the PR body.
All of this happens on the sandboxed clone.
4. Get the branch onto the remote
The branch has to be on origin before a PR can point at it. There are two ways it gets there —
know which one you are in:
-
Sandbox run (the intended demo, SANDBOX_MODE=docker/modal): just leave the REPL (exit,
or /ship while idle). On exit, Hand-back secures the final Workspace onto a deterministic
decode/<session-id> Session Branch, auto-commits any uncommitted model work, and
git pushes it back to the course repo with your ambient host git credentials — every git
command runs host-side, so no credential ever enters the sandbox. The friendly exit line names
the branch it pushed. You do not push by hand in this path.
-
No sandbox, or your own feature branch: if decode is running straight on the host (no
SANDBOX_MODE), there is no Hand-back — commit your work on a feature branch and push it
yourself:
git push -u origin <your-branch>
Give this push a generous timeout (≥ 180s) and do not kill it. This repo installs a
pre-push hook that runs the full unit suite (make unit-tests, ~2 minutes) before the push
goes out — a short tool timeout will terminate it mid-run and look like a network hang. It is
the gate doing its job; you already ran the suite green in step 3, so just let it finish. Do
not reach for git push --no-verify to dodge it — that skips the format/lint/test gate the
push is supposed to enforce. Only fall back to --no-verify if the human explicitly tells you
to.
5. Open a draft PR against the course repo
Turn the pushed branch into a draft PR with the gh CLI — --head decode/<session-id> for the
Hand-back path, or --head <your-branch> for the manual path. Build the body with a heredoc so
newlines and backticks land literally (never hand-escape \n into --body):
gh pr create --draft \
--repo decodingai-magazine/building-a-coding-agent-from-scratch-course \
--head <branch> --title "<feature>" \
--body "$(cat <<'EOF'
<what & why, 2-3 lines>
Test evidence:
```
<the green pytest summary line>
```
Built end-to-end inside a decode sandbox Workspace (SANDBOX_MODE=docker) and shipped by Hand-back.
EOF
)"
Report the feature you built, the branch it landed on, and the draft-PR URL.
