41 lines
3.6 KiB
Markdown
41 lines
3.6 KiB
Markdown
---
|
|
status: accepted
|
|
supersedes:
|
|
- 0001-workflow-architecture-24AUG2026.md
|
|
- 0002-workflow-interaction-and-recovery-25AUG2026.md
|
|
- 0002-workflow-standard-agent-overlays-27AUG2026.md
|
|
---
|
|
|
|
# Replace the custom workflow engine with a skill-led workflow
|
|
|
|
> The legacy-runtime retention and pilot-before-retirement prerequisite below are superseded by [ADR 0007](0007-archive-legacy-workflows-05SEP2026.md). The skill-led workflow and its outstanding validation requirements remain in force.
|
|
|
|
## Context
|
|
|
|
The custom `workflow` extension encoded useful approval, isolation, verification, and reviewer-independence policy, but coupled that policy to a large state machine, child runtime, scheduler, persistence layer, and TUI. Recorded runs failed or stalled before implementation when exact planner output, child delivery, recovery state, or liveness mechanics diverged from the engine contract.
|
|
|
|
Pi already provides the useful orchestration primitives: `ask_user`, task tools, direct subagents, artifact presentation, prototypes, browser/application validation, project commands, and Git worktrees. Repository Markdown and commits provide a simpler recovery boundary than a second workflow runtime.
|
|
|
|
## Decision
|
|
|
|
Use the model-invoked [`develop-workflow` skill](../../skills/develop/develop-workflow/SKILL.md) for feature work and other multi-step changes. Keep questions and obvious low-risk edits on lightweight paths. Add no replacement extension.
|
|
|
|
The parent agent owns classification, requirements, the retained workflow record, task state, worktree, assignments, verification, commits, review, and local integration. Preserve categorical human gates for the exact implementation plan, non-trivial UI direction, and just-in-time risk. Require observable evidence rather than exact model-authored transition schemas.
|
|
|
|
Keep one committed Markdown workflow record per active change. Update it atomically at meaningful checkpoints with optimistic SHA-256 concurrency and retain it after completion. Treat Git and the last committed valid record as authoritative recovery evidence.
|
|
|
|
Use bounded subagent assignments with exclusive file ownership and before/after Git evidence. Exclude every mutator identity from independent standards and specification review. Require Git-capable read-only reviewer profiles to regenerate and confirm the pinned binary diff fingerprint. Reviewers report findings but never remediate them.
|
|
|
|
Automate verified commits, rebase, fresh review, clean local fast-forward integration, metadata-only closure, and safe cleanup. Keep destructive actions, force operations, conflict-driven behavior changes, pushes, publishing, deployment, and production access behind explicit approval.
|
|
|
|
Retain `extensions/workflow` and `extensions/_workflows` as private historical reference during the pilot. Keep them unexposed. Archive or remove them only in a separate change after three successful real-work pilots and explicit retirement approval.
|
|
|
|
## Consequences
|
|
|
|
- Workflow gates become procedural and testable, not technically enforced by a custom state machine.
|
|
- Recovery depends on repository evidence and proven child liveness rather than leases or automatic replay.
|
|
- The skill composes existing Pi capabilities and adds no runtime dependency.
|
|
- A Git-capable reviewer profile declares no edit/write tools, while parent before/after Git checks remain necessary because shell access can mutate indirectly.
|
|
- Existing package and imported-snapshot ADRs remain valid except for workflow-extension-specific prerequisites, which this decision supersedes.
|
|
- The twelve scenario evaluations and three real-change pilot remain required before retiring the legacy implementation or closing the replacement TODO.
|