Documentation

Workflow-blueprint scaffolds an agent-oriented documentation system for any repository. It generates a structure of orchestrator skills, executable workflow contracts, reference docs, and visual HTML manuals — all from a single command.

The system is built on one idea: documentation should be something the agent follows, not just reads. Every file is a contract with triggers, inputs, procedures, and review gates. The agent loads what it needs, executes deterministically, and verifies the output.

What gets generated

skills/<project>/
├── SKILL.md                     ← Orchestrator: routes tasks to workflows
├── template.json                ← Manifest: commands, version, entry point
├── reference/
│   ├── routing-matrix.md        ← Task category → workflow mapping
│   ├── role-contracts.md        ← Who does what, boundaries, handoffs
│   └── hook-blueprint.md        ← Optional: CI/automation hooks
├── workflows/
│   ├── document/SKILL.md        ← Contract: document a codebase
│   ├── review/SKILL.md          ← Contract: review a PR
│   └── plan-to-blueprint/SKILL.md  ← Contract: plan → skill
└── README.html                  ← Visual companion to SKILL.md

docs/runbooks/
├── agent-role-system.md         ← How the agent operates in this project
└── plan-to-blueprint.md         ← How to transform plans into skills

Each part below is explained in the order the agent encounters them: from the entry point (SKILL.md) through the manifest (template.json), into the reference layer, and down to individual workflow contracts.

Orchestrator entry

SKILL.md

The orchestrator is the agent's front door. It stays short — under 100 lines — and does three things: classifies the task, selects a workflow, and closes with a validation gate. Everything else lives behind links.

Structure

Description

One-line summary of what the skill does. This is what appears in the agent's skill index — the 60-char window that determines whether the skill gets loaded.

Orchestrator section

Explains how to classify a task (by intent, file type, or keyword), how to select the matching workflow, and how to close — whether there is a validation gate, a review step, or a simple confirmation.

Command routing

The routing table maps each command to its workflow file. Users invoke/{skillName} {cmd}and the orchestrator resolves it to exactly one contract.

Project constraints

Hard rules that apply to every workflow: testing conventions, deployment rules, naming standards, API patterns. Short bullets, never essays.

Example routing table

| User intent              | Workflow                      |
|--------------------------|-------------------------------|
| "Document this feature"  | workflows/document/SKILL.md   |
| "Review my PR"           | workflows/review/SKILL.md     |
| "Turn plan into skill"   | workflows/plan-to-blueprint   |

Invocation: /my-project document
           /my-project review
           /my-project plan-to-blueprint

Declarative manifest

template.json

The manifest is the machine-readable companion to SKILL.md. External tools — CLIs, IDE plugins, CI runners — read it to discover available commands without parsing markdown. It declares the skill name, version, entry point, routing strategy, and the full command list.

template.json structure

{
  "name": "my-project",
  "version": "1.0.0",
  "entry": "SKILL.md",
  "routing": "router-only",
  "commands": [
    {
      "name": "document",
      "description": "Document a codebase feature",
      "skill": "workflows/document/SKILL.md"
    },
    {
      "name": "review",
      "description": "Review a pull request",
      "skill": "workflows/review/SKILL.md"
    }
  ]
}

Sync rules

→Every commands[].name must match an existing folder under workflows/
→Every commands[].skill path must resolve to a real SKILL.md file
→The command list must match the routing table in SKILL.md exactly
→"routing": "router-only" means no flat aliases — every command goes through the orchestrator

Progressive disclosure layer

reference/

The reference folder holds context that the orchestrator links to but does not inline. Each file is self-contained, linkable, and loaded only when the agent needs it. This is what keeps SKILL.md short — details live here.

routing-matrix.md

Maps task categories to workflows. More detailed than the SKILL.md routing table — includes intent triggers, file pattern triggers, and edge cases. Example: a task that touches.test.ts files routes to the review workflow; a task mentioning "deploy" routes to the deployment runbook.

Format: table with columns [Intent / File Pattern → Workflow / Slash Command]

role-contracts.md

Defines who does what. In a multi-agent setup, this file specifies which agent role handles which workflow, where handoffs happen, and what each role is not allowed to do. For a single agent, it documents the agent's operating boundaries.

Format: role definitions + handoff diagram + boundary list

hook-blueprint.md

Optional. An automation checklist for CI/CD integration. Documents which workflow should fire on which git event (push, PR open, tag), and what the hook script should execute. Generated only when the project requests hooks.

Format: event → workflow mapping + hook script templates

Executable contracts

workflows/

Each workflow is a folder containing a SKILL.md contract. The agent reads the contract, identifies whether the triggers match, collects the inputs, executes the procedure step by step, produces the outputs, and checks the review gate. If any section is missing or the gate fails, the workflow fails — no best-effort fallback.

The 8 contract sections

Goal

One sentence. What this workflow does. If it takes two sentences, the scope is too broad — split it.

