Skip to content

English · Español

Phase 00 — Foundations

Requires: none — this phase is the entry point Teaches: reproducibility · seeding · lockfile · pre-commit · ci · mypy Jump to any chapter from the phase reference index.

Chapter map

Spec section: LYNX_CORTEX.md §4 row 0. Goal: a reproducible, hygienic, well-typed Python environment where the rest of the curriculum can run. Nothing more, nothing less.

🇪🇸 Resumen. Fase de higiene: entorno reproducible (seeds, lockfile, manifiestos), tooling (ruff, mypy, pytest, pre-commit, bandit, pip-audit), CLAUDE.md + .claude/ para que toda sesión futura respete las reglas del proyecto. No tocamos NumPy ni mates aún.

Definition of Done

The phase is only done when all of the following are true (verified by the phase-gatekeeper subagent — see .claude/agents/phase-gatekeeper.md):

  • just setup && just lint && just test is green on a fresh clone.
  • CI passes on a stub commit (badge green on main).
  • CLAUDE.md + .claude/settings.json + .claude/commands/ + .claude/agents/ populated and a slash command (/phase-checkpoint) resolves in a new Claude Code session.
  • learners/borja/ initialized; progress.md row 00 reflects in-flight → done at close.
  • theory/, lab/, solutions/ populated.
  • lab/00-env-checklist.md completed by Borja.
  • just audit-deps (pip-audit) clean.
  • bandit clean on src/.
  • First journal entry exists (learners/borja/journal/2026-05-22.md).
  • src/utils/BLUEPRINT.md + src/utils/README.md written.

Read order

  1. theory/00-motivation.md — why hygiene before AI.
  2. theory/01-reproducibility.md — seeds, lockfiles, manifests.
  3. theory/02-engineering-hygiene.md — pre-commit, ruff, mypy as policy.
  4. theory/03-dev-environment.md — IDE, plugins, CLI, Claude Code customization.
  5. lab/00-env-checklist.md — install + verify (Borja runs).
  6. lab/01-write-the-justfile.md — extend Justfile with one new recipe.
  7. lab/02-write-the-pre-commit-hooks.md — add one custom hook.
  8. lab/03-seed-by-hand.md — re-implement seed_everything without peeking.
  9. Only after lab attempts → solutions/*.md.

Layout

docs/phase-00-foundations/
├── README.md                  (this file)
├── theory/
│   ├── 00-motivation.md
│   ├── 01-reproducibility.md
│   ├── 02-engineering-hygiene.md
│   └── 03-dev-environment.md
├── lab/
│   ├── 00-env-checklist.md
│   ├── 01-write-the-justfile.md
│   ├── 02-write-the-pre-commit-hooks.md
│   └── 03-seed-by-hand.md
├── solutions/
│   ├── 01-justfile-ref.md
│   ├── 02-precommit-ref.md
│   └── 03-seeding-ref.md
├── notebooks/                 (any executable demos)
├── diagrams/                  (mermaid + svg)
└── PHASE_00_REPORT.md         (written at phase close)

Phase report

After /phase-report 00, PHASE_00_REPORT.md lands at repo root (the report is a top-level artifact, not inside this directory, because it's the gate to Phase 1).

Further reading

Optional — enrichment, not required to pass the phase.