dev-context-engineering

Context Engineering Use this skill to design repo-native agent context that is portable, high-signal, and maintainable. It owns the context model, migration path, maturity assessment, and context-graph discipline across , runtime-specific layers, specs, rules, hooks, compiled markdown knowledge bases, and related artifacts. Quick Reference | Task | Use | |------|-----| | Portable repo instructions | the skill, references/fast-track-guide.md | | Spec and plan flow | docs-ai-prd, dev-workflow-planning | | Context graph design | references/context-graph-guide.md, , | | Hot-tier staleness + super…

| head -5)\n if [ -n \"$UNSIGNED\" ]; then\n echo \"::error::Unsigned commits detected. All commits must be signed (GPG or SSH).\"\n echo \"$UNSIGNED\"\n exit 1\n fi\n echo \"All commits are signed.\"\n\n secrets-detection:\n name: Secrets Detection\n runs-on: ubuntu-latest\n steps:\n - uses: actions/checkout@v4\n with:\n fetch-depth: 0\n\n - name: Run gitleaks\n uses: gitleaks/gitleaks-action@v2\n env:\n GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}\n\n sast-scanning:\n name: Static Analysis\n runs-on: ubuntu-latest\n steps:\n - uses: actions/checkout@v4\n\n - name: Run Semgrep\n uses: semgrep/semgrep-action@v1\n with:\n config: >-\n p/security-audit\n p/secrets\n p/owasp-top-ten\n env:\n SEMGREP_APP_TOKEN: ${{ secrets.SEMGREP_APP_TOKEN }}\n\n pii-detection:\n name: PII Pattern Detection\n runs-on: ubuntu-latest\n steps:\n - uses: actions/checkout@v4\n\n - name: Scan for PII patterns in changed files\n run: |\n # Get changed files\n CHANGED_FILES=$(git diff --name-only origin/main...HEAD 2>/dev/null || git diff --name-only HEAD~1)\n\n # PII patterns to detect (conservative, high-precision)\n PII_PATTERNS=(\n '[0-9]{2}/[0-9]{2}/[0-9]{4}' # UK date format (potential DOB)\n '[A-Z]{2}[0-9]{6}[A-Z]' # UK National Insurance Number\n '[0-9]{4}[[:space:]][0-9]{4}[[:space:]][0-9]{4}[[:space:]][0-9]{4}' # Card number format\n 'password[[:space:]]*=[[:space:]]*[\"\\x27][^\"\\x27]+' # Hardcoded passwords\n )\n\n FOUND=false\n for file in $CHANGED_FILES; do\n [ ! -f \"$file\" ] && continue\n # Skip binary files and known safe files\n case \"$file\" in\n *.png|*.jpg|*.gif|*.ico|*.woff|*.lock|*.sum) continue ;;\n esac\n\n for pattern in \"${PII_PATTERNS[@]}\"; do\n if grep -qE \"$pattern\" \"$file\" 2>/dev/null; then\n echo \"::warning file=$file::Potential PII pattern detected: $pattern\"\n FOUND=true\n fi\n done\n done\n\n if $FOUND; then\n echo \"::error::PII patterns detected in changed files. Review findings above.\"\n echo \"If these are false positives (e.g., test data), add inline comments explaining why.\"\n exit 1\n fi\n echo \"No PII patterns detected.\"\n\n ai-disclosure:\n name: AI Disclosure Check\n runs-on: ubuntu-latest\n if: github.event_name == 'pull_request'\n steps:\n - name: Check PR body for AI disclosure\n env:\n PR_BODY: ${{ github.event.pull_request.body }}\n run: |\n if [ -z \"$PR_BODY\" ]; then\n echo \"::error::PR description is empty. Please use the PR template with AI disclosure section.\"\n exit 1\n fi\n\n # Check for AI disclosure section\n if ! echo \"$PR_BODY\" | grep -qi \"AI.*Involvement\\|AI.*Disclosure\\|AI.*Tools.*Used\"; then\n echo \"::error::PR description missing AI Involvement Disclosure section.\"\n echo \"Please use the PR template and complete the AI disclosure checklist.\"\n exit 1\n fi\n\n # Check for human verification checklist\n if ! echo \"$PR_BODY\" | grep -qi \"Human.*Verification\\|Verification.*Checklist\"; then\n echo \"::warning::PR description may be missing the Human Verification Checklist.\"\n fi\n\n echo \"AI disclosure section found in PR description.\"\n\n dependency-scan:\n name: Dependency Vulnerability Scan\n runs-on: ubuntu-latest\n steps:\n - uses: actions/checkout@v4\n\n - name: Run dependency audit\n run: |\n # Detect package manager and run audit\n if [ -f \"package-lock.json\" ] || [ -f \"yarn.lock\" ]; then\n npm audit --audit-level=high 2>/dev/null || echo \"::warning::npm audit found vulnerabilities\"\n elif [ -f \"requirements.txt\" ] || [ -f \"Pipfile.lock\" ]; then\n pip install pip-audit 2>/dev/null && pip-audit 2>/dev/null || echo \"::warning::pip-audit found vulnerabilities\"\n elif [ -f \"go.sum\" ]; then\n go install golang.org/x/vuln/cmd/govulncheck@latest 2>/dev/null && govulncheck ./... 2>/dev/null || echo \"::warning::govulncheck found vulnerabilities\"\n else\n echo \"No recognized package manager found. Skipping dependency audit.\"\n fi\n\n compliance-summary:\n name: Compliance Summary\n runs-on: ubuntu-latest\n needs: [signed-commits, secrets-detection, sast-scanning, pii-detection, ai-disclosure, dependency-scan]\n if: always()\n steps:\n - name: Report compliance status\n run: |\n echo \"## FCA Compliance Gate Results\"\n echo \"\"\n echo \"| Check | Status |\"\n echo \"|-------|--------|\"\n echo \"| Signed Commits | ${{ needs.signed-commits.result }} |\"\n echo \"| Secrets Detection | ${{ needs.secrets-detection.result }} |\"\n echo \"| SAST Scanning | ${{ needs.sast-scanning.result }} |\"\n echo \"| PII Detection | ${{ needs.pii-detection.result }} |\"\n echo \"| AI Disclosure | ${{ needs.ai-disclosure.result }} |\"\n echo \"| Dependency Scan | ${{ needs.dependency-scan.result }} |\"\n\n # Fail if any critical check failed\n if [[ \"${{ needs.signed-commits.result }}\" == \"failure\" ]] || \\\n [[ \"${{ needs.secrets-detection.result }}\" == \"failure\" ]] || \\\n [[ \"${{ needs.sast-scanning.result }}\" == \"failure\" ]] || \\\n [[ \"${{ needs.pii-detection.result }}\" == \"failure\" ]] || \\\n [[ \"${{ needs.ai-disclosure.result }}\" == \"failure\" ]]; then\n echo \"::error::One or more compliance gates failed. PR cannot be merged.\"\n exit 1\n fi\n echo \"All compliance gates passed.\"\n","content_type":"application/yaml; charset=utf-8","language":"yaml","size":7262,"content_sha256":"afcd3cde9869b723222de5bec97ffb2235914061070709d758a3df02d89f56e6"},{"filename":"assets/pr-template-ai-disclosure.md","content":"> **Example template for a regulated fintech.** Swap rule IDs, regime references (FCA/EMI, SM&CR, SS1/23, IBS register), and gate steps for your own regulatory context before use. This is illustrative scaffolding, not legal or compliance advice.\n\n# Pull Request Template with AI Disclosure\n\n> Copy this file to `.github/pull_request_template.md` in every repository.\n\n```markdown\n## Summary\n\n\u003c!-- Brief description of what this PR does and why -->\n\n## Changes\n\n\u003c!-- Bulleted list of changes -->\n\n-\n\n## AI Involvement Disclosure\n\n### AI Tools Used\n\u003c!-- Check all that apply -->\n- [ ] Claude Code\n- [ ] Codex\n- [ ] Cursor\n- [ ] GitHub Copilot\n- [ ] Other: ___\n- [ ] No AI tools used\n\n### AI Role\n\u003c!-- Check all that apply -->\n- [ ] Generated code\n- [ ] Reviewed/analyzed code\n- [ ] Generated tests\n- [ ] Assisted debugging\n- [ ] Generated documentation\n- [ ] Planned implementation\n\n### Files Primarily AI-Generated\n\u003c!-- List files where >50% of the code was AI-generated, or write \"None\" -->\n\n-\n\n### Human Verification Checklist\n\u003c!-- All boxes must be checked before merge approval -->\n- [ ] I have read and understand all AI-generated code in this PR\n- [ ] I have verified the code works as intended (ran tests, manual testing)\n- [ ] I have reviewed for security concerns (injection, auth, data exposure)\n- [ ] I have checked compliance with coding standards and architecture patterns\n- [ ] I have verified no sensitive data (PII, credentials, card data) is included\n- [ ] I have confirmed the code does not introduce unintended side effects\n\n## Test Plan\n\n\u003c!-- How was this tested? -->\n\n- [ ] Unit tests added/updated\n- [ ] Integration tests added/updated\n- [ ] Manual testing performed\n- [ ] No testing needed (docs/config only)\n\n## Compliance\n\u003c!-- For changes to auth/, payments/, crypto/, compliance/ directories -->\n- [ ] Security review requested (if applicable)\n- [ ] Compliance review requested (if applicable)\n- [ ] N/A — no security-critical changes\n```\n","content_type":"text/markdown; charset=utf-8","language":"markdown","size":1966,"content_sha256":"569488c9fcfffc3470d9db72ee9b5a5b44fb6aa152b2a753eb942bb68b70d420"},{"filename":"data/sources.json","content":"{\n \"metadata\": {\n \"skill\": \"dev-context-engineering\",\n \"title\": \"Context Engineering for AI-Augmented Development\",\n \"description\": \"Curated sources for context-driven development with AI coding agents across single and multi-repo organizations. Covers context engineering foundations, AGENTS.md standard, paradigm shift evidence, tool documentation, multi-repo patterns, regulatory compliance, security tooling, and practitioner insights.\",\n \"last_updated\": \"2026-04-13\",\n \"updated\": \"2026-04-13\",\n \"version\": \"3.3\",\n \"total_sources\": 105,\n \"verified_on\": \"2026-03-21\",\n \"verification_policy\": \"Prefer official vendor docs, regulator pages, and primary research for volatile claims. Mark high-volatility sources explicitly.\"\n },\n \"external_sources\": [\n {\n \"name\": \"garrytan/gbrain\",\n \"url\": \"https://github.com/garrytan/gbrain\",\n \"commit_sha\": \"adb02b7826a010700efc968b18df8aaf17d8ffa1\",\n \"license\": \"MIT\",\n \"extracted_date\": \"2026-04-13\",\n \"patterns_used\": [\n \"context-resolver-pattern\",\n \"latent-vs-deterministic\",\n \"information-routing-rules\",\n \"durable-vs-replaceable-axis\"\n ],\n \"research_pack\": \"docs/research/2026-04-13-context-engineering-skill-scan.md\"\n },\n {\n \"name\": \"MemPalace/mempalace\",\n \"url\": \"https://github.com/MemPalace/mempalace\",\n \"commit_sha\": \"6614b9b4e71e67da2236493b036b7bf42ba2d55f\",\n \"license\": \"MIT\",\n \"extracted_date\": \"2026-04-13\",\n \"patterns_used\": [\n \"progressive-loading-tiers-l0-l3\",\n \"hot-layer-performance-budgets\",\n \"verbatim-raw-anti-summarization\"\n ],\n \"research_pack\": \"docs/research/2026-04-13-context-engineering-skill-scan.md\"\n }\n ],\n \"categories\": {\n \"knowledge_graph_methodology\": [\n {\n \"name\": \"Understand-Anything: Multi-Agent Knowledge Graph Pipeline\",\n \"url\": \"https://github.com/Lum1104/Understand-Anything\",\n \"type\": \"reference_implementation\",\n \"description\": \"Multi-agent pipeline using tree-sitter AST and LLM semantic enrichment to build JSON knowledge graphs from codebases. Adoptable patterns: graph-as-artifact (committable JSON), BFS traversal for focused context windows, 7-check automated validation, two-pass analysis (deterministic + LLM).\",\n \"relevance\": \"Influenced the context-graph schema and scan_context_artifacts.py design — specifically the graph-as-artifact pattern and validation check framework\",\n \"update_frequency\": \"occasional\",\n \"access\": \"open-source\",\n \"add_as_web_search\": false,\n \"verified_on\": \"2026-03-21\",\n \"volatility\": \"medium\",\n \"tags\": [\"knowledge-graph\", \"context-engineering\", \"reference-implementation\"]\n }\n ],\n \"context_engineering\": [\n {\n \"name\": \"Anthropic: Effective Context Engineering for AI Agents\",\n \"url\": \"https://www.anthropic.com/engineering/effective-context-engineering-for-coding-agents\",\n \"type\": \"documentation\",\n \"description\": \"Anthropic's official guide to context engineering for coding agents. Covers context retrieval, memory, tools, planning, and execution patterns.\",\n \"relevance\": \"Foundational framework for context design principles used throughout this skill\",\n \"update_frequency\": \"static\",\n \"access\": \"free\",\n \"add_as_web_search\": true,\n \"verified_on\": \"2026-03-13\",\n \"volatility\": \"medium\",\n \"tags\": [\"context-engineering\", \"anthropic\", \"agents\", \"foundational\"]\n },\n {\n \"name\": \"Martin Fowler: Context Engineering for Coding Agents\",\n \"url\": \"https://martinfowler.com/articles/exploring-gen-ai/context-engineering-coding-agents.html\",\n \"type\": \"article\",\n \"description\": \"Fowler's analysis of context engineering as an emerging discipline. Covers structured prompting, codebase context, and progressive disclosure.\",\n \"relevance\": \"Industry validation from a respected voice — establishes CE as engineering, not hacking\",\n \"update_frequency\": \"static\",\n \"access\": \"free\",\n \"add_as_web_search\": true,\n \"verified_on\": \"2026-03-13\",\n \"volatility\": \"low\",\n \"tags\": [\"context-engineering\", \"thought-leadership\", \"patterns\"]\n },\n {\n \"name\": \"The Context Development Lifecycle (CDLC)\",\n \"url\": \"https://jedi.be/blog/2025/06/02/the-context-development-lifecycle/\",\n \"type\": \"article\",\n \"description\": \"Generate-Evaluate-Distribute-Observe lifecycle for context artifacts. The continuous improvement loop for keeping context fresh.\",\n \"relevance\": \"Core CDLC framework referenced throughout this skill — the feedback loop that makes CE sustainable\",\n \"update_frequency\": \"static\",\n \"access\": \"free\",\n \"add_as_web_search\": true,\n \"tags\": [\"cdlc\", \"lifecycle\", \"context-engineering\", \"core\"]\n },\n {\n \"name\": \"Andrej Karpathy: Observations on Agentic Coding\",\n \"url\": \"https://karpathy.ai\",\n \"type\": \"article\",\n \"description\": \"Karpathy's observations on disciplined agentic coding patterns — surfacing assumptions, managing scope, pushing back on bad approaches\",\n \"relevance\": \"Source material for the canonical behavioral rules maintained in agents-memory: frameworks/shared-skills/skills/agents-memory/references/coding-behavior.md (standalone file) and frameworks/shared-skills/skills/agents-memory/references/memory-examples.md §Example 6 (inline template). The repo-root .claude/rules/coding-behavior.md is a symlink to the canonical file.\",\n \"derivative_source\": {\n \"name\": \"forrestchang/andrej-karpathy-skills\",\n \"url\": \"https://github.com/forrestchang/andrej-karpathy-skills\",\n \"commit_sha\": \"fb8fdb0aa74ccf587d2b666da7160e0d0eb94e6a\",\n \"license\": \"MIT\",\n \"extracted\": \"2026-04-15\",\n \"refinements_applied\": [\n \"goal transformation (vague task → verifiable goal)\",\n \"trace test (every changed line traces to user request)\",\n \"200-line rewrite heuristic\",\n \"orphan vs pre-existing dead code distinction\",\n \"tradeoff disclosure framing\",\n \"working-if success metric\"\n ]\n },\n \"update_frequency\": \"static\",\n \"access\": \"free\",\n \"add_as_web_search\": true,\n \"tags\": [\"agentic-coding\", \"discipline\", \"patterns\", \"karpathy\", \"behavioral-rules\"]\n },\n {\n \"name\": \"karpathy/autoresearch\",\n \"url\": \"https://github.com/karpathy/autoresearch\",\n \"type\": \"tool\",\n \"description\": \"Autonomous ML experiment agent with bounded modification surface, fixed eval metric, and git-as-experiment-ledger. The original autonomous improvement loop pattern.\",\n \"relevance\": \"Reference implementation for autonomous context improvement — defines the change→eval→keep/revert loop applied to CDLC\",\n \"update_frequency\": \"continuous\",\n \"access\": \"free\",\n \"add_as_web_search\": true,\n \"tags\": [\"autoresearch\", \"autonomous-improvement\", \"experiment-loop\", \"karpathy\"]\n },\n {\n \"name\": \"Simon Willison: Context Engineering Practices\",\n \"url\": \"https://simonwillison.net/tags/context-engineering/\",\n \"type\": \"article\",\n \"description\": \"Willison's ongoing documentation of context engineering patterns, tool comparisons, and practical tips\",\n \"relevance\": \"Practitioner-level insights on what works and what doesn't in daily CE practice\",\n \"update_frequency\": \"continuous\",\n \"access\": \"free\",\n \"add_as_web_search\": true,\n \"tags\": [\"context-engineering\", \"practitioner\", \"tips\"]\n },\n {\n \"name\": \"Sourcegraph: The Death of the Junior Developer (and the Rise of the Context Engineer)\",\n \"url\": \"https://sourcegraph.com/blog/the-death-of-the-junior-developer\",\n \"type\": \"article\",\n \"description\": \"Analysis of how AI agents change the role of developers, with context engineering as the new core skill\",\n \"relevance\": \"Role transformation evidence — supports paradigm-comparison.md role evolution section\",\n \"update_frequency\": \"static\",\n \"access\": \"free\",\n \"add_as_web_search\": true,\n \"tags\": [\"role-transformation\", \"context-engineering\", \"career\"]\n },\n {\n \"name\": \"Anthropic: Claude Code Memory and CLAUDE.md\",\n \"url\": \"https://docs.anthropic.com/en/docs/claude-code/memory\",\n \"type\": \"documentation\",\n \"description\": \"Official Claude Code documentation for memory files, imports, project memory, and directory-scoped guidance.\",\n \"relevance\": \"Authoritative guide for CLAUDE.md structure, imports, and repo-level memory patterns\",\n \"update_frequency\": \"continuous\",\n \"access\": \"free\",\n \"add_as_web_search\": true,\n \"verified_on\": \"2026-03-13\",\n \"volatility\": \"high\",\n \"tags\": [\"claude-code\", \"best-practices\", \"anthropic\"]\n },\n {\n \"name\": \"Codified Context: Infrastructure for AI Agents in a Complex Codebase\",\n \"url\": \"https://arxiv.org/abs/2602.20478\",\n \"type\": \"research\",\n \"description\": \"Three-tier memory architecture (hot constitution → specialist agents → cold MCP knowledge base) for 108K LOC codebase. 283 sessions over 70 days. Context infrastructure = 24.2% of codebase. Key finding: single-file manifests cannot scale beyond modest codebases.\",\n \"relevance\": \"Research validation of tiered context architecture — supports maturity progression from L1 (single file) to L3+ (agents + knowledge base)\",\n \"update_frequency\": \"static\",\n \"access\": \"free\",\n \"add_as_web_search\": true,\n \"tags\": [\"research\", \"three-tier\", \"mcp\", \"architecture\", \"context-infrastructure\"]\n },\n {\n \"name\": \"Manus: Context Engineering for AI Agents — Lessons from Building Manus\",\n \"url\": \"https://manus.im/blog/Context-Engineering-for-AI-Agents-Lessons-from-Building-Manus\",\n \"type\": \"article\",\n \"description\": \"Production patterns: KV-cache hit rate as primary metric (10x cost difference), masking over removal, file system as extended memory, attention through recitation (todo.md), preserving failure states, avoiding few-shot brittleness.\",\n \"relevance\": \"Advanced context optimization patterns applicable to CDLC Observe phase — cost and performance tuning\",\n \"update_frequency\": \"static\",\n \"access\": \"free\",\n \"add_as_web_search\": true,\n \"tags\": [\"manus\", \"production\", \"kv-cache\", \"optimization\", \"context-engineering\"]\n },\n {\n \"name\": \"Context Development Lifecycle: Your AI Agent Isn't Broken, Your Context Is\",\n \"url\": \"https://www.vibesparking.com/en/blog/ai/context-engineering/2026-03-04-context-development-lifecycle-optimizing-context-for-ai-coding-agents/\",\n \"type\": \"article\",\n \"description\": \"External validation of CDLC framework (Generate → Evaluate → Distribute → Observe). Key insight: 'Every new session = onboarding a hire who knows programming but nothing about your project.' Adds test-driven context development concept.\",\n \"relevance\": \"Independent validation of CDLC framework — confirms Generate-Evaluate-Distribute-Observe as industry-recognized lifecycle\",\n \"update_frequency\": \"static\",\n \"access\": \"free\",\n \"add_as_web_search\": true,\n \"tags\": [\"cdlc\", \"validation\", \"context-engineering\", \"lifecycle\"]\n }\n ],\n \"agents_md_standard\": [\n {\n \"name\": \"AGENTS.md Specification\",\n \"url\": \"https://agents.md\",\n \"type\": \"specification\",\n \"description\": \"The AGENTS.md standard for repository agent instructions. Defines file format, sections, and cross-tool compatibility.\",\n \"relevance\": \"Primary standard this entire skill builds upon — AGENTS.md is the source of truth\",\n \"update_frequency\": \"continuous\",\n \"access\": \"free\",\n \"add_as_web_search\": true,\n \"verified_on\": \"2026-03-13\",\n \"volatility\": \"medium\",\n \"tags\": [\"agents-md\", \"specification\", \"standard\", \"core\"]\n },\n {\n \"name\": \"AGENTS.md GitHub Repository\",\n \"url\": \"https://github.com/openai/agents.md\",\n \"type\": \"repository\",\n \"description\": \"Official repository for the AGENTS.md specification with examples and tooling\",\n \"relevance\": \"Reference implementation and examples of well-structured AGENTS.md files\",\n \"update_frequency\": \"continuous\",\n \"access\": \"free\",\n \"add_as_web_search\": false,\n \"verified_on\": \"2026-03-13\",\n \"volatility\": \"medium\",\n \"tags\": [\"agents-md\", \"examples\", \"reference\"]\n },\n {\n \"name\": \"GitHub Docs: Repository Custom Instructions and AGENTS.md\",\n \"url\": \"https://docs.github.com/en/copilot/how-tos/custom-instructions/adding-repository-custom-instructions-for-github-copilot\",\n \"type\": \"reference\",\n \"description\": \"Official GitHub documentation for repository instructions, path-specific instructions, and agent instruction files including AGENTS.md, CLAUDE.md, and GEMINI.md.\",\n \"relevance\": \"Primary-source evidence that GitHub/Copilot now supports layered repository context instead of a single file convention\",\n \"update_frequency\": \"continuous\",\n \"access\": \"free\",\n \"add_as_web_search\": true,\n \"verified_on\": \"2026-03-13\",\n \"volatility\": \"high\",\n \"tags\": [\"agents-md\", \"github\", \"custom-instructions\", \"support\"]\n },\n {\n \"name\": \"Agentic AI Foundation Stewardship via AGENTS.md\",\n \"url\": \"https://agents.md\",\n \"type\": \"article\",\n \"description\": \"The AGENTS.md site documents stewardship under the Agentic AI Foundation and provides the current specification and FAQ.\",\n \"relevance\": \"Use this instead of outdated secondary references when discussing AGENTS.md governance or stewardship\",\n \"update_frequency\": \"static\",\n \"access\": \"free\",\n \"add_as_web_search\": true,\n \"verified_on\": \"2026-03-13\",\n \"volatility\": \"medium\",\n \"tags\": [\"agents-md\", \"governance\", \"stewardship\"]\n },\n {\n \"name\": \"AGENTS.md Adoption Tracker\",\n \"url\": \"https://github.com/search?q=filename%3AAGENTS.md&type=code\",\n \"type\": \"reference\",\n \"description\": \"GitHub search showing AGENTS.md adoption across public repositories\",\n \"relevance\": \"Use only as a rough directional signal; do not rely on this search page for stable adoption metrics\",\n \"update_frequency\": \"continuous\",\n \"access\": \"free\",\n \"add_as_web_search\": false,\n \"verified_on\": \"2026-03-13\",\n \"volatility\": \"high\",\n \"tags\": [\"agents-md\", \"adoption\", \"metrics\"]\n },\n {\n \"name\": \"ETH Zurich: Evaluating AGENTS.md — Are Context Files Helpful for Coding Agents?\",\n \"url\": \"https://arxiv.org/abs/2602.11988\",\n \"type\": \"research\",\n \"description\": \"Empirical evaluation of context file effectiveness. 138 tasks, 4 models. LLM-generated files degrade performance by 3% and increase costs 20%+. Human-written files provide marginal +4% but raise costs 19%. Recommends limiting to non-inferable details only.\",\n \"relevance\": \"Critical research caveat for AGENTS.md authoring — validates 'quality over quantity' principle and progressive disclosure pattern\",\n \"update_frequency\": \"static\",\n \"access\": \"free\",\n \"add_as_web_search\": true,\n \"tags\": [\"research\", \"agents-md\", \"evaluation\", \"eth-zurich\", \"evidence\"]\n }\n ],\n \"paradigm_shift\": [\n {\n \"name\": \"OpenAI: Harness Engineering\",\n \"url\": \"https://openai.com/index/harness-engineering/\",\n \"type\": \"article\",\n \"description\": \"OpenAI's framework for organizing engineering work around AI agents — structured task descriptions, verification, feedback loops\",\n \"relevance\": \"Codex-side perspective on context-driven development; validates dual-agent approach\",\n \"update_frequency\": \"static\",\n \"access\": \"free\",\n \"add_as_web_search\": true,\n \"verified_on\": \"2026-03-13\",\n \"volatility\": \"low\",\n \"tags\": [\"codex\", \"openai\", \"harness-engineering\"]\n },\n {\n \"name\": \"GitHub spec-kit\",\n \"url\": \"https://github.com/github/spec-kit\",\n \"type\": \"repository\",\n \"description\": \"GitHub's toolkit for spec-driven AI development — templates, validation, best practices. Specs live in .specify/specs/\u003cfeature>/ as spec.md, plan.md, tasks.md. Install via uv tool install specify-cli.\",\n \"relevance\": \"L3 artifact pipeline in framework-selection-matrix; most-cited spec-driven framework as of April 2026 (~92k stars, GitHub-backed)\",\n \"update_frequency\": \"continuous\",\n \"access\": \"free\",\n \"add_as_web_search\": false,\n \"verified_on\": \"2026-05-01\",\n \"volatility\": \"low\",\n \"tags\": [\"spec-driven\", \"github\", \"tooling\", \"L3\"]\n },\n {\n \"name\": \"OpenSpec (Fission-AI)\",\n \"url\": \"https://github.com/Fission-AI/OpenSpec\",\n \"type\": \"repository\",\n \"description\": \"Community spec-driven framework. Specs live in openspec/changes/ as proposal.md, spec.md, design.md, tasks.md. Installs via npm i -g @fission-ai/openspec; commands /opsx:propose, /opsx:apply, /opsx:archive. Integrates ADRs alongside specs.\",\n \"relevance\": \"L3 artifact pipeline alternative to Spec Kit in framework-selection-matrix; npm-native, ADRs co-located\",\n \"update_frequency\": \"continuous\",\n \"access\": \"free\",\n \"add_as_web_search\": true,\n \"verified_on\": \"2026-05-01\",\n \"volatility\": \"medium\",\n \"tags\": [\"spec-driven\", \"community\", \"L3\"]\n },\n {\n \"name\": \"obra/superpowers\",\n \"url\": \"https://github.com/obra/superpowers\",\n \"type\": \"repository\",\n \"description\": \"Skills-based engineering methodology shipped as a folder of Markdown files. 14 documented skills (brainstorming, writing-plans, TDD, systematic-debugging, subagent-driven-development, two-stage code review, …). Plugin configs for Claude Code, Codex, Cursor, OpenCode, Copilot CLI, Gemini CLI. Skills enforce discipline at runtime (refuse-to-code-until-clarified).\",\n \"relevance\": \"L2 methodology layer in framework-selection-matrix; pick when discipline drift (TDD, debugging quality) is the bottleneck. ~150-175k stars, on Anthropic plugin marketplace.\",\n \"update_frequency\": \"continuous\",\n \"access\": \"free\",\n \"add_as_web_search\": true,\n \"verified_on\": \"2026-05-01\",\n \"volatility\": \"medium\",\n \"tags\": [\"skills\", \"methodology\", \"claude-code\", \"L2\"]\n },\n {\n \"name\": \"gsd-build/get-shit-done (GSD)\",\n \"url\": \"https://github.com/gsd-build/get-shit-done\",\n \"type\": \"repository\",\n \"description\": \"Context-engineering and lifecycle framework targeting context rot — quality degradation as the context window fills. Full mode: 59 skills + 33 subagents; minimal mode: 6 skills. Generates PROJECT.md, REQUIREMENTS.md, ROADMAP.md, STATE.md, phase docs. Installs via npx get-shit-done-cc@latest. Ships git hooks for automated context management.\",\n \"relevance\": \"L2 lifecycle / context-management layer in framework-selection-matrix; pick when context rot in long sessions is the bottleneck. ~59k stars.\",\n \"update_frequency\": \"continuous\",\n \"access\": \"free\",\n \"add_as_web_search\": true,\n \"verified_on\": \"2026-05-01\",\n \"volatility\": \"medium\",\n \"tags\": [\"context-management\", \"subagents\", \"lifecycle\", \"L2\"]\n },\n {\n \"name\": \"Anthropic Agent Skills overview\",\n \"url\": \"https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview\",\n \"type\": \"documentation\",\n \"description\": \"Anthropic's official skill system. A skill is a directory with SKILL.md (YAML frontmatter + instructions) plus optional scripts and reference files. Three-level progressive disclosure: metadata always loaded (~100 tokens), instructions on trigger (\u003c5k tokens), bundled resources on demand. Personal skills at ~/.claude/skills/, project skills at .claude/skills/.\",\n \"relevance\": \"L2 capability layer foundation in framework-selection-matrix; the substrate superpowers, GSD, and custom skills build on.\",\n \"update_frequency\": \"continuous\",\n \"access\": \"free\",\n \"add_as_web_search\": true,\n \"verified_on\": \"2026-05-01\",\n \"volatility\": \"medium\",\n \"tags\": [\"skills\", \"anthropic\", \"claude-code\", \"L2\"]\n },\n {\n \"name\": \"AGENTS.md spec\",\n \"url\": \"https://agents.md\",\n \"type\": \"documentation\",\n \"description\": \"Canonical spec for the AGENTS.md portable baseline. Single Markdown file at repo root that all major agents (Codex, Claude Code, Amp, Jules, Cursor, Factory) read natively. 32 KiB Codex limit. Stewarded by the Linux Foundation's Agentic AI Foundation.\",\n \"relevance\": \"L0 portable baseline in framework-selection-matrix; mandatory layer for cross-tool consistency\",\n \"update_frequency\": \"static\",\n \"access\": \"free\",\n \"add_as_web_search\": true,\n \"verified_on\": \"2026-05-01\",\n \"volatility\": \"low\",\n \"tags\": [\"agents-md\", \"portable-baseline\", \"linux-foundation\", \"L0\"]\n },\n {\n \"name\": \"Cursor rules documentation\",\n \"url\": \"https://cursor.com/docs/rules\",\n \"type\": \"documentation\",\n \"description\": \"Per-project and per-path instruction files for Cursor IDE using .mdc (Markdown Cursor) format with YAML frontmatter for conditional activation. Legacy .cursorrules root file deprecated. Global rules at ~/.cursor/rules/.\",\n \"relevance\": \"L1 runtime-specific layer in framework-selection-matrix; mandatory for Cursor-primary teams (Cursor does not read AGENTS.md natively)\",\n \"update_frequency\": \"continuous\",\n \"access\": \"free\",\n \"add_as_web_search\": true,\n \"verified_on\": \"2026-05-01\",\n \"volatility\": \"medium\",\n \"tags\": [\"cursor\", \"ide\", \"rules\", \"L1\"]\n },\n {\n \"name\": \"GitHub Copilot custom instructions\",\n \"url\": \"https://docs.github.com/copilot/customizing-copilot/adding-custom-instructions-for-github-copilot\",\n \"type\": \"documentation\",\n \"description\": \"Copilot repo-wide instructions at .github/copilot-instructions.md. Path-specific instructions via .github/**/*.instructions.md with applyTo frontmatter (added July 2025). Agent-specific instructions added November 2025.\",\n \"relevance\": \"L1 runtime-specific layer in framework-selection-matrix; mandatory for Copilot-primary teams\",\n \"update_frequency\": \"continuous\",\n \"access\": \"free\",\n \"add_as_web_search\": true,\n \"verified_on\": \"2026-05-01\",\n \"volatility\": \"medium\",\n \"tags\": [\"copilot\", \"github\", \"rules\", \"L1\"]\n },\n {\n \"name\": \"Cline rules documentation\",\n \"url\": \"https://docs.cline.bot/features/cline-rules\",\n \"type\": \"documentation\",\n \"description\": \".clinerules file or .clinerules/ directory injected into Cline's system prompt on every request. Inactive rules at clinerules-bank/. v3.13 added a per-rule toggle UI.\",\n \"relevance\": \"L1 runtime-specific layer in framework-selection-matrix; required for Cline (VS Code extension) workflows\",\n \"update_frequency\": \"continuous\",\n \"access\": \"free\",\n \"add_as_web_search\": true,\n \"verified_on\": \"2026-05-01\",\n \"volatility\": \"medium\",\n \"tags\": [\"cline\", \"vscode\", \"rules\", \"L1\"]\n },\n {\n \"name\": \"Aider conventions\",\n \"url\": \"https://aider.chat/docs/usage/conventions.html\",\n \"type\": \"documentation\",\n \"description\": \"CONVENTIONS.md loaded into every Aider session via .aider.conf.yml. Documents language preferences, style, testing standards, git practices. Community-editable conventions at github.com/Aider-AI/conventions.\",\n \"relevance\": \"L1 runtime-specific layer in framework-selection-matrix; required for Aider pair-programming workflows\",\n \"update_frequency\": \"continuous\",\n \"access\": \"free\",\n \"add_as_web_search\": true,\n \"verified_on\": \"2026-05-01\",\n \"volatility\": \"low\",\n \"tags\": [\"aider\", \"cli\", \"conventions\", \"L1\"]\n },\n {\n \"name\": \"Martin Fowler / Böckeler: SDD Tools — Three Levels of Spec-Driven Development\",\n \"url\": \"https://martinfowler.com/articles/exploring-gen-ai/sdd-3-tools.html\",\n \"type\": \"article\",\n \"description\": \"Defines three maturity levels for spec-driven development: Spec-First (write then discard), Spec-Anchored (spec lives alongside code), Spec-as-Source (spec is primary artifact, code regenerated). Evaluates tooling landscape.\",\n \"relevance\": \"Canonical SDD maturity framework referenced in the Spec-Driven Development section of this skill\",\n \"update_frequency\": \"static\",\n \"access\": \"free\",\n \"add_as_web_search\": true,\n \"verified_on\": \"2026-03-17\",\n \"volatility\": \"low\",\n \"tags\": [\"spec-driven\", \"maturity\", \"martin-fowler\", \"methodology\"]\n },\n {\n \"name\": \"Julián De Angelis: The Spec Is the New Code — A Guide to Spec Driven Development\",\n \"url\": \"https://x.com/juliandeangeIis/status/2033303156340240481\",\n \"type\": \"article\",\n \"description\": \"SDD methodology guide from MercadoLibre's GenAI Technical Leader. Covers the ambiguity problem, ecosystem convergence (Spec Kit, Symphony, Ralph Loop), the specify-plan-task-implement process, tradeoffs (2-3x token cost for dramatically better results), and rollout to 20,000 developers.\",\n \"relevance\": \"Practitioner case study at scale — validates SDD methodology with 5,000+ workshop participants and production evidence\",\n \"update_frequency\": \"static\",\n \"access\": \"free\",\n \"add_as_web_search\": true,\n \"verified_on\": \"2026-03-17\",\n \"volatility\": \"low\",\n \"tags\": [\"spec-driven\", \"case-study\", \"mercadolibre\", \"methodology\", \"scale\"]\n },\n {\n \"name\": \"METR: Measuring AI Ability to Complete Long Tasks\",\n \"url\": \"https://metr.org/blog/2025-07-01-measuring-ai-ability-to-complete-long-tasks/\",\n \"type\": \"article\",\n \"description\": \"Research showing unstructured AI coding ('vibe coding') is 19% slower with 1.7x more issues than structured approaches\",\n \"relevance\": \"Key evidence for why context engineering matters — data-backed case against vibe coding\",\n \"update_frequency\": \"static\",\n \"access\": \"free\",\n \"add_as_web_search\": true,\n \"tags\": [\"research\", \"vibe-coding\", \"evidence\", \"quantitative\"]\n },\n {\n \"name\": \"Gartner: AI-Augmented Software Engineering Predictions\",\n \"url\": \"https://www.gartner.com/en/articles/ai-augmented-development\",\n \"type\": \"article\",\n \"description\": \"Gartner predictions on AI-augmented development — 75% of enterprise developers using AI assistants by 2028\",\n \"relevance\": \"Strategic context for organizational adoption planning\",\n \"update_frequency\": \"continuous\",\n \"access\": \"free\",\n \"add_as_web_search\": true,\n \"tags\": [\"predictions\", \"enterprise\", \"adoption\", \"strategy\"]\n },\n {\n \"name\": \"McKinsey: The Economic Potential of Generative AI in Software Engineering\",\n \"url\": \"https://www.mckinsey.com/capabilities/mckinsey-digital/our-insights/the-economic-potential-of-generative-ai\",\n \"type\": \"article\",\n \"description\": \"McKinsey analysis of AI impact on developer productivity — 20-45% time savings on coding tasks\",\n \"relevance\": \"Business case data for CDLC investment and SDLC compression claims\",\n \"update_frequency\": \"static\",\n \"access\": \"free\",\n \"add_as_web_search\": true,\n \"tags\": [\"research\", \"productivity\", \"business-case\"]\n },\n {\n \"name\": \"Stack Overflow Developer Survey: AI Tools Adoption\",\n \"url\": \"https://survey.stackoverflow.co/\",\n \"type\": \"reference\",\n \"description\": \"Annual developer survey tracking AI tool adoption rates, tool preferences, and satisfaction\",\n \"relevance\": \"Industry benchmarks for AI tool adoption — useful for making the case internally\",\n \"update_frequency\": \"continuous\",\n \"access\": \"free\",\n \"add_as_web_search\": true,\n \"tags\": [\"survey\", \"adoption\", \"benchmarks\", \"industry\"]\n },\n {\n \"name\": \"Google DeepMind: AI-Assisted Software Engineering Study\",\n \"url\": \"https://deepmind.google/discover/blog/\",\n \"type\": \"article\",\n \"description\": \"Google's research on AI coding agent productivity including Gemini-based development\",\n \"relevance\": \"Multi-vendor evidence for context-driven development effectiveness\",\n \"update_frequency\": \"continuous\",\n \"access\": \"free\",\n \"add_as_web_search\": true,\n \"tags\": [\"research\", \"google\", \"productivity\", \"evidence\"]\n },\n {\n \"name\": \"Anthropic: 2026 Agentic Coding Trends Report\",\n \"url\": \"https://resources.anthropic.com/2026-agentic-coding-trends-report\",\n \"type\": \"report\",\n \"description\": \"Eight trends reshaping software engineering: role shift to agent coordination, multi-agent teams, end-to-end agent runs (hours/days), agents learning to ask for help, spread beyond engineers, shorter timelines, security implications. AI in 60% of work but only 0-20% fully delegated.\",\n \"relevance\": \"Authoritative industry report validating paradigm shift — data-backed trend evidence from the primary agent platform\",\n \"update_frequency\": \"static\",\n \"access\": \"free\",\n \"add_as_web_search\": true,\n \"tags\": [\"anthropic\", \"trends\", \"report\", \"multi-agent\", \"paradigm-shift\"]\n },\n {\n \"name\": \"Shopify CEO: AI Hiring Freeze Memo\",\n \"url\": \"https://www.cnbc.com/2025/04/07/shopify-ceo-says-staffers-need-to-prove-jobs-cant-be-done-by-ai-before-asking-for-more-headcount.html\",\n \"type\": \"article\",\n \"description\": \"Shopify CEO Tobi Lutke's April 2025 internal memo: teams must demonstrate why AI cannot do the work before requesting headcount. AI usage added to performance reviews.\",\n \"relevance\": \"Highest-profile public statement of AI-first hiring policy — direct evidence for team size paradigm shift\",\n \"update_frequency\": \"static\",\n \"access\": \"free\",\n \"add_as_web_search\": true,\n \"verified_on\": \"2026-03-16\",\n \"volatility\": \"low\",\n \"tags\": [\"shopify\", \"hiring-freeze\", \"team-transformation\", \"policy\", \"paradigm-shift\"]\n },\n {\n \"name\": \"Anthropic: How AI Is Transforming Work at Anthropic\",\n \"url\": \"https://www.anthropic.com/news/how-ai-is-transforming-work-at-anthropic\",\n \"type\": \"article\",\n \"description\": \"Anthropic internal data: 90% of Claude Code written by Claude, engineers use Claude in 59% of work (up from 28%), 50% productivity boost, 5 PRs/engineer/day. Most employees can fully delegate only 0-20% of work.\",\n \"relevance\": \"Primary-source quantitative evidence from the leading agent platform — both the promise and the limits\",\n \"update_frequency\": \"static\",\n \"access\": \"free\",\n \"add_as_web_search\": true,\n \"verified_on\": \"2026-03-16\",\n \"volatility\": \"low\",\n \"tags\": [\"anthropic\", \"internal-data\", \"productivity\", \"team-transformation\", \"evidence\"]\n },\n {\n \"name\": \"Pragmatic Engineer: Future of Software Engineering with AI\",\n \"url\": \"https://newsletter.pragmaticengineer.com/p/the-future-of-software-engineering\",\n \"type\": \"article\",\n \"description\": \"Gergely Orosz on the 'one-pizza team' replacing the 'two-pizza team.' Predicts decrease in specialization, consolidation into 3-4 full-stack engineers. Warns AI makes teams 'dysfunctional faster' if culture is poor.\",\n \"relevance\": \"Origin of 'one-pizza team' taxonomy — key thought leader framing the shift with both optimism and caveats\",\n \"update_frequency\": \"static\",\n \"access\": \"free\",\n \"add_as_web_search\": true,\n \"verified_on\": \"2026-03-16\",\n \"volatility\": \"low\",\n \"tags\": [\"pragmatic-engineer\", \"one-pizza-team\", \"team-transformation\", \"taxonomy\", \"counterpoint\"]\n },\n {\n \"name\": \"Satya Nadella: AI Writes 30% of Microsoft's Code\",\n \"url\": \"https://www.theverge.com/news/648818/satya-nadella-microsoft-ai-code-llamacon\",\n \"type\": \"article\",\n \"description\": \"Nadella at LlamaCon (April 2025): 30% of Microsoft code is AI-generated. Describes a 'new production function' where AI generates code without proportionally more engineers.\",\n \"relevance\": \"Direct evidence from a $3T company — validates the scale of AI code generation in big tech\",\n \"update_frequency\": \"static\",\n \"access\": \"free\",\n \"add_as_web_search\": true,\n \"verified_on\": \"2026-03-16\",\n \"volatility\": \"low\",\n \"tags\": [\"microsoft\", \"nadella\", \"ai-generated-code\", \"big-tech\", \"paradigm-shift\"]\n },\n {\n \"name\": \"CNBC: Y Combinator Startups Fastest Growing in Fund History\",\n \"url\": \"https://www.cnbc.com/2025/03/06/y-combinators-latest-batch-of-startups-is-on-pace-to-be-the-fastest-growing-in-fund-history.html\",\n \"type\": \"article\",\n \"description\": \"Y Combinator 2025 batch on pace to be fastest-growing in fund history. 88% of startups are AI-native. 25% have 95%+ AI-generated codebases.\",\n \"relevance\": \"VC ecosystem evidence for AI-native startup economics — validates 'lean team + AI' investment thesis\",\n \"update_frequency\": \"static\",\n \"access\": \"free\",\n \"add_as_web_search\": true,\n \"verified_on\": \"2026-03-16\",\n \"volatility\": \"low\",\n \"tags\": [\"y-combinator\", \"vc\", \"startups\", \"ai-native\", \"investment\"]\n },\n {\n \"name\": \"Every.to: The Two-Slice Team\",\n \"url\": \"https://every.to/napkin-math/the-two-slice-team\",\n \"type\": \"article\",\n \"description\": \"Concept of the 'two-slice team' (1-2 people). Every.to runs 4 products each operated by 1 person with 99% AI-written code. Explores the economics and psychology of extreme team minimalism.\",\n \"relevance\": \"Origin of 'two-slice team' taxonomy — demonstrates the solo-operator model with real revenue data\",\n \"update_frequency\": \"static\",\n \"access\": \"free\",\n \"add_as_web_search\": true,\n \"verified_on\": \"2026-03-16\",\n \"volatility\": \"low\",\n \"tags\": [\"every-to\", \"two-slice-team\", \"solo-operator\", \"taxonomy\", \"ai-native\"]\n },\n {\n \"name\": \"Fortune: Klarna CEO Admits AI Cuts Went Too Far\",\n \"url\": \"https://fortune.com/2025/05/22/klarna-ceo-humans-ai/\",\n \"type\": \"article\",\n \"description\": \"Klarna CEO Sebastian Siemiatkowski: chatbot gave generic responses, couldn't handle nuance. Company began rehiring. Average pay rose 60% ($126K → $203K) as workforce skewed senior.\",\n \"relevance\": \"Critical counterpoint — the highest-profile AI-driven layoff reversal. Essential caveat for team transformation planning.\",\n \"update_frequency\": \"static\",\n \"access\": \"free\",\n \"add_as_web_search\": true,\n \"verified_on\": \"2026-03-16\",\n \"volatility\": \"low\",\n \"tags\": [\"klarna\", \"reversal\", \"counterpoint\", \"team-transformation\", \"cautionary\"]\n },\n {\n \"name\": \"MLQ: Klarna CEO Regrets AI-Driven Layoffs\",\n \"url\": \"https://www.mlq.ai/klarna-ceo-regrets-ai-layoffs/\",\n \"type\": \"article\",\n \"description\": \"Analysis of Klarna's 2026 reversal: cut from 5,527 to 2,907 employees, AI replaced 853 FTEs, then admitted going too far. 55% of companies report regretting AI-driven layoffs.\",\n \"relevance\": \"Quantitative details on the Klarna reversal — the '55% regret rate' data point\",\n \"update_frequency\": \"static\",\n \"access\": \"free\",\n \"add_as_web_search\": true,\n \"verified_on\": \"2026-03-16\",\n \"volatility\": \"low\",\n \"tags\": [\"klarna\", \"reversal\", \"quantitative\", \"regret-rate\", \"team-transformation\"]\n },\n {\n \"name\": \"Faros AI: The Real Impact of AI on Coding Productivity\",\n \"url\": \"https://www.faros.ai/blog/the-real-impact-of-ai-on-coding-productivity\",\n \"type\": \"article\",\n \"description\": \"Study of 10,000+ developers: high-AI teams completed 21% more tasks but PR review time increased 91%, bugs per developer up 9%, PR sizes up 154%. Bottleneck shifted from writing to reviewing.\",\n \"relevance\": \"Critical quantitative counterpoint — shows AI throughput gains come with review and quality costs\",\n \"update_frequency\": \"static\",\n \"access\": \"free\",\n \"add_as_web_search\": true,\n \"verified_on\": \"2026-03-16\",\n \"volatility\": \"low\",\n \"tags\": [\"faros-ai\", \"productivity\", \"counterpoint\", \"quantitative\", \"review-bottleneck\"]\n },\n {\n \"name\": \"Lean AI Leaderboard: Revenue Per Employee\",\n \"url\": \"https://www.leanaileaderboard.com/\",\n \"type\": \"reference\",\n \"description\": \"Tracks revenue-per-employee metrics for AI-native companies. AI-native average: $3.48M RPE vs traditional SaaS $200K-$610K (5.7x gap). Midjourney $4.1M, Cursor $3.3M.\",\n \"relevance\": \"Quantitative foundation for AI-native RPE claims and the team-size economic argument\",\n \"update_frequency\": \"continuous\",\n \"access\": \"free\",\n \"add_as_web_search\": true,\n \"verified_on\": \"2026-03-16\",\n \"volatility\": \"high\",\n \"tags\": [\"rpe\", \"economics\", \"ai-native\", \"metrics\", \"leaderboard\"]\n },\n {\n \"name\": \"Optimum Partners: Engineering Management in the Age of AI (2026)\",\n \"url\": \"https://optimumpartners.co/engineering-management-2026/\",\n \"type\": \"article\",\n \"description\": \"Introduces the 'Centaur Pod' model: 3-person team (architect + 2 AI reliability engineers + agents). Predicts engineering management evolves from people management to agent orchestration.\",\n \"relevance\": \"Origin of 'Centaur Pod' taxonomy — specific team structure for AI-augmented engineering\",\n \"update_frequency\": \"static\",\n \"access\": \"free\",\n \"add_as_web_search\": true,\n \"verified_on\": \"2026-03-16\",\n \"volatility\": \"low\",\n \"tags\": [\"centaur-pod\", \"team-structure\", \"taxonomy\", \"engineering-management\"]\n },\n {\n \"name\": \"Gartner: 80% of Engineering Workforce Must Upskill by 2027\",\n \"url\": \"https://www.gartner.com/en/newsroom/press-releases/2024-10-29-gartner-says-by-2027-80-percent-of-the-software-engineering-workforce-will-need-to-upskill\",\n \"type\": \"article\",\n \"description\": \"Gartner prediction (Oct 2024): 80% of the software engineering workforce will need to upskill in AI-augmented development practices by 2027.\",\n \"relevance\": \"Sets the scale of the transition challenge — upskilling is non-trivial and affects team planning timelines\",\n \"update_frequency\": \"static\",\n \"access\": \"free\",\n \"add_as_web_search\": true,\n \"verified_on\": \"2026-03-16\",\n \"volatility\": \"low\",\n \"tags\": [\"gartner\", \"upskilling\", \"workforce\", \"prediction\", \"transition\"]\n },\n {\n \"name\": \"CNBC: Duolingo 'AI-First' Company\",\n \"url\": \"https://www.cnbc.com/2025/09/02/duolingo-ai-first-company.html\",\n \"type\": \"article\",\n \"description\": \"Duolingo's AI-first policy: contractors cut in waves, CEO reports '4 or 5 times as much content in the same time,' 148 AI-written courses delivered.\",\n \"relevance\": \"Evidence of AI-first transformation in a consumer tech company — content generation as a proxy for engineering output\",\n \"update_frequency\": \"static\",\n \"access\": \"free\",\n \"add_as_web_search\": true,\n \"verified_on\": \"2026-03-16\",\n \"volatility\": \"low\",\n \"tags\": [\"duolingo\", \"ai-first\", \"content-generation\", \"team-transformation\"]\n },\n {\n \"name\": \"Sam Altman: The One-Person Unicorn\",\n \"url\": \"https://fortune.com/2024/02/04/sam-altman-predicts-one-person-unicorn-ai/\",\n \"type\": \"article\",\n \"description\": \"Sam Altman's prediction that AI will enable solo founders to build billion-dollar companies. Origin of the 'one-person unicorn' concept.\",\n \"relevance\": \"Origin of the 'one-person unicorn' term — sets the aspirational endpoint of the team-size spectrum\",\n \"update_frequency\": \"static\",\n \"access\": \"free\",\n \"add_as_web_search\": true,\n \"verified_on\": \"2026-03-16\",\n \"volatility\": \"low\",\n \"tags\": [\"altman\", \"one-person-unicorn\", \"prediction\", \"solo-founder\"]\n },\n {\n \"name\": \"Meta: Zuckerberg Predicts Mid-Level Engineer AI\",\n \"url\": \"https://www.entrepreneur.com/business-news/mark-zuckerberg-says-meta-will-have-ai-that-is-as-good-as/487133\",\n \"type\": \"article\",\n \"description\": \"Zuckerberg (Jan 2025): 'AI that can effectively be a mid-level engineer.' Meta cut 5% of staff while investing in AI infrastructure.\",\n \"relevance\": \"Big tech CEO framing AI as replacing mid-level engineering work — shapes hiring and team composition decisions\",\n \"update_frequency\": \"static\",\n \"access\": \"free\",\n \"add_as_web_search\": true,\n \"verified_on\": \"2026-03-16\",\n \"volatility\": \"low\",\n \"tags\": [\"meta\", \"zuckerberg\", \"mid-level-engineer\", \"big-tech\", \"prediction\"]\n }\n ],\n \"tool_documentation\": [\n {\n \"name\": \"Claude Code Documentation\",\n \"url\": \"https://docs.anthropic.com/en/docs/claude-code\",\n \"type\": \"documentation\",\n \"description\": \"Official Claude Code CLI documentation — hooks, subagents, worktrees, MCP, memory files\",\n \"relevance\": \"Primary agent tool — all CDLC patterns built on Claude Code capabilities\",\n \"update_frequency\": \"continuous\",\n \"access\": \"free\",\n \"add_as_web_search\": true,\n \"tags\": [\"claude-code\", \"anthropic\", \"cli\", \"primary\"]\n },\n {\n \"name\": \"Claude Code GitHub Repository\",\n \"url\": \"https://github.com/anthropics/claude-code\",\n \"type\": \"repository\",\n \"description\": \"Claude Code source repository with issues, discussions, and changelog\",\n \"relevance\": \"Track feature updates, bug reports, and community patterns\",\n \"update_frequency\": \"continuous\",\n \"access\": \"free\",\n \"add_as_web_search\": false,\n \"tags\": [\"claude-code\", \"github\", \"changelog\"]\n },\n {\n \"name\": \"OpenAI: Introducing Codex\",\n \"url\": \"https://openai.com/index/introducing-codex/\",\n \"type\": \"documentation\",\n \"description\": \"OpenAI's Codex launch and product overview covering agentic coding workflows, repository setup, and execution model.\",\n \"relevance\": \"Primary-source overview for Codex positioning and workflow assumptions\",\n \"update_frequency\": \"continuous\",\n \"access\": \"free\",\n \"add_as_web_search\": true,\n \"verified_on\": \"2026-03-13\",\n \"volatility\": \"high\",\n \"tags\": [\"codex\", \"openai\", \"cloud-agent\", \"primary\"]\n },\n {\n \"name\": \"Cursor Documentation\",\n \"url\": \"https://docs.cursor.com\",\n \"type\": \"documentation\",\n \"description\": \"Cursor IDE with AI integration — .cursor/rules, agent mode, context management\",\n \"relevance\": \"Supplementary tool — reads .cursor/rules for IDE-level context\",\n \"update_frequency\": \"continuous\",\n \"access\": \"free\",\n \"add_as_web_search\": false,\n \"tags\": [\"cursor\", \"ide\", \"supplementary\"]\n },\n {\n \"name\": \"GitHub Copilot Documentation\",\n \"url\": \"https://docs.github.com/en/copilot\",\n \"type\": \"documentation\",\n \"description\": \"GitHub Copilot documentation covering repository instructions, path-specific instructions, AGENTS.md support, coding agent, and custom agents.\",\n \"relevance\": \"Primary-source documentation for GitHub-native context files and agent workflows\",\n \"update_frequency\": \"continuous\",\n \"access\": \"free\",\n \"add_as_web_search\": false,\n \"verified_on\": \"2026-03-13\",\n \"volatility\": \"high\",\n \"tags\": [\"copilot\", \"github\", \"supplementary\"]\n },\n {\n \"name\": \"Windsurf (Codeium) Documentation\",\n \"url\": \"https://docs.codeium.com\",\n \"type\": \"documentation\",\n \"description\": \"Windsurf IDE agent with Cascade — .windsurfrules context file support\",\n \"relevance\": \"Alternative AI IDE — context patterns translate across tools\",\n \"update_frequency\": \"continuous\",\n \"access\": \"free\",\n \"add_as_web_search\": false,\n \"tags\": [\"windsurf\", \"codeium\", \"supplementary\"]\n },\n {\n \"name\": \"Amazon Q Developer Documentation\",\n \"url\": \"https://docs.aws.amazon.com/amazonq/latest/qdeveloper-ug/\",\n \"type\": \"documentation\",\n \"description\": \"AWS AI coding assistant — workspace context, guardrails, enterprise features\",\n \"relevance\": \"Enterprise alternative — relevant for AWS-heavy organizations evaluating tools\",\n \"update_frequency\": \"continuous\",\n \"access\": \"free\",\n \"add_as_web_search\": false,\n \"tags\": [\"amazon-q\", \"aws\", \"enterprise\"]\n },\n {\n \"name\": \"Google Gemini CLI / Code Assist\",\n \"url\": \"https://github.com/google-gemini/gemini-cli\",\n \"type\": \"repository\",\n \"description\": \"Google's CLI agent for coding — GEMINI.md context file, agent mode\",\n \"relevance\": \"Third major agent platform — multi-agent strategy may include Gemini\",\n \"update_frequency\": \"continuous\",\n \"access\": \"free\",\n \"add_as_web_search\": false,\n \"tags\": [\"gemini\", \"google\", \"cli\"]\n },\n {\n \"name\": \"GitHub Docs: Enterprise Management for Agents\",\n \"url\": \"https://docs.github.com/en/copilot/concepts/agents/enterprise-management\",\n \"type\": \"documentation\",\n \"description\": \"Official GitHub documentation for enterprise agent management, governance controls, and organization-wide administration.\",\n \"relevance\": \"Use this for GitHub enterprise governance claims instead of unstable branding or marketing names\",\n \"update_frequency\": \"continuous\",\n \"access\": \"free\",\n \"add_as_web_search\": true,\n \"verified_on\": \"2026-03-13\",\n \"volatility\": \"high\",\n \"tags\": [\"github\", \"enterprise\", \"audit\", \"governance\", \"agents\"]\n },\n {\n \"name\": \"VS Code: Context Engineering Guide\",\n \"url\": \"https://code.visualstudio.com/docs/copilot/guides/context-engineering-guide\",\n \"type\": \"documentation\",\n \"description\": \"VS Code guidance for layered context: AGENTS.md, custom instructions, prompt files, and custom chat modes / agents.\",\n \"relevance\": \"Primary-source evidence that editor workflows now converge on layered repository context\",\n \"update_frequency\": \"continuous\",\n \"access\": \"free\",\n \"add_as_web_search\": true,\n \"verified_on\": \"2026-03-13\",\n \"volatility\": \"high\",\n \"tags\": [\"vscode\", \"copilot\", \"context-engineering\", \"agents\"]\n },\n {\n \"name\": \"context-hub (chub) — Curated API Docs and Skills for Coding Agents\",\n \"url\": \"https://github.com/andrewyng/context-hub\",\n \"type\": \"repository\",\n \"description\": \"CLI tool providing agents with curated, versioned API documentation from a searchable CDN. Dual content model (Docs vs Skills), self-improving loop via annotations and feedback, progressive disclosure, multi-source trust signaling (official/maintainer/community), Agent Skills spec compatible. 500+ library entries.\",\n \"relevance\": \"External knowledge distribution tool complementing repo-native context — fills the gap between AGENTS.md (repo context) and web search (unreliable). Supports the Cross-Tool Context Model's external knowledge layer.\",\n \"update_frequency\": \"continuous\",\n \"access\": \"free\",\n \"add_as_web_search\": false,\n \"verified_on\": \"2026-03-17\",\n \"volatility\": \"medium\",\n \"tags\": [\"context-distribution\", \"external-knowledge\", \"api-docs\", \"tooling\", \"andrew-ng\"]\n }\n ],\n \"multi_repo_patterns\": [\n {\n \"name\": \"Spine Pattern for Polyrepo Coordination\",\n \"url\": \"https://www.thoughtworks.com/radar/techniques/spine-model\",\n \"type\": \"article\",\n \"description\": \"Coordination pattern for managing shared concerns across many repositories without coupling\",\n \"relevance\": \"Architectural pattern for 100+ repo organizations — basis for coordination repo pattern\",\n \"update_frequency\": \"static\",\n \"access\": \"free\",\n \"add_as_web_search\": true,\n \"tags\": [\"multi-repo\", \"coordination\", \"architecture\", \"spine\"]\n },\n {\n \"name\": \"InnerSource Patterns\",\n \"url\": \"https://patterns.innersourcecommons.org/\",\n \"type\": \"reference\",\n \"description\": \"Community patterns for internal open source practices — governance, contribution, review\",\n \"relevance\": \"Governance model for shared context artifacts across teams\",\n \"update_frequency\": \"continuous\",\n \"access\": \"free\",\n \"add_as_web_search\": false,\n \"tags\": [\"innersource\", \"governance\", \"patterns\"]\n },\n {\n \"name\": \"GitHub Template Repositories\",\n \"url\": \"https://docs.github.com/en/repositories/creating-and-managing-repositories/creating-a-template-repository\",\n \"type\": \"documentation\",\n \"description\": \"GitHub's template repository feature for standardizing new repo creation\",\n \"relevance\": \"Mechanism for Pattern 2 (Template Repository + Sync) in multi-repo strategy\",\n \"update_frequency\": \"continuous\",\n \"access\": \"free\",\n \"add_as_web_search\": false,\n \"tags\": [\"github\", \"template\", \"bootstrapping\"]\n },\n {\n \"name\": \"Git Submodules Documentation\",\n \"url\": \"https://git-scm.com/book/en/v2/Git-Tools-Submodules\",\n \"type\": \"documentation\",\n \"description\": \"Official Git documentation for submodules — version-pinned shared code across repos\",\n \"relevance\": \"Distribution mechanism for shared context: version-pinned, explicit updates\",\n \"update_frequency\": \"static\",\n \"access\": \"free\",\n \"add_as_web_search\": false,\n \"tags\": [\"git\", \"submodules\", \"distribution\"]\n },\n {\n \"name\": \"Monorepo vs Polyrepo: Comparison and Strategies\",\n \"url\": \"https://www.atlassian.com/git/tutorials/monorepos\",\n \"type\": \"article\",\n \"description\": \"Atlassian's comparison of monorepo vs polyrepo strategies with trade-offs\",\n \"relevance\": \"Background for choosing coordination pattern based on repo structure\",\n \"update_frequency\": \"static\",\n \"access\": \"free\",\n \"add_as_web_search\": false,\n \"tags\": [\"monorepo\", \"polyrepo\", \"strategy\"]\n },\n {\n \"name\": \"GitHub Actions: Reusable Workflows\",\n \"url\": \"https://docs.github.com/en/actions/sharing-automations/reusing-workflows\",\n \"type\": \"documentation\",\n \"description\": \"GitHub Actions reusable workflows for sharing CI/CD patterns across repositories\",\n \"relevance\": \"Mechanism for distributing compliance gates across 100 repos\",\n \"update_frequency\": \"continuous\",\n \"access\": \"free\",\n \"add_as_web_search\": false,\n \"tags\": [\"github-actions\", \"ci-cd\", \"distribution\"]\n }\n ],\n \"security_tooling\": [\n {\n \"name\": \"Gitleaks: Secret Detection\",\n \"url\": \"https://github.com/gitleaks/gitleaks\",\n \"type\": \"tool\",\n \"description\": \"SAST tool for detecting hardcoded secrets in git repos — API keys, tokens, passwords\",\n \"relevance\": \"Required compliance gate in fca-compliance-gate.yml — blocks merge on secrets\",\n \"update_frequency\": \"continuous\",\n \"access\": \"free\",\n \"add_as_web_search\": false,\n \"tags\": [\"security\", \"secrets\", \"sast\", \"ci-cd\"]\n },\n {\n \"name\": \"Semgrep\",\n \"url\": \"https://semgrep.dev\",\n \"type\": \"tool\",\n \"description\": \"Lightweight static analysis for finding bugs, security issues, and enforcing code standards\",\n \"relevance\": \"SAST scanning in compliance gate — security-audit, secrets, OWASP top 10 rulesets\",\n \"update_frequency\": \"continuous\",\n \"access\": \"free\",\n \"add_as_web_search\": true,\n \"tags\": [\"security\", \"sast\", \"static-analysis\", \"ci-cd\"]\n },\n {\n \"name\": \"GitHub CodeQL\",\n \"url\": \"https://codeql.github.com\",\n \"type\": \"tool\",\n \"description\": \"GitHub's semantic code analysis engine for finding security vulnerabilities\",\n \"relevance\": \"Alternative to Semgrep for SAST scanning in compliance gates\",\n \"update_frequency\": \"continuous\",\n \"access\": \"free\",\n \"add_as_web_search\": false,\n \"tags\": [\"security\", \"codeql\", \"github\", \"sast\"]\n },\n {\n \"name\": \"Snyk\",\n \"url\": \"https://snyk.io\",\n \"type\": \"tool\",\n \"description\": \"Developer security platform — dependency scanning, container scanning, code analysis\",\n \"relevance\": \"Dependency vulnerability scanning in compliance gate; alternative to Dependabot\",\n \"update_frequency\": \"continuous\",\n \"access\": \"free\",\n \"add_as_web_search\": false,\n \"tags\": [\"security\", \"dependencies\", \"vulnerabilities\"]\n },\n {\n \"name\": \"GitHub Dependabot\",\n \"url\": \"https://docs.github.com/en/code-security/dependabot\",\n \"type\": \"documentation\",\n \"description\": \"Automated dependency updates and security alerts for GitHub repositories\",\n \"relevance\": \"Dependency vulnerability scanning — complements gitleaks and SAST\",\n \"update_frequency\": \"continuous\",\n \"access\": \"free\",\n \"add_as_web_search\": false,\n \"tags\": [\"security\", \"dependencies\", \"github\", \"automation\"]\n },\n {\n \"name\": \"OWASP Top 10\",\n \"url\": \"https://owasp.org/www-project-top-ten/\",\n \"type\": \"reference\",\n \"description\": \"OWASP Top 10 web application security risks — the baseline security checklist\",\n \"relevance\": \"Referenced in Semgrep ruleset (p/owasp-top-ten); baseline for security rules\",\n \"update_frequency\": \"static\",\n \"access\": \"free\",\n \"add_as_web_search\": false,\n \"tags\": [\"security\", \"owasp\", \"baseline\"]\n },\n {\n \"name\": \"OWASP LLM Top 10\",\n \"url\": \"https://owasp.org/www-project-top-10-for-large-language-model-applications/\",\n \"type\": \"reference\",\n \"description\": \"OWASP Top 10 risks specific to LLM applications — prompt injection, data leakage, etc.\",\n \"relevance\": \"AI-specific security risks relevant when using coding agents in regulated environments\",\n \"update_frequency\": \"continuous\",\n \"access\": \"free\",\n \"add_as_web_search\": true,\n \"tags\": [\"security\", \"owasp\", \"llm\", \"ai-security\"]\n },\n {\n \"name\": \"NIST AI Risk Management Framework\",\n \"url\": \"https://www.nist.gov/artificial-intelligence/ai-risk-management-framework\",\n \"type\": \"reference\",\n \"description\": \"NIST framework for managing AI system risks — governance, mapping, measuring, managing\",\n \"relevance\": \"Complements FCA requirements; US equivalent for AI risk governance\",\n \"update_frequency\": \"static\",\n \"access\": \"free\",\n \"add_as_web_search\": true,\n \"tags\": [\"nist\", \"ai-risk\", \"governance\", \"framework\"]\n },\n {\n \"name\": \"NIST AI Agent Standards Initiative\",\n \"url\": \"https://www.nist.gov/caisi/ai-agent-standards-initiative\",\n \"type\": \"reference\",\n \"description\": \"NIST CAISI initiative for AI agent standards and security. Covers agent identity, authorization, governance controls, and security research.\",\n \"relevance\": \"Emerging regulatory framework — complements FCA requirements with US-aligned standards for multinational organizations\",\n \"update_frequency\": \"continuous\",\n \"access\": \"free\",\n \"add_as_web_search\": true,\n \"verified_on\": \"2026-03-13\",\n \"volatility\": \"high\",\n \"tags\": [\"nist\", \"standards\", \"ai-agents\", \"governance\", \"security\"]\n },\n {\n \"name\": \"Northflank: How to Sandbox AI Agents — Isolation Patterns 2026\",\n \"url\": \"https://northflank.com/blog/how-to-sandbox-ai-agents\",\n \"type\": \"article\",\n \"description\": \"Comprehensive sandbox isolation patterns: microVMs (Firecracker ~125ms boot, Kata), gVisor (syscall interception), standard containers. Network isolation, resource limits, zero-trust permissions. Sandboxed agents reduce security incidents 90%.\",\n \"relevance\": \"Security isolation patterns for regulated agent execution — extends Stripe devbox pattern with vendor-neutral options\",\n \"update_frequency\": \"static\",\n \"access\": \"free\",\n \"add_as_web_search\": true,\n \"tags\": [\"sandbox\", \"isolation\", \"microvm\", \"security\", \"agents\"]\n }\n ],\n \"fca_emi_compliance\": [\n {\n \"name\": \"FCA PS21/3: Building Operational Resilience\",\n \"url\": \"https://www.fca.org.uk/publications/policy-statements/ps21-3-building-operational-resilience\",\n \"type\": \"reference\",\n \"description\": \"FCA policy on operational resilience — Important Business Services, impact tolerances, scenario testing\",\n \"relevance\": \"AI tools as critical dependencies in IBS; manual fallback pathways required\",\n \"update_frequency\": \"static\",\n \"access\": \"free\",\n \"add_as_web_search\": true,\n \"tags\": [\"fca\", \"operational-resilience\", \"regulation\", \"core\"]\n },\n {\n \"name\": \"FCA/PRA SS1/23: Model Risk Management\",\n \"url\": \"https://www.bankofengland.co.uk/prudential-regulation/publication/2023/model-risk-management-principles-for-banks\",\n \"type\": \"reference\",\n \"description\": \"Model risk management principles — AI-generated code as model output requiring inventory, validation, monitoring\",\n \"relevance\": \"Legal basis for tracking AI-generated code artifacts in model risk register\",\n \"update_frequency\": \"static\",\n \"access\": \"free\",\n \"add_as_web_search\": true,\n \"tags\": [\"model-risk\", \"fca\", \"pra\", \"governance\", \"core\"]\n },\n {\n \"name\": \"FCA SM&CR Regime\",\n \"url\": \"https://www.fca.org.uk/firms/senior-managers-certification-regime\",\n \"type\": \"reference\",\n \"description\": \"Senior Managers and Certification Regime — named accountability for regulated activities\",\n \"relevance\": \"Named Senior Manager must be accountable for AI tool governance; 'AI did it' is not a defense\",\n \"update_frequency\": \"continuous\",\n \"access\": \"free\",\n \"add_as_web_search\": false,\n \"tags\": [\"smcr\", \"accountability\", \"fca\", \"core\"]\n },\n {\n \"name\": \"FCA PS24/16: Critical Third Parties\",\n \"url\": \"https://www.fca.org.uk/publications/policy-statements/ps24-16-oversight-critical-third-parties\",\n \"type\": \"reference\",\n \"description\": \"Critical Third Party oversight regime — AI providers (Anthropic, OpenAI) may be designated CTPs\",\n \"relevance\": \"Portability requirement — dual-agent strategy (Claude Code + Codex) avoids vendor lock-in\",\n \"update_frequency\": \"static\",\n \"access\": \"free\",\n \"add_as_web_search\": true,\n \"tags\": [\"ctp\", \"third-party\", \"fca\", \"portability\"]\n },\n {\n \"name\": \"ICO: Guidance on AI and Data Protection\",\n \"url\": \"https://ico.org.uk/for-organisations/uk-gdpr-guidance-and-resources/artificial-intelligence/\",\n \"type\": \"reference\",\n \"description\": \"UK Information Commissioner's Office guidance on AI systems and data protection\",\n \"relevance\": \"DPIA requirements, lawful basis for AI code generation, context files must not contain PII\",\n \"update_frequency\": \"continuous\",\n \"access\": \"free\",\n \"add_as_web_search\": true,\n \"tags\": [\"gdpr\", \"ico\", \"data-protection\", \"ai\", \"core\"]\n },\n {\n \"name\": \"FCA: Artificial Intelligence Update\",\n \"url\": \"https://www.fca.org.uk/publications/corporate-documents/ai-update\",\n \"type\": \"reference\",\n \"description\": \"FCA's latest position on AI use by regulated firms — expectations, good practice, supervisory focus\",\n \"relevance\": \"Regulatory direction on AI adoption in financial services; shapes governance requirements\",\n \"update_frequency\": \"continuous\",\n \"access\": \"free\",\n \"add_as_web_search\": true,\n \"tags\": [\"fca\", \"ai-policy\", \"governance\", \"direction\"]\n },\n {\n \"name\": \"EBA: Guidelines on AI Use in Financial Services\",\n \"url\": \"https://www.eba.europa.eu/activities/single-rulebook/regulatory-activities/model-validation\",\n \"type\": \"reference\",\n \"description\": \"European Banking Authority guidelines on AI/ML models in financial services\",\n \"relevance\": \"EU counterpart to FCA guidance — relevant for firms operating across UK and EU\",\n \"update_frequency\": \"continuous\",\n \"access\": \"free\",\n \"add_as_web_search\": false,\n \"tags\": [\"eba\", \"eu\", \"financial-services\", \"regulation\"]\n },\n {\n \"name\": \"UK Government: Pro-Innovation Approach to AI Regulation\",\n \"url\": \"https://www.gov.uk/government/publications/ai-regulation-a-pro-innovation-approach\",\n \"type\": \"reference\",\n \"description\": \"UK government white paper on AI regulation principles — context-specific, proportionate approach\",\n \"relevance\": \"Regulatory landscape for AI in UK — informs how FCA/PRA apply AI oversight\",\n \"update_frequency\": \"static\",\n \"access\": \"free\",\n \"add_as_web_search\": true,\n \"tags\": [\"uk-government\", \"ai-regulation\", \"policy\"]\n },\n {\n \"name\": \"FINRA 2026: GenAI Regulatory Oversight — AI Agents Section\",\n \"url\": \"https://www.finra.org/rules-guidance/guidance/reports/2026-finra-annual-regulatory-oversight-report/gen-ai\",\n \"type\": \"reference\",\n \"description\": \"FINRA's first dedicated AI agents section. Defines agents as 'systems capable of autonomous actions on behalf of users.' Requires: prompt/output logging, model version tracking, human-in-the-loop review, agent action audit trails, guardrails to restrict behaviors.\",\n \"relevance\": \"US financial regulator guidance — validates FCA approach and adds specificity on audit trail requirements for AI coding agents\",\n \"update_frequency\": \"static\",\n \"access\": \"free\",\n \"add_as_web_search\": true,\n \"tags\": [\"finra\", \"regulation\", \"ai-agents\", \"audit-trail\", \"financial-services\"]\n }\n ],\n \"data_protection\": [\n {\n \"name\": \"IAPP: GDPR and Agentic AI\",\n \"url\": \"https://iapp.org/resources/article/gdpr-and-agentic-ai/\",\n \"type\": \"article\",\n \"description\": \"IAPP analysis of GDPR implications for agentic AI systems — data processing, legal basis, safeguards\",\n \"relevance\": \"Legal framework for AI agent data processing in development workflows\",\n \"update_frequency\": \"static\",\n \"access\": \"free\",\n \"add_as_web_search\": true,\n \"tags\": [\"gdpr\", \"iapp\", \"agentic-ai\", \"legal\"]\n },\n {\n \"name\": \"PCI SSC: AI Principles for Payment Security\",\n \"url\": \"https://www.pcisecuritystandards.org/\",\n \"type\": \"reference\",\n \"description\": \"PCI Security Standards Council — card data must never appear in agent context, prompts, or code\",\n \"relevance\": \"Hard prohibition on card data in AI context — mandatory data-handling rule\",\n \"update_frequency\": \"continuous\",\n \"access\": \"free\",\n \"add_as_web_search\": true,\n \"tags\": [\"pci-dss\", \"payments\", \"security\"]\n },\n {\n \"name\": \"Anthropic: Data Processing Agreement (DPA)\",\n \"url\": \"https://www.anthropic.com/policies/data-processing-agreement\",\n \"type\": \"reference\",\n \"description\": \"Anthropic's Data Processing Agreement for Claude and Claude Code usage\",\n \"relevance\": \"Required contractual basis for using Claude Code under GDPR — verify DPA is in place\",\n \"update_frequency\": \"continuous\",\n \"access\": \"free\",\n \"add_as_web_search\": false,\n \"tags\": [\"anthropic\", \"dpa\", \"gdpr\", \"contractual\"]\n },\n {\n \"name\": \"OpenAI: Enterprise Data Processing\",\n \"url\": \"https://openai.com/enterprise-privacy/\",\n \"type\": \"reference\",\n \"description\": \"OpenAI's enterprise privacy and data processing commitments for Codex\",\n \"relevance\": \"Required for Codex usage under GDPR — verify terms meet FCA requirements\",\n \"update_frequency\": \"continuous\",\n \"access\": \"free\",\n \"add_as_web_search\": false,\n \"tags\": [\"openai\", \"dpa\", \"gdpr\", \"enterprise\"]\n }\n ],\n \"sdlc_and_devops\": [\n {\n \"name\": \"DORA: State of DevOps Report\",\n \"url\": \"https://dora.dev/research/\",\n \"type\": \"reference\",\n \"description\": \"Google DORA research on DevOps capabilities, metrics (deployment frequency, lead time, MTTR, change failure rate)\",\n \"relevance\": \"Baseline metrics for measuring SDLC compression — DORA metrics validate CDLC impact\",\n \"update_frequency\": \"continuous\",\n \"access\": \"free\",\n \"add_as_web_search\": true,\n \"tags\": [\"devops\", \"metrics\", \"dora\", \"benchmarks\"]\n },\n {\n \"name\": \"GitHub Branch Protection Rules\",\n \"url\": \"https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-a-branch-protection-rule\",\n \"type\": \"documentation\",\n \"description\": \"GitHub branch protection configuration — required reviews, signed commits, status checks\",\n \"relevance\": \"Enforcement mechanism for separation of duties, signed commits, and compliance gates\",\n \"update_frequency\": \"continuous\",\n \"access\": \"free\",\n \"add_as_web_search\": false,\n \"tags\": [\"github\", \"branch-protection\", \"enforcement\"]\n },\n {\n \"name\": \"Conventional Commits Specification\",\n \"url\": \"https://www.conventionalcommits.org/\",\n \"type\": \"specification\",\n \"description\": \"Standard for structured commit messages — type(scope): description\",\n \"relevance\": \"Commit convention referenced in compliance rules — enables automated changelogs and audit\",\n \"update_frequency\": \"static\",\n \"access\": \"free\",\n \"add_as_web_search\": false,\n \"tags\": [\"commits\", \"convention\", \"audit-trail\"]\n },\n {\n \"name\": \"GitHub CODEOWNERS\",\n \"url\": \"https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners\",\n \"type\": \"documentation\",\n \"description\": \"GitHub CODEOWNERS file for automatic review assignment based on file paths\",\n \"relevance\": \"Enforcement mechanism for requiring security/compliance review on sensitive directories\",\n \"update_frequency\": \"continuous\",\n \"access\": \"free\",\n \"add_as_web_search\": false,\n \"tags\": [\"github\", \"codeowners\", \"review\", \"enforcement\"]\n },\n {\n \"name\": \"Git Signed Commits\",\n \"url\": \"https://git-scm.com/book/en/v2/Git-Tools-Signing-Your-Work\",\n \"type\": \"documentation\",\n \"description\": \"Git documentation for GPG/SSH commit signing — cryptographic attribution\",\n \"relevance\": \"Mandatory audit trail requirement — all commits must be signed in regulated repos\",\n \"update_frequency\": \"static\",\n \"access\": \"free\",\n \"add_as_web_search\": false,\n \"tags\": [\"git\", \"signing\", \"audit-trail\", \"compliance\"]\n },\n {\n \"name\": \"GitHub Docs: Agentic Audit Log Events\",\n \"url\": \"https://docs.github.com/en/enterprise-cloud@latest/copilot/reference/agentic-audit-log-events\",\n \"type\": \"documentation\",\n \"description\": \"Official GitHub documentation for agent-specific audit log events and enterprise observability of agent activity.\",\n \"relevance\": \"Primary-source reference for audit and accountability claims in regulated GitHub agent workflows\",\n \"update_frequency\": \"continuous\",\n \"access\": \"free\",\n \"add_as_web_search\": true,\n \"verified_on\": \"2026-03-13\",\n \"volatility\": \"high\",\n \"tags\": [\"github\", \"audit\", \"enterprise\", \"agents\"]\n }\n ],\n \"practitioner_insights\": [\n {\n \"name\": \"Addy Osmani: AI-Assisted Coding — Moving Beyond Autocomplete\",\n \"url\": \"https://addyosmani.com/blog/ai-coding/\",\n \"type\": \"article\",\n \"description\": \"Google Chrome engineer on structured approaches to AI coding — beyond simple suggestions\",\n \"relevance\": \"Practical patterns for moving from copilot-style to agent-style development\",\n \"update_frequency\": \"static\",\n \"access\": \"free\",\n \"add_as_web_search\": true,\n \"tags\": [\"practitioner\", \"google\", \"patterns\"]\n },\n {\n \"name\": \"Kent Beck: AI-Assisted Software Development\",\n \"url\": \"https://tidyfirst.substack.com\",\n \"type\": \"article\",\n \"description\": \"Kent Beck's ongoing analysis of how AI changes software design — from TDD to AI-assisted patterns\",\n \"relevance\": \"Foundational thinking on how development practices evolve with AI agents\",\n \"update_frequency\": \"continuous\",\n \"access\": \"free\",\n \"add_as_web_search\": true,\n \"tags\": [\"practitioner\", \"tdd\", \"design\", \"thought-leadership\"]\n },\n {\n \"name\": \"Lenny's Newsletter: How Top Engineering Teams Use AI Coding Agents\",\n \"url\": \"https://www.lennysnewsletter.com\",\n \"type\": \"article\",\n \"description\": \"Case studies of engineering teams adopting AI coding agents at scale\",\n \"relevance\": \"Real-world adoption patterns and organizational change management insights\",\n \"update_frequency\": \"continuous\",\n \"access\": \"free\",\n \"add_as_web_search\": true,\n \"tags\": [\"case-studies\", \"adoption\", \"teams\"]\n },\n {\n \"name\": \"Cognition AI: Building with Devin — Lessons Learned\",\n \"url\": \"https://www.cognition.ai/blog\",\n \"type\": \"article\",\n \"description\": \"Cognition's blog on autonomous coding agents — context management, verification, limitations\",\n \"relevance\": \"Alternative agent perspective — validates need for structured context regardless of tool\",\n \"update_frequency\": \"continuous\",\n \"access\": \"free\",\n \"add_as_web_search\": false,\n \"tags\": [\"devin\", \"autonomous-agents\", \"lessons\"]\n },\n {\n \"name\": \"Stripe: Minions — One-Shot End-to-End Coding Agents\",\n \"url\": \"https://stripe.dev/blog/minions-stripes-one-shot-end-to-end-coding-agents\",\n \"type\": \"article\",\n \"description\": \"Stripe's internal coding agents merging 1,000+ PRs/week across hundreds of millions of LOC. Covers pre-hydration context patterns, 400+ MCP Toolshed, devbox isolation, max-2-CI-rounds verification, and the 'good for humans = good for LLMs' principle.\",\n \"relevance\": \"Production-scale evidence for context engineering at a $1T+ payment company. Validates shift-left verification, agent rule files, selective CI, and human review separation of duties.\",\n \"update_frequency\": \"static\",\n \"access\": \"free\",\n \"add_as_web_search\": true,\n \"tags\": [\"stripe\", \"coding-agents\", \"scale\", \"fintech\", \"case-study\", \"mcp\", \"verification\"]\n },\n {\n \"name\": \"Block/Square: Goose — Open Source Coding Agent\",\n \"url\": \"https://github.com/block/goose\",\n \"type\": \"repository\",\n \"description\": \"Open-source coding agent by Block (Square). Stripe's Minions forked Goose as their core agent loop.\",\n \"relevance\": \"Alternative agent framework — demonstrates interleaved agent loops with deterministic code\",\n \"update_frequency\": \"continuous\",\n \"access\": \"free\",\n \"add_as_web_search\": false,\n \"tags\": [\"goose\", \"block\", \"open-source\", \"agent-framework\"]\n },\n {\n \"name\": \"Sourcegraph: Code Intelligence for AI Agents\",\n \"url\": \"https://sourcegraph.com\",\n \"type\": \"tool\",\n \"description\": \"Code intelligence platform used by Stripe Minions for codebase search and understanding via MCP\",\n \"relevance\": \"Context retrieval tool for large codebases — alternative to grep/ripgrep for 100M+ LOC repos\",\n \"update_frequency\": \"continuous\",\n \"access\": \"free\",\n \"add_as_web_search\": false,\n \"tags\": [\"sourcegraph\", \"code-intelligence\", \"search\", \"context-retrieval\"]\n },\n {\n \"name\": \"Cortex: The Engineering Leader's Guide to AI Tools for Developers in 2026\",\n \"url\": \"https://www.cortex.io/post/the-engineering-leaders-guide-to-ai-tools-for-developers-in-2026\",\n \"type\": \"article\",\n \"description\": \"Engineering leader perspective on AI tool adoption. ROI measurement (connect to DORA metrics, not usage), governance (SOC 2, ISO 27001), internal developer portal integration, multi-tool strategy. Key insight: 'Well-defined engineering standards enable meaningful AI measurement.'\",\n \"relevance\": \"Leadership/management perspective on CE adoption — complements technical guidance with organizational strategy\",\n \"update_frequency\": \"static\",\n \"access\": \"free\",\n \"add_as_web_search\": true,\n \"tags\": [\"leadership\", \"enterprise\", \"roi\", \"adoption\", \"governance\"]\n },\n {\n \"name\": \"Block/Square: Jack Dorsey AI-Driven 40% Workforce Reduction\",\n \"url\": \"https://fortune.com/2026/02/27/block-jack-dorsey-ceo-xyz-stock-square-4000-ai-layoffs/\",\n \"type\": \"article\",\n \"description\": \"Block cut 4,000 employees (40% of workforce) citing 'intelligence tools enabling smaller and flatter teams.' Gross profit up 24% YoY, stock rose 18%. Dorsey predicted most companies will follow within a year.\",\n \"relevance\": \"Highest-profile case study of AI-driven team restructuring — validates the parallel team hypothesis at scale\",\n \"update_frequency\": \"static\",\n \"access\": \"free\",\n \"add_as_web_search\": true,\n \"tags\": [\"team-transformation\", \"layoffs\", \"block\", \"case-study\", \"ai-native\"]\n },\n {\n \"name\": \"HBR: Companies Are Laying Off Workers Because of AI's Potential — Not Its Performance\",\n \"url\": \"https://hbr.org/2026/01/companies-are-laying-off-workers-because-of-ais-potential-not-its-performance\",\n \"type\": \"article\",\n \"description\": \"Harvard Business Review analysis showing many AI-driven layoffs are based on anticipated capabilities, not proven performance. Critical counter-narrative to the restructuring hype.\",\n \"relevance\": \"Essential caveat for team transformation — challenges the assumption that AI has already proven itself enough to justify team cuts\",\n \"update_frequency\": \"static\",\n \"access\": \"free\",\n \"add_as_web_search\": true,\n \"tags\": [\"team-transformation\", \"layoffs\", \"caveat\", \"hbr\", \"critical-analysis\"]\n },\n {\n \"name\": \"SF Standard: AI Writes the Code Now — What's Left for Software Engineers?\",\n \"url\": \"https://sfstandard.com/2026/02/19/ai-writes-code-now-s-left-software-engineers/\",\n \"type\": \"article\",\n \"description\": \"Graduate hiring at top 15 US tech companies down 55% since 2019. UC CS enrollment declining for first time since dot-com era. One engineer generates 100K+ lines across 6 projects in 2 weeks using Claude Code.\",\n \"relevance\": \"Labor market evidence for the shift — data points on engineering role transformation and hiring trends\",\n \"update_frequency\": \"static\",\n \"access\": \"free\",\n \"add_as_web_search\": true,\n \"tags\": [\"team-transformation\", \"labor-market\", \"hiring\", \"role-evolution\"]\n },\n {\n \"name\": \"Harvard/P&G: When AI Joins the Team, Better Ideas Surface\",\n \"url\": \"https://www.library.hbs.edu/working-knowledge/when-ai-joins-the-team-better-ideas-surface\",\n \"type\": \"research\",\n \"description\": \"Field experiment at P&G: teams with AI produced 3x more top-10% quality ideas. Individuals with AI matched quality of 2-person human teams without AI. AI expanded problem-solving expertise across broader employee populations.\",\n \"relevance\": \"Rigorous experimental evidence that AI amplifies team capability — supports the 'smaller team + AI' hypothesis\",\n \"update_frequency\": \"static\",\n \"access\": \"free\",\n \"add_as_web_search\": true,\n \"tags\": [\"research\", \"team-transformation\", \"harvard\", \"p&g\", \"evidence\"]\n },\n {\n \"name\": \"OpenAI: Building an AI-Native Engineering Team\",\n \"url\": \"https://developers.openai.com/codex/guides/build-ai-native-engineering-team\",\n \"type\": \"documentation\",\n \"description\": \"OpenAI's guide to structuring engineering teams around Codex and AI coding agents. Covers role definitions, workflow patterns, and team sizing for AI-native organizations.\",\n \"relevance\": \"Authoritative guidance on AI-native team structure from the Codex platform provider\",\n \"update_frequency\": \"continuous\",\n \"access\": \"free\",\n \"add_as_web_search\": true,\n \"tags\": [\"team-transformation\", \"openai\", \"codex\", \"ai-native\", \"guide\"]\n },\n {\n \"name\": \"VC Corner: The Billion-Dollar Startup Formula — AI-Driven Small Teams Beating Giants\",\n \"url\": \"https://www.thevccorner.com/p/the-billion-dollar-startup-formula\",\n \"type\": \"article\",\n \"description\": \"Midjourney ($200M ARR, 10 people), Cursor ($100M ARR, 20 people), BuiltWith ($14M/year, 1 person). Solo founders = 35% of 2024 startups. 1 AI engineer ≈ 5 traditional engineers.\",\n \"relevance\": \"Venture capital perspective on AI-native team economics — concrete revenue/headcount ratios\",\n \"update_frequency\": \"static\",\n \"access\": \"free\",\n \"add_as_web_search\": true,\n \"tags\": [\"team-transformation\", \"startups\", \"vc\", \"metrics\", \"ai-native\"]\n }\n ]\n }\n}\n","content_type":"application/json; charset=utf-8","language":"json","size":79104,"content_sha256":"83b46bc70648a6102c07453660c2f7bc4fd5fdfae711d6a69675881ba4be5f85"},{"filename":"references/context-graph-guide.md","content":"# Context Graph Guide\n\nA practical reference for generating, reading, and using the per-repo context graph produced by the dev-context-engineering skill.\n\n## Table of Contents\n\n- [What Is a Context Graph](#what-is-a-context-graph)\n- [Generating the Graph](#generating-the-graph)\n- [Loading Tiers](#loading-tiers)\n- [Query Mode Taxonomy](#query-mode-taxonomy)\n- [Relationship Detection](#relationship-detection)\n- [Integration with CDLC](#integration-with-cdlc-context-driven-llm-collaboration)\n- [Context Impact Analysis](#context-impact-analysis)\n- [Maturity Model Integration](#maturity-model-integration)\n- [Related References](#related-references)\n\n---\n\n## What Is a Context Graph\n\nA context graph is a per-repo JSON graph (`context-graph.json`) that maps every context artifact in a repository and the relationships between those artifacts.\n\nArtifacts include: AGENTS.md, CLAUDE.md, coding rules, specs, plans, subagent definitions, hooks, and other files that shape how AI coding agents understand and operate inside the repo.\n\nThe graph is produced by running `scan_context_artifacts.py` against a repository root. It complements the portfolio-level knowledge graph maintained by the `dev-context-multi-repo` skill, which aggregates context signals across many repositories. The per-repo graph gives fine-grained visibility into a single codebase; the portfolio graph gives cross-repo comparisons.\n\n**Why it matters.** AI agents load context on every turn. Without a graph, agents reload all context blindly, wasting tokens and risking stale or conflicting instructions. With a graph, the loading tier of each artifact is explicit, relationships are traceable, and changes can be evaluated for downstream impact before context is reloaded.\n\n---\n\n## Generating the Graph\n\nRun `scan_context_artifacts.py` from any environment that has Python 3:\n\n```bash\npython3 /path/to/scan_context_artifacts.py /path/to/repo\n# Output: /path/to/repo/context-graph.json\n```\n\nThe script walks the repository tree, identifies artifacts by path pattern and file name, classifies each into a loading tier, and detects edges between artifacts by scanning file content. The output is a single JSON file at the repository root.\n\nValidate the result immediately after generation:\n\n```bash\npython3 /path/to/validate_context_graph.py /path/to/repo/context-graph.json --repo /path/to/repo\n# Optional: --output reports/context-graph-validation.json\n```\n\n**12 artifact types detected:**\n\n| Type | Matched paths |\n|---|---|\n| `agents_md` | `AGENTS.md` at root |\n| `claude_md` | `CLAUDE.md` at root |\n| `rule` | `.claude/rules/*.md` |\n| `spec` | `docs/specs/*.md`, `specs/*.md`, `SPEC.md` |\n| `plan` | `docs/plans/*.md`, `plans/*.md` |\n| `subagent` | `.claude/agents/*.md`, `.github/agents/*.md` |\n| `hook` | Entries under `.claude/hooks/` |\n| `copilot_instructions` | `.github/copilot-instructions.md`, `.github/instructions/*.md`, `.github/instructions/*.instructions.md` |\n| `github_agent` | `.github/agents/*.md` |\n| `reference` | `docs/references/*.md` |\n| `asset` | `assets/**/*` |\n| `skill` | `skills/*/SKILL.md` |\n\nRe-run the script whenever artifacts are added, renamed, or removed. For automated freshness, add it to CI or a git commit hook (see [Maturity Model Integration](#maturity-model-integration)).\n\n---\n\n## Loading Tiers\n\nEvery node in the graph carries a `loading_tier` field that tells agents when to load it:\n\n| Tier | Label | Artifact types | Load policy |\n|---|---|---|---|\n| L1 | `L1_always` | `agents_md`, `claude_md`, `hook`, root `copilot_instructions` | Loaded on every agent turn, unconditionally |\n| L2 | `L2_on_demand` | `rule`, `subagent`, path-scoped `copilot_instructions`, `github_agent` | Loaded when the agent determines it is relevant to the current task |\n| L3 | `L3_referenced` | `spec`, `plan`, `reference`, `asset`, `skill` | Pulled only when explicitly referenced by the task, another artifact, or an agent instruction |\n\nLoading tiers exist to control token budgets. L1 nodes are always in context; L2 and L3 nodes are lazy-loaded. Misclassifying a frequently-needed spec as L3 will cause agents to miss it; misclassifying a large asset file as L1 will waste tokens every turn.\n\n---\n\n## Query Mode Taxonomy\n\n\u003c!-- Source: Microsoft GraphRAG (Local / Global / DRIFT / Basic). Aligned with the loading-tier model above and the portfolio query taxonomy in dev-context-multi-repo/references/knowledge-graph-patterns.md §15. -->\n\nLoading tiers say *when* to load an artifact. Query modes say *how* to find it. Microsoft GraphRAG's four canonical modes map onto this skill's context-graph operations:\n\n| Mode | Question shape | Default route | Loading tier interaction |\n|---|---|---|---|\n| **Basic** | \"What does this rule say?\" \"Show me the spec for X\" | Direct file read by `id` or `path` | Pulls one L2/L3 artifact on demand |\n| **Local** | \"What rules apply to this subagent?\" \"What artifacts reference CLAUDE.md?\" | Edge traversal at 1–2 hops in `context-graph.json` | L1 nodes always in scope; traversal pulls L2/L3 neighbors |\n| **DRIFT** | \"Pull all context relevant to this task\" | Personalized PageRank from a seed (the task's anchor artifact); see `dev-context-multi-repo/references/knowledge-graph-patterns.md` §13 | L1 plus the highest-PPR L2/L3 nodes within token budget |\n| **Global** | \"What's the overall context architecture?\" \"How is this repo's context organized?\" | Community detection (Leiden) over the artifact graph; see knowledge-graph-patterns.md §14 | Returns community summaries, not raw artifacts |\n\nFor most per-repo work, Basic and Local are sufficient — the artifact graph in a single repo rarely needs PPR or community detection. DRIFT becomes useful when the L2/L3 layer has 50+ artifacts and the agent needs to pull \"task-relevant context\" without reading everything. Global becomes useful when documenting the context system itself for new contributors.\n\nThe cheapest mode that answers the question wins. Escalate only when the question genuinely needs it.\n\n---\n\n## Relationship Detection\n\nThe current scanner auto-detects 4 edge types by inspecting file content:\n\n| Edge type | Detection rule |\n|---|---|\n| `imports` | Explicit `!include`, `# @import`, or `@path` directive referencing another artifact path |\n| `references` | Markdown link `[text](path)` where the path resolves to another artifact in the graph |\n| `delegates_to` | A bracketed skill mention or `(skill:...)` reference that resolves to a discovered `skill` node |\n| `enforces` | A hook node that references a rule node by filename stem in its trigger or command |\n\nThe schema also reserves `documents`, `triggers`, `validates`, `overrides`, and `extends` for future deterministic scanners or manual augmentation, but `scan_context_artifacts.py` does not emit those relations today.\n\nEach edge in `context-graph.json` has the form:\n\n```json\n{\n \"source\": \"relative-path-derived-node-id\",\n \"target\": \"relative-path-derived-node-id\",\n \"relation\": \"references\"\n}\n```\n\nEdges are directional. `source → target` means the source artifact depends on or is aware of the target. Backward traversal (finding all artifacts that depend on a given artifact) is used for impact analysis (see [Context Impact Analysis](#context-impact-analysis)).\n\nMissing edges are a common finding on first scan. If a rule is never referenced by any other artifact, agents cannot discover it through graph traversal and must rely on L1 or L2 loading alone.\n\n---\n\n## Integration with CDLC (Context-Driven LLM Collaboration)\n\nThe context graph plugs directly into the four CDLC phases:\n\n**Generate.** `scan_context_artifacts.py` produces `context-graph.json`. Run it once at repo setup, then re-run on any structural change to the context layer.\n\n**Evaluate.** Inspect the graph to find:\n- Artifacts with no edges (isolated nodes — often orphaned specs or stale rules)\n- L1 nodes that are unexpectedly large (token cost risk)\n- Missing `enforces` edges between hooks and the rules they are meant to enforce\n- Broken paths or dangling refs reported by `validate_context_graph.py`\n\n**Distribute.** When an agent session starts, load all L1 nodes. For L2 and L3, use the graph edges to identify which artifacts are reachable from the current task context and load only those.\n\n**Observe.** Each node records `last_modified_at` from the file system at scan time. The scanner initializes `stale: false`; freshness is maintained by regenerating the graph after structural changes and validating it in CI or pre-commit.\n\n---\n\n## Context Impact Analysis\n\nWhen an artifact changes, use graph edges to determine which other artifacts are affected before reloading context.\n\n**Changed rule node — backward traversal:**\n\n1. Find the rule node in the graph.\n2. Collect all nodes with an edge pointing to it (`references`, `imports`, or `enforces` edges with this node as `to`).\n3. Those dependent nodes may need to be reloaded or reviewed for consistency.\n\n**Changed spec — subagent impact:**\n\n1. Find the spec node.\n2. Walk forward to find any subagent nodes that `delegates_to` a context that includes the spec, or that `references` the spec directly.\n3. Reload those subagent definitions before the next agent turn.\n\n**Changed CLAUDE.md or AGENTS.md (L1 nodes):**\n\nBecause these are always loaded, any change takes effect on the next turn automatically. However, if other artifacts `references` them, check whether those references are still valid after the change.\n\nImpact analysis replaces the default behavior of reloading all context on any change. On large repositories with many artifacts, targeted reloading reduces token usage and avoids accidental context pollution from unrelated artifacts.\n\n---\n\n## Maturity Model Integration\n\nThe context graph is a gating requirement for L2 and above in the repository context maturity model (see [maturity-model.md](maturity-model.md)):\n\n| Level | Name | Graph requirement |\n|---|---|---|\n| L0 | No Context | No graph. No documented context artifacts. |\n| L1 | Basic Context | Has AGENTS.md or CLAUDE.md. No graph required. |\n| L2 | Structured Context | `context-graph.json` present with at least `agents_md` or `claude_md` + at least one `rule` node. |\n| L3 | Automated Context | Full graph: plans, specs, subagents, and documented edges between them. Graph passes `validate_context_graph.py` and hook-to-rule links are reviewed. |\n| L4 | Full Context Engineering | Automated refresh: `scan_context_artifacts.py` and `validate_context_graph.py` run in CI or on git commit hook. |\n\nTo reach L4, add the scanner to a pre-commit hook or CI step:\n\n```bash\n# .git/hooks/pre-commit or CI step\npython3 /path/to/scan_context_artifacts.py $(git rev-parse --show-toplevel)\npython3 /path/to/validate_context_graph.py $(git rev-parse --show-toplevel)/context-graph.json --repo $(git rev-parse --show-toplevel)\ngit add context-graph.json\n```\n\nThis ensures `context-graph.json` is always current when code is committed, and that agents in CI environments start with a fresh graph on every run.\n\n---\n\n## Related References\n\n- [maturity-model.md](maturity-model.md) — Full 5-level maturity model with scoring checklists\n- [context-development-lifecycle.md](context-development-lifecycle.md) — CDLC phases in depth\n- [multi-repo-strategy.md](multi-repo-strategy.md) — Portfolio-level context graph (dev-context-multi-repo)\n- [repo-conversion-playbook.md](repo-conversion-playbook.md) — Step-by-step guide for adding context engineering to an existing repository\n","content_type":"text/markdown; charset=utf-8","language":"markdown","size":11492,"content_sha256":"b934f8d925c95d765f96ed0eb5626e226c490d6bf9542824a20bc3ab27da35ca"},{"filename":"references/context-resolver-pattern.md","content":"# Context Resolver Pattern\n\n> **Source**: Adapted from [garrytan/gbrain](https://github.com/garrytan/gbrain) at commit `adb02b7826a010700efc968b18df8aaf17d8ffa1`. License: MIT. Extracted 2026-04-13.\n\nA **resolver** is a routing table for context. It answers the question \"when task type X appears, which document should the agent load first?\" Skills say HOW to do something; resolvers say WHAT to load WHEN.\n\n## Why Resolvers Matter\n\nThe temptation, when an agent gets something wrong, is to put more text into always-on context. Add a caveat to `AGENTS.md`. Add another rule file. Bolt on an extra section explaining the edge case. Repeat for six months and the hot instruction layer becomes a 20,000-line swamp that the model starts ignoring because attention degrades with length.\n\nThe resolver pattern fixes this by separating two things:\n\n- **Execution policy** (hot layer): the small set of rules that must be true on every request.\n- **Contextual triggers** (resolver layer): pointers that say \"when the user asks about X, load document Y first.\"\n\nThe hot layer stays small. The body of knowledge that the model actually needs for any specific task stays out of the prompt until the resolver pulls it in.\n\n## How Claude Code Already Does This\n\nClaude Code ships with a built-in resolver: every skill has a `description` field, and the runtime matches user intent against those descriptions automatically. You don't have to remember `/ship` exists — the description *is* the resolver. The same mechanism applies to subagents and hooks.\n\nThis is why a terse, specific skill description matters more than a long one. The description is the selector. If the description doesn't distinguish your skill from a neighbor, the resolver can't route to it.\n\n## Designing a Resolver Layer for Your Repo\n\nThree rules keep the resolver healthy:\n\n1. **One task type → one primary document.** When a user asks about deployments, the resolver should point at one deployment doc, not three. If three exist, consolidate or disambiguate.\n2. **Descriptions carry the trigger vocabulary.** The words that appear in user requests should appear in the description. \"Run the migration safely under load\" → description contains \"migration\", \"safe\", \"load\", not \"alters table schema.\"\n3. **Leave deep content out of the resolver file.** The resolver is a map, not the territory. A ten-line pointer file that says \"when the question is about payments, read `docs/payments/overview.md` + `docs/payments/webhooks.md`\" is more useful than copying the content into the hot layer.\n\n## Anti-Pattern: The 20,000-Line AGENTS.md\n\nFrom the source essay: \"A confession: my CLAUDE.md was 20,000 lines. Every single thing I ran across went in there. Every quirk, every pattern, every lesson. Completely ridiculous. The model's attention degraded. Claude Code literally told me to cut it back. The fix: about 200 lines. Just pointers to documents. The resolver loads the right one when it matters.\"\n\nThe diagnostic signal is straightforward: if your always-on context file is longer than a single printed page, you are almost certainly paying for it in two ways — slower sessions and lower adherence. Cut to pointers, move the body into skills or docs, and let description-matched routing handle loading.\n\n## Skills vs Resolvers vs Rules\n\n| Layer | Answers | Example |\n|-------|---------|---------|\n| **Skill** | How to perform a task | `dev-git-workflow/SKILL.md` describes branching strategy |\n| **Resolver** | Which document to load when a task type appears | `AGENTS.md` says \"for release steps, read `docs/release.md`\" |\n| **Rule** | What must always be true | `.claude/rules/no-force-push-main.md` is a hard constraint |\n\nRules go in the hot layer because they always apply. Resolvers go in the hot layer because they are short pointers. Skills live outside the hot layer and are summoned by the resolver.\n\n## Related\n\n- [context-development-lifecycle.md](context-development-lifecycle.md) — Progressive disclosure pattern and distribution hierarchy (the loading tiers that the resolver targets)\n- [fast-track-guide.md](fast-track-guide.md) — When a repo is small enough that a resolver layer is premature\n- [paradigm-comparison.md](paradigm-comparison.md) — Why rule files and resolver files serve different purposes\n","content_type":"text/markdown; charset=utf-8","language":"markdown","size":4303,"content_sha256":"7dd9d895f36c6a7a06484acdf9399e777a565ecab592754e08e2fbd801bd2191"},{"filename":"references/fast-track-guide.md","content":"# Fast-Track Guide\n\nGetting productive with context-driven development quickly. Three tracks based on repo size, plus batch onboarding for organizations with many repos.\n\n## Table of Contents\n\n- [Key Research Insight (March 2026)](#key-research-insight-march-2026)\n- [Quick Wins (Under 5 Minutes Each)](#quick-wins-under-5-minutes-each)\n- [30-Minute Fast-Track (Medium Repos, 10K-100K LOC)](#30-minute-fast-track-medium-repos-10k-100k-loc)\n- [Minute 0-5: Orientation](#minute-0-5-orientation)\n- [Understand the codebase](#understand-the-codebase)\n- [Minute 5-15: Create AGENTS.md](#minute-5-15-create-agentsmd)\n- [[Project Name]](#project-name)\n- [Overview](#overview)\n- [Tech Stack](#tech-stack)\n- [Commands](#commands)\n- [Key Patterns](#key-patterns)\n- [Known Constraints](#known-constraints)\n- [Conventions](#conventions)\n- [Minute 15-25: Add 2-3 Rules](#minute-15-25-add-2-3-rules)\n- [Minute 25-30: First Plan File](#minute-25-30-first-plan-file)\n- [Use Claude Code to generate: \"Create a plan for [your next task]\"](#use-claude-code-to-generate-create-a-plan-for-your-next-task)\n- [2-Hour Fast-Track (Large Repos, 100K-1M LOC)](#2-hour-fast-track-large-repos-100k-1m-loc)\n- [Hour 1: Hierarchical Context](#hour-1-hierarchical-context)\n- [[Project Name]](#project-name)\n- [Overview](#overview)\n- [Architecture](#architecture)\n- [Commands](#commands)\n- [Scoped Areas](#scoped-areas)\n- [Key Decisions](#key-decisions)\n- [Cross-Cutting Concerns](#cross-cutting-concerns)\n- [For each major subdirectory](#for-each-major-subdirectory)\n- [Rules (5-10 min each)](#rules-5-10-min-each)\n- [Create 3-5 focused rule files covering major concerns](#create-3-5-focused-rule-files-covering-major-concerns)\n- [See agents-memory for templates](#see-agents-memory-for-templates)\n- [Agents (10-15 min each)](#agents-10-15-min-each)\n- [Create 1-2 specialized subagents for common tasks](#create-1-2-specialized-subagents-for-common-tasks)\n- [See agents-subagents for templates](#see-agents-subagents-for-templates)\n- [Hour 2: Automation](#hour-2-automation)\n- [Test the setup with a real task](#test-the-setup-with-a-real-task)\n- [Use Claude Code to work on something and observe:](#use-claude-code-to-work-on-something-and-observe)\n- [- Does the agent follow your conventions?](#does-the-agent-follow-your-conventions)\n- [- Are the rules being applied?](#are-the-rules-being-applied)\n- [- Is any context missing?](#is-any-context-missing)\n- [Common gap: agents don't know about your test patterns](#common-gap-agents-dont-know-about-your-test-patterns)\n- [Fix: add a testing rule or test-writer subagent](#fix-add-a-testing-rule-or-test-writer-subagent)\n- [Batch Onboarding (100 Repos)](#batch-onboarding-100-repos)\n- [Phase 1: Foundation (Week 1)](#phase-1-foundation-week-1)\n- [Phase 2: Pilot (Week 2-3)](#phase-2-pilot-week-2-3)\n- [Phase 3: Scale (Week 4-8)](#phase-3-scale-week-4-8)\n- [Phase 4: Sustain (Ongoing)](#phase-4-sustain-ongoing)\n- [Batch Priority Matrix](#batch-priority-matrix)\n- [Cross-References](#cross-references)\n\n## Key Research Insight (March 2026)\n\nBefore you start: **quality matters more than quantity**. ETH Zurich research (arxiv 2602.11988) found that LLM-generated AGENTS.md files actually degrade agent performance by 3% while increasing costs 20%+. Human-written files help only when limited to **non-inferable details** — things the agent cannot discover by reading your code and docs:\n\n- Custom build/test commands not in package.json or Makefile\n- Domain-specific conventions not evident from code patterns\n- Known failure modes and workarounds\n- Specific CI/CD quirks\n\n**Do NOT include**: project structure descriptions, dependency lists, or README-level documentation the agent can find itself.\n\n## Quick Wins (Under 5 Minutes Each)\n\nDo these first regardless of repo size:\n\n| # | Action | Time | Impact |\n|---|--------|------|--------|\n| 1 | Create `AGENTS.md` with only non-inferable details | 2 min | Portable baseline for agent instructions |\n| 2 | Add Claude compatibility only if needed | 2 min | `CLAUDE.md` wrapper/import or symlink for Claude Code |\n| 3 | Add build/test/lint commands to `AGENTS.md` | 2 min | Agents can verify their own work |\n| 4 | Add `.claude/rules/` with one coding standard | 3 min | Consistent code style from agents |\n| 5 | Add 2-3 repo-specific constraints or failure modes | 3 min | Higher signal than directory summaries |\n| 6 | Create `docs/` directory | 30 sec | Home for specs and plans |\n| 7 | Add `.gitignore` entries for agent temp files | 1 min | Clean repo state |\n| 8 | Set up signed commits: `git config commit.gpgsign true` | 1 min | Audit trail (required for regulated) |\n| 9 | Add PR template with AI disclosure section | 3 min | Transparency in PRs |\n| 10 | Run orientation: `wc -l **/*.{ts,py,go} \\| tail -1` | 30 sec | Know your codebase size |\n\n## 30-Minute Fast-Track (Medium Repos, 10K-100K LOC)\n\nFor repos where a single developer can understand the whole codebase.\n\n### Minute 0-5: Orientation\n\n```bash\n# Understand the codebase\nfind . -name '*.ts' -o -name '*.py' -o -name '*.go' | head -20\nwc -l $(find . -name '*.ts' -o -name '*.py' -o -name '*.go') | tail -1\ncat package.json 2>/dev/null || cat pyproject.toml 2>/dev/null || cat go.mod 2>/dev/null\nls -la\n```\n\n### Minute 5-15: Create AGENTS.md\n\n```markdown\n# [Project Name]\n\n## Overview\n[1-2 sentence description from README]\n\n## Tech Stack\n- Language: [e.g., TypeScript 5.x]\n- Framework: [e.g., Next.js 15]\n- Database: [e.g., PostgreSQL via Prisma]\n- Testing: [e.g., Vitest + Playwright]\n\n## Commands\n- Build: `npm run build`\n- Test: `npm test`\n- Lint: `npm run lint`\n- Dev: `npm run dev`\n\n## Key Patterns\n- [Pattern 1: e.g., \"All API routes use middleware chain in src/middleware/\"]\n- [Pattern 2: e.g., \"Database queries go through repository pattern in src/repos/\"]\n\n## Known Constraints\n- [Constraint 1: e.g., \"Use pnpm only; npm lockfiles are rejected in CI\"]\n- [Constraint 2: e.g., \"Playwright tests require local auth seed before running\"]\n\n## Conventions\n- Commits: conventional commits (feat:, fix:, chore:)\n- Branches: feature/*, fix/*, chore/*\n- PRs: require 1 approval minimum\n```\n\nIf your team uses Claude Code, add `CLAUDE.md` as either:\n\n```markdown\[email protected]\n```\n\nor a symlink if that is your team convention.\n\n### Minute 15-25: Add 2-3 Rules\n\n```bash\nmkdir -p .claude/rules\n```\n\nCreate focused rule files (one concern per file):\n\n**`.claude/rules/code-style.md`** — Key patterns, naming conventions, import ordering\n\n**`.claude/rules/testing.md`** — Test file location, naming, coverage expectations\n\n**`.claude/rules/architecture.md`** — Layer boundaries, dependency direction, prohibited patterns\n\n### Minute 25-30: First Plan File\n\nCreate `docs/plans/` and write a small plan for your next task using dev-workflow-planning. This validates the entire setup.\n\n```bash\nmkdir -p docs/plans\n# Use Claude Code to generate: \"Create a plan for [your next task]\"\n```\n\n**Result**: L1-L2 maturity in 30 minutes. Agents now produce consistent, context-aware output.\n\n## 2-Hour Fast-Track (Large Repos, 100K-1M LOC)\n\nFor repos too large for a single developer to hold in memory.\n\n### Hour 1: Hierarchical Context\n\n**Step 1 (15 min): Root AGENTS.md**\n\nKeep the root file as an orientation guide. Don't try to document everything:\n\n```markdown\n# [Project Name]\n\n## Overview\n[Brief description]\n\n## Architecture\n[High-level architecture: services, layers, data flow]\n\n## Commands\n[Build, test, lint, deploy — the essentials]\n\n## Scoped Areas\n- `src/auth/` — Authentication rules live in `src/auth/AGENTS.md`\n- `src/payments/` — Payment rules live in `src/payments/AGENTS.md`\n- `src/api/` — API layer with shared request/response patterns\n- `src/shared/` — Shared utilities\n- `packages/` — Internal packages\n\n## Key Decisions\n- [Decision 1: e.g., \"Event-driven architecture using RabbitMQ\"]\n- [Decision 2: e.g., \"Domain-Driven Design with bounded contexts\"]\n\n## Cross-Cutting Concerns\n- Error handling: [pattern]\n- Logging: [pattern]\n- Authentication: [pattern]\n```\n\n**Step 2 (15 min): Subdirectory AGENTS.md files**\n\nFor complex subdirectories, create focused context:\n\n```bash\n# For each major subdirectory\necho \"# Auth Module\\n\\n## Purpose\\n...\\n## Patterns\\n...\\n## Testing\\n...\" > src/auth/AGENTS.md\necho \"# Payments Module\\n\\n## Purpose\\n...\\n## Patterns\\n...\\n## Testing\\n...\" > src/payments/AGENTS.md\n```\n\n**Step 3 (30 min): Rules and agents**\n\n```bash\nmkdir -p .claude/rules .claude/agents\n\n# Rules (5-10 min each)\n# Create 3-5 focused rule files covering major concerns\n# See agents-memory for templates\n\n# Agents (10-15 min each)\n# Create 1-2 specialized subagents for common tasks\n# See agents-subagents for templates\n```\n\n### Hour 2: Automation\n\n**Step 4 (20 min): Hooks**\n\nSet up hooks for the most common pain points. See agents-hooks for patterns:\n- Pre-commit: lint check, test runner\n- Notification: context reminders\n\n**Step 5 (20 min): CI/CD gates**\n\nAdd compliance gates if regulated. See `assets/fca-compliance-gate.yml`.\n\n**Step 6 (20 min): Validate and iterate**\n\n```bash\n# Test the setup with a real task\n# Use Claude Code to work on something and observe:\n# - Does the agent follow your conventions?\n# - Are the rules being applied?\n# - Is any context missing?\n\n# Common gap: agents don't know about your test patterns\n# Fix: add a testing rule or test-writer subagent\n```\n\n**Result**: L2-L3 maturity in 2 hours. Agents work within guardrails with automated enforcement.\n\n## Batch Onboarding (100 Repos)\n\nRolling out context-driven development across an organization.\n\n### Phase 1: Foundation (Week 1)\n\n1. **Create coordination repo** (see multi-repo-strategy.md)\n2. **Create template AGENTS.md** with org-wide sections\n3. **Create mandatory rules** (compliance, data handling, AI governance)\n4. **Write sync scripts** for rule distribution\n\n### Phase 2: Pilot (Week 2-3)\n\n1. **Select 10 pilot repos** — pick diverse sizes and tech stacks\n2. **Priority ordering**: Start with most-active repos (highest commit frequency)\n3. **Apply 30-minute or 2-hour fast-track** to each pilot repo\n4. **Collect feedback**: What worked? What context was missing?\n\n### Phase 3: Scale (Week 4-8)\n\n1. **Batch apply** to remaining repos in groups of 10-20\n2. **Use automation**: Template sync or CI/CD sync for mandatory rules\n3. **Allow local customization**: Repo teams own their AGENTS.md content\n4. **Track maturity**: Use audit script from maturity-model.md\n\n### Phase 4: Sustain (Ongoing)\n\n1. **Monthly context retrospective** per team\n2. **Quarterly org-wide context audit**\n3. **Context curation guild** reviews shared rules\n4. **Retire stale context** aggressively\n\n### Batch Priority Matrix\n\n| Priority | Criteria | Action |\n|----------|----------|--------|\n| **P1 (now)** | Active development + customer-facing + regulated | Full fast-track + compliance gates |\n| **P2 (week 2-3)** | Active development + internal | Standard fast-track |\n| **P3 (week 4-6)** | Moderate activity | Basic AGENTS.md + mandatory rules |\n| **P4 (later)** | Dormant/archived | Minimal AGENTS.md only |\n\n## Performance Budgets for the Hot Layer\n\n\u003c!-- Source: github.com/MemPalace/mempalace@6614b9b4e71e67da2236493b036b7bf42ba2d55f (MIT), extracted 2026-04-13 -->\n\nQualitative guidance like \"keep it fast\" doesn't survive a sprint. Pin numeric thresholds so CI can enforce them and so tradeoffs become visible at review time:\n\n| Operation | Budget | Why |\n|-----------|--------|-----|\n| Session startup injection (loading L0+L1) | **\u003c 100ms** | Anything slower is felt as lag on the first token |\n| Pre-session hook (e.g. context assembly, environment checks) | **\u003c 500ms** | Longer hooks push the user past the \"it's ready\" threshold and erode trust in automation |\n| Post-response hook (background save, index write, cron trigger) | **\u003c 500ms** | Must run out-of-band; user should never wait for it |\n| Bookkeeping chat tokens (status messages, \"saving…\", \"indexing…\") | **Zero** | Background work should be invisible; every visible bookkeeping message is a tax on the real work |\n\n**Enforcement**:\n- Put a stopwatch in your hooks. Fail CI or log a warning when a hook exceeds its budget.\n- Audit the always-on context monthly. If L0+L1 together cross ~1,000 tokens, the budget is being breached silently on every request.\n- When something is slow, move it to the background (async, scheduled, post-response) rather than optimizing the hot path. \"Background everything\" is cheaper than \"make the hot path twice as fast.\"\n\n**Why zero bookkeeping tokens**: every \"saving context now…\" message costs tokens *and* user attention. Move the save to a PreCompact/Stop hook that runs after the response completes. The user sees the reply; the save runs invisibly. This pattern alone can cut per-session cost meaningfully when bookkeeping previously happened in the chat window.\n\n## Cross-References\n\n- **agents-memory** — Detailed AGENTS.md writing patterns\n- **agents-memory/references/large-codebase-strategy.md** — 100K-1M LOC specific strategies\n- **docs-ai-prd/references/architecture-extraction.md** — Extracting architecture from existing code\n- **docs-ai-prd/references/convention-mining.md** — Mining conventions from codebases\n- **maturity-model.md** — Self-assessment before and after onboarding\n- **multi-repo-strategy.md** — Coordination patterns for batch onboarding\n","content_type":"text/markdown; charset=utf-8","language":"markdown","size":13347,"content_sha256":"39dc9b7c725d3107d3c06aa9aec44505451c012f2ed91ddb1e8b0f8efcffc838"},{"filename":"references/framework-selection-matrix.md","content":"# Context-Engineering Framework Selection Matrix (April 2026)\n\nHow to pick between the major context-engineering frameworks active in April 2026 — and how they stack without fighting each other.\n\n## Table of Contents\n\n- [The four-layer model](#the-four-layer-model)\n- [Decision matrix — pick by symptom](#decision-matrix--pick-by-symptom)\n- [Layering matrix — what each replaces vs extends](#layering-matrix--what-each-replaces-vs-extends)\n- [Stack recipes](#stack-recipes)\n- [Anti-stacks](#anti-stacks)\n- [Maturity signals](#maturity-signals)\n- [Sources](#sources)\n\n## The four-layer model\n\nThe April 2026 landscape resolves cleanly into four layers. A team chooses *one* answer per layer; conflicts within a layer cause drift, but layers stack cleanly.\n\n| Layer | Role | What it produces |\n|-------|------|------------------|\n| **L0 portable baseline** | Cross-tool conventions every agent reads | A single Markdown file at the repo root that all agents pick up natively |\n| **L1 runtime-specific** | Tool-specific extensions for a single CLI/IDE | Per-tool config: `.claude/rules/`, `.codex/agents/`, `.cursor/rules/`, `.github/copilot-instructions.md`, `.clinerules/` |\n| **L2 capability / methodology** | On-demand capabilities or enforced workflow discipline | Skills, plugins, hooks — load conditionally and gate behavior |\n| **L3 artifact pipeline** | Spec → plan → tasks → code as committed artifacts | A `specs/` or `changes/` directory with structured documents |\n\nL0 is mandatory. L1 is mandatory if a tool refuses to read AGENTS.md. L2 is optional, useful when discipline drift or context rot is the bottleneck. L3 is optional, useful when feature ambiguity is the bottleneck.\n\n## Decision matrix — pick by symptom\n\nRead the left column as \"the thing my team is currently failing at.\" Pick exactly one framework per row.\n\n| Symptom | Pick | Why this and not the others |\n|---------|------|----------------------------|\n| Conventions drift across Codex / Claude Code / Cursor | **AGENTS.md** | The only L0 artifact all major tools read natively as of April 2026; LF-stewarded |\n| Agent ignores TDD, debugs sloppily, skips brainstorming | **superpowers** | Skills *enforce* discipline at runtime (refuse-to-code-until-clarified); AGENTS.md is passive |\n| Long sessions degrade — context rot, agent forgets earlier decisions | **GSD (get-shit-done)** | Built specifically for context rot: fresh subagent dispatch + `PROJECT.md` / `ROADMAP.md` / `STATE.md` planning artifacts |\n| Feature ambiguity causes drift; specs and code drift apart | **GitHub Spec Kit** | Spec → plan → tasks → code artifact pipeline; `.specify/specs/\u003cfeature>/`; most-cited and GitHub-backed |\n| Same need as Spec Kit but want lighter / npm-native + ADRs co-located | **OpenSpec** (Fission-AI) | `openspec/changes/`, npm install, integrates ADRs alongside specs |\n| Repeated domain expertise (PDF / Excel / internal DSL) bloats AGENTS.md | **Claude Code Skills** | Progressive disclosure: ~100-token metadata always-on, instructions on trigger, scripts on demand |\n| GitHub Copilot users need persistent project rules | **`.github/copilot-instructions.md`** | Only instruction layer Copilot reads natively; path-scoped via `.instructions.md` with `applyTo` |\n| Cursor IDE users need scoped rules per file/dir | **`.cursor/rules/*.mdc`** | YAML frontmatter activation; legacy `.cursorrules` deprecated |\n| Cline (VS Code) workflows | **`.clinerules/`** | Toggle UI per rule; rules-bank pattern |\n| Aider pair-programming sessions | **`CONVENTIONS.md`** | Loaded every session via `.aider.conf.yml` |\n\n## Layering matrix — what each replaces vs extends\n\n| Framework | Layer | Repo location | Composes with AGENTS.md | Install path |\n|-----------|-------|---------------|-------------------------|--------------|\n| **AGENTS.md** | L0 | `/AGENTS.md` (+ subdir overlays) | — *is* the baseline | File only |\n| **CLAUDE.md / `.claude/rules/`** | L1 | `/CLAUDE.md`, `.claude/rules/*.md` | Extends (Claude-only behavior) | File only |\n| **`.codex/agents/*.toml`** | L1 | `.codex/agents/` | Extends (Codex parallel workers) | File only |\n| **`.cursor/rules/*.mdc`** | L1 | `.cursor/rules/` | Parallel — Cursor does not read AGENTS.md | File only |\n| **`.github/copilot-instructions.md`** | L1 | `.github/` | Parallel — Copilot does not read AGENTS.md | File only |\n| **`.clinerules/`** | L1 | `/.clinerules/` | Parallel | File only |\n| **CONVENTIONS.md (Aider)** | L1 | configurable | Parallel | Config flag |\n| **Claude Code Skills** | L2 | `~/.claude/skills/` or `.claude/skills/` | Extends (on-demand, doesn't bloat hot layer) | Plugin or filesystem |\n| **superpowers** (obra/superpowers) | L2 | `.claude/`, `.cursor/`, `.opencode`, etc. | Extends (multi-runtime via plugin configs) | Anthropic plugin marketplace |\n| **GSD** (gsd-build/get-shit-done) | L2 | `~/.claude/` or `./.claude/` | Extends (skills + subagents + git hooks) | `npx get-shit-done-cc@latest` |\n| **GitHub Spec Kit** | L3 | `.specify/specs/\u003cfeature>/` | Orthogonal — produces docs that feed any agent | `uv tool install specify-cli` |\n| **OpenSpec** (Fission-AI) | L3 | `openspec/changes/` | Orthogonal | `npm i -g @fission-ai/openspec` |\n\n## Stack recipes\n\n| Team profile | Recommended stack |\n|--------------|-------------------|\n| Solo dev, single repo, single tool | AGENTS.md only. Add Spec Kit if features ship with ambiguity. |\n| Solo dev, Claude Code primary | AGENTS.md + Claude Code Skills (on-demand) + superpowers if drift recurs |\n| Small team, mixed tools (Claude + Codex + Cursor) | AGENTS.md (baseline) + thin runtime layers + Spec Kit for feature work |\n| Long-running project / monorepo / multi-phase | AGENTS.md + GSD (context-rot is the bottleneck) + Spec Kit for new features |\n| Regulated / enterprise (audit, separation of duties) | AGENTS.md + `.claude/rules/` + Spec Kit (auditable artifacts) + governance gates from this skill's `assets/` directory |\n| Cursor-primary IDE shop | `.cursor/rules/*.mdc` + AGENTS.md mirror + Spec Kit |\n| GitHub Copilot shop | `.github/copilot-instructions.md` + AGENTS.md mirror + Spec Kit |\n\n## Anti-stacks\n\nCombinations that fight each other and should not be deployed together without explicit scoping.\n\n| Don't | Reason | Mitigation if you must |\n|-------|--------|-------------------------|\n| superpowers + GSD without scoping | Both ship skills/subagents — overlap on planning, debugging | Namespace via `/sp:` vs `/gsd:` slash prefixes; pick a dominant one for each workflow |\n| Spec Kit + OpenSpec on the same repo | Two competing spec stores; agents won't know which is canonical | Pick one; if migrating, archive the other under `.archive/` |\n| Conventions duplicated in AGENTS.md + `.cursor/rules` + `.clinerules` + `copilot-instructions.md` | Drift inevitable across four parallel files | Write once in AGENTS.md or `docs/`; tool-specific layers reference, never duplicate |\n| Claude Code Skills used for always-on policy | Defeats progressive disclosure — that policy belongs in AGENTS.md / `.claude/rules/` | Move always-on rules to L0/L1; keep skills for capability that *should* load conditionally |\n| Hot AGENTS.md carrying methodology enforcement (TDD, debugging discipline) | Passive text doesn't enforce; just bloats the hot layer | Move enforcement to L2 (superpowers or custom skills) |\n\n## Maturity signals\n\nApril 2026 snapshot of adoption signals. Stars and adoption are noisy — use as a sanity check, not as a buy decision.\n\n| Framework | Adoption signal | Backing |\n|-----------|----------------|---------|\n| AGENTS.md | 67% of active repos contain `CLAUDE.md` / `AGENTS.md` / equivalent (Greptile State of AI Coding 2025) | Linux Foundation (Agentic AI Foundation) |\n| GitHub Spec Kit | ~92k stars; v0.8.4 May 2026; 30+ supported agents | GitHub official |\n| superpowers (obra/superpowers) | ~150–175k stars; v5.0.7 March 2026; 14 documented skills | Anthropic plugin marketplace listed |\n| GSD (gsd-build/get-shit-done) | ~59k stars; v1.39.0; 59 skills + 33 subagents in full mode | Independent (`gsd-build` org) |\n| Claude Code Skills | Official Anthropic product; reference catalog at `anthropics/skills` | Anthropic |\n| OpenSpec (Fission-AI) | Smaller but actively maintained; integrates ADRs; npm package | Fission-AI community |\n| Cursor rules `.cursor/rules/*.mdc` | Standardized 2025; widely adopted | Cursor (commercial) |\n| Copilot instructions | GA; path-specific instructions added July 2025; agent-specific November 2025 | GitHub official |\n| Cline rules | Stable feature; v3.13 toggle UI 2025 | Cline (open source) |\n| Aider conventions | Mature, documented behavior change in code output | Aider (open source) |\n\n## Sources\n\nExternal source mapping for this matrix lives in [data/sources.json](../data/sources.json) under the entries: `agents.md spec`, `GitHub spec-kit`, `obra/superpowers`, `gsd-build/get-shit-done`, `Fission-AI/OpenSpec`, `Anthropic Agent Skills overview`, `cursor.com/docs/rules`, `Cline rules docs`, `Aider conventions docs`.\n\nUse the maturity-signal numbers in this file as a snapshot, not a tracking signal — re-verify before any procurement or migration decision. Star counts and skill counts move month-to-month; the layer model and the decision matrix are the durable parts of this reference.\n","content_type":"text/markdown; charset=utf-8","language":"markdown","size":9310,"content_sha256":"db2c3e5231cbd5c24bd42c9cd8e67951139f49bbcb80d5fcbb40673cf0478faf"},{"filename":"references/information-routing-rules.md","content":"# Information Routing Rules\n\n> **Source**: Adapted from [garrytan/gbrain](https://github.com/garrytan/gbrain) at commit `adb02b7826a010700efc968b18df8aaf17d8ffa1`. License: MIT. Extracted 2026-04-13.\n\nWhen new information enters the session — something the user says, something an agent discovers, a decision made in conversation — it belongs in exactly one layer. Get the routing wrong and three failure modes appear: things get re-asked (because the answer lived in the wrong layer), things are lost on reset (because durable knowledge was saved only to session memory), or the hot layer bloats (because everything ends up in `AGENTS.md`).\n\n## The Three Layers and Their Purposes\n\n| Layer | What it stores | Survives agent reset? | Cost to read |\n|-------|---------------|----------------------|--------------|\n| **Compiled knowledge** (docs hub, brain, wiki) | World facts: people, systems, decisions, concepts, architecture | Yes | One retrieval hop |\n| **Agent memory** (operational state) | How the agent should behave: preferences, tool configs, defaults | Depends on platform | In always-on context |\n| **Session context** (conversation window) | What was just said, current task, immediate state | No — ephemeral | Free |\n\n## The Boundary Test\n\nFor any new piece of information, ask: **\"Is this about the world, or about how to operate?\"**\n\n- *World* → compiled knowledge layer. Facts about entities that are external to the agent and would matter even if you swapped the agent for a different one.\n- *Operations* → agent memory. Guidance that changes how the agent behaves but isn't a fact about anything outside the agent.\n- *Current conversation* → session. What's already in the window. No storage action needed.\n\n## Worked Examples\n\n| New information | Layer | Why |\n|-----------------|-------|-----|\n| \"Pedro is CEO of Acme Corp\" | Compiled knowledge | World fact — still true if you swap the agent |\n| \"Acme raised Series D at $1.2B in March\" | Compiled knowledge | World fact — dateable, citable |\n| \"User prefers concise formatting with no preamble\" | Agent memory | Operational — how to respond, not a fact about the world |\n| \"Always run the lint check before committing\" | Agent memory | Operational — enforces behavior, doesn't describe reality |\n| \"The file I just pasted\" | Session | Ephemeral — already in the window |\n| \"User's take on the zero-to-one framework\" | Compiled knowledge | The user's *original thinking* is world content worth preserving — goes in an originals/ area, not memory |\n| \"API key for Stripe goes in `.env`\" | Agent memory | Operational — a rule for the agent, not a fact about Stripe |\n\n## The Three Failure Modes\n\n1. **People in agent memory**: \"Pedro prefers email over Slack\" feels like a preference, but it is a fact *about Pedro*. If you store it in agent memory and the memory wipes on reset, you've lost knowledge that should survive forever. Put it on Pedro's page in the compiled layer.\n2. **Preferences in the compiled layer**: \"User likes bullet points over paragraphs\" is about agent behavior, not about the world. Parking it in the docs hub clutters pages that should be about entities and decisions. Put it in agent memory.\n3. **Durable facts in session only**: \"We decided to use PostgreSQL\" said in a single conversation and never written down is lost the moment the window rolls. If it's a decision that will matter next week, write it to the compiled layer *in the same turn* it gets made.\n\n## Lookup Routing\n\nReading follows the same rule with a safety net: always check the compiled knowledge layer *before* reaching for an external API or the web.\n\n1. Search the compiled layer for the entity or topic.\n2. If found: read the relevant page(s). Use that data as the first-pass answer. External sources only fill gaps.\n3. If not found: then and only then reach for external lookup.\n\nQuote from the source: \"An agent that reaches for the web before checking its own brain is wasting money and giving worse answers.\"\n\n## When to Apply This\n\n- **New repo with durable knowledge needs**: apply from day one. Set up the compiled layer structure and the boundary test before the first session.\n- **Existing repo with a bloated `AGENTS.md`**: audit each section. For every item, ask \"world or operations?\" Move world content out to docs, keep operations in the hot layer.\n- **Multi-agent setup**: the compiled layer is the shared ground truth. Agent memory stays per-agent; the compiled layer is portable across agents.\n\n## Related\n\n- [fast-track-guide.md](fast-track-guide.md) — Setting up the initial layer structure in a new repo\n- [multi-repo-strategy.md](multi-repo-strategy.md) — How the three layers distribute across repos when knowledge and behavior have different portability requirements\n- [context-resolver-pattern.md](context-resolver-pattern.md) — The routing layer that connects \"user asks X\" to \"load compiled-layer document Y\"\n","content_type":"text/markdown; charset=utf-8","language":"markdown","size":4938,"content_sha256":"ce1ef84d16636a72a35aa4e21e83535e5e5909c8390106094c0204680f62c5ff"},{"filename":"references/multi-repo-strategy.md","content":"# Multi-Repo Context Strategy\n\nManaging context-driven development across 100+ repositories. Patterns for sharing context, enforcing standards, and coordinating AI agent instructions at scale.\n\n```mermaid\nflowchart TD\n AGENTS[\"AGENTS.md\\n(source of truth)\"]\n CLAUDE[\"CLAUDE.md\\n(optional wrapper)\"]\n\n AGENTS ---|\"import or symlink\"| CLAUDE\n\n CC[\"Claude Code\\nreads CLAUDE.md\"]\n CX[\"Codex\\nreads AGENTS.md\"]\n\n CLAUDE --> CC\n AGENTS --> CX\n\n style AGENTS fill:#d4edda,color:#155724\n style CLAUDE fill:#d6eaf8,color:#1b4f72\n style CC fill:#e8daef,color:#4a235a\n style CX fill:#fdebd0,color:#7e5109\n```\n\n## Table of Contents\n\n- [Cross-Platform Convention](#cross-platform-convention)\n- [Coordination Patterns](#coordination-patterns)\n- [Pattern 1: Root Coordination Layer (Recommended for Polyrepo)](#pattern-1-root-coordination-layer-recommended-for-polyrepo)\n- [Pattern 2: Template Repository + Sync](#pattern-2-template-repository-sync)\n- [.github/workflows/template-sync.yml](#githubworkflowstemplate-syncyml)\n- [Pattern 3: Workspace-Level Context](#pattern-3-workspace-level-context)\n- [Developer workflow](#developer-workflow)\n- [Or via shell alias](#or-via-shell-alias)\n- [Pattern 4: Centralized MCP Toolshed (from Stripe)](#pattern-4-centralized-mcp-toolshed-from-stripe)\n- [GitHub Agents and Enterprise Controls (March 2026)](#github-agents-and-enterprise-controls-march-2026)\n- [VS Code Context Engineering Patterns](#vs-code-context-engineering-patterns)\n- [Shared vs Local Context](#shared-vs-local-context)\n- [Mandatory Context (All 100 repos)](#mandatory-context-all-100-repos)\n- [Recommended Context (Most repos)](#recommended-context-most-repos)\n- [Local-Only Context (Per-repo)](#local-only-context-per-repo)\n- [Distribution Mechanisms](#distribution-mechanisms)\n- [Recommended combination for regulated orgs](#recommended-combination-for-regulated-orgs)\n- [Token Budget at Scale](#token-budget-at-scale)\n- [Optimization strategies](#optimization-strategies)\n- [Cost estimation (100 repos, 20 developers)](#cost-estimation-100-repos-20-developers)\n- [Sync Scripts](#sync-scripts)\n- [Validate all repos for compliance](#validate-all-repos-for-compliance)\n- [validate-repos.sh — Run from parent directory containing all repos](#validate-repossh-—-run-from-parent-directory-containing-all-repos)\n- [Push mandatory rules to all repos](#push-mandatory-rules-to-all-repos)\n- [sync-rules.sh — Push mandatory rules from coordination repo to all repos](#sync-rulessh-—-push-mandatory-rules-from-coordination-repo-to-all-repos)\n- [InnerSource Governance](#innersource-governance)\n- [Context Curation Guild](#context-curation-guild)\n- [Change Management](#change-management)\n- [Quarterly Context Audit](#quarterly-context-audit)\n- [Skill Usage Metrics](#skill-usage-metrics)\n- [Anti-Patterns](#anti-patterns)\n- [Related References](#related-references)\n\n## Cross-Platform Convention\n\n**AGENTS.md is the portable baseline.** Add runtime-specific files only when they unlock real capability:\n\n- Codex uses `AGENTS.md` directly.\n- Claude Code can use `CLAUDE.md`, imports, `.claude/rules/`, and `.claude/agents/`.\n- GitHub Copilot and VS Code can use `AGENTS.md`, `.github/copilot-instructions.md`, `.github/instructions/*.instructions.md`, and `.github/agents/*.agent.md`.\n\nIf you maintain both `AGENTS.md` and `CLAUDE.md`, use a thin wrapper/import or a symlink. The key rule is **no duplicated drift**.\n\n## Coordination Patterns\n\nChoose one primary coordination pattern based on your organization's structure.\n\n### Pattern 1: Root Coordination Layer (Recommended for Polyrepo)\n\nA dedicated meta-repo holds shared context. Individual repos maintain focused local context.\n\n```\ncoordination-repo/ # Shared context (ONE repo)\n├── AGENTS.md # Org-wide agent instructions (PRIMARY)\n├── CLAUDE.md # Optional Claude wrapper/import\n├── .claude/\n│ ├── skills/ -> shared-skills/ # Shared skills (symlink or submodule)\n│ ├── rules/\n│ │ ├── coding-standards.md # Org-wide coding conventions\n│ │ ├── compliance-fca-emi.md # FCA/EMI regulatory rules (mandatory)\n│ │ ├── data-handling-gdpr-pci.md # GDPR/PCI DSS rules (mandatory)\n│ │ ├── security-baseline.md # Security standards (mandatory)\n│ │ └── ai-agent-governance.md # AI tool restrictions (mandatory)\n│ └── settings.json\n├── .github/\n│ ├── copilot-instructions.md # GitHub-wide agent guidance\n│ ├── instructions/ # Path-specific instructions\n│ └── agents/ # Custom GitHub/Copilot agents\n├── docs/\n│ ├── architecture-overview.md # Cross-repo architecture map\n│ └── engineering-standards.md # Org-wide engineering standards\n├── templates/\n│ ├── AGENTS.md.template # Starting point for new repos\n│ ├── pr-template.md # PR template with AI disclosure\n│ └── compliance-gate.yml # CI/CD workflow template\n└── scripts/\n ├── clone-repos.sh # Onboard new developers\n ├── sync-rules.sh # Push rule updates to all repos\n ├── validate-repos.sh # Audit all repos for compliance\n └── sync-agent-entrypoints.sh # Keep entrypoints aligned\n```\n\n```\nper-repo/ (each of 100 repos)\n├── AGENTS.md # Repo-specific context (PRIMARY)\n├── CLAUDE.md # Optional Claude wrapper/import\n├── .claude/\n│ └── rules/ # Repo-specific rules only\n│ └── domain-patterns.md # Tech/domain-specific rules\n├── .github/\n│ ├── copilot-instructions.md # Optional GitHub/Copilot guidance\n│ ├── instructions/ # Optional path-specific instructions\n│ └── agents/ # Optional custom agents\n├── docs/\n│ ├── specs/ # Feature specifications\n│ └── plans/ # Implementation plans\n└── ...\n```\n\n**How it works**:\n1. Developer clones coordination repo alongside work repos\n2. `claude --add-dir ../coordination-repo` loads shared context into sessions\n3. Shared rules supplement (not replace) repo-local rules\n4. Updates to shared rules go through PR review in coordination repo\n\n### Pattern 2: Template Repository + Sync\n\nGitHub template repo with `.claude/`, `AGENTS.md`, CI workflows. New repos start from template; updates propagated via sync workflow.\n\n```yaml\n# .github/workflows/template-sync.yml\nname: Sync from template\non:\n schedule:\n - cron: '0 6 * * 1' # Weekly Monday 6am\n workflow_dispatch:\n\njobs:\n sync:\n runs-on: ubuntu-latest\n steps:\n - uses: actions/checkout@v4\n - name: Sync mandatory rules\n run: |\n # Pull latest mandatory rules from template repo\n git clone --depth 1 https://github.com/org/template-repo /tmp/template\n cp /tmp/template/.claude/rules/compliance-*.md .claude/rules/\n cp /tmp/template/.claude/rules/data-handling-*.md .claude/rules/\n cp /tmp/template/.claude/rules/ai-agent-governance.md .claude/rules/\n # Do NOT overwrite repo-specific AGENTS.md or local rules\n - name: Create PR if changes\n run: |\n if [ -n \"$(git status --porcelain)\" ]; then\n git checkout -b template-sync-$(date +%Y%m%d)\n git add .claude/rules/\n git commit -m \"chore: sync mandatory rules from template\"\n gh pr create --title \"Sync mandatory rules\" --body \"Automated sync from template repo\"\n fi\n```\n\n**Best for**: Organizations that want automated propagation without `--add-dir`.\n\n### Pattern 3: Workspace-Level Context\n\nClaude Code `--add-dir` loads shared context from a coordination repo at session start.\n\n```bash\n# Developer workflow\nclaude --add-dir ~/work/coordination-repo --add-dir ~/work/service-repo\n\n# Or via shell alias\nalias cc-service='claude --add-dir ~/work/coordination-repo'\ncc-service # Start session with shared context pre-loaded\n```\n\n**Best for**: Small organizations (5-20 repos) where a full coordination repo feels heavy.\n\n### Pattern 4: Centralized MCP Toolshed (from Stripe)\n\nA single MCP server aggregates 400+ tools spanning internal systems and SaaS platforms. Agents connect to one endpoint and get access to documentation, ticket details, build statuses, code intelligence, and more.\n\n```\n┌─────────────────────────────────────┐\n│ Toolshed (MCP Server) │\n│ ┌──────────┐ ┌──────────────────┐ │\n│ │ Internal │ │ Code Intelligence│ │\n│ │ Docs │ │ (Sourcegraph) │ │\n│ └──────────┘ └──────────────────┘ │\n│ ┌──────────┐ ┌──────────────────┐ │\n│ │ Ticket │ │ Build/CI Status │ │\n│ │ Systems │ │ │ │\n│ └──────────┘ └──────────────────┘ │\n└──────────────┬──────────────────────┘\n │ MCP protocol\n ┌──────────┼──────────┐\n ▼ ▼ ▼\n Agent A Agent B Agent C\n(Service X) (Service Y) (Service Z)\n```\n\n**Key patterns from Stripe**:\n- **Pre-hydration**: Deterministically run relevant MCP tools on linked resources *before* agent starts (faster than agent-driven exploration)\n- **Curated access**: Agents get a subset of tools relevant to their task, not all 400+\n- **Agent rule files**: Conditional rules by subdirectory — same formats as Cursor/Claude Code\n- **Scale result**: 1,000+ merged PRs per week across hundreds of millions of LOC\n\n**Best for**: Large organizations (50+ repos) with centralized platform teams who can maintain the MCP server. Requires investment but provides the richest context.\n\n**Combining patterns**: Stripe's Toolshed (Pattern 4) complements the Coordination Repo (Pattern 1). Use Pattern 1 for static context (rules, AGENTS.md templates) and Pattern 4 for dynamic context (ticket details, build status, code search).\n\n### GitHub Agents and Enterprise Controls (March 2026)\n\nGitHub now provides two complementary layers:\n\n- **Repository context surfaces**: `AGENTS.md`, `.github/copilot-instructions.md`, and `.github/instructions/*.instructions.md`\n- **Agent surfaces**: `.github/agents/*.agent.md` plus GitHub Copilot coding agent and third-party agents\n\nFor enterprise governance, GitHub's agent control plane adds:\n\n- audit-log events that distinguish agent actions from human actions\n- session-level visibility for agent tasks\n- enterprise controls for which agents and MCP servers are allowed\n\nUse GitHub for platform-level governance and execution. Use the coordination repo for shared policy, templates, and cross-repo standards.\n\n### VS Code Context Engineering Patterns\n\nVS Code's March 2026 guidance converges on the same layered model:\n\n1. `AGENTS.md` as a portable baseline\n2. `.github/copilot-instructions.md` for repo-wide GitHub/Copilot instructions\n3. `.github/instructions/*.instructions.md` for path-specific behavior\n4. `.github/agents/*.agent.md` for planning or implementation personas\n\nFor multi-repo organizations, standardize the baseline plus the runtime-specific layers you actually use.\n\n## Shared vs Local Context\n\n### Mandatory Context (All 100 repos)\n\nThese are the baseline artifacts for regulated organizations. `AGENTS.md` and the compliance rule files are mandatory. `CLAUDE.md` is optional, but if present it must stay aligned:\n\n| File | Purpose | Enforcement |\n|------|---------|-------------|\n| `AGENTS.md` | Portable agent instructions | CI check: file exists |\n| `CLAUDE.md` | Optional Claude wrapper/import | CI check: if present, no duplicated drift |\n| `.claude/rules/compliance-fca-emi.md` | FCA/EMI audit trail, separation of duties | Template sync |\n| `.claude/rules/data-handling-gdpr-pci.md` | GDPR/PCI safe/prohibited data | Template sync |\n| `.claude/rules/ai-agent-governance.md` | AI tool restrictions, disclosure | Template sync |\n\n### Recommended Context (Most repos)\n\n| File | Purpose | When to skip |\n|------|---------|-------------|\n| `.claude/rules/coding-standards.md` | Code style, patterns | Archived repos |\n| `.claude/rules/commit-conventions.md` | Commit message format | Archived repos |\n| `.github/pull_request_template.md` | PR template with AI disclosure | Internal-only repos |\n\n### Local-Only Context (Per-repo)\n\n| File | Purpose | Examples |\n|------|---------|---------|\n| AGENTS.md body | Repo-specific instructions | \"This is a Next.js app using Prisma...\" |\n| `.claude/rules/domain-*.md` | Domain patterns | Payment flows, auth patterns |\n| `.claude/agents/*.md` | Specialized subagents | Test writer, migration helper |\n| `docs/architecture.md` | Repo architecture | Service boundaries, data flow |\n\n## Distribution Mechanisms\n\n| Mechanism | Pros | Cons | Best For |\n|-----------|------|------|----------|\n| **Git submodule** | Version-pinned, explicit updates | Requires `git submodule update` | Strict version control |\n| **Symlinks** | Fast, no extra tooling | Fragile on Windows, path-dependent | Unix-only teams |\n| **NPM/package** | Semver, familiar tooling | Overhead for non-JS repos | JS/TS monorepos |\n| **CI/CD sync** | Automated, auditable | PR noise, delayed propagation | Regulated environments |\n| **`--add-dir`** | Zero setup per repo | Requires coordination repo clone | Developer workstations |\n| **Template sync** | Automated PR creation | Requires merging sync PRs | Large orgs with many repos |\n\n### Recommended combination for regulated orgs\n1. **CI/CD sync** for mandatory compliance rules (automated, auditable)\n2. **`--add-dir`** for shared skills and coding standards (developer convenience)\n3. **Template repo** for new repo bootstrapping (consistent starting point)\n\n## Token Budget at Scale\n\nContext has a cost. Budget it:\n\n| Context Layer | Approximate Tokens | Notes |\n|--------------|-------------------|-------|\n| Shared rules (mandatory) | ~2,000 | Compliance + data handling + governance |\n| Shared rules (recommended) | ~1,500 | Coding standards + commit conventions |\n| Repo AGENTS.md | ~500-2,000 | Varies by repo complexity |\n| Skills discovery | ~500 | Skill router overhead |\n| **Workspace overhead** | **~4,500-6,000** | Before any task-specific context |\n| Available for work | ~144,000-195,000 | Depends on model context window |\n\n### Optimization strategies\n- **Progressive disclosure**: Load detailed rules only when relevant (use rule file names as triggers)\n- **Scoped AGENTS.md**: Keep top-level brief, use subdirectory AGENTS.md for deep context\n- **Sub-agent isolation**: Heavy research in subagents (separate context windows)\n- **RAG patterns**: For repos with extensive documentation, summarize in AGENTS.md, link to full docs\n\n### Cost estimation (100 repos, 20 developers)\n\n```\nPer session: ~5K tokens overhead + ~50K tokens work = ~55K tokens\nSessions per developer per day: ~10\nDaily org total: 20 devs x 10 sessions x 55K = 11M tokens/day\nMonthly: ~220M tokens (input) + ~40M tokens (output)\n```\n\n## Sync Scripts\n\n### Validate all repos for compliance\n\n```bash\n#!/bin/bash\n# validate-repos.sh — Run from parent directory containing all repos\nMANDATORY_FILES=(\n \"AGENTS.md\"\n \".claude/rules/compliance-fca-emi.md\"\n \".claude/rules/data-handling-gdpr-pci.md\"\n \".claude/rules/ai-agent-governance.md\"\n)\n\npass=0; fail=0; total=0\n\nfor repo in */; do\n [ ! -d \"$repo/.git\" ] && continue\n total=$((total + 1))\n repo_pass=true\n\n for file in \"${MANDATORY_FILES[@]}\"; do\n if [ ! -f \"$repo/$file\" ]; then\n echo \"MISSING: $repo$file\"\n repo_pass=false\n fi\n done\n\n # Check CLAUDE.md does not drift if present\n if [ -f \"$repo/CLAUDE.md\" ] && [ ! -L \"$repo/CLAUDE.md\" ] && ! grep -q '@AGENTS.md' \"$repo/CLAUDE.md\"; then\n echo \"REVIEW: ${repo}CLAUDE.md exists but is neither a wrapper nor a symlink\"\n repo_pass=false\n fi\n\n if $repo_pass; then\n pass=$((pass + 1))\n else\n fail=$((fail + 1))\n fi\ndone\n\necho \"\"\necho \"Results: $pass/$total repos compliant ($fail non-compliant)\"\n```\n\n### Push mandatory rules to all repos\n\n```bash\n#!/bin/bash\n# sync-rules.sh — Push mandatory rules from coordination repo to all repos\nCOORDINATION_REPO=\"./coordination-repo\"\nMANDATORY_RULES=(\n \"compliance-fca-emi.md\"\n \"data-handling-gdpr-pci.md\"\n \"ai-agent-governance.md\"\n)\n\nfor repo in repos/*/; do\n [ ! -d \"$repo/.git\" ] && continue\n name=$(basename \"$repo\")\n\n # Ensure .claude/rules/ exists\n mkdir -p \"$repo/.claude/rules\"\n\n # Copy mandatory rules\n for rule in \"${MANDATORY_RULES[@]}\"; do\n cp \"$COORDINATION_REPO/.claude/rules/$rule\" \"$repo/.claude/rules/$rule\"\n done\n\n # Ensure Claude compatibility wrapper if desired\n if [ -f \"$repo/AGENTS.md\" ] && [ ! -f \"$repo/CLAUDE.md\" ]; then\n printf '@AGENTS.md\\n' > \"$repo/CLAUDE.md\"\n fi\n\n echo \"Synced: $name\"\ndone\n```\n\n## InnerSource Governance\n\nFor organizations managing shared context at scale:\n\n### Context Curation Guild\n- **Members**: 1 engineering lead per team + security + compliance + platform\n- **Cadence**: Monthly review of shared rules and skills\n- **Authority**: Approve/reject changes to mandatory rules in coordination repo\n- **CODEOWNERS**: `.claude/rules/compliance-*` owned by compliance team\n\n### Change Management\n- **Mandatory rules**: Require 2 approvals (engineering + compliance)\n- **Recommended rules**: Require 1 approval (engineering lead)\n- **Local rules**: Team discretion (no cross-team review)\n- **Breaking changes**: Announced 2 weeks before propagation, major version bump\n\n### Quarterly Context Audit\n1. Review context freshness: `git log --since=\"90 days\" -- AGENTS.md .claude/`\n2. Identify stale rules (no updates in 6+ months with active repo)\n3. Measure rule compliance rate across repos\n4. Survey developers: \"Which rules helped? Which were noise?\"\n5. Retire low-value rules, update outdated ones\n\n### Skill Usage Metrics\n- Track which skills are invoked (if instrumented)\n- Retire skills with \u003c5% usage over a quarter\n- Promote high-usage skills to mandatory/recommended\n\n## Anti-Patterns\n\n| Anti-Pattern | Problem | Fix |\n|-------------|---------|-----|\n| **God coordination repo** | 5000+ line AGENTS.md covering everything | Keep coordination AGENTS.md to org-wide concerns only |\n| **Copy-paste rules** | Same rules duplicated across 100 repos | Use sync mechanism, single source of truth |\n| **Divergent entrypoints** | `CLAUDE.md` drifts away from `AGENTS.md` | Enforce wrapper-or-symlink checks in CI |\n| **Manual sync** | \"Remember to copy rules when they change\" | Automate with CI/CD sync workflow |\n| **No local context** | Repos rely entirely on coordination repo | Each repo needs its own AGENTS.md with repo-specific content |\n| **Over-syncing** | Every rule synced to every repo | Distinguish mandatory (sync) vs recommended (opt-in) |\n\n## Durable vs Replaceable — The Tool-Portability Boundary\n\n\u003c!-- Source: github.com/garrytan/gbrain@adb02b7826a010700efc968b18df8aaf17d8ffa1 (MIT), extracted 2026-04-13 -->\n\nThe patterns above handle *portfolio* multi-repo strategy — many services, one org, shared rules. There's a second, orthogonal axis worth naming explicitly: splitting **agent behavior** from **world knowledge** into two repos along a durability line.\n\n**The boundary test** (apply to every file):\n\n| Question | If YES → | Example |\n|----------|---------|---------|\n| Would this file transfer if you switched AI agents? | Agent repo (replaceable) | `AGENTS.md`, `.claude/rules/`, hooks, subagent configs, operational state |\n| Would this file transfer if you switched to a different person or team? | Knowledge repo (durable) | Architecture docs, decision records, system maps, domain concepts, entity dossiers |\n\nThe two axes — \"which agent runs this?\" and \"whose knowledge is this?\" — are independent. A repo can have:\n\n- Replaceable *and* portable → agent repo\n- Durable *and* org-owned → knowledge/docs repo\n- Both → split into two repos so the survival rules are explicit\n\n**Why this matters**: if agent config and world knowledge live in the same repo, you lose one when you swap the other. Switch from Claude Code to Codex and you shouldn't lose your architecture docs. Change teams and the incoming team shouldn't inherit your personal tool preferences. The split makes each failure mode impossible by construction.\n\n**Decision tree for a new file**:\n\n```\nAbout a person, company, system, decision, or domain concept → knowledge repo\nAbout how the agent should behave → agent repo\nOriginal thinking (yours, an architect's, a PM's) → knowledge repo (under an originals/ area)\nSession logs, daily ops state, task lists → agent repo\nSkill configs, hooks, cron definitions → agent repo\nRules about policy, compliance, safety → knowledge repo if org-wide, agent repo if agent-local\n```\n\n**Interaction with the portfolio patterns above**: the durable/replaceable split happens *per organizational unit* (a team, a user, a project). The portfolio patterns handle how multiple such units coordinate. Pattern 1 (Root Coordination Layer) can itself be split — the coordination repo holds shared policy (durable), while each developer's agent config lives elsewhere (replaceable).\n\n## Related References\n\n- **maturity-model.md** — Assess readiness before scaling\n- **regulated-environment-patterns.md** — Compliance rules that must be synced\n- **fast-track-guide.md** — Batch onboarding for 100 repos\n- **context-development-lifecycle.md** — The CDLC feedback loop at scale\n- **information-routing-rules.md** — The *per-information* routing rule (world vs operations vs session) that complements this *per-file* repo boundary\n","content_type":"text/markdown; charset=utf-8","language":"markdown","size":22274,"content_sha256":"6be3ac8e2a0562d815c773094c9b324e43ae3f529e711ae3943c91e04cd017d1"},{"filename":"references/regulated-environment-patterns.md","content":"# Regulated Environment Patterns\n\nFCA/EMI compliance patterns for AI-driven development. Covers regulatory framework mapping, mandatory agent rules, CI/CD compliance gates, change approval workflows, and audit trail requirements.\n\n## Table of Contents\n\n- [Regulatory Framework Coverage](#regulatory-framework-coverage)\n- [PS21/3: Operational Resilience](#ps213-operational-resilience)\n- [SS1/23: Model Risk Management](#ss123-model-risk-management)\n- [SM&CR: Senior Managers and Certification Regime](#sm&cr-senior-managers-and-certification-regime)\n- [PS24/16: Critical Third Parties (CTP)](#ps2416-critical-third-parties-ctp)\n- [GDPR / UK GDPR](#gdpr-uk-gdpr)\n- [PCI DSS](#pci-dss)\n- [NIST AI Agent Standards Initiative (2026)](#nist-ai-agent-standards-initiative-2026)\n- [FINRA 2026: AI Agent Regulatory Precedent](#finra-2026-ai-agent-regulatory-precedent)\n- [Industry Evidence: AI Agents in Regulated Fintech](#industry-evidence-ai-agents-in-regulated-fintech)\n- [Stripe Minions (1,000+ PRs/week, $1T+ payment volume)](#stripe-minions-1000-prsweek-$1t-payment-volume)\n- [Mandatory Agent Rules](#mandatory-agent-rules)\n- [1. FCA/EMI Compliance (`.claude/rules/compliance-fca-emi.md`)](#1-fcaemi-compliance-clauderulescompliance-fca-emimd)\n- [2. Data Handling (`.claude/rules/data-handling-gdpr-pci.md`)](#2-data-handling-clauderulesdata-handling-gdpr-pcimd)\n- [3. AI Agent Governance (`.claude/rules/ai-agent-governance.md`)](#3-ai-agent-governance-clauderulesai-agent-governancemd)\n- [Change Approval Workflow](#change-approval-workflow)\n- [Standard Flow](#standard-flow)\n- [Enhanced Flow (Security-Critical Paths)](#enhanced-flow-security-critical-paths)\n- [CODEOWNERS Configuration](#codeowners-configuration)\n- [.github/CODEOWNERS](#githubcodeowners)\n- [Security-critical directories require security team review](#security-critical-directories-require-security-team-review)\n- [Agent rules require compliance review](#agent-rules-require-compliance-review)\n- [Infrastructure requires DevOps review](#infrastructure-requires-devops-review)\n- [Audit Trail Requirements](#audit-trail-requirements)\n- [Git as Compliance Tool](#git-as-compliance-tool)\n- [PR Description Template](#pr-description-template)\n- [Quarterly Integrity Checks](#quarterly-integrity-checks)\n- [Run quarterly across all repos](#run-quarterly-across-all-repos)\n- [Audit Log Export](#audit-log-export)\n- [Export audit log for a date range](#export-audit-log-for-a-date-range)\n- [Compliance-Aware CI/CD](#compliance-aware-cicd)\n- [Gate Summary](#gate-summary)\n- [Compliance Metrics](#compliance-metrics)\n- [Incident Response: AI Tool Failures](#incident-response-ai-tool-failures)\n- [Severity Classification](#severity-classification)\n- [Post-Incident Actions](#post-incident-actions)\n- [Agent Execution Security](#agent-execution-security)\n- [Sandbox Isolation Patterns](#sandbox-isolation-patterns)\n- [GitHub Enterprise Agent Audit Integration](#github-enterprise-agent-audit-integration)\n- [Related References](#related-references)\n\n## Regulatory Framework Coverage\n\n### PS21/3: Operational Resilience\n\nAI coding tools are critical dependencies in your Important Business Services (IBS):\n\n- **Impact tolerance**: Define maximum tolerable disruption if AI tools become unavailable\n- **Scenario testing**: Test manual fallback pathways quarterly (can your team ship without AI agents?)\n- **Dependency mapping**: Document AI tool providers (Anthropic, OpenAI) in your IBS dependency register\n- **Exit strategy**: Maintain ability to develop without any single AI provider (dual-agent strategy helps)\n\n### SS1/23: Model Risk Management\n\nAI-generated code is model output that must be governed:\n\n- **Inventory**: Track which code artifacts were AI-generated (PR disclosure, commit metadata)\n- **Validation**: Human review required for all AI-generated code before merge\n- **Testing**: AI-generated code must meet same test coverage thresholds as human code\n- **Explainability**: Developers must understand AI-generated code before approving\n- **Monitoring**: Track defect rates in AI-generated vs human-written code\n\n### SM&CR: Senior Managers and Certification Regime\n\nNamed accountability for AI tool governance:\n\n- **Senior Manager Function**: Designate SMF responsible for AI tool governance (typically CTO/CIO)\n- **Delegation is not a defense**: \"The AI did it\" is not an acceptable explanation to the FCA\n- **Reasonable steps**: Document policies, training, and controls for AI tool usage\n- **Certification**: Developers using AI tools should be certified under SM&CR if in scope\n\n### PS24/16: Critical Third Parties (CTP)\n\nAI providers may be designated as Critical Third Parties:\n\n- **Portability**: Maintain ability to switch between AI providers and context surfaces\n- **Concentration risk**: Do not depend on a single AI provider for all development\n- **Contractual provisions**: Ensure DPA and service terms with AI providers meet FCA requirements\n- **Incident reporting**: AI tool outages affecting IBS must be reported per operational resilience framework\n\n### GDPR / UK GDPR\n\nData protection requirements for AI-assisted development:\n\n- **DPA**: Data Processing Agreement with Anthropic and OpenAI (both offer DPAs)\n- **DPIA**: Data Protection Impact Assessment if AI processes personal data\n- **Context safety**: Agent context files (AGENTS.md, rules, plans) must NEVER contain personal data\n- **Lawful basis**: Legitimate interest for code generation; explicit consent if processing customer data patterns\n- **Right to explanation**: If AI-generated decisions affect individuals, explainability required\n\n### PCI DSS\n\nPayment Card Industry requirements:\n\n- **Card data prohibition**: Real or synthetic card numbers must NEVER appear in agent context, prompts, or code comments\n- **Segmentation**: AI agents must not have access to cardholder data environments\n- **Logging**: AI tool access to payment-related code must be auditable\n- **Key management**: AI agents must never see encryption keys, even in test environments\n\n### NIST AI Agent Standards Initiative (2026)\n\nThe first US government framework specifically targeting autonomous AI agents, launched by NIST's Center for AI Standards and Innovation (CAISI):\n\n**Three pillars:**\n1. **Industry-led standards**: Gap analyses, voluntary guidelines, international standards coordination\n2. **Community-led protocols**: Open-source agent protocol interoperability (NSF investment)\n3. **Security research**: Agent authentication, identity infrastructure, security evaluations\n\n**Key focus areas for coding agents:**\n- **Agent identity and authorization**: How agents authenticate and what permissions they hold\n- **Governance and oversight controls**: Human supervision, escalation protocols, access controls\n- **Security controls**: Mitigating misuse, privilege escalation, unintended autonomous actions\n\n**Relevance for FCA-regulated firms**: While NIST standards are US-focused, they provide a complementary framework. FCA-regulated firms operating internationally should track NIST developments for alignment opportunities.\n\n### FINRA 2026: AI Agent Regulatory Precedent\n\nFINRA's 2026 Regulatory Oversight Report contains the first dedicated section on AI agents by a major financial regulator, defining them as \"systems capable of autonomous actions on behalf of users\":\n\n**Agent-specific risks identified:**\n- Autonomy without human validation and approval\n- Scope creep beyond intended authority\n- Auditability challenges (multi-step reasoning difficult to trace)\n- Data sensitivity (unintended storage or disclosure)\n- Misaligned reward functions affecting outcomes\n\n**Required controls (applicable to coding agents):**\n- Track and log agent actions and decisions\n- Store prompt and output logs for accountability\n- Record which model version was used and when\n- Implement human-in-the-loop review procedures\n- Define guardrails to restrict agent behaviors\n\n**Mapping to FCA context**: While FINRA is a US regulator, its specificity on AI agent audit trails is more detailed than current FCA guidance. FCA-regulated EMIs should proactively adopt FINRA's logging recommendations as best practice — regulators learn from each other.\n\n## Industry Evidence: AI Agents in Regulated Fintech\n\n### Stripe Minions (1,000+ PRs/week, $1T+ payment volume)\n\nStripe's internal coding agents demonstrate that AI-generated code at scale is compatible with stringent financial regulation:\n\n| Control | Stripe's Implementation | FCA Equivalent |\n|---------|------------------------|---------------|\n| **Isolation** | Pre-warmed devboxes, no production/internet access | Operational resilience (PS21/3) |\n| **Human review** | All agent output requires human review before merge | Separation of duties (SM&CR) |\n| **Verification** | Max 2 CI rounds, local lint \u003c5s, selective test running | Model risk validation (SS1/23) |\n| **Context rules** | Agent rule files conditional by subdirectory | `.claude/rules/` per directory |\n| **Tool governance** | Curated MCP tool subset per task (from 400+) | Approved tool list |\n| **Audit trail** | Full visibility into agent decisions via web UI | PR disclosure + signed commits |\n\n**Key takeaway for FCA-regulated EMIs**: If Stripe can merge 1,000+ AI-generated PRs weekly while processing $1T+ in payments, the approach is viable for EMIs — but requires the same rigor: isolation, human review, verification constraints, and auditability.\n\n**Isolation pattern worth adopting**: Stripe's devboxes are fully isolated from production and the internet. For EMIs, consider container-based agent execution environments that:\n- Cannot reach production databases or APIs\n- Cannot make outbound network calls (prevents data exfiltration)\n- Are pre-loaded with code and test infrastructure only\n- Spin up in \u003c30 seconds for developer ergonomics\n\n## Mandatory Agent Rules\n\nThese rules templates must be installed in every repository. Copy from `assets/` directory.\n\n### 1. FCA/EMI Compliance (`.claude/rules/compliance-fca-emi.md`)\n\nCovers:\n- Signed commits required (audit trail)\n- No force-push (immutable history)\n- Merge commits only to main (traceable changes)\n- AI cannot approve or deploy (separation of duties)\n- Different reviewer required (four-eyes principle)\n- Prohibited: auto-merge to production branches\n- Model risk: all AI-generated artifacts tracked\n\nSee: `assets/compliance-fca-emi.md` for copy-ready template.\n\n### 2. Data Handling (`.claude/rules/data-handling-gdpr-pci.md`)\n\nCovers:\n- Safe data categories (code abstractions, business logic, synthetic test data)\n- Prohibited data categories (PII, card data, credentials, connection strings)\n- Context filtering patterns\n- Test data guidelines\n\nSee: `assets/data-handling-gdpr-pci.md` for copy-ready template.\n\n### 3. AI Agent Governance (`.claude/rules/ai-agent-governance.md`)\n\nCovers:\n- Approved AI tool list\n- Usage restrictions per environment\n- Disclosure requirements\n- Training requirements\n- Incident response for AI tool failures\n\nSee: `assets/ai-agent-governance.md` for copy-ready template.\n\n## Change Approval Workflow\n\n```mermaid\nsequenceDiagram\n participant Dev as Developer + AI Agent\n participant PR as Pull Request\n participant Rev as Code Reviewer\u003cbr/>(different person)\n participant CI as CI/CD Gates\n participant Sec as Security Reviewer\u003cbr/>(if critical path)\n participant Ops as DevOps\n\n Dev->>PR: Create PR with AI disclosure\n PR->>Rev: Request review\n Rev->>PR: Approve (four-eyes)\n PR->>CI: Run compliance gates\n Note over CI: Signed commits\u003cbr/>Secrets scan\u003cbr/>SAST\u003cbr/>PII detection\u003cbr/>AI disclosure check\n CI->>PR: All gates pass\n alt Security-critical path\n PR->>Sec: Request security review\n Sec->>PR: Approve\n end\n PR->>PR: Merge (merge commit, no squash)\n PR->>Ops: Request deployment\n Ops->>Ops: Deploy (separate approval)\n```\n\n### Standard Flow\n\n```\nDeveloper + AI Agent\n ↓ creates PR\nHuman Review (PR author cannot be sole reviewer)\n ↓ approves\nCode Reviewer (different person, required)\n ↓ approves\nAutomated Gates (CI/CD)\n ├── Signed commit verification\n ├── Secrets detection (gitleaks)\n ├── SAST scanning\n ├── PII pattern detection\n ├── AI disclosure check\n ├── Test coverage threshold\n └── Dependency vulnerability scan\n ↓ all pass\nMerge to main (merge commit, no squash)\n ↓\nDevOps approves deployment (separate from code approval)\n```\n\n### Enhanced Flow (Security-Critical Paths)\n\nFor changes touching `auth/`, `payments/`, `crypto/`, `compliance/`:\n\n```\nStandard Flow\n ↓ plus\nSecurity Reviewer (separate from code reviewer)\n ↓ approves\nCompliance Check (manual or automated)\n ↓ clears\nMerge with 2+ approvals\n```\n\n### CODEOWNERS Configuration\n\n```\n# .github/CODEOWNERS\n# Security-critical directories require security team review\n/auth/ @org/security-team @org/backend-leads\n/payments/ @org/security-team @org/payments-team\n/crypto/ @org/security-team\n/compliance/ @org/compliance-team @org/security-team\n\n# Agent rules require compliance review\n/.claude/rules/compliance-* @org/compliance-team\n/.claude/rules/data-handling* @org/compliance-team @org/security-team\n\n# Infrastructure requires DevOps review\n/.github/workflows/ @org/devops-team\n/terraform/ @org/devops-team\n/k8s/ @org/devops-team\n```\n\n## Audit Trail Requirements\n\n### Git as Compliance Tool\n\nGit provides an immutable, signed audit trail when configured correctly:\n\n| Requirement | Git Implementation | Enforcement |\n|------------|-------------------|-------------|\n| **Immutability** | No force-push, no rebase on main | Branch protection rules |\n| **Attribution** | Signed commits (GPG/SSH) | `git config commit.gpgsign true` |\n| **Traceability** | Merge commits (no squash) | Branch protection: merge commits only |\n| **Disclosure** | PR template with AI involvement | PR template check in CI |\n| **Chronology** | Commit timestamps | Git's native ordering |\n| **Integrity** | SHA-256 commit hashes | `git fsck --full` quarterly |\n\n### PR Description Template\n\nEvery PR must include AI involvement disclosure. See `assets/pr-template-ai-disclosure.md`.\n\nKey fields:\n- AI tools used (Claude Code, Codex, Cursor, Copilot, none)\n- AI role (generated code, reviewed code, generated tests, assisted debugging)\n- Human verification checklist (understood code, ran tests, reviewed security, checked compliance)\n- Files primarily AI-generated (list)\n- Confidence level (high/medium/low for each AI-generated section)\n\n### Quarterly Integrity Checks\n\n```bash\n# Run quarterly across all repos\nfor repo in repos/*/; do\n echo \"=== $(basename $repo) ===\"\n (cd \"$repo\" && git fsck --full 2>&1 | tail -1)\n (cd \"$repo\" && git log --oneline --no-merges main | wc -l)\n echo \"---\"\ndone\n```\n\n### Audit Log Export\n\nFor compliance reporting, export git history to immutable storage:\n\n```bash\n# Export audit log for a date range\ngit log --since=\"2026-01-01\" --until=\"2026-03-31\" \\\n --format='%H|%ai|%an|%ae|%s' \\\n --show-signature \\\n > audit-log-2026-Q1.csv\n```\n\n## Compliance-Aware CI/CD\n\nSee `assets/fca-compliance-gate.yml` for the full GitHub Actions workflow template.\n\n### Gate Summary\n\n| Gate | Tool | Blocks Merge | Purpose |\n|------|------|-------------|---------|\n| Signed commits | `git verify-commit` | Yes | Audit trail attribution |\n| Secrets detection | gitleaks | Yes | Prevent credential exposure |\n| SAST scanning | Semgrep/CodeQL | Yes | Vulnerability detection |\n| PII detection | Custom regex | Yes | Data protection |\n| AI disclosure | PR template check | Yes | Regulatory transparency |\n| Test coverage | Coverage tool | Yes (if below threshold) | Code quality |\n| Dependency scan | Dependabot/Snyk | Warning | Supply chain security |\n| License check | License tool | Warning | Legal compliance |\n\n## Compliance Metrics\n\nTrack and report these metrics for regulatory purposes:\n\n| Metric | Target | Frequency | Report To |\n|--------|--------|-----------|-----------|\n| % repos with mandatory rules | 100% | Weekly | CTO/compliance |\n| % PRs with AI disclosure | 100% | Weekly | Engineering leads |\n| Security scan pass rate | >95% | Daily | Security team |\n| Mean time to gate resolution | \u003c4 hours | Weekly | Engineering leads |\n| Signed commit compliance | 100% | Daily | DevOps |\n| Force-push attempts blocked | 0 | Daily | Security team |\n| PII detection true positive rate | >80% | Monthly | DPO |\n| Quarterly git integrity pass | 100% | Quarterly | Compliance/audit |\n\n## Incident Response: AI Tool Failures\n\nWhen an AI tool fails or produces problematic output:\n\n### Severity Classification\n\n| Severity | Criteria | Response Time | Escalation |\n|----------|----------|---------------|------------|\n| **P1 Critical** | AI-generated code causes production incident | 15 min | CTO + compliance |\n| **P2 High** | AI tool leaks sensitive data | 1 hour | Security + DPO |\n| **P3 Medium** | AI tool produces non-compliant code (caught in review) | 24 hours | Engineering lead |\n| **P4 Low** | AI tool unavailable | 48 hours | DevOps |\n\n### Post-Incident Actions\n1. Isolate: Revert AI-generated code if in production\n2. Investigate: Determine root cause (context issue, model behavior, human oversight failure)\n3. Remediate: Fix the immediate issue\n4. Prevent: Update rules, gates, or training to prevent recurrence\n5. Report: Log incident per operational resilience framework\n\n## Agent Execution Security\n\n### Sandbox Isolation Patterns\n\nFor regulated environments, agent code execution requires isolation beyond git worktrees. Choose isolation level based on threat model:\n\n| Technology | Isolation | Boot Time | Security Level | Best For |\n|-----------|-----------|-----------|---------------|----------|\n| **Git worktrees** | Branch-level | Instant | Code isolation only | Development (L2) |\n| **Docker containers** | Process (shared kernel) | Milliseconds | Process-level | Trusted, audited code |\n| **gVisor** | Syscall interception | Milliseconds | Syscall-level | CI/CD, multi-tenant |\n| **Firecracker microVM** | Hardware (dedicated kernel) | ~125ms | Hardware-enforced | Production agents, regulated |\n| **Kata Containers** | Hardware (via VMM) | ~200ms | Hardware-enforced | Kubernetes, regulated industries |\n\n**Recommendation for FCA-regulated EMIs:**\n- **Development**: Git worktrees (standard for agent isolation)\n- **CI/CD**: gVisor or Firecracker (stronger isolation for automated runs)\n- **Production agent execution**: Firecracker microVMs (dedicated kernel, \u003c5 MiB overhead)\n\n**Defense-in-depth for agent execution:**\n1. Network isolation: Block all outbound connections by default; whitelist only required endpoints\n2. Resource limits: CPU/memory caps, disk quotas, I/O rate limiting\n3. Zero-trust credentials: Short-lived tokens with task-specific scope\n4. Human-in-the-loop gates: Approval required for high-risk operations\n5. Immutable audit trails: Track every code execution, tool call, and API request\n\nSandboxing and network restriction materially reduce blast radius compared to unrestricted agent execution.\n\n### GitHub Enterprise Agent Audit Integration\n\nGitHub's enterprise agent controls provide platform-level audit capabilities that complement repository-level compliance:\n\n**Audit log enhancements for agents:**\n- agent-specific audit events distinguish agent actions from human actions\n- session-level task events capture lifecycle and status\n- events can be reviewed at organization and enterprise scope\n\n**Enterprise governance features:**\n- custom agent definitions in `.github/agents/`\n- enterprise controls for approved agents and MCP servers\n- policy enforcement and review at org / enterprise scope\n- custom roles for AI governance\n\n**Integration with FCA compliance:**\nThese controls map to FCA requirements:\n- agent-specific audit events → SM&CR accountability\n- session events → PS21/3 operational resilience\n- approved-agent and MCP controls → PS24/16 third-party governance\n- protected agent definition files → separation of duties\n\n## Related References\n\n- **multi-repo-strategy.md** — How to distribute compliance rules across repos\n- **maturity-model.md** — L3+ requires compliance gates\n- **context-development-lifecycle.md** — Compliance rules need CDLC maintenance\n- **software-security-appsec** — Application security patterns (OWASP, auth)\n","content_type":"text/markdown; charset=utf-8","language":"markdown","size":20387,"content_sha256":"9f28995f91d766a94492f0eeaf9bef08f2cda9762471f556a7d0d4d360197b4c"},{"filename":"schemas/context-graph.schema.json","content":"{\n \"$schema\": \"https://json-schema.org/draft/2020-12/schema\",\n \"$id\": \"https://example.com/dev-context-engineering/schemas/context-graph.schema.json\",\n \"title\": \"ContextGraph\",\n \"description\": \"Per-repo context graph: instructions, rules, specs, plans, hooks, subagents, references, assets, and the relationships between them.\",\n \"type\": \"object\",\n \"required\": [\"meta\", \"nodes\", \"edges\"],\n \"properties\": {\n \"meta\": {\n \"type\": \"object\",\n \"required\": [\"scope\", \"generated_at\"],\n \"properties\": {\n \"scope\": { \"type\": \"string\" },\n \"generated_at\": { \"type\": \"string\", \"format\": \"date-time\" },\n \"graph_contract_version\": {\n \"type\": \"string\",\n \"description\": \"Schema contract version. Bump on breaking changes.\"\n },\n \"maturity_level\": { \"type\": \"string\", \"enum\": [\"L0\",\"L1\",\"L2\",\"L3\",\"L4\"] },\n \"validation\": {\n \"type\": \"object\",\n \"properties\": {\n \"checks_passed\": { \"type\": \"integer\" },\n \"checks_total\": { \"type\": \"integer\" },\n \"last_validated_at\": { \"type\": \"string\", \"format\": \"date-time\" }\n }\n }\n }\n },\n \"nodes\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"object\",\n \"required\": [\"id\", \"type\", \"label\", \"path\"],\n \"properties\": {\n \"id\": { \"type\": \"string\" },\n \"type\": {\n \"type\": \"string\",\n \"enum\": [\"agents_md\",\"claude_md\",\"rule\",\"spec\",\"plan\",\"subagent\",\"hook\",\"copilot_instructions\",\"github_agent\",\"reference\",\"asset\",\"skill\"]\n },\n \"label\": { \"type\": \"string\" },\n \"path\": { \"type\": \"string\" },\n \"summary\": {\n \"type\": \"string\",\n \"description\": \"1-2 sentence description of this artifact's purpose.\"\n },\n \"tags\": {\n \"type\": \"array\",\n \"items\": { \"type\": \"string\" }\n },\n \"last_modified_at\": { \"type\": \"string\", \"format\": \"date-time\" },\n \"last_verified_at\": { \"type\": \"string\", \"format\": \"date-time\" },\n \"first_seen_at\": { \"type\": \"string\", \"format\": \"date-time\" },\n \"token_cost\": { \"type\": \"integer\" },\n \"loading_tier\": { \"type\": \"string\", \"enum\": [\"L1_always\",\"L2_on_demand\",\"L3_referenced\"] },\n \"stale\": { \"type\": \"boolean\" },\n \"confidence\": { \"type\": \"number\", \"minimum\": 0, \"maximum\": 1 },\n \"evidence\": {\n \"type\": \"array\",\n \"items\": { \"type\": \"object\" },\n \"description\": \"Provenance refs (file paths, line ranges, scan timestamps). LLM-enrichable.\"\n },\n \"importance\": {\n \"type\": \"number\",\n \"minimum\": 0,\n \"description\": \"Fan-in count or PageRank score. Computed by validate/query passes.\"\n }\n }\n }\n },\n \"edges\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"object\",\n \"required\": [\"source\", \"target\", \"relation\"],\n \"properties\": {\n \"source\": { \"type\": \"string\" },\n \"target\": { \"type\": \"string\" },\n \"relation\": {\n \"type\": \"string\",\n \"enum\": [\"imports\",\"delegates_to\",\"enforces\",\"documents\",\"triggers\",\"validates\",\"overrides\",\"extends\",\"references\",\"supersedes\"]\n },\n \"weight\": {\n \"type\": \"number\",\n \"minimum\": 0,\n \"maximum\": 1,\n \"description\": \"Static dependency strength. Convention: enforces=1.0, imports=0.9, delegates_to=0.8, documents=0.5, references=0.3\"\n },\n \"weight_static\": {\n \"type\": \"number\",\n \"minimum\": 0,\n \"maximum\": 1,\n \"description\": \"Original static weight before calibration. Set by calibration passes.\"\n },\n \"weight_calibrated\": {\n \"type\": \"number\",\n \"minimum\": 0,\n \"maximum\": 1,\n \"description\": \"Calibrated weight from multi-source evidence. Set by calibration passes; preferred when present.\"\n },\n \"confidence\": { \"type\": \"number\", \"minimum\": 0, \"maximum\": 1 },\n \"evidence\": {\n \"type\": \"array\",\n \"items\": { \"type\": \"object\" },\n \"description\": \"Provenance refs that justify this edge (file path, line range, regex match, doc anchor).\"\n },\n \"notes\": { \"type\": \"string\" },\n \"first_seen_at\": { \"type\": \"string\", \"format\": \"date-time\" },\n \"last_verified_at\": { \"type\": \"string\", \"format\": \"date-time\" },\n \"stale\": { \"type\": \"boolean\" },\n \"valid_at\": {\n \"type\": \"string\",\n \"format\": \"date-time\",\n \"description\": \"Bitemporal: when this relationship became true in the world. Optional.\"\n },\n \"valid_until\": {\n \"type\": \"string\",\n \"format\": \"date-time\",\n \"description\": \"Bitemporal: when this relationship stopped being true. Optional. Use null for currently-valid edges.\"\n },\n \"superseded_by\": {\n \"type\": \"string\",\n \"description\": \"Edge id that replaced this edge. Used for supersession instead of deletion.\"\n },\n \"supersedes\": {\n \"type\": \"string\",\n \"description\": \"Edge id that this edge replaces. Inverse of superseded_by.\"\n },\n \"edge_id\": {\n \"type\": \"string\",\n \"description\": \"Stable edge identifier. Required when supersession or bitemporal fields are used.\"\n }\n }\n }\n }\n }\n}\n","content_type":"application/json; charset=utf-8","language":"json","size":5514,"content_sha256":"e3f29b3172283f6a843bbac18df21a0058e8a941cd98498889c45c74c500ad0e"},{"filename":"scripts/query_context_graph.py","content":"#!/usr/bin/env python3\n\"\"\"\nQuery a context-graph.json file.\n\nSupports:\n --node \u003cid> [--hops N] BFS neighborhood\n --impact \u003cid> [--hops N] Downstream impact (outgoing only)\n --rank [--top N] Rank by weighted incoming edges\n --ppr --seed \u003cid> Personalized PageRank around 1+ seeds\n --tier-budget Show how token cost is distributed across loading tiers\n\nExamples:\n python3 query_context_graph.py context-graph.json --node \"agents_md:AGENTS.md\" --hops 2\n python3 query_context_graph.py context-graph.json --ppr --seed \"rule:.claude/rules/coding-behavior.md\" --top 20\n python3 query_context_graph.py context-graph.json --tier-budget --format table\n\"\"\"\nfrom __future__ import annotations\n\nimport argparse\nimport json\nimport sys\nfrom collections import deque\nfrom pathlib import Path\n\n\ndef load_graph(graph_path: str) -> tuple[list[dict], list[dict], dict[str, dict]]:\n data = json.loads(Path(graph_path).read_text(encoding=\"utf-8\"))\n nodes = data.get(\"nodes\", [])\n edges = data.get(\"edges\", [])\n return nodes, edges, {node[\"id\"]: node for node in nodes if \"id\" in node}\n\n\ndef edge_weight(edge: dict) -> float:\n \"\"\"Pick the most informative weight available, preferring calibrated values.\"\"\"\n for field in (\"weight_calibrated\", \"weight_static\", \"weight\"):\n value = edge.get(field)\n if value is not None:\n try:\n return max(float(value), 0.0)\n except (TypeError, ValueError):\n continue\n return 1.0\n\n\ndef build_adjacency(edges: list[dict]) -> tuple[dict, dict]:\n forward: dict[str, list[tuple[str, dict]]] = {}\n backward: dict[str, list[tuple[str, dict]]] = {}\n for edge in edges:\n source = edge.get(\"source\")\n target = edge.get(\"target\")\n if not source or not target:\n continue\n forward.setdefault(source, []).append((target, edge))\n backward.setdefault(target, []).append((source, edge))\n return forward, backward\n\n\ndef bfs_neighborhood(start: str, forward: dict, backward: dict, hops: int) -> tuple[set[str], list[dict]]:\n visited = {start}\n edge_keys: set[tuple[str, str, str]] = set()\n collected_edges: list[dict] = []\n queue = deque([(start, 0)])\n while queue:\n node_id, depth = queue.popleft()\n if depth >= hops:\n continue\n for neighbor, edge in forward.get(node_id, []):\n key = (edge[\"source\"], edge[\"target\"], edge.get(\"relation\", \"\"))\n if key not in edge_keys:\n edge_keys.add(key)\n collected_edges.append(edge)\n if neighbor not in visited:\n visited.add(neighbor)\n queue.append((neighbor, depth + 1))\n for neighbor, edge in backward.get(node_id, []):\n key = (edge[\"source\"], edge[\"target\"], edge.get(\"relation\", \"\"))\n if key not in edge_keys:\n edge_keys.add(key)\n collected_edges.append(edge)\n if neighbor not in visited:\n visited.add(neighbor)\n queue.append((neighbor, depth + 1))\n return visited, collected_edges\n\n\ndef bfs_impact(start: str, forward: dict, hops: int) -> tuple[set[str], list[dict]]:\n visited = {start}\n edge_keys: set[tuple[str, str, str]] = set()\n collected_edges: list[dict] = []\n queue = deque([(start, 0)])\n while queue:\n node_id, depth = queue.popleft()\n if depth >= hops:\n continue\n for neighbor, edge in forward.get(node_id, []):\n key = (edge[\"source\"], edge[\"target\"], edge.get(\"relation\", \"\"))\n if key not in edge_keys:\n edge_keys.add(key)\n collected_edges.append(edge)\n if neighbor not in visited:\n visited.add(neighbor)\n queue.append((neighbor, depth + 1))\n return visited, collected_edges\n\n\ndef personalized_pagerank(\n nodes: list[dict],\n edges: list[dict],\n seeds: list[str],\n *,\n alpha: float = 0.15,\n max_iter: int = 100,\n tol: float = 1e-9,\n) -> dict[str, float]:\n \"\"\"Weighted PPR for context-graph retrieval. Pure-python.\"\"\"\n node_ids = [node[\"id\"] for node in nodes if \"id\" in node]\n node_set = set(node_ids)\n if not node_ids:\n return {}\n\n seed_set = [seed for seed in seeds if seed in node_set]\n if not seed_set:\n raise ValueError(\"at least one seed must exist in the graph\")\n\n personalization = {nid: 0.0 for nid in node_ids}\n for seed in seed_set:\n personalization[seed] = 1.0 / len(seed_set)\n\n outgoing: dict[str, list[tuple[str, float]]] = {nid: [] for nid in node_ids}\n for edge in edges:\n src = edge.get(\"source\")\n tgt = edge.get(\"target\")\n if src not in node_set or tgt not in node_set:\n continue\n weight = edge_weight(edge)\n if weight \u003c= 0:\n continue\n outgoing[src].append((tgt, weight))\n\n scores = dict(personalization)\n for _ in range(max_iter):\n next_scores = {nid: alpha * personalization[nid] for nid in node_ids}\n dangling = 0.0\n for nid, score in scores.items():\n targets = outgoing.get(nid, [])\n if not targets:\n dangling += score\n continue\n total = sum(weight for _t, weight in targets)\n if total \u003c= 0:\n dangling += score\n continue\n walk = (1.0 - alpha) * score\n for tgt, weight in targets:\n next_scores[tgt] += walk * (weight / total)\n if dangling:\n redistribution = (1.0 - alpha) * dangling\n for nid, seed_score in personalization.items():\n if seed_score:\n next_scores[nid] += redistribution * seed_score\n delta = sum(abs(next_scores[nid] - scores.get(nid, 0.0)) for nid in node_ids)\n scores = next_scores\n if delta \u003c tol:\n break\n\n total = sum(scores.values())\n if total > 0:\n scores = {nid: value / total for nid, value in scores.items()}\n return scores\n\n\ndef rank_nodes(nodes: list[dict], edges: list[dict], top: int) -> list[dict]:\n fan_in: dict[str, float] = {}\n for edge in edges:\n target = edge.get(\"target\")\n if not target:\n continue\n fan_in[target] = fan_in.get(target, 0.0) + edge_weight(edge)\n ranked = []\n for node in nodes:\n nid = node.get(\"id\")\n if not nid:\n continue\n ranked.append({\n \"id\": nid,\n \"type\": node.get(\"type\"),\n \"label\": node.get(\"label\"),\n \"loading_tier\": node.get(\"loading_tier\"),\n \"weighted_fan_in\": round(fan_in.get(nid, 0.0), 4),\n })\n ranked.sort(key=lambda item: (-item[\"weighted_fan_in\"], item.get(\"label\") or item[\"id\"]))\n return ranked if top == 0 else ranked[:top]\n\n\ndef tier_budget(nodes: list[dict]) -> dict:\n by_tier: dict[str, dict] = {}\n for node in nodes:\n tier = node.get(\"loading_tier\") or \"untiered\"\n bucket = by_tier.setdefault(tier, {\"node_count\": 0, \"token_cost_total\": 0, \"stale_count\": 0})\n bucket[\"node_count\"] += 1\n bucket[\"token_cost_total\"] += int(node.get(\"token_cost\") or 0)\n if node.get(\"stale\"):\n bucket[\"stale_count\"] += 1\n return by_tier\n\n\ndef format_table(payload: dict) -> str:\n if \"tier_budget\" in payload:\n budget = payload[\"tier_budget\"]\n lines = [f\"{'TIER':\u003c20} {'NODES':\u003c8} {'TOKENS':\u003c10} STALE\"]\n lines.append(\"-\" * 50)\n for tier, bucket in sorted(budget.items()):\n lines.append(\n f\"{tier:\u003c20} {bucket['node_count']:\u003c8} {bucket['token_cost_total']:\u003c10} {bucket['stale_count']}\"\n )\n return \"\\n\".join(lines)\n\n rows = payload.get(\"results\") or payload.get(\"nodes\") or []\n if not rows:\n return \"No results.\"\n headers = [\"id\", \"type\", \"label\", \"loading_tier\"]\n if \"ppr_score\" in rows[0]:\n headers.append(\"ppr_score\")\n if \"weighted_fan_in\" in rows[0]:\n headers.append(\"weighted_fan_in\")\n lines = [\" | \".join(headers), \" | \".join(\"---\" for _ in headers)]\n for row in rows:\n lines.append(\" | \".join(str(row.get(header, \"\")) for header in headers))\n return \"\\n\".join(lines)\n\n\ndef main() -> int:\n parser = argparse.ArgumentParser(description=__doc__)\n parser.add_argument(\"graph\", help=\"Path to context-graph.json\")\n cmd = parser.add_mutually_exclusive_group(required=True)\n cmd.add_argument(\"--node\", help=\"BFS neighborhood around a node\")\n cmd.add_argument(\"--impact\", help=\"Downstream impact from a node\")\n cmd.add_argument(\"--rank\", action=\"store_true\", help=\"Rank nodes by weighted fan-in\")\n cmd.add_argument(\"--ppr\", action=\"store_true\", help=\"Personalized PageRank (use --seed)\")\n cmd.add_argument(\"--tier-budget\", action=\"store_true\", dest=\"tier_budget\", help=\"Show node and token distribution per loading tier\")\n\n parser.add_argument(\"--seed\", action=\"append\", default=[], help=\"Seed node id for --ppr (repeatable)\")\n parser.add_argument(\"--alpha\", type=float, default=0.15, help=\"Teleport probability for --ppr (default: 0.15)\")\n parser.add_argument(\"--include-seeds\", action=\"store_true\", help=\"Include seed nodes in --ppr results\")\n parser.add_argument(\"--filter-type\", help=\"Comma-separated node types to keep in --ppr results\")\n parser.add_argument(\"--top\", type=int, default=20, help=\"Top results for --rank or --ppr (0 = all)\")\n parser.add_argument(\"--hops\", type=int, default=1, help=\"Hops for --node and --impact (default: 1)\")\n parser.add_argument(\"--format\", choices=(\"json\", \"table\"), default=\"json\")\n parser.add_argument(\"--output\", help=\"Optional output file\")\n args = parser.parse_args()\n\n nodes, edges, node_index = load_graph(args.graph)\n forward, backward = build_adjacency(edges)\n\n result: dict\n if args.node:\n if args.node not in node_index:\n print(f\"Error: node '{args.node}' not in graph\", file=sys.stderr)\n return 1\n ids, edge_rows = bfs_neighborhood(args.node, forward, backward, args.hops)\n result = {\n \"query\": \"node\",\n \"node\": args.node,\n \"hops\": args.hops,\n \"nodes\": [node_index[i] for i in sorted(ids) if i in node_index],\n \"edges\": edge_rows,\n }\n elif args.impact:\n if args.impact not in node_index:\n print(f\"Error: node '{args.impact}' not in graph\", file=sys.stderr)\n return 1\n ids, edge_rows = bfs_impact(args.impact, forward, args.hops)\n result = {\n \"query\": \"impact\",\n \"node\": args.impact,\n \"hops\": args.hops,\n \"nodes\": [node_index[i] for i in sorted(ids) if i in node_index],\n \"edges\": edge_rows,\n }\n elif args.rank:\n result = {\"query\": \"rank\", \"results\": rank_nodes(nodes, edges, args.top)}\n elif args.ppr:\n if not args.seed:\n print(\"Error: --ppr requires at least one --seed\", file=sys.stderr)\n return 1\n if not 0 \u003c args.alpha \u003c 1:\n print(\"Error: --alpha must be between 0 and 1\", file=sys.stderr)\n return 1\n unknown = [seed for seed in args.seed if seed not in node_index]\n if unknown:\n print(f\"Error: unknown seed(s): {', '.join(unknown)}\", file=sys.stderr)\n return 1\n scores = personalized_pagerank(nodes, edges, args.seed, alpha=args.alpha)\n seed_set = set(args.seed)\n allowed_types = {value.strip() for value in args.filter_type.split(\",\")} if args.filter_type else None\n ranked = []\n for node in nodes:\n nid = node.get(\"id\")\n if not nid:\n continue\n if not args.include_seeds and nid in seed_set:\n continue\n if allowed_types and node.get(\"type\") not in allowed_types:\n continue\n ranked.append({\n \"id\": nid,\n \"type\": node.get(\"type\"),\n \"label\": node.get(\"label\"),\n \"loading_tier\": node.get(\"loading_tier\"),\n \"ppr_score\": round(scores.get(nid, 0.0), 10),\n })\n ranked.sort(key=lambda item: (-item[\"ppr_score\"], item.get(\"label\") or item[\"id\"]))\n if args.top > 0:\n ranked = ranked[:args.top]\n result = {\n \"query\": \"ppr\",\n \"seeds\": args.seed,\n \"alpha\": args.alpha,\n \"results\": ranked,\n }\n elif args.tier_budget:\n result = {\"query\": \"tier_budget\", \"tier_budget\": tier_budget(nodes)}\n else:\n print(\"Error: choose exactly one query mode\", file=sys.stderr)\n return 1\n\n if args.format == \"table\":\n rendered = format_table(result)\n else:\n rendered = json.dumps(result, indent=2, default=str)\n\n if args.output:\n out = Path(args.output).expanduser().resolve()\n out.parent.mkdir(parents=True, exist_ok=True)\n out.write_text(rendered, encoding=\"utf-8\")\n else:\n print(rendered)\n return 0\n\n\nif __name__ == \"__main__\":\n raise SystemExit(main())\n","content_type":"text/x-python; charset=utf-8","language":"python","size":13190,"content_sha256":"dfc1eb3a3f4e8cc477cc4dca19fa6af18bb0c85d013bad0b90620de9abdd5007"},{"filename":"scripts/scan_context_artifacts.py","content":"#!/usr/bin/env python3\n\"\"\"\nScan a repo for context artifacts (AGENTS.md, CLAUDE.md, rules, specs, hooks, etc.)\nand build a context-graph.json.\n\nUsage:\n python3 scan_context_artifacts.py /path/to/repo [--output /path/to/context-graph.json]\n\"\"\"\nimport argparse\nimport json\nimport re\nimport sys\nfrom datetime import datetime, timezone\nfrom pathlib import Path\n\n# ---------------------------------------------------------------------------\n# Artifact pattern catalogue\n# ---------------------------------------------------------------------------\n\n# Each entry: (glob_pattern, node_type, loading_tier)\nARTIFACT_PATTERNS = [\n (\"AGENTS.md\", \"agents_md\", \"L1_always\"),\n (\"CLAUDE.md\", \"claude_md\", \"L1_always\"),\n (\".claude/rules/*.md\", \"rule\", \"L1_always\"),\n (\".claude/agents/*.md\", \"subagent\", \"L2_on_demand\"),\n (\".claude/hooks/*\", \"hook\", \"L1_always\"),\n (\"docs/specs/*.md\", \"spec\", \"L2_on_demand\"),\n (\"specs/*.md\", \"spec\", \"L2_on_demand\"),\n (\"SPEC.md\", \"spec\", \"L2_on_demand\"),\n (\"docs/plans/*.md\", \"plan\", \"L2_on_demand\"),\n (\"plans/*.md\", \"plan\", \"L2_on_demand\"),\n (\"docs/references/*.md\", \"reference\", \"L3_referenced\"),\n (\"assets/**/*\", \"asset\", \"L3_referenced\"),\n (\"skills/*/SKILL.md\", \"skill\", \"L3_referenced\"),\n (\".github/copilot-instructions.md\", \"copilot_instructions\",\"L1_always\"),\n (\".github/instructions/*.md\", \"copilot_instructions\",\"L2_on_demand\"),\n (\".github/instructions/*.instructions.md\", \"copilot_instructions\", \"L2_on_demand\"),\n (\".github/agents/*.md\", \"github_agent\", \"L2_on_demand\"),\n]\n\n\n# ---------------------------------------------------------------------------\n# Helpers\n# ---------------------------------------------------------------------------\n\ndef now_iso() -> str:\n return datetime.now(timezone.utc).isoformat()\n\n\ndef file_mtime_iso(path: Path) -> str:\n mtime = path.stat().st_mtime\n return datetime.fromtimestamp(mtime, tz=timezone.utc).isoformat()\n\n\ndef path_to_id(relative_path: str) -> str:\n \"\"\"Convert a relative path to a node ID: replace / and . and spaces with -.\"\"\"\n # strip extension, replace path separators and special chars\n no_ext = re.sub(r\"\\.[^/]+$\", \"\", relative_path)\n return re.sub(r\"[/\\\\ ]+\", \"-\", no_ext).strip(\"-\")\n\n\ndef rel_path_str(abs_path: Path, repo_root: Path) -> str:\n try:\n return str(abs_path.relative_to(repo_root))\n except ValueError:\n return str(abs_path)\n\n\ndef token_cost(path: Path) -> int:\n try:\n return int(path.stat().st_size / 4)\n except OSError:\n return 0\n\n\n# ---------------------------------------------------------------------------\n# Scanner\n# ---------------------------------------------------------------------------\n\ndef scan_artifacts(repo_root: Path) -> list[dict]:\n \"\"\"Return a list of node dicts for all discovered context artifacts.\"\"\"\n nodes: list[dict] = []\n seen_paths: set[str] = set()\n\n for glob_pattern, node_type, tier in ARTIFACT_PATTERNS:\n for abs_path in sorted(repo_root.glob(glob_pattern)):\n if not abs_path.is_file():\n continue\n rel = rel_path_str(abs_path, repo_root)\n if rel in seen_paths:\n continue\n seen_paths.add(rel)\n\n node_id = path_to_id(rel)\n label = abs_path.stem\n\n node = {\n \"id\": node_id,\n \"type\": node_type,\n \"label\": label,\n \"path\": rel,\n \"last_modified_at\": file_mtime_iso(abs_path),\n \"token_cost\": token_cost(abs_path),\n \"loading_tier\": tier,\n \"stale\": False,\n }\n nodes.append(node)\n\n return nodes\n\n\n# ---------------------------------------------------------------------------\n# Edge detection\n# ---------------------------------------------------------------------------\n\n# Patterns to search within file content\n# imports: CLAUDE.md !include or # @import or @path directives\nRE_IMPORT = re.compile(r\"(?:!include|#\\s*@import|@path)\\s+([^\\s\\\"']+)\", re.MULTILINE)\n# references: markdown links to relative paths\nRE_MD_LINK = re.compile(r\"\\[([^\\]]+)\\]\$(\\./|\\.\\./)([^)]+)\$\")\n# delegates_to: skill delegation patterns like [skill-name] or (skill:...) in text\nRE_SKILL_BRACKET = re.compile(r\"\\[([a-z][a-z0-9-]{2,})\\](?!\$)\") # [skill-name] not followed by (\nRE_SKILL_PAREN = re.compile(r\"\\(skill:([a-z][a-z0-9-]+)\$\") # (skill:name)\n# enforces: hook file references a rule file by filename stem\nRE_RULE_REF = re.compile(r\"\\b([a-z][a-z0-9-]+(?:-rule|-policy|-coding))\\b\")\n\n\ndef detect_edges(nodes: list[dict], repo_root: Path) -> list[dict]:\n \"\"\"\n Parse each node's file to detect edges.\n Returns list of edge dicts with source, target, relation.\n \"\"\"\n edges: list[dict] = []\n edge_keys_seen: set[tuple] = set()\n\n # Build lookup: path → node_id and id → node for fast reverse lookups\n path_to_node: dict[str, dict] = {n[\"path\"]: n for n in nodes}\n id_to_node: dict[str, dict] = {n[\"id\"]: n for n in nodes}\n\n # All node IDs for target resolution\n all_ids = set(id_to_node)\n all_paths = set(path_to_node)\n\n def add_edge(src_id: str, tgt_id: str, relation: str):\n if src_id == tgt_id:\n return\n key = (src_id, tgt_id, relation)\n if key in edge_keys_seen:\n return\n edge_keys_seen.add(key)\n edges.append({\"source\": src_id, \"target\": tgt_id, \"relation\": relation})\n\n def resolve_path_ref(ref: str, source_path: str) -> str:\n \"\"\"Given a relative ref in a file, return the matching node_id or ''.\"\"\"\n # Normalise: strip leading ./ or ../\n clean = re.sub(r\"^\\.{1,2}/\", \"\", ref)\n # Try direct path match\n for p in all_paths:\n if p.endswith(clean) or Path(p).name == Path(clean).name:\n return path_to_node[p][\"id\"]\n # Try id match\n stem = Path(clean).stem\n candidate_id = path_to_id(clean)\n if candidate_id in all_ids:\n return candidate_id\n # Partial stem match\n for nid in all_ids:\n if nid.endswith(stem) or nid == stem:\n return nid\n return \"\"\n\n for node in nodes:\n src_id = node[\"id\"]\n node_type = node[\"type\"]\n file_path = repo_root / node[\"path\"]\n\n if not file_path.exists() or not file_path.is_file():\n continue\n\n try:\n content = file_path.read_text(encoding=\"utf-8\", errors=\"replace\")\n except OSError:\n continue\n\n # ── imports (CLAUDE.md and similar) ──────────────────────────────────\n if node_type in (\"claude_md\", \"agents_md\", \"copilot_instructions\"):\n for m in RE_IMPORT.finditer(content):\n tgt = resolve_path_ref(m.group(1), node[\"path\"])\n if tgt:\n add_edge(src_id, tgt, \"imports\")\n\n # Binary-ish assets are modeled as nodes, but we do not try to parse them.\n if node_type == \"asset\":\n continue\n\n # ── references (markdown links in any artifact) ───────────────────────\n for m in RE_MD_LINK.finditer(content):\n ref = m.group(3) # path after ./ or ../\n tgt = resolve_path_ref(ref, node[\"path\"])\n if tgt:\n add_edge(src_id, tgt, \"references\")\n\n # ── delegates_to (Quick Reference tables or inline skill mentions) ────\n if node_type in (\"claude_md\", \"agents_md\", \"rule\", \"spec\"):\n for m in RE_SKILL_BRACKET.finditer(content):\n skill_name = m.group(1)\n # Only add if another node with matching id/stem exists\n for nid, nd in id_to_node.items():\n if nd.get(\"type\") == \"skill\" or skill_name in nid:\n add_edge(src_id, nid, \"delegates_to\")\n break\n for m in RE_SKILL_PAREN.finditer(content):\n skill_name = m.group(1)\n for nid, nd in id_to_node.items():\n if skill_name in nid:\n add_edge(src_id, nid, \"delegates_to\")\n break\n\n # ── enforces (hook → rule) ────────────────────────────────────────────\n if node_type == \"hook\":\n for m in RE_RULE_REF.finditer(content):\n rule_name = m.group(1)\n for nid, nd in id_to_node.items():\n if nd.get(\"type\") == \"rule\" and (\n rule_name in nid or nid.endswith(rule_name)\n ):\n add_edge(src_id, nid, \"enforces\")\n\n return edges\n\n\n# ---------------------------------------------------------------------------\n# Main\n# ---------------------------------------------------------------------------\n\ndef build_context_graph(repo_root: Path) -> dict:\n nodes = scan_artifacts(repo_root)\n edges = detect_edges(nodes, repo_root)\n\n return {\n \"meta\": {\n \"scope\": repo_root.name,\n \"generated_at\": now_iso(),\n \"maturity_level\": None,\n },\n \"nodes\": nodes,\n \"edges\": edges,\n }\n\n\ndef main():\n parser = argparse.ArgumentParser(\n description=\"Scan a repo for context artifacts and build a context-graph.json.\"\n )\n parser.add_argument(\"repo\", help=\"Path to the repository root\")\n parser.add_argument(\n \"--output\", metavar=\"FILE\",\n help=\"Output JSON path (default: \u003crepo>/context-graph.json)\"\n )\n args = parser.parse_args()\n\n repo_root = Path(args.repo).resolve()\n if not repo_root.is_dir():\n print(f\"Error: repo path not found: {repo_root}\", file=sys.stderr)\n sys.exit(1)\n\n print(f\"[scan] Scanning {repo_root}\")\n graph = build_context_graph(repo_root)\n\n output_path = Path(args.output).resolve() if args.output else repo_root / \"context-graph.json\"\n output_path.parent.mkdir(parents=True, exist_ok=True)\n output_path.write_text(\n json.dumps(graph, indent=2, ensure_ascii=False),\n encoding=\"utf-8\"\n )\n\n n = len(graph[\"nodes\"])\n e = len(graph[\"edges\"])\n print(\n f\"[done] Context graph written to {output_path}\\n\"\n f\" nodes={n} edges={e}\"\n )\n\n if n == 0:\n print(\n \"[info] No context artifacts found. \"\n \"Expected files like AGENTS.md, CLAUDE.md, .claude/rules/*.md, etc.\",\n file=sys.stderr\n )\n\n\nif __name__ == \"__main__\":\n main()\n","content_type":"text/x-python; charset=utf-8","language":"python","size":11253,"content_sha256":"389bbf35a02b1ae146918fa3be66c4358c13fdff82a568fb6c89bf063c955923"},{"filename":"scripts/validate_context_graph.py","content":"#!/usr/bin/env python3\n\"\"\"\nValidate a context-graph.json file produced by scan_context_artifacts.py.\n\nUsage:\n python3 validate_context_graph.py /path/to/context-graph.json\n python3 validate_context_graph.py /path/to/context-graph.json --repo /path/to/repo\n python3 validate_context_graph.py /path/to/context-graph.json --output report.json\n\"\"\"\nimport argparse\nimport json\nimport sys\nfrom datetime import datetime, timezone\nfrom pathlib import Path\n\n\nVALID_NODE_TYPES = {\n \"agents_md\",\n \"claude_md\",\n \"rule\",\n \"spec\",\n \"plan\",\n \"subagent\",\n \"hook\",\n \"copilot_instructions\",\n \"github_agent\",\n \"reference\",\n \"asset\",\n \"skill\",\n}\n\nVALID_RELATIONS = {\n \"imports\",\n \"delegates_to\",\n \"enforces\",\n \"documents\",\n \"triggers\",\n \"validates\",\n \"overrides\",\n \"extends\",\n \"references\",\n \"supersedes\",\n}\n\nSTALE_TIER_DAYS = 90\nSTALE_TIERS = {\"L1_always\"}\n\n\ndef check_schema_compliance(nodes: list[dict], edges: list[dict]) -> list[str]:\n issues = []\n for node in nodes:\n if node.get(\"type\") not in VALID_NODE_TYPES:\n issues.append(\n f\"Node '{node.get('id', '?')}' has invalid type '{node.get('type')}'\"\n )\n for field in (\"id\", \"type\", \"label\", \"path\"):\n if field not in node:\n issues.append(f\"Node '{node.get('id', '?')}' missing required field '{field}'\")\n for edge in edges:\n if edge.get(\"relation\") not in VALID_RELATIONS:\n issues.append(\n f\"Edge {edge.get('source', '?')}→{edge.get('target', '?')} has invalid relation '{edge.get('relation')}'\"\n )\n for field in (\"source\", \"target\", \"relation\"):\n if field not in edge:\n issues.append(f\"Edge missing required field '{field}'\")\n return issues\n\n\ndef check_dangling_refs(nodes: list[dict], edges: list[dict]) -> list[str]:\n node_ids = {n[\"id\"] for n in nodes if \"id\" in n}\n issues = []\n for edge in edges:\n src = edge.get(\"source\")\n tgt = edge.get(\"target\")\n if src not in node_ids:\n issues.append(f\"Edge references unknown source '{src}'\")\n if tgt not in node_ids:\n issues.append(f\"Edge references unknown target '{tgt}'\")\n return issues\n\n\ndef check_duplicate_ids(nodes: list[dict], edges: list[dict]) -> list[str]:\n seen = {}\n for node in nodes:\n nid = node.get(\"id\")\n if not nid:\n continue\n seen[nid] = seen.get(nid, 0) + 1\n return [f\"Node id '{nid}' is duplicated {count} times\" for nid, count in seen.items() if count > 1]\n\n\ndef check_paths_exist(nodes: list[dict], edges: list[dict], repo_root: Path) -> list[str]:\n issues = []\n for node in nodes:\n node_path = node.get(\"path\")\n if not node_path:\n continue\n abs_path = repo_root / node_path\n if not abs_path.exists():\n issues.append(f\"Node '{node.get('id', '?')}' path does not exist: {node_path}\")\n return issues\n\n\ndef _parse_iso(value: str) -> datetime | None:\n if not value:\n return None\n try:\n if value.endswith(\"Z\"):\n value = value[:-1] + \"+00:00\"\n dt = datetime.fromisoformat(value)\n if dt.tzinfo is None:\n dt = dt.replace(tzinfo=timezone.utc)\n return dt\n except (TypeError, ValueError):\n return None\n\n\ndef check_stale_tiers(nodes: list[dict], edges: list[dict]) -> list[str]:\n \"\"\"Flag hot-tier nodes that haven't been touched recently.\n\n Hot instructions (L1_always) drift fastest because they are read every\n session. Anything older than STALE_TIER_DAYS deserves a re-verification pass.\n \"\"\"\n issues = []\n now = datetime.now(timezone.utc)\n for node in nodes:\n tier = node.get(\"loading_tier\")\n if tier not in STALE_TIERS:\n continue\n last_modified = _parse_iso(node.get(\"last_modified_at\", \"\"))\n last_verified = _parse_iso(node.get(\"last_verified_at\", \"\"))\n anchor = last_verified or last_modified\n if not anchor:\n issues.append(\n f\"Hot-tier node '{node.get('id', '?')}' has no last_modified_at or last_verified_at\"\n )\n continue\n age_days = (now - anchor).days\n if age_days > STALE_TIER_DAYS:\n issues.append(\n f\"Hot-tier node '{node.get('id', '?')}' is {age_days}d old (>{STALE_TIER_DAYS}d threshold)\"\n )\n return issues\n\n\ndef check_supersession_integrity(nodes: list[dict], edges: list[dict]) -> list[str]:\n \"\"\"Validate bitemporal supersession edges form a consistent chain.\"\"\"\n edge_index = {edge.get(\"edge_id\"): edge for edge in edges if edge.get(\"edge_id\")}\n issues = []\n for edge in edges:\n succ = edge.get(\"superseded_by\")\n if succ and succ not in edge_index:\n issues.append(\n f\"Edge {edge.get('source')}→{edge.get('target')} superseded_by unknown edge_id '{succ}'\"\n )\n valid_at = _parse_iso(edge.get(\"valid_at\", \"\"))\n valid_until = _parse_iso(edge.get(\"valid_until\", \"\"))\n if valid_at and valid_until and valid_until \u003c valid_at:\n issues.append(\n f\"Edge {edge.get('source')}→{edge.get('target')} valid_until precedes valid_at\"\n )\n return issues\n\n\ndef check_orphans(nodes: list[dict], edges: list[dict]) -> list[str]:\n connected = set()\n for edge in edges:\n if edge.get(\"source\"):\n connected.add(edge[\"source\"])\n if edge.get(\"target\"):\n connected.add(edge[\"target\"])\n\n exempt = {\"asset\"}\n issues = []\n for node in nodes:\n nid = node.get(\"id\")\n if not nid or node.get(\"type\") in exempt:\n continue\n if nid not in connected:\n issues.append(f\"Node '{nid}' has zero edges (orphan)\")\n return issues\n\n\nCHECKS = [\n check_schema_compliance,\n check_dangling_refs,\n check_duplicate_ids,\n check_paths_exist,\n check_orphans,\n check_stale_tiers,\n check_supersession_integrity,\n]\n\n\ndef validate(graph_path: Path, repo_root: Path) -> dict:\n data = json.loads(graph_path.read_text(encoding=\"utf-8\"))\n nodes = data.get(\"nodes\", [])\n edges = data.get(\"edges\", [])\n\n results = []\n for check in CHECKS:\n if check is check_paths_exist:\n issues = check(nodes, edges, repo_root)\n else:\n issues = check(nodes, edges)\n results.append(\n {\n \"check\": check.__name__.replace(\"check_\", \"\"),\n \"passed\": not issues,\n \"issue_count\": len(issues),\n \"issues\": issues[:10],\n }\n )\n\n report = {\n \"graph\": str(graph_path),\n \"repo_root\": str(repo_root),\n \"checks_passed\": sum(1 for result in results if result[\"passed\"]),\n \"checks_total\": len(results),\n \"node_count\": len(nodes),\n \"edge_count\": len(edges),\n \"results\": results,\n }\n return report\n\n\ndef main():\n parser = argparse.ArgumentParser(description=\"Validate a context-graph.json file.\")\n parser.add_argument(\"graph\", help=\"Path to context-graph.json\")\n parser.add_argument(\n \"--repo\",\n help=\"Repository root for validating node paths. Defaults to the graph file's parent directory.\",\n )\n parser.add_argument(\"--output\", help=\"Optional path to write the JSON report.\")\n args = parser.parse_args()\n\n graph_path = Path(args.graph).resolve()\n if not graph_path.exists():\n print(f\"Error: graph not found: {graph_path}\", file=sys.stderr)\n sys.exit(1)\n\n repo_root = Path(args.repo).resolve() if args.repo else graph_path.parent\n report = validate(graph_path, repo_root)\n output = json.dumps(report, indent=2, ensure_ascii=False)\n print(output)\n\n if args.output:\n out_path = Path(args.output).resolve()\n out_path.parent.mkdir(parents=True, exist_ok=True)\n out_path.write_text(output, encoding=\"utf-8\")\n\n sys.exit(0 if report[\"checks_passed\"] == report[\"checks_total\"] else 1)\n\n\nif __name__ == \"__main__\":\n main()\n","content_type":"text/x-python; charset=utf-8","language":"python","size":8113,"content_sha256":"f35d2a866f35288b357f1bd51c06274bdbdf5c76d7e0458abafdd43541795db5"}],"content_json":{"type":"doc","content":[{"type":"heading","attrs":{"level":1},"content":[{"text":"Context Engineering","type":"text"}]},{"type":"paragraph","content":[{"text":"Use this skill to design repo-native agent context that is portable, high-signal, and maintainable. It owns the context model, migration path, maturity assessment, and context-graph discipline across ","type":"text"},{"text":"AGENTS.md","type":"text","marks":[{"type":"code_inline"}]},{"text":", runtime-specific layers, specs, rules, hooks, compiled markdown knowledge bases, and related artifacts.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Quick Reference","type":"text"}]},{"type":"table","attrs":{"layout":null},"content":[{"type":"tr","content":[{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Task","type":"text"}]}]},{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Use","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Portable repo instructions","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"the ","type":"text"},{"text":"agents-memory","type":"text","marks":[{"type":"code_inline"}]},{"text":" skill, ","type":"text"},{"text":"references/fast-track-guide.md","type":"text","marks":[{"type":"link","attrs":{"href":"references/fast-track-guide.md","title":null}}]}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Spec and plan flow","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"docs-ai-prd","type":"text","marks":[{"type":"link","attrs":{"href":"../docs-ai-prd/SKILL.md","title":null}}]},{"text":", ","type":"text"},{"text":"dev-workflow-planning","type":"text","marks":[{"type":"link","attrs":{"href":"../dev-workflow-planning/SKILL.md","title":null}}]}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Context graph design","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"references/context-graph-guide.md","type":"text","marks":[{"type":"link","attrs":{"href":"references/context-graph-guide.md","title":null}}]},{"text":", ","type":"text"},{"text":"python3 scripts/scan_context_artifacts.py --help","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"python3 scripts/validate_context_graph.py --help","type":"text","marks":[{"type":"code_inline"}]}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Hot-tier staleness + supersession integrity checks","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"scripts/validate_context_graph.py","type":"text","marks":[{"type":"code_inline"}]},{"text":" (checks ","type":"text"},{"text":"check_stale_tiers","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"check_supersession_integrity","type":"text","marks":[{"type":"code_inline"}]},{"text":")","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Query a context graph (PPR, BFS, fan-in, tier budget)","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"python3 scripts/query_context_graph.py \u003cgraph> --help","type":"text","marks":[{"type":"code_inline"}]},{"text":" (modes: ","type":"text"},{"text":"--node","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"--impact","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"--rank","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"--ppr --seed","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"--tier-budget","type":"text","marks":[{"type":"code_inline"}]},{"text":")","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Compiled markdown knowledge layer","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"the ","type":"text"},{"text":"docs-notes-retrieval","type":"text","marks":[{"type":"code_inline"}]},{"text":" skill, ","type":"text"},{"text":"references/context-graph-guide.md","type":"text","marks":[{"type":"link","attrs":{"href":"references/context-graph-guide.md","title":null}}]},{"text":", ","type":"text"},{"text":"references/multi-repo-strategy.md","type":"text","marks":[{"type":"link","attrs":{"href":"references/multi-repo-strategy.md","title":null}}]}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Multi-repo strategy","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"references/multi-repo-strategy.md","type":"text","marks":[{"type":"link","attrs":{"href":"references/multi-repo-strategy.md","title":null}}]},{"text":", ","type":"text"},{"text":"dev-context-multi-repo","type":"text","marks":[{"type":"link","attrs":{"href":"../dev-context-multi-repo/SKILL.md","title":null}}]}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Pick a framework (superpowers, GSD, Spec Kit, OpenSpec, …)","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"references/framework-selection-matrix.md","type":"text","marks":[{"type":"link","attrs":{"href":"references/framework-selection-matrix.md","title":null}}]}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Regulated environment rollout","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"references/regulated-environment-patterns.md","type":"text","marks":[{"type":"link","attrs":{"href":"references/regulated-environment-patterns.md","title":null}}]},{"text":", ","type":"text"},{"text":"assets/ai-agent-governance.md","type":"text","marks":[{"type":"link","attrs":{"href":"assets/ai-agent-governance.md","title":null}}]},{"text":", ","type":"text"},{"text":"assets/compliance-fca-emi.md","type":"text","marks":[{"type":"link","attrs":{"href":"assets/compliance-fca-emi.md","title":null}}]}]}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"When to Use","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Set up or modernize ","type":"text"},{"text":"AGENTS.md","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"CLAUDE.md","type":"text","marks":[{"type":"code_inline"}]},{"text":", Copilot instructions, hooks, or agent rule layers.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Migrate a repo from ad hoc prompting to durable agent context.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Decide what belongs in always-on context vs docs, retrieval, or on-demand artifacts.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Build a context graph and loading-tier model for a repo.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Define a maturity path for AI-assisted development across one repo or a portfolio.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Design the operating model for a large compiled repo knowledge base where agents create and refresh repo descriptions, indexes, and reports from structured artifacts.","type":"text"}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Route Elsewhere","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Writing the portable repo instructions themselves: use the ","type":"text"},{"text":"agents-memory","type":"text","marks":[{"type":"code_inline"}]},{"text":" skill.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Repo-portfolio discovery and hub generation: use ","type":"text"},{"text":"dev-context-multi-repo","type":"text","marks":[{"type":"link","attrs":{"href":"../dev-context-multi-repo/SKILL.md","title":null}}]},{"text":".","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Symbol-level code graphs and blast radius: use ","type":"text"},{"text":"dev-context-code-graph","type":"text","marks":[{"type":"link","attrs":{"href":"../dev-context-code-graph/SKILL.md","title":null}}]},{"text":".","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Task decomposition and verification plans: use ","type":"text"},{"text":"dev-workflow-planning","type":"text","marks":[{"type":"link","attrs":{"href":"../dev-workflow-planning/SKILL.md","title":null}}]},{"text":".","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Hooks, MCP, or subagent implementation details: use ","type":"text"},{"text":"agents-hooks","type":"text","marks":[{"type":"link","attrs":{"href":"../agents-hooks/SKILL.md","title":null}}]},{"text":", ","type":"text"},{"text":"agents-mcp","type":"text","marks":[{"type":"link","attrs":{"href":"../agents-mcp/SKILL.md","title":null}}]},{"text":", or ","type":"text"},{"text":"agents-subagents","type":"text","marks":[{"type":"link","attrs":{"href":"../agents-subagents/SKILL.md","title":null}}]},{"text":".","type":"text"}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Defaults","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Keep ","type":"text"},{"text":"AGENTS.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" as the portable baseline.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Add runtime-specific layers only when they unlock a real capability.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Put only non-inferable constraints in always-on context.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Use a small hot instruction layer plus a larger compiled markdown knowledge base instead of one giant manifest.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Prefer better state and structure over more text.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Let the LLM maintain cold knowledge layers and derived notes; humans review policy, safety, and architectural constraints.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Prefer outputs as durable files that can be filed back into the repo context instead of living only in chat history.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Run a documentation placement gate before creating new Markdown; prefer updating canonical docs or generated context artifacts over adding one-off files.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Treat context changes like code changes: review, validate, and prune.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Generate ","type":"text"},{"text":"context-graph.json","type":"text","marks":[{"type":"code_inline"}]},{"text":" once a repo reaches structured-context maturity.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Tool-set minimization","type":"text","marks":[{"type":"strong"}]},{"text":": Only give agents the tools they actually need. If a human engineer cannot say which tool should be used for a given task, an AI agent will not do better. Start small; expand on demand.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Resolver over accretion","type":"text","marks":[{"type":"strong"}]},{"text":": when the hot layer starts growing to handle a new edge case, prefer a pointer-style resolver (description-matched skill selection) that loads the right document on demand. See ","type":"text"},{"text":"references/context-resolver-pattern.md","type":"text","marks":[{"type":"link","attrs":{"href":"references/context-resolver-pattern.md","title":null}}]},{"text":".","type":"text"}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"May 2026 Validation Stance","type":"text"}]},{"type":"paragraph","content":[{"text":"Current context engineering should treat context as an evolving system, not a larger prompt. The strongest source-backed principles are:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Context is finite working memory: optimize for the smallest high-signal token set that changes the outcome, then load deeper evidence just in time.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Context adaptation is a first-class engineering loop: generate, reflect, curate, and validate updates without letting iterative summaries collapse detail.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Raw evidence must stay retrievable. Summaries, memories, and graph nodes are routing layers; they are not substitutes for source files, transcripts, artifacts, or primary docs.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Memory needs lifecycle semantics: provenance, freshness, supersession, contradiction handling, and user or tenant scope. Use temporal graph memory only when temporal reasoning, relationship change, or cross-session continuity matters.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Graph retrieval is conditional. Use direct reads or lexical search for simple lookup; use graph traversal, PPR, or community summaries only for relational, multi-hop, or global sensemaking questions.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Tool and context surfaces should be minimal and governed. More tools or more always-on rules create ambiguity unless the selection boundary is explicit.","type":"text"}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Multi-Tool Composition","type":"text"}]},{"type":"paragraph","content":[{"text":"Teams that ship fastest use the right tool for each task rather than forcing one agent to do everything. As of May 2026, the most effective pattern is:","type":"text"}]},{"type":"table","attrs":{"layout":null},"content":[{"type":"tr","content":[{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Tool","type":"text"}]}]},{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Best For","type":"text"}]}]},{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Context Model","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Cursor / IDE agent","type":"text","marks":[{"type":"strong"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Day-to-day editing, inline completions, tab-to-accept, quick refactors","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"IDE-native: open files + project index","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Claude Code","type":"text","marks":[{"type":"strong"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Complex agentic tasks, multi-file changes, agent teams, code review, architecture","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"CLI: AGENTS.md + .claude/rules + skills + subagents","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Codex","type":"text","marks":[{"type":"strong"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Parallel background work, batch processing, CI-adjacent tasks","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Threads: AGENTS.md + .codex/agents + sandboxed workers","type":"text"}]}]}]}]},{"type":"paragraph","content":[{"text":"How to keep context consistent across tools:","type":"text","marks":[{"type":"strong"}]}]},{"type":"ordered_list","attrs":{"order":1,"listStyle":"number"},"content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"AGENTS.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" is the portable baseline — all three tools read it.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Runtime-specific layers (","type":"text"},{"text":".claude/rules/","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":".codex/agents/","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":".cursor/rules/","type":"text","marks":[{"type":"code_inline"}]},{"text":") extend the baseline for each tool's strengths.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"docs/","type":"text","marks":[{"type":"code_inline"}]},{"text":" in the repo is universally readable — invest knowledge there, not in tool-specific memory.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Use ","type":"text"},{"text":"dev-context-multi-repo","type":"text","marks":[{"type":"link","attrs":{"href":"../dev-context-multi-repo/SKILL.md","title":null}}]},{"text":" to keep multi-repo context aligned across tools.","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Anti-pattern","type":"text","marks":[{"type":"strong"}]},{"text":": Duplicating conventions in Cursor rules, Claude rules, AND Codex agents. Write it once in ","type":"text"},{"text":"AGENTS.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" or ","type":"text"},{"text":"docs/","type":"text","marks":[{"type":"code_inline"}]},{"text":", then reference it.","type":"text"}]},{"type":"paragraph","content":[{"text":"Stack on top of the IDE layer","type":"text","marks":[{"type":"strong"}]},{"text":" when discipline drift or feature ambiguity is the bottleneck:","type":"text"}]},{"type":"table","attrs":{"layout":null},"content":[{"type":"tr","content":[{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Layer","type":"text"}]}]},{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Role","type":"text"}]}]},{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Pick from","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"L0 portable baseline","type":"text","marks":[{"type":"strong"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Cross-tool conventions","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"AGENTS.md","type":"text","marks":[{"type":"code_inline"}]}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"L1 runtime-specific","type":"text","marks":[{"type":"strong"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Tool-specific extensions","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":".claude/rules/","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":".codex/agents/","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":".cursor/rules/","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":".github/copilot-instructions.md","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":".clinerules/","type":"text","marks":[{"type":"code_inline"}]},{"text":", Aider ","type":"text"},{"text":"CONVENTIONS.md","type":"text","marks":[{"type":"code_inline"}]}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"L2 capability / methodology","type":"text","marks":[{"type":"strong"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"On-demand or enforced discipline","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Claude Code Skills · superpowers (obra/superpowers) · GSD (gsd-build/get-shit-done)","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"L3 artifact pipeline","type":"text","marks":[{"type":"strong"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Spec → plan → tasks → code","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"GitHub Spec Kit (","type":"text"},{"text":".specify/specs/","type":"text","marks":[{"type":"code_inline"}]},{"text":") · OpenSpec (Fission-AI, ","type":"text"},{"text":"openspec/changes/","type":"text","marks":[{"type":"code_inline"}]},{"text":")","type":"text"}]}]}]}]},{"type":"paragraph","content":[{"text":"L0 is mandatory; L1 is mandatory for tools that don't read AGENTS.md natively; L2 and L3 are optional but high-leverage when their named symptoms are present. Full decision matrix, stack recipes, and anti-stacks in ","type":"text"},{"text":"references/framework-selection-matrix.md","type":"text","marks":[{"type":"link","attrs":{"href":"references/framework-selection-matrix.md","title":null}}]},{"text":".","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Workflow","type":"text"}]},{"type":"ordered_list","attrs":{"order":1,"listStyle":"number"},"content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Identify the toolchain, repo shape, and the behaviors that need to be influenced.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Define the portable baseline, the compiled knowledge layer, and the minimum runtime-specific layers needed.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Separate hot instructions from warm compiled knowledge and cold raw evidence the agent can inspect on demand.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Install the right supporting artifacts: specs, plans, hooks, rules, subagents, docs, and index pages that make the compiled layer navigable.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Decide which answers or analyses should become durable markdown files, diagrams, or reports instead of one-off chat output, and place them under the repo's docs governance model.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Generate and validate a context graph when the repo has enough artifacts to justify it.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Run health checks over the context system for stale dependencies, missing summaries, inconsistent claims, and dead links.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Score maturity, then decide whether the next step is onboarding, pruning, or automation.","type":"text"}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"ASCII Flow","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"text"},"content":[{"text":"context engineering request\n -> identify toolchain, repo shape, and target agent behaviors\n -> define portable baseline in AGENTS.md\n -> split layers\n +-- hot -> non-inferable execution policy\n +-- warm -> compiled docs, hubs, indexes, context graph\n +-- cold -> raw evidence and primary artifacts\n -> add runtime-specific rules only where they unlock capability\n -> run docs placement and context hygiene gates\n -> validate graph, freshness, links, and contradictions\n -> decide onboarding, pruning, automation, or maturity next step","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Core Decisions","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Cross-Tool Context Model","type":"text"}]},{"type":"paragraph","content":[{"text":"Use layers intentionally:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"AGENTS.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" for hot shared execution policy","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"CLAUDE.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" and ","type":"text"},{"text":".claude/*","type":"text","marks":[{"type":"code_inline"}]},{"text":" only for Claude-specific behavior","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":".github/*","type":"text","marks":[{"type":"code_inline"}]},{"text":" only for GitHub or Copilot-specific behavior","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"compiled markdown hubs, index pages, and context graphs for reusable repo knowledge","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"raw evidence packs for articles, repos, transcripts, screenshots, and other source captures","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"docs and specs for on-demand context","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"external knowledge via skills, MCP, or runtime retrieval","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Do not assume one tool’s memory model maps cleanly onto another.","type":"text"}]},{"type":"paragraph","content":[{"text":"At small and medium corpus sizes, a maintained index plus concise summaries is often enough; do not add RAG just because a knowledge base exists.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"What Belongs in Context","type":"text"}]},{"type":"paragraph","content":[{"text":"Keep always-on context for:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"custom commands and repo workflows","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"safety or compliance constraints","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"fragile architecture boundaries","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"known failure modes and approval rules","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"cross-repo data flows that are hard to infer locally","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Keep the compiled knowledge base for:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"domain summaries and concept pages","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"cross-repo maps and architecture views","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"volatile tool or product findings that should be re-checked but are still worth preserving","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"derived outputs such as reports, diagrams, and slide notes that should compound over time","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Keep out:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"README-style summaries","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"big file inventories","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"dependency lists the agent can inspect","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"duplicated coding-style philosophy","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"docs that add no execution constraint","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"raw source dumps that belong in evidence folders instead of the hot instruction layer","type":"text"}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Documentation Placement Resolver","type":"text"}]},{"type":"paragraph","content":[{"text":"Before creating a context artifact, choose the smallest durable home:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"hot instruction: ","type":"text"},{"text":"AGENTS.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" / ","type":"text"},{"text":"CLAUDE.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" for short execution policy and pointers only","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"canonical docs: ","type":"text"},{"text":"docs/tech/","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"docs/architecture/","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"docs/api/","type":"text","marks":[{"type":"code_inline"}]},{"text":", or equivalent for stable truth","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"operational docs: ","type":"text"},{"text":"docs/operations/","type":"text","marks":[{"type":"code_inline"}]},{"text":" or ","type":"text"},{"text":"docs/runbooks/","type":"text","marks":[{"type":"code_inline"}]},{"text":" for procedures and incident/release steps","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"reports and plans: ","type":"text"},{"text":"docs/reports/","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"docs/specs/","type":"text","marks":[{"type":"code_inline"}]},{"text":", or ","type":"text"},{"text":"docs/plans/","type":"text","marks":[{"type":"code_inline"}]},{"text":" with lifecycle state and integration path","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"generated context: ","type":"text"},{"text":"docs/context/","type":"text","marks":[{"type":"code_inline"}]},{"text":" or ","type":"text"},{"text":"context/","type":"text","marks":[{"type":"code_inline"}]},{"text":" with structured inputs and rebuild commands","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"raw evidence: ","type":"text"},{"text":"raw/","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"evidence/","type":"text","marks":[{"type":"code_inline"}]},{"text":", or repo-specific captures excluded from hot context","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"If the artifact has no owner, lifecycle, index link, or rebuild path, do not create a new Markdown file. Update the closest canonical doc or keep the result in the task thread.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Knowledge Base Pattern","type":"text"}]},{"type":"paragraph","content":[{"text":"The strongest default is a three-layer repo-native system:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"hot layer: portable instructions and execution policy","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"compiled layer: LLM-maintained markdown with summaries, backlinks, concept pages, and index files","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"raw layer: source captures and evidence the agent can revisit when a compiled claim needs re-verification","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Humans should mostly edit the hot layer and review the compiled layer. The compiled and raw layers can be largely agent-maintained if validation and review gates are in place.","type":"text"}]},{"type":"paragraph","content":[{"text":"For portfolio hubs, add one more practical rule:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"structured artifacts such as profile JSON, graph JSON, and freshness reports should be the compiler inputs for markdown pages, not sidecars that drift independently","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"This is how you keep repo descriptions, concept notes, and system maps synchronized at scale.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Context Graph","type":"text"}]},{"type":"paragraph","content":[{"text":"Use a context graph to map relationships between:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"instructions","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"rules","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"specs","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"plans","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"hooks","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"subagents","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"references and assets","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Generate it when the repo reaches L2+ maturity and use it to assess loading tiers, blast radius, and stale dependencies before changing core artifacts.","type":"text"}]},{"type":"paragraph","content":[{"text":"The context graph complements the compiled markdown layer. Use the graph for relationship integrity and loading-tier analysis, then publish the useful findings back into markdown notes or reports.","type":"text"}]},{"type":"paragraph","content":[{"text":"When the repo is a native/mobile codebase, pair this skill with:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"dev-context-multi-repo","type":"text","marks":[{"type":"link","attrs":{"href":"../dev-context-multi-repo/SKILL.md","title":null}}]},{"text":" to classify the repo correctly from project files such as ","type":"text"},{"text":"project.yml","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":".xcodeproj","type":"text","marks":[{"type":"code_inline"}]},{"text":", or ","type":"text"},{"text":"Package.swift","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"dev-context-code-graph","type":"text","marks":[{"type":"link","attrs":{"href":"../dev-context-code-graph/SKILL.md","title":null}}]},{"text":" to build the single-repo symbol graph from Swift or mixed-language source after generated build trees are excluded","type":"text"}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Spec-Driven Development","type":"text"}]},{"type":"paragraph","content":[{"text":"Use full spec-driven development when ambiguity would otherwise cause agent drift:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"specify what","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"plan how","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"decompose into bounded tasks","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"implement with the right context attached","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Use direct prompting for small fixes and low-ambiguity work.","type":"text"}]},{"type":"paragraph","content":[{"text":"For recurring hub maintenance, treat page generation as a compiler pass:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"define the source artifacts","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"define the target page shape","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"define what gets regenerated incrementally","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"define the lint or health checks that block publication","type":"text"}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Regulated Environments","type":"text"}]},{"type":"paragraph","content":[{"text":"In regulated environments, context engineering must preserve:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"auditability","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"separation of duties","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"sensitive-data boundaries","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"provider portability","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"named human accountability","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"If those requirements are real, treat context artifacts as part of the control surface, not just helper docs.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Output Modes","type":"text"}]},{"type":"paragraph","content":[{"text":"Default to one of these:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Repo context package: portable baseline, runtime-specific layers, and supporting artifact map.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Knowledge-base operating model: hot instructions, compiled markdown layer, raw evidence layout, and maintenance loop.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Hub compiler design: source artifacts, generated page types, incremental rebuild strategy, and validation gates.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Migration plan: current-state issues, target shape, phased rollout, and validation steps.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Maturity assessment: current level, blockers, and next infrastructure step.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Regulated rollout brief: control requirements, artifact placement, and review gates.","type":"text"}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Known Traps","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Pushing too much policy, process, and repo knowledge into always-on instructions until agents ignore or truncate the layer that actually matters.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Building runtime-specific rule stacks before the portable baseline is stable, which guarantees drift across tools.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Treating a compiled markdown hub as static documentation instead of a maintained product with freshness and validation loops.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Shipping large context changes without a clear loading-tier model, so hot instructions and cold evidence get mixed together.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Assuming tool abundance helps by default instead of reducing the tool set to the smallest model the team can actually govern.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Creating a new Markdown file for every useful answer instead of routing it into the existing docs, report, or generated-context lifecycle.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Mixing operational runbooks, agent hot memory, canonical docs, and generated context until no file has clear authority.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"LLM-summarizing raw evidence before retrieval. Measured failure mode: on LongMemEval, verbatim-text retrieval scores 96.6% R@5 while LLM-extracted memory systems score 30-45% on ConvoMem — preemptive summarization throws away the context that made the answer findable. Keep the raw layer raw. (","type":"text"},{"text":"source","type":"text","marks":[{"type":"link","attrs":{"href":"https://github.com/MemPalace/mempalace","title":null}}]},{"text":" ","type":"text"},{"text":"benchmarks/BENCHMARKS.md","type":"text","marks":[{"type":"code_inline"}]},{"text":")","type":"text"}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Anti-Patterns","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"One giant context file.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Using ","type":"text"},{"text":"AGENTS.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" as a general knowledge base instead of a hot instruction layer.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Blindly generating context from docs without pruning.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Using more text instead of fixing state and structure.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Locking policy to one vendor format.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Treating context as static instead of a maintained system.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Keeping execution-critical guidance outside the repo.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Letting useful answers disappear in chat instead of filing them back into the compiled layer.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Filing useful answers as unindexed one-off Markdown files with no owner, lifecycle state, or canonical parent.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Adding heavy retrieval infrastructure before maintaining indexes, summaries, and basic health checks.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Treating JSON, graphs, and markdown pages as separate truth systems instead of a compiler pipeline.","type":"text"}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Navigation","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Core references: ","type":"text"},{"text":"references/fast-track-guide.md","type":"text","marks":[{"type":"link","attrs":{"href":"references/fast-track-guide.md","title":null}}]},{"text":", ","type":"text"},{"text":"references/framework-selection-matrix.md","type":"text","marks":[{"type":"link","attrs":{"href":"references/framework-selection-matrix.md","title":null}}]},{"text":", ","type":"text"},{"text":"references/information-routing-rules.md","type":"text","marks":[{"type":"link","attrs":{"href":"references/information-routing-rules.md","title":null}}]},{"text":", ","type":"text"},{"text":"references/context-resolver-pattern.md","type":"text","marks":[{"type":"link","attrs":{"href":"references/context-resolver-pattern.md","title":null}}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Context graph and multi-repo strategy: ","type":"text"},{"text":"references/context-graph-guide.md","type":"text","marks":[{"type":"link","attrs":{"href":"references/context-graph-guide.md","title":null}}]},{"text":", ","type":"text"},{"text":"references/multi-repo-strategy.md","type":"text","marks":[{"type":"link","attrs":{"href":"references/multi-repo-strategy.md","title":null}}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Regulated and governed rollout: ","type":"text"},{"text":"references/regulated-environment-patterns.md","type":"text","marks":[{"type":"link","attrs":{"href":"references/regulated-environment-patterns.md","title":null}}]},{"text":", ","type":"text"},{"text":"assets/ai-agent-governance.md","type":"text","marks":[{"type":"link","attrs":{"href":"assets/ai-agent-governance.md","title":null}}]},{"text":", ","type":"text"},{"text":"assets/data-handling-gdpr-pci.md","type":"text","marks":[{"type":"link","attrs":{"href":"assets/data-handling-gdpr-pci.md","title":null}}]},{"text":", ","type":"text"},{"text":"assets/compliance-fca-emi.md","type":"text","marks":[{"type":"link","attrs":{"href":"assets/compliance-fca-emi.md","title":null}}]},{"text":", ","type":"text"},{"text":"assets/pr-template-ai-disclosure.md","type":"text","marks":[{"type":"link","attrs":{"href":"assets/pr-template-ai-disclosure.md","title":null}}]},{"text":", ","type":"text"},{"text":"assets/fca-compliance-gate.yml","type":"text","marks":[{"type":"link","attrs":{"href":"assets/fca-compliance-gate.yml","title":null}}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Scripts and schema: ","type":"text"},{"text":"scripts/scan_context_artifacts.py","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"scripts/validate_context_graph.py","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"scripts/query_context_graph.py","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"schemas/context-graph.schema.json","type":"text","marks":[{"type":"link","attrs":{"href":"schemas/context-graph.schema.json","title":null}}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Related skills: the ","type":"text"},{"text":"agents-memory","type":"text","marks":[{"type":"code_inline"}]},{"text":" skill, ","type":"text"},{"text":"docs-ai-prd","type":"text","marks":[{"type":"link","attrs":{"href":"../docs-ai-prd/SKILL.md","title":null}}]},{"text":", ","type":"text"},{"text":"dev-workflow-planning","type":"text","marks":[{"type":"link","attrs":{"href":"../dev-workflow-planning/SKILL.md","title":null}}]},{"text":", ","type":"text"},{"text":"agents-hooks","type":"text","marks":[{"type":"link","attrs":{"href":"../agents-hooks/SKILL.md","title":null}}]},{"text":", ","type":"text"},{"text":"agents-mcp","type":"text","marks":[{"type":"link","attrs":{"href":"../agents-mcp/SKILL.md","title":null}}]},{"text":", ","type":"text"},{"text":"agents-subagents","type":"text","marks":[{"type":"link","attrs":{"href":"../agents-subagents/SKILL.md","title":null}}]},{"text":", ","type":"text"},{"text":"agents-swarm-orchestration","type":"text","marks":[{"type":"link","attrs":{"href":"../agents-swarm-orchestration/SKILL.md","title":null}}]},{"text":", ","type":"text"},{"text":"dev-context-multi-repo","type":"text","marks":[{"type":"link","attrs":{"href":"../dev-context-multi-repo/SKILL.md","title":null}}]},{"text":", ","type":"text"},{"text":"dev-context-code-graph","type":"text","marks":[{"type":"link","attrs":{"href":"../dev-context-code-graph/SKILL.md","title":null}}]}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Fact-Checking","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Known bugs, regressions, framework/compiler/runtime footguns, and version-specific crash or workaround guidance must be verified against current primary web sources before being treated as current fact.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"External source mapping lives in ","type":"text"},{"text":"data/sources.json","type":"text","marks":[{"type":"link","attrs":{"href":"data/sources.json","title":null}}]},{"text":".","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Product capabilities, runtime semantics, and regulator guidance are volatile; verify current primary sources before making definitive claims about tools or compliance timelines.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Remove or mark any claim that cannot be re-verified from a primary source.","type":"text"}]}]}]},{"type":"hr","attrs":{"markup":"---"}}]},"metadata":{"date":"2026-06-05","name":"dev-context-engineering","author":"@skillopedia","source":{"stars":60,"repo_name":"ai-agents-public","origin_url":"https://github.com/vasilyu1983/ai-agents-public/blob/HEAD/frameworks/shared-skills/skills/dev-context-engineering/SKILL.md","repo_owner":"vasilyu1983","body_sha256":"de8a989caaf8be960ef9467840cc20db825658210d17526587525fc450763cb6","cluster_key":"b0cda5b28a7ee7cfef89e544e2aa7f544c1f23fa8550681e78af74dd207e1346","clean_bundle":{"format":"clean-skill-bundle-v1","source":"vasilyu1983/ai-agents-public/frameworks/shared-skills/skills/dev-context-engineering/SKILL.md","attachments":[{"id":"dc9a93b1-de4c-56ea-97db-152b2736c646","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/dc9a93b1-de4c-56ea-97db-152b2736c646/attachment.md","path":"assets/ai-agent-governance.md","size":3585,"sha256":"1479b85ffa72ee46927412ddea22dc1213960c0e742e9670b5bf1615df1b24c0","contentType":"text/markdown; charset=utf-8"},{"id":"888b8c18-28b6-563e-9155-ff404c85f4be","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/888b8c18-28b6-563e-9155-ff404c85f4be/attachment.md","path":"assets/compliance-fca-emi.md","size":2944,"sha256":"b551b6413e89e7f80239fe3fdf50127f67798d6d4cab7688231b10cf49063352","contentType":"text/markdown; charset=utf-8"},{"id":"ca4650f7-0274-5224-950a-5d6aba50c98d","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/ca4650f7-0274-5224-950a-5d6aba50c98d/attachment.md","path":"assets/data-handling-gdpr-pci.md","size":3363,"sha256":"8ed951078a170eff479811f97974912c02b76c0ab581cbed31cdf2552607abdb","contentType":"text/markdown; charset=utf-8"},{"id":"f8302233-a789-5d47-a2b1-68cde6afd634","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/f8302233-a789-5d47-a2b1-68cde6afd634/attachment.yml","path":"assets/fca-compliance-gate.yml","size":7262,"sha256":"afcd3cde9869b723222de5bec97ffb2235914061070709d758a3df02d89f56e6","contentType":"application/yaml; charset=utf-8"},{"id":"0cb9818d-362a-574d-a869-d42869c33e83","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/0cb9818d-362a-574d-a869-d42869c33e83/attachment.md","path":"assets/pr-template-ai-disclosure.md","size":1966,"sha256":"569488c9fcfffc3470d9db72ee9b5a5b44fb6aa152b2a753eb942bb68b70d420","contentType":"text/markdown; charset=utf-8"},{"id":"111a431c-d087-5f46-86b5-7c884e4e2641","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/111a431c-d087-5f46-86b5-7c884e4e2641/attachment.json","path":"data/sources.json","size":79104,"sha256":"83b46bc70648a6102c07453660c2f7bc4fd5fdfae711d6a69675881ba4be5f85","contentType":"application/json; charset=utf-8"},{"id":"3b7601b3-81e6-54b9-b3a0-d0faddd02c4f","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/3b7601b3-81e6-54b9-b3a0-d0faddd02c4f/attachment.md","path":"references/context-graph-guide.md","size":11492,"sha256":"b934f8d925c95d765f96ed0eb5626e226c490d6bf9542824a20bc3ab27da35ca","contentType":"text/markdown; charset=utf-8"},{"id":"af038e62-1cbf-5ca6-a5a0-11cdde7c3f22","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/af038e62-1cbf-5ca6-a5a0-11cdde7c3f22/attachment.md","path":"references/context-resolver-pattern.md","size":4303,"sha256":"7dd9d895f36c6a7a06484acdf9399e777a565ecab592754e08e2fbd801bd2191","contentType":"text/markdown; charset=utf-8"},{"id":"4ffbac23-5c8f-59dd-8889-ebaec6a60ea0","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/4ffbac23-5c8f-59dd-8889-ebaec6a60ea0/attachment.md","path":"references/fast-track-guide.md","size":13347,"sha256":"39dc9b7c725d3107d3c06aa9aec44505451c012f2ed91ddb1e8b0f8efcffc838","contentType":"text/markdown; charset=utf-8"},{"id":"838586fe-aa41-5bca-95c5-1fc58c66611a","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/838586fe-aa41-5bca-95c5-1fc58c66611a/attachment.md","path":"references/framework-selection-matrix.md","size":9310,"sha256":"db2c3e5231cbd5c24bd42c9cd8e67951139f49bbcb80d5fcbb40673cf0478faf","contentType":"text/markdown; charset=utf-8"},{"id":"ee1bba8c-f435-5fa6-9c34-219eff04a4eb","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/ee1bba8c-f435-5fa6-9c34-219eff04a4eb/attachment.md","path":"references/information-routing-rules.md","size":4938,"sha256":"ce1ef84d16636a72a35aa4e21e83535e5e5909c8390106094c0204680f62c5ff","contentType":"text/markdown; charset=utf-8"},{"id":"9fe347ba-6242-5d47-9f8c-e492626f788e","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/9fe347ba-6242-5d47-9f8c-e492626f788e/attachment.md","path":"references/multi-repo-strategy.md","size":22274,"sha256":"6be3ac8e2a0562d815c773094c9b324e43ae3f529e711ae3943c91e04cd017d1","contentType":"text/markdown; charset=utf-8"},{"id":"543c3a3c-c9dc-5d56-b100-91327c743e6a","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/543c3a3c-c9dc-5d56-b100-91327c743e6a/attachment.md","path":"references/regulated-environment-patterns.md","size":20387,"sha256":"9f28995f91d766a94492f0eeaf9bef08f2cda9762471f556a7d0d4d360197b4c","contentType":"text/markdown; charset=utf-8"},{"id":"77501036-7b4f-51d2-af47-74324f3f35c0","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/77501036-7b4f-51d2-af47-74324f3f35c0/attachment.json","path":"schemas/context-graph.schema.json","size":5514,"sha256":"e3f29b3172283f6a843bbac18df21a0058e8a941cd98498889c45c74c500ad0e","contentType":"application/json; charset=utf-8"},{"id":"56e0310e-7401-56fc-8d40-642a763e2aa2","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/56e0310e-7401-56fc-8d40-642a763e2aa2/attachment.pyc","path":"scripts/__pycache__/query_context_graph.cpython-314.pyc","size":20993,"sha256":"d5cbf82c7999c1d641501c8d765cdc8a0c531bbfc007f621febe34c1e9add0b9","contentType":"application/x-python-code"},{"id":"6e3d73d3-6bc5-5447-bf3b-4fd474cf642b","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/6e3d73d3-6bc5-5447-bf3b-4fd474cf642b/attachment.pyc","path":"scripts/__pycache__/scan_context_artifacts.cpython-314.pyc","size":13082,"sha256":"63f6763d7878aae8093fe3558f7d3ad73f1b026b05103a265a358c0c8d3eb101","contentType":"application/x-python-code"},{"id":"19eed1cd-9685-5295-ad25-b7477874d11a","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/19eed1cd-9685-5295-ad25-b7477874d11a/attachment.pyc","path":"scripts/__pycache__/validate_context_graph.cpython-314.pyc","size":13941,"sha256":"10cc9fe7408229523c7b632beba83ac5a38c4f2829be03b379decfa7925f5a63","contentType":"application/x-python-code"},{"id":"7818b3fc-d46b-58aa-b823-158bcd7309aa","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/7818b3fc-d46b-58aa-b823-158bcd7309aa/attachment.py","path":"scripts/query_context_graph.py","size":13190,"sha256":"dfc1eb3a3f4e8cc477cc4dca19fa6af18bb0c85d013bad0b90620de9abdd5007","contentType":"text/x-python; charset=utf-8"},{"id":"82dc47dc-5def-5504-89bd-0553126f7988","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/82dc47dc-5def-5504-89bd-0553126f7988/attachment.py","path":"scripts/scan_context_artifacts.py","size":11253,"sha256":"389bbf35a02b1ae146918fa3be66c4358c13fdff82a568fb6c89bf063c955923","contentType":"text/x-python; charset=utf-8"},{"id":"55420638-3247-5426-9d2b-cf989907c8dd","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/55420638-3247-5426-9d2b-cf989907c8dd/attachment.py","path":"scripts/validate_context_graph.py","size":8113,"sha256":"f35d2a866f35288b357f1bd51c06274bdbdf5c76d7e0458abafdd43541795db5","contentType":"text/x-python; charset=utf-8"}],"bundle_sha256":"dc9b26da9bbae55c74d431c5c538114790a22a6707dfcd8d0d18132c599540d4","attachment_count":20,"text_attachments":17,"attachment_storage":"skillopedia-attachments-v1","binary_attachments":3,"excluded_attachments":[]},"cluster_size":1,"skill_md_path":"frameworks/shared-skills/skills/dev-context-engineering/SKILL.md","import_metadata":{"date":"2026-06-05","author":"@skillopedia","version":"v1","category":"productivity-workflow","category_label":"Productivity"},"exact_dupes_collapsed_into_this":0},"version":"v1","category":"productivity-workflow","import_tag":"clean-skills-v1","description":"Context-driven AI development with AGENTS.md, repo knowledge bases, Claude Code, Codex, and Copilot. Use when adopting repo-native AI workflows or multi-repo setups.","compatibility":"Portable core. Works on Claude Code and Codex."}},"renderedAt":1782993524447}

Important: agents should read /llm.txt, /llms.txt, or /.well-known/skills.json to discover the public Skillopedia API.