agentleFS
chuckplayerchuckplayer/claude-agent-pack/skills/scaffold/SKILL.md

scaffold

Skill8 starsChanged 35 days agoMITView on GitHub

Scaffold a new feature end-to-end: API contract → database schema → backend service/controller → frontend. Use when building something new from scratch across multiple layers. More opinionated than /implement — always runs the full vertical slice in the correct dependency order. Trigger this when someone says: build this feature from scratch, scaffold a new endpoint, I need a full-stack feature, new feature end-to-end, build the whole thing. Do NOT use when the task is already partially built or only one layer needs changes — use /implement instead.

50 other projects use a version of this.

Adopted by

Most recently taken up by

Used with

Projects with it also use ascii-diagram, docs-ci and 10 more.

Other files people use alongside this one.

Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
  • SethGammonSkill

    ascii-diagram

    Generate perfectly aligned ASCII diagrams — architecture, flow, sequence, box-and-arrow. Uses a programmatic character-grid approach so alignment is guaranteed by math, not token prediction. Includes post-render verification.

    Also in 4 projects that use this

  • jh941213Skill

    docs-ci

    문서 CI(링크·OpenAPI lint·breaking 게이트·mermaid 검증)나 문서 드리프트 감지(docs.yaml 신선도 검사)를 설치하거나 돌릴 때 사용. 문서 내용 작성은 docs-architecture·docs-interfaces·docs-manuals.

    Also in 3 projects that use this

  • jh941213Skill

    docs-interfaces

    API·이벤트 인터페이스 문서(OpenAPI·swagger·AsyncAPI 명세, 엔드포인트 레퍼런스, API 구성도·시퀀스, API CHANGELOG)를 만들거나 코드와 맞출 때 사용. 시스템 구성도는 docs-architecture, API 설계 원칙은 api-design-principles.

    Also in 3 projects that use this

  • SethGammonSkill

    research-fleet

    Parallel research using Fleet wave mechanics. Spawns multiple scout agents, each investigating a different angle of the same question. Findings are compressed between waves. Produces a unified research brief from multiple independent perspectives.

    Also in 3 projects that use this

  • RachaelQuiselSkill

    client-docs

    Client documentation. Use when a build needs documentation updates or missing project documents need to be identified.

    Also in 3 projects that use this

  • vicoa-aiSkill

    live-preview

    Start a local app in the current user project, expose it through a tunnel, and return preview details in structured Markdown. Use when the user asks for a preview URL, public URL, shareable localhost, mobile/web preview, or tunnel setup.

    Also in 4 projects that use this

  • +4 more from jh941213

The file

Show its rules and text

We split this skill into the rules it gives an agent

17 rules. 0 are common, 13 are distinctive, and 4 are very specific to this project.

  • 0

    Common

    Most of the 43 edited versions we read keep these.

  • 13

    Distinctive

    This author's own choices. Worth a look.

  • 4

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Before starting, confirm with the user:

    line 12
  2. Distinctive:

    Always first. Confirm the working branch.

    line 21
  3. Distinctive:

    Always invoke for new features that expose any endpoint.

    line 25
  4. Very specific:

    Use isolation: "worktree" for database-engineer.

    line 35
  5. Very specific:

    Use isolation: "worktree" for the engineer agent.

    line 44
  6. Very specific:

    Run ts-linter immediately after if any .ts files were touched.

    line 46
  7. Very specific:

    Use isolation: "worktree" for frontend-engineer.

    line 54
  8. Distinctive:

    Run ts-linter immediately after.

    line 56
  9. Distinctive:

    If the patch conflicts, stop and route back to the responsible engineer with the conflicting file list.

    line 79
  10. Distinctive:

    After code-reviewer completes.

    line 90
  11. Distinctive:

    If PASS: proceed to step 9a.

    line 104
  12. Distinctive:

    If FAIL: retry up to 2 cycles, routing findings back to the responsible engineer.

    line 105
  13. Distinctive:

    If a worktree path no longer exists, skip the git worktree remove for that path and proceed to branch deletion.

    line 122
  14. Distinctive:

    After step 9a completes. Ask the user whether to push and open a pull request.

    line 126
  15. Distinctive:

    API contract not approved before engineers start: If the user skips api-designer approval and an engineer implements against a wrong shape, …

    line 131
  16. Distinctive:

    Mid-pipeline failure: If a layer fails (e.g., database-engineer errors out), stop and surface the failure to the user before continuing.

    line 132
  17. Distinctive:

    Worktree not cleaned up after FAIL: If merge-reviewer returns FAIL and the user abandons the scaffold, still run the worktree cleanup …

    line 133

“Common” is measured: kept by at least 6 in 10 of the 43 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Scaffold New Feature

Build a new feature end-to-end across all layers in the correct dependency order.

1. Confirm scope

Before starting, confirm with the user:

  • What is being built (feature name and one-sentence description)
  • Which layers are needed (API, DB, backend, frontend — not every feature needs all four)
  • Any constraints (naming conventions, existing patterns to follow, related entities)

Read docs/CONVENTIONS.md if it exists. Check memory/**/*.md for any architecture or design decisions relevant to this feature. If memory/architecture/repo-map.md exists, consult it to decide where new files for each layer belong (which directory owns API, data, service, and frontend code) so the scaffold follows the existing structure. After the feature lands and adds new directories, recommend /repo-map refresh so the map stays current.

2. git-engineer — branch setup

Always first. Confirm the working branch. If on main or master, ask the user to name the feature branch before proceeding. Do not start any implementation until the branch is confirmed.

3. api-designer — REST contract

Always invoke for new features that expose any endpoint. Pass:

  • The feature description and scope confirmed in step 1
  • Any existing API patterns to follow (from CONVENTIONS.md or memory)

