# karim-bhalwani/agentic-harness architecture

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

- Interactive diagram: https://gitdiagram.com/karim-bhalwani/agentic-harness
- Repository: https://github.com/karim-bhalwani/agentic-harness

## Overview

1. **What this repo is**
   - This is not an application runtime; it is a **Copilot workspace extension pack** for VS Code.
   - The repo defines four main artifact types: **agents/prompts**, **skills**, **instructions**, and **hooks**.
   - The architecture is intentionally layered: **global rules** at the bottom, **specialized workflows** above that, and **platform enforcement** around the edges.

2. **Primary execution environment**
   - The target runtime is **VS Code with GitHub Copilot**.
   - Most content is delivered as Markdown configuration files that Copilot consumes directly from user profile locations.
   - The only executable components are mostly **Python 3.11+ scripts** and **PowerShell hooks**, so this repo behaves more like a toolchain than a service.

3. **Agent and prompt layer**
   - `prompts/` contains the **16+ slash-command prompts** used to kick off specific workflows such as design, review, planning, debugging, and release tasks.
   - `prompts/*.agent.md` define **specialized agent personas** that collaborate in a fixed pipeline: discover → design → plan → build → review → ship.
   - This layer is the human-facing entry point; it routes work into the right phase and constrains the model to a role.

4. **Skill library layer**
   - `skills/` is the main knowledge subsystem, with **26 on-demand skill packs**.
   - Each skill has a `SKILL.md` and often a `references/` directory plus helper scripts.
   - Skills are domain-specific modules for things like data engineering, guardian/review, prompt library, LLM security, context engineering, story management, and verification.

5. **Global instruction layer**
   - `instructions/` contains the always-on policy layer: core behavior, language/format standards, and commit standards.
   - These files are auto-applied across sessions, so they act as the repo’s **baseline contract** for output style and safe behavior.
   - The instruction files are the “static guardrails,” while prompts and skills are the “task-specific playbooks.”

6. **Hook enforcement layer**
   - `hooks/` contains **14 PowerShell hooks** that enforce invariants Copilot instructions cannot guarantee.
   - Examples of responsibilities visible in the tree include: blocking destructive actions, scanning secrets, linting on write, quality gating, context/session handling, and subagent verification.
   - This is the repo’s policy enforcement boundary: it intercepts assistant actions at session or file-operation time.

7. **Data and control flow**
   - A typical flow is: user invokes a prompt or agent in VS Code → Copilot loads global instructions → relevant skill content is pulled in on demand → hooks validate or block risky actions.
   - Generated artifacts then pass through write-time or pre-compact checks, and final outputs can be reviewed by guardian/review-oriented skills and hooks.
   - The repo is designed so **knowledge is lazy-loaded**, while **safety checks are always-on**.

8. **Validation and scaffolding scripts**
   - Many skills include small Python utilities under `skills/*/scripts/` for verification, scaffolding, or report generation.
   - These scripts support repeatable artifact creation such as mem scaffolds, spec scaffolds, story scaffolds, review reports, or schema validation.
   - They are support tooling, not a separate product layer, but they matter because they encode the repo’s repeatable workflow mechanics.

9. **Documentation and operating model**
   - The root docs (`ARCHITECTURE.md`, `CORE_PRINCIPLES.md`, `USER-GUIDE.md`, `MEGA-MINIONS.md`, adoption guides, etc.) explain how to use the system and how the pieces fit together.
   - `README.md` frames the operating model clearly: **spec before code**, **one agent per phase**, and **hooks enforce what instructions can’t**.
   - The docs are part of the architecture because they define the contract for adopting and operating the system.

10. **Deployment/installation boundary**
   - Installation copies the repo’s content into Copilot’s user-scoped directories: prompts, instructions, skills, and hooks are installed separately.
   - That means the repo itself is a **source of truth**, while the actual runtime assets live in the user’s VS Code/Copilot environment.
   - On the platform side, the repo assumes **Windows + PowerShell** for hook installation and **UV/Python** for script execution support.

11. **Key architectural boundary**
   - The strongest boundary is between **model behavior shaping** and **policy enforcement**.
   - Prompts, agents, and instructions shape what the model tries to do; hooks decide what is allowed to happen.
   - This separation is central to the architecture and is the main thing to show in a diagram.

