Scaffold

Scaffold Skill

Quick Ref: Project scaffolding, component generation, CI/CD setup. /scaffold <language> <name> for new projects, /scaffold component <type> <name> for components, /scaffold ci <platform> for CI pipelines.

YOU MUST EXECUTE THIS WORKFLOW. Do not just describe it.

Generate real files, run real commands, verify real output. Every invocation produces a working, tested, committed scaffold.

Modes

Step 0: Determine Mode

Parse the invocation to identify which mode to run:

• If args contain component as first positional: Component mode
• If args contain ci as first positional: CI mode
• Otherwise: Project mode

If ambiguous, ask ONE clarifying question, then proceed.

Step 1: Gather Requirements

Collect these inputs (use defaults when not specified):

Validate the project name is kebab-case. Reject names with spaces, uppercase, or special characters.

Step 2: Generate Project Structure

Create the directory tree and all files. Every generated file must have real, functional content -- not placeholder comments.

Go CLI

<name>/
  cmd/<name>/main.go        # cobra or bare main with version flag
  internal/config/config.go  # configuration loading
  internal/config/config_test.go
  go.mod
  go.sum
  Makefile                   # build, test, lint, clean targets
  .goreleaser.yml            # cross-compile config
  .gitignore
  .editorconfig
  CLAUDE.md

Go Library

<name>/
  pkg/<name>.go              # primary exported API
  pkg/<name>_test.go
  examples/basic/main.go     # runnable example
  go.mod
  go.sum
  Makefile
  .gitignore
  .editorconfig
  CLAUDE.md

Python Package

<name>/
  src/<name>/__init__.py     # version and public API
  src/<name>/core.py         # primary module
  tests/__init__.py
  tests/test_core.py         # real behavioral test
  pyproject.toml             # black, ruff, mypy config included
  .github/workflows/ci.yml
  .gitignore
  .editorconfig
  CLAUDE.md

Node/TypeScript

<name>/
  src/index.ts               # entry point with exports
  src/core.ts                # primary module
  test/core.test.ts          # vitest test
  package.json               # scripts: build, test, lint, format
  tsconfig.json
  .gitignore
  .editorconfig
  CLAUDE.md

Rust

<name>/
  src/lib.rs                 # library root (or main.rs for CLI)
  src/core.rs                # primary module
  benches/benchmark.rs       # criterion bench stub
  Cargo.toml                 # with clippy, rustfmt config
  .gitignore
  .editorconfig
  CLAUDE.md

Step 3: Apply Best Practices

After generating the structure, layer on cross-cutting concerns:

For installer scripts, agent-facing tool servers, MCP surfaces, or Rust CLI storage scaffolds, apply references/agent-facing-tool-scaffolds.md before writing files.

.gitignore

Use the language-appropriate template. Include IDE files (.vscode/, .idea/), OS files (.DS_Store, Thumbs.db), and build artifacts.

.editorconfig

root = true

[*]
end_of_line = lf
insert_final_newline = true
trim_trailing_whitespace = true
charset = utf-8

[*.{go,rs}]
indent_style = tab
indent_size = 4

[*.{py,ts,js,json,yml,yaml,toml}]
indent_style = space
indent_size = 4

[Makefile]
indent_style = tab

Pre-commit Hooks

Generate a .pre-commit-config.yaml with language-appropriate hooks:

• Go: gofmt, go vet, golangci-lint
• Python: black, ruff, mypy
• Node/TS: eslint, prettier
• Rust: rustfmt, clippy

Testing Setup

Every scaffold includes at least one real test that:

• Tests actual behavior (not just != nil)
• Uses the language's idiomatic test patterns
• Passes on first run

CI Pipeline

Generate CI config unless the user explicitly opts out. Default: GitHub Actions.

CLAUDE.md

Generate a project-specific CLAUDE.md containing:

• Build commands
• Test commands
• Lint commands
• Project structure overview
• Key conventions for the language (loaded from /standards)

Step 4: Verify Scaffold Works

Run these checks in order. Stop and fix if any fail.