The api-designer will produce routes, HTTP methods, request/response shapes, status codes, and auth requirements. Present the contract to the user and ask for approval before proceeding to implementation.

4. database-engineer — schema and migrations

Invoke if the feature requires new or modified tables, columns, indexes, or stored procedures. Pass the approved API contract as context so entity names and field names stay consistent.

Use isolation: "worktree" for database-engineer. Collect the worktree path and branch name it returns.

5. Backend engineer — services and controllers

Invoke csharp-engineer (or the appropriate backend engineer for this project). Pass:

  • The approved API contract
  • The migration output or schema changes from database-engineer
  • Existing patterns for services, repositories, and controllers

Use isolation: "worktree" for the engineer agent. Collect the worktree path and branch name it returns.

Run ts-linter immediately after if any .ts files were touched. Block on FAIL before continuing.

6. frontend-engineer — UI and API client

Invoke if the feature has a frontend component. Pass:

  • The approved API contract (as the source of truth for endpoint URLs, request/response shapes)
  • Any relevant component patterns from CONVENTIONS.md

Use isolation: "worktree" for frontend-engineer. Collect the worktree path and branch name it returns.

Run ts-linter immediately after. Block on FAIL before continuing.

Sequencing note: frontend-engineer must run after csharp-engineer because the frontend depends on the API surface being defined. Do not run them in parallel.

6a. Verify worktree base

isolation: "worktree" (steps 4–6) only branches from the feature branch's HEAD if worktree.baseRef is "head" in settings.json. If unset or "fresh" (the harness default), it silently bases new worktrees on local/origin main instead — regardless of what branch you're on. Before the review pass, verify each worktree branch collected in steps 4–6:

git merge-base --is-ancestor <feature-branch> <worktree-branch>   # correct base?
git log --oneline <feature-branch>..<worktree-branch>             # any commits at all?

An empty commit list is also a failure, even when ancestry passes. Engineers are told not to commit — merge-reviewer owns commits — so a worktree branch routinely has zero commits while the work sits uncommitted. merge-base --is-ancestor is trivially satisfied then, so this check passes and merge-reviewer's later git merge --no-ff merges nothing while reporting success, silently stranding the work. If the commit list is empty, check git -C <worktree-path> status --short: modifications mean use the repair recipe below (it captures uncommitted changes by design); a clean worktree means the engineer changed nothing, which is a finding in its own right.

Non-zero exit means the worktree is stale and missing feature-branch-only commits. Repair before continuing:

git -C <worktree-path> diff "$(git -C <worktree-path> merge-base main HEAD)" > /tmp/<worktree-branch>.patch
git -C <worktree-path> reset --hard <feature-branch>
git -C <worktree-path> apply --3way /tmp/<worktree-branch>.patch

If the patch conflicts, stop and route back to the responsible engineer with the conflicting file list.

7. Review pass

Run in parallel:

  • code-reviewer — on all layers
  • security-reviewer — always for new API endpoints and data access
  • performance-reviewer — always for new database queries and API endpoints

8. test-engineer

After code-reviewer completes. Cover all new public methods, API endpoints, and frontend components.

9. merge-reviewer

No plan governs a scaffold run, deliberately. This skill passes no plan_id, so merge-reviewer's gate 4a reports "not applicable" and neither the acceptance bars nor the ## Deviations checks apply. Plan consumption is opt-in per invocation, and this skill never invokes tech-lead at all — its dependency order (contract → schema → backend → frontend) is the plan, expressed as the skill's own steps rather than as an artifact. Do not add plan_id handling here without first deciding who writes the plan, since there is currently no planner in this pipeline to write one.

Final gate. Pass the worktree branch names from steps 4–6 and a summary of all pipeline stages.

If PASS: proceed to step 9a. If FAIL: retry up to 2 cycles, routing findings back to the responsible engineer. Re-run the verification in step 6a against any new worktrees before continuing. Collect new paths/branches and pass them to the next merge-reviewer invocation.

9a. Worktree cleanup verification

merge-reviewer owns worktree cleanup on the PASS path (its Step 0a removes each worktree, deletes its branch, and prunes). After a PASS, just verify nothing was left behind:

git worktree list
git worktree prune

Only if the pipeline failed or was abandoned before merge-reviewer ran (or merge-reviewer stopped early on a merge conflict), clean up manually using the worktree paths and branch names collected in steps 4–6:

git worktree remove <worktree-path> --force
git branch -D <worktree-branch>
git worktree prune

If a worktree path no longer exists, skip the git worktree remove for that path and proceed to branch deletion. Do not skip cleanup on failure — stale worktrees accumulate and confuse future pipelines.

10. git-engineer — push and PR

After step 9a completes. Ask the user whether to push and open a pull request. Include the API contract summary in the PR description.

Gotchas

  • Frontend running before backend is ready: The frontend depends on the API contract being finalized. Never run frontend-engineer in parallel with csharp-engineer — the endpoint shapes must be locked first.
  • API contract not approved before engineers start: If the user skips api-designer approval and an engineer implements against a wrong shape, you will need to redo both layers. Always get explicit approval on the contract before step 4.
  • Mid-pipeline failure: If a layer fails (e.g., database-engineer errors out), stop and surface the failure to the user before continuing. Do not skip a broken layer and proceed to the next — downstream layers depend on it.
  • Worktree not cleaned up after FAIL: If merge-reviewer returns FAIL and the user abandons the scaffold, still run the worktree cleanup commands from step 9a. Stale worktrees accumulate and confuse future pipelines.
  • Schema changes not committed before backend: The csharp-engineer must have access to the migration output from database-engineer. Pass the schema diff explicitly — the engineer cannot read an uncommitted migration from a different worktree.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.