# Downstream walkthrough — Open Scaffold on a tiny non-scaffold project A fresh reader can clone Open Scaffold, read the protocol docs, and still walk away unsure whether the discipline is worth carrying into their own project. This page closes that gap on a project that is **not** Open Scaffold itself: a 20-line shell CLI called **Tiny Notes** that appends one note to a text file. The point is not the script. The point is the **second session**: a fresh human or agent can open the repo later, read the mission, plan folders, and evidence note, and know whether work is active, done, blocked, or ready for a new slice without asking for old chat history. The same fixture is exercised mechanically by `npm run smoke:e2e` (see [`../CI.md#lifecycle-e2e-smoke`](../CI.md#lifecycle-e2e-smoke)). This page narrates the same lifecycle so a human can read it in one sitting, copy the artifacts, and decide whether Open Scaffold pays for itself on their next task. No private credentials, no private coordinator, no chat surface, no runtime harness, and no network access are required. --- ## What you will see The walkthrough moves through Open Scaffold's canonical identity chain on Tiny Notes: ```text mission -> plan -> implementation -> verification -> optional run.json work package -> evidence -> close -> session-2 resume ``` Every step has a concrete file, a concrete command, and an expected observable. The artifacts already live under `examples/lifecycle-e2e-smoke/` in this repo — you can read them in place, or copy them into a clean temp directory and run the loop yourself. --- ## 0. Premise: Tiny Notes Tiny Notes is intentionally boring. The whole project is two shell scripts and a text file: | File | Role | |---|---| | `notes.sh` | the CLI that appends a note | | `test.sh` | a behavior check | | `notes.txt` | generated when notes are added | Tiny Notes is the kind of script most people would scratch out in a single session and never document. That is exactly why it makes a good demonstration: if Open Scaffold pays off here, the same discipline scales up to multi-session AI-assisted work without renegotiation. --- ## 1. Mission — what the project is and is not Path: `examples/lifecycle-e2e-smoke/MISSION.md` ```markdown # Mission Tiny Notes is a tiny shell CLI that appends notes to a local text file so the Open Scaffold lifecycle can be tested without external services. ## Goals - Add a note from the command line. - Keep notes in a plain `notes.txt` file. - Verify behavior with a local shell test. ## Non-Goals - Not a web app. - Not a database-backed app. - Not a hosted service. ## Changelog ``` **Why it matters.** Mission gates every later plan. The non-goals are not decoration — they are how a future agent or contributor knows that a "let's add a sync server" suggestion is out of scope and needs an amendment before code lands. --- ## 2. Plan — one slice of work Path: `examples/lifecycle-e2e-smoke/.osc/plans/active/001-add-note-command.md` ```markdown # Plan: 001-add-note-command ## Status active ## Context Tiny Notes needs one real behavior so the Open Scaffold lifecycle smoke can verify a project that is not Open Scaffold itself. ## Goal Add and verify a command that appends one note to `notes.txt`. ## Constraints / Out of scope - Do not add external dependencies. - Do not add networking, auth, databases, or web UI. - Keep the implementation understandable in one sitting. ## Files to touch - `notes.sh` — tiny CLI implementation. - `test.sh` — local behavior check. - `notes.txt` — generated by the CLI during verification. ## Acceptance criteria - [ ] Running `bash notes.sh add "hello smoke"` appends `hello smoke` to `notes.txt`. - [ ] Running `bash test.sh` exits 0 and prints `tiny-notes test passed`. - [ ] The smoke can close this plan and preserve evidence without private infrastructure. ## Verification steps 1. Run `bash test.sh`. 2. Expected output includes `tiny-notes test passed`. 3. Run `bash verify.sh --standard` after the scaffold scripts are copied into the temp project; expected `0 fail`. ``` **Why a plan for a 20-line script?** Because the plan is the contract: future-you, an agent, or a teammate can read it and decide whether a proposed change still belongs. The plan file is also the unit Open Scaffold tooling validates (acceptance criteria, verification steps, immutability after commit). --- ## 3. Implementation — the actual work Path: `examples/lifecycle-e2e-smoke/notes.sh` ```bash #!/usr/bin/env bash set -euo pipefail usage() { printf 'Usage: bash notes.sh add "note text"\n' >&2 } if [ "${1:-}" != "add" ] || [ $# -lt 2 ]; then usage exit 2 fi shift note="$*" if [ -z "$note" ]; then usage exit 2 fi printf '%s\n' "$note" >> notes.txt ``` Path: `examples/lifecycle-e2e-smoke/test.sh` ```bash #!/usr/bin/env bash set -euo pipefail rm -f notes.txt bash notes.sh add "hello smoke" grep -Fxq "hello smoke" notes.txt printf 'tiny-notes test passed\n' ``` --- ## 4. Verification — prove the slice works From a copy of the fixture (see [step 8](#8-run-the-walkthrough-from-a-clean-temp-directory) for how to copy it cleanly): ```bash bash test.sh ``` Expected output: ```text tiny-notes test passed ``` If Open Scaffold's helper scripts (`verify.sh`, `close.sh`) are also present alongside the fixture, the methodology check passes too: ```bash ./verify.sh --standard ``` Expected: exit `0`, `0 fail`. --- ## 5. Optional `run.json` work package — bind the plan to one execution attempt A run packet is the optional `run.json` handoff file that says "this plan, this attempt, this lane." On Tiny Notes, where the work is one human in one terminal, the run packet may feel ceremonial. Generate it once anyway so you can see the shape — the same shape is what an external coordinator, bot, or harness adapter consumes when work spans agents and surfaces. From the Open Scaffold repo root, generate a packet for the in-repo Tiny Notes fixture: ```bash npm run osc -- run examples/lifecycle-e2e-smoke/.osc/plans/active/001-add-note-command.md \ --task-id tiny-notes:001-add-note-command \ --executor plain-agent \ --operator-surface cli \ --repo "$PWD/examples/lifecycle-e2e-smoke" \ --worktree "$PWD/examples/lifecycle-e2e-smoke" \ --branch "$(git branch --show-current)" \ --commit-policy "no commit/push unless explicitly approved" ``` Expected: a new `.osc/runs//run.json` is created under the Open Scaffold checkout. This is still an in-repo fixture convenience: the packet points at Tiny Notes as the downstream repo/worktree so readers can see how a non-scaffold project would be addressed. Open Scaffold core writes the packet; it does **not** launch a runtime. Inspect it like a downstream binding would: ```bash RUN_JSON="$(ls -td .osc/runs/*/run.json | head -1)" node docs/examples/runtime-binding-dry-run.mjs "$RUN_JSON" ``` Expected: exits `0`, prints the run id, plan path, executor lane, repo/worktree/branch, and commit policy, and states that no runtime was launched. See [`docs/RUNTIME_BINDING_CONTRACT.md`](../RUNTIME_BINDING_CONTRACT.md) for the full schema. --- ## 6. Evidence — what shipped, how it was verified When the slice is done, the receipt lives in the downstream project, not in a chat log. For Tiny Notes the evidence note can be as short as: Path: `examples/lifecycle-e2e-smoke/.osc/releases/2026-05-15-add-note-command.md` (illustrative) ```markdown # Release / Evidence Note: tiny-notes add-note command ## Summary Tiny Notes can now append a note to `notes.txt` from the command line and verify the behavior with a local shell test. ## Traceability - Plan: `.osc/plans/active/001-add-note-command.md` (moves to `done/` on close). - Task: `tiny-notes:001-add-note-command`. - `run.json` work package / run packet: `.osc/runs//run.json` (optional for solo work). - Branch / PR: . ## Verification - `bash test.sh` exits 0 and prints `tiny-notes test passed`. - `./verify.sh --standard` exits 0 with `0 fail`. ## Outcome The add-note command meets every acceptance criterion in the plan. No private infrastructure was used. ## Follow-up - None for this slice. Future scope (sync, search, multi-file) would need a fresh plan and a mission amendment. ``` **Why an evidence note instead of just the commit message?** Because evidence connects plan → verification → outcome → follow-up in one place. The same shape works for a 20-line script and a 2,000-line feature. --- ## 7. Close — make the status visible by moving the plan Plans live in stage folders. The folder *is* the status. To mark the slice done, move the plan and stamp the mission changelog with one command: ```bash ./close.sh 001-add-note-command ``` Expected: - `examples/lifecycle-e2e-smoke/.osc/plans/active/001-add-note-command.md` is gone. - `examples/lifecycle-e2e-smoke/.osc/plans/done/001-add-note-command.md` exists. - `examples/lifecycle-e2e-smoke/MISSION.md` has a new dated line in its `## Changelog`. A final `./verify.sh --standard` should still exit `0`. --- ## 8. Run the walkthrough from a clean temp directory To prove the lifecycle does not depend on the surrounding repo, copy the fixture into a fresh temp directory and run only the parts that belong to Tiny Notes: ```bash TMP="$(mktemp -d)" cp -R examples/lifecycle-e2e-smoke/. "$TMP/" cp verify.sh close.sh "$TMP/" cd "$TMP" bash test.sh ./verify.sh --standard # Write a short evidence note, then close the plan. mkdir -p .osc/releases cat > .osc/releases/$(date -u +%Y-%m-%d)-add-note-command.md <<'EOF' # Release / Evidence Note: tiny-notes add-note command ## Summary add-note works and is locally verified. ## Traceability - Plan: `.osc/plans/active/001-add-note-command.md` before close. - Task: local walkthrough. ## Verification - `bash test.sh` -> `tiny-notes test passed`. - `./verify.sh --standard` -> `0 fail`. ## Outcome The add-note command meets the plan acceptance criteria. ## Follow-up None for this slice. EOF ./close.sh 001-add-note-command ./verify.sh --standard ``` Expected: every command exits `0`. No network call, no private credential, no Hermes/OMC/OMX/Codex/Discord dependency. The mechanical version of these steps is exercised by `npm run smoke:e2e` from the Open Scaffold repo root. --- ## 9. Day 2: resume from repo truth, not memory Now pretend the first session is gone. No chat transcript, no terminal scrollback, no person explaining what happened. A fresh human or agent gets only the repo. From the temp Tiny Notes project after step 8, inspect the durable truth: ```bash printf 'Mission:\n' sed -n '1,24p' MISSION.md printf '\nPlan folders:\n' for stage in active backlog blocked done; do printf '%s:\n' "$stage" find ".osc/plans/$stage" -maxdepth 1 -type f -name '*.md' -print | sort done printf '\nEvidence notes:\n' find .osc/releases -maxdepth 1 -type f -name '*.md' ! -name README.md -print -exec sed -n '1,80p' {} \; ``` Expected reading: - `MISSION.md` says Tiny Notes is a local shell CLI, with no web app, database, or hosted-service scope. - `.osc/plans/active/` is empty after close, so there is no hidden in-flight work. - `.osc/plans/done/001-add-note-command.md` exists, so the add-note slice is closed. - `.osc/releases/-add-note-command.md` records the verification: `bash test.sh` and `./verify.sh --standard`. - The next action is not “continue whatever the chat was doing.” The next action is either **stop** or write a fresh plan for the next explicit slice, such as search, sync, or multi-file notes. That is the session-2 payoff. The repo answers the four recovery questions: ```text What are we building? -> MISSION.md What was the slice? -> .osc/plans/done/001-add-note-command.md How was it verified? -> .osc/releases/-add-note-command.md What should happen next? -> no active plan; create a new plan before new scope ``` If you stop before closing the slice, the same recovery check points at `.osc/plans/active/001-add-note-command.md` instead. That tells the next session the work is still active and lists the acceptance criteria and verification commands to finish it. --- ## When this discipline pays off Open Scaffold is genuinely useful when work needs to outlive a single session: - **Multi-session AI-assisted development.** The plan/evidence trail survives context loss, so the next agent or human can pick up without renegotiating intent. - **Small-team or client delivery.** "What was the goal, how was it verified, who approved it?" is answered in files instead of chat history. - **Multi-agent handoff.** A plan plus optional `run.json` work package plus evidence note is enough for a second lane to continue work without inheriting hallucinated assumptions. - **Light audit and compliance contexts.** Mission, plans, amendments, and evidence give an auditor a readable trail without standing up heavier tooling. - **AI work that needs "done" to mean something.** Acceptance criteria + verification + evidence is harder to fake than "looks good." ## When it is overkill Open Scaffold is the wrong tool when ceremony costs more than it saves: - **A one-off script you will never look at again.** Tiny Notes itself, written and forgotten in five minutes, does not need this. The example only earns its keep because it lives inside a project that *does* use the discipline. - **A throwaway prototype with no review gate.** If nothing depends on "was this actually verified?", you do not need an evidence note. - **A task that fits in one clean session with one person.** A README and a commit message often beat a plan file. - **Pre-mission exploration.** When you do not yet know what the project is, write notes; do not yet bind yourself to a plan. A reasonable rule of thumb: adopt Open Scaffold when at least one of {multi-session, multi-agent, multi-person, audit, AI-assisted} is true. Skip it when none of them are. --- ## Where to go next - [`docs/EXAMPLES.md`](../EXAMPLES.md) — the 60-second reading-path version of the same loop on Open Scaffold itself. - [`../CI.md#lifecycle-e2e-smoke`](../CI.md#lifecycle-e2e-smoke) — the automated smoke that exercises this fixture mechanically. - [`docs/RUNTIME_BINDING_CONTRACT.md`](../RUNTIME_BINDING_CONTRACT.md) — the contract any external runtime, coordinator, or harness uses when consuming `.osc/runs//run.json`. - [`docs/WORKFLOW.md`](../WORKFLOW.md) — phase-to-tool guide. - [`docs/SLICE_CLOSE_PROTOCOL.md`](../SLICE_CLOSE_PROTOCOL.md) — what makes a work slice truly closed instead of merely merged.