# coleam00/context-engineering-intro architecture

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

- Interactive diagram: https://gitdiagram.com/coleam00/context-engineering-intro
- Repository: https://github.com/coleam00/context-engineering-intro

## Overview

1. This repository is a meta-template, not a single product runtime. Its main purpose is to teach and operationalize “context engineering” for AI coding assistants: define the task, supply examples and rules, generate a PRP, then execute that PRP against a target codebase.

2. The root-level control plane is made of `CLAUDE.md`, `INITIAL.md`, `.claude/commands/`, and `PRPs/`. The intended flow is: a human writes a feature request in `INITIAL.md`, `generate-prp` turns it into a detailed Product Requirements Prompt under `PRPs/`, and `execute-prp` uses that blueprint to implement the change.

3. `CLAUDE.md` is the persistent policy layer. It encodes project-wide instructions for the agent: coding conventions, documentation expectations, validation habits, and how to interpret the repo. In architecture terms, it is the shared rule set applied before any implementation work begins.

4. `examples/` is the pattern library. The template relies on concrete code examples so the agent can mirror file structure, imports, test style, and integration patterns instead of inventing them. This is a key boundary in the system: guidance comes from examples plus rules, not only from prompts.

5. `validation/` provides the quality gate layer. It contains validation guidance and example validation commands, which are meant to be referenced by PRPs and execution commands so the agent can verify its work before considering a feature complete.

6. `claude-code-full-guide/` is a documentation-heavy, self-contained reference workspace for Claude Code workflows. It includes custom commands, agent definitions, hooks, and a dev container, showing how to build a more structured agent environment with reproducible setup and tool-usage logging.

7. `use-cases/pydantic-ai/` and `use-cases/agent-factory-with-subagents/` are Python reference architectures for AI agents. They show common subsystems: agent definitions, tools, provider abstractions, settings, CLI entrypoints, prompt files, and tests. These folders are organized as example applications, each with their own local `.claude` config and PRP templates.

8. The most substantial Python subsystem is the RAG agent in `use-cases/agent-factory-with-subagents/agents/rag_agent/`. Its data flow is: local markdown documents in `documents/` go through `ingestion/` chunking and embedding, then into a SQL-backed persistence layer (`sql/schema.sql`, `utils/db_utils.py`), and finally into the agent runtime (`agent.py`, `tools.py`, `cli.py`). This is the clearest example of an end-to-end AI application in the repo.

9. `use-cases/mcp-server/` is a separate TypeScript architecture built around an MCP server running on Cloudflare Workers. The main flow is: `src/index.ts` boots the server, `src/auth/` handles OAuth/GitHub auth, `src/database/` manages connection/security/utilities, and `src/tools/register-tools.ts` exposes capabilities to MCP clients. `wrangler.jsonc` and worker typings indicate deployment is oriented around Cloudflare rather than a traditional Node server.

10. `use-cases/ai-coding-wisc-framework/` and `use-cases/ai-coding-workflows-foundation/` define workflow and governance patterns for agentic software delivery. They contain commands, rules, and documentation templates for planning, priming, handoff, isolation, and execution. Architecturally, these folders sit above code features and define how work should be split, reviewed, and coordinated.

11. `use-cases/template-generator/` is a specialization of the PRP workflow itself. It contains its own PRP templates and commands for generating execution plans tailored to Pydantic AI projects, making it a meta-template inside the larger template repository.

12. The repository is intentionally partitioned into many self-contained subprojects, each with its own `.claude`, `CLAUDE.md`, `PRPs/`, and sometimes its own tests, examples, or deployment config. That separation matters for diagramming: the root repo is the orchestration and documentation layer, while the `use-cases/` folders are independent reference implementations with their own local boundaries and runtime assumptions.

13. If you diagram the repo accurately, the top-level flows should show “request → PRP generation → PRP execution → validation,” and then branch into the example domains: Python agents, RAG pipelines, MCP server tooling, workflow frameworks, and documentation/tooling for Claude Code.

