init-script-contract

Name: init-script-contract
Author: Archive228

712stars129forks

How to install init-script-contract?

archive228/loopkit/init-script-contract

$npx -y skills add Archive228/loopkit --skill init-script-contract

Installs into the current project.

Summary

Author idempotent init.sh under 120s plus sibling test.sh, stop.sh, reset.sh, serve.sh with fixed names the harness relies on.

Files · 1

View on GitHub

SKILL.md

1	# Init Script Contract
2
3	Every coding session in a multi-session project starts by bringing the dev server up. If the entry point is named differently each time, or takes four minutes, or prompts for input, you burn tokens and wall-clock on every single session. The fix is a fixed set of script names at the project root with a hard contract. The initializer agent writes them once; every downstream session relies on them.
4
5	The names are load-bearing — [[shift-notes]] and [[broken-window-check]] both refer to them by name. Do not invent your own.
6
7	## When to apply
8
9	- You are the initializer agent scaffolding a fresh project.
10	- You just discovered setup exceeds 120s and need to split cleanly.
11	- You are auditing an existing project whose sessions keep re-discovering how to launch the app.
12
13	## The five scripts
14
15	\| Script \| Contract \|
16	\|---\|---\|
17	\| `init.sh` \| Clean clone → dev server up on `localhost`. Idempotent. Under 120s. Zero prompts. \|
18	\| `serve.sh` \| Start the dev server only. Written when `init.sh` cannot fit under 120s. \|
19	\| `test.sh` \| Run the full test suite. Exit non-zero on any failure. \|
20	\| `stop.sh` \| Cleanly kill the dev server. Sessions run this before exiting. \|
21	\| `reset.sh` \| Wipe local DB and ephemeral state. Leave code untouched. Used by [[broken-window-check]]. \|
22
23	## Procedure
24
25	1. Pick the stack the spec implies. Do not scaffold Docker, CI, or lint configs the spec does not require.
26	2. Write `init.sh` to run end-to-end from an empty clone. Pin every dependency (lockfile, `==`, `Pipfile.lock`). Answer every prompt non-interactively (`-y`, `--yes`, `DEBIAN_FRONTEND=noninteractive`).
27	3. Time it. Run `time ./init.sh` on a clean clone. If it exceeds 120s, split — move one-time setup into `init.sh` and server launch into `serve.sh`. Have `init.sh` call `serve.sh` at the end so single-command startup still works.
28	4. Make it idempotent. Run `./init.sh` twice back-to-back. If the second run errors or duplicates state, guard each step with existence checks (`if [ ! -d node_modules ]`, `createdb --if-not-exists`, etc.).
29	5. Write `stop.sh` to kill by PID file or port, not by process name grep. Grep kills sibling agents on shared sandboxes.
30	6. Write `test.sh` with a single end-to-end smoke test that proves `init.sh` produced a serving app. No feature tests — those belong to future sessions.
31	7. Write `reset.sh` to drop and recreate the DB, clear caches, wipe `/tmp` artifacts. Never touch tracked files.
32	8. Verify from empty state. `git clean -fdx && ./init.sh && ./test.sh && ./stop.sh`. Every script exits 0.
33
34	## Anti-patterns
35
36	- Naming it `bootstrap.sh`, `setup.sh`, `dev.sh`. Downstream sessions grep for the fixed names. A cute alias silently disables the harness.
37	- Interactive prompts. `yarn install` asking about peer deps, `createdb` asking for a password, `npm audit` waiting for input. Every prompt is a stall the session cannot answer.
38	- Unpinned deps. `npm install foo` without a lockfile means the next session gets a different transitive graph. See the Feb 2026 incident where an agent ran `npm update --save` and broke twelve sessions.
39	- Killing the server with `pkill node`. Kills every node process in the sandbox. Use a PID file written by `serve.sh`.
40	- Letting `init.sh` create files outside the project directory. Sandbox will reject it and the failure mode is opaque.
41	- Skipping `reset.sh` because "the DB is fine". [[broken-window-check]] needs it to isolate a bad commit from stale state.
42
43	## Red flags
44
45	- `init.sh` prints "Press Y to continue" anywhere in its output.
46	- Timing varies wildly run-to-run — some dep is fetched from the network on the hot path.
47	- Running `init.sh` twice leaves migrations doubled or ports bound.
48	- `stop.sh` exits 0 but `lsof -i :3000` still shows the server.
49
50	## When NOT to apply
51
52	Single-session scripts and one-shot demos. The contract exists to amortize setup cost across many sessions; a one-off run does not need it.
53
54	## Related
55
56	- [[shift-notes]] — the notes downstream sessions read after `init.sh` succeeds.
57	- [[broken-window-check]] — runs `init.sh` then `reset.sh` when reverting a bad feature.
58	- [[single-feature-per-session]] — the discipline this contract enables by keeping session startup cheap.
59
60	Inspiration: Prithvi's March 2026 planner/generator/evaluator write-up, where the fixed harness entry points let the evaluator persona re-verify any generator session from scratch without re-learning the launch procedure.

People who liked this also viewed

6 picks

Type

