pal-e-docs

Plan: Sprint Workflow Automation (DORA Instrumentation)

plan-2026-03-03-sprint-workflow-automation Plan

plan completed
Project

Vision

Sprint workflow automation is the DORA instrumentation layer for the pal-e platform. Without it, DORA metrics are manual estimates with "Low" confidence. With it, every agent action — setting a label, submitting a PR, passing QA — generates structured data that flows directly into DORA measurement.
Agent Action Data Generated DORA Metric Fed
Dev sets <code>status:in-progress</code> label Timestamp: work started Lead Time (start)
Dev submits PR, sets <code>status:qa</code> Timestamp: code complete + PR URL Lead Time (code complete), Deployment Frequency
QA sets <code>status:approved</code> Timestamp: review passed Lead Time (review complete), Change Failure Rate
QA sets <code>status:needs-fix</code> Rework iteration count Change Failure Rate (Agent CFR / Rework Rate)
Betty Sue moves item to Done Timestamp: shipped Lead Time (end), Plan-to-Ship Time
Betty Sue links PR to sprint item Deployment count per sprint Deployment Frequency per sprint
This plan implements the full agent-to-board loop: agents signal status via Forgejo labels, Betty Sue reads labels and syncs sprint boards, sprint boards accumulate the data that makes DORA real. The sprint system doesn't just organize work — it proves the platform thesis.

Projects & Repos Touched

Project/Repo Platform Role in this plan
All 29 Forgejo repos Forgejo Standard labels created via API (Phase 1 — DONE)
<code>forgejo_admin/claude-custom</code> Forgejo Hooks, skills, agent profiles (Phases 3-4 — DONE, Phase 5 pending)
pal-e-docs (notes) Forgejo SOP updates + skill notes (Phase 2 — DONE)

Context

