workflow-blueprint

---
name: workflow-blueprint
description: Blueprint workflow to scaffold agent-oriented documentation with progressive disclosure and executable contracts.
---

## agentic-workflows.blueprint

### Goal

Provide a reusable blueprint workflow that scaffolds an "agentic workflows" documentation structure for any codebase, with progressive disclosure and executable contracts (workflows).

### Scope

- Applies to: any repository that wants an agent-oriented documentation system (orchestrator + workflow skills + references + runbooks).
- Does not cover: implementing product features; this is scaffolding/documentation only.

### Triggers

- "Create agentic workflow structure"
- "Set up skills folder + workflows"
- "Make docs agent-friendly"
- "Refactor AGENTS.md into linked skills"

### Inputs

- `projectSlug`: short identifier for the repo (e.g. `my-backend`)
- `baseBranch`: default integration branch (e.g. `develop`, `main`)
- `techStack`: short list (e.g. `NestJS + MikroORM + Graphile Worker`)
- `existingRootDoc`: root instruction file path (`AGENTS.md`, `CLAUDE.md`, etc.)
- `workflowsWanted`: list of workflow ids to scaffold (e.g. `modules`, `specs`, `document`, `plan-to-blueprint`)
- `constraints`: project hard rules (e.g. "no emojis", "mock external boundaries only")
- `skillName` (optional): slash-invocation name for the project entry skill; defaults to `projectSlug` (lowercase, hyphens only)

### Outputs

Creates a minimal, navigable structure:

```
skills/<projectSlug>/
  SKILL.md
  template.json                     ← Declarative manifest (commands, entry)
  reference/
    routing-matrix.md
    role-contracts.md
    hook-blueprint.md (optional)
  workflows/
    <workflowName>/
      SKILL.md
      template.json (optional)      ← Per-workflow manifest when useful
docs/runbooks/
  agent-role-system.md
  agent-role-hooks.md (optional)
  plan-to-blueprint.md (when workflow included)
```

And updates the root doc (`AGENTS.md` or equivalent) to link to the new entrypoints.

This blueprint folder can also carry example workflows (`document`, `review`,
`changelog`, `linear`, `plan-to-blueprint`) to demonstrate chained execution,
plan-to-skill transformation, and MCP integration patterns. Optional
decomposition workflows (such as `mcp-linear-planner` and `mcp-linear-sync`)
can be added when needed.

It can also carry runbook examples under `runbooks/` to show operator-facing
execution playbooks for those workflows.

### Invariants (guardrails)

- Progressive disclosure: root doc stays short; details live behind links.
- Executable contracts: every workflow is written as a contract the agent can follow:
  - `Goal`, `Scope`, `Triggers`, `Inputs`, `Invariants`, `Procedure`, `Outputs`, `Review gate`, `References`.
- No duplication: do not copy/paste long rules across files; link to the source of truth.
- Consistency: workflow ids and file paths must match exactly across all references.
- Minimal surface: only add the workflows actually requested.
- Source of truth: `SKILL.md` is authoritative; `template.json` is a complementary declarative layer for agents/tools that expose command interfaces.
- Command routing: router-only — users invoke `/<skillName> <cmd>`; the entry skill resolves `cmd` to `workflows/<cmd>/SKILL.md` and loads only that contract.
- Manifest sync: every command in `template.json` must map to an existing workflow folder and match `routing-matrix.md`.

### Procedure

#### 1) Create the project entry skill

Create `skills/<projectSlug>/SKILL.md` as the global entrypoint:

- A short description of what the skill is for.
- An "orchestrator" section that explains:
  - how to classify a task
  - how to select one workflow
  - how to close (validation gate if applicable)
- A **Command routing** section (router-only):
  - invocation pattern: `/<skillName> <cmd>` (e.g. `/my-backend document`)
  - map each `cmd` in `workflowsWanted` to `workflows/<cmd>/SKILL.md`
  - if the agent does not parse subcommands, read `cmd` from the user message and load the mapped workflow contract
  - do not create flat alias skills unless explicitly requested
- A list of internal workflow helpers:
  - `workflows/<name>/SKILL.md` links
- Project constraints and hard rules (short bullets).

Create `skills/<projectSlug>/template.json` as the declarative manifest:

```json
{
  "name": "<skillName>",
  "version": "1.0.0",
  "entry": "SKILL.md",
  "routing": "router-only",
  "commands": [
    {
      "name": "<workflowName>",
      "description": "Short trigger description",
      "skill": "workflows/<workflowName>/SKILL.md"
    }
  ]
}
```

- Include one `commands[]` entry per item in `workflowsWanted`.
- Keep `name` aligned with `skillName` (folder may remain `projectSlug`).

#### 2) Create references (progressive disclosure)

In `skills/<projectSlug>/reference/`, create:

- `routing-matrix.md`: task category -> workflow mapping; include slash form `/<skillName> <cmd>` alongside intent triggers.
- `role-contracts.md`: roles, boundaries, handoffs.
- Optional `hook-blueprint.md`: opt-in automation checklist.

Keep each file self-contained and linkable.

#### 3) Scaffold each workflow as an executable contract

For each workflow in `workflowsWanted`, create:

`skills/<projectSlug>/workflows/<workflowName>/SKILL.md` with:

- `id`: `"<projectSlug>.workflow.<workflowName>"` (as the first header line)
- `Goal`: 1 sentence
- `Scope`: applies/does not cover
- `Triggers`: file triggers + intent triggers
- `Inputs`: baseBranch, diff scope, required config
- `Invariants`: the project's hard rules + workflow-specific rules
- `Procedure`: deterministic steps (evidence-driven; use git diff when documenting)
- `Outputs`: what files/notes/checkpoints must be produced
- `Review gate`: checklist with pass/fail criteria
- `References`: links back to `skills/<projectSlug>/SKILL.md` and any deep dives

Optionally, for each workflow, add `workflows/<workflowName>/template.json` when an external tool needs a standalone command descriptor; keep it minimal (`name`, `entry`, `parent`).

#### 4) Wire everything into the root doc

Update `existingRootDoc` to include:

- "Start here": link to `skills/<projectSlug>/SKILL.md`
- Under "Skills" (or similar), list:
  - the project skill
  - internal workflow skills (links to the new workflow SKILL.md files)
  - runbook links

Do not duplicate workflow contents in the root doc.

#### 5) Optional: deprecate legacy skill locations (wrapper)

If there are existing skills in other directories:

- Keep the file
- Add a top banner:
  - "Moved: canonical workflow is at `skills/<projectSlug>/workflows/...`"
- Leave the rest as a deep dive reference

#### 6) Consistency verification (required)

Before declaring the scaffold done:

- Verify every link path exists.
- Verify workflow ids are consistent:
  - `projectSlug.workflow.*` matches the file it lives in.
- Verify root doc points only to canonical locations.
- Verify `template.json` `commands[].name` values exist under `workflows/` and appear in Command routing + `routing-matrix.md`.
- Verify router-only behavior is documented in the project entry `SKILL.md` (no undocumented flat aliases).

### Review gate (must pass)

- Root doc remains minimal and only links out.
- Each workflow has the full contract sections (Goal..References).
- Constraints are explicit and testable (no vague "best practices").
- No duplication between root, project skill, and workflows.
- All links resolve.
- `template.json` is valid JSON and consistent with `workflowsWanted`.
- Command routing resolves every listed subcommand to exactly one workflow contract.

### Notes

- This blueprint is intentionally stack-agnostic. For stack-specific rules (logging, ORM patterns, testing rules), keep them in the project skill and link them from workflows.