repo-scaffold-factory

name	repo-scaffold-factory
description	Generate the base repository file structure including README, AGENTS.md, docs layout, ticket templates, and the agent configuration scaffold. Use when creating a greenfield repo foundation or resetting a weakly structured project. This generates a generic starting structure that other skills then customize. Do not use when the repo already has established structure (risks overwriting).

Repo Scaffold Factory

Use this skill to generate the initial repository file tree. This is a TWO-PHASE process.

Phase A: Generate the base scaffold

Option 1: Script-assisted generation (recommended for large scaffolds)

If a bootstrap script is available (e.g., scripts/bootstrap_repo_scaffold.py), use it for deterministic mechanical work: copying template files, substituting placeholders, and generating metadata.

python3 scripts/bootstrap_repo_scaffold.py \
  --dest <destination-path> \
  --project-name "<Project Name>" \
  --model-provider "<provider>" \
  --planner-model "<planner-model-string>" \
  --implementer-model "<implementer-model-string>"

Common placeholder substitutions:

• __PROJECT_NAME__ → project name
• __PROJECT_SLUG__ → URL-safe slug
• __AGENT_PREFIX__ → prefix for agent filenames
• __MODEL_PROVIDER__ → provider label
• __STACK_LABEL__ → stack/framework label

Derive arguments from the canonical brief and user decisions.

Option 2: Manual generation

If no script exists, create the structure manually:

# Core structure
mkdir -p src tests docs scripts .github/ISSUE_TEMPLATE .github/workflows

# Agent-operated repo additions
mkdir -p tickets
# Plus agent config dir: .opencode/, .copilot/, .codex/, or equivalent

Generate these files:

1. README.md: Project name, one-line description, quick-start commands, pointer to AGENTS.md
2. AGENTS.md: Reading order, before-making-changes checklist, commit convention, what NOT to modify
3. .github/ISSUE_TEMPLATE/: Bug report and feature request templates
4. .github/pull_request_template.md: PR template with checklist
5. docs/ARCHITECTURE.md: Placeholder for system design
6. docs/CONTRIBUTING.md: Setup and workflow instructions
7. .gitignore: Language-appropriate ignores

Phase B: Customize with project-specific content

After the base files exist, customize them with actual project content from the canonical brief:

Files to customize now

1. README.md — Replace generic sections with actual project description and setup instructions
2. AGENTS.md — Populate with actual project rules, conventions, and truth hierarchy
3. Canonical brief — Ensure it's placed correctly (docs/spec/CANONICAL-BRIEF.md or docs/BRIEF.md)
4. docs/process/workflow.md — Customize if the project has specific process requirements

Files to leave for other skills

• START-HERE.md — Generated by handoff-brief at flow end
• Agent prompts — Customized by opencode-team-bootstrap (or equivalent)
• Project-local skills — Customized by project-skill-bootstrap

Files NOT to customize at this stage

• Standard workflow tools, enforcement plugins, and stage-gate config — keep as generated

Output contract

./
├── README.md
├── AGENTS.md
├── .gitignore
├── docs/
│   ├── BRIEF.md or spec/CANONICAL-BRIEF.md (input, not generated)
│   ├── ARCHITECTURE.md
│   └── CONTRIBUTING.md
├── .github/
│   ├── ISSUE_TEMPLATE/
│   │   ├── bug_report.md
│   │   └── feature_request.md
│   └── pull_request_template.md
├── src/
├── tests/
├── scripts/
├── tickets/ (if agent-operated)
└── <agent-config-dir>/ (if agent-operated)

Failure handling

• No canonical brief: Stop. Cannot generate meaningful scaffold without knowing what the project is.
• No stack profile: Proceed with generic structure. Log warning: "Stack not specified, using generic scaffold."
• Directory already exists with content: Do not overwrite. Report conflict and ask for confirmation.
• Git init fails: Continue without git. Note that repo is not version controlled.

References

• This is step 3 of the scaffold-kickoff flow — continue to ../opencode-team-bootstrap/SKILL.md
• GitHub template repositories: https://docs.github.com/en/repositories/creating-and-managing-repositories/creating-a-repository-from-a-template