# neolabhq/context-engineering-kit architecture

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

- Interactive diagram: https://gitdiagram.com/neolabhq/context-engineering-kit
- Repository: https://github.com/neolabhq/context-engineering-kit

## Overview

1. **What this repository is**
   - This is a **plugin marketplace for AI coding assistants**, centered on Claude Code compatibility.
   - The repo is mostly **content/configuration**, not a traditional application: plugins are delivered as markdown prompts, rules, skills, agents, and hooks.

2. **Top-level architectural split**
   - The repository has three major surfaces:
     - **Installable plugins** under `plugins/`
     - **Human-facing documentation** under `docs/`
     - **Internal specs/process artifacts** under `.specs/`
   - That separation is important: the installable assets are what users load into their assistant; the docs explain usage; the specs track ongoing development work.

3. **Plugin packaging model**
   - Each plugin lives in its own folder under `plugins/<name>/` and has a `.claude-plugin/plugin.json` manifest.
   - That manifest is the boundary between repo content and the installer/runtime: it tells the host tool what to install and load.
   - Most plugins are delivered as **Markdown-based skill files** and/or **agent prompts**, with minimal executable code.

4. **Primary plugin types**
   - **Skills-only plugins**: many folders contain `skills/.../SKILL.md`, which encode behavior instructions for the assistant.
   - **Agent-based plugins**: some include `agents/*.md`, defining specialized sub-agent roles for tasks like review, architecture, or research.
   - **Rule-based plugins**: `ddd` and `tech-stack` provide reusable rules that influence generation behavior when relevant files are touched.
   - **Command/workflow plugins**: `sdd`, `sadd`, `git`, `tdd`, `kaizen`, `mcp`, and `customaize-agent` focus on command-driven flows orchestrating multiple steps.

5. **The most code-like subsystem: Reflexion hooks**
   - `plugins/reflexion/hooks/` is the only clear executable subsystem in the repo.
   - It is implemented in **TypeScript** and uses **Bun** tooling (`package.json`, `bun.lockb`, `vitest`).
   - Its job is to act as a runtime hook layer: when certain prompt conditions are met, it triggers reflection behavior and related logic.
   - This makes Reflexion the repo’s main boundary between static prompt content and live execution.

6. **Multi-agent workflow architecture**
   - Several plugins are designed around **sub-agent orchestration** rather than a single prompt:
     - `sadd` coordinates parallel, sequential, competitive, or judge-based agent patterns.
     - `review` fans out to specialized reviewers like bug, security, test coverage, and historical-context agents.
     - `sdd` uses a planning pipeline with distinct roles such as researcher, code-explorer, architect, tech lead, QA, developer, reviewer, and writer.
     - `fpf` introduces an evidence-based hypothesis/verification loop via a dedicated reasoning agent.
   - Architecturally, these plugins are “control planes” for dispatching specialized prompt agents.

7. **Spec-driven development as a workflow system**
   - `plugins/sdd` is the repo’s most structured workflow subsystem.
   - It organizes development into **task files** and **phases** under `.specs/tasks/...`, then produces implementation guidance using multiple agents.
   - The important data flow is: task prompt → spec refinement → implementation plan → execution → verification → archived task.
   - This subsystem also integrates architectural guidance from `ddd`, showing a deliberate dependency between quality rules and implementation planning.

8. **Documentation architecture**
   - `docs/` is a GitBook-style documentation tree with:
     - conceptual docs,
     - getting started material,
     - plugin guides,
     - reference pages,
     - best practices and resource lists.
   - This docs layer mirrors the plugin catalog and acts as the user-facing explanation layer for installation and usage.
   - `docs/SUMMARY.md` and the folder structure indicate a navigation-driven documentation site.

9. **Repository-internal process and governance**
   - `.specs/` contains task drafts, completed task records, research notes, and reports.
   - This is a project-management boundary for how the marketplace itself evolves: feature drafts, work reports, analysis notes, and roadmap items are stored separately from the installable plugins.
   - It suggests the repo is maintained through a spec-and-report workflow, not just ad hoc edits.

10. **Tooling and environment**
   - `.devcontainer/` indicates a containerized development setup.
   - `justfile` provides task automation for contributor workflows.
   - `.cursor/`, `.claude/`, and `.claude-plugin/` files support editor/assistant integration and marketplace metadata.
   - These are enabling layers rather than product runtime components.

