scaffolding

Code Scaffolding

You generate new structural units (endpoints, commands, components, migrations, etc.) that follow the project's established patterns. The goal is consistency — every new unit looks like the existing ones, with nothing forgotten.

Read config.json in this skill directory for project-specific scaffolding config. If it doesn't exist, analyze the codebase to discover patterns, then save what you find for next time.

How it works

When asked to scaffold something new:

1. Identify the pattern. Look at 2-3 existing examples of the same kind of unit in the codebase. Note the file structure, naming, imports, boilerplate, tests, and registration steps.

2. Check templates. Look in templates/ for pre-built scaffolds. If a matching template exists, use it. If not, create one from the pattern you discovered for next time.

3. Generate all pieces. A new endpoint isn't just a handler — it's the handler + route registration + validation + tests + docs update. Generate everything the pattern requires.

4. Verify completeness. Check that the new unit is registered/imported where it needs to be. A handler that exists but isn't routed is invisible.

Template format

Templates in templates/ use simple placeholder syntax:

# templates/api-endpoint.md
Files to create:
- src/routes/{{name}}.py — handler
- tests/test_{{name}}.py — tests

Pattern to follow: see src/routes/health.py as reference.

Registration: add route in src/app.py

Don't forget:
- Input validation at the boundary
- Auth middleware (unless public)
- Error response shape: { data, error, meta }
- At least one happy-path test

Templates are reference docs, not rigid code generators. They tell you what to create and what not to forget, not exactly how to write it.

Setup

Create config.json after analyzing the project:

{
  "patterns_discovered": {
    "api_endpoint": {
      "example": "src/routes/health.py",
      "files": ["src/routes/{name}.py", "tests/test_{name}.py"],
      "registration": "src/app.py",
      "checklist": ["validation", "auth middleware", "error shape", "test"]
    },
    "bot_command": {
      "example": "src/bot/cogs/help.py",
      "files": ["src/bot/cogs/{name}.py", "tests/test_{name}.py"],
      "registration": "src/bot/main.py",
      "checklist": ["slash command decorator", "permissions", "error handling", "test"]
    }
  }
}