find-skillsHelps users discover and install agent skills when they ask questions like "how do I do X", "find a skill for X", "is there a skill that can...", or express interest in extending capabilities. This skSkillsJul 20262.6M27k
grill-meA relentless interview to sharpen a plan or design.SkillsJul 2026633k182k
vercel-react-best-practicesVercel's official collection of agent skillsSkillsJul 2026573k29k
improve-codebase-architectureScan a codebase for deepening opportunities, present them as a visual HTML report, then grill through whichever one you pick.SkillsJul 2026522k182k
setup-matt-pocock-skillsConfigure this repo for the engineering skills — set up its issue tracker, triage label vocabulary, and domain doc layout. Run once before first use of the other engineering skills.SkillsJul 2026454k182k
triageMove issues and external PRs through a state machine of triage roles — categorise, verify, grill if needed, and write agent-ready briefs.SkillsJul 2026424k182k

init-script-contract

712stars129forks

View on GitHub

How to install init-script-contract?

archive228/loopkit/init-script-contract

$npx -y skills add Archive228/loopkit --skill init-script-contract

Installs into the current project.

Summary

Author idempotent init.sh under 120s plus sibling test.sh, stop.sh, reset.sh, serve.sh with fixed names the harness relies on.

Files · 1

View on GitHub

SKILL.md

1	# Init Script Contract
2
3	Every coding session in a multi-session project starts by bringing the dev server up. If the entry point is named differently each time, or takes four minutes, or prompts for input, you burn tokens and wall-clock on every single session. The fix is a fixed set of script names at the project root with a hard contract. The initializer agent writes them once; every downstream session relies on them.
4
5	The names are load-bearing — [[shift-notes]] and [[broken-window-check]] both refer to them by name. Do not invent your own.
6
7	## When to apply
8
9	- You are the initializer agent scaffolding a fresh project.
10	- You just discovered setup exceeds 120s and need to split cleanly.
11	- You are auditing an existing project whose sessions keep re-discovering how to launch the app.
12
13	## The five scripts
14
15	\| Script \| Contract \|
16	\|---\|---\|
17	\| `init.sh` \| Clean clone → dev server up on `localhost`. Idempotent. Under 120s. Zero prompts. \|
18	\| `serve.sh` \| Start the dev server only. Written when `init.sh` cannot fit under 120s. \|
19	\| `test.sh` \| Run the full test suite. Exit non-zero on any failure. \|
20	\| `stop.sh` \| Cleanly kill the dev server. Sessions run this before exiting. \|
21	\| `reset.sh` \| Wipe local DB and ephemeral state. Leave code untouched. Used by [[broken-window-check]]. \|
22
23	## Procedure
24
25	1. Pick the stack the spec implies. Do not scaffold Docker, CI, or lint configs the spec does not require.
26	2. Write `init.sh` to run end-to-end from an empty clone. Pin every dependency (lockfile, `==`, `Pipfile.lock`). Answer every prompt non-interactively (`-y`, `--yes`, `DEBIAN_FRONTEND=noninteractive`).
27	3. Time it. Run `time ./init.sh` on a clean clone. If it exceeds 120s, split — move one-time setup into `init.sh` and server launch into `serve.sh`. Have `init.sh` call `serve.sh` at the end so single-command startup still works.
28	4. Make it idempotent. Run `./init.sh` twice back-to-back. If the second run errors or duplicates state, guard each step with existence checks (`if [ ! -d node_modules ]`, `createdb --if-not-exists`, etc.).
29	5. Write `stop.sh` to kill by PID file or port, not by process name grep. Grep kills sibling agents on shared sandboxes.
30	6. Write `test.sh` with a single end-to-end smoke test that proves `init.sh` produced a serving app. No feature tests — those belong to future sessions.
31	7. Write `reset.sh` to drop and recreate the DB, clear caches, wipe `/tmp` artifacts. Never touch tracked files.
32	8. Verify from empty state. `git clean -fdx && ./init.sh && ./test.sh && ./stop.sh`. Every script exits 0.
33
34	## Anti-patterns
35
36	- Naming it `bootstrap.sh`, `setup.sh`, `dev.sh`. Downstream sessions grep for the fixed names. A cute alias silently disables the harness.
37	- Interactive prompts. `yarn install` asking about peer deps, `createdb` asking for a password, `npm audit` waiting for input. Every prompt is a stall the session cannot answer.
38	- Unpinned deps. `npm install foo` without a lockfile means the next session gets a different transitive graph. See the Feb 2026 incident where an agent ran `npm update --save` and broke twelve sessions.
39	- Killing the server with `pkill node`. Kills every node process in the sandbox. Use a PID file written by `serve.sh`.
40	- Letting `init.sh` create files outside the project directory. Sandbox will reject it and the failure mode is opaque.
41	- Skipping `reset.sh` because "the DB is fine". [[broken-window-check]] needs it to isolate a bad commit from stale state.
42
43	## Red flags
44
45	- `init.sh` prints "Press Y to continue" anywhere in its output.
46	- Timing varies wildly run-to-run — some dep is fetched from the network on the hot path.
47	- Running `init.sh` twice leaves migrations doubled or ports bound.
48	- `stop.sh` exits 0 but `lsof -i :3000` still shows the server.
49
50	## When NOT to apply
51
52	Single-session scripts and one-shot demos. The contract exists to amortize setup cost across many sessions; a one-off run does not need it.
53
54	## Related
55
56	- [[shift-notes]] — the notes downstream sessions read after `init.sh` succeeds.
57	- [[broken-window-check]] — runs `init.sh` then `reset.sh` when reverting a bad feature.
58	- [[single-feature-per-session]] — the discipline this contract enables by keeping session startup cheap.
59
60	Inspiration: Prithvi's March 2026 planner/generator/evaluator write-up, where the fixed harness entry points let the evaluator persona re-verify any generator session from scratch without re-learning the launch procedure.

People who liked this also viewed

6 picks

Type