--- name: vibepro-workflow description: Use when working with VibePro CLI, Graphify, Story diagnosis, task planning, PR preparation, Gate evidence, or VibePro review artifacts. --- # VibePro Workflow ## Purpose Use VibePro as a Story / Architecture / Spec / Graphify / Gate control plane. The CLI creates evidence; this Skill tells the agent how to use that evidence without skipping the intended order. ## When to Use Use this Skill when the task mentions VibePro, Story/Spec/Architecture, Graphify, Gate DAG, PR preparation, Agent Review, diagnosis packages, review cockpit, or VibePro-managed evidence under `.vibepro/`. Also use it when the user asks whether VibePro work is done, PR-ready, verified, reviewable, or safe to merge. In those cases the answer must be grounded in current VibePro artifacts and repository state, not a general impression. ## Operating Order 1. Confirm the target repository and current branch. 2. Initialize only when needed: `vibepro init --language ja`. 3. Before manually adding or editing human-facing VibePro artifacts, resolve the output language from `.vibepro/config.json` `output.language` or the explicit CLI `--language` override. 4. Select or create the Story before diagnosing or changing code. 5. Import impact context before impact-sensitive work: - Run Graphify when artifact-level graph context is useful: `vibepro graph --run-graphify`. - Use `vibepro-codebase-memory` when `codebase-memory-mcp` is available and changed-file topology, symbols, routes, call paths, or risk hints would affect implementation, tests, review roles, or split boundaries. 6. Diagnose and derive the repo context: - Before final Architecture/Spec on workflow-heavy or cross-surface stories, use design-input diagnosis: `vibepro story diagnose --id --pre-architecture --run-graphify` - Before implementation or PR readiness, rerun the consistency gates after Architecture/Spec exist. - `vibepro story derive --run-graphify` - `vibepro story map ` 7. When the user asks for a purpose-level check, use diagnosis packages instead of guessing the scanner set. Run `vibepro check list` for the current registry, then `vibepro check `. Registered packs include `ui`, `security`, `performance`, `architecture`, `pr-readiness` (`--base --head `), `launch-readiness`, `agent-harness`, `public-discovery`, `self-dogfood`, `oss-readiness`, `regression-risk`, and `all`. 8. For performance improvement stories, define and record Story-level performance evidence before claiming speedups: - `vibepro performance define --id --metric-id --user-story --start-condition --completion-condition --evidence-source ` - `vibepro performance record --id --metric-id --label before|after --status completed --duration-ms --evidence-source ` - `vibepro performance compare --id ` 9. For existing UI modernization, derive the product-local Design System before screen implementation: - Run Graphify first when available: `vibepro graph --run-graphify`. - Run `vibepro design-system derive --id --product --routes --brief --from-code`. - Review `.vibepro/design-system//evidence-coverage.json` and `ds-gate.json` before accepting the DS as an implementation constraint. - Treat `.vibepro/design-system//design-system.json`, `semantic-tokens.json`, `component-roles.json`, `component-states.json`, `screen-patterns.json`, `cta-policy.json`, `density-policy.json`, `navigation-policy.json`, `anti-patterns.json`, and `implementation-mapping.json` as product-local DS evidence. 10. For screen-level UI modernization, create the story-specific design decision space before screen implementation: - `vibepro design-modernize derive-system --id --product --routes --brief ` - `vibepro design-modernize plan --id --product --routes --base-url ` - Treat `.vibepro/design-modernize//derived-design-system.json`, `design-modernize.json`, and `ds-gate.json` as implementation constraints. - External Design System bundles, screenshots, and image-generated ideas are visual hypotheses. The VibePro-derived Design System, current UI evidence, Story/Spec, and Gate DAG remain authoritative. 11. When you receive a Story, judge whether UI/UX intake applies — before implementation, for every story. `gate:uiux_intake_judgment` in `pr prepare` fails closed on the absence of this judgment (not on the intake itself): - If the story carries UI/UX intent (screens, routes, visual/interaction/UX changes, vague design briefs), run `vibepro uiux intake template --id `, fill it, then `vibepro uiux intake validate --id `. The coverage artifact satisfies the gate. - If you judge intake not applicable (no UI/UX intent), record that judgment with its reason: `vibepro decision record --id --type intake_not_applicable --summary --reason `. Silence is not an option; an unreasoned skip blocks PR preparation. 12. For UI/UX requests that start from user intent rather than existing screens, use the uiux preparation cockpit before implementation: - `vibepro uiux intake template --id ` then fill and `vibepro uiux intake validate --id ` - `vibepro uiux map --id ` - `vibepro uiux evidence --id ` - `vibepro uiux prepare --id ` 13. Plan work from VibePro evidence: `vibepro story plan `. 14. Create task context before implementation: `vibepro task create --from-plan --id `. Use `vibepro task brief|plan|handoff --task ` for task-scoped context. 15. During implementation, checkpoint progress with `vibepro checkpoint --story-id ` and check gate state early with `vibepro gate check --story-id ` instead of discovering blocks at PR time. 16. After code changes, run `vibepro pr prepare --story-id `. Record verification evidence with `vibepro verify record`, and import CI results with `vibepro verify import-ci --id --pr ` instead of rerunning full suites locally when a PR exists. 17. Read the `pr prepare --summary-json` or `--view` output first, then `.vibepro/pr//pr-prepare.json` `gate_status` before treating work as PR-ready. Also inspect `decision-index.json` and `evidence-plan.json` when present so skipped or depth-limited artifacts are not mistaken for missing evidence. 18. If `gate_status.agent_review_instruction` is present, Agent Review is mandatory. Treat the generated review plan as an instruction to dispatch Codex/Claude Code subagents when the coordinator runtime provides subagent capability. Do not convert it into a user-permission wait or silently skip it. 19. Run parallel subagent review: - Run each listed `vibepro review prepare --id --stage `. - Open the generated `.vibepro/reviews///parallel-dispatch.md`. - Before spawning, run `vibepro review authorize` for each role with the intended model, risk closure, judgment delta, reusable evidence, and freeze state. Spawn only roles whose authorization returns `action: dispatch`; a stop means no subagent is started. - After an authorized spawn returns the real subagent id, immediately register it with `vibepro review start --dispatch-authorization `. Authorized reservations count against the Story-wide budget so parallel coordinators cannot overbook it. Close each lifecycle with `vibepro review close --close-reason completed` after the subagent returns. Use `vibepro review repair --story-id ` to generate the repair command sequence for incomplete review evidence. - After each subagent returns, close/shutdown that review subagent before recording the result. Do not leave review subagents running. - Record every result with `vibepro review record` and include subagent provenance plus closed lifecycle evidence: - Codex: `--agent-system codex --execution-mode parallel_subagent --agent-id --agent-closed` plus `--agent-thread-id` or `--agent-call-id` when available. - Claude Code: `--agent-system claude_code --execution-mode parallel_subagent --agent-id --agent-closed` plus `--agent-session-id` or `--agent-transcript` when available. - Rerun `vibepro pr prepare` and continue only after `gate:agent_review` passes. - If the runtime cannot spawn subagents, block or record a human waiver decision; manual review records do not satisfy required Agent Review Gate. 20. Close the adjudication gates before PR create when `pr prepare` reports `gate:evidence_adjudication` or `gate:judgment_dag_adjudication` unresolved: `vibepro adjudicate prepare --id ` (and `--judgment`), dispatch the generated request to an **independent fresh-context subagent** (not the implementing agent), record verdicts with `vibepro adjudicate record`, and close `not_verifiable_by_automation` / `needs_human_judgment` entries with accepted decision records. Verdicts are head-bound and fail closed; see `vibepro-gate-evidence` for the full playbook. 21. Read `pr-body.md` as the concise GitHub decision brief only. Do not treat it as the audit log or as the full Gate record. 22. Open `review-cockpit.html`, `gate-dag.html`, and `split-plan.html` only when the evidence-depth policy generated them. When they are skipped, use their JSON sidecars or the embedded summaries in `pr-prepare.json` / `decision-index.json`. 23. Use `vibepro pr create`; do not bypass VibePro with raw `gh pr create`. When the Release Surface Guard blocks a release command, restore readiness via `pr prepare` instead of working around the guard (see Release Surface Guard below). 24. After the PR exists, wait for remote checks, import CI evidence with `vibepro verify import-ci`, rerun `vibepro pr prepare`, and rerun `vibepro pr create` so an existing PR body and `pr-create.json` are refreshed for the current head. 25. Merge through `vibepro execute merge --story-id --strategy merge` (`--infer-session` or `--session-id auto` attaches session cost accounting); do not use raw GitHub merge as the normal VibePro completion path. `execute merge` writes `pr-merge.json` and persists canonical audit artifacts under `docs/management/audit-artifacts//`. 26. After merge, close the audit loop when asked about traceability, cost, or ROI: `vibepro audit replay --story-id `, `vibepro audit session-cost --story-id `, `vibepro trace backfill ` / `vibepro trace declare --story-id --lifecycle `, and `vibepro usage report --subagent-roi --gate-roi`. ## Human Artifact Language - Human-facing Story, Journey, Architecture, Spec, Task, Review, Diagnosis, and PR artifacts should be written in the resolved output language. - Preserve machine-facing identifiers exactly: JSON keys, schema names, enums, Story IDs, Gate IDs, DAG node IDs, task IDs, role IDs, commands, file paths, package names, and external tool names. - Preserve user-provided text and external evidence text unless the artifact explicitly asks for translation or localization. - When CLI-generated artifacts are incomplete and the agent fills them manually, match the repository language policy instead of defaulting to English. ## Managed Worktree Execution - `vibepro execute start --story-id ` creates or reuses a managed worktree and reports its state (`managed_worktree: preferred/created|reused`). Prefer this over creating git worktrees manually for VibePro work. - Use `vibepro execute status|next|reconcile` to inspect and advance the Execution DAG, and `vibepro execute merge` to complete it. - Run implementation, verification, review, PR preparation, and PR creation from the reported worktree. Do not claim VibePro created a worktree unless the command output records that state. - Create branches from inside the worktree. Running `git switch -c` from another checkout (for example the canonical repo) creates the branch in the wrong place. ## Release Surface Guard - `vibepro guard` blocks release-surface commands (`gh pr create`, `gh pr merge`, `fly deploy`, `vercel deploy|--prod`, `npm publish`, pushes to protected branches) while the selected story is not `ready_for_pr_create=true`. Readiness that cannot be evaluated **fails closed**: release surfaces stay blocked. - Commands: `vibepro guard check [--command ] [--pre-push ] [--pretooluse]`, `vibepro guard install [--claude]` (git pre-push hook / Claude Code PreToolUse hook), `vibepro guard status`, `vibepro guard uninstall`. - When blocked, the correct response is to close the blocking gates and rerun `vibepro pr prepare` — not to reroute the release through another surface. - Bypass exists only for genuine emergencies: set `VIBEPRO_GUARD_BYPASS=""`; the bypass is appended to `.vibepro/guard/bypass-log.jsonl` with command, story, head SHA, and timestamp for audit. Never bypass silently or without a real reason. ## Context Economy - Do not read full PR artifacts into agent context first. Start from `vibepro pr prepare --story-id --summary-json` or a limited `--view `. - Drill down into full JSON artifacts only for the specific gate ids or paths the summary flags. - For evidence recording, gate troubleshooting, spec/architecture write validators, and review lifecycle details, use the `vibepro-gate-evidence` Skill. ## Guardrails - Do not treat VibePro diagnosis as truth by itself. Verify with code, tests, runtime logs, or product behavior. - Do not patch graph-sensitive runtime, auth, data, or UI state-machine code before checking Graphify impact. - Do not skip `codebase-memory-mcp` impact context for broad VibePro core, Gate DAG, Agent Review, auth/security, data/state, route, or workflow changes when the provider is installed and indexed. - Do not skip Story -> Architecture -> Spec ordering when the task is a refactor. - Do not treat `scope.status=reviewable` as completion approval. It is PR size/scope guidance only. - Do not ignore unresolved Gates. Add evidence, split the PR, block, or record a waiver reason. - Do not treat an `inconclusive` scanner status as a pass. Zero scanned targets means nothing was examined; only `not_applicable` is a legitimate out-of-scope resolution. - Do not record adjudication verdicts from the implementing agent. `gate:evidence_adjudication` and `gate:judgment_dag_adjudication` require an independent fresh-context subagent, and verdicts are head-bound (fail closed on missing or mismatched `head_commit`). - Do not work around the Release Surface Guard. A blocked release surface means gate readiness is not real yet; bypass only with a recorded `VIBEPRO_GUARD_BYPASS` reason in a genuine emergency. - Do not waive critical unresolved Gates with a reason alone. Critical Gates require evidence closure or a split/block decision. - Do not treat Agent Review Gate as optional. When it is unresolved, the coordinator must prepare, dispatch, record, and rerun the VibePro review flow before calling the work complete. - Do not record a passing Agent Review result without Codex/Claude Code parallel subagent provenance and closed lifecycle evidence (`--agent-closed`). Manual `pass` records are audit notes, not enough to satisfy `gate:agent_review`. - Keep JSON artifacts as the machine-readable source of truth. HTML is the human control plane when generated. The GitHub PR body is a concise decision brief, not an audit store. - Do not claim user-perceived performance improvement from server logs alone. Use a separate `user_perceived` metric backed by `browser_e2e`, `client_marker`, or `manual_observation`. - Do not mix server readiness, API completion, DOM visibility, snapshot visibility, and interactive readiness as the same completion condition. Define them as separate metrics. - Do not treat type-check or a superficially rendered UI as enough when UI code introduces `/api/...` calls. Network Contract Gate requires matching Next.js routes and network-aware flow evidence for API 4xx/5xx. - Do not treat Story-level E2E existence as enough for UI-heavy changes. Clickable-looking controls on the changed screen need an interaction contract: save/mutate, visible state change, navigation, scroll/focus, disabled, or explicit unfinished state. - Do not skip `design-system derive` for existing products that need a reusable DS. Screen-level modernization should not invent product semantics when current routes, CTAs, states, style tokens, or Graphify evidence can define them. - Do not treat `.vibepro/design-system//design-system.json` as complete unless `evidence-coverage.json` and `ds-gate.json` are reviewed. Missing Graphify/style evidence may be a warning; missing semantic roles or implicit fallback is a design gate problem. - Do not implement a generated design proposal directly. For UI modernization, first verify the current route, information architecture, CTA priority, state behavior, and data dependencies against the Derived Design System and `ds-gate.json`. - Do not let `ds-gate.json` fall back implicitly. If DS drift, component role, composition, visual hypothesis, or anti-pattern clauses are missing, treat the design-modernize evidence as incomplete. ## Git / Worktree Dirty Guardrails - Do not use `git stash`, `git restore`, `git reset`, or checkout changes as the first response to a dirty repository worktree. First classify the dirty state. - Before cleaning dirty state, record: - `git status --short --branch` - `git diff --name-status` - `git diff --cached --name-status` - `git diff --stat` - `git diff --cached --stat` - `git reflog --date=iso -8 HEAD` - `git reflog --date=iso -8 ` - If a checked-out branch moved via an external sync, merge, rebase, or another worktree, verify whether the dirty diff is a stale reverse diff before treating it as user work. - A stale reverse diff is likely when the branch reflog advanced from an old commit to `HEAD`, while `git diff --cached` or `git diff` is exactly the inverse of the commits between that old commit and `HEAD`. - Prove this before cleanup by comparing the dirty diff with the commit range, for example: - `git diff --stat HEAD` - `git diff --stat HEAD ` - `git diff --name-status HEAD` - `git diff --name-status HEAD ` - If the dirty state is a proven stale reverse diff, say so explicitly and then synchronize the worktree/index to `HEAD` with the least destructive command that resolves the observed state. Do not preserve it as a stash unless the user asks for archival. - If the dirty state contains files or hunks that do not match the stale reverse diff, treat them as possible user work and do not clean them without reporting the exact files and asking for direction when needed. ## Common Rationalizations - "The code looks done, so VibePro can be skipped." Reject this; VibePro readiness is based on Story/Spec/Architecture, verification evidence, Agent Review, and Gate DAG status. - "The change is small, so no Story or evidence is needed." Small changes can still affect contracts, generated artifacts, and review gates. - "Tests passed once, so PR readiness is proven." Tests must be current-head evidence and still need the relevant VibePro gates to close. - "Manual review is enough for Agent Review Gate." Required Agent Review needs Codex/Claude Code parallel subagent provenance and closed lifecycle evidence unless a waiver is explicitly recorded outside the gate. - "The PR body says it is verified." PR body text is not the source of truth; inspect `pr-prepare.json`, `decision-index.json`, `evidence-plan.json`, Gate DAG evidence, and verification artifacts. ## Red Flags - `gate_status.ready_for_pr_create` is false or missing. - `gate:agent_review`, `gate:artifact_consistency`, `gate:definition_of_done`, `gate:network_contract`, `gate:e2e`, or any critical required gate is unresolved. - The answer cites HTML artifacts but not their JSON sidecars. - Verification evidence predates the current git head or omits the changed path. - Agent Review records have `manual_review` provenance where the gate required parallel subagents. - Dirty worktree files are cleaned or hidden before they are classified. ## Verification Before saying VibePro confirmed the work, name the exact VibePro command or artifact inspected, including `.vibepro/pr//pr-prepare.json` and the relevant Gate DAG node. For implementation work, rerun `vibepro pr prepare` after verification evidence and review records are updated, then confirm `gate_status.ready_for_pr_create=true` and `overall_status=ready_for_review`. ## Key Artifacts - `.vibepro/stories/story-map.md`: repo Story map for human review. - `.vibepro/stories/story-plan.md`: candidate work items. - `.vibepro/pr//pr-prepare.json`: PR readiness source of truth; check `gate_status`. - `.vibepro/pr//decision-index.json`: compact index of Story, decisions, review path, and evidence references. - `.vibepro/pr//evidence-plan.json`: evidence-depth policy, generated artifacts, skipped artifacts, and required follow-up evidence. - `.vibepro/pr//verification-evidence.json`: current-head verification commands and imported CI evidence. - `.vibepro/pr//pr-body.md`: concise GitHub decision brief; not the full audit log. - `.vibepro/pr//review-cockpit.html`: first screen for human decision when generated. - `.vibepro/pr//human-review.json`: machine-readable human decision template. - `.vibepro/pr//gate-dag.json`: Gate dependency evidence. `gate-dag.html` is an optional view. - `.vibepro/pr//split-plan.json`: split lanes and Graphify investigation scope. `split-plan.html` is an optional view. - `.vibepro/pr//pr-create.json`: PR create or existing-PR refresh lifecycle evidence. - `.vibepro/pr//pr-merge.json`: merge lifecycle evidence from `vibepro execute merge`. - `docs/management/audit-artifacts//`: canonical persisted audit artifacts written at merge time. - `.vibepro/uiux//`: uiux intake, map, evidence, and prepare artifacts for intent-first UI/UX work. - `.vibepro/reviews///parallel-dispatch.md`: required parallel subagent dispatch instructions when Agent Review Gate is unresolved. - `.vibepro/adjudication//adjudication.json` / `judgment-adjudication.json`: head-bound adjudication verdicts for AC clauses and judgment items; `adjudication-request.md` / `judgment-adjudication-request.md` are the subagent dispatch requests. - `.vibepro/guard/bypass-log.jsonl`: audit log of Release Surface Guard bypasses. - `.vibepro/checks///check.json`: purpose-level diagnosis package evidence. - `.vibepro/checks///check.md`: human-readable diagnosis package report. - `.vibepro/checks/ui//check.json`: UI check evidence, including `flow_design.interactive_contract_hits`. - `.vibepro/pr//performance-runs/*.json`: Story-level performance evidence runs. - `.vibepro/design-system//design-system.json`: product-local Design System derived from current evidence. - `.vibepro/design-system//evidence-coverage.json`: route/style/Graphify/semantic coverage findings for the native DS. - `.vibepro/design-system//ds-gate.json`: explicit DS gate with fallback disabled. - `.vibepro/design-system//implementation-mapping.json`: route/component/file mapping for implementation handoff. - `.vibepro/design-modernize//design-system-derivation.json`: product semantics and Derived Design System derivation. - `.vibepro/design-modernize//derived-design-system.json`: semantic tokens, component roles, CTA hierarchy, anti-patterns, and visual hypothesis policy. - `.vibepro/design-modernize//design-modernize.json`: screen modernization plan and Design Quality DAG. - `.vibepro/design-modernize//ds-gate.json`: explicit DS drift and UX regression gate clauses.