[Spec] Document education-related agentic workflows

## 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:

````markdown
###

**Use case**:
**Tool**: Autoloop / Crane / Goal / Custom gh-aw
**Trigger**:
**Audience**: K-12 / Higher Ed / Both

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

**Install**:
```text

```
````

### 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`:

```markdown
## 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`:

```yaml
---
name:
description:
on:
: ...
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](https://classroom.github.com/) 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](https://github.com/githubnext/next-ed/actions/runs/27225877165) for issue #4 · sonnet46 828.4K · [◷](https://github.com/search?q=repo%3Agithubnext%2Fnext-ed+is%3Aissue+%22gh-aw-workflow-call-id%3A+githubnext%2Fnext-ed%2Fspec-elaborator%22&type=issues)

Commencez par lire README.md pour comprendre son ton, ainsi que l’exemple de frontmatter dans .github/workflows/spec-elaborator.md pour les conventions de gh-aw. Créez EDUCATION-WORKFLOWS.md avec l’introduction, le tableau de référence, les huit entrées de workflow spécifiées et les ressources supplémentaires, puis ajoutez le lien Education Workflow Gallery à README.md. La tâche est terminée lorsque le document se rend correctement, respecte le modèle demandé et que ses prompts et ses liens externes sont vérifiés.

Rédigé par le modèle d'indexation à partir du texte de l'issue.