SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillsworkflow-blueprint

workflow-blueprint

Agents & models

View repository

Updated 10-15 21:09

About this skill

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, network-engineering, infra-operations, iac, os-platform, 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 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, 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.
  • 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:

{
  "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

  • Special Scaffold Case — embed-aihero-radioactive: When requested, adapt skills/<projectSlug>/workflows/radioactive/SKILL.md to run the 14-phase lifecycle embedding Matt Pocock's skills, and scaffold skills/<projectSlug>/workflows/mattpocock/ containing wayfinder, grilling, domain-modeling, research, prototype, and to-spec. Ensure Phase 1 ALWAYS executes the primary project skill (skills/<projectSlug>/SKILL.md) FIRST for request classification and constraint extraction before executing /wayfinder.

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 link
    • internal workflow skills links
    • 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 (.md).
  • 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 (.md).
  • 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).