Skip to content

Agentic dev-workflow skills & automation — make the Story workflow executable, not memorised

epic_id: CVN-N014-EC need_id: CVN-N014 (parent — see Continuous improvement) OP: wp#205 GH issue: #1027 Status: in progress Created: 2026-05-23 Owner: dococeven Trigger: the Story workflow (ADR-69/81) + committee + OP rituals were correct but memorised and hand-run, so they drifted (forgotten OP wp, skipped committee meeting log, stale-DAG re-triggers). This Epic turns the recurring rituals into deterministic scripts + judgment-layer skills, so the discipline is executed, not remembered.

1. Objective

Encode the recurring agentic dev-workflow rituals as two complementary layers:

  • SCRIPTS (deterministic, tested, PR'd) — the mechanism: op_story_transition.py, create_story.py, loki_query.py, airflow_xcom_pull.py, the skill event emitter.
  • SKILLS (judgment layer, user-invocable) — whether and with what to run the mechanism: story-advance, loki-query, cr-round, committee-review, create-story, diagnostic-scaffold.

Each ritual becomes auditable (skill events → local audit log + Loki) and gated (the skill verifies the gate before the side effect). The Epic mirrors the SSoT discipline of ADR-77 (docs) and ADR-70 (MLOps readiness) for the process domain.

2. Scope (components)

  • scripts/ — op_story_transition.py, create_story.py, loki_query.py, airflow_xcom_pull.py, op_save_committee_as_meeting.py, new_worktree.sh.
  • .claude/skills/ — story-advance, loki-query, cr-round, committee-review, create-story, diagnostic-scaffold, plus the canonical skill-authoring standard (S00).
  • documentation/process/ — STORY_WORKFLOW.md, CREATE_STORY.md, LOKI_QUERY.md, AIRFLOW_XCOM_READER.md, PARALLEL_DEV_WORKTREES.md.
  • ADRs touched/created by member Stories: ADR-81 (8-state workflow), ADR-82 (committee→meeting), ADR-87 (story-phase tests), ADR-92 (DAG provenance), ADR-95 (diagnostic template).

3. Cross-Story architecture — the SCRIPT / SKILL split

operator types  /story-advance 247
        │
        ▼
SKILL (judgment)  ── verifies the ADR-81 gate, derives verdict/evidence,
   story-advance      asks for explicit operator approval, emits skill events
        │
        ▼
SCRIPT (mechanism) ── op_story_transition.py : the deterministic PATCH
   op_story_transition  (lockVersion, legal-edge refusal, comment) — tested
        │
        ▼
OpenProject (SSoT)  ── state + verdict/evidence comment

A skill never re-implements the mechanism (PATCH/lockVersion/legal-edge live in the tested script); a script never makes the whether/with-what judgment (that is the skill + operator). Every skill emits the canonical skill_invoked/skill_operator_approval/skill_completed events via emit_skill_event.py (local audit log; best-effort Loki).

4. Stories

Story Title Type State
CVN-N014-EC-S00 Skill-authoring standards & template standard open
CVN-N014-EC-S01 op-story-transition SCRIPT closed
CVN-N014-EC-S02 loki-query SCRIPT closed
CVN-N014-EC-S03 cr-round SKILL open
CVN-N014-EC-S04 committee-review SKILL open
CVN-N014-EC-S05 diagnostic-story-scaffold SKILL+template closed
CVN-N014-EC-S06 story-plan-gate SKILL closed
CVN-N014-EC-S07 create-story SCRIPT closed
CVN-N014-EC-S08 pr-merge SKILL open
CVN-N014-EC-S09 dag-run-readiness SKILL open
CVN-N014-EC-S10 story-close SKILL closed
CVN-N014-EC-S11 story-advance (generalist ADR-81 transition) SKILL closed
CVN-N014-EC-S12 loki-query SKILL (judgment over the script) SKILL closed
CVN-N014-EC-S13 migrate diagnostic-story pattern to Hamilton reference DAG closed
CVN-N014-EC-S14 create-story (SKILL) SKILL closed
CVN-N014-EC-S15 Harden the canonical skill emitter (escaping + flock) SKILL hardening open
CVN-N014-EC-S16 dev-productivity tooling: XCom reader + worktree bootstrap SCRIPT open
CVN-N014-EC-S17 Generalize the canonical Story/Epic documentation standard (+ remediate gaps) governance in progress
CVN-N014-EC-S18 epic-close — gated Epic/version closure wrap-up skill SKILL in progress

(State reflects the GH issue at epic-doc creation; OpenProject is the live SSoT, ADR-76.)

5. Validation strategy

Each member Story validates at its own gate (committee plan_review/pr_review, CI, dogfood). Epic-level validation = the rituals are executed, auditable, and gated: skill events land in the audit log; OP transitions carry verdict/evidence; committee sessions are logged as OP Meetings (ADR-82). This Epic's own discoverability gap (no epic doc / nav) — fixed by CVN-N014-EC-S17 — is the trigger that generalised the documentation standard beyond diagnostics.

6. Status

in progress — foundational SCRIPTS + SKILLS shipped (S01/S02/S05/S06/S07/S10/S11/S12/S13/S14 closed); open: S00 (skill standard), S03/S04/S08/S09 (skills), S15 (emitter hardening), S16 (XCom tooling), S17 (doc-standard generalization), S18 (epic-close wrap-up skill).