12. **Overall system shape**
   - In diagram terms, this repo is best represented as a **Copilot control plane**: documentation at the top, reusable knowledge packs in the middle, and enforcement hooks at the bottom.
   - The external dependency is GitHub Copilot in VS Code; the repo’s output is behavior inside that environment, not a standalone server or app.

Main entry points: [`skills`](https://github.com/karim-bhalwani/agentic-harness/tree/main/skills) (Skills), [`prompts`](https://github.com/karim-bhalwani/agentic-harness/tree/main/prompts) (Prompts), [`ARCHITECTURE.md`](https://github.com/karim-bhalwani/agentic-harness/blob/main/ARCHITECTURE.md) (Architecture), [`instructions`](https://github.com/karim-bhalwani/agentic-harness/tree/main/instructions) (Instructions)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_g_docs["Docs"]
  node_n_readme["README<br/>overview doc<br/>[README.md]"]
  node_n_architecture["Architecture<br/>[ARCHITECTURE.md]"]
  node_n_principles["Principles<br/>policy doc<br/>[CORE_PRINCIPLES.md]"]
  node_n_adoption["Adoption<br/>guides"]
end

subgraph group_g_prompts["Prompts"]
  node_n_prompts_layer["Prompts<br/>copilot entrypoints"]
  node_n_discover_design_plan(("Discover→Plan<br/>agent pipeline"))
  node_n_build_review_ship(("Build→Ship<br/>agent pipeline"))
  node_n_task_prompts(("Task prompts<br/>workflow prompts<br/>[design.prompt.md]"))
end

subgraph group_g_skills["Skills"]
  node_n_skills_layer["Skills<br/>knowledge packs"]
  node_n_task_routing["Routing<br/>coordination skill<br/>[SKILL.md]"]
  node_n_architect_skill["Architect<br/>spec skill<br/>[SKILL.md]"]
  node_n_guardian_skill["Guardian<br/>review skill<br/>[SKILL.md]"]
  node_n_context_skill["Context Eng.<br/>session skill<br/>[SKILL.md]"]
  node_n_data_skills["Data skills<br/>domain bundle<br/>[SKILL.md]"]
  node_n_security_skills["Security<br/>risk skill<br/>[SKILL.md]"]
end

subgraph group_g_instructions["Instructions"]
  node_n_instructions_layer["Instructions<br/>always-on policy"]
  node_n_core_instruction["Core behavior<br/>policy rule"]
  node_n_format_standards["Format stds<br/>style rules"]
  node_n_commit_standards["Commit stds<br/>git policy"]
end

subgraph group_g_hooks["Hooks"]
  node_n_hooks_layer["Hooks<br/>enforcement boundary"]
  node_n_guard_hooks["Guard hooks<br/>safety checks"]
  node_n_quality_hooks["Quality hooks<br/>gates<br/>[lint-on-write.ps1]"]
  node_n_session_hooks["Session hooks<br/>context guards"]
end

subgraph group_g_runtime["Runtime"]
  node_n_install["Install<br/>deployment scripts<br/>[INSTALL.md]"]
  node_n_copilot_vs_code(("Copilot+VS Code<br/>target runtime"))
end

node_n_readme -->|"explains"| node_n_architecture
node_n_readme -->|"guides setup"| node_n_install
node_n_architecture -->|"layers"| node_n_prompts_layer
node_n_architecture -->|"layers"| node_n_skills_layer
node_n_architecture -->|"layers"| node_n_instructions_layer
node_n_architecture -->|"layers"| node_n_hooks_layer
node_n_prompts_layer -->|"starts"| node_n_discover_design_plan
node_n_prompts_layer -->|"starts"| node_n_build_review_ship
node_n_prompts_layer -->|"includes"| node_n_task_prompts
node_n_task_routing -->|"routes"| node_n_prompts_layer
node_n_skills_layer -->|"contains"| node_n_architect_skill
node_n_skills_layer -->|"contains"| node_n_guardian_skill
node_n_skills_layer -->|"contains"| node_n_context_skill
node_n_skills_layer -->|"contains"| node_n_data_skills
node_n_skills_layer -->|"contains"| node_n_security_skills
node_n_instructions_layer -->|"contains"| node_n_core_instruction
node_n_instructions_layer -->|"contains"| node_n_format_standards
node_n_instructions_layer -->|"contains"| node_n_commit_standards
node_n_hooks_layer -->|"contains"| node_n_guard_hooks
node_n_hooks_layer -->|"contains"| node_n_quality_hooks
node_n_hooks_layer -->|"contains"| node_n_session_hooks
node_n_install -->|"deploys to"| node_n_copilot_vs_code
node_n_prompts_layer -->|"consumed by"| node_n_copilot_vs_code
node_n_instructions_layer -->|"consumed by"| node_n_copilot_vs_code
node_n_skills_layer -->|"pulled on demand"| node_n_copilot_vs_code
node_n_hooks_layer -->|"intercepts"| node_n_copilot_vs_code
node_n_guardian_skill -.->|"reinforces"| node_n_quality_hooks
node_n_context_skill -.->|"aligns with"| node_n_session_hooks
node_n_security_skills -.->|"supports"| node_n_guard_hooks

click node_n_readme "https://github.com/karim-bhalwani/agentic-harness/blob/main/README.md"
click node_n_architecture "https://github.com/karim-bhalwani/agentic-harness/blob/main/ARCHITECTURE.md"
click node_n_principles "https://github.com/karim-bhalwani/agentic-harness/blob/main/CORE_PRINCIPLES.md"
click node_n_adoption "https://github.com/karim-bhalwani/agentic-harness/blob/main/SOLO-ADOPTION-GUIDE.md"
click node_n_prompts_layer "https://github.com/karim-bhalwani/agentic-harness/tree/main/prompts"
click node_n_discover_design_plan "https://github.com/karim-bhalwani/agentic-harness/blob/main/prompts/brownfield-discovery.agent.md"
click node_n_build_review_ship "https://github.com/karim-bhalwani/agentic-harness/blob/main/prompts/ai-engineer.agent.md"
click node_n_task_prompts "https://github.com/karim-bhalwani/agentic-harness/blob/main/prompts/design.prompt.md"
click node_n_skills_layer "https://github.com/karim-bhalwani/agentic-harness/tree/main/skills"
click node_n_task_routing "https://github.com/karim-bhalwani/agentic-harness/blob/main/skills/task-routing/SKILL.md"
click node_n_architect_skill "https://github.com/karim-bhalwani/agentic-harness/blob/main/skills/architect/SKILL.md"
click node_n_guardian_skill "https://github.com/karim-bhalwani/agentic-harness/blob/main/skills/guardian/SKILL.md"
click node_n_context_skill "https://github.com/karim-bhalwani/agentic-harness/blob/main/skills/context-engineer/SKILL.md"
click node_n_data_skills "https://github.com/karim-bhalwani/agentic-harness/blob/main/skills/data-engineering/SKILL.md"
click node_n_security_skills "https://github.com/karim-bhalwani/agentic-harness/blob/main/skills/genai-security/SKILL.md"
click node_n_instructions_layer "https://github.com/karim-bhalwani/agentic-harness/tree/main/instructions"
click node_n_core_instruction "https://github.com/karim-bhalwani/agentic-harness/blob/main/instructions/core-behavior.instructions.md"
click node_n_format_standards "https://github.com/karim-bhalwani/agentic-harness/blob/main/instructions/markdown-standards.instructions.md"
click node_n_commit_standards "https://github.com/karim-bhalwani/agentic-harness/blob/main/instructions/git-commit-standards.instructions.md"
click node_n_hooks_layer "https://github.com/karim-bhalwani/agentic-harness/tree/main/hooks"
click node_n_guard_hooks "https://github.com/karim-bhalwani/agentic-harness/blob/main/hooks/block-destructive.ps1"
click node_n_quality_hooks "https://github.com/karim-bhalwani/agentic-harness/blob/main/hooks/lint-on-write.ps1"
click node_n_session_hooks "https://github.com/karim-bhalwani/agentic-harness/blob/main/hooks/session-context.ps1"
click node_n_install "https://github.com/karim-bhalwani/agentic-harness/blob/main/hooks/INSTALL.md"

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_n_readme,node_n_architecture,node_n_principles,node_n_adoption toneBlue
class node_n_prompts_layer,node_n_discover_design_plan,node_n_build_review_ship,node_n_task_prompts toneAmber
class node_n_skills_layer,node_n_task_routing,node_n_architect_skill,node_n_guardian_skill,node_n_context_skill,node_n_data_skills,node_n_security_skills toneMint
class node_n_instructions_layer,node_n_core_instruction,node_n_format_standards,node_n_commit_standards toneRose
class node_n_hooks_layer,node_n_guard_hooks,node_n_quality_hooks,node_n_session_hooks toneIndigo
class node_n_install,node_n_copilot_vs_code toneTeal
```

## Components

### Docs

Operating model and adoption guidance

- [README](https://github.com/karim-bhalwani/agentic-harness/blob/main/README.md): overview doc · Frames the repo’s operating model and install flow · `README.md`
- [Architecture](https://github.com/karim-bhalwani/agentic-harness/blob/main/ARCHITECTURE.md): architecture doc · Explains the layered control-plane design · `ARCHITECTURE.md`
- [Principles](https://github.com/karim-bhalwani/agentic-harness/blob/main/CORE_PRINCIPLES.md): policy doc · Baseline conventions and system rules · `CORE_PRINCIPLES.md`
- [Adoption](https://github.com/karim-bhalwani/agentic-harness/blob/main/SOLO-ADOPTION-GUIDE.md): guides · Solo, team, and operational usage guides · `SOLO-ADOPTION-GUIDE.md`

### Prompts

Slash commands and agent personas

- [Prompts](https://github.com/karim-bhalwani/agentic-harness/tree/main/prompts): copilot entrypoints · Slash commands and agent personas that start workflows · `prompts`
- [Discover→Plan](https://github.com/karim-bhalwani/agentic-harness/blob/main/prompts/brownfield-discovery.agent.md): agent pipeline · Early-phase agents for discovery, architecture, and planning · `prompts/brownfield-discovery.agent.md`
- [Build→Ship](https://github.com/karim-bhalwani/agentic-harness/blob/main/prompts/ai-engineer.agent.md): agent pipeline · Implementation, review, release, and closure agents · `prompts/ai-engineer.agent.md`
- [Task prompts](https://github.com/karim-bhalwani/agentic-harness/blob/main/prompts/design.prompt.md): workflow prompts · Focused commands for design, debugging, mem, release, and data work · `prompts/design.prompt.md`

### Skills

Reusable on-demand knowledge packs

- [Skills](https://github.com/karim-bhalwani/agentic-harness/tree/main/skills): knowledge packs · On-demand domain knowledge and repeatable workflows · `skills`
- [Routing](https://github.com/karim-bhalwani/agentic-harness/blob/main/skills/task-routing/SKILL.md): coordination skill · Selects the right workflow and stage for a task · `skills/task-routing/SKILL.md`
- [Architect](https://github.com/karim-bhalwani/agentic-harness/blob/main/skills/architect/SKILL.md): spec skill · Defines specs, contracts, and artifact scaffolding · `skills/architect/SKILL.md`
- [Guardian](https://github.com/karim-bhalwani/agentic-harness/blob/main/skills/guardian/SKILL.md): review skill · Review, calibration, and quality assessment workflows · `skills/guardian/SKILL.md`
- [Context Eng.](https://github.com/karim-bhalwani/agentic-harness/blob/main/skills/context-engineer/SKILL.md): session skill · Session state, compaction, and context management · `skills/context-engineer/SKILL.md`
- [Data skills](https://github.com/karim-bhalwani/agentic-harness/blob/main/skills/data-engineering/SKILL.md): domain bundle · Data engineering, analysis, science, and narrative workflows · `skills/data-engineering/SKILL.md`
- [Security](https://github.com/karim-bhalwani/agentic-harness/blob/main/skills/genai-security/SKILL.md): risk skill · LLM and prompt-injection security guidance · `skills/genai-security/SKILL.md`

### Instructions

Always-on behavior and format rules

- [Instructions](https://github.com/karim-bhalwani/agentic-harness/tree/main/instructions): always-on policy · Global behavior, formatting, and commit standards · `instructions`
- [Core behavior](https://github.com/karim-bhalwani/agentic-harness/blob/main/instructions/core-behavior.instructions.md): policy rule · Always-applied baseline conduct and output expectations · `instructions/core-behavior.instructions.md`
- [Format stds](https://github.com/karim-bhalwani/agentic-harness/blob/main/instructions/markdown-standards.instructions.md): style rules · Language-specific and document-format standards · `instructions/markdown-standards.instructions.md`
- [Commit stds](https://github.com/karim-bhalwani/agentic-harness/blob/main/instructions/git-commit-standards.instructions.md): git policy · Commit message and source-control standards · `instructions/git-commit-standards.instructions.md`

### Hooks

Policy enforcement and session/file guards

- [Hooks](https://github.com/karim-bhalwani/agentic-harness/tree/main/hooks): enforcement boundary · PowerShell checks that block or gate risky actions · `hooks`
- [Guard hooks](https://github.com/karim-bhalwani/agentic-harness/blob/main/hooks/block-destructive.ps1): safety checks · Destructive-action blocking, secret scanning, holdout rules · `hooks/block-destructive.ps1`
- [Quality hooks](https://github.com/karim-bhalwani/agentic-harness/blob/main/hooks/lint-on-write.ps1): gates · Linting, quality gates, retrospectives, and write-time validation · `hooks/lint-on-write.ps1`
- [Session hooks](https://github.com/karim-bhalwani/agentic-harness/blob/main/hooks/session-context.ps1): context guards · Session context, subagent context, compact-save, and verification · `hooks/session-context.ps1`

### Runtime

External Copilot and local execution environment

- [Install](https://github.com/karim-bhalwani/agentic-harness/blob/main/hooks/INSTALL.md): deployment scripts · Copies repo assets into Copilot user-scoped directories · `hooks/INSTALL.md`
- **Copilot+VS Code**: target runtime · External environment where prompts, skills, instructions, and hooks take effect

## Connections

- README → Architecture: explains · README points to the layered operating model
- README → Install: guides setup · Repository content is installed into user-scoped runtime locations
- Architecture → Prompts: layers · Architecture positions prompts as the human entry point
- Architecture → Skills: layers · Skills provide reusable knowledge and workflows
- Architecture → Instructions: layers · Instructions form the always-on baseline contract
- Architecture → Hooks: layers · Hooks enforce policy at runtime boundaries
- Prompts → Discover→Plan: starts · Agent personas move work through discover/design/plan phases
- Prompts → Build→Ship: starts · Later agents handle build/review/release/closure phases
- Prompts → Task prompts: includes · Slash-command prompts trigger specific task workflows
- Routing → Prompts: routes · Task routing chooses the right prompt or agent entrypoint
- Skills → Architect: contains · Architect skill scaffolds specs and contracts
- Skills → Guardian: contains · Guardian skill performs calibrated review and QA
- Skills → Context Eng.: contains · Context engineering manages session state and compaction
- Skills → Data skills: contains · Data-focused packs cover analysis, engineering, and science
- Skills → Security: contains · Security packs cover prompt and LLM threat patterns
- Instructions → Core behavior: contains · Core behavior is the main always-on instruction
- Instructions → Format stds: contains · Formatting and language standards are auto-applied
- Instructions → Commit stds: contains · Commit rules shape source-control output
- Hooks → Guard hooks: contains · Blocking and scanning hooks enforce safety policies
- Hooks → Quality hooks: contains · Quality hooks gate writes and workflow outputs
- Hooks → Session hooks: contains · Session hooks manage context and subagent boundaries
- Install → Copilot+VS Code: deploys to · Repo assets are copied into the Copilot runtime
- Prompts → Copilot+VS Code: consumed by · Prompts and agent files are loaded by Copilot
- Instructions → Copilot+VS Code: consumed by · Global instructions shape assistant behavior in the runtime
- Skills → Copilot+VS Code: pulled on demand · Skills are lazy-loaded when workflows need them
- Hooks → Copilot+VS Code: intercepts · Hooks validate or block actions during use
- Guardian → Quality hooks: reinforces · Human-readable review logic complements automated gating
- Context Eng. → Session hooks: aligns with · Context management skills and session hooks coordinate state
- Security → Guard hooks: supports · Security guidance aligns with secret and prompt-injection checks