1. Focus

Narrow the agent’s world to what matters; what remains is the right context.

Max: 30 points

Focus is what you exclude; context is what you include. Inseparable — focus without context is blindness, context without focus is noise. Narrow the agent’s world to what matters, then ensure what remains is structured, relevant, and current.

Ordered as substrate → task-level → external knowledge → internal knowledge → signal capture.

#	Criterion	0	1	2	3
1.1	`PL1-corpus-taxonomy` Corpus taxonomy, filing, indexing — every document in the project corpus has an unambiguous type (epic, investigation, feature spec, ADR, runbook, research doc, spike), is filed in a predictable location by that type, and is indexed for agent retrieval. An agent should be able to answer “what investigations exist for this subsystem?” or “what is the current feature spec for X?” without guessing at file locations or scanning raw directories	No taxonomy; document type ambiguous from filename alone; documents scattered across ad-hoc locations; no index. Agent cannot reliably locate or classify documents	Informal conventions exist (naming patterns, rough folder structure) but inconsistently applied; some document types are distinguishable, others are not; no index — retrieval requires human navigation or broad search	Explicit type system enforced: every document carries a type marker (frontmatter field, filename prefix, or designated folder per type); filing structure is consistent and documented; corpus is indexed and agent-queryable by type, project, and recency. Humans and agents can reliably find what they need	Taxonomy evolves with use: new document types extracted from observed patterns and formalised; stale or merged types deprecated with migration; retrieval success rate tracked; filing gaps (documents created outside the taxonomy) auto-flagged and remediated
1.2	`PL1-codebase-scoping` Codebase-aware scoping — agent is pointed at the relevant subset of the codebase for a given task, not the whole surface area; boundaries are structurally enforced, not advisory	Agent sees everything	Partial path hints; boundaries informal and not enforced	Explicit, structurally-enforced context boundaries per task type — sparse-checkout patterns for monorepos, MCP tool scoping per task, or equivalent mechanism ensures the agent operates on the declared subset	Scoping rules learn from agent failure patterns — when an agent needed context it didn’t have, the scope rules update
1.3	`PL1-task-decomposition` Task decomposition — work is broken into bugs / features / epics / investigations as documents, not just tickets	No structure	Linear tickets only	Structured doc-as-task with clear scope; each of at least `{investigation, feature, bug fix, tech research, spike}` has its own template with type-appropriate required fields (e.g. investigation templates include incident reference, reproduction steps, and timeline; feature templates include acceptance criteria and scope boundaries)	Past task structures inform new task templates; templates improve with use — template drift is tracked, recurring shapes produce reusable templates, and the template set itself evolves (new types added, stale ones deprecated)
1.4	`PL1-tech-research` Tech research precedes implementation — solution space is narrowed before coding starts	Agent searches the web mid-task	Sometimes researched by human first	Tech research is a first-class task type with its own output doc	Past research is indexed and retrieved before launching new research; negative findings prevent re-evaluation; research corpus compounds across the portfolio
1.5	`PL1-primary-source-access` Primary source access — agent has first-class access to authoritative documentation for every platform, protocol, and major dependency: Apple dev docs, Swift/language API refs, vendor SDKs, specifications (OCPI / OCPP / OAuth). Must be in agent-consumable form (MCP, indexed markdown, llms.txt) — PDFs and JS-rendered SPAs don’t count. Prevents the silent failure mode where agents fall back to training cutoff or web-search blog quality	Agent relies on training cutoff and web search; critical sources are PDFs or JS-rendered SPAs the agent can’t parse; frequent silent hallucination	Some sources accessible (GitHub READMEs, markdown-native vendors); critical stack components still inaccessible (Apple docs, protocol PDFs); agent falls back to training data with no flag	All major stack components have agent-accessible primary sources: MCPs for proprietary docs (swift-docs-mcp, apple-docs-mcp), markdown conversions for specs (ocpp.md, ocpi.md), llms.txt for vendors; agent defaults to primary source over training	Source freshness tracked — upstream releases trigger reindex; missing sources auto-flagged when agent encounters them; primary-source retrieval rate measured; training-data-fallback rate trends toward zero
1.6	`PL1-decision-records` Decision records (ADRs) — architecture and technology decisions captured with reasoning, alternatives considered, and context at time of decision; retrievable before related changes	No decision history; agents re-derive or contradict past choices	Some decisions documented informally (Slack, meeting notes)	ADRs are a first-class artifact; agent retrieves relevant ADRs before making architecture-adjacent changes	ADR retrieval is logged; decisions that get re-litigated despite existing ADRs are flagged; decision-recurrence rate trends toward zero
1.7	`PL1-design-intent` Design intent accessible — Figma specs, design system docs, component library, and UX guidelines available as agent context for UI/UX work	No design reference; agent guesses at visual intent	Design files exist but not agent-accessible (locked in Figma, not exported)	Design tokens, component specs, and layout guidelines exported and indexed as agent context	Design drift detected — agent output compared against design spec; recurring deviations inform design-system updates or prompt refinements
1.8	`PL1-documentation-loop` Documentation loop — operational and product docs — runbooks (ops / infra), feature specs, user guides, admin and dev docs exist, are current, and are consumed by agents. Produced with the work that needs them, and retrievable as agent context for downstream work	Docs are an afterthought; tribal knowledge for ops	Some docs exist; rarely referenced by agents; runbooks present but stale	Both operational and product docs are living; agents cite them in task output and PRs; indexed and retrievable as agent context	Access patterns logged; gaps and stale entries auto-flagged; docs version alongside features; deprecation cascades automatically; doc retrieval rate tracked
1.9	`PL1-stakeholder-context` Client / stakeholder context — per-client preferences, business constraints, IP boundaries, compliance posture, and relationship history captured and retrievable. Distinct from 1.8 (operational and product docs) — this is relationship knowledge	No client context captured; agent treats all projects as generic	Informal knowledge in Slack / email / head of key people	Per-client context captured in structured form (preferences, IP boundaries, compliance requirements, stakeholder map); retrievable as agent context before client-facing work	Client context evolves with each engagement; decisions affecting client relationships logged; cross-client patterns extracted while preserving tenant boundaries
1.10	`PL1-real-world-feedback` Real-world feedback loop — structured signal from user reviews, support tickets, bug reports, meeting notes, and app store ratings enters the agent’s context pool. The focus is signal quality: bug reports enriched with environment / version / reproduction; meeting notes processed with participant / topic metadata; reviews classified by feature area. A raw “it’s broken” note is noise; a structured repro is focus. Ingestion is the last boundary before external content becomes persistent agent context; both instruction-shaped content (`PL4-prompt-injection-defence`) and personal information (`PL4-pii-masking`) are sanitised here, not downstream. (Automation of the ingestion loop itself is scored in `PL5-signal-driven-tasks`.)	No feedback capture; raw noise in inboxes and Slack	Some signal captured but unstructured; raw tickets, unparsed reviews	Signal is enriched / structured before entering context: bug reports carry env / version / repro; reviews classified; meeting notes tagged with participants and topics. Ingestion sanitisation is two-layered — instruction-shaped content handled per `PL4-prompt-injection-defence`, and PII stripped or pseudonymised at the ingestion boundary per `PL4-pii-masking` (raw personal data from feedback sources does not enter persistent agent context)	Structure quality improves over time; enrichment rules evolve from retrieval patterns; signal-noise ratio measured and trends down

Recipes that advance criteria in this pillar

Each recipe is an abstract pattern that moves one or more criteria. Recipes that advance the same criterion are grouped together. A criterion with no listed recipe is a gap the canon has not yet named a known-good pattern for.

PL1-corpus-taxonomy — Corpus taxonomy, filing, indexing