[Spec] Document education-related agentic workflows

[mrjf]

Overview

Create a focused, educator-facing documentation resource — a new EDUCATION-WORKFLOWS.md file at the repository root — that catalogs agentic workflow recipes specifically valuable in educational settings. The document should be practical and hands-on, matching the tone and format already established in this repository's README.md.

Motivation

Educators at the GitHub Educator Summit and beyond need concrete, discipline-specific examples of what agentic workflows can do for their day-to-day teaching. The current README.md provides a solid general introduction to Autoloop, Crane, and Goal, but lacks educator-specific workflow examples. A dedicated, well-structured document lowers the adoption barrier by showing exactly how to apply these tools to real classroom scenarios — auto-grading, feedback generation, progress tracking, and more.

Detailed Design

1. File and Location

Create a new file: EDUCATION-WORKFLOWS.md at the repository root.

Also add a brief "Education Workflow Gallery" section near the bottom of README.md that links to the new document, so summit attendees discover it during the hands-on session.

2. Per-Workflow Entry Template

Each workflow entry in EDUCATION-WORKFLOWS.md should follow a consistent mini-template:

### <Workflow Name>

**Use case**: <One-line description>  
**Tool**: Autoloop / Crane / Goal / Custom gh-aw  
**Trigger**: <GitHub event or schedule>  
**Audience**: K-12 / Higher Ed / Both  

<2–3 sentence description of what the workflow does and why it helps educators.>

**Install**:
```text
<install or create prompt>
```

3. Workflows to Document

The following eight workflow categories should each have a fully written entry:

3.1 Auto-Grading

• Trigger: Student opens a PR on their assignment branch
• Action: Runs the instructor's test suite, posts a grade summary as a PR comment, labels the PR pass or needs-work
• Tool: Goal (tracks the issue until tests pass) or custom gh-aw workflow

3.2 Inline Code Feedback

• Trigger: Student opens a PR
• Action: Reviews code quality, style, and logic; leaves structured inline review comments following a rubric defined in the workflow prompt
• Tool: Custom gh-aw workflow (similar in spirit to the spec-elaborator in this repo)

3.3 Assignment Distribution

• Trigger: Issue labeled assignment is opened by the instructor
• Action: Creates per-student repositories from a template, populates starter code, sets a due-date label, and posts a confirmation comment
• Tool: Custom gh-aw workflow

3.4 Plagiarism / Similarity Flagging

• Trigger: PR opened by a student
• Action: Compares the submission diff to a corpus of known examples and previously submitted work; flags high-similarity PRs for instructor review with a similarity score
• Tool: Custom gh-aw workflow

3.5 Progress Reporting

• Trigger: Scheduled (e.g., every Monday morning)
• Action: Scans all student repos in the classroom org for PR/issue/commit activity; generates a weekly progress report posted as a GitHub Issue in the instructor's dashboard repo
• Tool: Custom gh-aw report workflow

3.6 Curriculum Improvement Loop

• Trigger: Scheduled or manual dispatch
• Action: Autoloop iterates on exercise difficulty, test coverage, or example quality against a measurable evaluation (e.g., percentage of students who pass on first attempt)
• Tool: Autoloop

3.7 Course Material Migration

• Trigger: New semester or major framework/language version bump
• Action: Crane migrates starter code and exercises to the new framework version, verifying correctness via existing tests before committing changes
• Tool: Crane

3.8 Student Q&A Assistant

• Trigger: Student opens an issue with a question (optionally labeled question)
• Action: Agent searches past issues, course documentation, and README files to post a helpful answer; escalates to instructor if confidence is low
• Tool: Goal

4. Document Structure

EDUCATION-WORKFLOWS.md
├── Introduction (2–3 paragraphs)
├── Quick Reference Table (workflow name | tool | trigger | audience)
├── Workflows
│   ├── 3.1 Auto-Grading
│   ├── 3.2 Inline Code Feedback
│   ├── 3.3 Assignment Distribution
│   ├── 3.4 Plagiarism / Similarity Flagging
│   ├── 3.5 Progress Reporting
│   ├── 3.6 Curriculum Improvement Loop
│   ├── 3.7 Course Material Migration
│   └── 3.8 Student Q&A Assistant
└── Further Resources
    ├── Link to gh-aw quickstart
    ├── Link to GitHub Classroom
    └── Link to Discord community

5. README.md Update

Add a section near the bottom of README.md:

## Education Workflow Gallery

Looking for classroom-specific examples? See [EDUCATION-WORKFLOWS.md](./EDUCATION-WORKFLOWS.md) for ready-to-use agentic workflow recipes covering auto-grading, feedback, progress reporting, and more.

API / Interface Changes

No programmatic API changes. This is a documentation deliverable.

If any companion runnable workflow files are created (see Open Questions), they follow the standard gh-aw frontmatter schema already used in .github/workflows/spec-elaborator.md:

---
name: <workflow-name>
description: <short description>
on:
  <trigger>: ...
permissions:
  issues: write
tools:
  github:
    mode: gh-proxy
    toolsets: [default]
safe-outputs:
  add-comment:
---

Data Model Changes

None. No database or schema changes are required for this documentation-only deliverable.

Testing Strategy

Manual Verification

• Walk through the document as an educator persona with no prior GitHub Actions experience — verify clarity and completeness
• Confirm every install/create prompt resolves to a real, working file or URL
• Verify all external links are live (gh-aw quickstart, GitHub Classroom, Discord)
• Confirm the document renders correctly on GitHub (tables, code blocks, collapsible sections)

Peer Review

• Open a PR targeting main; request review from at least one educator stakeholder and one gh-aw practitioner
• Review checklist: consistent template, working prompts, no broken links, appropriate audience level

Automated Link Checking (Optional Enhancement)

A gh-aw workflow (scheduled weekly or triggered on PR) can run a markdown link-checker against EDUCATION-WORKFLOWS.md to catch link rot.

Rollout Plan

Phase	Action	Owner
1 — Draft	Create EDUCATION-WORKFLOWS.md with intro + at least 3 complete workflow entries (Auto-Grading, Feedback, Q&A)	Author
2 — Expand	Add remaining 5 workflow entries	Author
3 — PR Review	Open PR, gather educator + gh-aw feedback	Reviewer
4 — Publish	Merge EDUCATION-WORKFLOWS.md; update README.md link	Author
5 — Live Examples (optional)	Add runnable .github/workflows/*.md files for each entry	Future contributor

No feature flags, migrations, or backwards-compatibility concerns — this is a net-new documentation addition.

Open Questions

1. Single file vs. multi-file: Should each workflow category live in its own file under a docs/education/ directory, or is a single EDUCATION-WORKFLOWS.md sufficient for now?
2. Audience scope: Is the primary audience K-12 teachers, university professors, or both? The complexity, vocabulary, and examples should be calibrated accordingly.
3. GitHub Classroom integration: Should workflows explicitly target GitHub Classroom setups (roster-based, per-student forks), or remain generic enough for any classroom org structure?
4. Runnable examples: Should the repo include actual .github/workflows/*.md files (compiled and runnable) for each documented workflow, or just descriptive prose documentation?
5. Maintenance ownership: Who will keep this document current as gh-aw and the underlying tools (Autoloop, Crane, Goal) evolve?
6. Localization: Is an English-only document sufficient, or should translations be planned for a broader global educator audience?

---

Original Issue

Title: Document a lot of great education-related agentic workflows

have a document somewhere

Generated by 📋 Spec Elaborator for issue #4 · sonnet46 828.4K · ◷