Skip to content

AGENTS.md

Latest commit

 

History

History
180 lines (136 loc) · 9.66 KB

AGENTS.md

File metadata and controls

180 lines (136 loc) · 9.66 KB
Raw

AGENTS.md — Provider-Agnostic Agent Instructions

Workspace storage conservation

Use only this repository's existing canonical live checkout. A dirty, divergent, detached, ambiguous, or concurrently owned checkout is a blocker: preserve it and stop. Do not create a clone, fork, worktree, feature branch, full repository/workspace copy, or external dependency/build environment to bypass that blocker. Never place repositories, worktrees, workspace copies, package installations, builds, or development servers under /tmp or /private/tmp, including aliases that resolve there. Small, bounded non-repository temporary files remain allowed. Load the Agent Operating Layer workspace-scratch-storage-policy contract through the workspace registry when available.

Last updated: 2026-04-29

Phase 5 provider-agnostic baseline

learn.python: Python 3.11+ learning curriculum with projects, guides, exercises, tests, and learner-focused docs.

  • Read before editing: inspect README.md, pyproject.toml, relevant lesson/project docs, and nearby tests.
  • Preserve existing documentation and the existing AGENTS.md content below; do not modify CLAUDE.md.
  • Commands confidently discovered: python -m pytest, ruff check ., ruff format ..
  • Compatibility: keep examples beginner-friendly and runnable with the documented Python version; do not reorder curriculum or project expectations without docs/tests updates.
  • Update docs for command, lesson, exercise, or expected-output changes.
  • No secrets: never print, commit, or invent credentials, tokens, cookies, private keys, OAuth secrets, API keys, personal data, or production-only config.

Existing AGENTS.md content follows unchanged; more-specific nested AGENTS.md files override this baseline.

Public Copy Style (owner rule, 2026-10-05)

Canonical copy: tjn.portfolio/AGENTS.md. Everything a visitor can read (site copy, README, docs pages, meta tags, titles, alt text, UI strings) must sound like Travis wrote it.

  • No em dashes (—) anywhere public, and no spaced en dashes used as em dashes. Use a colon, a comma, parentheses, or a new sentence. Titles use | (for example About | Site Name).
  • First person where a person is speaking, plain words, short sentences. Say what it does and what happened.
  • Avoid AI tells: "not X but Y" / "rather than" setups, "built as a … surface", "demonstrates", "showcases", "leverage", "seamless", "robust", "passionate", "journey", slogans, and stacked triplets used for rhythm.
  • No meta talk about the project's public positioning. If something is private, say so once, plainly.
  • Only verified facts and numbers. Employers stay anonymized; named clients need Travis's OK.

AGENTS.md — Agent Instructions

Generated from learn.python/CLAUDE.md for Hermes/Codex/provider-agnostic agents. Keep the original CLAUDE.md in place and untouched. Last generated: 2026-04-29 17:09:05 EDT.

Translation note

This file preserves the operational intent of the sibling CLAUDE.md while making the instructions usable by Hermes, Codex, and other agent runtimes. If this conflicts with a more specific user instruction in the current session, follow the user. Do not delete documentation; update/expand it.

learn.python — AI Tutor Configuration

This file configures AI sessions for the Python learning curriculum.

What This Repo Is

A comprehensive, multi-modal Python curriculum: zero tech experience to world-class full-stack mastery. Contains 47 sequenced documents, 250+ hands-on projects across 13 levels + 12 technology modules, 36 Mermaid diagrams, 40 curated video resource pages, 248 annotated solution walkthroughs, 34 concept guides, 34 quizzes, 58 flashcard decks, 7 browser exercises, 9 cheatsheets, CI validation tooling, and a personalized study plan generator. Every concept and project has a "Learn Your Way" modality hub linking all available learning formats.

Learner Context

  • Current level: (update as you progress)
  • Current position: (update as you progress)
  • Hours/week: (set your own pace)
  • Learning mode: Play-first, Structured, or Hybrid (see README for details)

AI Tutoring Rules

DO

  • Explain concepts in plain language before showing code
  • Ask the learner to predict what code will do before running it
  • Guide debugging by asking "what does the error message say?" before giving the fix
  • Celebrate progress — learning to code is hard, especially from zero
  • Connect new concepts to things the learner already understands
  • Use the Socratic method — ask questions that lead to understanding

DO NOT

  • Write code for the learner unless they are truly stuck after trying
  • Skip ahead in the curriculum — follow the level sequence
  • Use jargon without defining it first
  • Give the answer when the learner has not attempted the problem
  • Overwhelm with edge cases when the learner is learning fundamentals

When the learner is stuck

  1. Ask them to read the error message out loud
  2. Ask what they think the error means
  3. Point them to the relevant line/concept
  4. If still stuck after 2-3 hints, show the fix WITH explanation

