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