# Dia Guide > > - **Type:** Skill - **Install:** `agentstack add skill-pssah4-digital-innovation-agents-dia-guide` - **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior - **Seller:** [pssah4](https://agentstack.voostack.com/s/pssah4) - **Installs:** 0 - **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills) - **Latest version:** 0.1.0 - **License:** MIT - **Upstream author:** [pssah4](https://github.com/pssah4) - **Source:** https://github.com/pssah4/digital-innovation-agents/tree/main/skills/dia-guide - **Website:** https://pssah4.github.io/digital-innovation-agents/ ## Install ```sh agentstack add skill-pssah4-digital-innovation-agents-dia-guide ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About # V-Model Workflow Guide ## What this skill does (and does not do) `/dia-guide` is the read-only orientation layer of DIA. It: - Reads `BACKLOG.md`, the latest `HANDOFFS.md` entry, and git state when the user invokes it - Recommends the next phase skill in plain text - Audits whether the last handoff carries the binding fields (`triage:`, `triage_kind:`, `epic:`, `feature:`) - Runs the Closing Handoff after a green `/security-audit` - Owns two narrow CRUD moments at workflow boundaries that no single phase skill covers: (a) the **post-`/reverse-engineering` item promotion** (described below), and (b) the **item-start branch creation** when the user enters at A/B/C from a fresh repo What the guide does NOT do: - It does not perform artifact triage. Triage lives in every phase skill's MANDATORY Phase 0 block. See `skills/project-conventions/references/graph-invariants.md`, section "Artifact triage at entry point". - It does not enforce the plan gate. The plan gate lives in `/coding` Phase 3a as the "Plan Coverage Gate (binding, runs before Status flips to Active)". `/coding` runs the gate; the guide only reads the result. - It does not run `/consistency-check` mode A at phase boundaries. Each phase skill runs mode A in its own handoff ritual. Mode B fires from the Closing Handoff, see below. - It does not call other skills. It recommends; the user invokes. ## Item-start branch creation When the user picks entry-point A, B, or C in the hybrid entry-point detection (see "Start: Determine Phase" below), the guide creates a fresh feature branch from the configured source branch before the phase skill takes over. The phase skill itself does not own this because the branch must exist before the first artifact is written. Steps: 1. **Read `.dia/config.toml`.** Extract the `source_branch` (default `develop`) and the `mode`. If the file is missing, fall back to `develop` and treat the mode as `git-only`. 2. **Slug input.** Ask the user (single `AskUserQuestion`, short plain-text "Other" slot) for a short kebab-case slug describing the item. The slug is provisional. It becomes the suffix of the feature branch name. Example: `auto-save-on-input`. 3. **Branch creation.** ```bash git fetch origin --quiet || true git checkout git pull --ff-only origin 2>/dev/null || true git checkout -b feature/ ``` If the branch already exists, switch to it and warn the user. Do not overwrite work. 4. **Mode-aware GitHub side-effect.** If `mode = "github-sync"` and the user has an existing GitHub issue tracking this item, the guide reminds the user to assign themselves on GitHub so that `flow.py sync-status` can mirror the assignee into the BACKLOG `Claim` column once the item gets a real ID. The guide does not create an issue at this stage; the phase skill that first writes a backlog row (typically `/business-analysis` or `/requirements-engineering`) calls `flow.py create-issue` once the ID is known. 5. **Hand-off.** Print the branch name to the user, then recommend the relevant phase skill: A -> `/business-analysis`, B -> `/requirements-engineering`, C -> `/architecture`. The phase skill takes over. Branch rename after RE: when `/requirements-engineering` finishes and the EPIC ID is known, the user (or `/dia-guide` on a later invocation) can run ``` python3 tools/github-integration/flow.py promote-to-epic --item EPIC-NN --rename-branch ``` to retitle the parent issue, create sub-issues, and rename the branch from `feature/` to `feature/epic-NN-`. The guide does not run this automatically; the user invokes it via the RE handoff or directly. ## Post-reverse-engineering item promotion (the only CRUD moment) `/reverse-engineering` finishes with a backlog seed: 20+ items at `Status: Backlog, Source: REV, Notes: anticipated` on a single `feature/reverse-engineer-` branch. The Status column uses the GitHub-aligned vocabulary; the "anticipated" flavour is recorded in the Notes column so the user can filter for it during triage. Per-item branches and per-item GitHub issues kick in only after a user-driven triage: which seed items become real backlog candidates? `/reverse-engineering` explicitly defers this step to the guide (see RE's Pre-Phase 0). This is the only place where the guide writes. It is a multi-item user interaction at a workflow boundary that no single phase skill covers. The user drives the triage; the guide executes the per-item operations. Steps: 1. Read `BACKLOG.md`, list items with `Status: Backlog, Source: REV` whose Notes column contains `anticipated`. 2. AskUserQuestion: which items should be promoted now (vs. left in `Backlog` with the `anticipated` note for later)? 3. For each promoted item: ``` python3 ${DIA_PLUGIN_ROOT:-.}/tools/github-integration/flow.py create-issue --item git tag -a /reverse-engineered -m "Item promoted from /reverse-engineering" ``` 4. Update BACKLOG row: `Status` -> `Ready` (or `In Progress` if the item already ships and only needs the inventory recorded). Remove the `anticipated` note from the Notes column. 5. Recommend the next skill: typically `/business-analysis` to validate the BA draft, or `/coding` for items that already ship and just need the inventory recorded. ## Handoff state audit (read-only, on user invocation) When the user invokes `/dia-guide` after a phase skill has finished, the guide reads the team-workflow surface and reports any drift between artifact state and collaboration state. It does NOT write, fix, or tag. It surfaces, the user decides. Audited surfaces (full reference: `skills/project-conventions/references/team-workflow.md`): 1. **Branch.** Is the current branch on an item-branch (per `team-workflow.md` schema)? If not, surface a warning. 2. **Phase tag.** Did the just-finished phase set its `/-done` tag via `tools/github-integration/flow.py tag-phase`? Each phase skill is responsible for setting its own tag during its handoff ritual. If missing, the guide names the phase skill that should re-run its handoff ritual. 3. **Backlog row.** Does the BACKLOG row's status reflect the phase progress (Building during BA -> RE -> Coding, Released only after merge)? Discrepancies indicate the phase skill's handoff ritual did not write the row before the phase-end commit. 4. **GitHub issue.** Does the issue exist and carry the right phase label and ticked checklist? Each phase skill's `flow.py tag-phase` call invokes `update_issue_after_tag` internally to keep the issue in sync. The guide only reads `flow.py status --item ` and reports the snapshot. 5. **HANDOFFS entry.** Does the latest entry have `triage:`, `triage_kind:`, and (for IMP/FIX) `epic:` + `feature:`? Missing fields are flagged with the responsible phase skill named. The guide reports findings in plain text and recommends the next step. It does not auto-fix, does not append to METRICS, does not tag, and does not call other skills. METRICS is written by phase skills directly; the guide only reads it. ## Feature-complete read (before release) When the user asks "is this item ready for release?", the guide reads the phase tags and reports. No tagging, no PR transition, no skill invocation. Audit: 1. Verify all required phase tags exist for the active item: - `/code-done` (always) - `/test-done` (always) - `/sec-done` (when item touches security-relevant surface; legacy `/audit-done` is also accepted) 2. Run `flow.py status --item ` and show the user the result. 3. Report in plain text: ``` Item '' phase status: - code-done: yes/no - test-done: yes/no - sec-done: yes/no/n-a Verdict: feature-complete | missing tags: ``` If a tag is missing, the guide names the responsible phase skill so the user can re-run it. If feature-complete, the user can mark the PR ready (`flow.py ready-for-review --item `) and invoke their private release skill themselves. The guide does neither. --- This skill is the navigation layer. Each phase builds on the previous one and produces artifacts as input for the next phase. All phases follow the conventions from `/project-conventions`. ## Workflow Overview ``` Phase 0 (brownfield only): /reverse-engineering REVERSE WALK Input: existing codebase + documentation (backwards Output: plan-context.md, ADRs (Inferred), up the V) arc42 (Snapshot), FEATURE-*.md (Observed), BA-{PROJECT}.md (Draft), backlog seed | v (forward walk starts here) Phase 1: /business-analysis DESIGN Output: _devprocess/analysis/BA-{PROJECT}.md (left side | of the V) v Phase 2: /requirements-engineering Input: BA document Output: Epics, Features, architect-handoff.md | v Phase 3: /architecture Input: Features, ASRs, NFRs Output: ADRs, arc42, plan-context.md | v Phase 4: /coding IMPLEMENTATION Input: plan-context.md + ADRs + Features (bottom of the V) Action: Load context, critical review, brief the Default agent (task breakdown, optional TDD, debugging protocol, verification gate), write artifacts back | v Phase 5: /testing VERIFICATION Input: Implemented codebase + Features (right side Output: Unit + integration tests, fix-loop of the V) | v Phase 6: /security-audit Input: Implemented codebase Output: Security report + remediation, fix-loop | v Closing Handoff (not a phase) Input: Green security audit Output: /consistency-check mode B verdict + release-to-ba HANDOFFS template; user can run their private release skill ``` ## Phase Transitions (read-only audit) When the user invokes `/dia-guide` between phases, the guide reads project state and surfaces the next step. The guide does not drive or launch phase skills; phase skills are autonomous and own their own handoff ritual. The guide observes: 1. Reads the latest entry in `_devprocess/context/HANDOFFS.md` (artifact report, triage IDs, release-readiness markers) 2. Reports the recommended next step in plain text and names the skill to invoke (e.g. "Recommended next: `/coding`") 3. The user invokes the next phase skill themselves; the guide does not call other skills The guide does not loop, does not auto-advance, and does not block. Every phase transition is a separate user action. The guide is re-invoked whenever the user wants the next-step audit again. **When a phase-skill is invoked directly (without `/dia-guide`):** The Handoff Ritual still runs, and the handoff context is still written to `_devprocess/context/HANDOFFS.md`. The user can then manually start the next skill, which will pick up the handoff entry. ### Handoff entry format (binding) Every new handoff entry in `_devprocess/context/HANDOFFS.md` starts with a short header block that carries the **artifact triage** from Phase 0. The next skill does not need to re-ask the triage question. ``` ## {skill-from}-to-{skill-to} {YYYY-MM-DD} triage: FEAT-01-03 # or IMP-007 / FIX-012 / ADR-04 triage_kind: feature # one of: feature | improvement | fix | adr epic: EPIC-01 # mandatory for IMP/FIX; recommended otherwise feature: FEAT-01-03 # mandatory for IMP/FIX ... (phase-specific fields, e.g. NFR summary, open questions, ...) ``` **Rule:** a skill that reads a handoff entry and finds a `triage` ID uses it as the Phase-0 assignment and skips the triage question. If the field is missing, the skill falls back to normal Phase-0 logic (derive from prompt, ask if needed). Exception: the very first handoff entry in a greenfield project (e.g. `/business-analysis` to `/requirements-engineering` without an existing feature) MAY carry `triage: new-feature-pending`. The concrete FEATURE ID is then assigned by `/requirements-engineering` and written into the next handoff entry. ## Ensure project structure exists Before a phase starts, check whether the directory structure exists. If not, initialize it per `/project-conventions`: ```bash mkdir -p _devprocess/{analysis/sources,requirements/{epics,features,fixes,improvements,handoff},architecture,rules,implementation/plans,context} mkdir -p src docs scripts memory touch _devprocess/context/HANDOFFS.md ``` For `_devprocess/context/BACKLOG.md`, do not `touch` an empty file. Seed it from `skills/requirements-engineering/templates/BACKLOG-TEMPLATE.md` with the project name, an empty dashboard, and the placeholder sections. Every phase skill updates this file per the binding format. For `_devprocess/rules/`, seed `technical.md` from `skills/architecture/templates/RULES-TECHNICAL-TEMPLATE.md`. Add `design.md` only if the project has UI surface, seeded from `RULES-DESIGN-TEMPLATE.md`. Add `domain.md` if the project has business-domain rules, seeded from `RULES-DOMAIN-TEMPLATE.md`. For `src/ARCHITECTURE.map`, seed from `skills/architecture/templates/ARCHITECTURE-MAP-TEMPLATE.md` with empty rows. `/architecture` and `/coding` populate it as entry-points appear. ## Start: Determine Phase Before asking the user, the guide runs a **hybrid entry-point detection** (added 2026-04-20): it scans the project, diagnoses the graph state, and formulates a recommendation. The user keeps the override. ### Step 1: Scan + recommend 1. Detect the project root convention (`_devprocess/` or `docs/`). 2. Run `/consistency-check` in Mode A (syntactic). The result is the current Graph-Health snapshot. 3. Infer the likely entry point from the snapshot: | Observation | Recommended entry | | ------------------------------------------------------------- | ------------------------------------------ | | No V-Model artifacts at all, empty repo or pure greenfield | `/business-analysis` (Project-BA) | | Code exists, no `_devprocess/analysis/BA-*.md`, no FEATUREs | `/reverse-engineering` | | Project-BA exists as Draft, not yet validated | `/business-analysis` Validation Mode | | Project-BA validated, user wants to start a new epic / feature | `/business-analysis` (Item-BA) | | Project-BA validated and Item-BA exists, no EPIC/FEAT yet | `/requirements-engineering` | | Features exist, no ADRs or plan-context.md | `/architecture` | | plan-context.md exists, no recent code changes | `/coding` | | Coding done, no test coverage / failing tests | `/testing` | | Tests green, no security audit | `/security-audit` | | Everything closed, release pending | Closing Handoff (`/consistency-check` mode B + `/release` if configured) | | Graph-Health shows many orphans or dead links | `/consistency-check` + Cleanup first | ### Step 2: Present recommendation + alternatives Show the user one `AskUserQuestion` with the recommendation as the first option and the manual list as alternatives: ``` Graph-State (letzter Check {date}): - Epics {n}, Features {n} (Released {a}, Building {b}, Planned {c}, Candidates {d}), ADRs {n}, FIX/IMPs {n}, offene Luecken {n}. Empfehlung basierend auf dem Graph-State: {recommended entry} Oder du waehlst manuell aus: A0 /reverse-engineering (brownfield) A /business-analysis (BA von Beginn) B /requirements-engineering C /architecture D /coding E /testing F /security-audit G Closing Handoff (Audit ist gruen, Cycle abschliessen) H /consistency-check (nur Graph-Pflege) I Orientierungs-Interview (helfe beim Entscheiden) ``` If the user picks the recommended option or says "ok/go/next", start that phase. If the user picks a different option, start that one. If the user wants an interview, ask short follow-up questions to refine the recommendation. ### Step 3: Phase-Entry mit Konsistenz-Hinweis Beim Start der gewaehlten Phase zeigt der Guide eventuelle Konsistenz-Luecken aus `/consistency-check`, die fuer die Phase relevant sind. Beispiel: vor `/architecture`-Start "Du hast 3 Features ohne Epic-Parent, das sollten wir vorher klaeren, willst du `/consistency-check` auto-fixes laufen lassen?" ## Recommended next step per phase These are the standard recommendations the guide surfaces when a phase is complete. The guide does not invoke the next skill; it prints t … ## Source & license This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code. - **Author:** [pssah4](https://github.com/pssah4) - **Source:** [pssah4/digital-innovation-agents](https://github.com/pssah4/digital-innovation-agents) - **License:** MIT - **Homepage:** https://pssah4.github.io/digital-innovation-agents/ Install and usage instructions live in the source repository linked above. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** no - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** no - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: passed — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/skill-pssah4-digital-innovation-agents-dia-guide - Seller: https://agentstack.voostack.com/s/pssah4 - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.