smarzban/agent-sdlc/repo-setup

Repo setup: machinery and marked skeletons

Take a repo — empty or existing — to a sound operational baseline: the machinery and marked skeletons that make it workable for humans and agents alike, plus the public/private split for agent instructions. This phase never writes prose. It stubs; the writing-* skills fill.

<HARD-GATE> An audit of the full target surface — each item reported present / missing / drifted — precedes every create/modify step, on any repo state (an empty repo just degenerates to all-missing; the procedure does not branch). No existing target file is ever replaced wholesale: read it, diff it against the seed template, and surface the proposed change in the same offer. Owner-decision items (LICENSE, security policy, code of conduct, issue/PR template content, CODEOWNERS assignments, remote-settings values) are flagged or asked, never invented. Remote settings are propose-only — state the exact value, never mutate it. The agent-sdlc pipeline half is asked exactly once, and its artifacts exist only after an explicit yes. Do NOT write README/CONTRIBUTING/SECURITY/CHANGELOG/ usage content, or any dev-environment onboarding walkthrough — that is the writing-* skills' job against the skeletons this skill leaves behind. </HARD-GATE>

Checklist (do in order)

1. Audit the universal target surface — enumerate all twelve seeded files: AGENTS.md,

CLAUDE.md, AGENTS.local.md, .gitignore, .gitattributes, .editorconfig, the CI workflow skeleton, the issue template, the PR template, CODEOWNERS, the README stub, and HANDOFF.md (live state routes to HANDOFF.md, standing rules route to the instruction files, per the litmus the handoff skill states). Judge each against its contract (reference/templates.md's block purpose), never against byte-identity with the raw template: report present (exists and satisfies its contract — for an awaiting-fill file, the seed token is gone and the required elements hold; a properly filled file is present, never drifted), missing (absent, OR an awaiting-fill file whose seed token is still there — report as "awaiting fill", offer nothing destructive), or drifted (exists but violates its contract: AGENTS.md lost one of its five routing-guideline elements, CLAUDE.md grew past its one-line pointer, .gitignore lost the AGENTS.local.md entry or the HANDOFF.md entry, or a template/CODEOWNERS file was emptied). On an empty repo every item is missing (same procedure, not a shortcut).

1. Present the audit report before proposing any change. Nothing is created or modified until

the owner sees the full present/missing/drifted picture.

1. Offer each missing item — propose materializing it from the matching fenced block in

reference/templates.md, adapting only the clearly-marked <placeholders> (project name, stack, toolchain) to the real repo. Never reword or add content beyond that. Owner-decision items (see step 5) are flagged or asked in the same offer, not auto-filled.

1. Offer each drifted item — read the existing file, diff it against the template, and propose

an in-place update that surfaces exactly what would change. Never propose (or perform) a wholesale overwrite, even when the drift is large. When the drifted file holds richer content than the seed — an existing instruction file (e.g. a populated CLAUDE.md), not an empty stub — the update is a migration: re-home its content into the split (public → AGENTS.md, private → AGENTS.local.md), never seed an empty skeleton over it. See `reference/migration.md` for the procedure, the gitignored→tracked CLAUDE.md flip call-out, the privacy de-leak checklist, and external-mirror coupling.

1. Hold the line on owner decisions — LICENSE, security policy, code of conduct, issue/PR

template content, CODEOWNERS assignments, and any remote-settings value (branch protection, repo metadata) are never fabricated. LICENSE absence is flagged, never invented (the writing-readmes rule — cite it). Remote settings are proposed as exact values for the owner to apply; this skill never mutates them. `CODEOWNERS` exception for a single unambiguous owner: when the repo has exactly one owner (a sole committer / the repo owner), propose the obvious * @<owner> line for confirmation — proposing the one obvious assignment for the owner to confirm is not inventing. Assigning other people, or guessing among several candidates, still is: flag it, don't fabricate.

1. Materialize only on confirmation — create or modify strictly what the owner confirmed from

the audit/offer above. Nothing else.

1. Ask once about the pipeline half — "set this repo up for the agent-sdlc pipeline too?" Ask

this exactly one time, after the universal half is settled.

• No → stop here. Zero pipeline artifacts.
• Yes → audit the pipeline artifacts the same way (.agent-sdlc/config.json, the spec-tree

location, constitution.md, CONTEXT.md — present/missing/drifted, offer, confirm), then materialize what was confirmed.

1. Declare the seed token and the awaiting-fill list in the report: the canonical token is

repo-setup:seed. It appears in AGENTS.md (body sections only — the routing guideline itself is complete-at-seed), AGENTS.local.md, .gitignore, the CI workflow skeleton, the issue template, the PR template, CODEOWNERS, the README stub, and HANDOFF.md (9 of the 12 seeded files). Three are complete-at-seed and never carry it: CLAUDE.md (exactly one line, forever) and .gitattributes/.editorconfig (self-sufficient baselines — no writing-* skill fills machinery; stack rules are an optional owner extension, not an awaiting-fill obligation).

1. Report what was created, what was updated in place (with the surfaced diff), what remains

flagged as an owner decision, and — if opted in — the pipeline artifacts created or flagged.

Principles

• Audit before act, unconditionally. The report precedes creation on every repo state, including

the degenerate all-missing case. There is no fast path around it.

• No blind overwrite. Existing files are read, diffed, and updated in place with the change

surfaced — never replaced wholesale, regardless of how stale they are.

• Migrate, don't stub, over existing content. A drifted instruction file richer than the seed

is re-homed into the split (content moved, never authored) — never overwritten with an empty skeleton. Splitting a formerly-private file into a public AGENTS.md is privacy-sensitive: flag the flip and de-leak the public half before it is committed (reference/migration.md).

• Owner decisions are never invented. LICENSE, security policy, code of conduct, template

content, CODEOWNERS assignments, and remote-settings values are the owner's call; this skill flags or asks, and stops there.

• Remote settings are propose-only. Branch protection and repo metadata: state the exact value

proposed, never mutate it.

• One ask for the pipeline half. Never assumed, never asked twice.
• Machinery, not prose. Skeletons only; writing-repo-docs and writing-readmes fill the

content — their own trigger lists are the hand-off point, not this skill's business.

• Single source of truth for seed content. Every seeded file's canonical content lives in

reference/templates.md; this skill body never restates it.

Rationalizations (excuses to skip the bar, and the rebuttal)

Red flags (stop and fix)

• Any create/modify step reachable before the audit report is presented.
• A file replaced wholesale instead of read → diffed → offered as an in-place update.
• An existing rich instruction file stubbed over with an empty seed skeleton instead of migrated —

destroying orientation the repo already had (reference/migration.md).

• A gitignored→tracked CLAUDE.md flip, or any formerly-private content becoming public, performed

without an explicit privacy call-out and de-leak scan in the audit.

• LICENSE, security policy, code of conduct, template content, CODEOWNERS assignments, or a

remote-settings value invented rather than flagged or asked.

• The pipeline question asked more than once, or a pipeline artifact created without an explicit

yes.

• Seed content duplicated in this SKILL.md instead of linked from reference/templates.md.
• AGENTS.override.md seeded or recommended.
• A per-harness shim beyond CLAUDE.md seeded by default (e.g. an opencode.json instructions

entry) — that is documented optional hardening, never seeded.

• Dev-environment onboarding content, or any writing-* deliverable (README body beyond the

stub, install/usage docs, CONTRIBUTING/SECURITY/CHANGELOG/llms.txt content) written by this skill instead of stubbed for writing-* to fill.

Done when

• The audit report was presented before any file was touched, covering the full target surface

(universal half, plus the pipeline half if opted in) with a present/missing/drifted verdict per item.

• Every materialization is confirmed and drawn from reference/templates.md's fenced blocks, with

only the marked <placeholders> adapted.

• No owner-decision item was invented; each was flagged, asked, or confirmed by the owner.
• The pipeline half was asked exactly once, and its artifacts exist only if the answer was yes.
• The report names the seed token and the awaiting-fill file list, matching

reference/templates.md's declarations exactly.

The artifact (output)