Skip to content

AGENTS.md

Latest commit

 

History

History
252 lines (181 loc) · 7.24 KB

AGENTS.md

File metadata and controls

252 lines (181 loc) · 7.24 KB
Raw

Universal Robotics Curriculum Markdown Authoring Guide

This file defines how content agents must create learning path modules as Markdown files for any robotics curriculum (Mobile Robots, Robotic Arms, Drones, Perception, SLAM, RL, Embedded, Controls, etc.). It is optimized for the workflow: Founder gives lecture/thoughts → agents produce structured modules + lecture videos + assignments.

0) Output Rules (Non-Negotiable)

  1. One module per file, named:
    • Module X _ <Module Title>.md
  2. Use this exact section ordering in every module file:
    • # Module X: <Title>
    • ## 1. Purpose & Scope
    • ## 2. Curriculum Focus
    • ## 3. Concrete–Pictorial–Abstract (CPA) Breakdown
    • ## Updated Video List
    • ## Assignments & Practice Tasks
    • ## Final Summary
  3. Each module must explicitly include:
    • Simulation/Emulation track (even if minimal)
    • Real system track (hardware/field/bench testing), or clearly marked “optional”
  4. Keep language practical and execution-focused:
    • what learner builds, runs, measures, and submits
  5. Keep sections short and structured (bullets > paragraphs).

1) How to Convert “Founder Lecture/Thoughts” into Modules

Inputs you may receive

  • A voice note, rough lecture notes, brainstorm text, or a big outline.
  • Possibly messy ordering, repeated ideas, or jumps between topics.

Your job

  1. Extract the capability progression (what student can do after each module).
  2. Split into modules where each module:
    • has a single clear outcome
    • contains a small set of concepts that support that outcome
  3. For each module:
    • define deliverables
    • define videos
    • define assignments with measurable outputs

If the lecture contains too much material

  • Create multiple modules rather than an overloaded module.
  • Prefer 60–120 minutes total video per module (guideline, not strict).

2) Standard Module Skeleton (Copy/Paste Template)

Module :

1. Purpose & Scope

  • Overall Goal:

    1. In simulation/emulation:
    2. On real system/hardware:

  • Prerequisites:

    • <module/skills/tools required>

  • Deliverables (Must Produce):

    • <repo folder / notebook / package / config>
    • <plots/logs/bag/metrics>

  • Key Steps (Execution Path):

    • <Step 1>
    • <Step 2>
    • <Step 3>
    • <Step 4>

2. Curriculum Focus

Part A: Simulation / Emulation Track

  1. Concepts
  2. Implementation
  3. Validation

Part B: Real System / Hardware Track (or Optional)

  1. Bringup
    • <drivers, interfaces, calibration>
  2. Runtime Testing
    • <tests, limits, safety>
  3. Debugging
    • <common failures + checks>

3. Concrete–Pictorial–Abstract (CPA) Breakdown

Concrete (Hands-On / Doing)

  • <commands they run, nodes they launch, physical tests, experiments>

Pictorial (Visual / Intuition)

  • <RViz/Gazebo plots, diagrams, animations, dashboards>

Abstract (Math / Architecture / Theory)

  • <equations, transforms, control loops, state machines, data flow>

Updated Video List

Naming convention: M<N>_V<NN>_<Title>_[F|S|A]

  • [F] face recording (teaching/explaining)
  • [S] screen recording (demo/implementation)
  • [A] animation (editor instructions included)
  • Optional [U] prefix for “update later” items

Part A: Simulation / Emulation

  1. MV01<Intro & Outcome>_[F]

    • Content: <1–4 lines, goal + what will be built>

  2. MV02_[A]

    • Content:
      • Context:
      • Analogy Start: ""
      • Explanation:
      • Animation Style: <2D/3D, elements, vibe>
      • Process:

  3. MV03_[S]

    • Content: <files/components shown + what is implemented>

  4. MV04<Validation + Metrics>_[S]

    • Content: <how to test + what plots/logs prove success>

Part B: Real System / Hardware (continue numbering)

  1. MV05<Real Bringup & Calibration>_[S]

    • Content: <setup steps + checks + safety>

  2. MV06<Real Test + Failure Debug>_[S]

    • Content: <common failures + how to diagnose>

Assignments & Practice Tasks

Each assignment must specify a measurable submission (plot/log/bag/video/PR).

  1. MA01

    • Goal:
    • Steps:
    • Submission:
    • Pass Criteria: <threshold/expected behavior>

  2. MA02

    • ...

  3. MA03

    • ...

  4. MA04

    • ...

Final Summary

  • <3–6 bullets: what learner can now do>

3) Universal “Robotics Curriculum Types” Mapping

Agents must categorize each module as one (or more) of:

  • Foundations: frames, units, timing, tooling, debugging mindset
  • Modeling: URDF, kinematics, dynamics, sensors as models
  • Control: PID/MPC basics, stability, tuning, constraints
  • Perception: camera/lidar pipelines, filtering, detection, tracking
  • Mapping/SLAM: occupancy, point clouds, loop closure concepts
  • Planning: global/local planning, trajectory generation, cost functions
  • Autonomy Execution: FSM/BT, mission logic, recovery behaviors
  • Robot Learning (RL/IL): rewards, observations/actions, training loop, eval
  • Embedded/Hardware Interface: MCU comms, drivers, latency, safety
  • System Integration: ROS2 graph, QoS, performance, logging, bagging

This mapping helps you split the founder lecture into modules correctly.

4) Consistency Checklist (Must Answer in Every Module)

Every module must explicitly state:

  • What stays the same in sim vs real (interfaces, messages, math, logic)
  • What changes in real (noise, drift, latency, calibration, safety)
  • Minimum validation required (test + metric)
  • Failure modes + debugging checks (at least 3)

5) Assignment Quality Bar

Each module must include 3–5 assignments spanning:

  • Simulation: implement + verify
  • Configuration: parameters/QoS/frames/tuning
  • Debugging: injected error or broken setup to fix
  • Optional: comparison (A/B) to build engineering judgment

6) Recommended Folder Layout (Conceptual)

learning-paths/ / Module 1 _ <...>.md Module 2 _ <...>.md ...

Do not assume hidden context. Each module must stand alone.

7) Pitfalls to Avoid

  • Vague goals like “understand concept”
  • Long unstructured paragraphs
  • Video list without clear “what will be shown/built”
  • No measurable criteria (no plots/logs/bags/videos)
  • Skipping CPA
  • Skipping real-system consideration (even if optional)

8) Definition of Done (DoD)

A module .md is complete when it has:

  • correct headings/order
  • sim + real track coverage
  • at least:
    • 1 intro [F]
    • 1 animation [A] with full storyboard
    • 2+ validation/debug [S]
  • 3–5 assignments with measurable submissions
  • a clear final summary linking to the next module