devton/agentic-workflow-blueprint/plan-to-blueprint

agentic-workflows-blueprint.workflow.plan-to-blueprint

Goal

Transform a technical plan into an executable project skill blueprint: entry skill, command routing, workflow contracts, manifests, and runbook links.

Scope

• Applies to: converting structured implementation plans into skills/<projectSlug>/ scaffold outputs.
• Does not cover: implementing product features described in the plan.

Triggers

• "Turn this plan into a skill blueprint"
• "Convert plan to executable workflows"
• "Scaffold skills from this technical plan"
• After a Plan-mode session when the user wants persistent, rerunnable agent contracts

Inputs

• projectSlug: short identifier for the target repo
• skillName (optional): slash name for router invocation; defaults to projectSlug
• baseBranch: default integration branch
• techStack: short stack description
• existingRootDoc: root instruction file path (AGENTS.md, CLAUDE.md, etc.)
• technicalPlan: structured plan (milestones, tasks, acceptance criteria, constraints)
• workflowsWanted: workflow ids inferred from the plan (must include at least one)
• constraints: project hard rules extracted from the plan
• operationalContext (optional): environment tiers, maintenance window, rollback strategy, compliance boundaries

Invariants

• SKILL.md remains the source of truth; template.json mirrors routing, never replaces contracts.
• Router-only command model: /<skillName> <cmd> maps to workflows/<cmd>/SKILL.md.
• Every workflow in workflowsWanted gets a full contract (Goal through References).
• Do not invent scope not present in technicalPlan; mark gaps explicitly in handoff notes.
• Workflow ids and folder names must match exactly (kebab-case).
• For infra/network/IaC/OS plans, include explicit operational verification and rollback criteria in generated contracts.

Procedure

1. Parse technicalPlan and extract: objectives, milestones, deliverables, constraints, and candidate workflow boundaries.
2. Propose workflowsWanted (confirm or refine with user if ambiguous).

• Include network-engineering, infra-operations, iac, and os-platform when the technical plan includes those domains.

1. Scaffold skills/<projectSlug>/SKILL.md with orchestrator + Command routing (router-only).
2. Generate skills/<projectSlug>/template.json with commands[] for each workflow in workflowsWanted.
3. Create reference/routing-matrix.md and reference/role-contracts.md from plan evidence.
4. For each workflow id, create workflows/<workflowName>/SKILL.md with executable contract sections grounded in the plan.
5. Optionally add workflows/<workflowName>/template.json when a tool needs per-workflow manifests.
6. Wire existingRootDoc with "Start here" and skill/runbook links (no duplication of workflow bodies).
7. Add or update runbook docs/runbooks/plan-to-blueprint.md when operator guidance is needed.
8. Run consistency verification: links, ids, manifest commands, routing-matrix alignment.

Outputs

• skills/<projectSlug>/SKILL.md (entry orchestrator with command routing).
• skills/<projectSlug>/template.json (declarative command manifest).
• skills/<projectSlug>/reference/routing-matrix.md and role-contracts.md.
• skills/<projectSlug>/workflows/<workflowName>/SKILL.md for each item in workflowsWanted.
• Updated existingRootDoc with canonical links.
• Handoff note listing mapped plan sections -> workflows and any unresolved gaps.

Review gate

• [ ] Every command in template.json resolves to an existing workflows/<cmd>/SKILL.md.
• [ ] Entry skill documents router-only invocation (/<skillName> <cmd>).
• [ ] Each workflow contract is complete and traceable to plan evidence.
• [ ] Root doc links only to canonical paths; no duplicated workflow content.
• [ ] All referenced paths exist and ids follow <projectSlug>.workflow.<name>.

References

• ../../SKILL.md
• ../document/SKILL.md
• ../review/SKILL.md