web-service-scaffold

name	web-service-scaffold
description	Use only when explicitly invoked as $web-service-scaffold to run the bundled web-service scaffold script.

Web Service Scaffold

Turn a web-service request into a copied baseline scaffold. The scaffold is a platform baseline, not a full product implementation. This global skill owns web-service defaults; the global AGENTS.md does not.

Scope Control

• Only ask for the service name if it is missing.
• Do not ask for target directory by default. Use the current working directory as the target repository root.
• Do not ask whether this is a new or existing repository. Detect it: if the current working directory has no .git/, run git init; otherwise preserve and extend the existing repository.
• Do not invent a product domain, workflow, data model, or feature set from a vague scaffold request.
• Default scaffold surface is deliberately small:
  • Express health endpoint.
  • Vite React shadcn/ui shell with one accessible main view.
  • Minimal Docker deploy path.
  • Minimal docs and tests proving the scaffold contract.
• If the user asks for a product feature in the same request, run the scaffold script first, then stop and report the scaffold result unless the user explicitly asks to continue into feature implementation.
• Avoid hand-written scaffold generation. The baseline is a one-shot copy from bundled assets.

Scope

• Use the current working directory as the target repository root.

• Use this skill's bundled script as the scaffold implementation. It takes the target repository root and the service name as arguments:

  bash scripts/install_project_codex.sh <target-root> <service-name>
  

  That path is relative to this skill's own directory, which the loader reports when it opens the skill — not to the target repository, which has no scaffold script of its own until the baseline is copied.

• First action after extracting the service name: run the bundled script.

• Do not read checklist, markup contract, companion skills, package files, or repository tree before running the script for a scaffold-only request.

• The script creates the Git repository when .git/ is absent, installs the project contract, copies the complete baseline root from assets/baseline/root, substitutes service placeholders, generates the local apps/<service>/docker/.env from the committed docker/env.defaults template, and creates the initial scaffold suite/report/summary.

• assets/baseline/root is the source of truth. It includes root AGENTS.md, .codex/skills, monorepo config, service source, Docker files, docs, and scaffold test artifacts. Do not copy AGENTS.md or .codex through a separate path.

• Do not hand-create baseline scaffold files that already exist under assets/baseline/root.

• Do not run npm install, npm run build, npm test, npm run deploy, browser checks, or git commit after the scaffold script unless the user explicitly asks for verification, deployment, or commit.

• Do not generate project files outside a Git repository.

• One service = one app module.

• App shape: src/server + src/front.

• One service app = one generated domain package: apps/<service> pairs with packages/<service>_domain.

• The generated domain package uses src/common, src/server, and src/front.

• Apps may depend on packages; packages must never depend on apps.

• App modules own framework lifecycle and orchestration. Domain rules, invariants, and framework-independent product logic belong in the paired domain package, not in additional domain packages.

The scaffold installs before it returns

The scaffold hands back a project that is ready to build. The installer runs npm ci against the committed package-lock.json as its last step, so the service compiles and deploys without a separate setup instruction.

This is deliberate rather than incidental: leaving the install to the first deploy only moves the wait somewhere less expected, and a scaffold that cannot compile is not finished. The install is also what produces the workspace link, which npm writes with an absolute target and no copy could carry.

The installer writes the deploy install marker afterwards, so the first npm run deploy reports phase=install status=skipped reason=up-to-date rather than installing twice.

The lockfile it installs from is regenerated with:

bash scripts/update-baseline-lockfile.sh

Run that after changing any dependency in a baseline manifest.

Shipping an already-installed node_modules in the baseline was tried and rejected. It is roughly 1.8x faster and works offline, but it puts 7257 third-party files under version control, and secret scanning refuses the commit outright - test fixtures inside those packages contain token-shaped strings.

Maintaining The Baseline

assets/baseline/root is the only reference implementation of the skills it ships. Every rule those skills state must be true of a freshly scaffolded project, and every bundled verifier must pass against it. That is what makes the baseline general rather than a copy of one past project.

After changing anything under assets/, run the guard:

bash scripts/check-baseline.sh

It installs the baseline into a throwaway directory and proves: no absolute paths, no foreign package manager, no host Node version gate, no hardcoded port, no product-specific identifier from references/denied-identifiers.txt, every placeholder substituted, AGENTS.md routing matching the installed skills exactly, every bundled verifier clean, the deploy entrypoint owned by the project, every script parsing, and the copy being runnable as delivered - installed tree, lockfile, workspace link, and install marker all present.

When a project-specific name is found in the baseline, delete it and add it to references/denied-identifiers.txt so the same leak cannot return silently.

Non-Negotiable

• Git repository creation is the first filesystem mutation for a new scaffold: it is handled by the bundled install script.
• Follow repo AGENTS.md.
• Let the script copy AGENTS.md and .codex/skills from assets/baseline/root together with the rest of the baseline.
• The copied baseline already contains monorepo, Docker, docs, test, and headless-browser-friendly markup contracts.
• Frontend implementation must use shadcn/ui components, Tailwind CSS, and Radix UI primitives by default. Do not introduce another UI component framework unless the user explicitly overrides this project contract.
• Prefer vendoring reusable internal packages over reimplementation when relevant.
• Scaffold npm workspaces only: root workspaces for apps/* and packages/*, package-lock.json committed, and dependency changes through npm commands after the scaffold when requested.
• Do not introduce another package manager: no yarn.lock, .yarnrc.yml, pnpm-lock.yaml, or pnpm-workspace.yaml.
• Create standard npm run deploy, but do not execute it during fast scaffold unless explicitly requested.

Required Output State

• Repo root has a web-service AGENTS.md copied from assets/baseline/root.
• Copied AGENTS.md includes the direct-code abstraction budget: no one-line private helpers, no single-use helper chains, no nested helper decomposition without concrete duplication or a meaningful boundary, and no namespace-only classes.
• Repo .codex/skills/ contains the web-service companion skill set copied from assets/baseline/root/.codex/skills.
• Baseline files were copied from assets/baseline/root by the script in one pass, not reauthored manually.
• apps/<service> exists and is wired.
• packages/<service>_domain exists, is wired as the app's single domain package dependency, and exposes src/common, src/server, and src/front.
• Front is a minimal Vite-built shadcn/ui shell, and prod serving is only through Express server.
• Front markup exposes the small set of landmark, heading, and state contracts needed for scaffold smoke tests.
• Docker assets and root compose integration exist.
• Docs are written during scaffolding, not later.
• Test suite and strict JSON report exist for scaffold contract checks.
• No install/build/test/deploy/browser/commit step was run unless explicitly requested.

Completion Rule

For a scaffold request, completion is the successful return of this skill's scripts/install_project_codex.sh "$PWD" <service-name> plus the script's own required-file checks and generated scaffold suite/report/summary. Stop there. Do not run dependency install, build, tests, deploy, browser checks, or commit unless the user explicitly asks for those actions.