Scope

Two lists: what the workflow applies to, and what it does not cover. Boundaries prevent scope creep.

Triggers

File patterns (e.g. *.test.ts changed) and intent keywords (e.g. "review this PR"). The agent matches these to decide if the workflow fires.

Inputs

What the workflow needs: base branch, diff scope, required config files, environment variables. If an input is missing, the agent reports it — does not guess.

Invariants

Hard rules that cannot be broken. Project conventions + workflow-specific rules. Example: "never modify lock files" or "always run tests before declaring done".

Procedure

Numbered, deterministic steps. Each step uses evidence (git diff, file reads, test output). No vague instructions like "improve the code" — each step names exactly what to do.

Outputs

What the workflow produces: files, notes, checkpoints, git commits. Verifiable artifacts, not intentions.

Review gate

A checklist with pass/fail criteria. The workflow is not done until every item passes. If any item fails, the agent reports which one and why — it does not retry blindly.

Example: review/SKILL.md (abridged)

## review

### Goal
Review a pull request diff and produce a verdict.

### Scope
Applies to: open PRs with a diff
Does not cover: architecture review (use thermo-nuclear)

### Triggers
- Files: *.ts, *.tsx, *.py changed on a PR branch
- Intent: "review this PR", "code review"

### Inputs
- baseBranch: develop
- diff scope: PR commits only
- required: PR must have a description

### Invariants
- Never modify files outside the diff
- Every finding must cite line numbers
- No stylistic opinions — only correctness + maintainability

### Procedure
1. Read the PR description
2. Run git diff origin/develop...HEAD
3. For each changed file, analyze:
   a. Correctness (logic errors, edge cases)
   b. Security (injection, auth bypass)
   c. Tests (coverage, assertions)
4. Collect findings with severity

### Outputs
- findings.md: numbered list with file:line, severity, description
- verdict: PASS or FAIL

### Review gate
- [ ] Every finding has a file:line citation
- [ ] No finding is a stylistic preference
- [ ] Verdict matches finding severities
- [ ] No file outside diff was touched

Operator playbooks

docs/runbooks/

Runbooks are operator-facing documents — they describe how a human (or a human-in-the-loop) interacts with the agent system. Unlike workflow contracts, which are for the agent, runbooks are for the person supervising or triggering workflows.

agent-role-system.md

How the agent operates in this project: what it can do autonomously, what requires human approval, how to escalate, and what the escalation path looks like. The operator's manual for working alongside the agent.

plan-to-blueprint.md

Step-by-step guide for transforming an implementation plan into a skill contract. Covers when to create a new skill vs. extend an existing one, how to name workflows, and how to verify the generated contract is complete.

agent-role-hooks.md (optional)

Documents CI/CD hook configuration: which events trigger which workflows, how to set up webhook receivers, and how to inspect hook execution logs.

Visual companions

HTML Manuals

Every markdown file in the generated structure has an HTML companion. The agent reads the markdown; the human navigates the HTML. The HTML is self-contained — Tailwind CSS via CDN, dark mode, glassmorphic cards, interactive badges — and opens in any browser without a build step.

HTML companion mapping

SKILL.md              → README.html
workflows/review/
  SKILL.md            → README.html
reference/
  routing-matrix.md   → routing-matrix.html
  role-contracts.md   → role-contracts.html
docs/runbooks/
  agent-role-system.md → agent-role-system.html

HTML manual features

→Self-contained — single file, no dependencies beyond CDN Tailwind
→Dark mode — bg-zinc-950 text-zinc-100 with glassmorphic cards
→Method badges — GET, POST, PUT, DELETE, or workflow step types as colored pills
→Status indicators — done, in-progress, blocked as visual badges
→Code snippets — syntax-highlighted blocks with copy buttons
→Linked — each .md file references its .html under ## References

The HTML is generated by the agent itself during the scaffold. When the markdown is updated, the agent regenerates the HTML. The two never drift — they are produced by the same process.

How invocation works

Command Routing

Routing is router-only. The user invokes a command through the orchestrator skill, and the orchestrator resolves it to exactly one workflow contract. There are no flat aliases — every command goes through the entry point.

Routing flow

User: /my-project review
        │
        ▼
  SKILL.md (orchestrator)
  reads routing table
        │
        ▼
  workflows/review/SKILL.md
  loads the review contract
        │
        ▼
  Agent executes contract
  (Triggers → Inputs → Procedure → Gate)
        │
        ▼
  Output: findings.md + verdict

If the agent does not parse subcommands (some harnesses do not), it reads thecmd from the user message and loads the mapped workflow directly. The routing table in SKILL.md is the fallback mechanism — it is human-readable and agent-readable.

The consistency verification (run after scaffolding) checks that every command in template.json exists as a workflow folder, appears in the routing table, and has a matching SKILL.md. If any link is broken, the scaffold is not complete.

The bundled workflows