Software engineering
governance engine

sequenceDiagram
    participant Dev as 👤 Developer
    participant CLI as ⚡ vibe CLI
    participant Gov as 🛡️ Governance Engine
    participant AI as 🤖 Claude
    participant FS as 📁 Filesystem

    rect rgb(30, 30, 33)
    Note over Dev,FS: Phase 1 — Initialize Governance Framework
    Dev->>CLI: vibe init
    CLI->>Gov: Generate 59 YAML policies
    Gov-->>FS: .vibe/policies/*.yaml
    CLI->>AI: Generate CLAUDE.md (stack-aware)
    AI-->>FS: CLAUDE.md
    CLI->>FS: .claude/commands/ (auto-skills)
    CLI->>FS: .claude/settings.json
    CLI->>FS: docs/adr/000-template.md
    CLI-->>Dev: ✅ Framework ready
    end

    rect rgb(30, 30, 33)
    Note over Dev,FS: Phase 2 — Build with Governance
    Dev->>CLI: vibe build
    CLI->>Dev: Describe your idea
    Dev-->>CLI: "A pet health tracker..."
    CLI->>AI: Enrich idea → Personas, Features, Architecture
    AI-->>CLI: EnrichmentBrief
    CLI->>Dev: Review enrichment
    Dev-->>CLI: Approve ✅
    CLI->>AI: Build project (CLAUDE.md + Brief + ADR as context)
    AI-->>FS: Complete project with governance
    CLI-->>Dev: ✅ Project built
    end

    rect rgb(30, 30, 33)
    Note over Dev,FS: Phase 3 — Anchor & Audit
    Dev->>CLI: vibe anchor "auth"
    CLI-->>FS: docs/context/auth.md (decisions, constraints, state)
    Dev->>CLI: vibe audit
    CLI->>Gov: Check 59 policies against project
    Gov-->>CLI: 10-category scorecard
    CLI-->>Dev: Grade: A+ to F + fix suggestions
    end
      

flowchart LR
    subgraph INPUT["Input"]
        idea["💡 Idea"]
        project["📂 Existing Project"]
        feature["🔧 Feature Name"]
    end

    subgraph DETECT["Detection"]
        stack["Stack Detection
Next.js · FastAPI · Go · Node"]
        practice["Practice Detection
Docker · CI · Tests · Lint
Env · Logging · Health
Hooks · Security · Docs"]
    end

    subgraph PROCESS["Processing"]
        enrich["Claude Enrichment
→ Personas
→ P0/P1/P2 Features
→ Architecture"]
        generate["Policy Generation
→ 59 YAML files
→ 10 categories
→ 3 severity levels"]
        score["Health Scoring
→ 17 weighted checks
→ 7 categories
→ A+ through F"]
    end

    subgraph OUTPUT["Output"]
        claudemd["CLAUDE.md
AI Instructions"]
        yaml["YAML Policies
Security · Clean Code
Reliability · 12-Factor
API · Performance
Data · Code Review
Observability · A11y"]
        codebase["Built Codebase
Governed by CLAUDE.md"]
        report["Audit Report
Scorecard + Fix Commands"]
    end

    idea --> enrich
    project --> stack
    project --> practice
    feature --> generate

    stack --> enrich
    practice --> score
    enrich --> codebase
    generate --> yaml
    score --> report
    enrich --> claudemd

      

graph TB
    GOV["🛡️ Governance Engine
59 Policies · 10 Categories"]

    subgraph SEC["Security — 9 policies"]
        s1["sec-001 .gitignore"]
        s2["sec-002 No secrets"]
        s3["sec-003 Env validation"]
        s4["sec-004 Input validation"]
        s5["sec-005 ORM usage"]
    end

    subgraph CC["Clean Code — 10 policies"]
        c1["cc-001 TS strict"]
        c2["cc-002 No any"]
        c3["cc-003 Linter"]
        c4["cc-004 Formatter"]
        c5["cc-005 Git hooks"]
    end

    subgraph REL["Reliability — 8 policies"]
        r1["rel-001 Health endpoint"]
        r2["rel-002 CI/CD"]
        r3["rel-003 Tests"]
        r4["rel-004 Graceful shutdown"]
    end

    subgraph API["API Governance — 5 policies"]
        a1["api-001 OpenAPI spec"]
        a2["api-002 Versioning"]
        a3["api-003 Rate limiting"]
    end

    subgraph TF["12-Factor — 7 policies"]
        t1["12f-001 VCS"]
        t2["12f-002 Deps"]
        t3["12f-003 Config in env"]
    end

    subgraph OTHER["+ 5 More Categories"]
        o1["Code Review — 6"]
        o2["Performance — 4"]
        o3["Data Governance — 4"]
        o4["Observability — 4"]
        o5["Accessibility — 2"]
    end

    GOV --> SEC
    GOV --> CC
    GOV --> REL
    GOV --> API
    GOV --> TF
    GOV --> OTHER