# Agent Workflows — full corpus # LLM Wiki An open-source template for building LLM-powered knowledge bases, following [Andrej Karpathy's "LLM Wiki" pattern](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f). You provide raw sources. The LLM reads them, writes structured wiki pages, cross-links everything, and maintains it over time. You never edit the wiki directly — you curate sources and ask questions. ## How It Works The system has three layers: ``` raw/ Sources you collect (articles, transcripts, notes, PDFs) wiki/ LLM-written & maintained pages (summaries, concepts, entities, syntheses) CLAUDE.md Schema that tells the LLM how to structure everything ``` Three operations drive the workflow: | Operation | Trigger | What happens | |-----------|---------|--------------| | **Ingest** | "ingest raw/my-source.txt" | LLM reads the source, creates a summary page, creates/updates concept and entity pages, adds cross-links, updates the index and log | | **Query** | Ask any question | LLM searches the wiki, synthesizes an answer with citations, optionally creates a synthesis page for novel insights | | **Lint** | "lint" or "health check" | LLM audits all pages for orphans, contradictions, missing links, incomplete sections, and low-confidence claims — fixes what it can, reports the rest | ## Quick Start 1. **Clone this repo** ```bash git clone https://github.com/YOUR_USERNAME/llm-wiki.git my-knowledge-base cd my-knowledge-base ``` 2. **Customize CLAUDE.md** for your domain - Update the Purpose section with your topic - Replace the placeholder tagging taxonomy with your own categories - Adjust confidence level descriptions if needed - Everything else (workflows, page formats, linking rules) works as-is 3. **Drop sources into `raw/`** - Text files, transcripts, articles, notes — any plain text - These are immutable once added; the LLM never modifies them 4. **Tell the LLM to ingest** ``` ingest raw/my-first-source.txt ``` The LLM will create summary pages, concept pages, entity pages, cross-links, and update the index. 5. **Ask questions** ``` What are the key differences between X and Y? ``` The LLM answers from the wiki, citing specific pages. 6. **Run health checks** ``` lint ``` The LLM audits the wiki and fixes issues. ## Directory Structure ``` . ├── CLAUDE.md # Schema — the LLM's instructions ├── raw/ # Your source documents (immutable) └── wiki/ ├── index.md # Master catalog of all pages ├── log.md # Append-only activity log ├── dashboard.md # Dataview dashboard (Obsidian) ├── analytics.md # Charts View analytics (Obsidian) ├── flashcards.md # Spaced repetition cards ├── summaries/ # One page per source document ├── concepts/ # Concept and framework pages ├── entities/ # People, tools, organizations, etc. ├── syntheses/ # Cross-cutting analyses and comparisons ├── journal/ # Research/session journal entries │ └── template.md # Journal entry template └── presentations/ # Marp slide decks ``` ## Enhancements This template includes several extras beyond the core wiki pattern: ### Dataview Dashboard (`wiki/dashboard.md`) Live queries that surface low-confidence pages, recent updates, concepts by tag, and pages with the most sources. Requires the [Dataview](https://github.com/blacksmithgu/obsidian-dataview) Obsidian plugin. ### Charts View Analytics (`wiki/analytics.md`) Visual analytics with pie charts, bar charts, and word clouds. Requires the [Charts View](https://github.com/caronchen/obsidian-chartsview-plugin) Obsidian plugin. ### Mermaid Diagrams Use Mermaid code blocks in any wiki page to create flowcharts, sequence diagrams, or concept maps. Native support in Obsidian and GitHub. ### Marp Slides (`wiki/presentations/`) Create slide decks from markdown using [Marp](https://marp.app/). Drop presentation files in this directory. ### Research Journal (`wiki/journal/`) Track your research sessions, experiments, or applied work with the included template. The LLM can reference journal entries when answering queries. ### Spaced Repetition (`wiki/flashcards.md`) Flashcards in the format used by the [Spaced Repetition](https://github.com/st3v3nmw/obsidian-spaced-repetition) Obsidian plugin. Ask the LLM to generate flashcards from any wiki page. ### MCP Server This repo works with Claude Code's MCP server capabilities. Point an MCP-compatible client at this repo and the LLM can read/write the wiki programmatically. ## Customizing for Your Domain The schema in `CLAUDE.md` is domain-agnostic. To adapt it: 1. **Purpose** — Describe your knowledge domain in one paragraph 2. **Tagging taxonomy** — Replace placeholder categories with your own (e.g., for a cooking KB: `cuisine`, `technique`, `ingredient`, `equipment`) 3. **Confidence levels** — Adjust the descriptions to match your domain's evidence standards 4. **Entity types** — Update the entity page description to match what entities mean in your domain (people, tools, companies, etc.) 5. **Journal template** — Customize `wiki/journal/template.md` for your workflow Everything else — page format, linking conventions, workflows, rules — is universal and works across domains. ## Example Domains This template works for any knowledge-intensive topic: - **Research notes** — papers, experiments, methodologies - **Book analysis** — themes, characters, author techniques - **Competitive analysis** — companies, products, market trends - **Course notes** — lectures, readings, key concepts - **Personal development** — frameworks, habits, book summaries - **Technical documentation** — APIs, architectures, design patterns - **Hobby deep-dives** — any subject you want to master ## License MIT --- title: "Knowledge Base Index" type: index updated: 2026-06-10 --- # Knowledge Base Index Master catalog of all wiki pages. Every page in the wiki must have an entry here. ## Concepts | Page | Tags | Confidence | Updated | |------|------|------------|---------| | [workflows-vs-agents](concepts/workflows-vs-agents.md) | agents, workflows, architecture | high | 2026-06-10 | | [workflow-patterns](concepts/workflow-patterns.md) | patterns, routing, parallelization, orchestrator | high | 2026-06-10 | | [context-engineering](concepts/context-engineering.md) | context, prompts, tokens | high | 2026-06-10 | | [tool-design](concepts/tool-design.md) | tools, mcp, structured-outputs, evals | high | 2026-06-10 | | [control-flow-and-state](concepts/control-flow-and-state.md) | control-flow, state, pause-resume | high | 2026-06-10 | | [human-in-the-loop](concepts/human-in-the-loop.md) | approvals, channels, outer-loop | high | 2026-06-10 | | [reliability-factors](concepts/reliability-factors.md) | errors, small-agents, reliability | high | 2026-06-10 | | [multi-agent-systems](concepts/multi-agent-systems.md) | multi-agent, subagents, orchestration | high | 2026-06-10 | | [planning-memory-evaluation](concepts/planning-memory-evaluation.md) | planning, memory, evaluation, surveys | high | 2026-06-10 | ## Entities | Page | Tags | Updated | |------|------|---------| | [twelve-factor-agents](entities/twelve-factor-agents.md) | 12-factor, humanlayer, principles | 2026-06-10 | ## Summaries | Page | Source | Key Topics | Created | |------|--------|------------|---------| | [corpus-catalog](summaries/corpus-catalog.md) | 31 sources, 3 families | source map, gap notes | 2026-06-10 | ## Syntheses | Page | Pages Compared | Created | |------|----------------|---------| | [convergent-principles](syntheses/convergent-principles.md) | 12-factor × Anthropic essays × surveys | 2026-06-10 | ## Statistics - **Total pages**: 12 - **Concepts**: 9 - **Entities**: 1 - **Summaries**: 1 - **Syntheses**: 1 - **Sources ingested**: 31 (24 12-factor docs, 4 Anthropic essays, 2 surveys, 1 issue) - **High confidence**: 11 - **Medium confidence**: 1 - **Low confidence**: 0 --- title: "Context Engineering" type: concept tags: [context, context-window, prompts, tokens, state] updated: 2026-06-10 confidence: high sources: [raw/web_community-effective-context-engineering-for-ai-agents-anthropic.md, raw/github_doc-content-factor-03-own-your-context-window-md.md, raw/github_doc-content-factor-02-own-your-prompts-md.md] --- # Context Engineering The successor framing to prompt engineering (Anthropic, Sep 2025): building with LLMs is less about finding the right words and more about **"what configuration of context is most likely to generate the desired behavior?"** Context = the full set of tokens sampled over; the engineering problem is optimizing their utility against the model's constraints — context is a **critical but finite resource**, and you must "think in context": consider the holistic state the model sees at each step and what behaviors it yields. ## The 12-factor formulation - **Factor 2 — Own your prompts**: don't outsource prompt engineering to a framework's black box; production quality requires hand-controlling what goes in. - **Factor 3 — Own your context window**: you're not obligated to use standard message formats. The operating definition of an agent step: *"here's what's happened so far, what's the next step?"* LLMs are **stateless functions** — best inputs ⇒ best outputs, so everything is context engineering. Custom serializations (compact event logs instead of verbose message arrays) are fair game. ## Practical levers - Compaction/summarization as conversations grow; retrieval instead of stuffing - Compact error representations rather than full stack-trace dumps ([reliability-factors](reliability-factors.md)) - Sub-agents as context isolation — each gets its own window ([multi-agent-systems](multi-agent-systems.md)) - Token-efficient tool responses ([tool-design](tool-design.md)) This is the lens under which agent-readable knowledge bases exist at all: curating what enters the window beats making the model search harder. --- title: "Control Flow & State (Factors 5, 6, 8, 12)" type: concept tags: [control-flow, state, pause-resume, stateless-reducer, 12-factor] updated: 2026-06-10 confidence: high sources: [raw/github_doc-content-factor-05-unify-execution-state-md.md, raw/github_doc-content-factor-06-launch-pause-resume-md.md, raw/github_doc-content-factor-08-own-your-control-flow-md.md, raw/github_doc-content-factor-12-stateless-reducer-md.md] --- # Control Flow & State (Factors 5, 6, 8, 12) The infrastructure core of 12-factor-agents: treat the agent as a normal program whose loop you own. ## Factor 5 — Unify execution state and business state Separating "execution state" (current step, retry counts, waiting status) from "business state" creates complexity that's often overkill — you don't *have* to manage them separately. One unified state (often just the event/context log itself) is simpler to persist, resume, and debug. ## Factor 6 — Launch/pause/resume with simple APIs Agents are just programs: expect the standard verbs — launch, query, pause, resume, stop — as simple APIs. Long-running tool calls (a human approval, a training pipeline) shouldn't hold a process hostage; serialize state, come back when the result arrives. ## Factor 8 — Own your control flow Build the control structures your use case needs: certain tool calls should **break the loop** and wait (human response, long-running task); add custom retries, gating, or summarization steps. Frameworks that hide the loop take this power away — the same argument [workflow-patterns](workflow-patterns.md) makes from the architecture side. ## Factor 12 — The agent as a stateless reducer The unifying mental model (self-described as "mostly for fun" but conceptually load-bearing): an agent is a **fold** — a stateless function repeatedly applied over a growing event sequence to produce the next action. Combined with factors 5/6, this is exactly what makes pause/resume trivial: persist the sequence, re-apply the reducer. LLM statelessness ([context-engineering](context-engineering.md)) is a feature, not a bug. --- title: "Humans in the Loop (Factors 7, 11)" type: concept tags: [human-in-the-loop, approvals, channels, 12-factor] updated: 2026-06-10 confidence: high sources: [raw/github_doc-content-factor-07-contact-humans-with-tools-md.md, raw/github_doc-content-factor-11-trigger-from-anywhere-md.md] --- # Humans in the Loop (Factors 7, 11) ## Factor 7 — Contact humans with tool calls Vanilla LLM APIs hinge on one **high-stakes first-token choice**: plaintext (reply to a human) vs structured data (call a tool). Factor 7 removes that fork: make *contacting a human* itself a structured tool call (`request_approval`, `ask_clarification`, `done_for_now`). The model always emits structured output; "talk to a person" becomes just another action the control loop can route, queue, and resume from ([control-flow-and-state](control-flow-and-state.md)). This is the natural shape for approval gates on high-stakes actions: the agent proposes via tool call, the loop pauses (factor 6), a human answers hours later, the event is appended, the reducer resumes. ## Factor 11 — Trigger from anywhere, meet users where they are With pause/resume (6) and human-contact-as-tools (7) in place, agents can be **triggered from Slack, email, SMS, or any channel — and respond on the same channel**. The agent stops being a chat-window product and becomes an ambient coworker: kicked off by a cron job, an alert, or a forwarded email, escalating to a human wherever that human lives. (This factor is explicitly the HumanLayer pitch — the project's sponsoring company productizes it.) Together, 7 + 11 define **outer-loop agents**: systems that mostly run autonomously and pull humans in as a tool, rather than humans driving every turn. --- title: "Multi-Agent Systems" type: concept tags: [multi-agent, orchestration, subagents, research, parallelism] updated: 2026-06-10 confidence: high sources: [raw/web_community-how-we-built-our-multi-agent-research-system-anthropic.md] --- # Multi-Agent Systems Lessons from Anthropic's production multi-agent Research system (Jun 2025) — a lead agent that plans, then spawns parallel search subagents. ## Why multi-agent - Open-ended research is **dynamic and path-dependent** — you can't hardcode the path; the model must steer across many turns ([workflows-vs-agents](workflows-vs-agents.md)). - **"The essence of search is compression."** Subagents compress: each explores an aspect in its *own context window* in parallel, then condenses the most important tokens back to the lead agent. - **Separation of concerns**: distinct tools, prompts, and trajectories per subagent reduce path dependency and yield thorough independent investigations. ## Architecture Orchestrator-workers at scale ([workflow-patterns](workflow-patterns.md)): a planning agent decomposes the query, spawns parallel searchers, synthesizes. Multi-agent introduces *new* problem classes — agent coordination, evaluation, and reliability — that single-agent systems don't have. ## Costs and caveats Multi-agent burns substantially more tokens than chat (each subagent is a full agentic loop), so it suits **high-value tasks where the answer justifies the spend** and where work parallelizes cleanly. Prompt engineering the *delegation* (clear subagent task descriptions, effort scaling, tool guidance) was a primary lever in getting it to production. Reliability rationale for small scoped agents: [reliability-factors](reliability-factors.md). Context-isolation rationale: [context-engineering](context-engineering.md). --- title: "Planning, Memory & Evaluation (the Survey View)" type: concept tags: [planning, memory, evaluation, surveys, failure-modes] updated: 2026-06-10 confidence: high sources: [raw/web_community-llm-powered-autonomous-agents-lil-log.md, raw/web_community-agents.md] --- # Planning, Memory & Evaluation (the Survey View) Two canonical survey treatments complement the practitioner essays. ## Lilian Weng, "LLM Powered Autonomous Agents" (2023) The field's founding taxonomy — agent = LLM brain + three components: 1. **Planning** — task decomposition (think step-by-step, subgoals) and **self-reflection** (critique and refine past actions). 2. **Memory** — typed by analogy to human memory (short-term = in-context; long-term = external store retrieved via embeddings, with MIPS/ANN search as the retrieval substrate). 3. **Tool use** — extending the model beyond its weights with external APIs ([tool-design](tool-design.md)). Most later frameworks are elaborations of this triad. ## Chip Huyen, "Agents" (2025) Frames agents by the Russell & Norvig lineage (AI as "the study and design of rational agents") and centers two capability determinants — **tools and planning** — plus the consequence: *agents have new modes of operation, therefore new modes of failure*, so **evaluation must be designed to catch agent-specific failures** (wrong plans, wrong tool calls, compounding multi-step errors), not just bad text. ## Where the views meet The surveys' planning/self-reflection maps to evaluator-optimizer loops ([workflow-patterns](workflow-patterns.md)); memory management is [context-engineering](context-engineering.md) by another name; failure-mode evaluation is the systematic version of factor 9's compact-error self-healing ([reliability-factors](reliability-factors.md)). --- title: "Reliability: Small Agents & Compact Errors (Factors 9, 10)" type: concept tags: [reliability, errors, small-agents, context-limits, 12-factor] updated: 2026-06-10 confidence: high sources: [raw/github_doc-content-factor-09-compact-errors-md.md, raw/github_doc-content-factor-10-small-focused-agents-md.md] --- # Reliability: Small Agents & Compact Errors (Factors 9, 10) ## Factor 9 — Compact errors into the context window Agents "self-heal": a good LLM reading an error message or stack trace has a fair chance of fixing the next tool call. The factor: feed errors back **compactly** (the salient line, not the full dump), with a retry counter — escalate or break the loop after N consecutive failures rather than looping forever. Notably adoptable standalone: you can do just this without any of the other 11 factors. ## Factor 10 — Small, focused agents The key insight is an LLM limitation: bigger task ⇒ more steps ⇒ longer context ⇒ the model **gets lost or loses focus**. So build small agents that do one thing well — **3–10, maybe 20 steps max** — embedded in a larger, mostly deterministic system, instead of one monolithic do-everything agent. This is the reliability argument for the same architecture that [workflow-patterns](workflow-patterns.md) (orchestrator-workers) and [multi-agent-systems](multi-agent-systems.md) (subagents as parallel context windows) reach from capability arguments — three independent paths to "many small contexts beat one big one." Failure taxonomies and evaluation as the systematic counterpart: [planning-memory-evaluation](planning-memory-evaluation.md). --- title: "Tool Design for Agents" type: concept tags: [tools, tool-use, mcp, structured-outputs, evals] updated: 2026-06-10 confidence: high sources: [raw/web_community-writing-effective-tools-for-ai-agents-using-ai-agents-anthro.md, raw/github_doc-content-factor-01-natural-language-to-tool-calls-md.md, raw/github_doc-content-factor-04-tools-are-structured-outputs-md.md] --- # Tool Design for Agents ## Demystifying tools (12-factor) - **Factor 1 — Natural language → tool calls**: the atomic agent pattern is translating a phrase ("create a $750 payment link for Terri") into a structured object describing an API call. That's it — reasoning in, JSON out. - **Factor 4 — Tools are just structured outputs**: a "tool call" is structured LLM output that *triggers deterministic code you wrote*. Asking the model to "use one of several tools" = asking it to emit parseable JSON for one of several schemas. No magic, no framework required. ## Engineering quality tools (Anthropic, Sep 2025) "Agents are only as effective as the tools we give them" — MCP can expose hundreds of tools; making them effective is the work: 1. **Prototype** the tool, then **evaluate it with agents actually using it** on realistic tasks — not by eyeballing the schema. 2. Iterate from eval transcripts; failure modes (wrong tool chosen, malformed params, misread results) are visible there. 3. **Use the model to optimize its own tools**: Claude rewriting tool descriptions/schemas against eval feedback measurably boosts performance. ## Design rules of thumb - Fewer, well-described tools beat many overlapping ones (choice ambiguity is a failure mode — see also factor 10's small-agents argument in [reliability-factors](reliability-factors.md)). - Token-efficient responses: return what the next step needs, not the whole object graph ([context-engineering](context-engineering.md)). - Human contact can itself be a tool ([human-in-the-loop](human-in-the-loop.md)). --- title: "The Five Workflow Patterns" type: concept tags: [workflows, patterns, routing, parallelization, orchestrator, evaluator] updated: 2026-06-10 confidence: high sources: [raw/web_community-building-effective-ai-agents-anthropic.md] --- # The Five Workflow Patterns The canonical pattern vocabulary (Anthropic, "Building effective agents"): ## 1. Prompt chaining Decompose into a sequence; each call processes the previous output. Add programmatic **gates** between steps to check the process is on track. Use when a task cleanly splits into fixed subtasks — trading latency for accuracy. ## 2. Routing Classify the input, dispatch to a specialized follow-up (separate prompts per category — optimizing one input type stops hurting the others). Also the cost lever: route easy queries to small models (Haiku-class), hard ones to capable models. Works when categories are distinct and classification is reliable. ## 3. Parallelization Run subtasks simultaneously — either **sectioning** (independent pieces for speed) or **voting** (multiple perspectives/attempts for confidence). LLMs do better when each consideration gets its own focused call. ## 4. Orchestrator-workers A central LLM dynamically breaks down the task and delegates to worker calls, synthesizing results — the bridge toward full agents, and the skeleton of multi-agent systems ([multi-agent-systems](multi-agent-systems.md)). ## 5. Evaluator-optimizer One call generates, another evaluates and feeds back, looping — useful when you have clear evaluation criteria and iteration measurably helps. These compose: a router can front a chain whose middle step parallelizes. Keep agents ([workflows-vs-agents](workflows-vs-agents.md)) for what genuinely can't be pre-structured; 12-factor's "own your control flow" makes the same argument from the infrastructure side ([control-flow-and-state](control-flow-and-state.md)). --- title: "Workflows vs Agents" type: concept tags: [agents, workflows, architecture, definitions] updated: 2026-06-10 confidence: high sources: [raw/web_community-building-effective-ai-agents-anthropic.md] --- # Workflows vs Agents The field's most-cited architectural distinction (Anthropic, "Building effective agents", Dec 2024): everything is an **agentic system**, but — - **Workflows** — LLMs and tools orchestrated through *predefined code paths*. You know the steps in advance; the LLM fills in the steps. - **Agents** — the LLM *dynamically directs its own process and tool usage*, deciding the path at runtime. ## The core finding Across dozens of production teams, **the most successful implementations used simple, composable patterns — not complex frameworks or specialized libraries**. Start with plain LLM calls; add a workflow pattern when a task demands it; only graduate to an autonomous agent when the path genuinely can't be predicted (open-ended, dynamic, path-dependent work — the canonical example being research, see [multi-agent-systems](multi-agent-systems.md)). ## Choosing | Situation | Build | |---|---| | Steps known, output structured | Single call / prompt chain | | Distinct input categories | Routing workflow | | Path unpredictable, many turns | Agent (tools in a loop) | The named workflow patterns: [workflow-patterns](workflow-patterns.md). The same "agents are just programs — keep the deterministic parts deterministic" stance is the through-line of [12-factor-agents](../entities/twelve-factor-agents.md). --- title: "12-Factor Agents (HumanLayer)" type: entity tags: [12-factor, humanlayer, principles, reference] updated: 2026-06-10 confidence: high sources: [raw/github_doc-readme-md.md, raw/github_issue-use-00-notation-for-factor-markdowns.md] --- # 12-Factor Agents (HumanLayer) `humanlayer/12-factor-agents` — "Principles for building reliable LLM applications", the agent-era homage to Heroku's 12-factor apps. Code Apache-2.0, content CC BY-SA 4.0; maintained by HumanLayer (whose product is the factor-11 pitch — [human-in-the-loop](../concepts/human-in-the-loop.md)); accompanied by conference-talk and deep-dive videos. ## The twelve factors → wiki coverage | # | Factor | Page | |---|---|---| | 1 | Natural language → tool calls | [tool-design](../concepts/tool-design.md) | | 2 | Own your prompts | [context-engineering](../concepts/context-engineering.md) | | 3 | Own your context window | [context-engineering](../concepts/context-engineering.md) | | 4 | Tools are structured outputs | [tool-design](../concepts/tool-design.md) | | 5 | Unify execution & business state | [control-flow-and-state](../concepts/control-flow-and-state.md) | | 6 | Launch/pause/resume | [control-flow-and-state](../concepts/control-flow-and-state.md) | | 7 | Contact humans with tools | [human-in-the-loop](../concepts/human-in-the-loop.md) | | 8 | Own your control flow | [control-flow-and-state](../concepts/control-flow-and-state.md) | | 9 | Compact errors | [reliability-factors](../concepts/reliability-factors.md) | | 10 | Small, focused agents | [reliability-factors](../concepts/reliability-factors.md) | | 11 | Trigger from anywhere | [human-in-the-loop](../concepts/human-in-the-loop.md) | | 12 | Stateless reducer | [control-flow-and-state](../concepts/control-flow-and-state.md) | ## Repo notes `content/` holds one markdown per factor; files exist under both `factor-N` and zero-padded `factor-0N` names (the tracker has an open issue to standardize on 00-notation) — this corpus mirrors both, so prefer the `factor-0N` variants when citing. --- title: "Activity Log" type: log --- # Activity Log Append-only record of all wiki changes. ## Format Each entry follows this format: ``` ### YYYY-MM-DD HH:MM — [Action Type] - **Source/Trigger**: what initiated the action - **Pages created**: list of new pages - **Pages updated**: list of updated pages - **Notes**: any contradictions flagged, decisions made ``` --- ### 2026-04-08 00:00 — Setup - **Source/Trigger**: Repository initialized - **Pages created**: index.md, log.md, dashboard.md, analytics.md, flashcards.md - **Pages updated**: none - **Notes**: Empty knowledge base ready for first source ingestion ### 2026-06-10 00:00 — Initial curation (medium rung) - **Source/Trigger**: 31 raw sources (12-factor-agents + 4 Anthropic essays + Weng/Huyen surveys) - **Pages created**: 9 concepts, 1 entity (twelve-factor-agents), 1 summary (corpus-catalog), 1 synthesis (convergent-principles) - **Pages updated**: index.md - **Notes**: LangGraph concepts fetch returned 0 files (upstream restructure) — gap recorded in corpus-catalog. convergent-principles confidence:medium (interpretive crosswalk). --- ## 2026-06-10 — removed Obsidian scaffolding from the served wiki Deleted `analytics.md`, `dashboard.md`, `flashcards.md` (Obsidian plugin pages — Dataview/Charts View/Spaced Repetition markup, unusable when served as plain Markdown to agents) and the `journal/` scaffold (template only). `CLAUDE.md` directory layout updated: production/planning material lives at repo root, never under `wiki/` (everything under `wiki/` is served publicly). --- title: "Corpus Catalog" type: summary tags: [catalog, sources, map, reference] updated: 2026-06-10 confidence: high sources: [raw/github_doc-readme-md.md, raw/web_community-building-effective-ai-agents-anthropic.md] --- # Corpus Catalog Patterns domain (not a software product). 31 raw sources across three source families: | Family | Raw files | Wiki coverage | |---|---|---| | 12-factor-agents (HumanLayer) | github_doc-readme-md + github_doc-content-factor-{01..12} (duplicated under factor-N and factor-0N names; prefer 0N) + 1 tracker issue | [twelve-factor-agents](../entities/twelve-factor-agents.md) + factor pages: [tool-design](../concepts/tool-design.md), [context-engineering](../concepts/context-engineering.md), [control-flow-and-state](../concepts/control-flow-and-state.md), [human-in-the-loop](../concepts/human-in-the-loop.md), [reliability-factors](../concepts/reliability-factors.md) | | Anthropic engineering essays | building-effective-ai-agents (Dec 2024), how-we-built-our-multi-agent-research-system (Jun 2025), effective-context-engineering (Sep 2025), writing-effective-tools (Sep 2025) | [workflows-vs-agents](../concepts/workflows-vs-agents.md), [workflow-patterns](../concepts/workflow-patterns.md), [multi-agent-systems](../concepts/multi-agent-systems.md), [context-engineering](../concepts/context-engineering.md), [tool-design](../concepts/tool-design.md) | | Surveys | llm-powered-autonomous-agents (Lilian Weng, 2023), agents (Chip Huyen, 2025) | [planning-memory-evaluation](../concepts/planning-memory-evaluation.md) | Gap note: LangGraph concept docs were specced but the fetch returned no files (docs restructured upstream) — graph-framework perspective is currently represented only via the framework-skepticism discussion in [convergent-principles](../syntheses/convergent-principles.md); candidate for a future gather. --- title: "Convergent Principles Across Sources" type: synthesis tags: [principles, crosswalk, synthesis, design] updated: 2026-06-10 confidence: medium sources: [raw/web_community-building-effective-ai-agents-anthropic.md, raw/github_doc-readme-md.md, raw/web_community-how-we-built-our-multi-agent-research-system-anthropic.md, raw/web_community-effective-context-engineering-for-ai-agents-anthropic.md, raw/web_community-llm-powered-autonomous-agents-lil-log.md] --- # Convergent Principles Across Sources Where independent sources — a practitioner manifesto (12-factor), a lab's customer-derived essays (Anthropic), and academic-leaning surveys (Weng, Huyen) — arrive at the same conclusions. Confidence medium: the crosswalk is interpretive; claims live in the linked pages. ## 1. Determinism by default, autonomy by exception Anthropic: prefer simple composable workflows; agents only for unpredictable paths. 12-factor: own your control flow, agents are just programs. Same rule from opposite directions — *spend model autonomy only where code can't go*. ([workflows-vs-agents](../concepts/workflows-vs-agents.md), [control-flow-and-state](../concepts/control-flow-and-state.md)) ## 2. Context is the scarce resource Anthropic's context-engineering essay ("critical but finite"), factor 3 ("everything is context engineering"), Weng's memory component — three vocabularies for one budget. ([context-engineering](../concepts/context-engineering.md)) ## 3. Many small contexts beat one big one Factor 10 (3–20 steps max, reliability argument) ≍ orchestrator-workers (architecture argument) ≍ research subagents as parallel compression (capability argument). ([reliability-factors](../concepts/reliability-factors.md), [multi-agent-systems](../concepts/multi-agent-systems.md)) ## 4. Tools are interfaces, and interfaces need engineering Factor 4 demystifies (structured output + deterministic code); Anthropic's tool essay professionalizes (eval-driven tool iteration, agents optimizing their own tools). ([tool-design](../concepts/tool-design.md)) ## 5. Humans are a tool call, not an interrupt Factor 7/11's structured human contact is what Anthropic's approval-gated production systems implement. ([human-in-the-loop](../concepts/human-in-the-loop.md)) ## Open disagreement worth tracking Framework value: 12-factor is explicitly framework-skeptical (factors 2, 3, 8); graph frameworks (LangGraph et al.) argue the loop *should* be a managed abstraction. The Anthropic essays side with the skeptics for simple cases while their own products are frameworks of a kind. Unresolved; design accordingly.