From vibeflow
Validates a proposed software architecture against domain policies, the approved PRD, and (optionally) the current codebase's import graph. Writes .vibeflow/reports/architecture-report.md and one .vibeflow/reports/adr-NNN-<slug>.md per accepted decision. Blocks advance if any criticalPolicyViolations > 0. PIPELINE-1 step 2.
How this skill is triggered — by the user, by Claude, or both
Slash command
/vibeflow:architecture-validatorThis skill is limited to the following tools:
The summary Claude sees in its skill listing — used to decide when to auto-load this skill
You are the second gate in VibeFlow's PIPELINE-1 (New Feature Development).
You are the second gate in VibeFlow's PIPELINE-1 (New Feature Development). Your job is to produce a deterministic, explainable verdict on a proposed architecture before Planning starts spending effort on it.
Invoked automatically during /vibeflow:advance from DESIGN → ARCHITECTURE.
Also callable on demand as /vibeflow:architecture-validator.
| Input | Required | Source |
|---|---|---|
| Architecture description | yes | Path arg, or .vibeflow/artifacts/architecture.md |
| PRD quality report | yes | .vibeflow/reports/prd-quality-report.md (from prd-quality-analyzer) |
| Domain config | yes | vibeflow.config.json → domain |
| Risk tolerance | yes | vibeflow.config.json → riskTolerance |
| Existing import graph | optional | ci_dependency_graph tool on codebase-intel MCP |
| Prior ADRs | optional | .vibeflow/artifacts/adr/*.md |
Hard preconditions (refuse to run with a clear error instead of inventing findings):
vibeflow.config.json must declare a domain from
{ financial | e-commerce | healthcare | general }.If any precondition fails, emit a single finding with impact: blocks merge
and stop.
Read ./references/policy-catalog.md. It groups policies into:
Parse the architecture description and enumerate:
Normalize each claim into a canonical shape so policies can be evaluated uniformly:
{
"id": "claim-<slug>",
"type": "component|flow|tech|decision",
"summary": "one-sentence description",
"evidence": ["file:line refs to the source material"]
}
For each policy in the catalog that applies to the project's domain:
soft warning by default
but escalates to blocks merge for critical financial/healthcare
policies (flagged in the catalog).Findings must include a confidence score (0..1): HIGH for explicit
textual evidence, MEDIUM for implication-by-layer, LOW for heuristic
matches. If you cannot score a confidence, mark the finding as
confidence: 0.0 and explain why — never guess.
If codebase-intel MCP is available and the project is brownfield:
ci_dependency_graph with { root: ".", detectCycles: true }.blocks merge finding, citing the exact from → to edge.blocks merge finding. Cycles are never
OK at the architecture layer — fix them or record an explicit ADR
accepting the tradeoff with a mitigation plan.If codebase-intel is unavailable (greenfield, MCP not loaded), record
this as a limitation in the report — do not silently skip the check.
For every new decision detected in the architecture description that
isn't already covered by an existing ADR, draft a new ADR using
./references/adr-template.md. Number ADRs monotonically:
.vibeflow/artifacts/adr/ADR-000N-<slug>.md.
Do not create an ADR for a decision whose status is "rejected" in the report — those belong in the report body, not the ADR archive.
criticalPolicyViolations = findings.filter(f.impact == "blocks merge").length
softWarnings = findings.filter(f.impact == "soft warning").length
informational = findings.filter(f.impact == "informational").length
Verdict rules:
| Condition | Verdict |
|---|---|
criticalPolicyViolations == 0 && softWarnings <= allowedFor(riskTolerance) | APPROVED |
criticalPolicyViolations == 0 && softWarnings > allowedFor(riskTolerance) | NEEDS_REVISION |
criticalPolicyViolations > 0 | BLOCKED |
allowedFor(risk):
low → 0 (every soft warning must be addressed)medium → 3high → 6The gate contract is criticalPolicyViolations == 0 — no other condition
can produce a BLOCKED verdict, and no condition can suppress BLOCKED.
Every run MUST write all output files below to .vibeflow/reports/
on disk. Never print them to chat only. Create the directory if it
doesn't exist.
.vibeflow/reports/architecture-report.md# Architecture Validation Report
## Summary
- Verdict: [APPROVED|NEEDS_REVISION|BLOCKED]
- Domain: <financial|e-commerce|healthcare|general>
- Risk tolerance: <low|medium|high>
- criticalPolicyViolations: N
- softWarnings: M
- informational: K
- Policies evaluated: X (of Y applicable)
- Brownfield codebase cross-check: [done | skipped: reason]
## Critical Policy Violations (must fix)
For each:
- **finding**: <one-liner>
- **why**: <what rule is broken + catalog reference>
- **impact**: <what breaks if ignored; quantify where possible>
- **confidence**: <0.0..1.0>
- **evidence**: <file:line or graph edge>
- **mitigation**: <concrete fix, not "improve architecture">
## Soft Warnings
<same shape, lower severity>
## Informational
<same shape>
## New Architecture Decisions
- ADR-000N: <title> — <approved|rejected|pending>
- See `.vibeflow/artifacts/adr/ADR-000N-<slug>.md`
## Codebase Cross-Check
- Edges evaluated: N
- Forbidden crossings: M (listed below)
- Cycles: K (listed below)
- Limitation notes: <e.g. "ci_dependency_graph not available — only the document-level policy checks ran">
## Next Steps
### If APPROVED
- Proceed to `/vibeflow:advance` DESIGN → ARCHITECTURE
- Execute planned ADRs in the sprint planning phase
### If NEEDS_REVISION
- Address each soft warning above that exceeds the risk-tolerance budget
- Re-run `/vibeflow:architecture-validator`
### If BLOCKED
- Each `blocks merge` finding must be resolved in the architecture
description OR an explicit ADR accepting the tradeoff
- The gate contract is `criticalPolicyViolations == 0`
.vibeflow/artifacts/adr/ADR-000N-<slug>.md (one file per new ADR)Use the template at ./references/adr-template.md. Never rewrite an
existing ADR — if a decision changes, create a new ADR that supersedes
the old one and link both ways.
Every finding — violation, warning, or informational — MUST carry:
finding: one-line descriptionwhy: which policy + catalog referenceimpact: what fails in production if this stays brokenconfidence: 0..1, justified by the source materialevidence: pointer back to architecture description or graph edgeDo not invent findings. Do not grade on vibes. If you cannot cite evidence, you cannot record a finding.
This skill's output feeds:
test-strategy-planner — architecture claims become scenario seedstraceability-engine — ADRs become traceability anchorsrelease-decision-engine — criticalPolicyViolations flows into
the release hard-blocker listAfter the architecture report is written, auto-satisfy the
adr.recorded exit criterion via the sdlc-engine MCP tool — but
only when the verdict is not BLOCKED. A BLOCKED verdict
means policy violations are serious enough that any ADR the
skill produced is unsafe to count as "recorded and accepted"; the
gate correctly stays closed until the violations are resolved.
Read the verdict from the report:
PROJECT_ID="$(vf_config_get '.project')"
VERDICT="$(grep -m1 '^Verdict:' .vibeflow/reports/architecture-report.md \
| awk '{print $2}' | tr -d '[:space:]')"
Then, only if VERDICT != "BLOCKED":
mcp__sdlc-engine__sdlc_satisfy_criterion {
"projectId": "<project id>",
"criterion": "adr.recorded"
}
Emit a one-line confirmation:
Recorded: adr.recorded (verdict=<APPROVED|NEEDS_REVISION>, ADRs under .vibeflow/artifacts/adr/).
On BLOCKED, instead emit a visible advisory naming the violating policy + the ADRs that need revision. Do NOT call the MCP tool.
If the sdlc-engine MCP isn't reachable, fall back to:
sdlc-engine MCP unavailable — satisfy manually:
mcp__sdlc-engine__sdlc_satisfy_criterion {projectId:…, criterion:'adr.recorded'}
The other ARCHITECTURE exit criterion —
consensus.architecture.approved — is the consensus-orchestrator's
responsibility (recorded automatically in Sprint 17.2).
After your output files are written to .vibeflow/reports/, your
final action is to Write the auto-consensus marker at
.vibeflow/state/consensus-needed.json with:
{
"primaryArtifact": "docs/architecture.md",
"evidence": [
".vibeflow/reports/architecture-report.md"
],
"artifact": ".vibeflow/reports/architecture-report.md",
"requiredCommand": "/vibeflow:consensus-orchestrator docs/architecture.md",
"createdAt": "<current UTC ISO-8601 timestamp>",
"createdBy": "architecture-validator"
}
Sprint 16-A's consensus-gate hook blocks every Bash|Write|Edit
tool call while the marker is present, surfacing the
requiredCommand to the operator until they run the orchestrator —
which drains the marker on APPROVED / NEEDS_REVISION / REJECTED
(Sprint 16-B). This is the mandatory layer; the prose invocation
below is best-effort for the main-agent case:
/vibeflow:consensus-orchestrator .vibeflow/reports/architecture-report.md
It triggers the Claude + codex + gemini review and — if verdict is
NEEDS_REVISION — auto-chains /vibeflow:consensus-arbiter for
diff-first patches.
Skip condition (only one): if VF_SKIP_AUTO_CONSENSUS=1 is set,
do NOT write the marker. Log "auto-consensus skipped by env
(VF_SKIP_AUTO_CONSENSUS)" and stop. The phase-gate in sdlc-engine
(Sprint 15-C) still blocks the next /vibeflow:advance until a
fresh consensus record exists — the env bypass is call-scoped,
not phase-scoped.
npx claudepluginhub mytechsonamy/vibeflow --plugin vibeflowProvides behavioral guidelines to reduce common LLM coding mistakes, focusing on simplicity, surgical changes, assumption surfacing, and verifiable success criteria.
Searches, retrieves, and installs Agent Skills from prompts.chat registry using MCP tools like search_skills and get_skill. Activates for finding skills, browsing catalogs, or extending Claude.
Creates, edits, and optimizes skills for Claude Code, including drafting, evaluating with test prompts, iterating on performance, and improving skill descriptions for better triggering accuracy.