11. **Cross-plugin relationships**
   - The plugins are intentionally composable and non-overlapping:
     - `ddd` supplies design rules used by `sdd`.
     - `tech-stack` injects language-specific standards when relevant.
     - `reflexion` adds reflection/memory loops.
     - `review` adds post-change evaluation.
     - `git` bridges assistant workflows to Git operations.
   - The architecture is therefore a **toolkit of orthogonal behaviors**, not a single monolithic assistant.

12. **External interfaces that matter**
   - The marketplace is distributed through the Claude plugin ecosystem and also references other assistant ecosystems like Cursor, OpenCode, Antigravity, and Codex.
   - GitHub is relevant for installation, PR workflows, and CI integration.
   - GitBook is used as the documentation publishing surface.
   - Bun is required specifically for the Reflexion hook implementation.

13. **How to draw it**
   - A good architecture diagram would show:
     - a central **plugin marketplace repository**,
     - branching into **installable plugin packages**,
     - a separate **docs site**,
     - a separate **spec/task management area**,
     - and a small **runtime hook/code subsystem** for Reflexion.
   - Inside plugins, emphasize that most behavior is encoded as **markdown prompt assets** plus manifests, with only a small amount of executable TypeScript.

14. **Overall architectural character**
   - This repo is a **content-oriented, modular plugin distribution system** for agent behavior engineering.
   - Its core design principles are: isolation, composability, minimal token footprint, and workflow specialization.
   - The main architectural concern is not request routing or data storage, but **how assistant capabilities are packaged, loaded, and orchestrated**.

