Skip to content

AGENTS.md

Latest commit

 

History

History
119 lines (81 loc) · 4.74 KB

AGENTS.md

File metadata and controls

119 lines (81 loc) · 4.74 KB
Raw

PathMX Agent Instructions

You are assisting an instructor who is using this repository as a PathMX starter for a CS1 course.

Primary Goals

  • help the instructor adapt the scaffold quickly
  • keep the repository minimal and easy to understand
  • place all student-facing curriculum in paths/
  • preserve PathMX conventions and clean cross-links

Repository Split

  • Root files are for instructor and agent onboarding.
  • paths/ contains all student-facing material.
  • paths/index.path.md is the root entry to the student graph.

If you create or revise student-facing content, it belongs in paths/ and should be linked from paths/index.path.md when appropriate.

Start Here

Before generating new course material:

  1. Read README.md
  2. Read course.outcomes.md
  3. Read course.style-guide.md
  4. Read paths/index.path.md
  5. Check any relevant template in templates/

Default Assumptions

  • This is a standard CS1 course.
  • The default sample language is Python.
  • The instructor may switch to Java or another common CS1 language.
  • Student-facing work should stay beginner-appropriate unless the instructor changes scope.

If key course facts are missing, ask for them before generating substantial new material. At minimum, clarify:

  • course name/code
  • programming language
  • student population
  • any course-specific constraints or themes

PathMX Conventions

PathMX uses type-hinted filenames of the form {name}.{type}.md. The type hint is an ad-hoc label that describes the file's role within the course domain. Because the type appears in the filename, agents can infer what a file is from ls or tree output alone, without reading its contents. Type hints also enable targeted automation (e.g., "export all .slides.md files to PowerPoint").

The type vocabulary is open-ended. Use whatever nouns fit the course. This starter includes:

  • .path.md — graph root or path entry files
  • .outcomes.md — course outcomes
  • .style-guide.md — writing and content rules
  • .spec.md — labs and projects
  • .rubric.md — evaluation criteria
  • .guide.md — supporting instructions
  • .persona.md — optional anonymized student profiles
  • .profile.md — aggregated cohort context

Types you might add as the course grows:

  • .slides.md — lecture slides
  • .schedule.md — weekly schedule
  • .syllabus.md — course syllabus
  • .feedback.md — student-facing feedback
  • .feedback-harness.md — bundled context for agent-generated code review

Use YAML frontmatter in curriculum files to attach metadata (outcomes, difficulty, prerequisites, theme, etc.) that supports both agent inference and deterministic tooling.

Use relative markdown links between related files. Agents follow these links to navigate context, so well-linked files produce better results.

Student-Facing Content Rules

  • Keep all student-facing files in paths/
  • Keep the language clear, direct, and encouraging
  • Keep examples focused on one or two concepts at a time
  • Show expected output where it helps beginners
  • Keep themes secondary to learning goals
  • Prefer simple console-based assignments for baseline CS1 examples

Instructor-Facing Content Rules

  • Keep root scaffolding concise and reusable
  • Preserve the distinction between optional personalization and required course structure
  • Do not create filled student persona examples in the public scaffold unless explicitly asked

Privacy Rules

Never include personally identifiable information.

  • Use anonymized IDs only in .persona.md files
  • Keep mappings between IDs and real identities outside the repo or in ignored files
  • Keep cohort/cohort.profile.md aggregated and non-identifying

When Adding New Work

When generating a new student-facing artifact:

  1. align it to course.outcomes.md
  2. follow course.style-guide.md
  3. place it under paths/
  4. link it from paths/index.path.md or another relevant student-facing file
  5. preserve beginner-friendly scope unless instructed otherwise

Helping Build Scripts And Tooling

If the instructor wants to export, transform, or batch-process curriculum files, help them write simple scripts that leverage type-hinted filenames to select files. The scripts/ directory has starter examples.

When building new scripts:

  • prefer Python and standard tools (pandoc, etc.)
  • use glob patterns on the type hint (e.g., **/*.spec.md) to select files
  • keep scripts minimal and self-contained
  • write output to exports/ (which is gitignored)

This is a key part of the PathMX workflow: agents help build the tooling, not just the curriculum.

Out Of Scope For This Repo

Do not add LMS integrations, deployment pipelines, or real-time student-facing agents unless the instructor explicitly asks. Direct advanced workflow questions to pathmx.dev.