Sprint 1 exists with 18 plans, 18 phases, and 10 issues across boards — but the sprint is still in "planning" status with no execution engine. The DORA baseline (2026-03-01) showed "Low-Medium" overall confidence. Agent DORA metrics (PRs/day, rework rate, plan-to-ship time, autonomy ratio) are entirely qualitative estimates marked "Low" confidence.
The todo-sprint-workflow-automation note captured the design decisions and work areas during the 2026-03-02 session. This plan promoted that TODO to a proper phased plan.
What's already done:
  • Sprint tables + API deployed (Phase 1 of pal-e-sprints backend)
  • Sprint MCP tools deployed (PR #9 merged on pal-e-docs-mcp)
  • Sprint 1 created with all 5 boards populated
  • Phases 1-4 of this plan DONE (see below)
  • Post-merge documentation SOP + /update-docs skill added (supplementary work)

Previous Plan

plan-2026-03-01-pal-e-sprints — the backend plan that delivered sprint tables, API, and MCP tools. This plan builds the agent behavior layer on top of that infrastructure.

Depends On

  • plan-2026-03-01-pal-e-sprints Phase 1 (tables + API + MCP tools) — COMPLETED
  • Schema expansion (PR #67) — nice-to-have for repo/project boards, but NOT blocking.

Decisions Made

Decision Rationale
Forgejo labels as status signals Agents already interact with Forgejo. Labels are the lightest-weight signal mechanism.
Hooks as enforcement, not prompts PostToolUse hooks fire automatically — agents can't forget to set labels. Hooks use curl via forgejo-helper.sh. No new MCP tools needed.
Three enforcement layers: hooks &gt; skills &gt; prompts Hooks enforce (can't skip), skills structure (recipe to follow), prompts inform (awareness only). Each layer serves a different purpose.
Agents comment on PRs, hooks mirror to issues QA has no Bash or comment_on_issue MCP tool. Hook on comment_on_pr parses verdict and mirrors to issue. TODO created for forgejo-mcp to add proper tools.
Betty Sue syncs boards, agents don't touch pal-e-docs Separation of concerns preserved. Agents own repos. Betty Sue owns docs.
SOPs before implementation Document the workflow before coding the workflow. Betty Sue's rule.
Labels first, orchestration last Foundation before automation. Each phase is independently valuable.
Post-merge docs as gate before "done" Merged ≠ done. Docs must be current before sprint item moves to done. Formalized as sop-post-merge-docs + /update-docs skill.

Phases

See child phase notes: list_notes(parent_slug="plan-2026-03-03-sprint-workflow-automation")
Five phases, each independently deployable:
  • Forgejo Labels — DONE. 7 labels across 29 repos. (PR: API calls)
  • SOP Updates — DONE. agent-workflow, pr-lifecycle, template-sprint-item.
  • Agent Label Behavior — DONE. 3 PostToolUse hooks (label-on-branch, label-on-pr, label-on-verdict) + forgejo-helper.sh extensions + dev.md/qa.md awareness + skill-review-pr VERDICT format. (PR #52 on claude-custom)
  • Betty Sue Sprint Skill — DONE. 4 main-session skills (/sprint-sync, /sprint-status, /sprint-add, /sprint-kickoff) + post-merge sprint reminder hook + 4 skill notes in pal-e-docs. (PR #54 on claude-custom)
  • Orchestration Automation — NOT STARTED. Auto-QA trigger on PR submission. Auto-board sync on merge. Closes the loop for minimal human intervention.
Supplementary: Post-merge documentation gate — sop-post-merge-docs + skill-update-docs + /update-docs SKILL.md + remind-update-docs.sh hook update. (PR #56 on claude-custom)

Key Files

Phase File Repo/Location Change
1 N/A (API calls) Forgejo DONE — labels created
2 agent-workflow, pr-lifecycle, template-sprint-item pal-e-docs DONE — SOPs updated
3 <code>hooks/forgejo-helper.sh</code> claude-custom DONE — forgejo_set_label, forgejo_comment_on_issue, forgejo_get_issue_number_from_branch
3 <code>hooks/label-on-branch.sh</code> claude-custom DONE — PostToolUse: set status:in-progress
3 <code>hooks/label-on-pr.sh</code> claude-custom DONE — PostToolUse: set status:qa + comment PR URL
3 <code>hooks/label-on-verdict.sh</code> claude-custom DONE — PostToolUse: parse verdict, set status label
3 <code>settings.json</code>, <code>agents/dev.md</code>, <code>agents/qa.md</code> claude-custom DONE — hook registration + awareness
3 <code>skill-review-pr</code> note pal-e-docs DONE — exact VERDICT format required
4 <code>skills/sprint-*/SKILL.md</code> claude-custom DONE — 4 sprint management skills
4 <code>hooks/remind-sprint-update.sh</code> claude-custom DONE — post-merge sprint reminder
— <code>skills/update-docs/SKILL.md</code>, <code>hooks/remind-update-docs.sh</code> claude-custom DONE — post-merge docs gate
5 Existing hooks claude-custom PENDING — auto-QA trigger + auto-board sync

Verification

  • Phase 1: DONE — labels visible on all 29 repos
  • Phase 2: DONE — SOPs reviewed and consistent
  • Phase 3: DONE — Dev agent submits PR → hook sets status:qa + comments PR URL on issue automatically. QA agent posts verdict → hook sets status:approved or status:needs-fix automatically.
  • Phase 4: DONE — /sprint-sync, /sprint-status, /sprint-add, /sprint-kickoff skills deployed.
  • Phase 5: PENDING — Dev submits PR → QA auto-spawned → verdict auto-labels → merge auto-syncs board. Full loop.
  • End-to-end: One issue through the full loop with all DORA timestamps captured.

Discovered Scope

  • todo-fix-remind-mcp-review-loop-paldocs-ref — stale pal-e-docs reference in remind-mcp-review-loop.sh (Phase 3 QA)
  • todo-forgejo-mcp-label-comment-tools — MCP gap: no set_label or comment_on_issue tools (Phase 3 design)

Next Plan Seeds

  • DORA dashboard automation — once timestamps are captured, build the Grafana dashboard (connects to plan-2026-02-25-platform-observability Phase 4)
  • Token metrics integration — layer token tracking (connects to todo-token-metrics-dora-correlation)
  • forgejo-mcp tool expansion — proper set_label + comment_on_issue MCP tools (see todo-forgejo-mcp-label-comment-tools)
  • Sprint auto-population — API-side auto-sync (connects to phase-sprints-2-issue-sync)
  • dora-framework — the axiom this plan serves
  • plan-2026-03-01-pal-e-sprints — parent backend plan
  • phase-sprints-2-issue-sync — API-side complement
  • todo-sprint-workflow-automation — the TODO this plan was promoted from
  • todo-token-metrics-dora-correlation — future token tracking
  • todo-forgejo-mcp-label-comment-tools — MCP gap discovered in Phase 3 design
  • sop-claude-config-development — SOP for Phases 3-5
  • sop-post-merge-docs — post-merge documentation gate (supplementary deliverable)
  • agent-workflow — label signaling protocol
  • pr-lifecycle — PR flow with label integration