# Workflow Blueprint > Blueprint workflow to scaffold agent-oriented documentation with progressive disclosure and executable contracts. - Skill: `devton/workflow-blueprint` (Agent Skill, multi-file: 4 files) - Install (CLI): `npx skillmds@latest add devton/workflow-blueprint` - Raw SKILL.md: https://api.skillmd.com/api/skills/devton/workflow-blueprint/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: AI & ML - Author: devton (https://skillmd.com/u/devton) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/devton/workflow-blueprint --- ## agentic-workflows.blueprint ### Goal Provide a reusable blueprint workflow that scaffolds an "agentic workflows" documentation structure for any codebase, with progressive disclosure, executable contracts (workflows), and self-contained interactive visual HTML manuals (`README.html` / `.html`). ### Scope - Applies to: any repository that wants an agent-oriented documentation system (orchestrator + workflow skills + references + runbooks + visual HTML manuals). - 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" - "Generate HTML manuals for skills and runbooks" ### 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`, `network-engineering`, `infra-operations`, `iac`, `os-platform`, `html-manual`, `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 with matching HTML visual manuals: ``` skills// SKILL.md README.html ← Interactive visual HTML manual for project skill template.json ← Declarative manifest (commands, entry) reference/ routing-matrix.md routing-matrix.html ← Visual HTML version matching base filename role-contracts.md role-contracts.html ← Visual HTML version matching base filename hook-blueprint.md (optional) hook-blueprint.html (optional) workflows/ / SKILL.md README.html ← Interactive visual HTML manual for workflow template.json (optional) ← Per-workflow manifest when useful docs/runbooks/ agent-role-system.md agent-role-system.html ← Visual HTML version matching runbook filename agent-role-hooks.md (optional) agent-role-hooks.html (optional) plan-to-blueprint.md (when workflow included) plan-to-blueprint.html (when workflow included) ``` And updates the root doc (`AGENTS.md` or equivalent) to link to the new entrypoints. This blueprint folder carries bundled workflows (`embed-aihero-radioactive`, `mattpocock/wayfinder`, `mattpocock/grilling`, `mattpocock/domain-modeling`, `mattpocock/research`, `mattpocock/prototype`, `mattpocock/to-spec`, `radioactive`, `brainstorming`, `plan-writing`, `ui-ux-pro-max`, `remotion-video-motion`, `thermo-nuclear-code-quality-review`, `thermo-fix`, `html-manual`, `changelog-generator`, `document`, `review`, `changelog`, `linear`, `mcp-linear-planner`, `mcp-linear-sync`, `network-engineering`, `infra-operations`, `iac`, `os-platform`, `implementing-devsecops-security-scanning`, `scanning-containers-with-trivy-in-cicd`, `scanning-docker-images-with-trivy`, `scanning-kubernetes-manifests-with-kubesec`, `implementing-network-policies-for-kubernetes`, `implementing-rbac-hardening-for-kubernetes`, `implementing-pod-security-admission-controller`, `securing-aws-iam-permissions`, `securing-container-registry-images`, `securing-kubernetes-on-cloud`, `triaging-vulnerabilities-with-ssvc-framework`, `performing-kubernetes-cis-benchmark-with-kube-bench`, `analyzing-kubernetes-audit-logs`, `securing-github-actions-workflows`, `performing-container-image-hardening`, `remediating-s3-bucket-misconfiguration`, `performing-container-security-scanning-with-trivy`, `performing-vulnerability-scanning-with-nessus`, `implementing-syslog-centralization-with-rsyslog`, `c4-architecture`, `plan-to-blueprint`) to demonstrate full-lifecycle chained execution, Matt Pocock / AI Hero methodology embedding, plan-to-skill transformation, visual documentation generation, MCP integration patterns, and infrastructure operations coverage. 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`. - Visual HTML Manuals (Default Behavior): Every skill, workflow contract, reference doc (`.md`), and runbook (`.md`) MUST have a corresponding self-contained interactive visual HTML document (`README.html` for skills/workflows, `.html` matching base name for references/runbooks) formatted with Tailwind CSS CDN, dark mode (`bg-zinc-950 text-zinc-100`), glassmorphic styling, and method/status badges. The source `.md` file MUST link to its `.html` companion under `## 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 `/ `; the entry skill resolves `cmd` to `workflows//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//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: `/ ` (e.g. `/my-backend document`) - map each `cmd` in `workflowsWanted` to `workflows//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//SKILL.md` links - Project constraints and hard rules (short bullets). Create `skills//template.json` as the declarative manifest: ```json { "name": "", "version": "1.0.0", "entry": "SKILL.md", "routing": "router-only", "commands": [ { "name": "", "description": "Short trigger description", "skill": "workflows//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//reference/`, create: - `routing-matrix.md`: task category -> workflow mapping; include slash form `/ ` 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//workflows//SKILL.md` with: - `id`: `".workflow."` (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//SKILL.md` and any deep dives - **Special Scaffold Case — `embed-aihero-radioactive`**: When requested, adapt `skills//workflows/radioactive/SKILL.md` to run the 14-phase lifecycle embedding Matt Pocock's skills, and scaffold `skills//workflows/mattpocock/` containing `wayfinder`, `grilling`, `domain-modeling`, `research`, `prototype`, and `to-spec`. Ensure Phase 1 ALWAYS executes the primary project skill (`skills//SKILL.md`) FIRST for request classification and constraint extraction before executing `/wayfinder`. Optionally, for each workflow, add `workflows//template.json` when an external tool needs a standalone command descriptor; keep it minimal (`name`, `entry`, `parent`). #### 4) Generate Visual HTML Manuals (Default Requirement) For every generated or updated markdown file: - **Skills & Workflows:** Generate `README.html` inside the skill/workflow folder (`skills//README.html` and `skills//workflows//README.html`). - **References:** Generate `.html` in `skills//reference/` matching the markdown filename (e.g. `routing-matrix.md` ➔ `routing-matrix.html`, `role-contracts.md` ➔ `role-contracts.html`). - **Runbooks:** Generate `.html` in `docs/runbooks/` matching the markdown filename (e.g. `agent-role-system.md` ➔ `agent-role-system.html`). - Format each HTML file as a single, self-contained visual manual using Tailwind CSS via CDN (``), dark mode (`bg-zinc-950 text-zinc-100`), glassmorphic cards (`background: rgba(24, 24, 27, 0.65); backdrop-filter: blur(12px)`), method/status badges, and code snippets. - Update each source `.md` file to include a reference link to its `.html` companion under `## References` (e.g. `[Interactive HTML View](./README.html)` or `[Visual HTML Version](./routing-matrix.html)`). #### 5) Wire everything into the root doc Update `existingRootDoc` to include: - "Start here": link to `skills//SKILL.md` and `skills//README.html` - Under "Skills" (or similar), list: - the project skill & visual manual link - internal workflow skills & visual manual links - runbook links & visual manual links Do not duplicate workflow contents in the root doc. #### 6) 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//workflows/...`" - Leave the rest as a deep dive reference #### 7) Consistency verification (required) Before declaring the scaffold done: - Verify every link path exists (`.md` and `.html`). - 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). - Verify every `.md` file has a matching `.html` visual manual companion. ### 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"). - Self-contained interactive HTML visual manuals (`README.html` for skills/workflows, `.html` for references/runbooks) are generated for all files. - Every source `.md` file links to its `.html` companion under `## References`. - No duplication between root, project skill, and workflows. - All links resolve (`.md` and `.html`). - `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, network policies, IaC standards, and OS baselines), keep them in the project skill and link them from workflows. - Installable skill contract with frontmatter: see `SKILL.md` (`name: workflow-blueprint`). ### References - [Interactive HTML View](./README.html)