skills/sssf/cookbooks/install.md

Install

/sssf install — stamp the entire factory out of the skill and into the current working directory.

Install the skill

The skill is distributed from the INDigitalStudio/skills repo. Install it with the skills CLI:

skills add INDigitalStudio/skills --skill sssf -g -y

That places the skill (with its scripts/, templates/, and the visualizer app) into your agent's skills directory. The rest of this cookbook assumes the skill is installed and you can point at its scripts/install.py.

Run it

uv run <skill>/scripts/install.py

Run from the target repo root — the cwd is where everything lands. <skill> is the directory this skill was installed into (e.g. ~/.agents/skills/sssf, a repo's .claude/skills/sssf, or wherever the skills CLI placed it). The scripts resolve their own location, so any of those paths works.

install.py asks which coding-agent harness to use — pi or omp — and writes your choice into the stamped config's defaults.coding_agent. Pass --harness pi|omp to skip the prompt. It also registers the repo in the visualizer's repos.json (next to the skill), so the multi-repo trace UI can browse this repo's sessions.

What gets stamped

install.py copies templates/ into the cwd:

Stamped	From	Tracked?
adws/adw_sssf_config/sssf.config.yaml	templates/sssf.config.yaml	yes — the agent roster
.env.sample	templates/env.sample	yes
adws/adw_*.py	templates/adws/	yes — the thirteen starter ADWs (incl. adw_validate.py)
adws/adw_modules/	templates/adws/adw_modules/	yes — all low-level logic
adws/adw_data/prompt_engineering/{planner,builder,scout,reviewer,documenter}/	templates/prompt_engineering/	yes — the user-owned home for prompts
adws/adw_data/harness_engineering/	templates/harness_engineering/	yes — the user-owned home for pi extensions
justfile	templates/justfile	yes — starter recipes: just demo, the workflows, the trace reads, just obs
adws/adw_data/sessions/, adws/adw_data/sssf.db	created at runtime	no — gitignored

The two *_engineering dirs mirror the two config keys of the same name: prompt_engineering is what an agent is told, harness_engineering is what its harness can do. Both are yours the moment they are stamped. Edit them in adws/adw_data/, never back inside the skill.

harness_engineering/ ships with subagents.ts — the pi extension backing subagent_create / _continue / _list / _remove, wired to the planner and scout in the starter roster.

Idempotency

Re-running is safe. install.py skips every file that already exists — your config, your prompts, and previously stamped code alike — and reports what it skipped, so a second run doubles as a drift check. To refresh stamped code (adw_modules/, the starter adw_*.py) to the skill's current version, run with --force — but know that --force overwrites ALL existing stamped files, including sssf.config.yaml and prompt_engineering/, so commit or back up user-owned edits first.

Post-install checklist

1. Env — if the repo has no .env yet, cp .env.sample .env and set the key(s) your harness needs. If the repo already has a .env (an app's own env, e.g. PocketBase keys), do NOT overwrite it — the ADWs read .env via dotenv and merge, so just append the SSSF keys you need. Pi needs OPENROUTER_API_KEY; omp reads its own model catalog (omp models --json). ANTHROPIC_API_KEY / CLAUDE_CODE_PATH are only needed once Claude Code lands in v2.
2. The harness is installed and on PATH — pi --version (or omp --version). Set PI_PATH / OMP_PATH in .env if not.
3. The model resolves — just validate checks the whole roster (names, prompt files, models) without running anything. If a model doesn't resolve, point the roster at one that does: set defaults.model and drop the per-agent model: overrides. See references/config.md for model resolution.
4. Gitignore — install.py appends adws/adw_data/sessions/, adws/adw_data/sssf.db*, and .env for you; confirm they landed. All three are runtime or secrets and must never be committed.
5. Git repo — ADWs that end in a commit phase call git_helper.commit_all, which raises if the cwd is not a git repository. Run git init and make a first commit before using adw_plan_build.py, adw_plan_build_test.py, or adw_simple_sdlc.py. adw_document.py needs one too: it measures the change with git diff against a base ref (main by default, --base to override).
6. Smoke test — first just validate (roster check, nothing runs), then just demo runs two cheap read-only workflows back to back, or run the smallest ADW directly:

just validate                                                  # roster check first
just demo                                                      # both, end to end
uv run adws/adw_prompt.py "reply with a one-line summary of this repo"   # the raw form

Green means the whole path works: config validated, session minted, the coding agent ran, envelope parsed, events landed in adws/adw_data/sssf.db. Verify the trace exists before trusting anything larger:

sqlite3 adws/adw_data/sssf.db "select adw_id, status from sessions order by started_at desc limit 1;"

If the smoke test fails, fix it before composing chains — every multi-agent ADW rides on this exact path.