--- name: build description: Build, review, and assess full-stack apps (FastAPI + React + Docker) against a set of conventions. Three modes via the first argument — new (phased build), review (check the branch's changes), assess (whole-repo conformance audit). argument-hint: [new|review|assess] [project-name | scope] allowed-tools: Bash(*), Read, Write, Edit, Glob, Grep, Agent --- # Build: $0 This skill has **three modes**, chosen by the first argument (`$0`): | `$0` | Mode | What it does | Writes code? | |------|------|--------------|--------------| | `new` | **New build** | Scaffold/continue a phased full-stack build | Yes | | `review` | **Review changes** | Review the current git branch's changes against the build conventions | No (read-only) | | `assess` | **Assess repo** | Audit the whole repo for conformance with the build conventions | No (read-only) | If `$0` is empty or unrecognized: if the working directory is an empty/new project, assume **new**; if it's an existing repo, state the three modes in one line and ask which to run. Don't guess between `review` and `assess` — confirm. The conventions that `review` and `assess` check against are the phase docs in this skill, distilled into `${CLAUDE_SKILL_DIR}/conventions.md` (the audit rubric). The phase docs themselves are canonical. --- ## Mode: `new` — phased build Remaining args: `$1` = project name (optional), `$2` = phase number (optional). ### Available Phases !`ls -1 ${CLAUDE_SKILL_DIR}/phases/ | sed 's/\.md$//'` ### Available References !`ls -1 ${CLAUDE_SKILL_DIR}/references/ | sed 's/\.md$//'` You are initializing or continuing work on a phased build. **If a phase number is provided (`$2`):** Read `${CLAUDE_SKILL_DIR}/phases/$2-*.md` (glob for the matching phase file) and execute that phase step-by-step. **If no phase number is provided:** 1. Check the current state of the project directory to determine which phases have been completed 2. Suggest which phase to run next 3. Wait for confirmation before proceeding **Phase execution rules:** 1. **Read the full phase doc** before starting any work 2. **Make the relevant decisions** (see the README's "Decisions to Make" table — deployment path, auth strategy, workers, file storage, etc.) and **ask** when a phase needs one 3. **Execute step-by-step**, following the phase doc exactly 4. **Check off each item** in the phase's checklist before moving on 5. **Do not skip ahead** — stop and confirm when a phase is complete **Reference docs** — pull in only when the app needs the capability: - `${CLAUDE_SKILL_DIR}/references/file-storage.md` — file upload/download - `${CLAUDE_SKILL_DIR}/references/background-workers.md` — async processing - `${CLAUDE_SKILL_DIR}/references/google-auth.md` — Google sign-in and/or mandatory email verification See `${CLAUDE_SKILL_DIR}/README.md` for the phase map and the decisions table. --- ## Mode: `review` — review the branch's changes Review **only what changed on the current branch** against the conventions — use this after building, or after an agent has edited the code. **Read-only**: report findings, don't fix them. Remaining arg: `$1` = scope override (optional). Default scope is the branch diff vs. its base. 1. **Read `${CLAUDE_SKILL_DIR}/conventions.md`** — the audit rubric. 2. **Establish the diff:** - Default (no `$1`): diff the branch against `main` — `git diff $(git merge-base HEAD main)...HEAD` (fall back to `master`, or to `git diff` of the working tree if there's no base). - `$1 = staged` → `git diff --cached`; `$1 = diff` → `git diff` (working tree); `$1 =` a ref/range → `git diff `. - Capture the list of changed files and the changed lines. 3. **Map each changed file to the conventions that govern it** (per `conventions.md`'s sections). Skip capabilities the app doesn't use (one-line "N/A"). 4. **Judge each change:** does it conform, introduce a violation, or leave a gap? Cite `file:line` evidence from the diff. 5. **Report** (see Severity & Output) with a verdict: are the changes conformant and safe to keep, conditionally OK (with a must-fix list), or should they be revised? --- ## Mode: `assess` — whole-repo conformance audit Audit the **entire codebase** against the conventions — a point-in-time conformance check. **Read-only**: report findings, don't fix them. Remaining arg: `$1` = subtree to scope to (optional; default is the repo root). 1. **Read `${CLAUDE_SKILL_DIR}/conventions.md`** — the audit rubric. 2. **Detect which capabilities are in use** (conventions.md §0) so optional sections are skipped cleanly rather than flagged. 3. **Check every applicable convention** against the code. Prefer Grep/Glob/Read. For a large repo, fan out with the Agent tool — one agent per area (project layout, backend, backend testing, frontend, frontend testing, docker/deploy, optional capabilities) — and synthesize. 4. **Cite concrete evidence** (`file:line`, offending pattern, or missing path) for every finding. 5. **Report** (see Severity & Output) with an overall conformance summary (counts by severity) and the top 3 things to fix. --- ## Severity & Output (`review` and `assess`) Rate every finding: - **Violation** — contradicts a stated convention (wrong structure, banned pattern, missing required piece). Must fix. - **Gap** — a convention is unmet but plausibly intentional/incomplete (e.g. tests missing for a new route). Should address. - **Note** — minor drift, naming nit, or a conformance-improving suggestion. - **Conforms** — call out the areas that are correct, so the report is a complete picture, not just a problem list. Group findings by area (matching `conventions.md`'s sections). For each: ``` [SEVERITY] — evidence: expected: fix: ``` End with the mode's verdict (review: keep / conditionally-OK / revise · assess: conformance summary + top 3 fixes). Keep it concrete and skimmable; don't restate conventions the code already follows beyond brief "Conforms" callouts. This is review-only — never edit code in these modes.