1. Build passes        →  language-specific build command
2. Tests pass          →  language-specific test command
3. Lint passes         →  language-specific lint command (warn-only if tools not installed)

Verification Commands by Language

If a tool is not installed (e.g., ruff, golangci-lint), note it as a warning but do not fail the scaffold.

Step 5: Initial Commit

After verification passes, create the initial commit:

bootstrap(<name>): scaffold <language> <type> project

Example: bootstrap(my-cli): scaffold go cli project

Do NOT push. The user decides when to push.

Component Mode

When invoked as /scaffold component <type> <name>:

Go Component

internal/<name>/<name>.go       # package with exported API
internal/<name>/<name>_test.go  # behavioral tests

Register the new package in relevant imports. Run go build ./... and go test ./... to verify.

Python Component

src/<project>/modules/<name>/__init__.py
src/<project>/modules/<name>/core.py
tests/test_<name>.py

Node/TS Component

src/<name>/index.ts
src/<name>/types.ts
test/<name>.test.ts

React Component

src/components/<Name>/<Name>.tsx
src/components/<Name>/<Name>.test.tsx
src/components/<Name>/<Name>.stories.tsx  # Storybook story
src/components/<Name>/index.ts            # barrel export

After generating, run the project's test suite to verify the new component integrates cleanly.

CI Mode

When invoked as /scaffold ci <platform>:

GitHub Actions

Generate .github/workflows/ci.yml:

This is a skeleton — expand steps using the detected language's actual commands.

name: CI
on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Setup # use actions/setup-go, setup-node, setup-python as detected
        uses: actions/setup-go@v5  # example for Go
        with:
          go-version-file: go.mod
      - name: Lint
        run: golangci-lint run  # replace with detected linter

  test:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        os: [ubuntu-latest, macos-latest]
    steps:
      - uses: actions/checkout@v4
      - name: Setup
        uses: actions/setup-go@v5
        with:
          go-version-file: go.mod
      - name: Test
        run: go test ./...  # replace with detected test command

  build:
    runs-on: ubuntu-latest
    needs: [lint, test]
    steps:
      - uses: actions/checkout@v4
      - name: Setup
        uses: actions/setup-go@v5
        with:
          go-version-file: go.mod
      - name: Build
        run: go build ./...  # replace with detected build command

Include language-appropriate caching (actions/cache for Go modules, pip, node_modules, cargo registry). Replace Go-specific steps with the detected language's toolchain.

GitLab CI

Generate .gitlab-ci.yml:

stages:
  - lint
  - test
  - build

variables:
  # language-specific cache paths

lint:
  stage: lint
  script: [lint command]

test:
  stage: test
  script: [test command]
  parallel:
    matrix:
      - IMAGE: [language versions]

build:
  stage: build
  script: [build command]
  needs: [lint, test]

Include caching directives and artifact definitions.

Domain-Slice Mode

When invoked as /scaffold domain <name>, scaffold a domain-slice manifest — the bounded-context declaration used to scope an operating-loop run.

There is no `scaffold` subcommand on the `ao` CLI. Domain-slice scaffolding is this skill's responsibility; the old phased-engine flags are superseded by ADR-0009.

Workflow

1. Generate the manifest. Run the write-and-exit flag — it creates the template and returns without starting an RPI run:

Run /scaffold domain <name>.

This writes docs/domains/<name>/manifest.yaml from a template that already validates against schemas/domain-slice-manifest.v1.schema.json. An existing manifest is not overwritten unless --force is passed.

2. Fill in the placeholders. Edit the generated manifest:

• bounded_context — one sentence: what this slice owns and explicitly does NOT own.
• directive_ids — stable GOALS.md directive IDs (pattern d-<slug>) this slice owns.
• scenario_ids — promoted spec scenario IDs from spec/scenarios/ (may stay [] initially).
• context_roots — repo-relative implementation surface (at least one entry).
• allowed_read_globs / denied_read_globs — the read fence (gitignore syntax; deny wins).
• validation_commands — ordered build/test/lint steps.

