generating-training

name	generating-training
description	Use when a maintainer asks to generate, build, or create the training package/course/deliverable for the current project ("generate the training", "build the course for this repo", "/training-generator:generate") — runs the full analyze → design → assemble → validate → register workflow.

Generating a Training Package

You are running the training generator against the project in the current working directory (Layer 2, the source project). The output is an independent training repository registered as a submodule (Layer 3). This repository's generator machinery lives at ${CLAUDE_PLUGIN_ROOT}.

Announce the workflow, then execute these phases in order. Stop at the first failure and report it precisely; never work around a refused precondition.

Phase 1 — Discover

1. Confirm the invoking repository root (git rev-parse --show-toplevel) and read its CLAUDE.md / AGENTS.md if present.
2. If training-generator.config.json exists at the root, it configures discovery and placement (schema: ${CLAUDE_PLUGIN_ROOT}/schemas/generator-config.schema.json).
3. Run: node ${CLAUDE_PLUGIN_ROOT}/scripts/discover.mjs <sourceRoot> [--config training-generator.config.json] --out /tmp/knowledge-model.json
4. If sufficientForGeneration is false, stop. Report each blocking gap and what the maintainer must add (typically a Superpowers spec under docs/superpowers/specs/ and plan under docs/superpowers/plans/, or specPath/planPath config entries). Generation must fail safely on thin evidence — do not improvise a course from vibes.

Phase 2 — Analyze

Dispatch the documentation-analyst sub-agent with the knowledge-model path and source root. It reads the spec, plan, instructions, docs, code, and tests; fills conflicts (with an authority ranking: verified implementation and tests establish realized behavior; the spec establishes intent) and refines gaps; and returns the enriched knowledge model plus a project summary. Record any conflict it finds — conflicts must surface in generated instructor notes, never be silently resolved.

Phase 3 — Design the course

Dispatch the curriculum-architect sub-agent with the enriched knowledge model and the full generator config (audience, experience level, duration, required/optional modules, exercise capabilities, sandbox, validation methods, allowed commands — these shape the course). It must produce a content manifest (schema: ${CLAUDE_PLUGIN_ROOT}/schemas/content-manifest.schema.json) containing:

• the curriculum object (schema: schemas/curriculum.schema.json): modules with stable ids (module-NN-slug), lessons, activities, objectives, completion criteria — organized for learning, not document order;
• every content file: lesson Markdown (with > Grounding: provenance lines citing source paths), reference material, exercises (workspace-only, with expected results and validation criteria), demonstrations, and project-specific instructor notes;
• copies of any source assets the course needs (e.g. the tool under reference/), because the training repository must work without the source project.

Write the manifest to a temp file (e.g. /tmp/content-manifest.json).

Phase 4 — Assemble

1. Decide the destination: config submodulePath, default training/.
2. Run: node ${CLAUDE_PLUGIN_ROOT}/scripts/scaffold.mjs --source <sourceRoot> --content /tmp/content-manifest.json --dest <sourceRoot>/<submodulePath> [--config training-generator.config.json] Always pass --config when the project has one — it drives spec/plan correlation, source versioning, prohibited-command enforcement, and instructor-policy overrides.
3. The scaffolder is the only thing that writes the training repository. If it refuses (existing non-training directory, live learner state), report the refusal verbatim and stop.

Phase 5 — Validate

1. node ${CLAUDE_PLUGIN_ROOT}/scripts/validate-package.mjs <dest> — must exit 0.
2. claude plugin validate <dest> --strict — must pass.
3. cd <dest> && node scripts/selftest.mjs — must pass (proves the package validates itself independently).
4. Dispatch the course-reviewer sub-agent for a fresh-context semantic review of the generated package against the source evidence. Fix findings by regenerating the content manifest and re-running Phase 4–5.

Phase 6 — Register the submodule

node ${CLAUDE_PLUGIN_ROOT}/scripts/register-submodule.mjs --source <sourceRoot> [--path <submodulePath>] [--url <remote-url>]

The script enforces the mutation boundary (only .gitmodules + gitlink are committed) and rolls back on failure. If it refuses because of staged changes, tell the maintainer to commit or unstage them — do not do it for them.

Phase 7 — Report

Summarize: what was generated (modules, lessons, exercises), version correlation (package version, source commit, spec/plan identity), validation results, submodule state, and any conflicts or warnings. Then state the publication commands the maintainer may run themselves (creating a remote, git submodule set-url, pushing). Never push, publish, or create remotes yourself — under any circumstances.