How coleam00/context-engineering-intro works
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: commands .claude/commands · PRPs PRPs · claude-code-full-guide claude guide · validation validation
Components 18
Root template
Repository-wide control plane for context engineering and PRP-driven work.
- CLAUDE.md · Persistent repo-wide instructions and conventions for the agent.
CLAUDE.md - INITIAL.md · Human-written feature request that starts the PRP flow.
INITIAL.md - .claude/commands · Root command entrypoints for generating and executing PRPs.
.claude/commands - PRPs · Generated and templated Product Requirements Prompts.
PRPs - examples · Repository-wide example space for structure, imports, and style.
examples
Claude guide
Self-contained reference workspace for structured Claude Code usage.
- claude guide · Documentation-heavy workspace showing a structured Claude Code environment.
claude-code-full-guide - guide commands · Extended command set for primers, parallel execution, and PRPs.
claude-code-full-guide/.claude/commands - guide agents · Specialized agent definitions for documentation and validation.
claude-code-full-guide/.claude/agents - tool hooks · Tool-usage logging and hook configuration for reproducible workflows.
claude-code-full-guide/.claude/hooks - dev container · Containerized setup for repeatable local development.
claude-code-full-guide/.devcontainer
Python use cases
Pydantic AI reference architectures and agent examples.
- pydantic-ai · Pydantic AI project templates and example agent implementations.
use-cases/pydantic-ai - agent factory · Pydantic AI subagent architecture with planning and utility layers.
use-cases/agent-factory-with-subagents - rag agent · 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 · 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 · Commands and rules for planning, priming, isolation, and execution.
use-cases/ai-coding-wisc-framework - workflows foundation · Core planning and execution patterns for agentic software delivery.
use-cases/ai-coding-workflows-foundation - template generator · Specialized PRP generator for Pydantic AI projects.
use-cases/template-generator
Validation
Quality gate guidance and example checks.
- validation · Validation guidance and example commands for completion checks.
validation
Connections 23
- 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.