V-Model workflow guide

/dia-guide is the read-only orientation layer of DIA, invoked explicitly by the user (the skill is marked explicit-only; the model never auto-loads it). It reads project state, audits the last phase-end commit for the binding DIA trailers, recommends the next phase skill, and runs the Closing Handoff after a successful security audit. Almost every concrete change lives in the phase skill the guide dispatches to; the guide owns only two narrow CRUD moments at workflow boundaries: the post-/dia-realign item promotion (issues, tags) and the item-start branch creation.

The phase skills (/business-analysis, /requirements-engineering, /architecture, /coding, /testing, /security-audit) are autonomous. They run their own triage and their own handoff ritual. The pre-commit hook enforces the drift-critical graph invariants between boundaries; the full /consistency-check runs before release. The guide is the on-demand orientation layer above them.

When to use the guide

Use /dia-guide when:

• You are starting a new project and do not know which phase to begin with
• You want a status read of the current cycle ("where am I?")
• You finished a phase and want a recommendation for the next step
• You are unsure whether the last handoff was complete

Invoke a phase skill directly when:

• You know exactly which phase you need (for example, /coding because the design is finalised)
• You want to iterate inside one phase
• You are resuming a project mid-workflow without an orientation question

Both modes produce the same artifacts. The guide reduces friction by reading the state and recommending; it does not block direct phase-skill use.

What the guide actually does

Three responsibilities, all on demand:

Responsibility	Trigger	Output
Orientation interview	"Where do I start?" / "I am lost"	One recommended phase skill, with one or two alternatives, based on the state of BACKLOG.md, the latest DIA commit trailers, and the current branch
Handoff audit	After any phase, on user request	Read of the last phase-end commit; check for the binding trailers (DIA-Phase, DIA-Handoff, plus DIA-Triage where triage happened); report any gap and name the responsible skill
Closing Handoff	After /security-audit returns green or yellow	Recommend /consistency-check mode B; on Release-Ready: yes, output the closing report and queue the post-release review as a BACKLOG row

The guide does not write to artifacts. It reads, recommends, and hands off.

Phase 0: Artifact triage (delegated)

The artifact triage (FEAT / IMP / FIX / ADR) is owned by every phase skill at its own entry. The guide does not run the triage; it checks that the commit where triage happened carries a DIA-Triage trailer and reports the gap if missing. A skill that finds a DIA-Triage trailer for its item skips its own triage question.

Triage details live in graph-invariants.md, section "Artifact triage at entry point".

Hybrid entry-point detection

When invoked with an open question ("where do I start?"), the guide scans project state and proposes an entry point. The user picks from a clean menu:

A0) Continue current item (resume mid-cycle)
A)  Starting from scratch              -> /business-analysis
B)  Problem clear, need requirements   -> /requirements-engineering
C)  Requirements exist, need arch      -> /architecture
D)  Architecture ready                 -> /coding
E)  Implementation done                -> /testing
F)  Tests passed                       -> /security-audit
G)  Audit done                         -> Closing Handoff (consistency-check mode B + optional /release)
H)  Unsure                             -> short orientation interview
I)  Brownfield or legacy DIA repo      -> /dia-realign

The scan reads BACKLOG.md, the latest DIA commit trailers (git log --format='%(trailers:key=DIA-Handoff,valueonly)'), and git phase-done tags. The recommendation is the proposed default; the user can pick anything. In the lean profile the guide recommends /architecture or /coding directly and skips BA/RE recommendations unless the user asks for them.

The six phases plus Closing Handoff

Phase 1: /business-analysis          Problem exploration, ideation, validation
Phase 2: /requirements-engineering   Epics, FEAT-EE-FF, Success Criteria
Phase 3: /architecture               ADRs, arc42, wayfinder, plan-context.md
Phase 4: /coding                     Critical review, PLAN-NN, implementation, writeback
Phase 5: /testing                    Unit + integration tests, fix-loop
Phase 6: /security-audit             OWASP, SAST, SCA, Zero Trust
Closing Handoff (not a phase)        consistency-check mode B + optional release

Phase 1 starts on the left side of the V (design), descends to Phase 4 (implementation) at the bottom, then climbs the right side through Phase 5 and 6 (verification). The Closing Handoff is a short orientation output, not a numbered phase.

V-Model as a decision graph, not a straight path

The forward walk Phase 1 -> 6 is the default. Real projects discover things mid-flight. Three mid-course triggers can pause a phase skill and route work back:

• Mid-course bug discovery in /coding: triage, FIX backlog row, fix.
• Mid-course design discovery in /coding: amend or supersede the ADR, update arc42 and the wayfinder, then continue.
• Mid-course requirements discovery in /architecture: route back to /requirements-engineering for a FEAT update.
• Mid-course capability discovery in /coding: capture the capability gap as an ADR, route through /architecture, then continue.

The phase skills handle all four. The guide does not own iteration logic; it just observes the state and recommends what to do next.

