# abyakod/vibe-coding-harness architecture

> Architecture diagram of the GitHub repository abyakod/vibe-coding-harness, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/abyakod/vibe-coding-harness
- Repository: https://github.com/abyakod/vibe-coding-harness

## Overview

This repository is a BKM reference for engineering AI-assisted software, illustrated by a URL-shortener demo. Its principal workflow is to define a spec, provide durable context, design validation before implementation, build from structured prompts, run the test harness, then request semantic review. The README documents that sequence and the demo’s capabilities; sampled code confirms the engineered shortener’s SQLite behavior and the judge’s review flow. The dashboard is a separate interactive, partly simulated presentation. Some capability links reflect documented guidance rather than inspected implementations.

Main entry points: [`SKILL.md`](https://github.com/abyakod/vibe-coding-harness/blob/main/SKILL.md) (Skill Manifest), [`demo_app/engineered/app.py`](https://github.com/abyakod/vibe-coding-harness/blob/main/demo_app/engineered/app.py) (Engineered Shortener), [`demo_app/llm_judge.py`](https://github.com/abyakod/vibe-coding-harness/blob/main/demo_app/llm_judge.py) (LLM Judge), [`demo_app/engineered/context_spec.md`](https://github.com/abyakod/vibe-coding-harness/blob/main/demo_app/engineered/context_spec.md) (Shortener Spec)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_guidance["Engineering Guidance"]
  node_skill_manifest["Skill Manifest<br/>[SKILL.md]"]
  node_planning["Product Planning"]
  node_context["Context Engineering"]
  node_harness_guidance["Harness Engineering"]
  node_prompt_guidance["Prompt Patterns<br/>[prompt_patterns.md]"]
  node_judge_guidance["Judge Guidance<br/>[llm_judge.md]"]
  node_tool_rules["Tool Context Rules<br/>[harness.mdc]"]
  node_copilot_rules["Copilot Instructions"]
end

subgraph group_demo["Shortener Demo"]
  node_context_spec["Shortener Spec<br/>[context_spec.md]"]
  node_engineered_app["Engineered Shortener<br/>[app.py]"]
  node_sqlite[("SQLite Database")]
  node_harness["Test Harness<br/>[test_harness.py]"]
  node_chaos_app["Naive Shortener<br/>[app.py]"]
end

subgraph group_review["Semantic Review"]
  node_judge_script["LLM Judge<br/>[llm_judge.py]"]
  node_anthropic{{"Anthropic API"}}
end

subgraph group_dashboard["Comparison Dashboard"]
  node_dashboard_page["Dashboard Page<br/>[index.html]"]
  node_dashboard_logic["Dashboard Logic<br/>[app.js]"]
end

node_engineer(("Engineer"))
node_dashboard_user(("Dashboard Visitor"))

node_engineer -->|"loads"| node_skill_manifest
node_skill_manifest -->|"lists"| node_planning
node_skill_manifest -->|"lists"| node_context
node_skill_manifest -->|"lists"| node_harness_guidance
node_skill_manifest -->|"lists"| node_prompt_guidance
node_skill_manifest -->|"lists"| node_judge_guidance
node_planning -->|"defines spec"| node_context_spec
node_context -->|"provides context"| node_context_spec
node_harness_guidance -->|"guides design"| node_harness
node_prompt_guidance -->|"guides implementation"| node_engineered_app
node_context_spec -->|"specifies behavior"| node_engineered_app
node_engineered_app -->|"reads and writes"| node_sqlite
node_harness -->|"validates"| node_engineered_app
node_chaos_app -.->|"comparison content"| node_dashboard_logic
node_engineered_app -.->|"demo output"| node_dashboard_logic
node_engineer -->|"runs review"| node_judge_script
node_judge_script -->|"reads code"| node_engineered_app
node_judge_script -->|"reads spec"| node_context_spec
node_judge_script -.->|"requests review"| node_anthropic
node_judge_guidance -->|"guides review"| node_judge_script
node_dashboard_user -->|"opens"| node_dashboard_page
node_dashboard_page -->|"loads"| node_dashboard_logic
node_dashboard_user -->|"interacts"| node_dashboard_logic
node_tool_rules -->|"guides sessions"| node_engineer
node_copilot_rules -->|"guides sessions"| node_engineer

click node_skill_manifest "https://github.com/abyakod/vibe-coding-harness/blob/main/SKILL.md"
click node_planning "https://github.com/abyakod/vibe-coding-harness/blob/main/skills/product_planning.md"
click node_context "https://github.com/abyakod/vibe-coding-harness/blob/main/skills/context_engineering.md"
click node_harness_guidance "https://github.com/abyakod/vibe-coding-harness/blob/main/skills/harness_engineering.md"
click node_prompt_guidance "https://github.com/abyakod/vibe-coding-harness/blob/main/skills/prompt_patterns.md"
click node_judge_guidance "https://github.com/abyakod/vibe-coding-harness/blob/main/skills/llm_judge.md"
click node_tool_rules "https://github.com/abyakod/vibe-coding-harness/blob/main/.cursor/rules/harness.mdc"
click node_copilot_rules "https://github.com/abyakod/vibe-coding-harness/blob/main/.github/copilot-instructions.md"
click node_context_spec "https://github.com/abyakod/vibe-coding-harness/blob/main/demo_app/engineered/context_spec.md"
click node_engineered_app "https://github.com/abyakod/vibe-coding-harness/blob/main/demo_app/engineered/app.py"
click node_harness "https://github.com/abyakod/vibe-coding-harness/blob/main/demo_app/engineered/test_harness.py"
click node_chaos_app "https://github.com/abyakod/vibe-coding-harness/blob/main/demo_app/chaos/app.py"
click node_judge_script "https://github.com/abyakod/vibe-coding-harness/blob/main/demo_app/llm_judge.py"
click node_dashboard_page "https://github.com/abyakod/vibe-coding-harness/blob/main/demo_app/web/index.html"
click node_dashboard_logic "https://github.com/abyakod/vibe-coding-harness/blob/main/demo_app/web/app.js"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_skill_manifest,node_planning,node_context,node_harness_guidance,node_prompt_guidance,node_judge_guidance,node_tool_rules,node_copilot_rules toneBlue
class node_context_spec,node_engineered_app,node_sqlite,node_harness,node_chaos_app toneAmber
class node_judge_script,node_anthropic toneMint
class node_dashboard_page,node_dashboard_logic toneRose
class node_engineer,node_dashboard_user toneIndigo
```

## Components

### Engineering Guidance

- [Skill Manifest](https://github.com/abyakod/vibe-coding-harness/blob/main/SKILL.md): `SKILL.md`
- [Product Planning](https://github.com/abyakod/vibe-coding-harness/blob/main/skills/product_planning.md): `skills/product_planning.md`
- [Context Engineering](https://github.com/abyakod/vibe-coding-harness/blob/main/skills/context_engineering.md): `skills/context_engineering.md`
- [Harness Engineering](https://github.com/abyakod/vibe-coding-harness/blob/main/skills/harness_engineering.md): `skills/harness_engineering.md`
- [Prompt Patterns](https://github.com/abyakod/vibe-coding-harness/blob/main/skills/prompt_patterns.md): `skills/prompt_patterns.md`
- [Judge Guidance](https://github.com/abyakod/vibe-coding-harness/blob/main/skills/llm_judge.md): `skills/llm_judge.md`
- [Tool Context Rules](https://github.com/abyakod/vibe-coding-harness/blob/main/.cursor/rules/harness.mdc): `.cursor/rules/harness.mdc`
- [Copilot Instructions](https://github.com/abyakod/vibe-coding-harness/blob/main/.github/copilot-instructions.md): `.github/copilot-instructions.md`

### Shortener Demo

- [Shortener Spec](https://github.com/abyakod/vibe-coding-harness/blob/main/demo_app/engineered/context_spec.md): `demo_app/engineered/context_spec.md`
- [Engineered Shortener](https://github.com/abyakod/vibe-coding-harness/blob/main/demo_app/engineered/app.py): `demo_app/engineered/app.py`
- **SQLite Database**
- [Test Harness](https://github.com/abyakod/vibe-coding-harness/blob/main/demo_app/engineered/test_harness.py): `demo_app/engineered/test_harness.py`
- [Naive Shortener](https://github.com/abyakod/vibe-coding-harness/blob/main/demo_app/chaos/app.py): `demo_app/chaos/app.py`

### Semantic Review

- [LLM Judge](https://github.com/abyakod/vibe-coding-harness/blob/main/demo_app/llm_judge.py): `demo_app/llm_judge.py`
- **Anthropic API**

### Comparison Dashboard

- [Dashboard Page](https://github.com/abyakod/vibe-coding-harness/blob/main/demo_app/web/index.html): `demo_app/web/index.html`
- [Dashboard Logic](https://github.com/abyakod/vibe-coding-harness/blob/main/demo_app/web/app.js): `demo_app/web/app.js`

### Other components

- **Engineer**
- **Dashboard Visitor**

## Connections

- Engineer → Skill Manifest: loads
- Skill Manifest → Product Planning: lists
- Skill Manifest → Context Engineering: lists
- Skill Manifest → Harness Engineering: lists
- Skill Manifest → Prompt Patterns: lists
- Skill Manifest → Judge Guidance: lists
- Product Planning → Shortener Spec: defines spec
- Context Engineering → Shortener Spec: provides context
- Harness Engineering → Test Harness: guides design
- Prompt Patterns → Engineered Shortener: guides implementation
- Shortener Spec → Engineered Shortener: specifies behavior
- Engineered Shortener → SQLite Database: reads and writes
- Test Harness → Engineered Shortener: validates
- Naive Shortener → Dashboard Logic: comparison content
- Engineered Shortener → Dashboard Logic: demo output
- Engineer → LLM Judge: runs review
- LLM Judge → Engineered Shortener: reads code
- LLM Judge → Shortener Spec: reads spec
- LLM Judge → Anthropic API: requests review
- Judge Guidance → LLM Judge: guides review
- Dashboard Visitor → Dashboard Page: opens
- Dashboard Page → Dashboard Logic: loads
- Dashboard Visitor → Dashboard Logic: interacts
- Tool Context Rules → Engineer: guides sessions
- Copilot Instructions → Engineer: guides sessions