project-scaffolder

name: project-scaffolder description: > Scaffold a fully-provisioned VPS project with FastAPI backend, Vite+React frontend, PostgreSQL, Claude Agent SDK, Infisical secrets, GitHub CI/CD, MkDocs documentation, and curated agent skills. Creates everything needed to start building immediately. Use this skill whenever the user asks to scaffold, create, spin up, bootstrap, or start a new project — even if they just say "new project" or "make me an app called X". Also use when they mention wanting a new codebase, a new service, a new web application, or anything that implies standing up a fresh FastAPI/React stack on the VPS. Do NOT improvise project setup manually (e.g. uv init, mkdir) — always use this skill's scaffold.py script for consistency and completeness.

Project Scaffolder

Create a production-ready project on the VPS with a single command. This skill replaces any manual project setup — always prefer it over improvising directory structures.

Required Input

• project_name — lowercase, hyphenated (e.g., acme-dashboard). Used as directory name, GitHub repo, subdomain, systemd service prefix, and Infisical project name.
• project_description — one-liner describing the project purpose.

Prerequisites

Before running the scaffolder, ensure:

1. GitHub CLI authenticated — gh auth status must succeed on the VPS unless using --skip-github.
2. Infisical CLI installed — infisical --version must succeed unless using --skip-infisical.
3. Infisical credentials available — The UA .env must contain INFISICAL_CLIENT_ID and INFISICAL_CLIENT_SECRET. The Infisical project is auto-created by the script.
4. Core host CLIs installed — git, uv, node, npm, and docker compose must be available.
5. DNS records — Can be set up before or after scaffolding. The script will print the exact records needed.

Execution Procedure

Step 1: Collect Information

Ask the user for:

• project_name (required)
• project_description (required)

Do NOT ask for infisical_project_id — the script auto-creates it via the Infisical REST API.

Step 2: Run the Scaffold Script

cd /home/kjdragan/lrepos/universal_agent
uv run .agents/skills/project-scaffolder/scripts/scaffold.py \
  --name <project_name> \
  --description "<project_description>"

The script handles:

• Core host dependency preflight for git, uv, node, npm, Docker Compose, Infisical CLI, and GitHub CLI
• Infisical CLI preflight so generated projects are provisioned on a host that can manage Infisical secrets
• Infisical project auto-creation via REST API (idempotent — reuses existing)
• /opt permission handling with sudo fallback
• Directory creation at /opt/<project_name>/ when writable, otherwise ~/projects/<project_name>/
• Systemd, Nginx, and CI/CD templates rendered with the actual project directory
• Git initialization on main with an initial chore: initial scaffold commit
• Backend uv sync --extra dev and frontend npm install
• GitHub repository creation and push when gh is authenticated
• All project files from templates
• Port allocation (scans for next available)
• Bootstrap .env generation
• Structured project.scaffold.json metadata with paths, ports, DNS names, Infisical project ID, and install commands
• Generated scripts/preflight.sh so future agents can verify core CLIs, Infisical CLI, installed dependencies, and scaffold metadata
• Canonical .agents/skills/ skill symlinking with legacy .claude/skills/ fallback lookup

Optional flags:

• --skip-infisical — skip Infisical CLI preflight and project creation.
• --skip-install — skip dependency installation.
• --skip-github — skip GitHub repository creation and push.
• --github-owner <owner> — override the default GitHub owner (kjdragan).

Step 3: Remaining Operator Steps

After the script completes, perform only the steps that require external coordination or secrets.

3a. Create GitHub Repository (Only If Skipped Or Auth Failed)

cd <project_dir>
gh repo create kjdragan/<project_name> --private --source=. --push

3b. Seed Infisical Secrets

Copy shared API keys from UA's Infisical project to the new project:

# Get keys from UA project
ANTHROPIC_KEY=$(infisical secrets get ANTHROPIC_API_KEY --env production --plain --silent)

# Set in new project (switch to new project context)
infisical secrets set ANTHROPIC_API_KEY="$ANTHROPIC_KEY" --env production
infisical secrets set ANTHROPIC_API_KEY="$ANTHROPIC_KEY" --env development

Generate project-specific secrets:

APP_SECRET=$(python3 -c "import secrets; print(secrets.token_urlsafe(48))")
infisical secrets set APP_SECRET_KEY="$APP_SECRET" --env production
infisical secrets set APP_SECRET_KEY="$APP_SECRET" --env development
infisical secrets set DATABASE_URL="postgresql+asyncpg://postgres:postgres@localhost:<db_port>/<project_name>" --env development
infisical secrets set DATABASE_URL="postgresql+asyncpg://postgres:postgres@localhost:<db_port>/<project_name>" --env production

3c. Add GitHub Secrets for CI/CD

gh secret set TAILSCALE_OAUTH_CLIENT_ID --body "..."
gh secret set TAILSCALE_OAUTH_SECRET --body "..."
gh secret set INFISICAL_CLIENT_ID --body "..."
gh secret set INFISICAL_CLIENT_SECRET --body "..."
gh secret set INFISICAL_PROJECT_ID --body "<infisical_project_id>"

3d. Setup SSL

sudo certbot --nginx -d <project_name>.clearspringcg.com -d dev-<project_name>.clearspringcg.com

3e. Start Services

sudo systemctl daemon-reload
sudo systemctl enable --now <project_name>-db
sudo systemctl enable --now <project_name>-api
sudo systemctl enable --now <project_name>-web
sudo systemctl enable --now <project_name>-docs

3f. Run Initial Migration

cd <project_dir>/backend
uv run alembic upgrade head

Step 4: Verify

1. curl http://localhost:<backend_port>/health — should return {"status": "ok"}
2. curl http://localhost:<frontend_port> — should return HTML
3. Open https://dev-<project_name>.clearspringcg.com in browser
4. Verify gh repo view kjdragan/<project_name> shows the repo

Generated Project Stack

Curated Skills Included

The following skills are symlinked into the generated project's canonical .agents/skills/ directory from UA's skill library:

clean-code, systematic-debugging, verification-before-completion, git-commit, github, dependency-management, task-forge, skill-creator, coding-agent, deep-research, defuddle, deepwiki, image-generation, webapp-testing, pdf, media-processing, json-canvas, grill-me, ideation, just, obsidian, weather