How karim-bhalwani/agentic-harness works
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 Skills · prompts Prompts · ARCHITECTURE.md Architecture · instructions Instructions
Components 25
Docs
Operating model and adoption guidance
- README · Frames the repo’s operating model and install flow
README.md - Architecture · Explains the layered control-plane design
ARCHITECTURE.md - Principles · Baseline conventions and system rules
CORE_PRINCIPLES.md - Adoption · Solo, team, and operational usage guides
SOLO-ADOPTION-GUIDE.md
Prompts
Slash commands and agent personas
- Prompts · Slash commands and agent personas that start workflows
prompts - Discover→Plan · Early-phase agents for discovery, architecture, and planning
prompts/brownfield-discovery.agent.md - Build→Ship · Implementation, review, release, and closure agents
prompts/ai-engineer.agent.md - Task prompts · Focused commands for design, debugging, mem, release, and data work
prompts/design.prompt.md
Skills
Reusable on-demand knowledge packs
- Skills · On-demand domain knowledge and repeatable workflows
skills - Routing · Selects the right workflow and stage for a task
skills/task-routing/SKILL.md - Architect · Defines specs, contracts, and artifact scaffolding
skills/architect/SKILL.md - Guardian · Review, calibration, and quality assessment workflows
skills/guardian/SKILL.md - Context Eng. · Session state, compaction, and context management
skills/context-engineer/SKILL.md - Data skills · Data engineering, analysis, science, and narrative workflows
skills/data-engineering/SKILL.md - Security · LLM and prompt-injection security guidance
skills/genai-security/SKILL.md
Instructions
Always-on behavior and format rules
- Instructions · Global behavior, formatting, and commit standards
instructions - Core behavior · Always-applied baseline conduct and output expectations
instructions/core-behavior.instructions.md - Format stds · Language-specific and document-format standards
instructions/markdown-standards.instructions.md - Commit stds · Commit message and source-control standards
instructions/git-commit-standards.instructions.md
Hooks
Policy enforcement and session/file guards
- Hooks · PowerShell checks that block or gate risky actions
hooks - Guard hooks · Destructive-action blocking, secret scanning, holdout rules
hooks/block-destructive.ps1 - Quality hooks · Linting, quality gates, retrospectives, and write-time validation
hooks/lint-on-write.ps1 - Session hooks · Session context, subagent context, compact-save, and verification
hooks/session-context.ps1
Runtime
External Copilot and local execution environment
- Install · Copies repo assets into Copilot user-scoped directories
hooks/INSTALL.md - Copilot+VS Code · External environment where prompts, skills, instructions, and hooks take effect
Connections 29
- 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