Repo Scaffold
Purpose
Use this skill to create the repo foundation that lets product, architecture, implementation, verification, and operations stay connected. It is broader than agentsmd-scaffold; it may include AGENTS.md, but also specs, tests, CI, config, release, and runbook structure.
Search First
Before adding files, inspect the repo for existing equivalents:
rg --files -g 'AGENTS.md' -g 'CONTRIBUTING.md' -g 'README*' -g 'pyproject.toml' -g 'package.json' -g 'go.mod' -g 'Cargo.toml' -g '.github/workflows/*' -g 'docs/**' -g 'specs/**' -g 'tests/**'
Reuse existing conventions. Do not create parallel docs/, spec/, planning/, or test/ trees when the repo already has a standard location.
Scaffold Layers
Add only the layers needed for the repo:
| Layer |
Typical Files |
| Product and specs |
specs/PRODUCT.md, specs/TECH.md, docs/adr/ |
| Agent context |
AGENTS.md, scoped AGENTS.md, local skill notes |
| Source layout |
language-specific src/, pkg/, cmd/, app/, lib/ |
| Tests |
tests/, fixtures, golden snapshots, e2e harness |
| CI |
.github/workflows/ci.yml, lint/typecheck/test jobs |
| Config |
.env.example, config schema, secret inventory |
| Release |
CHANGELOG.md, release checklist, versioning notes |
| Operations |
docs/runbooks/, SLO and incident templates |
Decision Rules
- For a new repo, propose the tree first, then create files only after the user asks to apply.
- For an existing repo, make the smallest additive change that closes the foundation gap.
- Keep generated starter files short and executable. Prefer empty placeholders only when a tool requires them.
- Do not hardcode credentials, service names, ports, or cloud providers without repo evidence.
- Do not overwrite existing README, CI, or config files without showing the diff intent.
Minimal Output
For planning:
existing_foundation:
missing_layers:
proposed_tree:
files_to_create_or_update:
verification_commands:
For implementation, finish by running the repo's validation command and, when available, the scaffold-specific lint or generated-file check.
1---2name: repo-scaffold3description: Scaffold or standardize a production-ready repository structure with specs, source layout, tests, CI, agent context, config examples, release notes, and operational docs. Use when starting a new repo, turning a prototype into a maintainable project, adding missing repository foundations, or creating a repo skeleton before implementation. For AGENTS.md-only context scaffolding, use agentsmd-scaffold.4---5
6# Repo Scaffold
7
8## Purpose
9
10Use this skill to create the repo foundation that lets product, architecture, implementation, verification, and operations stay connected. It is broader than `agentsmd-scaffold`; it may include AGENTS.md, but also specs, tests, CI, config, release, and runbook structure.
11
12## Search First
13
14Before adding files, inspect the repo for existing equivalents:
15
16```bash
17rg --files -g 'AGENTS.md' -g 'CONTRIBUTING.md' -g 'README*' -g 'pyproject.toml' -g 'package.json' -g 'go.mod' -g 'Cargo.toml' -g '.github/workflows/*' -g 'docs/**' -g 'specs/**' -g 'tests/**'
18```
19
20Reuse existing conventions. Do not create parallel `docs/`, `spec/`, `planning/`, or `test/` trees when the repo already has a standard location.
21
22## Scaffold Layers
23
24Add only the layers needed for the repo:
25
26| Layer | Typical Files |
27|---|---|
28| Product and specs | `specs/PRODUCT.md`, `specs/TECH.md`, `docs/adr/` |
29| Agent context | `AGENTS.md`, scoped `AGENTS.md`, local skill notes |
30| Source layout | language-specific `src/`, `pkg/`, `cmd/`, `app/`, `lib/` |
31| Tests | `tests/`, fixtures, golden snapshots, e2e harness |
32| CI | `.github/workflows/ci.yml`, lint/typecheck/test jobs |
33| Config | `.env.example`, config schema, secret inventory |
34| Release | `CHANGELOG.md`, release checklist, versioning notes |
35| Operations | `docs/runbooks/`, SLO and incident templates |
36
37## Decision Rules
38
39- For a new repo, propose the tree first, then create files only after the user asks to apply.
40- For an existing repo, make the smallest additive change that closes the foundation gap.
41- Keep generated starter files short and executable. Prefer empty placeholders only when a tool requires them.
42- Do not hardcode credentials, service names, ports, or cloud providers without repo evidence.
43- Do not overwrite existing README, CI, or config files without showing the diff intent.
44
45## Minimal Output
46
47For planning:
48
49```text
50existing_foundation:
51missing_layers:
52proposed_tree:
53files_to_create_or_update:
54verification_commands:
55```
56
57For implementation, finish by running the repo's validation command and, when available, the scaffold-specific lint or generated-file check.
majiayu000