Workflow files: feature-development.yaml and friends

Where workflow files live

Workflow files are YAML files in docs/instructions/workflows/ in your project. YAML is a plain-text format for settings, written as indented key: value lines. Two file names are reserved and have a fixed meaning:

• feature-development.yaml: how each stage of a code change behaves in this project. Onboarding writes it for coding projects.
• delivery-policy.yaml: your shipping conventions (ticket system, branch names, commit and pull request templates, CI rules). It is optional; framework defaults apply when it is absent.

The folder may also hold custom workflow templates, which are covered at the end of this page. The AI loads the workflow files at the start of every routed message, alongside your stack and design-system documents.

What feature-development.yaml controls

The file tunes the built-in stages. It does not define them: paqad owns the routing, the stage order and which stages are mandatory. The top level has three keys.

Key	Meaning
schema_version	Always "1".
merge_mode	Always append: your entries are added to the framework defaults.
stages	One block per stage: ticket_intake, planning, specification, development, review, checks, documentation_sync, delivery.

Each stage block can contain these fields.

Field	What it does
read	Files or globs the AI reads before the stage, for example docs/modules/**.
instructions	Extra instructions for the stage, in plain sentences.
required_inputs	What the stage needs before it starts.
strictness	On or off switches such as require_spec or block_on_failure.
escalation	How to react to a named situation: warn, ask or stop.
artifacts	What the stage is expected to produce.
checks	Checks stage only: which project commands to run (see below).
rule_compliance	Checks stage only: how your rule scripts run (enabled, mode of off, warn or strict, scope of changed-files or whole-tree, diff_scope, cache_path, escalation).

The checks block names logical commands (format, test, build) that are looked up in your project profile, plus any literal shell_commands. paqad-ai checks run executes them and exits with an error on any failure.

An example customisation

This adds a reading list to planning and a type-check command to the checks stage. Everything else keeps the framework defaults.

schema_version: "1"
merge_mode: append

stages:
  planning:
    read:
      - docs/architecture/**
    instructions:
      - Prefer extending the existing billing services over adding new ones.
  checks:
    checks:
      shell_commands:
        - pnpm typecheck

How your edits are merged with the defaults

• Lists (read, instructions, required_inputs, artifacts, check commands) are appended to the defaults, with duplicates removed.
• escalation entries you set replace the default for that key.
• strictness can only get stricter. A switch that is on by default stays on. Five switches are always forced on: require_spec and require_spec_signoff (specification), require_review (review), block_on_failure (checks) and require_canonical_sync (documentation sync).
• If the file cannot be parsed, or fails schema validation, paqad ignores it, uses the framework defaults and reports a warning.

Which settings a script enforces and which rely on the AI

The generated file says this in its own header comments, and it is worth knowing before you rely on a setting.

• Script-enforced: checks.block_on_failure (a red command fails the change; a code change with no checks report ends as Inconclusive) and the rule that every mandatory stage must have run.
• Raised by the AI, then held by a script: review.escalation.review_findings and documentation_sync.escalation.stale_docs. No script can judge whether a review finding is blocking or a document is stale, so the AI must raise it. Once it raises it as a stop, it becomes a decision pause, and on hook-capable tools code edits stay blocked until you resolve it.

delivery-policy.yaml in brief

This file sits under a process key with sections for ticket, host, branch, commit, pr, ci and intake_decisions. Each section carries maintained: auto (paqad may fill it from detection) or maintained: manual (yours; detection never touches it). It uses the same merge_mode: append rule.

Custom workflow templates (advanced)

Any other .yaml or .yml file in the folder is treated as a custom workflow template: a named list of skill steps.

name: feature-with-review
description: Review-heavy variant for payment work
steps:
  - skill: scope-check
  - skill: spec-diff
    condition: { complexity: [medium, high] }
  - parallel:
      - skill: adversarial-review
      - skill: performance-regression-estimator
    on_failure: skip
  - skill: diff-doc-sync

• A template needs a name and at least one step, and every skill must be a known skill name.
• condition runs a step only when the request's classification matches (for example complexity, risk or workflow).
• on_failure is abort (the default: stop the run), skip (record it and continue) or retry (try once more).
• Progress is saved to .paqad/workflows/<name>/runs/<run-id>/progress.json, so a run can resume from its first unfinished step.