← Back to Catalog

workflow-contracts

Use when a task needs a durable handoff artifact for planning, review, or execution in agent-driven workflows — not just a chat summary.

Version: 1.0.0
Maturity: draft
Repository: matt-riley/agent-skills
License: GNU GPL v3

Compatibility:

Agent Skills-compatible coding agents.

SKILL.md

Workflow contracts

Use this skill when a task needs a durable handoff artifact instead of a chat summary, plan note, or loose prose.

Use this skill when

  • You are turning planning or research results into a reusable implementation handoff.
  • A reviewer needs to return an explicit approve|revise|blocked decision.
  • Implementation work needs a compact execution record with validation and blockers.
  • The surrounding workflow needs stable headings and frontmatter instead of ad hoc prose.

Do not use this skill when

  • A one-off chat response is enough and no durable artifact is needed.
  • The main task is inventing a new workflow instead of using the existing v1 contracts.
  • You need a client-specific parser, hook, or enforcement layer rather than a reusable artifact template.

Routing boundary

Situation Use this skill? Route instead
Create or consume a structured plan, review, or execution artifact in this repo Yes -
Create or revise a reusable skill package No skill-authoring
Write global policy that should always apply even when no artifact is produced No global instructions or a scoped instruction file
Produce requirements before creating the contract No to-prd
Break an approved contract into independently trackable tickets No to-issues

Inputs to gather

Required before editing

  • Which phase the artifact serves: planning, review, or implementation.
  • The target artifact path or durable destination.
  • The current goal or task_id.
  • The files, directories, or surfaces that must survive the handoff.
  • The constraints, evidence, or validation commands that the next phase must retain.

Helpful if present

  • The prior research memo, plan, or implementation note being converted.
  • Reviewer names or roles.
  • Existing legacy artifacts that need to be mapped into v1.

Only investigate if encountered

  • Older ad hoc artifact shapes that the current task depends on.
  • Client-specific automation or enforcement expectations outside this repository's current tooling.

First move

  1. Choose the matching v1 template from assets/.
  2. Keep the template's frontmatter keys and stable headings unchanged unless references/contract-spec.md is being revised too.
  3. Fill only the fields supported by concrete evidence, commands, or decisions.

Workflow

  1. Pick the correct template:
    • planner handoff
    • review outcome
    • execution record
  2. Set the required frontmatter fields:
    • contract_type
    • contract_version
    • created_by
    • status
  3. Populate the contract-specific fields from references/contract-spec.md.
  4. During migration, accept legacy prose as input but prefer v1 structured markdown for all new or revised artifacts.
  5. If a legacy artifact must feed the next phase, map it into the v1 headings before handing it off.
  6. Validate the finished artifact with references/checklist.md.
  7. Hand off the artifact with an explicit next action instead of assuming the next agent will infer it from chat history.
  8. If the task would require inventing a new artifact shape or parser, route to skill-authoring instead of stretching this skill.

Outputs

  • A populated v1 contract artifact using one of the templates in assets/:
    • planner handoff
    • review outcome
    • execution record
  • Required frontmatter and headings from references/contract-spec.md.
  • An explicit status plus a concrete next action for the next phase.

Guardrails

  • Must keep the stable field names and required headings from the contract spec.
  • Must make the status explicit instead of burying approval or blockers in prose.
  • Must not invent a third artifact shape during the migration window.
  • Must not stretch this skill into a new parser, framework, or orchestration layer.
  • Must not fill missing fields with wishful prose; if the evidence is not concrete yet, leave the artifact blocked or draft.
  • Should keep artifacts short, phase-specific, and directly usable by the next step in the workflow.

Validation

  • Confirm the artifact uses the correct template and contract_version: v1.

  • Confirm all shared frontmatter keys are present.

  • Confirm the contract-specific headings exist and are populated with concrete content.

  • Confirm any commands, evidence, or blockers are explicit enough that the next phase does not need to reconstruct them from chat history.

  • Confirm the next action is obvious within a few seconds of reading the artifact.

  • Confirm any example artifact in this package uses real-looking filled values instead of placeholder ellipses.

  • Run scripts/validate-contracts.mjs after changing assets/, references/, or contract samples so required frontmatter, status values, and headings stay mechanically checked.

  • Smoke test:

    • should trigger: "Turn this approved plan into a v1 execution handoff with blockers."
    • should not trigger: "Write a PRD for this idea before we create tickets." (→ to-prd)

Examples

  • "Turn this approved plan into a v1 planner handoff with status: ready, task_id, validation commands, and a next action the executor can start immediately."
  • "Rewrite these review notes into a review-outcome contract with status: revise, the comments that were accepted, and the ones intentionally left unresolved."
  • "Record the current implementation wave in an execution record that names the changed files, the checks run, and the remaining blocker."

Reference files