Phase boundary mechanics (owned by phase skills)

The boundary mechanics live in the phase skills, not in the guide. The guide only reads their output. Each phase skill runs at its end:

1. 3-part Handoff Ritual (artifact report, phase-end commit with DIA trailers and handoff context in the commit body, plus tag-phase, transition question). See Handoff Rituals. The pre-commit hook checks the drift-critical graph invariants on every commit.
2. Plan-gate (only at the start of /coding): SC coverage map, ADR alignment, codebase anchoring, verify commands ready. The plan must close every Critical ASR. This gate lives in the /coding entry block.

If a phase skill detects an issue at boundary, it reports and pauses. The guide can be invoked next to reread state and recommend a remediation step.

GitHub flow.py integration

The phase skills coordinate with GitHub through tools/github-integration/flow.py:

• flow.py create-issue --item <ITEM-ID>: create a tracking issue on phase entry, optional gh project item-add if a project is configured
• flow.py tag-phase --phase {ba|re|arch|code|test|sec}: attach a <id>/<phase>-done tag at every phase-end commit. The release-readiness marker ready-for-review is the single exception, it produces <id>/ready-for-review without the -done suffix
• flow.py sync-status --item <ITEM-ID>: mirror the BACKLOG Status to the GitHub issue and Project Status field, pull the GitHub Assignee back into the BACKLOG Claim column
• flow.py promote-to-epic --item EPIC-NN [--rename-branch]: rewrite the parent issue, create sub-issues, write the Sub-Issues tasklist, optionally rename the branch
• flow.py ready-for-review --item <ITEM-ID> [--with-sec]: flip the draft PR to ready when the cycle reaches the Closing Handoff
• flow.py validate-fix --item FIX-EE-FF-NN: hotfix-scoped consistency check (always runs the local checks; the GitHub-issue check is gated on mode = github-sync)
• flow.py apply-renumber --plan FILE: invoked from scripts/merge-to-dev.sh after a renumber to align GitHub issue titles and parent-body Sub-Issues tasklists
• Claim ownership now flows from the GitHub Assignee into the BACKLOG Claim column via sync-status. The earlier separate claim subcommand has been removed.

The guide reads flow.py status --item <ID> for its state audit. The local backlog row remains the source of truth for status; the GitHub Assignee is the source of truth for the Claim column; both sides are mirrored by sync-status.

Concurrent agent coordination

When multiple human-agent pairs work the same backlog, each pair identifies itself with a pair-id ({human-handle}-{model}, for example seb-opus-4-7) in the Claim column of BACKLOG.md. Phase skills claim a row at start and release on phase end or Status: Done. The backlog itself is the lock; there is no central lock service.

User Interaction Protocol

The guide follows three rules in user dialog:

1. One question per turn. No multi-question lists.
2. Pro / Con framing for every decision option. The user sees why each option exists and what it costs.
3. AskUserQuestion for choices. Free-form prompts only when the answer is genuinely open-ended.

Closing Handoff

The Closing Handoff is a short guide output, not a phase. It fires after /security-audit has produced a non-red verdict and the fix-loop is closed.

Four steps:

1. Suggest /consistency-check mode B (semantic; the check is an explicit user command). Mode B confirms BA Validation is filled, all Feature/ADR statuses are final, arc42 reflects the actual decisions, and plan-context matches the real tech stack. Mode B returns a Release-Ready verdict.
2. On Release-Ready: yes: output the closing report (Feature / bug / security counts, finalised artifacts). The user can then run a private release skill (the public DIA plugin does not own a release mechanism, since release pipelines are project-specific).
3. Queue the post-release review as a BACKLOG row under Deferred / Ideas: type BL-Item, with a revisit date scaled to scope and refs to the hypotheses to re-validate. No separate handoff file.
4. On Release-Ready: no: name the responsible skill and the items to fix. Cycle closure resumes after the fix.

The Closing Handoff does not invoke any skill. It is a handoff text the guide outputs and lets the user decide.

Opt-out

The workflow is advisory, not enforcing. You can:

• Leave the loop: at any handoff, say "stop" or ask something unrelated. The workflow pauses immediately.
• Temporarily disable the skills: say "ignore the V-Model today" or "just help me with X without the workflow".
• Permanently disable: /plugin disable digital-innovation-agents in the Claude Code CLI removes the SessionStart hook entirely.

The workflow state is preserved in _devprocess/ and in the git phase-done tags. You can resume later by re-invoking /dia-guide.

Read the skill file

Want to see the exact instructions the agent follows? skills/dia-guide/SKILL.md on GitHub.

What's next

• Business Analysis guide: Phase 1 detail
• Coding guide: Phase 4 detail, the heart of the system
• V-Model concept: why this shape?
• Handoff Rituals concept: how transitions work
• Consistency Check guide: the explicit graph check that runs before release
• Three-layer documentation model: why state lives in the backlog row
• Drift defense: the full catalog of drift sources and how each is defended