Main entry points: [`.claude/commands`](https://github.com/coleam00/context-engineering-intro/blob/main/.claude/commands) (.claude/commands), [`PRPs`](https://github.com/coleam00/context-engineering-intro/tree/main/PRPs) (PRPs), [`claude-code-full-guide`](https://github.com/coleam00/context-engineering-intro/tree/main/claude-code-full-guide) (claude guide), [`validation`](https://github.com/coleam00/context-engineering-intro/tree/main/validation) (validation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_root["Root template"]
  node_claude_md["CLAUDE.md<br/>policy layer<br/>[CLAUDE.md]"]
  node_initial_md["INITIAL.md<br/>request intake<br/>[INITIAL.md]"]
  node_commands_root[".claude/commands<br/>agent commands<br/>[commands]"]
  node_prps_root["PRPs<br/>prompt blueprints"]
  node_examples_root["examples<br/>pattern library"]
end

subgraph group_guide["Claude guide"]
  node_guide_workspace["claude guide<br/>reference workspace"]
  node_guide_commands["guide commands<br/>workflow commands<br/>[commands]"]
  node_guide_agents["guide agents<br/>agent roles<br/>[agents]"]
  node_guide_hooks["tool hooks<br/>logging hooks<br/>[hooks]"]
  node_guide_container["dev container<br/>environment setup<br/>[.devcontainer]"]
end

subgraph group_python["Python use cases"]
  node_pydantic_ai["pydantic-ai<br/>python reference"]
  node_rag_factory["agent factory<br/>python reference"]
  node_rag_agent["rag agent<br/>RAG application"]
end

subgraph group_typescript["TypeScript use cases"]
  node_mcp_server["mcp server<br/>worker service"]
end

subgraph group_workflow["Workflow frameworks"]
  node_wisc_framework["wisc framework<br/>workflow governance"]
  node_workflows_foundation["workflows foundation<br/>workflow foundation"]
  node_template_generator["template generator<br/>meta-template"]
end

subgraph group_validation["Validation"]
  node_validation_root["validation<br/>quality gate"]
end

node_initial_md -->|"generate PRP"| node_commands_root
node_commands_root -->|"write PRP"| node_prps_root
node_prps_root -->|"execute PRP"| node_commands_root
node_claude_md -->|"govern commands"| node_commands_root
node_claude_md -->|"set rules"| node_prps_root
node_examples_root -->|"ground examples"| node_prps_root
node_validation_root -->|"define checks"| node_prps_root
node_validation_root -->|"gate execution"| node_commands_root
node_guide_workspace -->|"contains"| node_guide_commands
node_guide_workspace -->|"contains"| node_guide_agents
node_guide_workspace -->|"contains"| node_guide_hooks
node_guide_workspace -->|"contains"| node_guide_container
node_pydantic_ai -->|"inspires"| node_template_generator
node_rag_factory -->|"hosts"| node_rag_agent
node_rag_agent -->|"data flow"| node_rag_agent
node_rag_agent -->|"mirrors patterns"| node_examples_root
node_mcp_server -->|"uses workflows"| node_guide_workspace
node_wisc_framework -->|"extends"| node_workflows_foundation
node_template_generator -->|"specializes"| node_commands_root
node_template_generator -->|"emits templates"| node_prps_root
node_mcp_server -->|"tests against"| node_validation_root
node_pydantic_ai -->|"validated by"| node_validation_root
node_rag_factory -->|"validated by"| node_validation_root

click node_claude_md "https://github.com/coleam00/context-engineering-intro/blob/main/CLAUDE.md"
click node_initial_md "https://github.com/coleam00/context-engineering-intro/blob/main/INITIAL.md"
click node_commands_root "https://github.com/coleam00/context-engineering-intro/blob/main/.claude/commands"
click node_prps_root "https://github.com/coleam00/context-engineering-intro/tree/main/PRPs"
click node_examples_root "https://github.com/coleam00/context-engineering-intro/tree/main/examples"
click node_validation_root "https://github.com/coleam00/context-engineering-intro/tree/main/validation"
click node_guide_workspace "https://github.com/coleam00/context-engineering-intro/tree/main/claude-code-full-guide"
click node_guide_commands "https://github.com/coleam00/context-engineering-intro/blob/main/claude-code-full-guide/.claude/commands"
click node_guide_agents "https://github.com/coleam00/context-engineering-intro/blob/main/claude-code-full-guide/.claude/agents"
click node_guide_hooks "https://github.com/coleam00/context-engineering-intro/blob/main/claude-code-full-guide/.claude/hooks"
click node_guide_container "https://github.com/coleam00/context-engineering-intro/blob/main/claude-code-full-guide/.devcontainer"
click node_pydantic_ai "https://github.com/coleam00/context-engineering-intro/tree/main/use-cases/pydantic-ai"
click node_rag_factory "https://github.com/coleam00/context-engineering-intro/tree/main/use-cases/agent-factory-with-subagents"
click node_rag_agent "https://github.com/coleam00/context-engineering-intro/tree/main/use-cases/agent-factory-with-subagents/agents/rag_agent"
click node_mcp_server "https://github.com/coleam00/context-engineering-intro/tree/main/use-cases/mcp-server"
click node_wisc_framework "https://github.com/coleam00/context-engineering-intro/tree/main/use-cases/ai-coding-wisc-framework"
click node_workflows_foundation "https://github.com/coleam00/context-engineering-intro/tree/main/use-cases/ai-coding-workflows-foundation"
click node_template_generator "https://github.com/coleam00/context-engineering-intro/tree/main/use-cases/template-generator"

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_claude_md,node_initial_md,node_commands_root,node_prps_root,node_examples_root toneBlue
class node_guide_workspace,node_guide_commands,node_guide_agents,node_guide_hooks,node_guide_container toneAmber
class node_pydantic_ai,node_rag_factory,node_rag_agent toneMint
class node_mcp_server toneRose
class node_wisc_framework,node_workflows_foundation,node_template_generator toneIndigo
class node_validation_root toneTeal
```

## Components

### Root template

Repository-wide control plane for context engineering and PRP-driven work.

- [CLAUDE.md](https://github.com/coleam00/context-engineering-intro/blob/main/CLAUDE.md): policy layer · Persistent repo-wide instructions and conventions for the agent. · `CLAUDE.md`
- [INITIAL.md](https://github.com/coleam00/context-engineering-intro/blob/main/INITIAL.md): request intake · Human-written feature request that starts the PRP flow. · `INITIAL.md`
- [.claude/commands](https://github.com/coleam00/context-engineering-intro/blob/main/.claude/commands): agent commands · Root command entrypoints for generating and executing PRPs. · `.claude/commands`
- [PRPs](https://github.com/coleam00/context-engineering-intro/tree/main/PRPs): prompt blueprints · Generated and templated Product Requirements Prompts. · `PRPs`
- [examples](https://github.com/coleam00/context-engineering-intro/tree/main/examples): pattern library · Repository-wide example space for structure, imports, and style. · `examples`

### Claude guide

Self-contained reference workspace for structured Claude Code usage.

- [claude guide](https://github.com/coleam00/context-engineering-intro/tree/main/claude-code-full-guide): reference workspace · Documentation-heavy workspace showing a structured Claude Code environment. · `claude-code-full-guide`
- [guide commands](https://github.com/coleam00/context-engineering-intro/blob/main/claude-code-full-guide/.claude/commands): workflow commands · Extended command set for primers, parallel execution, and PRPs. · `claude-code-full-guide/.claude/commands`
- [guide agents](https://github.com/coleam00/context-engineering-intro/blob/main/claude-code-full-guide/.claude/agents): agent roles · Specialized agent definitions for documentation and validation. · `claude-code-full-guide/.claude/agents`
- [tool hooks](https://github.com/coleam00/context-engineering-intro/blob/main/claude-code-full-guide/.claude/hooks): logging hooks · Tool-usage logging and hook configuration for reproducible workflows. · `claude-code-full-guide/.claude/hooks`
- [dev container](https://github.com/coleam00/context-engineering-intro/blob/main/claude-code-full-guide/.devcontainer): environment setup · Containerized setup for repeatable local development. · `claude-code-full-guide/.devcontainer`

### Python use cases

Pydantic AI reference architectures and agent examples.

- [pydantic-ai](https://github.com/coleam00/context-engineering-intro/tree/main/use-cases/pydantic-ai): python reference · Pydantic AI project templates and example agent implementations. · `use-cases/pydantic-ai`
- [agent factory](https://github.com/coleam00/context-engineering-intro/tree/main/use-cases/agent-factory-with-subagents): python reference · Pydantic AI subagent architecture with planning and utility layers. · `use-cases/agent-factory-with-subagents`
- [rag agent](https://github.com/coleam00/context-engineering-intro/tree/main/use-cases/agent-factory-with-subagents/agents/rag_agent): RAG application · End-to-end RAG subsystem from documents through ingestion to CLI/runtime. · `use-cases/agent-factory-with-subagents/agents/rag_agent`

### TypeScript use cases

Cloudflare Worker MCP server example.

- [mcp server](https://github.com/coleam00/context-engineering-intro/tree/main/use-cases/mcp-server): worker service · Cloudflare Workers MCP server with auth, database, and tool registration. · `use-cases/mcp-server`

### Workflow frameworks

Governance and execution patterns for agentic delivery.

- [wisc framework](https://github.com/coleam00/context-engineering-intro/tree/main/use-cases/ai-coding-wisc-framework): workflow governance · Commands and rules for planning, priming, isolation, and execution. · `use-cases/ai-coding-wisc-framework`
- [workflows foundation](https://github.com/coleam00/context-engineering-intro/tree/main/use-cases/ai-coding-workflows-foundation): workflow foundation · Core planning and execution patterns for agentic software delivery. · `use-cases/ai-coding-workflows-foundation`
- [template generator](https://github.com/coleam00/context-engineering-intro/tree/main/use-cases/template-generator): meta-template · Specialized PRP generator for Pydantic AI projects. · `use-cases/template-generator`

### Validation

Quality gate guidance and example checks.

- [validation](https://github.com/coleam00/context-engineering-intro/tree/main/validation): quality gate · Validation guidance and example commands for completion checks. · `validation`

## Connections

- INITIAL.md → .claude/commands: generate PRP · Feature request is transformed into a detailed Product Requirements Prompt.
- .claude/commands → PRPs: write PRP · Generation command produces a blueprint under PRPs/ .
- PRPs → .claude/commands: execute PRP · Execution command consumes the PRP to implement the change.
- CLAUDE.md → .claude/commands: govern commands · Persistent policy shapes how commands interpret and act on tasks.
- CLAUDE.md → PRPs: set rules · Shared conventions and expectations are embedded into PRP templates.
- examples → PRPs: ground examples · Pattern library informs PRPs with concrete structure and style references.
- validation → PRPs: define checks · Validation guidance is referenced by PRPs as completion criteria.
- validation → .claude/commands: gate execution · Execution should include validation before marking work complete.
- claude guide → guide commands: contains · The guide workspace packages its own command set.
- claude guide → guide agents: contains · The guide workspace defines specialized agent roles.
- claude guide → tool hooks: contains · The guide workspace includes hook-based logging and observability.
- claude guide → dev container: contains · The guide workspace provides reproducible container setup.
- pydantic-ai → template generator: inspires · Pydantic AI examples are the target pattern for the template generator.
- agent factory → rag agent: hosts · The factory project contains the RAG agent as its central runtime.
- rag agent → rag agent: data flow · Documents are ingested, embedded, persisted, and queried by the agent.
- rag agent → examples: mirrors patterns · The agent implementation is shaped by shared example conventions.
- mcp server → claude guide: uses workflows · The MCP server example mirrors structured Claude Code practices.
- wisc framework → workflows foundation: extends · The framework operationalizes planning and execution patterns.
- template generator → .claude/commands: specializes · Template-specific commands generate and execute tailored PRPs.
- template generator → PRPs: emits templates · It contributes PRP templates and initial prompts for execution plans.
- mcp server → validation: tests against · Worker/server implementation relies on unit and fixture-based validation.
- pydantic-ai → validation: validated by · Python examples are paired with testing and validation patterns.
- agent factory → validation: validated by · The reference architecture includes tests and validation reports.
