---
name: docxology/template-startup
source: https://app.decimal.ai/s/docxology-template-startup@2/SKILL.md
source_sha256: 40dcba7540dc
---

# 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`](../../../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](#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`](../../../docs/guides/fork-an-exemplar.md) |
| Write a manuscript | [`../academic-paper/SKILL.md`](../academic-paper/SKILL.md) |
| Debug a pipeline failure | [`../pipeline-debugging/SKILL.md`](../pipeline-debugging/SKILL.md) |
| Full health audit | [`../comprehensive-assessment/SKILL.md`](../comprehensive-assessment/SKILL.md) |
| Understand architecture | [`../../../docs/core/architecture.md`](../../../docs/core/architecture.md) |

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