[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)

Start by reading README.md for its tone and the frontmatter example in .github/workflows/spec-elaborator.md for gh-aw conventions. Create EDUCATION-WORKFLOWS.md with the introduction, reference table, eight specified workflow entries, and further resources, then add the Education Workflow Gallery link to README.md. Done means the document renders correctly, follows the requested template, and its prompts and external links are verified.

Scritto dal modello di indicizzazione a partire dal testo della issue.