Main entry points: [`plugins/README.md`](https://github.com/neolabhq/context-engineering-kit/blob/master/plugins/README.md) (Plugin catalog), [`plugins/reflexion`](https://github.com/neolabhq/context-engineering-kit/tree/master/plugins/reflexion) (Reflexion), [`plugins/sdd`](https://github.com/neolabhq/context-engineering-kit/tree/master/plugins/sdd) (SDD), [`docs/README.md`](https://github.com/neolabhq/context-engineering-kit/blob/master/docs/README.md) (Docs site)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_repo["Repository"]
  node_repo_root["Marketplace repo<br/>monorepo"]
  node_plugin_manifest["Plugin manifest<br/>package manifest<br/>[marketplace.json]"]
end

subgraph group_plugins["Installable plugins"]
  node_plugin_catalog["Plugin catalog<br/>distribution index<br/>[README.md]"]
  node_customaize_agent["Custom agent<br/>skill generator"]
  node_ddd["DDD rules<br/>rules plugin"]
  node_docs_plugin["Docs plugin<br/>skills plugin"]
  node_fpf["FPF<br/>evidence loop"]
  node_git_plugin["Git plugin<br/>workflow plugin"]
  node_kaizen["Kaizen<br/>analysis workflow"]
  node_mcp["MCP plugin<br/>integration skills"]
  node_reflexion["Reflexion<br/>hook runtime"]
  node_review["Review"]
  node_sadd["SADD<br/>agent orchestration"]
  node_sdd["SDD<br/>spec workflow"]
  node_tdd["TDD<br/>testing workflow"]
  node_tech_stack["Tech stack<br/>language rules"]
end

subgraph group_docs["Documentation"]
  node_docs_root["Docs site<br/>documentation tree<br/>[README.md]"]
  node_docs_guides["Guides<br/>how-to docs<br/>[README.md]"]
  node_docs_plugins["Plugin docs<br/>plugin reference<br/>[README.md]"]
  node_docs_reference["Reference<br/>[README.md]"]
end

subgraph group_specs["Specs and process"]
  node_spec_tasks["Task specs<br/>work tracker<br/>[roadmap.md]"]
  node_spec_reports["Reports"]
  node_spec_research["Research<br/>notes"]
end

subgraph group_tooling["Tooling"]
  node_devcontainer["Dev container<br/>environment setup<br/>[devcontainer.json]"]
  node_justfile["Just tasks<br/>automation"]
end

node_repo_root -->|"hosts"| node_plugin_catalog
node_repo_root -->|"publishes"| node_docs_root
node_repo_root -->|"tracks"| node_spec_tasks
node_repo_root -->|"supports"| node_devcontainer
node_repo_root -->|"automates"| node_justfile
node_plugin_catalog -->|"packages via"| node_plugin_manifest
node_plugin_catalog -->|"includes"| node_customaize_agent
node_plugin_catalog -->|"includes"| node_ddd
node_plugin_catalog -->|"includes"| node_docs_plugin
node_plugin_catalog -->|"includes"| node_fpf
node_plugin_catalog -->|"includes"| node_git_plugin
node_plugin_catalog -->|"includes"| node_kaizen
node_plugin_catalog -->|"includes"| node_mcp
node_plugin_catalog -->|"includes"| node_reflexion
node_plugin_catalog -->|"includes"| node_review
node_plugin_catalog -->|"includes"| node_sadd
node_plugin_catalog -->|"includes"| node_sdd
node_plugin_catalog -->|"includes"| node_tdd
node_plugin_catalog -->|"includes"| node_tech_stack
node_docs_root -->|"navigates to"| node_docs_guides
node_docs_root -->|"navigates to"| node_docs_plugins
node_docs_root -->|"navigates to"| node_docs_reference
node_spec_tasks -->|"produces"| node_spec_reports
node_spec_tasks -->|"depends on"| node_spec_research
node_sdd -->|"uses rules from"| node_ddd
node_sdd -->|"operates on"| node_spec_tasks
node_sdd -->|"orchestrates with"| node_sadd
node_review -->|"orchestrates with"| node_sadd
node_reflexion -->|"extends via"| node_plugin_manifest
node_reflexion -.->|"developed in"| node_devcontainer
node_reflexion -.->|"tested with"| node_justfile
node_fpf -.->|"complements"| node_review
node_git_plugin -.->|"records"| node_spec_reports
node_customaize_agent -.->|"documented by"| node_docs_plugins

click node_plugin_manifest "https://github.com/neolabhq/context-engineering-kit/blob/master/.claude-plugin/marketplace.json"
click node_plugin_catalog "https://github.com/neolabhq/context-engineering-kit/blob/master/plugins/README.md"
click node_customaize_agent "https://github.com/neolabhq/context-engineering-kit/tree/master/plugins/customaize-agent"
click node_ddd "https://github.com/neolabhq/context-engineering-kit/tree/master/plugins/ddd"
click node_docs_plugin "https://github.com/neolabhq/context-engineering-kit/tree/master/plugins/docs"
click node_fpf "https://github.com/neolabhq/context-engineering-kit/tree/master/plugins/fpf"
click node_git_plugin "https://github.com/neolabhq/context-engineering-kit/tree/master/plugins/git"
click node_kaizen "https://github.com/neolabhq/context-engineering-kit/tree/master/plugins/kaizen"
click node_mcp "https://github.com/neolabhq/context-engineering-kit/tree/master/plugins/mcp"
click node_reflexion "https://github.com/neolabhq/context-engineering-kit/tree/master/plugins/reflexion"
click node_review "https://github.com/neolabhq/context-engineering-kit/tree/master/plugins/review"
click node_sadd "https://github.com/neolabhq/context-engineering-kit/tree/master/plugins/sadd"
click node_sdd "https://github.com/neolabhq/context-engineering-kit/tree/master/plugins/sdd"
click node_tdd "https://github.com/neolabhq/context-engineering-kit/tree/master/plugins/tdd"
click node_tech_stack "https://github.com/neolabhq/context-engineering-kit/tree/master/plugins/tech-stack"
click node_docs_root "https://github.com/neolabhq/context-engineering-kit/blob/master/docs/README.md"
click node_docs_guides "https://github.com/neolabhq/context-engineering-kit/blob/master/docs/guides/README.md"
click node_docs_plugins "https://github.com/neolabhq/context-engineering-kit/blob/master/docs/plugins/README.md"
click node_docs_reference "https://github.com/neolabhq/context-engineering-kit/blob/master/docs/reference/README.md"
click node_spec_tasks "https://github.com/neolabhq/context-engineering-kit/blob/master/.specs/tasks/roadmap.md"
click node_spec_reports "https://github.com/neolabhq/context-engineering-kit/blob/master/.specs/reports/do-in-parallel-2026-01-01.1.md"
click node_spec_research "https://github.com/neolabhq/context-engineering-kit/blob/master/.specs/research/research-resources.md"
click node_devcontainer "https://github.com/neolabhq/context-engineering-kit/blob/master/.devcontainer/devcontainer.json"
click node_justfile "https://github.com/neolabhq/context-engineering-kit/tree/master/justfile"

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_repo_root,node_plugin_manifest toneBlue
class node_plugin_catalog,node_customaize_agent,node_ddd,node_docs_plugin,node_fpf,node_git_plugin,node_kaizen,node_mcp,node_reflexion,node_review,node_sadd,node_sdd,node_tdd,node_tech_stack toneAmber
class node_docs_root,node_docs_guides,node_docs_plugins,node_docs_reference toneMint
class node_spec_tasks,node_spec_reports,node_spec_research toneRose
class node_devcontainer,node_justfile toneIndigo
```

## Components

### Repository

Top-level workspace for the plugin marketplace and its support assets.

- **Marketplace repo**: monorepo · The repository acts as a content-oriented marketplace for assistant plugins and workflows.
- [Plugin manifest](https://github.com/neolabhq/context-engineering-kit/blob/master/.claude-plugin/marketplace.json): package manifest · `.claude-plugin/plugin.json` files define the install boundary for each plugin package. · `.claude-plugin/marketplace.json`

### Installable plugins

Claude-compatible plugin packages distributed from the repository.

- [Plugin catalog](https://github.com/neolabhq/context-engineering-kit/blob/master/plugins/README.md): distribution index · Top-level plugin collection organized as installable packages with manifests and assets. · `plugins/README.md`
- [Custom agent](https://github.com/neolabhq/context-engineering-kit/tree/master/plugins/customaize-agent): skill generator · Skills for creating agents, commands, hooks, skills, and workflows. · `plugins/customaize-agent`
- [DDD rules](https://github.com/neolabhq/context-engineering-kit/tree/master/plugins/ddd): rules plugin · Architectural and code-quality rules used as reusable behavioral guidance. · `plugins/ddd`
- [Docs plugin](https://github.com/neolabhq/context-engineering-kit/tree/master/plugins/docs): skills plugin · Skills for updating docs and writing concisely. · `plugins/docs`
- [FPF](https://github.com/neolabhq/context-engineering-kit/tree/master/plugins/fpf): evidence loop · Hypothesis, evidence, validation, and trust-management workflow around an agent. · `plugins/fpf`
- [Git plugin](https://github.com/neolabhq/context-engineering-kit/tree/master/plugins/git): workflow plugin · Skills that connect assistant actions to Git and pull-request workflows. · `plugins/git`
- [Kaizen](https://github.com/neolabhq/context-engineering-kit/tree/master/plugins/kaizen): analysis workflow · Continuous-improvement and root-cause analysis skills. · `plugins/kaizen`
- [MCP plugin](https://github.com/neolabhq/context-engineering-kit/tree/master/plugins/mcp): integration skills · Setup and build guidance for Model Context Protocol tooling. · `plugins/mcp`
- [Reflexion](https://github.com/neolabhq/context-engineering-kit/tree/master/plugins/reflexion): hook runtime · Runtime hook subsystem that adds reflection and memory behavior. · `plugins/reflexion`
- [Review](https://github.com/neolabhq/context-engineering-kit/tree/master/plugins/review): multi-agent review · Specialized reviewers for bugs, security, tests, contracts, and context. · `plugins/review`
- [SADD](https://github.com/neolabhq/context-engineering-kit/tree/master/plugins/sadd): agent orchestration · Multi-agent coordination patterns such as parallel, competitive, judge, and tree-of-thought flows. · `plugins/sadd`
- [SDD](https://github.com/neolabhq/context-engineering-kit/tree/master/plugins/sdd): spec workflow · Spec-driven development pipeline with planning, implementation, review, and documentation roles. · `plugins/sdd`
- [TDD](https://github.com/neolabhq/context-engineering-kit/tree/master/plugins/tdd): testing workflow · Skills for test design, coverage, test writing, and fixing failing tests. · `plugins/tdd`
- [Tech stack](https://github.com/neolabhq/context-engineering-kit/tree/master/plugins/tech-stack): language rules · Language-specific best-practice rules, currently focused on TypeScript. · `plugins/tech-stack`

### Documentation

Human-facing GitBook-style docs for concepts, guides, references, and plugin usage.

- [Docs site](https://github.com/neolabhq/context-engineering-kit/blob/master/docs/README.md): documentation tree · GitBook-style documentation site that explains the marketplace and its plugins. · `docs/README.md`
- [Guides](https://github.com/neolabhq/context-engineering-kit/blob/master/docs/guides/README.md): how-to docs · Operational and conceptual usage guides for workflows such as review, SDD, and CI integration. · `docs/guides/README.md`
- [Plugin docs](https://github.com/neolabhq/context-engineering-kit/blob/master/docs/plugins/README.md): plugin reference · Per-plugin documentation pages mirroring the installable catalog. · `docs/plugins/README.md`
- [Reference](https://github.com/neolabhq/context-engineering-kit/blob/master/docs/reference/README.md): reference docs · Reference pages for agents, commands, and skills. · `docs/reference/README.md`

### Specs and process

Task drafts, reports, research notes, and roadmap artifacts used to manage development work.

- [Task specs](https://github.com/neolabhq/context-engineering-kit/blob/master/.specs/tasks/roadmap.md): work tracker · Draft, in-progress, done, and roadmap task artifacts for ongoing repository work. · `.specs/tasks/roadmap.md`
- [Reports](https://github.com/neolabhq/context-engineering-kit/blob/master/.specs/reports/do-in-parallel-2026-01-01.1.md): execution reports · Outcome logs and step reports from spec-driven work and maintenance operations. · `.specs/reports/do-in-parallel-2026-01-01.1.md`
- [Research](https://github.com/neolabhq/context-engineering-kit/blob/master/.specs/research/research-resources.md): notes · Collected research notes and resource lists supporting plugin and workflow design. · `.specs/research/research-resources.md`

### Tooling

Development and integration helpers around the repository.

- [Dev container](https://github.com/neolabhq/context-engineering-kit/blob/master/.devcontainer/devcontainer.json): environment setup · Containerized contributor environment definition. · `.devcontainer/devcontainer.json`
- [Just tasks](https://github.com/neolabhq/context-engineering-kit/tree/master/justfile): automation · Contributor automation entrypoint for common repository tasks. · `justfile`

## Connections

- Marketplace repo → Plugin catalog: hosts · Repository contains the installable plugin catalog.
- Marketplace repo → Docs site: publishes · Repository exposes human-facing documentation.
- Marketplace repo → Task specs: tracks · Repository stores internal process and task artifacts.
- Marketplace repo → Dev container: supports · Repository includes a containerized development environment.
- Marketplace repo → Just tasks: automates · Repository provides task automation for contributors.
- Plugin catalog → Plugin manifest: packages via · Each plugin is bounded by a manifest that defines installable assets.
- Plugin catalog → Custom agent: includes · Installable skill-generator plugin.
- Plugin catalog → DDD rules: includes · Reusable architectural rule set.
- Plugin catalog → Docs plugin: includes · Docs-oriented skill plugin.
- Plugin catalog → FPF: includes · Evidence-based reasoning workflow plugin.
- Plugin catalog → Git plugin: includes · Git and PR workflow plugin.
- Plugin catalog → Kaizen: includes · Continuous-improvement workflow plugin.
- Plugin catalog → MCP plugin: includes · MCP setup/build plugin.
- Plugin catalog → Reflexion: includes · Hook-driven reflection plugin.
- Plugin catalog → Review: includes · Multi-agent review plugin.
- Plugin catalog → SADD: includes · Multi-agent orchestration plugin.
- Plugin catalog → SDD: includes · Spec-driven development plugin.
- Plugin catalog → TDD: includes · Testing workflow plugin.
- Plugin catalog → Tech stack: includes · Language-specific rules plugin.
- Docs site → Guides: navigates to · GitBook navigation fans out into guide pages.
- Docs site → Plugin docs: navigates to · Documentation mirrors the plugin catalog.
- Docs site → Reference: navigates to · Reference pages define commands, agents, and skills.
- Task specs → Reports: produces · Completed or executed work is recorded in reports.
- Task specs → Research: depends on · Task work is informed by research notes and resources.
- SDD → DDD rules: uses rules from · Spec-driven development incorporates architectural guidance.
- SDD → Task specs: operates on · SDD work is organized around task artifacts and phases.
- SDD → SADD: orchestrates with · SDD relies on sub-agent coordination patterns.
- Review → SADD: orchestrates with · Review fans out through specialized agent roles.
- Reflexion → Plugin manifest: extends via · Hook package is installed through the plugin manifest boundary.
- Reflexion → Dev container: developed in · Hook runtime is part of the repo's containerized dev setup.
- Reflexion → Just tasks: tested with · Repository automation helps run and maintain the hook subsystem.
- FPF → Review: complements · Evidence loop pairs naturally with verification and critique.
- Git plugin → Reports: records · Git workflow tasks can be captured as step reports.
- Custom agent → Plugin docs: documented by · Skill-generation workflows are explained in plugin docs.