Add WORKFLOW.md target-repo policy

[VincentShipsIt]

---

name: workflow-md-policy-file
description: Repo-owned WORKFLOW.md drives pipeline runtime config and prompts.
status: backlog
estimated_complexity: medium
blast_radius: cross-package

PRD: workflow-md-policy-file

Executive Summary

Adopt OpenAI Symphony's WORKFLOW.md pattern. Target repos commit .shipcode/WORKFLOW.md containing YAML front matter (concurrency, timeouts, hooks, retries) plus Markdown body (per-phase prompts). Pipeline loads at start. Missing file falls back to today's hardcoded prompts. Lets each repo version its own pipeline policy without forking shipcode.

Problem Statement

All pipeline prompts and runtime knobs are hardcoded in `packages/pipeline/src/pipeline.ts:148` and adjacent constants. A target-repo team that wants different plan-phase guidance, longer timeouts, or per-state concurrency caps must fork shipcode. No way to honor team- or repo-specific policy.

Goals

• Pipeline reads `.shipcode/WORKFLOW.md` (preferred) or `WORKFLOW.md` from target repo at start of each run.
• Front matter values override defaults.
• Prompt body replaces hardcoded plan/review/execute/verify templates when present.
• Falls back cleanly to today's behavior when file is absent.

Non-Goals

• Live hot-reload (Hot-reload WORKFLOW.md changes #71).
• Hook execution (Add workspace lifecycle hooks #66).
• Per-state concurrency runtime (Add per-state concurrency caps #72) — this PRD only adds the config surface.
• Strict template engine (Use strict template for prompts #77).

User Stories

• As a target-repo maintainer who wants longer verify timeouts and a custom planner prompt, I want to commit a WORKFLOW.md to my repo so the next pipeline picks up my settings without changes to shipcode.
  Acceptance:
  • Committing WORKFLOW.md with `agent.max_concurrent_agents: 2` causes the dispatcher to honor 2 instead of default.
  • Replacing the plan-phase prompt body changes the planner's prompt verbatim on the next run.
  • Removing the file restores default behavior on the next run.

Functional Requirements

1. Loader resolves path: prefer `/.shipcode/WORKFLOW.md`, fall back to `/WORKFLOW.md`.
2. Loader parses YAML front matter into typed config; missing file or absent front matter yields all defaults.
3. Markdown body becomes prompt template; empty/absent uses today's hardcoded prompts.
4. Loader emits structured errors for: file unreadable, YAML parse failure, front matter not a map.
5. Pipeline calls loader at start of each run and passes config to phase handlers.

Non-Functional Requirements

• Loader runs in <50ms on typical (<10KB) WORKFLOW.md.
• Loader failures must not crash pipeline; fall back to defaults and surface a structured warning to renderer.

Success Criteria

• Loader unit tests pass for: missing file, valid file, invalid YAML, non-map front matter.
• Integration test shows a target repo's WORKFLOW.md changing dispatcher's effective concurrency cap.
• Target repo without WORKFLOW.md runs pipeline with same observable behavior as today.
• Existing `pipeline.test.ts` and `pipeline.github-issue.smoke.test.ts` continue to pass unchanged.

Out of Scope

• File watcher / hot-reload.
• Hook script execution.
• HTTP dashboard reads.
• Migrating today's prompts into a default WORKFLOW.md.

Dependencies

• YAML parser (`js-yaml` or equivalent).
• `packages/pipeline/src/pipeline.ts` call site.
• Symphony spec: https://github.com/openai/symphony/blob/main/SPEC.md#5-workflow-specification-repository-contract

Verification Plan

• tests: new `packages/pipeline/src/workflow-loader.test.ts` covering parse cases; updates to `pipeline.test.ts` for loader integration.
• manual: create sample `.shipcode/WORKFLOW.md` in test repo with `agent.max_concurrent_agents: 1`; run two pipelines; confirm only one at a time.

Risks & Open Questions

• Schema-scope creep — keep this PRD's loader to minimum keys; consumer tickets own their own keys.
• Resolving target-repo path inside a worktree (which may not have file checked out yet).
• YAML parser dependency bundle-size impact for desktop app.