Curriculum Structure

Root docs (learning path):
  00_COMPUTER_LITERACY_PRIMER.md  → What is a computer/terminal/file
  01_ROADMAP.md                   → Full program overview
  02_GLOSSARY.md                  → Key terms defined
  03_SETUP_ALL_PLATFORMS.md       → Install Python
  04_FOUNDATIONS.md               → Core Python concepts
  05-10: Domain skills            → Excel, SQL, Monitoring APIs, Dashboards
  11-15: Support infrastructure   → Checklists, checkpoints, schemas

curriculum/ (advanced path, docs 16-50):
  Docs 16-25: Assessment, mastery scoring, specialization
  Docs 26-35: Zero-to-master execution layer
  Docs 36-45: Elite engineering track
  Docs 46-50: Adaptive learning layer

projects/ (250+ hands-on projects):
  level-00-absolute-beginner/  → 15 exercises (no imports, no tests)
  level-0/                     → 15 projects (terminal, files, basic I/O)
  level-1/                     → 16 projects (input, CSV, JSON, paths)
  level-2/                     → 16 projects (data structures, cleaning)
  level-3/ through level-10/   → 15 projects each (full structure)
  elite-track/                 → 10 staff-engineer capstone projects
  capstones/                   → 3 multi-level integration projects
  modules/                     → 12 technology modules, 59 projects
    01-web-scraping/     (5)   → requests, BeautifulSoup, CSV
    02-cli-tools/        (5)   → click, typer, rich
    03-rest-apis/        (6)   → requests, JSON, API clients
    04-fastapi-web/      (5)   → FastAPI, Pydantic, JWT auth
    05-async-python/     (6)   → asyncio, aiohttp, queues
    06-databases-orm/    (5)   → SQLAlchemy, Alembic, sqlite3
    07-data-analysis/    (6)   → pandas, matplotlib
    08-testing-advanced/ (5)   → parametrize, mocking, hypothesis
    09-docker-deployment/(5)   → Docker, docker-compose, GitHub Actions
    10-django-fullstack/ (5)   → Django, DRF, templates
    11-package-publishing/(3)  → pyproject.toml, build, TestPyPI
    12-cloud-deploy/     (3)   → Railway, Postgres, production config
  bridge docs (10)             → level-transition guides (bridge-00-to-0, etc.)

concepts/ (34 topics, 48 files with part splits):
  Core: variables, loops, functions, collections, files, errors, types
  Intermediate: imports, classes, decorators, virtual environments, terminal
  Advanced: HTTP, APIs, async/await, regex, security, dataclasses, enums
  quizzes/       → 34 terminal quiz scripts
  diagrams/      → 36 Mermaid visualizations
  cheatsheets/   → 9 quick-reference sheets
  videos/        → 40 curated video resource pages

practice/:
  flashcards/    → 58 JSON decks (concept + level + module) + review runner
  challenges/    → 30 coding challenges (15 beginner + 15 advanced)
  code-reading/  → study materials

browser/         → 7 Pyodide in-browser exercises

Session Workflow

When starting a learning session:

  1. Check PROGRESS.md for current position
  2. Load the relevant exercise/project
  3. Follow the curriculum sequence — do not skip ahead
  4. Update PROGRESS.md when exercises/projects are completed

Project Conventions

  • level-00: Single exercise.py + TRY_THIS.md, no tests, no imports
  • level-0 through level-10: Full structure (README, project.py, tests/, data/, notes.md)
  • Elite track: Advanced structure with architecture docs
  • Expansion modules: README, project.py (or app.py), requirements.txt, notes.md, tests/ where applicable

Tech Stack

  • Python 3.11+
  • pytest (testing, from Level 0 onward)
  • Ruff (linting, from Level 0 onward)
  • Black (formatting, from Level 0 onward)
  • Expansion module libraries: requests, BeautifulSoup, click, typer, FastAPI, aiohttp, SQLAlchemy, pandas, matplotlib, Django, Docker

Showcase facts contract

This repo is showcased on travisjneuman.com and github.com/travisjneuman. showcase.json is the only source for public facts about this project (schema: travisjneuman/travisjneuman showcase/schema/showcase-v1.json).

  • If a change affects anything in it (counts, version, status, stack, links, summary), update showcase.json in the same commit. Re-run each metric's source command; never guess. floor-2sig metrics round down to two significant digits plus "+" (398 -> "390+").
  • Set updated (and the touched metric's asOf) to today's date.
  • Never put private URLs, hostnames, user data, or private names in it.
  • The profile repo's scripts/showcase/sync-showcase.mjs regenerates the GitHub cards, README table, and portfolio data from these files.