3. Verify it loads. The scaffolded manifest already passes the F3.1 schema/loader. After editing, confirm it still validates:

Dry-run the operating-loop plan against docs/domains/<name>/manifest.yaml before execution.

A dry run loads the manifest, prints the scoped phase prompts, and exits — proving the slice attaches.

4. Run scoped RPI. Once the manifest is real:

Run the operating loop with docs/domains/<name>/manifest.yaml as the explicit scope contract.

Phase prompts carry the slice's boundaries; each run also writes a domain-scope audit artifact reporting any out-of-domain references visible in evidence.

Next commands the scaffold names

After writing the manifest, lint executable-spec links with ao goals scenarios --lint, preview the scoped operating-loop plan, then execute with the manifest as the scope contract. Run them in that order.

Error Recovery

Output Summary

After completion, print a summary:

Scaffold complete: <name> (<language> <type>)
  Files created: <count>
  Build: PASS
  Tests: PASS (<count> tests)
  Lint:  PASS | WARN (tool not installed)
  Commit: bootstrap(<name>): scaffold <language> <type> project

Next steps:
  cd <name>
  <language-specific "run" command>

References

• references/agent-facing-tool-scaffolds.md
• references/recommended-reading.md — forward-looking index of external skills (e.g., mcp-server-design) worth absorbing into scaffold when their trigger conditions arrive. Consult before designing a new scaffold mode that targets agent-facing tool surfaces.
• references/scaffold.feature — Executable spec: project/component/CI scaffolding entry points + domain-slice manifest routing (soc-qk4b)

Agent-Facing Tool Scaffolds

Use this reference when the scaffold output will be consumed by agents, installed by shell scripts, or exposed as a tool server.

Installer Workmanship

Installer scripts must be boring and reversible:

• Detect platform and shell before mutation.
• Print what will change before changing it.
• Use idempotent directory creation and file writes.
• Avoid curl | sh in generated docs unless the repo explicitly accepts it.
• Leave an uninstall or rollback path.
• Verify the installed command after mutation.

Agent-Facing Tool Server Rules

For MCP or similar tool servers:

• Tool names should describe user intent, not implementation internals.
• Inputs should be structured and narrow.
• Errors should explain what the agent can try next.
• Dangerous tools need dry-run or confirmation flows.
• Every tool should have at least one fixture-backed smoke test.

Rust CLI With Local State

When scaffolding a Rust CLI that stores local state:

• Prefer SQLite for transactional state and JSONL for inspectable event logs.
• Keep migrations explicit and tested.
• Expose --json for agent-readable output.
• Separate command parsing from storage logic.

---

Source: Adapted from an external skill corpus / installer-workmanship, mcp-server-design, and rust-cli-with-sqlite. Pattern-only, no verbatim text.

Recommended Reading for Future Scaffolding Work

Forward-looking index of external skills and methodologies worth absorbing into scaffold (or a sibling skill) when the right trigger arrives. Not active dependencies; just breadcrumbs so high-utility sources are not lost.

How to use this file

When a trigger condition listed below fires (new transport surface, new agent-API workload, new boilerplate domain), revisit the named source, evaluate whether the patterns still apply, and absorb the load-bearing ideas into the relevant SKILL.md or a new references/*.md. Do not bulk-import — extract only what is currently load-bearing. Append new candidates to the table below when a fresh source crosses the bar (recurring citations, repeated value, or distinct framing not already captured).

Candidates

Entry shape

When adding a new candidate, keep the same four fields so the table stays easy to scan:

• Skill / source — name and (if external) the upstream owner.
• Origin — where the skill currently lives (ACFS, third-party repo, internal experiment).
• Why relevant to scaffold — one or two sentences naming the specific patterns scaffold could borrow. Phrase the takeaway in our own words; do not paste the source's description verbatim.
• Trigger to absorb — the concrete condition that should re-open this absorption candidate. Avoid vague triggers ("when relevant"); name the workload, surface, or epic.

---

Forward-looking absorption-candidate index. Source skills credited inline above.