# 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:

```bash
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

```bash
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:

```bash
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:

```bash
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.