portable-project — a stranger can clone it and run it

The test: someone with a fresh machine, public internet and no access to the owner's accounts, repos or LAN runs git clone and the README's one install command — and the app works. Features that genuinely need the owner's infrastructure are off with a one-line message, never a crash, a hang or a silent failure.

Every project meets it unless its PROJECT_STATE.md says otherwise (see Audience below).

The rule — agent behavior

1. Before adding anything from the table below, stop and propose the better practice in one or two lines (what breaks for a stranger, the fix, its cost). Do the portable version unless the owner chooses otherwise; record a kept exception in PROJECT_STATE.md.
2. Spotted one already in the code while working nearby → mention it once at the end of the reply with the fix; don't rewrite unrelated code unasked.
3. Asked for an audit → run the scanner and the clean-room test below, then report.

Problem → better practice

Personal values belong in config.local/ (apps-config skill), .env (gitignored) or the project's private layer — never in tracked code, defaults or examples.

Audience

PROJECT_STATE.md → What This Is states who must be able to install it:

• public (default under a personal root): anyone — the full test above.
• team (default under a work root): a colleague on the company network — internal registries, GitLab and company hosts are fine; the owner's own paths, machines and personal tools are not.
• owner-only: infrastructure that only makes sense on the owner's setup (home-lab IaC, this template repo). Say so in one line with the reason; the audit then only checks that secrets and machine paths stay out of git.

Audit

1. Scanner (stdlib, advisory; ships with this skill):

   SCAN=~/.agents/skills/portable-project/scripts/scan_portability.py   # same file under ~/.claude/skills
   uv run "$SCAN" .                    # tracked files of the repo at .
   uv run "$SCAN" . --strict           # exit 1 when anything is found (CI)

   PowerShell: uv run "$HOME\.agents\skills\portable-project\scripts\scan_portability.py" .

   It reports machine paths, private-network addresses and LAN host names, path dependencies, references to sibling folders of the code root and sibling-deps.txt entries. The owner's personal terms (email, names) are checked by AICodeFactory's sync-ai-templates.sh <project> --scan-private.

2. Clean-room test — the only proof: a fresh clone in a temp folder, outside the code root, with the owner's environment hidden, then the README's install and test commands:

   tmp=$(mktemp -d) && git clone --depth 1 "$(git remote get-url origin)" "$tmp/app" && cd "$tmp/app"
   env -u AI_CODE_ROOT -u AI_TEMPLATE_DIR HOME="$tmp/home" ./install.sh   # then ./check.sh

   Better still, CI: a GitHub Actions runner has no siblings, no LAN and no owner tools — a workflow running install + tests from the checkout proves the test on every push.

3. Report one table — finding (file:line), what breaks for a stranger, proposed fix, effort (S/M/L) — ordered by what blocks install first. Fix only what the owner picks.