Startup skill — install, run, validate

Natural invocations

• "start"
• "set up the repo"
• "install everything and verify it works"
• "run setup on template_code_project"
• "does this repo work out of the box?"
• (agent pointed at repo with no other context)

Inputs to confirm

• Repo root — confirmed by presence of run.sh, AGENTS.md, infrastructure/, projects/templates/template_code_project/.
• OS — macOS or Linux (Windows: use Docker; see docs/CLOUD_DEPLOY.md).
• Ollama — optional; LLM stages auto-skip when absent.

Workflow

Step 0: Orient

Read START_HERE.md (3 min, project overview + key principles). Confirm you are in the repo root.

bash
ls run.sh AGENTS.md CLAUDE.md infrastructure/ projects/templates/template_code_project/

Gate: All paths exist → continue. Missing run.sh → not in repo root, abort and navigate there first.

Step 1: Check prerequisites

bash
pandoc --version   # need any 2.x or 3.x
xelatex --version  # need any version
uv --version       # need 0.4.x or later

If xelatex missing (macOS):

bash
brew install --cask basictex
sudo tlmgr update --self
sudo tlmgr install multirow cleveref doi newunicodechar subcaption bm

If xelatex missing (Linux):

bash
sudo apt-get install -y texlive-xetex texlive-fonts-recommended fonts-dejavu

If pandoc missing:

bash
brew install pandoc          # macOS
apt-get install pandoc       # Linux

If uv missing:

bash
Follow the [checksum-verified uv installation instructions](../../operational/build/dependency-management.md#installing-uv).

Gate: All three tools on PATH → continue.

Step 2: Install Python dependencies

bash
uv sync

Gate: Exit 0, no errors → continue. On failure: check a supported Python 3.10–3.14 interpreter is available and re-run.

Step 3: Install pre-commit hooks

bash
pre-commit install
pre-commit install --hook-type pre-push

Gate: Both commands report installed at .git/hooks/... → continue.

Step 4: Run core pipeline on template_code_project

bash
./run.sh --pipeline --project templates/template_code_project --core-only

This runs 8 core stages (no LLM required): clean, setup, infra tests, project tests, analysis, render, validate, copy. Wall-clock: 2–5 minutes.

Gate: Exit 0 with all stages showing success → continue. On any stage failure, see Triage below.

Step 5: Validate project tests + coverage

bash
uv run pytest projects/templates/template_code_project/tests/ \
  --cov=projects/templates/template_code_project/src \
  --cov-fail-under=90

Gate: Exit 0, coverage ≥ 90% → continue.

Step 6: Validate PDF output

bash
# Confirm PDF exists
ls output/templates/template_code_project/pdf/template_code_project_combined.pdf

# Validate content
uv run python scripts/pipeline/stage_04_validate.py --project templates/template_code_project

# Optional: open
open output/templates/template_code_project/pdf/template_code_project_combined.pdf   # macOS

Gate: PDF file exists and validation exits 0 → continue.

Step 7: Run repo gates

bash
uv run python scripts/audit/check_template_drift.py --strict
uv run python scripts/gates/module_line_count_check.py
uv run python -m infrastructure.core.health

Gate: All three exit 0 → setup is complete.

Deliverables

Report the outcome of each checkpoint in this structure:

STARTUP VALIDATION REPORT
=========================
Step 0: Orient            ✅ / ❌ [repo root confirmed / missing files: ...]
Step 1: Prerequisites     ✅ / ❌ [pandoc X.X, xelatex X.X, uv X.X / missing: ...]
Step 2: uv sync           ✅ / ❌
Step 3: Pre-commit hooks  ✅ / ❌
Step 4: Core pipeline     ✅ / ❌ [stages: 0/1/2/3/4/5/6/9 — first failure: ...]
Step 5: Tests + coverage  ✅ / ❌ [coverage: XX% / threshold 90%]
Step 6: PDF validation    ✅ / ❌ [PDF at output/templates/template_code_project/pdf/...]
Step 7: Repo gates        ✅ / ❌

OVERALL: PASS / FAIL
Time: Xm Xs

Do not declare PASS unless every step is ✅. A partial PASS is a FAIL.

Triage

Stage 1 (Environment Setup) fails

bash
uv run python scripts/pipeline/stage_00_setup.py --project templates/template_code_project

Read the error. Usually a missing system tool or wrong Python version.

Stage 2/3 (Tests) fails

bash
# Infrastructure tests
uv run pytest tests/infra_tests/ --cov=infrastructure --cov-report=term-missing

# Project tests (isolated)
uv run pytest projects/templates/template_code_project/tests/ \
  --cov=projects/templates/template_code_project/src \
  --cov-report=term-missing -v

Stage 4 (Analysis) completes in < 2 seconds with no figures

Missing project package in root .venv. Run the analysis script directly to see the actual error:

bash
uv run python projects/templates/template_code_project/scripts/optimization_analysis.py

Fix: add the missing package to root pyproject.toml → uv sync.

Stage 5 (PDF Rendering) fails

bash
uv run python -m infrastructure.rendering.latex_package_validator

Install missing packages with sudo tlmgr install <package>. Common: multirow, cleveref, doi, newunicodechar.

PDF shows ?? for references

Normal on the first LaTeX pass — the pipeline auto-runs multi-pass. Recheck after a full pipeline run.

Coverage below 90%

bash
uv run pytest projects/templates/template_code_project/tests/ \
  --cov=projects/templates/template_code_project/src \
  --cov-report=term-missing

Lines marked miss are the gap. Add tests for those lines.

After PASS

The repository is fully operational. Next steps:

| Goal | Resource | |------|----------| | Create a new project | ../../../docs/guides/fork-an-exemplar.md | | Write a manuscript | ../academic-paper/SKILL.md | | Debug a pipeline failure | ../pipeline-debugging/SKILL.md | | Full health audit | ../comprehensive-assessment/SKILL.md | | Understand architecture | ../../../docs/core/architecture.md |

See also ../../../AGENTS.md (full system reference) and ../../../CLAUDE.md (command cheatsheet).