PathMX CS1 Companion Repo

This repository is the companion starter template for the paper Toward True Differentiated Instruction with PathMX and Curriculum as Code (CCSC NE 2026). It provides a minimal, working PathMX scaffold for a typical CS1 course that instructors can adapt with the help of a coding agent.

It is designed for both instructors and agents to use:

• root files provide authoring context, conventions, and setup guidance
• student-facing material lives in paths/
• paths/index.path.md is the root entry to the student graph

The default sample language is Python because it is common in CS1, but the scaffold is meant to be adapted to any common introductory language.

Repository Layout

.
├── AGENTS.md
├── agent-setup.guide.md
├── course.outcomes.md
├── course.style-guide.md
├── cohort/
│   └── cohort.profile.md
├── students/
│   └── student-ax7k.persona.md      # example filled persona
├── templates/
│   ├── template.lab.md
│   ├── template.persona.md
│   ├── template.project.md
│   └── template.rubric.md
├── scripts/
│   ├── export-specs-to-pdf.py
│   └── export-by-type.py
└── paths/
    ├── index.path.md
    ├── labs/
    │   ├── lab-01.spec.md
    │   └── lab-01-fitness.spec.md    # example themed variant
    ├── projects/
    │   ├── project-1.spec.md
    │   └── project-1.rubric.md
    └── resources/
        └── getting-started.guide.md

What You Need

• A text editor or IDE with coding-agent support (e.g., Cursor, VS Code with Copilot, or a CLI agent)
• Basic comfort with Markdown files and a terminal
• Python 3 (for the example export scripts; also the default CS1 language)
• Pandoc (optional, for the export scripts)

How To Use This Repo

1. Read course.outcomes.md and course.style-guide.md.
2. Open AGENTS.md with your coding agent.
3. Ask the agent to adapt the scaffold to your own course.
4. Keep all student-facing output inside paths/.
5. Use paths/index.path.md as the root document for the student graph.

Suggested Starter Prompts

Use these as-is or adapt them:

Read README.md, AGENTS.md, course.outcomes.md, and course.style-guide.md, then help me adapt this repo for my CS1 course.

Update the scaffold for a Java-based CS1 course while preserving the PathMX structure and keeping all student-facing material in /paths.

Create paths/labs/lab-02.spec.md that follows the style guide, aligns with the outcomes, and links cleanly from paths/index.path.md.

PathMX Conventions

PathMX uses type-hinted filenames of the form {name}.{type}.md. The type hint describes the file's role within the course domain. Because the type is in the filename, agents can infer what a file is from ls or tree output alone, and downstream scripts can target specific types (e.g., "export all .spec.md files to PDF").

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

• .path.md — graph root documents that link to labs, projects, and other course material
• .spec.md — lab or project specifications, which may be used to create variant assignments
• .rubric.md — evaluation criteria for assignments and projects
• .guide.md — supporting instructions for students or instructors
• .persona.md — optional, anonymized instructor-facing student profiles (no PII)
• .profile.md — aggregated cohort context

Types you might add as the course grows: .slides.md for lectures, .schedule.md for a weekly plan, .feedback.md for student-facing code review, .feedback-harness.md for bundled review context, or anything else that fits the domain.

Privacy

Do not commit personally identifiable student information.

• Use anonymized IDs only in .persona.md files
• Keep any identity mappings outside the repo or in ignored private files
• Treat cohort/cohort.profile.md as aggregated, optional instructor context

What This Repo Does Not Include

This starter keeps the scope minimal. It does not include:

• publishing/deployment pipelines
• feedback harnesses
• LMS integrations

For advanced workflows, see pathmx.dev (WIP).

The scripts/ directory includes lightweight Python examples to demonstrate how type-hinted filenames enable targeted export. These are starting points -- ask your agent to help you build more (see AGENTS.md).