npm - @grvmithas/create-aies-kit - Versions diffs - 1.1.0 → 1.3.0 - Mend

@grvmithas/create-aies-kit 1.1.0 → 1.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (6) hide show

package/README.md +15 -3
package/bin/create-aies-kit.js +4 -2
package/lib/kit-core/embedded-corpus.js +20 -2
package/lib/kit-core/generate.js +218 -117
package/lib/kit-core/install-api.js +52 -42
package/package.json +1 -1

package/README.md CHANGED Viewed

@@ -17,6 +17,15 @@ npx @grvmithas/create-aies-kit@latest enhance
 Then open `*/prompts/enhance-repo.prompt.md` in your IDE agent so it adapts artifacts to your conventions.
+## Layout contract
+| Location | Contents |
+|----------|----------|
+| IDE folder (`.cursor` / `.github` / `.claude` / …) | **prompts**, **skills**, **agents** only (+ IDE rules / MCP config) |
+| Repo root | `cookbook/{stack}/`, `guides/`, `mcps/`, `templates/`, `MODEL_POLICY.md`, root instruction files |
+**Anti-pattern:** Nesting cookbook (or guides/MCP specs) under `.github/`. That folder is for Copilot discovery and GitHub metadata only.
 ## What you get
 | Path | Purpose |
@@ -27,7 +36,8 @@ Then open `*/prompts/enhance-repo.prompt.md` in your IDE agent so it adapts arti
 | `CLAUDE.md` | Root Claude / multi-IDE contract |
 | `copilot-instructions.md` | Root Copilot instructions |
 | `.github/copilot-instructions.md` | Copilot discovery copy |
-| IDE folder | skills, prompts (incl. create-* + enhance), cookbook, agents, **all MCP specs**, guides |
+| IDE `prompts/` `skills/` `agents/` | Lifecycle + create/enhance artifacts |
+| `cookbook/{stack}/` | Full stack cookbook at **repo root** |
 Maturity only changes the **reading path** in `AIES.md`.
@@ -39,5 +49,7 @@ Docs: https://www.ai-standards.dev/quickstart
 ## Changelog
-- **1.1.0** — Self-contained package (embedded corpus + generator). IDE-native install, `enhance`, AGENTS.md, full cookbook/MCP catalog. Fixes broken 1.0.0 that omitted kit-core.
-- **1.0.0** — Initial publish (incomplete; upgrade to ≥1.1.0).
+- **1.3.0** — Ephemeral `plans/{STORY_ID}-plan.md` + `reviews/{STORY_ID}-code-review.md`; agent hooks shipped; enhance-repo v2 with IDE chat invoke + deep guardrail scan (lint/style FE+BE).
+- **1.2.0** — Layout fix: cookbook/guides/mcps/templates at repo root for all IDEs; `.github` holds prompts/skills/agents (+ copilot-instructions) only.
+- **1.1.0** — Self-contained package (embedded corpus + generator).
+- **1.0.0** — Initial publish (incomplete; do not use).

package/bin/create-aies-kit.js CHANGED Viewed

@@ -26,8 +26,10 @@ Usage:
   npx @grvmithas/create-aies-kit --stack nextjs --ide cursor --role fullstack --maturity intermediate --goal new-product --model claude --data-class internal --yes
   npx @grvmithas/create-aies-kit enhance
-Install writes: AIES.md, implementation_plan.md, CLAUDE.md, copilot-instructions.md,
-skills/prompts/cookbook/agents/mcps under .cursor | .github | .claude | …
+Install writes: AIES.md, implementation_plan.md, CLAUDE.md, AGENTS.md,
+IDE prompts/skills/agents under .cursor | .github | .claude | …
+plus repo-root cookbook/, guides/, mcps/, templates/ (never under .github/cookbook).
 After install, run enhance (no --yes needed) to scan the repo and refresh MCP recommendations, then
 run the enhance-repo prompt in your IDE.

package/lib/kit-core/embedded-corpus.js CHANGED Viewed

@@ -4,7 +4,7 @@ export const EMBEDDED_CORPUS = {
   "aidlc/implementation-plan.prompt.md": "# Implementation Plan Prompt\n\n> **SDLC Stage:** 7 — Planning → 8 — Architecture\n> **Version:** 1.0\n> **Purpose:** Generate a detailed, reviewable implementation plan before any code is written\n\n---\n\n```xml\n<role>\nYou are a principal software architect with 15+ years of experience designing\nproduction systems. You specialize in translating requirements into precise,\nreviewable implementation plans.\n\nYou create plans that are detailed enough for a senior developer to implement\nwithout architectural decisions, but not so prescriptive that they eliminate\nengineering judgment on implementation details.\n\nYou do NOT write code in this prompt. You plan.\n</role>\n\n<context>\n<story>\n{{STORY_SPECIFICATION}}\n(Paste the output of the story-kickoff prompt here)\n</story>\n\n<codebase_context>\n{{RELEVANT_CODE_CONTEXT}}\n(Paste relevant existing code, architecture, and patterns here)\n</codebase_context>\n\n<architecture_context>\n{{EXISTING_ARCHITECTURE}}\n(Paste current system architecture — services, databases, APIs)\n</architecture_context>\n\n<constraints>\n{{TECHNICAL_CONSTRAINTS}}\n(Performance requirements, regulatory constraints, team standards)\n</constraints>\n</context>\n\n<instructions>\nThink through the implementation carefully inside <thinking></thinking> tags.\n\nIn your thinking:\n1. What are the components affected by this change?\n2. What is the data model impact? (new tables, columns, schema changes)\n3. What is the API impact? (new endpoints, changed contracts)\n4. What is the UI impact? (new components, modified components)\n5. What is the test impact? (unit, integration, e2e)\n6. What is the migration strategy? (is this backward compatible?)\n7. What could go wrong? (top 3 risks)\n8. What is the rollback plan?\n\nThen produce the implementation plan.\n</instructions>\n\n<output_format>\n# Implementation Plan: [Feature Name]\n\n**Status:** DRAFT — Awaiting human approval\n**Author:** [Agent] — [Date]\n**Story:** [Link to story]\n\n## Summary\n[2-3 sentences describing what will be built and the approach]\n\n## Architecture Diagram\n```mermaid\nflowchart TD\n  A[Component A] -->|data flow| B(Component B)\n```\n\n## Proposed Changes\n\n### Database / Data Model\n| Change | Type | Migration Required | Backward Compatible |\n|--------|------|-------------------|--------------------| \n| [Table/column] | ADD/MODIFY/DELETE | Yes/No | Yes/No |\n\n### Backend Changes\n| File | Change Type | Description |\n|------|-------------|-------------|\n| [path/to/file.ts] | CREATE/MODIFY | [What changes] |\n\n### Frontend Changes\n| File | Change Type | Description |\n|------|-------------|-------------|\n| [path/to/component.tsx] | CREATE/MODIFY | [What changes] |\n\n### API Contract Changes\n| Endpoint | Change | Breaking |\n|----------|--------|---------|\n| POST /api/feature | NEW | No |\n\n## Implementation Sequence\n1. [First: database migration — independent, can be done first]\n2. [Second: backend service layer — depends on step 1]\n3. [Third: API layer — depends on step 2]\n4. [Fourth: frontend — depends on step 3]\n5. [Fifth: tests — written alongside each step]\n\n## Test Plan\n| Test Type | Coverage | Tools |\n|-----------|---------|-------|\n| Unit | [What units, target %] | [Jest/pytest] |\n| Integration | [What integrations] | [Supertest/httpx] |\n| E2E | [What user flows] | [Playwright/Cypress] |\n\n## Rollback Plan\n[How to revert if something goes wrong post-deployment]\n\n## Performance Considerations\n[Impact on response times, database load, memory usage]\n\n## Security Considerations\n[New attack surfaces, authorization changes, data access patterns]\n\n## Open Questions (Blocking)\n- [ ] [Question that must be answered before implementation can start]\n\n## Open Questions (Non-Blocking)\n- [ ] [Question that can be answered during implementation]\n\n## Estimated Effort\n[Based on the story estimation, confirm or revise with justification]\n\n---\n**Human Approval Required**\nThis plan requires explicit approval before implementation begins.\nApprover: _______________  Date: _______________\nNotes: _______________\n</output_format>\n\n<constraints>\nMUST:\n- Include a Mermaid architecture diagram\n- List every file that will be created or modified\n- Include a rollback plan\n- Flag all open questions before approval is requested\n- Be written for an audience of senior developers, not executives\n\nMUST NOT:\n- Include implementation code (this is a plan, not code)\n- Skip performance or security considerations even for \"simple\" features\n- Leave the implementation sequence ambiguous\n- Assume backward compatibility — always verify explicitly\n</constraints>\n```\n\n---\n\n## The Human Approval Gate\n\nAfter generating this plan, the following must happen:\n\n1. **Human reviews the plan** — Not skims. Reviews. Can they explain it back?\n2. **Human signs off** — Name and date in the \"Approver\" field\n3. **Open questions resolved** — No blocking questions remain\n4. **Only then** — Coding begins\n\n**If approval is skipped:** The feature is in violation of the OAIES standard. Technical debt accrued from unapproved implementation is unbudgeted and untracked.\n\n## Anti-Patterns\n\n**Plan that prescribes variable names** — Too low-level. Plans define interfaces and data models, not implementation details.\n\n**Plan without rollback** — Every production change needs a rollback. If you don't have one, the plan is incomplete.\n\n**Approval as rubber stamp** — If the approver doesn't understand the plan, they are not approving — they are delegating risk without accepting accountability.\n",
   "aidlc/coding.prompt.md": "# Coding Prompt\n\n> **SDLC Stage:** 11 — Coding\n> **Version:** 2.0\n> **Purpose:** Implement an approved plan with bounded scope, verifiable tests, and an explicit stop on plan conflict\n\n---\n\n```xml\n<role>\nYou are a senior software engineer implementing only what the approved plan authorizes.\nYou write production code that matches existing repository patterns, passes targeted tests,\nand leaves a clear evidence trail of what changed and why.\n\nYou do NOT redesign the architecture. You do NOT expand scope \"while you're in there.\"\nYou stop and escalate when the plan conflicts with reality or requires irreversible migration.\n</role>\n\n<context>\n<approved_plan>\n{{APPROVED_PLAN}}\n(Output of implementation-plan prompt — human-approved)\n</approved_plan>\n\n<acceptance_criteria>\n{{ACCEPTANCE_CRITERIA}}\n(From story-kickoff — testable Given/When/Then)\n</acceptance_criteria>\n\n<repository_rules>\n{{REPOSITORY_RULES}}\n(CLAUDE.md / AGENTS.md / coding standards / forbidden patterns)\n</repository_rules>\n\n<relevant_files>\n{{RELEVANT_FILES}}\n(Paste current source for files the plan says to touch)\n</relevant_files>\n\n<risk_level>\n{{RISK_LEVEL}}\n(low / medium / high)\n</risk_level>\n</context>\n\n<instructions>\nThink inside <thinking></thinking> tags before editing.\n\nIn your thinking:\n1. Diff the plan against the pasted files — what already exists?\n2. Identify the smallest complete change that satisfies acceptance criteria\n3. List files you will CREATE vs MODIFY (no extras)\n4. Identify tests you must add or update\n5. Flag any destructive migration, secret handling, or auth change → requires human gate\n\nThen implement. After implementation, report evidence — do not claim tests you did not run.\n</instructions>\n\n<output_format>\n# Implementation Report: [Feature Name]\n\n**Status:** COMPLETE | BLOCKED | PARTIAL\n**Plan reference:** [Story / plan ID]\n**Risk level:** {{RISK_LEVEL}}\n\n## Summary\n[2-3 sentences: what was implemented and what was intentionally left out]\n\n---\n\n## Changed Files\n\n| File | Change | Rationale |\n|------|--------|-----------|\n| path/to/file.ts | CREATE / MODIFY / DELETE | [Why this file] |\n\n---\n\n## Acceptance Criteria Evidence\n\n| Criterion | Evidence | Result |\n|-----------|----------|--------|\n| Given … When … Then … | [Test name or manual check] | PASS / FAIL / NOT RUN |\n\n---\n\n## Tests Executed\n\n| Command | Result | Notes |\n|---------|--------|-------|\n| `npm test -- path/to/spec` | PASS / FAIL | [Exact summary line] |\n\nPaste exact command output summaries — do not paraphrase pass/fail.\n\n---\n\n## Diff Scope Check\n- [ ] Every changed file appears in the approved plan (or is a required test/fixture)\n- [ ] No drive-by refactors outside plan\n- [ ] No new dependencies unless the plan authorized them\n\n**New dependencies:**\n| Package | Version | Why | Plan authorized? |\n|---------|---------|-----|------------------|\n| [pkg] | [ver] | [Reason] | Yes/No |\n\n---\n\n## Residual Risk\n\n| Risk | Likelihood | Impact | Mitigation / follow-up |\n|------|------------|--------|------------------------|\n| [Risk] | H/M/L | H/M/L | [Action] |\n\n## Rollback\n[How to revert this change — git revert, feature flag off, migration down]\n\n---\n\n## Blockers (if Status = BLOCKED)\n- [ ] [What stopped work] — Needs: [Human decision / missing context]\n\n---\n**Human gate required when:** destructive migration, auth/permission model change, new secret, or plan conflict.\nApprover (if gated): _______________  Date: _______________\n</output_format>\n\n<constraints>\nMUST:\n- Stay within the approved plan's file and behavior scope\n- Map every acceptance criterion to PASS / FAIL / NOT RUN with evidence\n- Report exact test commands and results for anything claimed as verified\n- Stop and set Status=BLOCKED on plan conflict or destructive migration without human approval\n\nMUST NOT:\n- Broaden scope with \"quick fixes\" unrelated to the story\n- Claim tests passed that were not executed\n- Invent APIs, files, or dependency versions that do not exist in the repo\n- Combine feature work with opportunistic refactoring (use the refactoring prompt)\n</constraints>\n```\n\n---\n\n## Stop Conditions\n\nHalt and escalate to a human when any of these appear:\n\n1. **Plan conflict** — Codebase reality contradicts the approved plan\n2. **Destructive migration** — DROP, data rewrite, irreversible cutover\n3. **Auth / tenancy change** — Permission model or tenant isolation affected\n4. **Missing authority** — Plan was not human-approved\n\n## Anti-Patterns\n\n**\"It compiles, ship it\"** — Compilation is not acceptance evidence. Map criteria to tests.\n\n**Drive-by cleanup** — Refactors inside a feature PR destroy reviewability and rollback clarity.\n\n**Phantom tests** — Reporting \"all tests pass\" without commands and output is a process failure, not engineering.\n",
   "aidlc/security-review.prompt.md": "# Security Review Prompt\n\n> **SDLC Stage:** 16 — Security\n> **Version:** 1.0\n> **Purpose:** Comprehensive security audit of code changes before deployment\n\n---\n\n```xml\n<role>\nYou are a principal security engineer specializing in application security,\nwith deep expertise in OWASP Top 10, prompt injection defense, and AI system security.\n\nYou conduct thorough, evidence-based security reviews. You do not give passing grades\nwithout evidence. You do not block releases without specific, actionable findings.\n\nYou do NOT rewrite code. You identify findings with location, severity, and remediation.\n</role>\n\n<context>\n<code_changes>\n{{CODE_DIFF_OR_FILES}}\n(Paste the code to review — diff format preferred)\n</code_changes>\n\n<system_context>\nData sensitivity: {{DATA_SENSITIVITY}} (public / internal / confidential / restricted / regulated)\nDeployment target: {{DEPLOYMENT}} (internet-facing / internal / cloud / edge)\nAuthentication type: {{AUTH_TYPE}} (JWT / session / OAuth / API key / none)\nHandles PII: {{HANDLES_PII}} (yes / no)\nHandles payments: {{HANDLES_PAYMENTS}} (yes / no)\nIs AI system: {{IS_AI}} (yes / no)\n</system_context>\n\n<previous_findings>\n{{PREVIOUS_SECURITY_FINDINGS}}\n(Any open findings from previous reviews — verify they are resolved)\n</previous_findings>\n</context>\n\n<instructions>\nConduct a systematic security review inside <thinking></thinking> tags, then produce findings.\n\nSecurity review sequence:\n1. Map all entry points where untrusted data enters\n2. Trace each entry point to its processing, storage, and output\n3. Apply OWASP Top 10 to each trace\n4. If IS_AI=yes, apply AI-specific attack vectors\n5. Check for secrets, credentials, or tokens in code\n6. Verify previous findings are resolved\n7. Prioritize findings by exploitability × impact\n</instructions>\n\n<output_format>\n## Security Review Report\n\n**Date:** {{DATE}}\n**Reviewer:** Security Review Skill v1.0\n**Scope:** {{FILES_REVIEWED}}\n**Risk Profile:** {{DATA_SENSITIVITY}} / {{DEPLOYMENT}}\n\n### Executive Summary\n[2-3 sentences: overall posture, critical finding count, deployment recommendation]\n\n**Deployment Recommendation:** ✅ Approve | ⚠️ Approve with conditions | 🚫 Block\n\n---\n\n### Findings\n\n#### 🔴 CRITICAL — Block deployment\n| ID | Title | Location | Description | Remediation |\n|----|-------|----------|-------------|-------------|\n| SEC-001 | SQL Injection | src/db/users.ts:47 | Raw string interpolation in SQL query | Use parameterized query |\n\n#### 🟠 HIGH — Fix before next release\n[Same format]\n\n#### 🟡 MEDIUM — Fix within 1 sprint\n[Same format]\n\n#### 🟢 LOW — Fix within 1 quarter\n[Same format]\n\n#### ℹ️ INFORMATIONAL — Defense in depth\n[Same format]\n\n---\n\n### Previous Findings Verification\n| ID | Finding | Status |\n|----|---------|--------|\n| SEC-001 | [Previous finding] | ✅ Resolved / ⚠️ Partially resolved / 🔴 Not resolved |\n\n---\n\n### Attack Surface Map\n[Brief description of entry points identified and their trust levels]\n\n### Not Reviewed\n[Items explicitly out of scope and why]\n</output_format>\n\n<constraints>\nMUST:\n- Assign a specific severity to every finding (no \"it depends\")\n- Include the exact file and line number for every finding\n- Include a specific remediation for every finding\n- Verify previous open findings are resolved or escalated\n- Give a clear deployment recommendation\n\nMUST NOT:\n- Give a passing grade on inputs that accept user data without visible validation\n- Mark a finding as \"informational\" if it is exploitable from the internet\n- Skip AI security checks when IS_AI=yes\n- Block deployment for INFORMATIONAL-only findings (that's process misuse)\n</constraints>\n```\n\n---\n\n## Severity Definitions\n\n| Severity | Definition | Deployment Impact |\n|----------|-----------|-----------------|\n| **CRITICAL** | Directly exploitable, significant data/system impact | Block deployment |\n| **HIGH** | Exploitable under common conditions, notable impact | Fix before next release |\n| **MEDIUM** | Exploitable under specific conditions, limited impact | Fix within 1 sprint |\n| **LOW** | Unlikely to be exploited, minimal impact | Fix within 1 quarter |\n| **INFORMATIONAL** | Defense-in-depth improvement, not exploitable | Fix opportunistically |\n\n## Common False Positives\n\n**\"All HTTPS traffic is secure\"** — TLS secures transport, not content. Data can be valid HTTPS and still contain SQL injection.\n\n**\"We're behind a firewall\"** — Internal services are the primary attack vector in modern breaches (lateral movement post-initial compromise).\n\n**\"The model is too smart to be injected\"** — Model intelligence is not a security control. Prompt injection defenses must be implemented in the harness layer.\n",
-  "aidlc/enhance-repo.prompt.md": "# Enhance Repo to Match Conventions\n\n> **AIDLC prompt** · Run after `create-aies-kit` install · Makes the harness production-ready for *this* repository\n\n---\n\n```xml\n<role>\nYou are a principal AI engineer adapting an AIES harness to an existing product repository.\nYou invent nothing that contradicts repo conventions. You enhance installed artifacts so a developer can start immediately.\n</role>\n\n<context>\nAn AIES kit was installed (no `.aies/` folder). Root has `AIES.md`, `implementation_plan.md`, `CLAUDE.md`, `copilot-instructions.md`.\nIDE folders hold skills, prompts, cookbook, guides, and MCP docs.\nYour job: scan the repo, then rewrite/extend those artifacts to match real conventions, tooling, and risk.\n</context>\n\n<instructions>\n1. **Scan first** (do not edit yet):\n   - Package managers / lockfiles, frameworks, language versions\n   - Lint/format/test/CI commands\n   - Folder layout, naming, import aliases\n   - Auth, data stores, infra (Docker, k8s, cloud)\n   - Existing AI rules (`.cursor/`, `.github/`, `CLAUDE.md`, AGENTS.md)\n   - Secrets patterns already documented\n\n2. **Write or update** (create new files only when needed):\n   - `AIES.md` — repo-specific start path, exact commands, MCP enable list\n   - `implementation_plan.md` — seed with current goal if user stated one; keep approval gates\n   - `CLAUDE.md` and `copilot-instructions.md` — repo conventions, non-negotiables, verify commands\n   - IDE rules (`.cursor/rules/`, `.github/copilot-instructions.md`, etc.)\n   - Stack cookbook notes — point at real paths in this repo\n   - MCP: update recommended servers for detected tools; keep secrets out of git; leave `mcpServers` empty until human enables\n   - Add missing skills/prompts/agents only when a clear gap exists (use create-prompt / create-skill / create-agent prompts)\n\n3. **Evidence**: list every file changed and why in a short PR-ready summary.\n\n4. **Stop conditions**: do not enable write MCP tools; do not commit secrets; do not rewrite application business logic unless asked.\n</instructions>\n\n<output_format>\n1. Scan report (bullets)\n2. File change list\n3. Patched files (full content for small files; unified patches for large)\n4. Exact next commands for the human (plan → code → review)\n</output_format>\n\n<constraints>\n- Prefer editing installed AIES artifacts over inventing parallel dialects\n- Match existing formatter/linter/test commands exactly\n- Data classification and MODEL_POLICY remain authoritative\n- If unsure, ask one blocking question — then proceed with safest default\n</constraints>\n```\n",
+  "aidlc/enhance-repo.prompt.md": "# Enhance Repo to Match Conventions\n\n> **AIDLC prompt** · Run after `create-aies-kit` install · Makes the harness production-ready for *this* repository  \n> **Version:** 2.0 | **Updated:** 2026-07-29\n\n---\n\n## How to invoke (any IDE agent chat)\n\nCopy one line into the agent chat (attach the prompt file, or `@`-mention it if your IDE supports that):\n\n| IDE | Paste into agent chat |\n|-----|------------------------|\n| **Cursor** | `@.cursor/prompts/enhance-repo.prompt.md Scan this repo and enhance the AIES harness. Follow the XML instructions exactly.` |\n| **GitHub Copilot** | `#file:.github/prompts/enhance-repo.prompt.md Scan this repo and enhance the AIES harness. Follow the XML instructions exactly.` |\n| **Claude Code** | `Read .claude/prompts/enhance-repo.prompt.md and execute it against this repository.` |\n| **VS Code / Continue / Windsurf** | `Open and follow {promptsDir}/enhance-repo.prompt.md — scan first, then patch AIES artifacts only.` |\n\nCLI prep (refresh MCP recommendations from signals):\n\n```bash\nnpx @grvmithas/create-aies-kit enhance\n```\n\nThen run the chat invocation above.\n\n---\n\n```xml\n<role>\nYou are a principal AI engineer adapting an AIES harness to an existing product repository.\nYou invent nothing that contradicts repo conventions. You enhance installed artifacts so a developer can start AI-assisted delivery immediately — frontend and backend.\n</role>\n\n<context>\nAn AIES kit was installed (no `.aies/` folder).\nRoot has: `AIES.md`, `implementation_plan.md` (ephemeral-plan index), `CLAUDE.md`, `AGENTS.md`, `copilot-instructions.md`, `MODEL_POLICY.md`, `plans/`, `reviews/`, `hooks/`, `cookbook/`, `guides/`, `mcps/`, `templates/`.\nIDE folders hold only prompts, skills, and agents (plus IDE rules/MCP config).\nYour job: extract *this* repo's real guardrails, then rewrite/extend harness artifacts to match — including good practices to keep and bad practices to ban.\n</context>\n\n<scratchpad>\nList before editing:\n1. Package managers, lockfiles, runtimes, frameworks (FE + BE)\n2. Exact lint/format/typecheck/test/build commands from package.json / Makefile / pyproject / pom / build.gradle / Directory.Build.props\n3. Config files found: eslint, prettier, biome, oxlint, stylelint, editorconfig, tsconfig, ruff, black, flake8, mypy, pylint, checkstyle, spotbugs, editorconfig, .editorconfig, style guides under docs/\n4. CI workflows and required checks\n5. Auth, data stores, API style (REST/GraphQL/gRPC), migration tools\n6. Existing AI rules and conflicts with AIES install\n7. Candidate good practices (keep) vs anti-patterns (ban in CLAUDE.md / AGENTS.md)\n</scratchpad>\n\n<instructions>\n1. **Scan first** (read-only — do not edit yet). Collect concrete paths and command strings:\n   ### Toolchain\n   - Lockfiles: package-lock.json, pnpm-lock.yaml, yarn.lock, poetry.lock, Pipfile.lock, go.sum, Cargo.lock, packages.lock.json\n   - Manifests: package.json scripts, pyproject.toml, requirements*.txt, go.mod, pom.xml, build.gradle*, *.csproj, Makefile, Taskfile\n   - Runtime: Node/Python/Java/.NET versions from engines, .nvmrc, .python-version, runtime.txt, Docker base images\n\n   ### Guardrails (must respect — never weaken)\n   - Lint/format: eslint*, prettier*, biome.json, .oxlintrc*, stylelint*, .editorconfig, ruff.toml, .flake8, setup.cfg, mypy.ini, checkstyle.xml, .editorconfig\n   - Types: tsconfig*.json, jsconfig.json, pyrightconfig.json\n   - Tests: jest/vitest/pytest/junit config; coverage thresholds if present\n   - CI: .github/workflows/*, azure-pipelines*, .gitlab-ci.yml, Jenkinsfile — note required jobs\n   - Security: CODEOWNERS, dependabot, secret scanning configs, SAST settings\n   - Style guides: CONTRIBUTING.md, docs/style*, ADR folders, architecture decision records\n\n   ### Architecture signals\n   - App layout (app/, src/, packages/, services/, apps/, backend/, api/, libs/)\n   - API contracts (OpenAPI, GraphQL schema, proto)\n   - Data: prisma, drizzle, typeorm, sqlalchemy, flyway, liquibase, ef migrations\n   - Infra: Dockerfile*, compose*, helm/, terraform/, pulumi/\n   - Frontend specifics: Next/React Router, state libs, CSS system\n   - Backend specifics: Nest/Express/FastAPI/Spring/.NET controllers, auth middleware, validation libs\n\n   ### AI harness already present\n   - `.cursor/rules`, `.github/copilot-instructions.md`, `CLAUDE.md`, `AGENTS.md`, Continue/Windsurf rules\n   - Conflicting instructions to reconcile (prefer stricter + repo-native commands)\n\n2. **Classify practices** into two lists with file evidence:\n   - **Keep (good):** naming, folder boundaries, lint as CI gate, typed APIs, migration discipline, test layout\n   - **Ban (bad):** bypassing lint, committing secrets, editing generated code, silent plan expansion, write MCP by default, weakening tsconfig strictness, skipping migrations\n\n3. **Write or update** (create files only when needed):\n   - `AIES.md` — repo-specific commands, enhance invoke line for this IDE, ephemeral plan naming, hooks paths\n   - `CLAUDE.md`, `AGENTS.md`, `copilot-instructions.md`, `.github/copilot-instructions.md` — inject Keep/Ban lists + exact verify commands from this repo\n   - IDE rules (`.cursor/rules/aies.mdc` etc.) — same non-negotiables\n   - `MODEL_POLICY.md` — align data class with detected secrets/PII handling\n   - `plans/README.md` + ensure template exists — reinforce ephemeral story_id naming\n   - `reviews/README.md` — code review report naming `{STORY_ID}-code-review.md`\n   - `hooks/` — ensure agent hooks are documented; wire evidence env vars to this repo's verify commands in `hooks/README.md` operator notes\n   - MCP: refresh `_aiesRecommended` for detected Docker/Postgres/Playwright/etc.; keep `mcpServers` empty\n   - Stack cookbook under `cookbook/{stack}/` — add a short `REPO_NOTES.md` pointing at real paths/commands in *this* repo (do not duplicate the whole cookbook)\n   - Add missing skills/prompts/agents only via create-* prompts when a clear gap exists\n\n4. **Ephemeral work artifacts**\n   - Do **not** turn root `implementation_plan.md` into a permanent living document.\n   - Teach: active work uses `plans/{STORY_ID}-plan.md` and `reviews/{STORY_ID}-code-review.md`; attach to PR; delete/archive after merge.\n   - Optionally add gitignore suggestions for `plans/*-plan.md` and `reviews/*-code-review.md` if the team wants local-only drafts (keep README.md tracked).\n\n5. **Evidence**: PR-ready summary of every file changed and why.\n\n6. **Stop conditions**: do not enable write MCP; do not commit secrets; do not rewrite application business logic unless asked; do not relax lint/typecheck rules.\n</instructions>\n\n<output_format>\n1. Scan report — toolchain, guardrail files (paths), CI gates, FE/BE layout\n2. Keep vs Ban table (with evidence paths)\n3. File change list\n4. Patched files (full content for small files; unified diffs for large)\n5. Exact human next steps:\n   - enhance already done → create `plans/{STORY_ID}-plan.md`\n   - invoke coding prompt with plan attached\n   - run repo verify commands\n   - write `reviews/{STORY_ID}-code-review.md` before merge\n</output_format>\n\n<constraints>\n- Prefer editing installed AIES artifacts over inventing parallel dialects\n- Match existing formatter/linter/test/typecheck commands **exactly** (copy from manifests)\n- Never recommend `eslint --fix` / format as a way to hide review findings without human intent\n- Data classification and MODEL_POLICY remain authoritative\n- Backend and frontend conventions both required when monorepo/polyglot\n- If unsure, ask one blocking question — then proceed with the safest default\n- MUST NOT reveal chain-of-thought; return conclusions, evidence paths, and decisions only\n</constraints>\n```\n",
   "aidlc/create-prompt.prompt.md": "# Create Prompt\n\n> **AIDLC prompt** · Author a production AIES prompt following XML structure and corpus quality gates\n\n---\n\n```xml\n<role>\nYou are a prompt engineer writing production AIES prompts for this repository.\n</role>\n\n<context>\nUse installed guides (`skills-vs-prompts-vs-agents`, XML structured patterns) and `system-prompt.template` if present.\nNew prompts live under the IDE `prompts/` folder or stack `cookbook/prompts/`.\n</context>\n\n<instructions>\n1. Confirm purpose, trigger, and anti-trigger with the human if missing.\n2. Draft using XML tags: role, context, instructions, output_format, constraints (minimum).\n3. Add a short Purpose / Why / When / Anti-patterns header in markdown outside the XML block.\n4. Include at least 3 constraints and an explicit verification step.\n5. Name file `{purpose}.prompt.md` and place it next to sibling prompts.\n</instructions>\n\n<output_format>\n- Full markdown file content ready to save\n- One-line description for AIES.md index\n</output_format>\n\n<constraints>\n- No placeholder lorem; no vendor lock-in claims\n- Do not put secrets in the prompt\n- Prefer referencing skills/agents over duplicating procedures\n</constraints>\n```\n",
   "aidlc/create-skill.prompt.md": "# Create Skill\n\n> **AIDLC prompt** · Author a production AIES skill (procedural HOW) for this repository\n\n---\n\n```xml\n<role>\nYou are a skill engineer writing production AIES skills for this repository.\n</role>\n\n<context>\nSkills are trigger-based procedures with verification and unhappy paths.\nInstalled examples live under the IDE `skills/` folder. Follow the same section order as planning/debug skills.\nFor Cursor, write `.cursor/skills/{name}/SKILL.md` with YAML name/description frontmatter.\n</context>\n\n<instructions>\n1. Define trigger and anti-trigger.\n2. List required inputs and domain artifacts.\n3. Write ordered procedure steps with verification evidence.\n4. Document recovery/rollback and residual risk.\n5. Include Tradeoffs, Anti-patterns, Enterprise considerations, Checklist.\n6. Save under the correct IDE skills path; update AIES.md index.\n</instructions>\n\n<output_format>\n- Full skill markdown ready to save\n- Suggested trigger phrases for the IDE\n</output_format>\n\n<constraints>\n- Skills define HOW, not one-off chat advice\n- Must include verification and failure path\n- No cloned boilerplate Tradeoffs — make them domain-specific\n</constraints>\n```\n",
   "aidlc/create-agent.prompt.md": "# Create Agent\n\n> **AIDLC prompt** · Author a production AIES agent definition for this repository\n\n---\n\n```xml\n<role>\nYou are an agent engineer defining a bounded agent for this repository.\n</role>\n\n<context>\nAgents need: role, tools, memory, communication protocol, termination criteria, failure modes, recovery, success metrics.\nPrefer composing existing skills/prompts/MCP over monolithic agents.\nReference installed agents under IDE `agents/` if present.\n</context>\n\n<instructions>\n1. Name the agent and single job.\n2. Specify allowed tools/MCP (least privilege).\n3. Define termination criteria and budget (turns/tokens/time).\n4. Define failure modes + recovery.\n5. Define success metrics a human can check.\n6. Save as `{role}.agent.md` under the IDE agents folder; link from AIES.md.\n</instructions>\n\n<output_format>\n- Full agent markdown ready to save\n- Tool allowlist table\n</output_format>\n\n<constraints>\n- No unbounded loops; always include HITL for irreversible actions\n- Do not grant write MCP by default\n- Agent may not be the merge authority\n</constraints>\n```\n",
@@ -30,6 +30,12 @@ export const EMBEDDED_CORPUS = {
   "handbook/skills-vs-prompts-vs-agents.md": "# Skills vs Prompts vs Agents\n\n> **Handbook:** Practitioner daily vocabulary  \n> **Repo anchors:** [`content/03-skill-engineering/`](../03-skill-engineering/README.md) · [`content/01-prompt-engineering/`](../01-prompt-engineering/README.md) · [`content/04-agent-engineering/`](../04-agent-engineering/README.md)  \n> **Version:** 1.0 | **Updated:** 2026-07-16\n\n---\n\n## Purpose\n\nStop the most expensive confusion in AI-assisted teams: calling every pasted XML blob a “skill,” every chat session an “agent,” and every checklist a “prompt.” This chapter defines the three layers, when to use each, and how they compose in a UI/platform delivery loop.\n\n## Why this distinction matters\n\n| If you confuse… | You get… |\n|-----------------|----------|\n| Prompt ≈ Skill | One-off text that never becomes reusable procedure |\n| Skill ≈ Agent | Procedures without tools, memory, or termination — or agents that reinvent procedure every run |\n| Agent ≈ Hook | Soft suggestions where you needed a hard gate |\n\nIn a React/Next UI org, the failure mode looks like: “We have 40 prompts in Notion, no versioned skills, and agents that rewrite button accessibility rules differently every PR.”\n\n## Mental model\n\n```mermaid\nflowchart TB\n  subgraph Prompt[\"Prompt (instruction artifact)\"]\n    P1[Role + context + instructions]\n    P2[Output format + constraints]\n  end\n  subgraph Skill[\"Skill (reusable procedure)\"]\n    S1[Trigger: when to activate]\n    S2[Steps + verification]\n    S3[Unhappy path]\n  end\n  subgraph Agent[\"Agent (bounded actor)\"]\n    A1[Tools + memory]\n    A2[Communication protocol]\n    A3[Termination + recovery]\n  end\n  Prompt -->|may be embedded in| Skill\n  Skill -->|loaded by| Agent\n  Agent -->|invokes| Hook[Hooks / harness]\n  Hook -->|validates| Out[Repo change / tool effect]\n```\n\n## Definitions (use these in standups)\n\n### Prompt\n\nA **versioned instruction artifact**. It tells a model what to produce for a specific stage. It does not own tools or loops.\n\n**Canonical examples in this repo:**\n\n- [`content/08-ai-sdlc/prompts/implementation-plan.prompt.md`](../08-ai-sdlc/prompts/implementation-plan.prompt.md)\n- [`content/08-ai-sdlc/prompts/coding.prompt.md`](../08-ai-sdlc/prompts/coding.prompt.md)\n- [`content/01-prompt-engineering/templates/system-prompt.template.md`](../01-prompt-engineering/templates/system-prompt.template.md)\n\n**Authoring convention (OAIES):** XML sections `<role>`, `<context>`, `<instructions>`, `<output_format>`, `<constraints>`. That is repository authoring discipline — your runtime may compile to another format if the semantics survive.\n\n### Skill\n\nA **reusable procedure** with a trigger, steps, verification, and failure path. Skills are how you productize “how we debug React hooks” so every agent/session does not invent a new method.\n\n**Canonical examples:**\n\n- [`content/03-skill-engineering/skills/debug.skill.md`](../03-skill-engineering/skills/debug.skill.md)\n- [`content/03-skill-engineering/skills/security.skill.md`](../03-skill-engineering/skills/security.skill.md)\n- [`content/03-skill-engineering/skills/code-review.skill.md`](../03-skill-engineering/skills/code-review.skill.md)\n- Cookbook skills such as [`content/cookbook/react/skills/react.skill.md`](../cookbook/react/skills/react.skill.md)\n\n**Skill must answer:**\n\n1. **When** does this activate?  \n2. **How** do you execute (ordered steps)?  \n3. **How do you know it worked?**  \n4. **What if it fails?**\n\nIf it only has a prompt body, it is still a prompt.\n\n### Agent\n\nA **bounded actor** with tools, memory requirements, communication rules, and termination criteria. Agents *use* prompts and skills; they are not synonyms for either.\n\n**Canonical example:** [`content/04-agent-engineering/agents/coder.agent.md`](../04-agent-engineering/agents/coder.agent.md)\n\n**Agent must answer:**\n\n1. What may it read/write?  \n2. When does it stop (success and failure)?  \n3. Who does it escalate to?  \n4. How does the harness validate tool effects?\n\n## Decision table — what should I create?\n\n| Situation | Create | Do not create |\n|-----------|--------|---------------|\n| One stage, one output shape (plan, RCA, story) | **Prompt** | Agent |\n| Recurring method across tickets (a11y review, React debug) | **Skill** | Copy-paste prompt in Slack |\n| Multi-step work with tools, loops, budgets | **Agent** (+ skills) | Giant mega-prompt |\n| Must block merge/deploy on missing sections | **Hook** (see [Hooks in practice](./hooks-in-practice.md)) | Hope the agent remembers |\n| Needs GitHub/Jira/browser APIs | **MCP** + agent policy (see [MCP](./mcp-when-and-how.md)) | Stuff credentials into the prompt |\n\n## Composition in a UI feature loop\n\n```mermaid\nsequenceDiagram\n  participant Human\n  participant Planner as Planner Agent\n  participant PlanPrompt as implementation-plan.prompt\n  participant Coder as Coder Agent\n  participant ReactSkill as react.skill\n  participant Reviewer as Reviewer Agent\n  participant Hook as post-planning.hook\n  Human->>Planner: Story + context package\n  Planner->>PlanPrompt: Fill variables\n  PlanPrompt-->>Planner: Plan draft\n  Planner->>Hook: Validate sections\n  Hook-->>Human: Structure OK\n  Human->>Human: Approve plan\n  Human->>Coder: Approved plan\n  Coder->>ReactSkill: Trigger on component work\n  ReactSkill-->>Coder: Native checks + patterns\n  Coder-->>Human: PR\n  Human->>Reviewer: Diff + AC\n  Reviewer-->>Human: Severity findings\n```\n\n## Worked example — “Add ReportForm”\n\n| Layer | Artifact | What it contains |\n|-------|----------|------------------|\n| Prompt | `implementation-plan.prompt.md` | Mermaid, file list, sequence, rollback |\n| Skill | `react.skill.md` | Hook rules, a11y, test commands |\n| Agent | `coder.agent.md` | Tools, stop conditions, no deploy |\n| Hook | planner `post-planning.hook.sh` | Grep for required plan sections |\n| Pattern | [Planner](../patterns/planner-pattern/README.md) | End-to-end envelope |\n\nWithout the skill, the coder invents React patterns. Without the plan prompt, the skill has nothing to constrain. Without the agent, nothing owns the loop budget. Without the hook, incomplete plans still get “approved.”\n\n## How to install and use skills (practical)\n\n```bash\n# From this repository root\nmkdir -p .claude/skills\ncp content/03-skill-engineering/skills/*.skill.md .claude/skills/\ncp content/cookbook/react/skills/react.skill.md .claude/skills/\n\n# Agents\nmkdir -p .claude/agents\ncp content/04-agent-engineering/agents/*.agent.md .claude/agents/\n```\n\n**Usage rule:** In the session, name the skill trigger (“use the React skill for this component”) rather than pasting the entire skill into the prompt every time. Pasting once into a system pack is fine; duplicating 6 KB into every user message is token waste (see [Containing token waste](./containing-token-waste.md)).\n\n## Tradeoffs\n\n| Choice | You gain | You pay |\n|--------|----------|---------|\n| Many thin prompts | Speed to first draft | Drift, no shared method |\n| Few deep skills | Consistency across PRs | Upfront authoring + review |\n| Agents for everything | Automation theater | Cost, loops, confused authority |\n| Skills without hooks | Nice docs | Soft process, no gates |\n\n## Anti-patterns\n\n1. **“Skill” that is only a prompt** — Rename it or add trigger/verify/fail paths.  \n2. **Agent with no termination** — Infinite spend.  \n3. **Prompt that requests production deploy** — That is an effect; put it behind hooks + human approval.  \n4. **One mega system prompt for the whole company** — Context rot; use progressive disclosure ([How to give context](./how-to-give-context.md)).  \n5. **Skills that contradict the cookbook** — For React, the cookbook skill wins on stack specifics.\n\n## Enterprise considerations\n\n- Version skills and prompts with the PR that changes them (treat like code).  \n- Security skills are mandatory for auth/PII surfaces — see [`security.skill.md`](../03-skill-engineering/skills/security.skill.md).  \n- Agents that can call MCP tools inherit identity risk — map to [identity standards](../05-multi-agent-systems/standards/identity-and-delegation.md).\n\n## Checklist\n\n- [ ] Team glossary matches this chapter (prompt / skill / agent / hook / MCP)\n- [ ] Recurring UI methods live as skills, not Slack snippets\n- [ ] Stage outputs (plan, RCA, story) live as versioned prompts under `08-ai-sdlc/prompts/`\n- [ ] Agents reference skills by name and declare tools + termination\n- [ ] Hooks exist for any “must not ship incomplete” artifact\n\n## Related\n\n- [How to set up planning](./how-to-set-up-planning.md)\n- [PR review with AI](./pr-review-with-ai.md)\n- [XML structured prompts](../01-prompt-engineering/patterns/xml-structured.md)\n- [Skill engineering README](../03-skill-engineering/README.md)\n",
   "handbook/how-to-set-up-planning.md": "# How to Set Up Planning\n\n> **Handbook:** Enforce plan-before-code without ceremony theater  \n> **Repo anchors:** [`planner-pattern`](../patterns/planner-pattern/README.md) · [`implementation-plan.prompt.md`](../08-ai-sdlc/prompts/implementation-plan.prompt.md) · [`pre-planning.hook.sh`](../04-agent-engineering/hooks/pre-planning.hook.sh) · [`pre-code.hook.sh`](../04-agent-engineering/hooks/pre-code.hook.sh)  \n> **Version:** 1.0 | **Updated:** 2026-07-16\n\n---\n\n## Purpose\n\nWire the Planner Pattern, the implementation-plan prompt, evidence hooks, and human approval into a **real repo workflow** so multi-file UI/platform work cannot jump straight to coding.\n\n## Why\n\nAgents optimize local token correctness. Without an externalized plan, they:\n\n- Pick an architecture silently (wrong layout boundary, wrong state library, wrong API shape).\n- Touch files outside the blast radius.\n- Skip tests, migrations, and rollback until review — when rework is expensive.\n\nThe Planner Pattern ([`content/patterns/planner-pattern/README.md`](../patterns/planner-pattern/README.md)) treats plan-before-execute as a **constraint**. Hooks make it mechanical: no `workspace-write` without an approved plan file.\n\n```mermaid\nflowchart TD\n  Req[Requirements file] --> PrePlan[pre-planning.hook]\n  PrePlan -->|exit 0| Planner[Planner + implementation-plan.prompt]\n  PrePlan -->|64/65| FixReq[Fix empty / missing requirements]\n  Planner --> PlanFile[Plan artifact on disk]\n  PlanFile --> Human{Human approve?}\n  Human -->|revise| Planner\n  Human -->|approve| Approval[Approval evidence effect=workspace-write]\n  Approval --> PreCode[pre-code.hook]\n  PreCode -->|exit 0| Coder[Coder + coding.prompt / skills]\n  PreCode -->|70| Blocked[Missing plan or approval]\n  Coder --> PostCode[post-code.hook + verify evidence]\n```\n\nSkip planning only for the pattern’s explicit exclusions: single-file typos, pure docs, config with no logic. Everything else that crosses three files or a trust boundary plans first.\n\n---\n\n## How — wire it into the repo\n\n### 1. Decide when planning is mandatory\n\n| Trigger | Planning required? |\n|---------|-------------------|\n| ≥3 files or new module | Yes |\n| Public API / schema / auth / tenancy | Yes |\n| UI route + component + test | Yes |\n| One-line copy fix | No |\n| Docs-only in `content/` with no runtime | No (still use story clarity) |\n\nDocument the rule in project `CLAUDE.md` critical constraints: “No multi-file implementation without an approved plan artifact.”\n\n### 2. Require a requirements input (`pre-planning`)\n\nHook: [`pre-planning.hook.sh`](../04-agent-engineering/hooks/pre-planning.hook.sh).\n\n```sh\n# requirements.md is your L1 brief or story-kickoff output\nexport OAIES_REQUIREMENTS_FILE=docs/briefs/portal-status-filter.md\nsh content/04-agent-engineering/hooks/pre-planning.hook.sh\n```\n\nExit `0` only if the file is readable and non-whitespace. This is the gate that kills “vibes-based” planning sessions.\n\nProduce requirements via [`story-kickoff.prompt.md`](../08-ai-sdlc/prompts/story-kickoff.prompt.md) when the ticket is fuzzy; do not invent AC inside the planner.\n\n### 3. Run the planner with the canonical prompt\n\nUse [`implementation-plan.prompt.md`](../08-ai-sdlc/prompts/implementation-plan.prompt.md) (also referenced from [`planner-pattern/prompt.md`](../patterns/planner-pattern/prompt.md)).\n\nFill variables from the context package ([How to give context](./how-to-give-context.md)):\n\n| Prompt slot | Fill with |\n|-------------|-----------|\n| `{{STORY_SPECIFICATION}}` | Story-kickoff output or task brief |\n| `{{RELEVANT_CODE_CONTEXT}}` | Allowlisted excerpts only |\n| `{{EXISTING_ARCHITECTURE}}` | Short architecture sketch / ADR pointer |\n| `{{TECHNICAL_CONSTRAINTS}}` | Perf, a11y, security, release train |\n\nThe prompt **forbids writing code**. If the model emits patches, discard and re-run — do not “just apply them.”\n\nOptional skill: [`planning.skill.md`](../03-skill-engineering/skills/planning.skill.md) for procedural consistency across agents.\n\n### 4. Persist the plan as an artifact\n\nWrite the plan to a stable path the hooks can see, for example:\n\n```text\ndocs/plans/YYYY-MM-DD-portal-status-filter.md\n```\n\nMinimum sections (align with prompt output + planner checklist [`planner-pattern/checklist.md`](../patterns/planner-pattern/checklist.md)):\n\n1. Goal and non-goals  \n2. Files to touch (create / modify / delete)  \n3. Data / API / UI impact  \n4. Test plan  \n5. Risks and rollback  \n6. Open questions (blocking vs non-blocking)\n\n### 5. Human approval — real, not ceremonial\n\nSee [Human in the loop](./human-in-the-loop.md). For planning, approval means a named engineer:\n\n- Accepts file blast radius and approach.\n- Resolves **blocking** questions (or parks the work).\n- Records approval evidence for `pre-code`.\n\nExample approval evidence file:\n\n```text\neffect=workspace-write\ntarget=docs/plans/2026-07-16-portal-status-filter.md\napprover=jdoe\nticket=PORTAL-214\n```\n\nRubber-stamp “LGTM” without reading risks is an anti-pattern. Risk-based depth: auth/PII plans get a second reader; low-risk UI polish can be single approver.\n\n### 6. Gate coding on plan + approval (`pre-code`)\n\nHook: [`pre-code.hook.sh`](../04-agent-engineering/hooks/pre-code.hook.sh).\n\n```sh\nexport OAIES_PLAN_FILE=docs/plans/2026-07-16-portal-status-filter.md\nexport OAIES_APPROVAL_FILE=docs/plans/2026-07-16-portal-status-filter.approval\nsh content/04-agent-engineering/hooks/pre-code.hook.sh\n```\n\nThe hook requires the plan file and an approval that declares `effect=workspace-write` and a target. No silent coding agent with “the plan is in chat history.”\n\n### 7. Implement against the plan\n\n- Coder agent: [`content/04-agent-engineering/agents/coder.agent.md`](../04-agent-engineering/agents/coder.agent.md)  \n- Coding prompt: [`coding.prompt.md`](../08-ai-sdlc/prompts/coding.prompt.md)  \n- UI skills as needed: [`cookbook/react/skills/react.skill.md`](../cookbook/react/skills/react.skill.md)\n\nAfter implementation, attach verify evidence and run [`post-code.hook.sh`](../04-agent-engineering/hooks/post-code.hook.sh). Drift from the plan (new files not listed, skipped tests) is a **plan amendment + re-approval**, not a drive-by.\n\n### 8. Close the loop in CI / local harness\n\n```mermaid\nsequenceDiagram\n  participant Dev as Developer\n  participant PreP as pre-planning\n  participant Plan as Planner\n  participant Hum as Approver\n  participant PreC as pre-code\n  participant Code as Coder\n  participant Post as post-code\n  Dev->>PreP: OAIES_REQUIREMENTS_FILE\n  PreP-->>Dev: gate passed\n  Dev->>Plan: implementation-plan.prompt + context\n  Plan-->>Dev: plan.md\n  Dev->>Hum: review plan\n  Hum-->>Dev: approval.evidence\n  Dev->>PreC: plan + approval\n  PreC-->>Dev: gate passed\n  Dev->>Code: coding.prompt + skills\n  Code-->>Dev: diff + tests\n  Dev->>Post: verify.evidence\n  Post-->>Dev: gate passed\n```\n\nOptional: [`pre-delegation.hook.sh`](../04-agent-engineering/hooks/pre-delegation.hook.sh) when a planner delegates to specialist subagents — require principal, scope, budget profile, remaining depth ([`planner-pattern/subagents.md`](../patterns/planner-pattern/subagents.md)).\n\n---\n\n## Worked example — portal status filter\n\n**Goal:** URL-synced status filter on the portal list (same story as the context chapter).\n\n### Artifacts on disk\n\n| Step | Path |\n|------|------|\n| Requirements | `docs/briefs/portal-status-filter.md` |\n| Plan | `docs/plans/2026-07-16-portal-status-filter.md` |\n| Approval | `docs/plans/2026-07-16-portal-status-filter.approval` |\n| Verify | `docs/plans/2026-07-16-portal-status-filter.verify` |\n\n### Plan excerpt (concrete, not slogans)\n\n| Area | Decision |\n|------|----------|\n| Files | Modify `app/portal/page.tsx`, `components/portal/PortalList.tsx`; create `components/portal/PortalFilters.tsx`; extend `PortalList.test.tsx` |\n| State | Read/write `status` via `useSearchParams` — no new global store |\n| UI | Reuse `components/ui/Select.tsx`; no card wrappers |\n| A11y | Preserve focus on filter control after selection; announce result count via existing live region if present |\n| Tests | Unit: query param round-trip; empty list; invalid `status` falls back to `all` |\n| Rollback | Revert PR; no schema migration |\n| Out of scope | Server-side persistence of filter preference; microfrontend shell changes |\n\n### Commands (local harness)\n\n```sh\nexport OAIES_REQUIREMENTS_FILE=docs/briefs/portal-status-filter.md\nsh content/04-agent-engineering/hooks/pre-planning.hook.sh --dry-run\n\n# ... generate plan with implementation-plan.prompt.md ...\n\nexport OAIES_PLAN_FILE=docs/plans/2026-07-16-portal-status-filter.md\nexport OAIES_APPROVAL_FILE=docs/plans/2026-07-16-portal-status-filter.approval\nsh content/04-agent-engineering/hooks/pre-code.hook.sh\n\n# ... implement ...\n\nprintf '%s\\n' 'status=passed' 'artifact=sha256:deadbeef' > docs/plans/2026-07-16-portal-status-filter.verify\nexport OAIES_VERIFY_EVIDENCE=docs/plans/2026-07-16-portal-status-filter.verify\nsh content/04-agent-engineering/hooks/post-code.hook.sh\n```\n\n### Failure modes to expect\n\n| Symptom | Likely cause | Fix |\n|---------|--------------|-----|\n| `pre-planning` exit 65 | Empty brief | Complete task brief |\n| Plan lists 20 files | Context dump / gold-plating | Tighten allowlist; re-plan |\n| Coder adds Redux | Plan silent on state | Amend plan; re-approve |\n| Tests missing in PR | Plan test section ignored | Block in review; see [PR review](./pr-review-with-ai.md) |\n\n---\n\n## Tradeoffs\n\n| Choice | Gain | Cost |\n|--------|------|------|\n| Hook-enforced plan | Cannot “forget” planning | Slight process friction on small tasks — mitigate with clear skip rules |\n| Plans as files | Auditable, reviewable in PRs | Path discipline; stale plans if not amended |\n| Chat-only plans | Fast | No `pre-code` gate; no audit |\n| Deep plans for every chore | Consistency theater | Token waste; engineer revolt |\n| Planner subagents | Parallel research | Delegation depth + budget controls required |\n\nDefault: **hooks on for multi-file**; document skip list; amend plans instead of ghost-writing architecture in the coder prompt.\n\n---\n\n## Anti-patterns\n\n| Anti-pattern | Why | Instead |\n|--------------|-----|---------|\n| Plan in chat only | Hooks cannot validate; approval evaporates | File + approval evidence |\n| “Decision completeness = 100%” checklists | Fake rigor; ignores risk | Risk-based section depth |\n| Coding during planning | Contaminates the plan with accidental commits | Separate stages; discard early patches |\n| Approving without reading blast radius | Ceremony | Require file table + risks sign-off |\n| Skipping plan for “just UI” | UI still has a11y, routing, and state contracts | Plan for route+component+test triplets |\n| One mega-plan for a quarter | Unimplementable | Story-sized plans; link epics |\n\n---\n\n## Enterprise considerations\n\n- **Audit:** Store plan SHA and approver identity with the PR (SOC2 change management narrative).\n- **Segregation of duties:** For high-risk changes, planner approver ≠ sole merge approver (see HITL).\n- **Regulated UI:** Accessibility and data-residency constraints belong in `{{TECHNICAL_CONSTRAINTS}}`, not as afterthoughts in review.\n- **Vendor agents:** If planning runs in a third-party IDE agent, export still includes code context — apply the same package rules as [How to give context](./how-to-give-context.md).\n- **Knowledge capture:** After non-obvious plans, run [`knowledge-capture.hook.sh`](../04-agent-engineering/hooks/knowledge-capture.hook.sh) / [`knowledge-capture.prompt.md`](../08-ai-sdlc/prompts/knowledge-capture.prompt.md) so the next team does not re-litigate the same architecture.\n\n---\n\n## Repo anchors\n\n| Need | Path |\n|------|------|\n| Planner pattern | [`content/patterns/planner-pattern/README.md`](../patterns/planner-pattern/README.md) |\n| Checklist / skills / examples | [`checklist.md`](../patterns/planner-pattern/checklist.md), [`skills.md`](../patterns/planner-pattern/skills.md), [`examples/example.md`](../patterns/planner-pattern/examples/example.md) |\n| Implementation plan prompt | [`content/08-ai-sdlc/prompts/implementation-plan.prompt.md`](../08-ai-sdlc/prompts/implementation-plan.prompt.md) |\n| Story kickoff | [`story-kickoff.prompt.md`](../08-ai-sdlc/prompts/story-kickoff.prompt.md) |\n| Coding prompt | [`coding.prompt.md`](../08-ai-sdlc/prompts/coding.prompt.md) |\n| Planning skill | [`content/03-skill-engineering/skills/planning.skill.md`](../03-skill-engineering/skills/planning.skill.md) |\n| Hooks README | [`content/04-agent-engineering/hooks/README.md`](../04-agent-engineering/hooks/README.md) |\n| Gates | `pre-planning`, `pre-code`, `post-code`, `pre-delegation`, `budget-guard` under [`hooks/`](../04-agent-engineering/hooks/) |\n| DoR / DoD | [`definition-of-ready.md`](../08-ai-sdlc/quality-standards/definition-of-ready.md), [`definition-of-done.md`](../08-ai-sdlc/quality-standards/definition-of-done.md) |\n\n---\n\n## Checklist\n\n- [ ] Planning triggers documented in project contract (and skip list is short)\n- [ ] `OAIES_REQUIREMENTS_FILE` points at a real brief; `pre-planning` passes\n- [ ] Plan generated with [`implementation-plan.prompt.md`](../08-ai-sdlc/prompts/implementation-plan.prompt.md) — **no code**\n- [ ] Plan file lists files, tests, risks, rollback, open questions\n- [ ] Named human recorded approval with `effect=workspace-write` + target\n- [ ] `pre-code` passes before any agent writes the workspace\n- [ ] Implementation diffs checked against plan; amendments re-approved\n- [ ] `post-code` verify evidence attached\n- [ ] High-risk plans have appropriate second reader (HITL policy)\n\n## Changelog\n\n- 2026-07-16: Initial practitioner handbook chapter for planning workflow wiring.\n",
   "mcps/README.md": "# MCP Integrations\n\n> **The M×N Problem Solver — One standard integration per external system.**\n\n---\n\n## What Is MCP\n\nModel Context Protocol (MCP) is the open standard for connecting AI agents to external data and tools. It solves the M×N integration problem:\n- **Without MCP:** M models × N tools = M×N custom integrations\n- **With MCP:** M models × N MCP servers = M+N implementations\n\nEvery major AI system (Claude, GPT-4, Gemini, Cursor, Windsurf, Roo) now supports MCP. It is the integration standard.\n\n---\n\n## Why This Section Exists\n\nMCP servers are easy to create poorly. The most common mistake is treating MCP as a thin API wrapper — just exposing existing APIs as tools. This leads to:\n- Too many tools loaded into context (degrading agent reasoning)\n- Tool definitions designed for humans, not agents\n- Missing security controls on tool execution\n- No rate limiting or cost controls\n\nThis section provides production-ready MCP integration specs that avoid these mistakes.\n\n---\n\n## MCP Design Principles (OAIES Standard)\n\n### 1. Design for the Agent, Not the API\nThe tool name and description must make sense to an LLM reasoning about what to do next — not to a developer reading API docs.\n\n```json\n// Wrong — designed for API documentation\n{\n  \"name\": \"POST /api/v2/issues\",\n  \"description\": \"Creates a new issue via the REST API\"\n}\n\n// Correct — designed for agent reasoning\n{\n  \"name\": \"create_issue\",\n  \"description\": \"Create a new GitHub issue. Use when you need to report a bug, request a feature, or track work. Requires: title (required), body (optional), labels (optional array).\"\n}\n```\n\n### 2. Principle of Least Privilege\nEvery MCP server must only expose the minimum tools and permissions required. Do not expose delete operations if the agent only needs read access.\n\n### 3. Avoid Context Bloat\nLoad tool definitions progressively. Don't register 50 tools at startup. Use categories or lazy loading so only relevant tools are in context.\n\n### 4. Security First\nAll tool inputs are untrusted. Validate and sanitize before execution. Apply OAuth 2.1 for production deployments.\n\n### 5. Every Tool Call Is Audited\nAll tool invocations (inputs and outputs) must be logged for audit, debugging, and cost tracking.\n\n---\n\n## Available MCP Integrations\n\n### Developer Tools\n| MCP | File | Primary Use |\n|-----|------|------------|\n| GitHub | [github.mcp.md](./version-control/github.mcp.md) | Issues, PRs, code search |\n| GitLab | gitlab.mcp.md (Planned) | MRs, pipelines, issues |\n| Azure DevOps | azure-devops.mcp.md (Planned) | Work items, pipelines, repos |\n| Playwright | playwright.mcp.md (Planned) | Browser automation, testing |\n| Chrome DevTools | chrome-devtools.mcp.md (Planned) | Performance, debugging |\n\n### Project Management\n| MCP | Status | Primary Use |\n|-----|--------|------------|\n| Jira | jira.mcp.md (Planned) | Issues, sprints, backlogs |\n| Linear | linear.mcp.md (Planned) | Issues, projects, cycles |\n| Notion | notion.mcp.md (Planned) | Docs, databases, pages |\n\n### Communication\n| MCP | Status | Primary Use |\n|-----|--------|------------|\n| Slack | slack.mcp.md (Planned) | Messages, channels, search |\n| Microsoft Teams | teams.mcp.md (Planned) | Messages, meetings, files |\n\n### Infrastructure\n| MCP | Status | Primary Use |\n|-----|--------|------------|\n| Filesystem | filesystem.mcp.md (Planned) | File read/write with path validation |\n| Docker | docker.mcp.md (Planned) | Container management |\n| PostgreSQL | postgres.mcp.md (Planned) | Database queries (read-only by default) |\n| Redis | redis.mcp.md (Planned) | Cache operations |\n| Supabase | supabase.mcp.md (Planned) | Database + auth + storage |\n\n### Observability\n| MCP | Status | Primary Use |\n|-----|--------|------------|\n| Sentry | sentry.mcp.md (Planned) | Error tracking, performance |\n| Datadog | datadog.mcp.md (Planned) | Metrics, logs, traces |\n| Grafana | grafana.mcp.md (Planned) | Dashboards, alerts |\n| OpenTelemetry | opentelemetry.mcp.md (Planned) | Traces, metrics, logs |\n\n---\n\n## MCP Specification Format\n\nEvery MCP in this library follows this specification:\n\n```markdown\n# {Service} MCP Integration\n\n## Purpose\n[What this MCP enables an agent to do]\n\n## Security Model\n[Authentication method, required permissions, threat model]\n\n## Tool Definitions\n\n### Tool: {tool_name}\n**Description:** [Agent-facing description]\n**Input schema:**\n```json\n{\n  \"property\": \"type — description\"\n}\n```\n**Output:** [What the tool returns]\n**Rate limits:** [API limits to respect]\n**Errors:** [Common errors and handling]\n\n## Example Agent Interactions\n[Concrete example of agent using this MCP]\n\n## Anti-Patterns\n[What not to do with this MCP]\n```\n\n---\n\n## Security Considerations for All MCPs\n\nBefore deploying any MCP server in production:\n\n- [ ] Authentication: OAuth 2.1 or API key with rotation schedule\n- [ ] Authorization: Tool execution restricted by user permissions\n- [ ] Input validation: All tool inputs validated (type, length, allowed patterns)\n- [ ] Output filtering: Sensitive data stripped from tool responses\n- [ ] Rate limiting: Tool calls rate-limited per user/session\n- [ ] Audit logging: All tool calls logged with user, inputs, outputs\n- [ ] Least privilege: Server can only access what it needs\n- [ ] SSRF protection: Outbound calls from MCP server validate destinations\n\n---\n\n## Checklist\n\nFor each MCP server you deploy:\n- [ ] Tool descriptions are agent-optimized (not API-documentation-style)\n- [ ] Maximum 10-15 tools per server (fewer = better agent reasoning)\n- [ ] All tool inputs validated before execution\n- [ ] OAuth 2.1 authentication implemented\n- [ ] Audit logging enabled\n- [ ] Rate limiting configured\n- [ ] Tested with adversarial inputs (injection, path traversal, SSRF)\n- [ ] Documented in your system's architecture\n",
+  "hooks/CONTRACT.md": "# Deterministic Evidence Hooks\n\n> **Version:** 2.0  \n> **Updated:** 2026-07-16\n\n## Purpose\nThese 12 POSIX `sh` hooks validate declared lifecycle evidence and effect approvals. They are gates, not task runners, secret scanners, policy engines, or deployment systems.\n\n## Why\nExecuting command text from environment variables with `sh -c` creates an injection boundary and makes dry-run behavior ambiguous. Version 2.0 removes command execution: orchestration runs approved tools and supplies non-empty evidence records for deterministic validation.\n\n## Contract and Exit Semantics\n- Optional `--dry-run` validates declared inputs. Only `pre-commit` changes behavior: dry-run skips Git staged-diff inspection; every other hook performs the same read-only checks.\n- Exit `0`: the narrow gate passed.\n- Exit `64`: usage or required declaration is missing.\n- Exit `65`: evidence is malformed, unreadable, empty, or uses an unknown classification.\n- Exit `70`: evidence is valid but the policy condition failed.\n- Hooks read regular files, environment declarations, and for non-dry-run `pre-commit`, the staged Git diff. They execute no supplied command text and perform no network or external mutation.\n\n## Inputs\n| Hook | Required declarations | What it actually checks |\n|---|---|---|\n| `pre-planning` | `OAIES_REQUIREMENTS_FILE` | Readable, non-empty, non-whitespace requirements |\n| `pre-code` | `OAIES_PLAN_FILE`, `OAIES_APPROVAL_FILE` | Plan exists; approval declares `effect=workspace-write` and a target |\n| `post-code` | `OAIES_VERIFY_EVIDENCE` | Evidence declares passed status and artifact |\n| `pre-commit` | `OAIES_TEST_EVIDENCE`, `OAIES_SECRET_SCAN_EVIDENCE` | Both declare passed; non-dry-run also blocks a staged private-key header |\n| `pre-review` | `OAIES_FORMAT_EVIDENCE`, `OAIES_LINT_EVIDENCE` | Both evidence files declare passed |\n| `deployment` | `OAIES_RELEASE_MANIFEST`, `OAIES_APPROVAL_FILE`, `OAIES_RELEASE_EVIDENCE` | Digest/environment, deployment approval, and passed release evidence |\n| `knowledge-capture` | `OAIES_KNOWLEDGE_FILE` | Owner, source, and retention fields exist |\n| `pre-tool-call` | `OAIES_TOOL_EFFECT`; approval file for high effects | Known effect; high effect approval matches effect and names target |\n| `post-tool-call` | `OAIES_TOOL_RESULT_FILE` | Status, effect, and target fields exist |\n| `pre-delegation` | `OAIES_DELEGATION_FILE` | Principal, scope, budget profile, and positive remaining depth |\n| `post-deployment` | `OAIES_HEALTH_EVIDENCE` | Digest, environment, and healthy status |\n| `budget-guard` | `OAIES_BUDGET_PROFILE`, `OAIES_BUDGET_REMAINING` | Named profile and positive integer remaining budget |\n\n## How\n```sh\nprintf '%s\\n' 'status=passed' 'artifact=sha256:abc' > verify.evidence\nOAIES_VERIFY_EVIDENCE=verify.evidence sh ./post-code.hook.sh\n\nprintf '%s\\n' 'effect=deployment' 'target=staging' > approval.evidence\nOAIES_TOOL_EFFECT=deployment OAIES_APPROVAL_FILE=approval.evidence \\\n  sh ./pre-tool-call.hook.sh --dry-run\n```\n\n## Verification\nRun `sh ./tests/hooks.test.sh`. The isolated harness checks all 12 hooks, success and failure paths, dry-run behavior, effect matching, budget exhaustion, and a staged private-key fixture.\n\n## Security and Portability Audit\n- No `eval`, `sh -c`, temporary command construction, network call, or external mutation exists.\n- Scripts use POSIX `sh`, `case`, `grep`, `sed`, test, and `printf`; `pre-commit` additionally requires Git.\n- Evidence files are declarations, not cryptographic attestations. The orchestrator must protect and bind them to task, artifact, environment, and producer identity.\n- The private-key-header check is intentionally narrow and high-confidence. It does not claim to detect tokens, passwords, entropy, history leaks, or encoded secrets; use an approved scanner and provide its evidence.\n\n## Unhappy Paths and Recovery\nDo not bypass a failing gate. Correct malformed evidence, obtain a target-specific approval, rerun the external verifier, or escalate the exact failed condition. A passed gate proves only the checks listed above.\n\n## Tradeoffs\nEvidence gates are safer and more portable than command runners but cannot prove evidence authenticity or freshness alone. Production orchestration should sign evidence or store it in an access-controlled attestation service.\n\n## Anti-Patterns\n- Treating `status=passed` text as a trusted attestation without provenance controls.\n- Reusing an approval file for another target, effect, artifact, or time window.\n- Describing `pre-commit` as a comprehensive secret scanner.\n\n## Enterprise Considerations\nIssue signed, immutable evidence with task ID, producer identity, artifact digest, target, timestamps, and policy version. Enforce freshness and replay prevention in the orchestrator.\n\n## Checklist\n- [ ] All 12 hooks pass syntax and deterministic behavior tests\n- [ ] No command-text execution remains\n- [ ] Evidence producer and storage are protected\n- [ ] Approval binding is enforced upstream\n- [ ] Secret scanning and policy engines run separately\n\n## Authoritative Sources\n- [POSIX Shell Command Language](https://pubs.opengroup.org/onlinepubs/9799919799/utilities/V3_chap02.html)\n- [OWASP OS Command Injection Defense](https://cheatsheetseries.owasp.org/cheatsheets/OS_Command_Injection_Defense_Cheat_Sheet.html)\n- [SLSA Provenance](https://slsa.dev/spec/v1.0/provenance)\n\n## Changelog\n- **2.0 (2026-07-16):** Removed command execution, narrowed claims, defined evidence and exit contracts, and expanded deterministic tests.\n- **1.0:** Initial hook library.\n",
+  "kit/plans-README.md": "# Ephemeral implementation plans\n\n> **These files are temporary.** Scope = one story/task until done. Do **not** maintain a permanent living plan in git as the source of truth — that is an anti-pattern.\n\n---\n\n## Purpose\n\nGive the coding agent a **decision-complete contract for this slice only**. When the PR merges (or the task is cancelled), the plan’s job is finished.\n\n## Naming (required)\n\n| Artifact | Path |\n|----------|------|\n| Active plan | `plans/{STORY_ID}-plan.md` |\n| Code review report | `reviews/{STORY_ID}-code-review.md` |\n\nExamples: `plans/JIRA-1234-plan.md`, `plans/GH-88-plan.md`, `reviews/JIRA-1234-code-review.md`.\n\nIf there is no tracker id, use a short slug: `plans/2026-07-29-auth-refresh-plan.md`.\n\n## Lifecycle\n\n1. **Create** the plan with the `implementation-plan` prompt (copy from `_TEMPLATE.md`).\n2. **Approve** (human) before multi-file coding.\n3. **Attach** the plan in every agent session for that story (IDE attach / `@file` / `#file:`).\n4. **Attach to the PR** (description link or uploaded artifact) for audit.\n5. **Stop maintaining it** after merge — delete, move to `plans/archive/`, or leave as frozen PR evidence. Do **not** keep editing it as a roadmap.\n\n## Temporary memory (preferred patterns)\n\n| Approach | When |\n|----------|------|\n| Attach `plans/{STORY_ID}-plan.md` each chat turn | Default — durable across sessions without polluting long-term docs |\n| IDE chat “sticky” / context include for the plan file | Short spikes |\n| PR body checklist mirroring plan tasks | Human review only |\n| Agent memory / notes keyed by `STORY_ID` | Optional — still keep the file as the contract |\n\nDo **not** dump the full plan into `CLAUDE.md` / `AGENTS.md` / forever-rules.\n\n## Anti-patterns\n\n- A single root `implementation_plan.md` updated for every feature forever\n- Treating the plan as product roadmap or architecture ADR\n- Coding with no plan file for multi-file work\n- Renaming without `STORY_ID` so reviews cannot correlate plan ↔ PR ↔ review report\n\n## Template\n\nCopy [`_TEMPLATE.md`](./_TEMPLATE.md) → `plans/{STORY_ID}-plan.md`.\n",
+  "kit/plan-TEMPLATE.md": "# Implementation Plan — {{STORY_ID}}\n\n> **Ephemeral.** Valid only until this story/PR completes.  \n> **Do not** keep maintaining this file after merge. Attach to the PR, then archive or delete.  \n> Author with the `implementation-plan` prompt + planning skill.\n\n## Metadata\n\n| Field | Value |\n|-------|-------|\n| Story ID | `{{STORY_ID}}` |\n| Title | |\n| Author | |\n| Created | |\n| Expires / done when | PR merged or story cancelled |\n| Related review | `reviews/{{STORY_ID}}-code-review.md` |\n\n## Goal\n\n<!-- One sentence outcome for this story only -->\n\n## Context\n\n<!-- Tickets, ADRs, designs, prior PRs — links only -->\n\n## Scope\n\n### In scope\n\n-\n\n### Out of scope / non-goals\n\n-\n\n## Tasks\n\n| ID | Task | Files / areas | Verification command or evidence | Owner | Done |\n|----|------|---------------|----------------------------------|-------|------|\n| 1 | | | | | [ ] |\n\n## Dependencies & sequencing\n\n-\n\n## Risks\n\n| Risk | Likelihood | Impact | Mitigation |\n|------|------------|--------|------------|\n| | | | |\n\n## Rollback\n\n-\n\n## Test / eval plan\n\n-\n\n## Guardrails (from this repo)\n\n- Lint / typecheck / test commands that must stay green:\n- Style guides / ADRs that apply:\n\n## Human approval\n\n- [ ] Plan reviewed for completeness and scope leakage\n- [ ] Approved by: _______________\n- [ ] Date: _______________\n\n## Close-out (required)\n\n- [ ] PR link: _______________\n- [ ] Plan attached to PR\n- [ ] Review report written: `reviews/{{STORY_ID}}-code-review.md`\n- [ ] Plan marked done — **no further maintenance**\n",
+  "kit/reviews-README.md": "# Ephemeral code review reports\n\n> Reports are **per story**. Correlate with `plans/{STORY_ID}-plan.md`. Do not maintain a forever-growing review doc.\n\n## Naming\n\n`reviews/{STORY_ID}-code-review.md`\n\n## Lifecycle\n\n1. After implementation (or on PR open), run the **code-review** skill / Reviewer pattern.\n2. Write findings into `reviews/{STORY_ID}-code-review.md` (copy `_TEMPLATE.md`).\n3. Attach to the PR.\n4. After merge: freeze — do not keep editing as a living backlog (file issues instead).\n\n## Template\n\nCopy [`_TEMPLATE.md`](./_TEMPLATE.md).\n",
+  "kit/review-TEMPLATE.md": "# Code review report — {{STORY_ID}}\n\n> **Ephemeral.** Tied to `plans/{{STORY_ID}}-plan.md` and one PR.  \n> Severity-calibrated findings only. Human owns merge.\n\n## Metadata\n\n| Field | Value |\n|-------|-------|\n| Story ID | `{{STORY_ID}}` |\n| Plan | `plans/{{STORY_ID}}-plan.md` |\n| PR | |\n| Reviewer (human) | |\n| Date | |\n\n## Summary\n\n| Severity | Count | Blocks merge? |\n|----------|-------|---------------|\n| Critical | 0 | Yes |\n| High | 0 | Yes |\n| Medium | 0 | Policy |\n| Low / Note | 0 | No |\n\n## Findings\n\n| ID | Severity | Path:line | Issue | Evidence | Recommendation |\n|----|----------|-----------|-------|----------|----------------|\n| 1 | | | | | |\n\n## Guardrail compliance\n\n- [ ] Lint / typecheck / tests match repo commands\n- [ ] Diff stays inside planned paths (or approved delta)\n- [ ] No secrets committed\n- [ ] AuthZ / data-class reviewed if touched\n\n## Decision\n\n- [ ] Approve\n- [ ] Approve with follow-ups (issues filed)\n- [ ] Block — Critical/High open\n\n## Close-out\n\n- [ ] Attached to PR\n- [ ] No further maintenance after merge — file issues for leftovers\n",
+  "kit/hooks-README.md": "# AIES agent hooks (evidence gates)\n\n> Installed by `create-aies-kit`. These are **deterministic evidence gates**, not task runners.\n\n## Purpose\n\nBlock plan→code→commit→review→deploy progression unless declared evidence exists. Humans/orchestrators still run lint, tests, and deploys — hooks only validate that evidence was recorded.\n\n## Layout\n\n| Path | Role |\n|------|------|\n| `hooks/*.hook.sh` | POSIX gates (pre-planning, pre-code, pre-review, pre-commit, …) |\n| `hooks/README.md` | This file |\n| `aies-hooks.json` or `.cursor/aies-hooks.json` | Machine-readable hook registry for agents/IDEs |\n\n## Typical AI development loop\n\n```text\nstory → plans/{STORY_ID}-plan.md (approve)\n     → pre-planning / pre-code hooks\n     → coding prompt + plan attached\n     → verify (lint/typecheck/test — repo commands)\n     → reviews/{STORY_ID}-code-review.md\n     → pre-review / pre-commit hooks\n     → PR + attach plan + review\n```\n\n## Example (dry-run)\n\n```sh\n# After you have a plan file and approval record:\nprintf '%s\\n' 'effect=workspace-write' 'target=plans/JIRA-1-plan.md' > /tmp/approval.evidence\nOAIES_PLAN_FILE=plans/JIRA-1-plan.md OAIES_APPROVAL_FILE=/tmp/approval.evidence \\\n  sh hooks/pre-code.hook.sh --dry-run\n```\n\n## Wire to this repo\n\nAfter `enhance-repo`, document the **exact** lint/test commands in `AIES.md` and paste them into evidence producers. Do not invent commands.\n\n## Anti-patterns\n\n- Bypassing a failed hook with `--force` folklore\n- Treating `status=passed` text as cryptographic attestation\n- Putting hooks under `.github/` as if they were GitHub Actions (they are not)\n\nFull contract: see AIES handbook *Hooks in practice* / upstream `04-agent-engineering/hooks`.\n",
   "cookbook/react/architecture/patterns.md": "# React Architecture Patterns\n\n> Version: 1.1.0 | Updated: 2026-07-16\n\n## Purpose\n\nDefine the production components, control paths, state boundaries, and failure containment for component, Hook, context boundary, or route UI.\n\n## Why\n\nRendering stays pure; state has one owner; Effects synchronize only with external systems. The diagram models actual React platform elements so reviewers can identify ownership and unsafe coupling.\n\n## How\n\n```mermaid\nflowchart LR\n  Route[Router boundary] --> Feature[Feature container]\n  Feature --> Hook[Custom Hooks]\n  Hook --> Store[Server cache or state owner]\n  Feature --> View[Pure semantic components]\n  View --> DOM[Accessible DOM]\n  Boundary[Error and Suspense boundaries] -. contain .-> Feature\n  Profiler[React Profiler and RUM] -. observes .-> Feature\n```\n\n### Required boundaries\n\n1. Route and feature boundaries own orchestration; leaf components receive typed data and events.\n2. A custom Hook owns one synchronization concern and exposes no renderer-specific side effects.\n3. Error and Suspense boundaries are placed at independently recoverable UI regions.\n4. Server state remains in the data cache; transient interaction state remains local.\n5. The design system owns semantic primitives and focus behavior.\n\n### Operational evidence\n\n- `package.json` plus the lockfile entries for React, renderer, router, state, and test libraries\n- `tsconfig.json` and ESLint React/Hook rules\n- the nearest component, test, CSS, and Storybook conventions\n- React DevTools Profiler commit/flamegraph for the reproduced interaction\n\n### Rollback path\n\nDisable the owning feature flag first; otherwise redeploy the previous immutable client assets while preserving API compatibility for already-cached bundles.\n\n## Version-aware caution\n\nRead the installed `react` and `react-dom` versions from the lockfile. Concurrent rendering, form actions, and server integration differ across React and framework releases; never copy an API from current react.dev into an older dependency graph without checking that release's reference.\n\n## Tradeoffs\n\nThe architecture introduces explicit React boundaries and operational artifacts that require ownership. In return, failures in Rules of Hooks violations, stale closures and effect feedback loops, unstable keys or identity, hydration divergence, excessive render or bundle cost become observable and containable.\n\n## Anti-patterns\n\n- A page-wide context holding unrelated mutable state causes every consumer to share a render and release boundary.\n- Do not remove a native warning, validator, policy, or safety limit merely to make generated output pass.\n- Do not claim a successful result without preserving the command, target, artifact/revision, and observed output.\n\n## Enterprise considerations\n\nFor React estates, govern design-system packages, browser support, telemetry consent, third-party scripts, and accessibility evidence centrally; product teams retain ownership of feature behavior.\n\n## Official sources\n\n- [React Learn](https://react.dev/learn)\n- [Rules of Hooks](https://react.dev/reference/rules/rules-of-hooks)\n- [React DevTools Profiler](https://react.dev/learn/react-developer-tools)\n- [WAI-ARIA APG](https://www.w3.org/WAI/ARIA/apg/)\n\n## Checklist\n\n- [ ] Route and feature boundaries own orchestration; leaf components receive typed data and events.\n- [ ] A custom Hook owns one synchronization concern and exposes no renderer-specific side effects.\n- [ ] Error and Suspense boundaries are placed at independently recoverable UI regions.\n- [ ] Server state remains in the data cache; transient interaction state remains local.\n- [ ] The design system owns semantic primitives and focus behavior.\n- [ ] Diagram matches deployed topology rather than an aspirational target.\n- [ ] Rollback path preserves state and mixed-version contracts.\n\n## Changelog\n\n- 1.1.0 (2026-07-16): Replaced generic adapter diagram with native React architecture.\n- 1.0.0 (2026-07-16): Added initial pattern.\n",
   "cookbook/react/checklists/code-review.md": "# React Code Review Checklist\n\n> Version: 1.1.0 | Updated: 2026-07-16\n\n## Purpose\n\nGate correctness, security, operability, and maintainability of a React component, Hook, context boundary, or route UI.\n\n## Why\n\nReact correctness depends on source plus `package.json` plus the lockfile entries for React, renderer, router, state, and test libraries; `tsconfig.json` and ESLint React/Hook rules; the nearest component, test, CSS, and Storybook conventions. Diff-only review is insufficient.\n\n## How\n\nReview the change with its target/version fingerprint, then execute applicable native commands: `npm run lint -- --max-warnings=0`; `npx tsc --noEmit`; `npm test -- --runInBand` using the repository test script; `npm run build` and inspect the emitted bundle report when configured; React DevTools Profiler: record the exact interaction and compare committed renders. Findings must identify the violated React invariant.\n\n## Version-aware caution\n\nRead the installed `react` and `react-dom` versions from the lockfile. Concurrent rendering, form actions, and server integration differ across React and framework releases; never copy an API from current react.dev into an older dependency graph without checking that release's reference.\n\n## Tradeoffs\n\nReview must prove \"Hooks are top-level and exhaustive dependency analysis is satisfied without suppression\" using `package.json` plus the lockfile entries for React, renderer, router, state, and test libraries. That React evidence costs more than diff inspection but exposes Rules of Hooks violations before merge.\n\n## Anti-patterns\n\n- A page-wide context holding unrelated mutable state causes every consumer to share a render and release boundary.\n- Do not remove a native warning, validator, policy, or safety limit merely to make generated output pass.\n- Do not claim a successful result without preserving the command, target, artifact/revision, and observed output.\n\n## Enterprise considerations\n\nFor React estates, govern design-system packages, browser support, telemetry consent, third-party scripts, and accessibility evidence centrally; product teams retain ownership of feature behavior.\n\n## Official sources\n\n- [React Learn](https://react.dev/learn)\n- [Rules of Hooks](https://react.dev/reference/rules/rules-of-hooks)\n- [React DevTools Profiler](https://react.dev/learn/react-developer-tools)\n- [WAI-ARIA APG](https://www.w3.org/WAI/ARIA/apg/)\n\n## Checklist\n\n- [ ] Hooks are top-level and exhaustive dependency analysis is satisfied without suppression.\n- [ ] derived values are computed during render instead of mirrored through an Effect.\n- [ ] state is colocated with its owner; context values and callbacks avoid accidental identity churn.\n- [ ] list keys represent durable entity identity, never position where order can change.\n- [ ] loading, empty, error, disabled, and interrupted interaction states are represented.\n- [ ] native HTML semantics, focus behavior, accessible names, and keyboard operation are tested.\n- [ ] tests assert user-visible behavior with the project's renderer rather than component internals.\n- [ ] Profiler evidence justifies memoization; `useMemo` and `memo` are not speculative.\n- [ ] Disable the owning feature flag first; otherwise redeploy the previous immutable client assets while preserving API compatibility for already-cached bundles.\n- [ ] Evidence identifies version, target, artifact/revision, command or manual method, UTC time, and result.\n\n## Changelog\n\n- 1.1.0 (2026-07-16): Replaced generic gates with native React evidence and failure controls.\n- 1.0.0 (2026-07-16): Added initial checklist.\n",
   "cookbook/react/checklists/deployment.md": "# React Deployment Checklist\n\n> Version: 1.1.0 | Updated: 2026-07-16\n\n## Purpose\n\nGate promotion and rollback of a React component, Hook, context boundary, or route UI.\n\n## Why\n\nA syntactically valid React artifact can still fail because of Rules of Hooks violations, stale closures and effect feedback loops, unstable keys or identity, hydration divergence, excessive render or bundle cost. Promotion therefore requires target-state and rollback evidence.\n\n## How\n\nRun against the exact target and immutable candidate. Preserve outputs from `npm run lint -- --max-warnings=0`; `npx tsc --noEmit`; `npm test -- --runInBand` using the repository test script; `npm run build` and inspect the emitted bundle report when configured; React DevTools Profiler: record the exact interaction and compare committed renders. Stop promotion on any failed item.\n\n## Version-aware caution\n\nRead the installed `react` and `react-dom` versions from the lockfile. Concurrent rendering, form actions, and server integration differ across React and framework releases; never copy an API from current react.dev into an older dependency graph without checking that release's reference.\n\n## Tradeoffs\n\nPromotion waits for \"production build completes with the repository's exact React renderer and bundler versions\" and \"route-level chunks and source-map policy are inspected for unexpected dependency or secret exposure\". Those React target checks slow release but directly bound Rules of Hooks violations and make this rollback executable: Disable the owning feature flag first; otherwise redeploy the previous immutable client assets while preserving API compatibility for already-cached bundles.\n\n## Anti-patterns\n\n- A page-wide context holding unrelated mutable state causes every consumer to share a render and release boundary.\n- Do not remove a native warning, validator, policy, or safety limit merely to make generated output pass.\n- Do not claim a successful result without preserving the command, target, artifact/revision, and observed output.\n\n## Enterprise considerations\n\nFor React estates, govern design-system packages, browser support, telemetry consent, third-party scripts, and accessibility evidence centrally; product teams retain ownership of feature behavior.\n\n## Official sources\n\n- [React Learn](https://react.dev/learn)\n- [Rules of Hooks](https://react.dev/reference/rules/rules-of-hooks)\n- [React DevTools Profiler](https://react.dev/learn/react-developer-tools)\n- [WAI-ARIA APG](https://www.w3.org/WAI/ARIA/apg/)\n\n## Checklist\n\n- [ ] production build completes with the repository's exact React renderer and bundler versions.\n- [ ] route-level chunks and source-map policy are inspected for unexpected dependency or secret exposure.\n- [ ] SSR or prerendered pages hydrate without console errors under production mode.\n- [ ] critical interactions pass keyboard, focus, screen-reader smoke, and error-boundary tests.\n- [ ] real-user error and Web Vital dashboards are segmented by release.\n- [ ] canary cohort shows no increase in hydration, render, or JavaScript errors.\n- [ ] feature flag can disable the changed interaction without requiring an asset rollback.\n- [ ] rollback restores a compatible server/API contract for cached clients.\n- [ ] Disable the owning feature flag first; otherwise redeploy the previous immutable client assets while preserving API compatibility for already-cached bundles.\n- [ ] Evidence identifies version, target, artifact/revision, command or manual method, UTC time, and result.\n\n## Changelog\n\n- 1.1.0 (2026-07-16): Replaced generic gates with native React evidence and failure controls.\n- 1.0.0 (2026-07-16): Added initial checklist.\n",
@@ -116,5 +122,17 @@ export const EMBEDDED_CORPUS = {
   "mcps/project-management/monday.mcp.md": "# monday.com MCP Integration\n\n> **Version:** 1.1 | **Updated:** 2026-07-16 | **Category:** Project Management\n\n## Purpose and applicability\nProvide agent-safe access to accounts, workspaces, boards, items, updates. Use this integration only when those capabilities are required and a named owner accepts the data and write risk. The implementation baseline is monday.com's official MCP server.\n\n## Protocol, transport, and capability lifecycle\nImplement stable MCP `2025-11-25`. Negotiate `protocolVersion` in `initialize`; reject unsupported versions. Prefer Streamable HTTP for remote service and `stdio` only for a local, single-user process; do not expose `stdio` through a network shim. Advertise only implemented `tools`, `resources`, `prompts`, and `logging`. Paginate lists, use progress/cancellation where supported, and send the corresponding `list_changed` notification after authorization or configuration changes. Clients re-list and review metadata changes before use.\n\n## Tool, resource, and prompt design\n- **Tools:** bounded list/get/search operations over accounts, workspaces, boards, items, updates; mutations are separate, disabled by default, idempotency-aware, and approval-gated.\n- **Resources:** canonical read-only URIs scoped to account/workspace/board; stable IDs and versions replace display names where possible.\n- **Prompts:** vendor-specific triage/review prompts return instructions and resource links only; prompts never silently invoke tools.\n- **Validation:** closed JSON Schemas; normalize and authorize account/board/item IDs and GraphQL complexity; cap arrays, strings, time ranges, rows, bytes, and pagination. Return typed, size-bounded results with opaque cursors and structured errors. Label all provider content untrusted and redact credentials, secrets, personal data, and internal URLs.\n\n## Authorization, consent, and least privilege\nRemote deployments publish RFC 9728 Protected Resource Metadata and standards-compliant `WWW-Authenticate`. Discover the authorization server from metadata, require authorization code flow with PKCE `S256`, verify advertised PKCE support, and include the canonical MCP URI as RFC 8707 `resource` in authorization and token requests. Validate token signature, issuer, expiry/not-before, authorized party when applicable, and audience/resource for this server.\n\nNever pass an inbound MCP bearer token to the provider. Exchange/map it server-side to a short-lived, tenant-bound provider credential. Consent names the provider, tenant, enabled tools, data classes, and write effects. Use monday OAuth/app consent and board permissions; rely on the provider's current permission catalog and consent screen—never invent scope names. Step-up authorization cannot silently broaden prior consent.\n\n## Threat controls\n| Risk | Mandatory control |\n|---|---|\n| Prompt injection | Treat provider/web/database text as data; instructions in results cannot authorize calls or alter policy. |\n| Tool poisoning | Pin package/image and provenance; allowlist tools; diff descriptions/schemas on change before activation. |\n| Exfiltration | Enforce tenant/object allowlists, DLP/redaction, egress policy, response caps, and approval for cross-boundary transfer. |\n| SSRF | Fixed provider origins, DNS/IP checks, redirect revalidation, private/link-local denial, and no arbitrary URL fetch tool. |\n| Unsafe writes | Policy plus provider authorization, exact-argument approval, concurrency checks, idempotency key where supported, and no blind retry. |\n\n## Operations, tenancy, and incidents\nRate-limit against monday complexity, daily, minute, concurrency, and IP counters returned by the API. Do not claim a fixed limit where the provider makes limits endpoint-, plan-, or tenant-dependent. Apply budgets per user/tenant/tool, bounded jittered backoff for idempotent reads, circuit breaking, and surfaced retry times.\n\nEmit OpenTelemetry metrics/spans for tool, tenant hash, status, latency, bytes, pagination, approval ID, provider request ID, and rate-limit state; never record tokens or raw content. Partition credentials, caches, cursors, browser/database sessions, telemetry, and audit records by account/workspace/board. Re-authorize on tenant change.\n\nRevocation disables the grant immediately, removes provider credentials, terminates sessions, and evicts credential-bound caches. Incident response: disable risky tools, revoke/rotate credentials, preserve tamper-evident audit evidence, identify tenants/calls/data, contain egress, notify owners under policy, patch and adversarially retest before staged restoration.\n\n## Verification\n- Contract-test initialization/version failure, capability declarations/change, schemas, pagination, cancellation, errors, and output caps.\n- Test RFC 9728 discovery, PKCE downgrade refusal, RFC 8707 resource binding, issuer/audience/expiry rejection, no token passthrough, consent, revocation, and tenant isolation.\n- Attack-test injected content, poisoned tool metadata, DNS rebinding/redirect SSRF, oversized/secret output, confused deputy, approval replay, cross-tenant cursors, and rate-limit exhaustion.\n- Test read and write paths in a disposable tenant; prove provider authorization and rollback/compensation behavior.\n\n## Tradeoffs\nGraphQL flexibility improves coverage but requires strict complexity budgets. Least-privilege tool selection reduces agent flexibility and requires ongoing permission and schema maintenance.\n\n## Anti-patterns\n- Broad administrator credentials, undocumented scopes/quotas, shared cross-tenant sessions, or secrets in config/logs.\n- Exposing the provider API one-for-one, enabling all tools, trusting returned instructions, or treating model confirmation as durable approval.\n- Retrying writes after ambiguous failure, accepting arbitrary URLs/queries/paths, or logging complete payloads.\n\n## Enterprise considerations\nEnforce monday.com SAML/SCIM, account and workspace permissions, closed-workspace policy, app allowlists, audit-log export, data residency, and board-level data classification. Enforce separation of duties, legal hold and accessibility requirements where applicable; pin releases, verify provenance/SBOMs, stage upgrades, and document RTO/RPO plus outage behavior.\n\n## Checklist\n- [ ] Implementation and transports approved; MCP negotiation and capability change tested\n- [ ] Tools/resources/prompts bounded; input/output validation and write approvals enforced\n- [ ] RFC 9728, PKCE S256, RFC 8707, issuer/audience validation, consent, and least privilege verified\n- [ ] No token passthrough; injection, exfiltration, SSRF, and tool-poisoning defenses tested\n- [ ] Provider-aware limits, redacted telemetry, tenancy, revocation, and incident runbook operational\n- [ ] Tradeoffs, enterprise controls, contract/integration/adversarial tests accepted\n\n## Primary references\n- [monday.com implementation/API](https://developer.monday.com/apps/docs/mondaycom-mcp-integration)\n- [monday.com limits/security](https://developer.monday.com/api-reference/docs/rate-limits)\n- [MCP specification `2025-11-25`](https://modelcontextprotocol.io/specification/2025-11-25/)\n- [MCP authorization](https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization)\n\n## Changelog\n- **1.1 — 2026-07-16:** Replaced a template marker with concrete service-specific enterprise controls.\n- **1.0 — 2026-07-16:** Initial production specification.\n",
   "mcps/communication/slack.mcp.md": "# Slack MCP Integration\n\n> **Version:** 1.1 | **Updated:** 2026-07-16 | **Category:** Communication\n\n## Purpose and applicability\nProvide agent-safe access to workspaces, channels, threads, messages, search. Use this integration only when those capabilities are required and a named owner accepts the data and write risk. The implementation baseline is Slack's official hosted MCP server when available to the tenant; otherwise a Slack app adapter.\n\n## Protocol, transport, and capability lifecycle\nImplement stable MCP `2025-11-25`. Negotiate `protocolVersion` in `initialize`; reject unsupported versions. Prefer Streamable HTTP for remote service and `stdio` only for a local, single-user process; do not expose `stdio` through a network shim. Advertise only implemented `tools`, `resources`, `prompts`, and `logging`. Paginate lists, use progress/cancellation where supported, and send the corresponding `list_changed` notification after authorization or configuration changes. Clients re-list and review metadata changes before use.\n\n## Tool, resource, and prompt design\n- **Tools:** bounded list/get/search operations over workspaces, channels, threads, messages, search; mutations are separate, disabled by default, idempotency-aware, and approval-gated.\n- **Resources:** canonical read-only URIs scoped to Enterprise Grid organization/workspace/channel; stable IDs and versions replace display names where possible.\n- **Prompts:** vendor-specific triage/review prompts return instructions and resource links only; prompts never silently invoke tools.\n- **Validation:** closed JSON Schemas; normalize and authorize team/channel/user IDs, timestamps, and text length; cap arrays, strings, time ranges, rows, bytes, and pagination. Return typed, size-bounded results with opaque cursors and structured errors. Label all provider content untrusted and redact credentials, secrets, personal data, and internal URLs.\n\n## Authorization, consent, and least privilege\nRemote deployments publish RFC 9728 Protected Resource Metadata and standards-compliant `WWW-Authenticate`. Discover the authorization server from metadata, require authorization code flow with PKCE `S256`, verify advertised PKCE support, and include the canonical MCP URI as RFC 8707 `resource` in authorization and token requests. Validate token signature, issuer, expiry/not-before, authorized party when applicable, and audience/resource for this server.\n\nNever pass an inbound MCP bearer token to the provider. Exchange/map it server-side to a short-lived, tenant-bound provider credential. Consent names the provider, tenant, enabled tools, data classes, and write effects. Use Slack app/user consent and channel membership; rely on the provider's current permission catalog and consent screen—never invent scope names. Step-up authorization cannot silently broaden prior consent.\n\n## Threat controls\n| Risk | Mandatory control |\n|---|---|\n| Prompt injection | Treat provider/web/database text as data; instructions in results cannot authorize calls or alter policy. |\n| Tool poisoning | Pin package/image and provenance; allowlist tools; diff descriptions/schemas on change before activation. |\n| Exfiltration | Enforce tenant/object allowlists, DLP/redaction, egress policy, response caps, and approval for cross-boundary transfer. |\n| SSRF | Fixed provider origins, DNS/IP checks, redirect revalidation, private/link-local denial, and no arbitrary URL fetch tool. |\n| Unsafe writes | Policy plus provider authorization, exact-argument approval, concurrency checks, idempotency key where supported, and no blind retry. |\n\n## Operations, tenancy, and incidents\nRate-limit against Slack method-tier headers and `Retry-After`; no guessed fixed quota. Do not claim a fixed limit where the provider makes limits endpoint-, plan-, or tenant-dependent. Apply budgets per user/tenant/tool, bounded jittered backoff for idempotent reads, circuit breaking, and surfaced retry times.\n\nEmit OpenTelemetry metrics/spans for tool, tenant hash, status, latency, bytes, pagination, approval ID, provider request ID, and rate-limit state; never record tokens or raw content. Partition credentials, caches, cursors, browser/database sessions, telemetry, and audit records by Enterprise Grid organization/workspace/channel. Re-authorize on tenant change.\n\nRevocation disables the grant immediately, removes provider credentials, terminates sessions, and evicts credential-bound caches. Incident response: disable risky tools, revoke/rotate credentials, preserve tamper-evident audit evidence, identify tenants/calls/data, contain egress, notify owners under policy, patch and adversarially retest before staged restoration.\n\n## Verification\n- Contract-test initialization/version failure, capability declarations/change, schemas, pagination, cancellation, errors, and output caps.\n- Test RFC 9728 discovery, PKCE downgrade refusal, RFC 8707 resource binding, issuer/audience/expiry rejection, no token passthrough, consent, revocation, and tenant isolation.\n- Attack-test injected content, poisoned tool metadata, DNS rebinding/redirect SSRF, oversized/secret output, confused deputy, approval replay, cross-tenant cursors, and rate-limit exhaustion.\n- Test read and write paths in a disposable tenant; prove provider authorization and rollback/compensation behavior.\n\n## Tradeoffs\nSearch is powerful but increases exposure of conversational and regulated data. Least-privilege tool selection reduces agent flexibility and requires ongoing permission and schema maintenance.\n\n## Anti-patterns\n- Broad administrator credentials, undocumented scopes/quotas, shared cross-tenant sessions, or secrets in config/logs.\n- Exposing the provider API one-for-one, enabling all tools, trusting returned instructions, or treating model confirmation as durable approval.\n- Retrying writes after ambiguous failure, accepting arbitrary URLs/queries/paths, or logging complete payloads.\n\n## Enterprise considerations\nEnforce Slack Enterprise Grid SAML/SCIM, approved-app policy, channel and Slack Connect controls, Enterprise Key Management where required, audit-log export, legal holds, retention, and residency. Enforce separation of duties, legal hold and accessibility requirements where applicable; pin releases, verify provenance/SBOMs, stage upgrades, and document RTO/RPO plus outage behavior.\n\n## Checklist\n- [ ] Implementation and transports approved; MCP negotiation and capability change tested\n- [ ] Tools/resources/prompts bounded; input/output validation and write approvals enforced\n- [ ] RFC 9728, PKCE S256, RFC 8707, issuer/audience validation, consent, and least privilege verified\n- [ ] No token passthrough; injection, exfiltration, SSRF, and tool-poisoning defenses tested\n- [ ] Provider-aware limits, redacted telemetry, tenancy, revocation, and incident runbook operational\n- [ ] Tradeoffs, enterprise controls, contract/integration/adversarial tests accepted\n\n## Primary references\n- [Slack implementation/API](https://docs.slack.dev/ai/mcp-server/)\n- [Slack limits/security](https://docs.slack.dev/apis/web-api/rate-limits/)\n- [MCP specification `2025-11-25`](https://modelcontextprotocol.io/specification/2025-11-25/)\n- [MCP authorization](https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization)\n\n## Changelog\n- **1.1 — 2026-07-16:** Replaced a template marker with concrete service-specific enterprise controls.\n- **1.0 — 2026-07-16:** Initial production specification.\n",
   "mcps/communication/microsoft-teams.mcp.md": "# Microsoft Teams MCP Integration\n\n> **Version:** 1.1 | **Updated:** 2026-07-16 | **Category:** Communication\n\n## Purpose and applicability\nProvide agent-safe access to teams, channels, chats, messages, meetings. Use this integration only when those capabilities are required and a named owner accepts the data and write risk. The implementation baseline is a controlled MCP adapter over Microsoft Graph; Microsoft publishes Graph APIs, not a universal Teams MCP package assumed by this standard.\n\n## Protocol, transport, and capability lifecycle\nImplement stable MCP `2025-11-25`. Negotiate `protocolVersion` in `initialize`; reject unsupported versions. Prefer Streamable HTTP for remote service and `stdio` only for a local, single-user process; do not expose `stdio` through a network shim. Advertise only implemented `tools`, `resources`, `prompts`, and `logging`. Paginate lists, use progress/cancellation where supported, and send the corresponding `list_changed` notification after authorization or configuration changes. Clients re-list and review metadata changes before use.\n\n## Tool, resource, and prompt design\n- **Tools:** bounded list/get/search operations over teams, channels, chats, messages, meetings; mutations are separate, disabled by default, idempotency-aware, and approval-gated.\n- **Resources:** canonical read-only URIs scoped to Entra tenant/team/channel; stable IDs and versions replace display names where possible.\n- **Prompts:** vendor-specific triage/review prompts return instructions and resource links only; prompts never silently invoke tools.\n- **Validation:** closed JSON Schemas; normalize and authorize tenant/team/channel/chat IDs and message size; cap arrays, strings, time ranges, rows, bytes, and pagination. Return typed, size-bounded results with opaque cursors and structured errors. Label all provider content untrusted and redact credentials, secrets, personal data, and internal URLs.\n\n## Authorization, consent, and least privilege\nRemote deployments publish RFC 9728 Protected Resource Metadata and standards-compliant `WWW-Authenticate`. Discover the authorization server from metadata, require authorization code flow with PKCE `S256`, verify advertised PKCE support, and include the canonical MCP URI as RFC 8707 `resource` in authorization and token requests. Validate token signature, issuer, expiry/not-before, authorized party when applicable, and audience/resource for this server.\n\nNever pass an inbound MCP bearer token to the provider. Exchange/map it server-side to a short-lived, tenant-bound provider credential. Consent names the provider, tenant, enabled tools, data classes, and write effects. Use Microsoft Entra delegated consent and Teams/Graph authorization; rely on the provider's current permission catalog and consent screen—never invent scope names. Step-up authorization cannot silently broaden prior consent.\n\n## Threat controls\n| Risk | Mandatory control |\n|---|---|\n| Prompt injection | Treat provider/web/database text as data; instructions in results cannot authorize calls or alter policy. |\n| Tool poisoning | Pin package/image and provenance; allowlist tools; diff descriptions/schemas on change before activation. |\n| Exfiltration | Enforce tenant/object allowlists, DLP/redaction, egress policy, response caps, and approval for cross-boundary transfer. |\n| SSRF | Fixed provider origins, DNS/IP checks, redirect revalidation, private/link-local denial, and no arbitrary URL fetch tool. |\n| Unsafe writes | Policy plus provider authorization, exact-argument approval, concurrency checks, idempotency key where supported, and no blind retry. |\n\n## Operations, tenancy, and incidents\nRate-limit against Microsoft Graph `Retry-After` and throttling guidance. Do not claim a fixed limit where the provider makes limits endpoint-, plan-, or tenant-dependent. Apply budgets per user/tenant/tool, bounded jittered backoff for idempotent reads, circuit breaking, and surfaced retry times.\n\nEmit OpenTelemetry metrics/spans for tool, tenant hash, status, latency, bytes, pagination, approval ID, provider request ID, and rate-limit state; never record tokens or raw content. Partition credentials, caches, cursors, browser/database sessions, telemetry, and audit records by Entra tenant/team/channel. Re-authorize on tenant change.\n\nRevocation disables the grant immediately, removes provider credentials, terminates sessions, and evicts credential-bound caches. Incident response: disable risky tools, revoke/rotate credentials, preserve tamper-evident audit evidence, identify tenants/calls/data, contain egress, notify owners under policy, patch and adversarially retest before staged restoration.\n\n## Verification\n- Contract-test initialization/version failure, capability declarations/change, schemas, pagination, cancellation, errors, and output caps.\n- Test RFC 9728 discovery, PKCE downgrade refusal, RFC 8707 resource binding, issuer/audience/expiry rejection, no token passthrough, consent, revocation, and tenant isolation.\n- Attack-test injected content, poisoned tool metadata, DNS rebinding/redirect SSRF, oversized/secret output, confused deputy, approval replay, cross-tenant cursors, and rate-limit exhaustion.\n- Test read and write paths in a disposable tenant; prove provider authorization and rollback/compensation behavior.\n\n## Tradeoffs\nA custom adapter gives policy control but owns Graph API and MCP lifecycle drift. Least-privilege tool selection reduces agent flexibility and requires ongoing permission and schema maintenance.\n\n## Anti-patterns\n- Broad administrator credentials, undocumented scopes/quotas, shared cross-tenant sessions, or secrets in config/logs.\n- Exposing the provider API one-for-one, enabling all tools, trusting returned instructions, or treating model confirmation as durable approval.\n- Retrying writes after ambiguous failure, accepting arbitrary URLs/queries/paths, or logging complete payloads.\n\n## Enterprise considerations\nEnforce Microsoft Entra Conditional Access and PIM, Teams app permission policies, sensitivity labels, information barriers, Purview DLP/eDiscovery/retention, audit export, and Multi-Geo residency. Enforce separation of duties, legal hold and accessibility requirements where applicable; pin releases, verify provenance/SBOMs, stage upgrades, and document RTO/RPO plus outage behavior.\n\n## Checklist\n- [ ] Implementation and transports approved; MCP negotiation and capability change tested\n- [ ] Tools/resources/prompts bounded; input/output validation and write approvals enforced\n- [ ] RFC 9728, PKCE S256, RFC 8707, issuer/audience validation, consent, and least privilege verified\n- [ ] No token passthrough; injection, exfiltration, SSRF, and tool-poisoning defenses tested\n- [ ] Provider-aware limits, redacted telemetry, tenancy, revocation, and incident runbook operational\n- [ ] Tradeoffs, enterprise controls, contract/integration/adversarial tests accepted\n\n## Primary references\n- [Microsoft Teams implementation/API](https://learn.microsoft.com/en-us/graph/teams-concept-overview)\n- [Microsoft Teams limits/security](https://learn.microsoft.com/en-us/graph/throttling)\n- [MCP specification `2025-11-25`](https://modelcontextprotocol.io/specification/2025-11-25/)\n- [MCP authorization](https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization)\n\n## Changelog\n- **1.1 — 2026-07-16:** Replaced a template marker with concrete service-specific enterprise controls.\n- **1.0 — 2026-07-16:** Initial production specification.\n",
-  "mcps/communication/discord.mcp.md": "# Discord MCP Integration\n\n> **Version:** 1.1 | **Updated:** 2026-07-16 | **Category:** Communication\n\n## Purpose and applicability\nProvide agent-safe access to guilds, channels, threads, messages. Use this integration only when those capabilities are required and a named owner accepts the data and write risk. The implementation baseline is a reviewed adapter over Discord's official API; do not represent community servers as Discord-official.\n\n## Protocol, transport, and capability lifecycle\nImplement stable MCP `2025-11-25`. Negotiate `protocolVersion` in `initialize`; reject unsupported versions. Prefer Streamable HTTP for remote service and `stdio` only for a local, single-user process; do not expose `stdio` through a network shim. Advertise only implemented `tools`, `resources`, `prompts`, and `logging`. Paginate lists, use progress/cancellation where supported, and send the corresponding `list_changed` notification after authorization or configuration changes. Clients re-list and review metadata changes before use.\n\n## Tool, resource, and prompt design\n- **Tools:** bounded list/get/search operations over guilds, channels, threads, messages; mutations are separate, disabled by default, idempotency-aware, and approval-gated.\n- **Resources:** canonical read-only URIs scoped to application/guild/channel; stable IDs and versions replace display names where possible.\n- **Prompts:** vendor-specific triage/review prompts return instructions and resource links only; prompts never silently invoke tools.\n- **Validation:** closed JSON Schemas; normalize and authorize snowflake IDs, allowed guilds/channels, message length; cap arrays, strings, time ranges, rows, bytes, and pagination. Return typed, size-bounded results with opaque cursors and structured errors. Label all provider content untrusted and redact credentials, secrets, personal data, and internal URLs.\n\n## Authorization, consent, and least privilege\nRemote deployments publish RFC 9728 Protected Resource Metadata and standards-compliant `WWW-Authenticate`. Discover the authorization server from metadata, require authorization code flow with PKCE `S256`, verify advertised PKCE support, and include the canonical MCP URI as RFC 8707 `resource` in authorization and token requests. Validate token signature, issuer, expiry/not-before, authorized party when applicable, and audience/resource for this server.\n\nNever pass an inbound MCP bearer token to the provider. Exchange/map it server-side to a short-lived, tenant-bound provider credential. Consent names the provider, tenant, enabled tools, data classes, and write effects. Use Discord OAuth2/bot installation consent and guild permissions; rely on the provider's current permission catalog and consent screen—never invent scope names. Step-up authorization cannot silently broaden prior consent.\n\n## Threat controls\n| Risk | Mandatory control |\n|---|---|\n| Prompt injection | Treat provider/web/database text as data; instructions in results cannot authorize calls or alter policy. |\n| Tool poisoning | Pin package/image and provenance; allowlist tools; diff descriptions/schemas on change before activation. |\n| Exfiltration | Enforce tenant/object allowlists, DLP/redaction, egress policy, response caps, and approval for cross-boundary transfer. |\n| SSRF | Fixed provider origins, DNS/IP checks, redirect revalidation, private/link-local denial, and no arbitrary URL fetch tool. |\n| Unsafe writes | Policy plus provider authorization, exact-argument approval, concurrency checks, idempotency key where supported, and no blind retry. |\n\n## Operations, tenancy, and incidents\nRate-limit against Discord route/bucket headers and global-limit signals. Do not claim a fixed limit where the provider makes limits endpoint-, plan-, or tenant-dependent. Apply budgets per user/tenant/tool, bounded jittered backoff for idempotent reads, circuit breaking, and surfaced retry times.\n\nEmit OpenTelemetry metrics/spans for tool, tenant hash, status, latency, bytes, pagination, approval ID, provider request ID, and rate-limit state; never record tokens or raw content. Partition credentials, caches, cursors, browser/database sessions, telemetry, and audit records by application/guild/channel. Re-authorize on tenant change.\n\nRevocation disables the grant immediately, removes provider credentials, terminates sessions, and evicts credential-bound caches. Incident response: disable risky tools, revoke/rotate credentials, preserve tamper-evident audit evidence, identify tenants/calls/data, contain egress, notify owners under policy, patch and adversarially retest before staged restoration.\n\n## Verification\n- Contract-test initialization/version failure, capability declarations/change, schemas, pagination, cancellation, errors, and output caps.\n- Test RFC 9728 discovery, PKCE downgrade refusal, RFC 8707 resource binding, issuer/audience/expiry rejection, no token passthrough, consent, revocation, and tenant isolation.\n- Attack-test injected content, poisoned tool metadata, DNS rebinding/redirect SSRF, oversized/secret output, confused deputy, approval replay, cross-tenant cursors, and rate-limit exhaustion.\n- Test read and write paths in a disposable tenant; prove provider authorization and rollback/compensation behavior.\n\n## Tradeoffs\nBot permissions are granular, but community content creates a high injection risk. Least-privilege tool selection reduces agent flexibility and requires ongoing permission and schema maintenance.\n\n## Anti-patterns\n- Broad administrator credentials, undocumented scopes/quotas, shared cross-tenant sessions, or secrets in config/logs.\n- Exposing the provider API one-for-one, enabling all tools, trusting returned instructions, or treating model confirmation as durable approval.\n- Retrying writes after ambiguous failure, accepting arbitrary URLs/queries/paths, or logging complete payloads.\n\n## Enterprise considerations\nEnforce managed bot ownership, guild and channel allowlists, role separation, installation approval, AutoMod and moderation escalation, audit-log retention, and prohibition for regulated records unless governance requirements are met. Enforce separation of duties, legal hold and accessibility requirements where applicable; pin releases, verify provenance/SBOMs, stage upgrades, and document RTO/RPO plus outage behavior.\n\n## Checklist\n- [ ] Implementation and transports approved; MCP negotiation and capability change tested\n- [ ] Tools/resources/prompts bounded; input/output validation and write approvals enforced\n- [ ] RFC 9728, PKCE S256, RFC 8707, issuer/audience validation, consent, and least privilege verified\n- [ ] No token passthrough; injection, exfiltration, SSRF, and tool-poisoning defenses tested\n- [ ] Provider-aware limits, redacted telemetry, tenancy, revocation, and incident runbook operational\n- [ ] Tradeoffs, enterprise controls, contract/integration/adversarial tests accepted\n\n## Primary references\n- [Discord implementation/API](https://discord.com/developers/docs/topics/oauth2)\n- [Discord limits/security](https://discord.com/developers/docs/topics/rate-limits)\n- [MCP specification `2025-11-25`](https://modelcontextprotocol.io/specification/2025-11-25/)\n- [MCP authorization](https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization)\n\n## Changelog\n- **1.1 — 2026-07-16:** Replaced a template marker with concrete service-specific enterprise controls.\n- **1.0 — 2026-07-16:** Initial production specification.\n"
+  "mcps/communication/discord.mcp.md": "# Discord MCP Integration\n\n> **Version:** 1.1 | **Updated:** 2026-07-16 | **Category:** Communication\n\n## Purpose and applicability\nProvide agent-safe access to guilds, channels, threads, messages. Use this integration only when those capabilities are required and a named owner accepts the data and write risk. The implementation baseline is a reviewed adapter over Discord's official API; do not represent community servers as Discord-official.\n\n## Protocol, transport, and capability lifecycle\nImplement stable MCP `2025-11-25`. Negotiate `protocolVersion` in `initialize`; reject unsupported versions. Prefer Streamable HTTP for remote service and `stdio` only for a local, single-user process; do not expose `stdio` through a network shim. Advertise only implemented `tools`, `resources`, `prompts`, and `logging`. Paginate lists, use progress/cancellation where supported, and send the corresponding `list_changed` notification after authorization or configuration changes. Clients re-list and review metadata changes before use.\n\n## Tool, resource, and prompt design\n- **Tools:** bounded list/get/search operations over guilds, channels, threads, messages; mutations are separate, disabled by default, idempotency-aware, and approval-gated.\n- **Resources:** canonical read-only URIs scoped to application/guild/channel; stable IDs and versions replace display names where possible.\n- **Prompts:** vendor-specific triage/review prompts return instructions and resource links only; prompts never silently invoke tools.\n- **Validation:** closed JSON Schemas; normalize and authorize snowflake IDs, allowed guilds/channels, message length; cap arrays, strings, time ranges, rows, bytes, and pagination. Return typed, size-bounded results with opaque cursors and structured errors. Label all provider content untrusted and redact credentials, secrets, personal data, and internal URLs.\n\n## Authorization, consent, and least privilege\nRemote deployments publish RFC 9728 Protected Resource Metadata and standards-compliant `WWW-Authenticate`. Discover the authorization server from metadata, require authorization code flow with PKCE `S256`, verify advertised PKCE support, and include the canonical MCP URI as RFC 8707 `resource` in authorization and token requests. Validate token signature, issuer, expiry/not-before, authorized party when applicable, and audience/resource for this server.\n\nNever pass an inbound MCP bearer token to the provider. Exchange/map it server-side to a short-lived, tenant-bound provider credential. Consent names the provider, tenant, enabled tools, data classes, and write effects. Use Discord OAuth2/bot installation consent and guild permissions; rely on the provider's current permission catalog and consent screen—never invent scope names. Step-up authorization cannot silently broaden prior consent.\n\n## Threat controls\n| Risk | Mandatory control |\n|---|---|\n| Prompt injection | Treat provider/web/database text as data; instructions in results cannot authorize calls or alter policy. |\n| Tool poisoning | Pin package/image and provenance; allowlist tools; diff descriptions/schemas on change before activation. |\n| Exfiltration | Enforce tenant/object allowlists, DLP/redaction, egress policy, response caps, and approval for cross-boundary transfer. |\n| SSRF | Fixed provider origins, DNS/IP checks, redirect revalidation, private/link-local denial, and no arbitrary URL fetch tool. |\n| Unsafe writes | Policy plus provider authorization, exact-argument approval, concurrency checks, idempotency key where supported, and no blind retry. |\n\n## Operations, tenancy, and incidents\nRate-limit against Discord route/bucket headers and global-limit signals. Do not claim a fixed limit where the provider makes limits endpoint-, plan-, or tenant-dependent. Apply budgets per user/tenant/tool, bounded jittered backoff for idempotent reads, circuit breaking, and surfaced retry times.\n\nEmit OpenTelemetry metrics/spans for tool, tenant hash, status, latency, bytes, pagination, approval ID, provider request ID, and rate-limit state; never record tokens or raw content. Partition credentials, caches, cursors, browser/database sessions, telemetry, and audit records by application/guild/channel. Re-authorize on tenant change.\n\nRevocation disables the grant immediately, removes provider credentials, terminates sessions, and evicts credential-bound caches. Incident response: disable risky tools, revoke/rotate credentials, preserve tamper-evident audit evidence, identify tenants/calls/data, contain egress, notify owners under policy, patch and adversarially retest before staged restoration.\n\n## Verification\n- Contract-test initialization/version failure, capability declarations/change, schemas, pagination, cancellation, errors, and output caps.\n- Test RFC 9728 discovery, PKCE downgrade refusal, RFC 8707 resource binding, issuer/audience/expiry rejection, no token passthrough, consent, revocation, and tenant isolation.\n- Attack-test injected content, poisoned tool metadata, DNS rebinding/redirect SSRF, oversized/secret output, confused deputy, approval replay, cross-tenant cursors, and rate-limit exhaustion.\n- Test read and write paths in a disposable tenant; prove provider authorization and rollback/compensation behavior.\n\n## Tradeoffs\nBot permissions are granular, but community content creates a high injection risk. Least-privilege tool selection reduces agent flexibility and requires ongoing permission and schema maintenance.\n\n## Anti-patterns\n- Broad administrator credentials, undocumented scopes/quotas, shared cross-tenant sessions, or secrets in config/logs.\n- Exposing the provider API one-for-one, enabling all tools, trusting returned instructions, or treating model confirmation as durable approval.\n- Retrying writes after ambiguous failure, accepting arbitrary URLs/queries/paths, or logging complete payloads.\n\n## Enterprise considerations\nEnforce managed bot ownership, guild and channel allowlists, role separation, installation approval, AutoMod and moderation escalation, audit-log retention, and prohibition for regulated records unless governance requirements are met. Enforce separation of duties, legal hold and accessibility requirements where applicable; pin releases, verify provenance/SBOMs, stage upgrades, and document RTO/RPO plus outage behavior.\n\n## Checklist\n- [ ] Implementation and transports approved; MCP negotiation and capability change tested\n- [ ] Tools/resources/prompts bounded; input/output validation and write approvals enforced\n- [ ] RFC 9728, PKCE S256, RFC 8707, issuer/audience validation, consent, and least privilege verified\n- [ ] No token passthrough; injection, exfiltration, SSRF, and tool-poisoning defenses tested\n- [ ] Provider-aware limits, redacted telemetry, tenancy, revocation, and incident runbook operational\n- [ ] Tradeoffs, enterprise controls, contract/integration/adversarial tests accepted\n\n## Primary references\n- [Discord implementation/API](https://discord.com/developers/docs/topics/oauth2)\n- [Discord limits/security](https://discord.com/developers/docs/topics/rate-limits)\n- [MCP specification `2025-11-25`](https://modelcontextprotocol.io/specification/2025-11-25/)\n- [MCP authorization](https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization)\n\n## Changelog\n- **1.1 — 2026-07-16:** Replaced a template marker with concrete service-specific enterprise controls.\n- **1.0 — 2026-07-16:** Initial production specification.\n",
+  "hooks/pre-planning.hook.sh": "#!/bin/sh\nset -eu\nhook=\"pre-planning\"\ndry_run=0\ncase \"${1:-}\" in\n  \"\") ;;\n  --dry-run) dry_run=1 ;;\n  *) printf '%s\\n' \"$hook: usage: $0 [--dry-run]\" >&2; exit 64 ;;\nesac\nfail_usage() { printf '%s\\n' \"$hook: $*\" >&2; exit 64; }\nfail_data() { printf '%s\\n' \"$hook: $*\" >&2; exit 65; }\nfail_gate() { printf '%s\\n' \"$hook: $*\" >&2; exit 70; }\nrequire_file() {\n  [ -n \"$1\" ] || fail_usage \"$2 is required\"\n  [ -f \"$1\" ] && [ -r \"$1\" ] || fail_data \"$2 is not a readable regular file\"\n  [ -s \"$1\" ] || fail_data \"$2 is empty\"\n}\nrequirements=\"${OAIES_REQUIREMENTS_FILE:-}\"\nrequire_file \"$requirements\" \"OAIES_REQUIREMENTS_FILE\"\ngrep -q '[^[:space:]]' \"$requirements\" || fail_data \"requirements contain only whitespace\"\nif [ \"$dry_run\" -eq 1 ]; then\n  printf '%s\\n' \"$hook: dry-run validation passed\"\nelse\n  printf '%s\\n' \"$hook: gate passed\"\nfi\nexit 0\n",
+  "hooks/pre-code.hook.sh": "#!/bin/sh\nset -eu\nhook=\"pre-code\"\ndry_run=0\ncase \"${1:-}\" in\n  \"\") ;;\n  --dry-run) dry_run=1 ;;\n  *) printf '%s\\n' \"$hook: usage: $0 [--dry-run]\" >&2; exit 64 ;;\nesac\nfail_usage() { printf '%s\\n' \"$hook: $*\" >&2; exit 64; }\nfail_data() { printf '%s\\n' \"$hook: $*\" >&2; exit 65; }\nfail_gate() { printf '%s\\n' \"$hook: $*\" >&2; exit 70; }\nrequire_file() {\n  [ -n \"$1\" ] || fail_usage \"$2 is required\"\n  [ -f \"$1\" ] && [ -r \"$1\" ] || fail_data \"$2 is not a readable regular file\"\n  [ -s \"$1\" ] || fail_data \"$2 is empty\"\n}\nplan=\"${OAIES_PLAN_FILE:-}\"\napproval=\"${OAIES_APPROVAL_FILE:-}\"\nrequire_file \"$plan\" \"OAIES_PLAN_FILE\"\nrequire_file \"$approval\" \"OAIES_APPROVAL_FILE\"\ngrep -q '^effect=workspace-write$' \"$approval\" || fail_gate \"approval does not authorize workspace-write\"\ngrep -q '^target=' \"$approval\" || fail_data \"approval has no target\"\nif [ \"$dry_run\" -eq 1 ]; then\n  printf '%s\\n' \"$hook: dry-run validation passed\"\nelse\n  printf '%s\\n' \"$hook: gate passed\"\nfi\nexit 0\n",
+  "hooks/post-code.hook.sh": "#!/bin/sh\nset -eu\nhook=\"post-code\"\ndry_run=0\ncase \"${1:-}\" in\n  \"\") ;;\n  --dry-run) dry_run=1 ;;\n  *) printf '%s\\n' \"$hook: usage: $0 [--dry-run]\" >&2; exit 64 ;;\nesac\nfail_usage() { printf '%s\\n' \"$hook: $*\" >&2; exit 64; }\nfail_data() { printf '%s\\n' \"$hook: $*\" >&2; exit 65; }\nfail_gate() { printf '%s\\n' \"$hook: $*\" >&2; exit 70; }\nrequire_file() {\n  [ -n \"$1\" ] || fail_usage \"$2 is required\"\n  [ -f \"$1\" ] && [ -r \"$1\" ] || fail_data \"$2 is not a readable regular file\"\n  [ -s \"$1\" ] || fail_data \"$2 is empty\"\n}\nevidence=\"${OAIES_VERIFY_EVIDENCE:-}\"\nrequire_file \"$evidence\" \"OAIES_VERIFY_EVIDENCE\"\ngrep -q '^status=passed$' \"$evidence\" || fail_gate \"verification evidence is not passed\"\ngrep -q '^artifact=' \"$evidence\" || fail_data \"verification evidence has no artifact identifier\"\nif [ \"$dry_run\" -eq 1 ]; then\n  printf '%s\\n' \"$hook: dry-run validation passed\"\nelse\n  printf '%s\\n' \"$hook: gate passed\"\nfi\nexit 0\n",
+  "hooks/pre-commit.hook.sh": "#!/bin/sh\nset -eu\nhook=\"pre-commit\"\ndry_run=0\ncase \"${1:-}\" in\n  \"\") ;;\n  --dry-run) dry_run=1 ;;\n  *) printf '%s\\n' \"$hook: usage: $0 [--dry-run]\" >&2; exit 64 ;;\nesac\nfail_usage() { printf '%s\\n' \"$hook: $*\" >&2; exit 64; }\nfail_data() { printf '%s\\n' \"$hook: $*\" >&2; exit 65; }\nfail_gate() { printf '%s\\n' \"$hook: $*\" >&2; exit 70; }\nrequire_file() {\n  [ -n \"$1\" ] || fail_usage \"$2 is required\"\n  [ -f \"$1\" ] && [ -r \"$1\" ] || fail_data \"$2 is not a readable regular file\"\n  [ -s \"$1\" ] || fail_data \"$2 is empty\"\n}\ntests=\"${OAIES_TEST_EVIDENCE:-}\"\nsecrets=\"${OAIES_SECRET_SCAN_EVIDENCE:-}\"\nrequire_file \"$tests\" \"OAIES_TEST_EVIDENCE\"\nrequire_file \"$secrets\" \"OAIES_SECRET_SCAN_EVIDENCE\"\ngrep -q '^status=passed$' \"$tests\" || fail_gate \"test evidence is not passed\"\ngrep -q '^status=passed$' \"$secrets\" || fail_gate \"secret-scan evidence is not passed\"\nif [ \"$dry_run\" -eq 0 ]; then\n  git rev-parse --is-inside-work-tree >/dev/null 2>&1 || fail_data \"not inside a Git work tree\"\n  staged=$(git diff --cached --no-ext-diff --unified=0 --no-color 2>/dev/null) ||\n    fail_data \"cannot inspect staged diff\"\n  if printf '%s\\n' \"$staged\" | grep -Eq 'BEGIN (RSA |EC |DSA |OPENSSH )?PRIVATE KEY'; then\n    fail_gate \"staged diff contains a private-key header\"\n  fi\nfi\nif [ \"$dry_run\" -eq 1 ]; then\n  printf '%s\\n' \"$hook: dry-run validation passed\"\nelse\n  printf '%s\\n' \"$hook: gate passed\"\nfi\nexit 0\n",
+  "hooks/pre-review.hook.sh": "#!/bin/sh\nset -eu\nhook=\"pre-review\"\ndry_run=0\ncase \"${1:-}\" in\n  \"\") ;;\n  --dry-run) dry_run=1 ;;\n  *) printf '%s\\n' \"$hook: usage: $0 [--dry-run]\" >&2; exit 64 ;;\nesac\nfail_usage() { printf '%s\\n' \"$hook: $*\" >&2; exit 64; }\nfail_data() { printf '%s\\n' \"$hook: $*\" >&2; exit 65; }\nfail_gate() { printf '%s\\n' \"$hook: $*\" >&2; exit 70; }\nrequire_file() {\n  [ -n \"$1\" ] || fail_usage \"$2 is required\"\n  [ -f \"$1\" ] && [ -r \"$1\" ] || fail_data \"$2 is not a readable regular file\"\n  [ -s \"$1\" ] || fail_data \"$2 is empty\"\n}\nformat=\"${OAIES_FORMAT_EVIDENCE:-}\"\nlint=\"${OAIES_LINT_EVIDENCE:-}\"\nrequire_file \"$format\" \"OAIES_FORMAT_EVIDENCE\"\nrequire_file \"$lint\" \"OAIES_LINT_EVIDENCE\"\ngrep -q '^status=passed$' \"$format\" || fail_gate \"format evidence is not passed\"\ngrep -q '^status=passed$' \"$lint\" || fail_gate \"lint evidence is not passed\"\nif [ \"$dry_run\" -eq 1 ]; then\n  printf '%s\\n' \"$hook: dry-run validation passed\"\nelse\n  printf '%s\\n' \"$hook: gate passed\"\nfi\nexit 0\n",
+  "hooks/deployment.hook.sh": "#!/bin/sh\nset -eu\nhook=\"deployment\"\ndry_run=0\ncase \"${1:-}\" in\n  \"\") ;;\n  --dry-run) dry_run=1 ;;\n  *) printf '%s\\n' \"$hook: usage: $0 [--dry-run]\" >&2; exit 64 ;;\nesac\nfail_usage() { printf '%s\\n' \"$hook: $*\" >&2; exit 64; }\nfail_data() { printf '%s\\n' \"$hook: $*\" >&2; exit 65; }\nfail_gate() { printf '%s\\n' \"$hook: $*\" >&2; exit 70; }\nrequire_file() {\n  [ -n \"$1\" ] || fail_usage \"$2 is required\"\n  [ -f \"$1\" ] && [ -r \"$1\" ] || fail_data \"$2 is not a readable regular file\"\n  [ -s \"$1\" ] || fail_data \"$2 is empty\"\n}\nmanifest=\"${OAIES_RELEASE_MANIFEST:-}\"\napproval=\"${OAIES_APPROVAL_FILE:-}\"\nevidence=\"${OAIES_RELEASE_EVIDENCE:-}\"\nrequire_file \"$manifest\" \"OAIES_RELEASE_MANIFEST\"\nrequire_file \"$approval\" \"OAIES_APPROVAL_FILE\"\nrequire_file \"$evidence\" \"OAIES_RELEASE_EVIDENCE\"\ngrep -q '^artifact_digest=' \"$manifest\" || fail_data \"manifest has no artifact_digest\"\ngrep -q '^environment=' \"$manifest\" || fail_data \"manifest has no environment\"\ngrep -q '^effect=deployment$' \"$approval\" || fail_gate \"approval does not authorize deployment\"\ngrep -q '^status=passed$' \"$evidence\" || fail_gate \"release evidence is not passed\"\nif [ \"$dry_run\" -eq 1 ]; then\n  printf '%s\\n' \"$hook: dry-run validation passed\"\nelse\n  printf '%s\\n' \"$hook: gate passed\"\nfi\nexit 0\n",
+  "hooks/knowledge-capture.hook.sh": "#!/bin/sh\nset -eu\nhook=\"knowledge-capture\"\ndry_run=0\ncase \"${1:-}\" in\n  \"\") ;;\n  --dry-run) dry_run=1 ;;\n  *) printf '%s\\n' \"$hook: usage: $0 [--dry-run]\" >&2; exit 64 ;;\nesac\nfail_usage() { printf '%s\\n' \"$hook: $*\" >&2; exit 64; }\nfail_data() { printf '%s\\n' \"$hook: $*\" >&2; exit 65; }\nfail_gate() { printf '%s\\n' \"$hook: $*\" >&2; exit 70; }\nrequire_file() {\n  [ -n \"$1\" ] || fail_usage \"$2 is required\"\n  [ -f \"$1\" ] && [ -r \"$1\" ] || fail_data \"$2 is not a readable regular file\"\n  [ -s \"$1\" ] || fail_data \"$2 is empty\"\n}\nrecord=\"${OAIES_KNOWLEDGE_FILE:-}\"\nrequire_file \"$record\" \"OAIES_KNOWLEDGE_FILE\"\ngrep -q '^owner=' \"$record\" || fail_data \"knowledge record has no owner\"\ngrep -q '^source=' \"$record\" || fail_data \"knowledge record has no source\"\ngrep -q '^retention=' \"$record\" || fail_data \"knowledge record has no retention\"\nif [ \"$dry_run\" -eq 1 ]; then\n  printf '%s\\n' \"$hook: dry-run validation passed\"\nelse\n  printf '%s\\n' \"$hook: gate passed\"\nfi\nexit 0\n",
+  "hooks/pre-tool-call.hook.sh": "#!/bin/sh\nset -eu\nhook=\"pre-tool-call\"\ndry_run=0\ncase \"${1:-}\" in\n  \"\") ;;\n  --dry-run) dry_run=1 ;;\n  *) printf '%s\\n' \"$hook: usage: $0 [--dry-run]\" >&2; exit 64 ;;\nesac\nfail_usage() { printf '%s\\n' \"$hook: $*\" >&2; exit 64; }\nfail_data() { printf '%s\\n' \"$hook: $*\" >&2; exit 65; }\nfail_gate() { printf '%s\\n' \"$hook: $*\" >&2; exit 70; }\nrequire_file() {\n  [ -n \"$1\" ] || fail_usage \"$2 is required\"\n  [ -f \"$1\" ] && [ -r \"$1\" ] || fail_data \"$2 is not a readable regular file\"\n  [ -s \"$1\" ] || fail_data \"$2 is empty\"\n}\neffect=\"${OAIES_TOOL_EFFECT:-}\"\n[ -n \"$effect\" ] || fail_usage \"OAIES_TOOL_EFFECT is required\"\ncase \"$effect\" in\n  read|search|verify|workspace-write) ;;\n  production-mutation|deployment|deletion|irreversible-migration|external-message|permission-change|new-spend)\n    approval=\"${OAIES_APPROVAL_FILE:-}\"\n    require_file \"$approval\" \"OAIES_APPROVAL_FILE\"\n    grep -q \"^effect=$effect$\" \"$approval\" || fail_gate \"approval does not match effect=$effect\"\n    grep -q '^target=' \"$approval\" || fail_data \"approval has no target\"\n    ;;\n  *) fail_data \"unknown effect classification: $effect\" ;;\nesac\nif [ \"$dry_run\" -eq 1 ]; then\n  printf '%s\\n' \"$hook: dry-run validation passed\"\nelse\n  printf '%s\\n' \"$hook: gate passed\"\nfi\nexit 0\n",
+  "hooks/post-tool-call.hook.sh": "#!/bin/sh\nset -eu\nhook=\"post-tool-call\"\ndry_run=0\ncase \"${1:-}\" in\n  \"\") ;;\n  --dry-run) dry_run=1 ;;\n  *) printf '%s\\n' \"$hook: usage: $0 [--dry-run]\" >&2; exit 64 ;;\nesac\nfail_usage() { printf '%s\\n' \"$hook: $*\" >&2; exit 64; }\nfail_data() { printf '%s\\n' \"$hook: $*\" >&2; exit 65; }\nfail_gate() { printf '%s\\n' \"$hook: $*\" >&2; exit 70; }\nrequire_file() {\n  [ -n \"$1\" ] || fail_usage \"$2 is required\"\n  [ -f \"$1\" ] && [ -r \"$1\" ] || fail_data \"$2 is not a readable regular file\"\n  [ -s \"$1\" ] || fail_data \"$2 is empty\"\n}\nresult=\"${OAIES_TOOL_RESULT_FILE:-}\"\nrequire_file \"$result\" \"OAIES_TOOL_RESULT_FILE\"\ngrep -q '^status=' \"$result\" || fail_data \"tool result has no status\"\ngrep -q '^effect=' \"$result\" || fail_data \"tool result has no effect\"\ngrep -q '^target=' \"$result\" || fail_data \"tool result has no target\"\nif [ \"$dry_run\" -eq 1 ]; then\n  printf '%s\\n' \"$hook: dry-run validation passed\"\nelse\n  printf '%s\\n' \"$hook: gate passed\"\nfi\nexit 0\n",
+  "hooks/pre-delegation.hook.sh": "#!/bin/sh\nset -eu\nhook=\"pre-delegation\"\ndry_run=0\ncase \"${1:-}\" in\n  \"\") ;;\n  --dry-run) dry_run=1 ;;\n  *) printf '%s\\n' \"$hook: usage: $0 [--dry-run]\" >&2; exit 64 ;;\nesac\nfail_usage() { printf '%s\\n' \"$hook: $*\" >&2; exit 64; }\nfail_data() { printf '%s\\n' \"$hook: $*\" >&2; exit 65; }\nfail_gate() { printf '%s\\n' \"$hook: $*\" >&2; exit 70; }\nrequire_file() {\n  [ -n \"$1\" ] || fail_usage \"$2 is required\"\n  [ -f \"$1\" ] && [ -r \"$1\" ] || fail_data \"$2 is not a readable regular file\"\n  [ -s \"$1\" ] || fail_data \"$2 is empty\"\n}\ndelegation=\"${OAIES_DELEGATION_FILE:-}\"\nrequire_file \"$delegation\" \"OAIES_DELEGATION_FILE\"\ngrep -q '^principal=' \"$delegation\" || fail_data \"delegation has no principal\"\ngrep -q '^scope=' \"$delegation\" || fail_data \"delegation has no scope\"\ngrep -q '^budget_profile=' \"$delegation\" || fail_data \"delegation has no budget_profile\"\ndepth=$(grep '^remaining_depth=' \"$delegation\" | sed 's/^remaining_depth=//' | sed -n '1p')\ncase \"$depth\" in \"\"|*[!0-9]*) fail_data \"remaining_depth must be a non-negative integer\" ;; esac\n[ \"$depth\" -gt 0 ] || fail_gate \"delegation depth exhausted\"\nif [ \"$dry_run\" -eq 1 ]; then\n  printf '%s\\n' \"$hook: dry-run validation passed\"\nelse\n  printf '%s\\n' \"$hook: gate passed\"\nfi\nexit 0\n",
+  "hooks/post-deployment.hook.sh": "#!/bin/sh\nset -eu\nhook=\"post-deployment\"\ndry_run=0\ncase \"${1:-}\" in\n  \"\") ;;\n  --dry-run) dry_run=1 ;;\n  *) printf '%s\\n' \"$hook: usage: $0 [--dry-run]\" >&2; exit 64 ;;\nesac\nfail_usage() { printf '%s\\n' \"$hook: $*\" >&2; exit 64; }\nfail_data() { printf '%s\\n' \"$hook: $*\" >&2; exit 65; }\nfail_gate() { printf '%s\\n' \"$hook: $*\" >&2; exit 70; }\nrequire_file() {\n  [ -n \"$1\" ] || fail_usage \"$2 is required\"\n  [ -f \"$1\" ] && [ -r \"$1\" ] || fail_data \"$2 is not a readable regular file\"\n  [ -s \"$1\" ] || fail_data \"$2 is empty\"\n}\nhealth=\"${OAIES_HEALTH_EVIDENCE:-}\"\nrequire_file \"$health\" \"OAIES_HEALTH_EVIDENCE\"\ngrep -q '^artifact_digest=' \"$health\" || fail_data \"health evidence has no artifact_digest\"\ngrep -q '^environment=' \"$health\" || fail_data \"health evidence has no environment\"\ngrep -q '^status=healthy$' \"$health\" || fail_gate \"deployment health is not healthy\"\nif [ \"$dry_run\" -eq 1 ]; then\n  printf '%s\\n' \"$hook: dry-run validation passed\"\nelse\n  printf '%s\\n' \"$hook: gate passed\"\nfi\nexit 0\n",
+  "hooks/budget-guard.hook.sh": "#!/bin/sh\nset -eu\nhook=\"budget-guard\"\ndry_run=0\ncase \"${1:-}\" in\n  \"\") ;;\n  --dry-run) dry_run=1 ;;\n  *) printf '%s\\n' \"$hook: usage: $0 [--dry-run]\" >&2; exit 64 ;;\nesac\nfail_usage() { printf '%s\\n' \"$hook: $*\" >&2; exit 64; }\nfail_data() { printf '%s\\n' \"$hook: $*\" >&2; exit 65; }\nfail_gate() { printf '%s\\n' \"$hook: $*\" >&2; exit 70; }\nrequire_file() {\n  [ -n \"$1\" ] || fail_usage \"$2 is required\"\n  [ -f \"$1\" ] && [ -r \"$1\" ] || fail_data \"$2 is not a readable regular file\"\n  [ -s \"$1\" ] || fail_data \"$2 is empty\"\n}\nremaining=\"${OAIES_BUDGET_REMAINING:-}\"\nprofile=\"${OAIES_BUDGET_PROFILE:-}\"\n[ -n \"$profile\" ] || fail_usage \"OAIES_BUDGET_PROFILE is required\"\ncase \"$remaining\" in \"\"|*[!0-9]*) fail_data \"OAIES_BUDGET_REMAINING must be a non-negative integer\" ;; esac\n[ \"$remaining\" -gt 0 ] || fail_gate \"budget profile $profile is exhausted\"\nif [ \"$dry_run\" -eq 1 ]; then\n  printf '%s\\n' \"$hook: dry-run validation passed\"\nelse\n  printf '%s\\n' \"$hook: gate passed\"\nfi\nexit 0\n"
 };

package/lib/kit-core/generate.js CHANGED Viewed

@@ -108,7 +108,7 @@ ${
 ## Non-negotiables
 1. Human review is accountable — model output is advisory
-2. Fill \`implementation_plan.md\` before multi-file coding
+2. Multi-file work uses approved \`plans/{STORY_ID}-plan.md\` (ephemeral)
 3. Keep \`mcpServers: {}\` until a human enables approved stubs
 4. Eval gates for AI-touched paths before production
@@ -119,27 +119,27 @@ Online: ${SITE_URL}/docs/handbook/mcp-when-and-how
 function maturityReadingPath(maturity) {
   if (maturity === 'beginner') {
     return `1. \`guides/skills-vs-prompts-vs-agents.md\` + \`guides/human-in-the-loop.md\`
-2. Fill \`implementation_plan.md\` using \`prompts/implementation-plan.prompt.md\`
-3. Run **enhance** (below) so artifacts match this repo
-4. Use cookbook generate → coding → review
+2. Run enhance (CLI + agent chat invoke in §0)
+3. Create \`plans/{STORY_ID}-plan.md\` from \`plans/_TEMPLATE.md\`
+4. Cookbook generate → coding → \`reviews/{STORY_ID}-code-review.md\`
 5. Online: ${SITE_URL}/docs/handbook/README`;
   }
   if (maturity === 'intermediate') {
-    return `1. Fill plan → enhance repo → cookbook generate/review
+    return `1. Enhance repo → ephemeral plan → cookbook generate/review
 2. Wire \`guides/evals-as-quality-gates.md\` into CI
-3. Enable MCP only from recommended stubs after review
+3. Use \`hooks/\` before commit; enable MCP only from recommended stubs
 4. Online: ${SITE_URL}/workflows`;
   }
   if (maturity === 'advanced') {
-    return `1. Enhance repo + MCP handbook
+    return `1. Enhance repo + MCP handbook + agent hooks
 2. Compose agents (planner → coder → reviewer) with budgets
-3. Security skill before write tools
+3. Security skill before write tools; story-scoped plans/reviews
 4. Online: ${SITE_URL}/docs/04-agent-engineering/README`;
   }
   return `1. Enhance repo + SoA mapping (${SITE_URL}/portal)
 2. Migration bible: ${SITE_URL}/docs/handbook/ai-migration-bible-path
-3. Eval CI + MCP allowlists + segregation of duties
-4. Enterprise evidence retained on PRs`;
+3. Eval CI + MCP allowlists + hooks + segregation of duties
+4. Attach \`plans/{STORY_ID}-plan.md\` + \`reviews/{STORY_ID}-code-review.md\` on PRs — then stop maintaining them`;
 }
 function roleNext(role) {
@@ -174,6 +174,8 @@ function skillPath(L, name) {
 }
 function buildRootInstructions(profile, label, L) {
+  const enhancePrompt = `${L.promptsDir}/enhance-repo.prompt.md`;
+  const enhanceChat = invokeEnhanceChat(profile.ide, enhancePrompt);
   return `# AIES project instructions — ${label}
 This repository uses the **AI Engineering Standard (AIES)** harness.
@@ -190,37 +192,49 @@ This repository uses the **AI Engineering Standard (AIES)** harness.
 ## Non-negotiables
 1. Read \`AIES.md\` before coding with AI
-2. Fill and approve \`implementation_plan.md\` before multi-file changes
+2. Multi-file work requires approved \`plans/{STORY_ID}-plan.md\` (ephemeral — not a forever root plan)
 3. Prefer installed skills/prompts/cookbook over ad-hoc chat
-4. Human owns merges — AI is advisory
+4. Human owns merges — AI is advisory; write \`reviews/{STORY_ID}-code-review.md\` on AI-touched PRs
 5. No secrets in prompts, logs, or MCP args
 6. Keep MCP \`mcpServers\` empty until a human enables stubs from \`_aiesRecommended\`
+7. Respect this repo’s lint, typecheck, format, and style-guide configs — never weaken them
+8. Honor agent hooks under \`hooks/\` for plan/code/review gates
 ## Where to look
 | Need | Path |
 |------|------|
 | Operator guide | \`AIES.md\` |
-| Plan of record | \`implementation_plan.md\` |
+| Plan index | \`implementation_plan.md\` |
+| Active plan | \`plans/{STORY_ID}-plan.md\` |
+| Review report | \`reviews/{STORY_ID}-code-review.md\` |
+| Agent hooks | \`hooks/\` · \`${L.hooksFile}\` |
 | Skills | \`${L.skillsDir}/\` |
 | Prompts | \`${L.promptsDir}/\` |
-| Stack cookbook | \`${L.cookbookDir}/\` |
 | Agents | \`${L.agentsDir}/\` |
+| Stack cookbook | \`${L.cookbookDir}/\` (repo root) |
 | MCP specs | \`${L.mcpsDir}/\` |
 | MCP config | \`${L.mcpFile}\` |
+| Guides | \`${L.guidesDir}/\` |
 | Policy | \`${L.policyFile}\` |
+**Layout rule:** IDE folders hold **prompts, skills, and agents** only. Cookbook/guides/mcps/templates stay at repo root.
 ## First commands after install
 \`\`\`bash
 npx @grvmithas/create-aies-kit enhance
 \`\`\`
-Then open \`${L.promptsDir}/enhance-repo.prompt.md\` in your IDE agent and run it against this repo.
+Then paste into agent chat:
+\`\`\`text
+${enhanceChat}
+\`\`\`
 ## Workflow
-Plan (\`implementation-plan\`) → Enhance → Cookbook generate → Coding → Review → Security (as needed)
+Enhance → \`plans/{STORY_ID}-plan.md\` (approve) → coding with plan attached → verify (lint/test) → \`reviews/{STORY_ID}-code-review.md\` → PR
 `;
 }
@@ -235,27 +249,31 @@ function buildAiesReadme({ profile, label, L, stack, flags, now, recommendedIds
 **Profile:** ${profile.role} · ${profile.ide} · ${profile.maturity} · ${label} · model **${model}** · data **${dataClass}**
 This install is **always complete**. Maturity only changes the reading path — not which files were written.
-There is **no** \`.aies/\` folder. Artifacts live in IDE-native paths plus root instruction files.
+There is **no** \`.aies/\` folder.
+**IDE folders** hold prompts, skills, and agents. **Cookbook, guides, MCP specs, and templates** live at repo root (never under \`.github/cookbook\`).
 ---
 ## 0. Start from the word go (do this first)
 1. **Read this file** (AIES.md).
-2. **Enhance for *this* repo** (adapts skills/prompts/MCP/rules to your conventions):
+2. **Refresh kit signals** (MCP recommendations from repo scan):
 \`\`\`bash
 npx @grvmithas/create-aies-kit enhance
 \`\`\`
-3. In your IDE agent, open and run:
+3. **Run the enhance prompt in your IDE agent chat** (copy-paste):
-\`${enhancePrompt}\`
+\`\`\`text
+${invokeEnhanceChat(profile.ide, enhancePrompt)}
+\`\`\`
-That prompt scans the repo and upgrades installed artifacts (and may create new files) so you can develop immediately.
+Prompt path: \`${enhancePrompt}\`
+That scan rewrites harness files to match **this** repo’s lint, style guides, FE/BE layout, and guardrails.
-4. Fill \`implementation_plan.md\` (see §1) and get human approval.
-5. Use the right prompt + skill (§2–§3), then code.
+4. Create an **ephemeral** plan: \`plans/{STORY_ID}-plan.md\` (see §1) — approve before multi-file coding.
+5. Code with the plan attached → write \`reviews/{STORY_ID}-code-review.md\` → open PR with both attached.
 **Re-install kit (force):**
@@ -265,25 +283,34 @@ npx @grvmithas/create-aies-kit ${flags} --force
 ---
-## 1. How to create and use \`implementation_plan.md\`
+## 1. Ephemeral plans & review reports (not forever-docs)
+**Plans and review reports are temporary.** Scope ends when the story/PR completes. Keeping a single living \`implementation_plan.md\` forever is an anti-pattern.
-### Create / fill
+| Artifact | Path | After merge |
+|----------|------|-------------|
+| Plan | \`plans/{STORY_ID}-plan.md\` | Attach to PR; archive or delete — **do not maintain** |
+| Code review | \`reviews/{STORY_ID}-code-review.md\` | Attach to PR; freeze — file issues for leftovers |
+| Index only | \`implementation_plan.md\` | Points here — not the active plan |
-1. Open root \`implementation_plan.md\`.
-2. Attach \`${L.promptsDir}/implementation-plan.prompt.md\` in chat (or run the **planning** skill).
-3. Also load \`${L.guidesDir}/how-to-set-up-planning.md\`.
-4. Fill: Goal, In/Out of scope, Tasks with verification, Risks, Rollback, Human approval.
+### Create / fill a plan
-### Use
+1. Copy \`plans/_TEMPLATE.md\` → \`plans/{STORY_ID}-plan.md\`
+2. Attach \`${L.promptsDir}/implementation-plan.prompt.md\` (or planning skill)
+3. Fill tasks with verification commands from **this** repo (see enhance output)
+4. Human approval before multi-file coding
-- **Before** any multi-file AI coding: plan must be filled and approved.
-- Attach the plan file in every coding session for that slice.
-- Update the plan when scope changes — do not silently expand.
+### Temporary memory
+- Attach the plan file every agent turn for that story
+- Optional sticky/context include by \`STORY_ID\`
+- Never dump the full plan into forever rules (\`CLAUDE.md\` / \`AGENTS.md\`)
 ### Anti-patterns
-- Coding from a chat transcript with no plan file
-- Approving your own high-risk plan without a second human when policy requires it
+- Forever-editing one root plan for every feature
+- Coding multi-file work from chat with no \`plans/{STORY_ID}-plan.md\`
+- Skipping \`reviews/{STORY_ID}-code-review.md\` on AI-touched PRs
 ---
@@ -295,7 +322,7 @@ npx @grvmithas/create-aies-kit ${flags} --force
 | Build the plan | \`${L.promptsDir}/implementation-plan.prompt.md\` |
 | Implement approved plan | \`${L.promptsDir}/coding.prompt.md\` |
 | Security pass | \`${L.promptsDir}/security-review.prompt.md\` |
-| Adapt harness to this repo | \`${enhancePrompt}\` |
+| Adapt harness to this repo | \`${enhancePrompt}\` — see §0 chat invoke |
 | Author a new prompt | \`${L.promptsDir}/create-prompt.prompt.md\` |
 | Author a new skill | \`${L.promptsDir}/create-skill.prompt.md\` |
 | Author a new agent | \`${L.promptsDir}/create-agent.prompt.md\` |
@@ -340,7 +367,18 @@ Compose agents; do not give them merge authority.
 ---
-## 5. MCP connections (relevant + safe)
+## 5. Agent hooks (evidence gates)
+Scripts: \`hooks/*.hook.sh\` · Operator notes: \`hooks/README.md\` · Full contract: \`hooks/CONTRACT.md\`
+Registry: \`${L.hooksFile}\`
+Use hooks so agents cannot skip plan approval, lint evidence, or high-effect tools. Wire evidence to **this repo’s** verify commands after enhance.
+Typical loop: \`plans/{STORY_ID}-plan.md\` → pre-code hook → coding → lint/test evidence → \`reviews/{STORY_ID}-code-review.md\` → pre-review/pre-commit → PR.
+---
+## 6. MCP connections (relevant + safe)
 Specs (all catalog entries shipped): \`${L.mcpsDir}/\`
 Config: \`${L.mcpFile}\`
@@ -354,7 +392,7 @@ Config: \`${L.mcpFile}\`
 ---
-## 6. Root instruction files (always present)
+## 7. Root instruction files (always present)
 | File | Role |
 |------|------|
@@ -366,32 +404,39 @@ Config: \`${L.mcpFile}\`
 ---
-## 7. Layout (${profile.ide})
+## 8. Layout (${profile.ide})
 | Path | Purpose |
 |------|---------|
 | \`AIES.md\` | This operator guide |
-| \`implementation_plan.md\` | Plan of record |
-| \`${L.skillsDir}/\` | Skills (complete) |
-| \`${L.promptsDir}/\` | AIDLC + create/enhance prompts |
-| \`${L.cookbookDir}/\` | Full stack cookbook |
-| \`${L.agentsDir}/\` | Agent definitions |
-| \`${L.mcpsDir}/\` | MCP integration specs |
-| \`${L.guidesDir}/\` | Handbook slices |
-| \`${L.templatesDir}/\` | System prompt template |
+| \`implementation_plan.md\` | Ephemeral-plan **index** (not the active plan) |
+| \`plans/{STORY_ID}-plan.md\` | Active plan — temporary |
+| \`reviews/{STORY_ID}-code-review.md\` | Review report — temporary |
+| \`hooks/\` | Agent evidence-gate scripts |
+| \`${L.hooksFile}\` | Hook registry (agentHooks) |
+| \`${L.promptsDir}/\` | AIDLC + create/enhance prompts (**IDE**) |
+| \`${L.skillsDir}/\` | Skills (**IDE**) |
+| \`${L.agentsDir}/\` | Agent definitions (**IDE**) |
+| \`${L.cookbookDir}/\` | Full stack cookbook (**repo root**) |
+| \`${L.guidesDir}/\` | Handbook slices (**repo root**) |
+| \`${L.mcpsDir}/\` | MCP integration specs (**repo root**) |
+| \`${L.templatesDir}/\` | System prompt template (**repo root**) |
+| \`${L.mcpFile}\` | MCP config (empty \`mcpServers\` by default) |
 | \`${L.policyFile}\` | Model + data policy |
+**Anti-pattern:** Do not nest cookbook/guides/mcps under \`.github\` — that folder is for Copilot discovery (instructions, prompts, skills, agents) and GitHub metadata only.
 ---
-## 8. Reading path (${profile.maturity})
+## 9. Reading path (${profile.maturity})
 ${maturityReadingPath(profile.maturity)}
-## 9. Role next workflow
+## 10. Role next workflow
 ${SITE_URL}/workflows/${roleNext(profile.role)}
-## 10. Online
+## 11. Online
 - Quick start: ${SITE_URL}/quickstart
 - Cookbook: ${SITE_URL}/docs/cookbook/${stack.cookbook ?? 'README'}/README
@@ -400,68 +445,123 @@ ${SITE_URL}/workflows/${roleNext(profile.role)}
 `;
 }
-function implementationPlanTemplate(promptsDir) {
-  return `# Implementation Plan
-> AIES plan of record. **Approve before multi-file coding.**
-> Author with \`${promptsDir}/implementation-plan.prompt.md\` + the planning skill.
-## Goal
-<!-- One sentence outcome -->
-## Context
-<!-- Links: tickets, ADRs, designs, prior PRs -->
-## Scope
-### In scope
--
-### Out of scope / non-goals
--
-## Tasks
-| ID | Task | Files / areas | Verification command or evidence | Owner | Done |
-|----|------|---------------|----------------------------------|-------|------|
-| 1 | | | | | [ ] |
-## Dependencies & sequencing
--
+function invokeEnhanceChat(ide, enhancePrompt) {
+  switch (ide) {
+    case 'cursor':
+      return `@${enhancePrompt} Scan this repo and enhance the AIES harness. Follow the XML instructions exactly.`;
+    case 'copilot':
+      return `#file:${enhancePrompt} Scan this repo and enhance the AIES harness. Follow the XML instructions exactly.`;
+    case 'claude-code':
+      return `Read ${enhancePrompt} and execute it against this repository.`;
+    default:
+      return `Open ${enhancePrompt} and execute it — scan first, then patch AIES artifacts only.`;
+  }
+}
-## Risks
+function implementationPlanIndex(promptsDir) {
+  return `# Implementation plans (ephemeral index)
-| Risk | Likelihood | Impact | Mitigation |
-|------|------------|--------|------------|
-| | | | |
+> **Not a living document.** Plans exist only for the duration of one story/task.
+> Maintaining a forever-updated root plan is an **anti-pattern**.
-## Rollback
+## Create a plan for this story
--
+1. Copy \`plans/_TEMPLATE.md\` → \`plans/{STORY_ID}-plan.md\`
+2. Fill it with \`${promptsDir}/implementation-plan.prompt.md\` + the planning skill
+3. Get human approval before multi-file coding
+4. **Attach** \`plans/{STORY_ID}-plan.md\` in every agent chat for that story
+5. Attach the plan to the PR; when the PR merges, **stop maintaining it** (archive or delete)
-## Test / eval plan
+## Naming
--
+| Artifact | Path |
+|----------|------|
+| Plan | \`plans/{STORY_ID}-plan.md\` |
+| Code review report | \`reviews/{STORY_ID}-code-review.md\` |
-## Human approval
+Examples: \`plans/JIRA-1234-plan.md\`, \`reviews/JIRA-1234-code-review.md\`
-- [ ] Plan reviewed for completeness and scope leakage
-- [ ] Approved by: _______________
-- [ ] Date: _______________
+## Temporary memory
-## Changelog
+- Prefer attaching the plan file each session (durable, reviewable)
+- Optional: IDE sticky/context include keyed by story id
+- Do **not** paste the full plan into \`CLAUDE.md\` / \`AGENTS.md\` / forever rules
-| Date | Change |
-|------|--------|
-| | Initial |
+See \`plans/README.md\` and \`reviews/README.md\`.
 `;
 }
+function agentHooksRegistry(L) {
+  return {
+    version: '2',
+    description: 'AIES agent hooks — evidence gates for AI-assisted development',
+    hooksDir: 'hooks',
+    artifacts: {
+      plan: 'plans/{STORY_ID}-plan.md',
+      review: 'reviews/{STORY_ID}-code-review.md',
+    },
+    hooks: [
+      {
+        id: 'pre-planning',
+        phase: 'before-plan',
+        script: 'hooks/pre-planning.hook.sh',
+        requiredEvidence: ['requirements-path', 'risk-tier'],
+      },
+      {
+        id: 'pre-code',
+        phase: 'before-code',
+        script: 'hooks/pre-code.hook.sh',
+        requiredEvidence: ['approved-plan-path', 'human-approval'],
+      },
+      {
+        id: 'post-code',
+        phase: 'after-code',
+        script: 'hooks/post-code.hook.sh',
+        requiredEvidence: ['verify-evidence'],
+      },
+      {
+        id: 'pre-review',
+        phase: 'before-review',
+        script: 'hooks/pre-review.hook.sh',
+        requiredEvidence: ['format-evidence', 'lint-evidence'],
+      },
+      {
+        id: 'pre-commit',
+        phase: 'before-commit',
+        script: 'hooks/pre-commit.hook.sh',
+        requiredEvidence: ['test-evidence', 'secret-scan-evidence'],
+      },
+      {
+        id: 'pre-tool-call',
+        phase: 'before-tool',
+        script: 'hooks/pre-tool-call.hook.sh',
+        requiredEvidence: ['tool-effect', 'approval-if-high'],
+      },
+      {
+        id: 'budget-guard',
+        phase: 'budget',
+        script: 'hooks/budget-guard.hook.sh',
+        requiredEvidence: ['budget-profile', 'budget-remaining'],
+      },
+      {
+        id: 'deployment',
+        phase: 'before-deploy',
+        script: 'hooks/deployment.hook.sh',
+        requiredEvidence: ['release-manifest', 'approval', 'release-evidence'],
+      },
+    ],
+    agentGuidance: {
+      beforeMultiFileCoding: `Attach plans/{STORY_ID}-plan.md and confirm human approval`,
+      beforePr: `Write reviews/{STORY_ID}-code-review.md; run repo lint/typecheck/test`,
+      mcp: `Keep mcpServers empty until human copies from ${L.mcpFile} _aiesRecommended`,
+    },
+    _aies: {
+      hooksGuide: `${SITE_URL}/docs/handbook/hooks-in-practice`,
+      contract: 'hooks/CONTRACT.md',
+    },
+  };
+}
 /**
  * @param {object} profile
  * @param {{ recommendedMcpIds?: string[] }} [opts]
@@ -472,7 +572,7 @@ export function generateStarterKit(profile, opts = {}) {
   const now = new Date().toISOString();
   const model = profile.model ?? 'undecided';
   const dataClass = profile.dataClass ?? 'internal';
-  const L = layoutFor(profile.ide);
+  const L = layoutFor(profile.ide, { cookbookId: stack.cookbook ?? null });
   const recommendedIds = opts.recommendedMcpIds ?? stackMcpIds(profile.stack);
   const recommended = buildRecommendedMcpConfig(recommendedIds);
@@ -504,6 +604,17 @@ export function generateStarterKit(profile, opts = {}) {
   files[`${L.templatesDir}/system-prompt.template.md`] = corpus('templates/system-prompt.template.md');
+  files['plans/README.md'] = corpus('kit/plans-README.md');
+  files['plans/_TEMPLATE.md'] = corpus('kit/plan-TEMPLATE.md');
+  files['reviews/README.md'] = corpus('kit/reviews-README.md');
+  files['reviews/_TEMPLATE.md'] = corpus('kit/review-TEMPLATE.md');
+  files['hooks/README.md'] = corpus('kit/hooks-README.md');
+  files['hooks/CONTRACT.md'] = corpus('hooks/CONTRACT.md');
+  for (const key of Object.keys(EMBEDDED_CORPUS).filter(k => k.startsWith('hooks/') && k.endsWith('.hook.sh'))) {
+    files[key] = corpus(key);
+  }
   if (stack.cookbook) {
     const keys = cookbookKeys(stack.cookbook);
     for (const key of keys) {
@@ -543,18 +654,7 @@ export function generateStarterKit(profile, opts = {}) {
   };
   files[L.mcpFile] = JSON.stringify(mcpDoc, null, 2);
-  files[L.hooksFile] = JSON.stringify(
-    {
-      version: '1',
-      hooks: [
-        { id: 'pre-planning', phase: 'before-plan', requiredEvidence: ['requirements-path', 'risk-tier'] },
-        { id: 'pre-code', phase: 'before-code', requiredEvidence: ['approved-plan-path'] },
-      ],
-      _aies: { hooksGuide: `${SITE_URL}/docs/04-agent-engineering/hooks/README` },
-    },
-    null,
-    2,
-  );
+  files[L.hooksFile] = JSON.stringify(agentHooksRegistry(L), null, 2);
   const rootInstructions = buildRootInstructions(profile, label, L);
   files['CLAUDE.md'] = rootInstructions;
@@ -574,7 +674,7 @@ ${rootInstructions}
   } else if (profile.ide === 'claude-code') {
     // CLAUDE.md already written as rootInstructions
   } else if (profile.ide === 'copilot') {
-    // .github/copilot-instructions.md already written
+    // .github/copilot-instructions.md already written — do not nest cookbook under .github
   } else if (profile.ide === 'continue') {
     files[L.rulesFile] = rootInstructions;
     files['.continue/config.snippet.json'] = JSON.stringify(
@@ -584,6 +684,7 @@ ${rootInstructions}
           { name: 'file', params: { path: 'implementation_plan.md' } },
           { name: 'file', params: { path: L.cookbookDir } },
           { name: 'file', params: { path: L.skillsDir } },
+          { name: 'file', params: { path: L.promptsDir } },
         ],
       },
       null,
@@ -593,7 +694,7 @@ ${rootInstructions}
     files[L.rulesFile] = rootInstructions;
   }
-  files['implementation_plan.md'] = implementationPlanTemplate(L.promptsDir);
+  files['implementation_plan.md'] = implementationPlanIndex(L.promptsDir);
   files['AIES.md'] = buildAiesReadme({
     profile: { ...profile, model, dataClass },
@@ -609,7 +710,7 @@ ${rootInstructions}
     stack: profile.stack,
     generatedAt: now,
     profile: { ...profile, model, dataClass },
-    layout: describeInstallLayout(profile.ide),
+    layout: describeInstallLayout(profile.ide, { cookbookId: stack.cookbook ?? null }),
     files,
   };
 }
@@ -639,8 +740,8 @@ ${mergedIds.map(id => `- ${id}`).join('\n')}
 ## Next
-1. Review \`${layoutFor(profile.ide).mcpFile}\` → \`_aiesRecommended\`
-2. Run \`${layoutFor(profile.ide).promptsDir}/enhance-repo.prompt.md\` in your IDE agent
+1. Review \`${layoutFor(profile.ide, { cookbookId: stackMeta(profile.stack).cookbook }).mcpFile}\` → \`_aiesRecommended\`
+2. Run \`${layoutFor(profile.ide, { cookbookId: stackMeta(profile.stack).cookbook }).promptsDir}/enhance-repo.prompt.md\` in your IDE agent
 3. Fill \`implementation_plan.md\` before multi-file coding
 `;

package/lib/kit-core/install-api.js CHANGED Viewed

@@ -1,123 +1,131 @@
 /**
  * Client-safe kit helpers — no node:fs, safe for Next.js client components.
+ *
+ * Layout contract:
+ * - IDE root (.cursor / .github / .claude / …) = prompts + skills + agents (+ IDE rules/MCP config)
+ * - Repo root shared dirs = cookbook, guides, mcps, templates, policy (never nest these under .github)
  */
 import { SITE_URL } from './options.js';
-/** IDE-native roots — never writes `.aies/`. */
-export function layoutFor(ide) {
+/** Shared repo-root paths — identical for every IDE. */
+const SHARED = {
+  cookbookBase: 'cookbook',
+  guidesDir: 'guides',
+  mcpsDir: 'mcps',
+  templatesDir: 'templates',
+  policyFile: 'MODEL_POLICY.md',
+  hooksFile: 'aies-hooks.json',
+};
+/**
+ * @param {string} ide
+ * @param {{ cookbookId?: string | null }} [opts]
+ */
+export function layoutFor(ide, opts = {}) {
+  const cookbookId = opts.cookbookId ?? null;
+  const cookbookDir = cookbookId ? `${SHARED.cookbookBase}/${cookbookId}` : SHARED.cookbookBase;
   switch (ide) {
     case 'cursor':
       return {
         ide,
+        ...SHARED,
+        cookbookDir,
         root: '.cursor',
         rulesFile: '.cursor/rules/aies.mdc',
         skillsDir: '.cursor/skills',
         skillStyle: 'cursor-skill',
         promptsDir: '.cursor/prompts',
-        cookbookDir: '.cursor/cookbook',
-        guidesDir: '.cursor/guides',
         agentsDir: '.cursor/agents',
-        mcpsDir: '.cursor/mcps',
-        templatesDir: '.cursor/templates',
         mcpFile: '.cursor/mcp.json',
         hooksFile: '.cursor/aies-hooks.json',
-        policyFile: '.cursor/MODEL_POLICY.md',
       };
     case 'copilot':
       return {
         ide,
+        ...SHARED,
+        cookbookDir,
         root: '.github',
         rulesFile: '.github/copilot-instructions.md',
         skillsDir: '.github/skills',
         skillStyle: 'flat',
         promptsDir: '.github/prompts',
-        cookbookDir: '.github/cookbook',
-        guidesDir: '.github/guides',
         agentsDir: '.github/agents',
-        mcpsDir: '.github/mcps',
-        templatesDir: '.github/templates',
-        mcpFile: '.github/mcp.json',
-        hooksFile: '.github/aies-hooks.json',
-        policyFile: '.github/MODEL_POLICY.md',
+        // Copilot discovery only under .github — MCP config at repo root
+        mcpFile: '.mcp.json',
       };
     case 'claude-code':
       return {
         ide,
+        ...SHARED,
+        cookbookDir,
         root: '.claude',
         rulesFile: 'CLAUDE.md',
         skillsDir: '.claude/skills',
         skillStyle: 'cursor-skill',
         promptsDir: '.claude/prompts',
-        cookbookDir: '.claude/cookbook',
-        guidesDir: '.claude/guides',
         agentsDir: '.claude/agents',
-        mcpsDir: '.claude/mcps',
-        templatesDir: '.claude/templates',
         mcpFile: '.mcp.json',
-        hooksFile: '.claude/aies-hooks.json',
-        policyFile: '.claude/MODEL_POLICY.md',
       };
     case 'vscode':
       return {
         ide,
+        ...SHARED,
+        cookbookDir,
         root: '.vscode',
         rulesFile: '.vscode/aies-instructions.md',
         skillsDir: '.vscode/skills',
         skillStyle: 'flat',
         promptsDir: '.vscode/prompts',
-        cookbookDir: '.vscode/cookbook',
-        guidesDir: '.vscode/guides',
         agentsDir: '.vscode/agents',
-        mcpsDir: '.vscode/mcps',
-        templatesDir: '.vscode/templates',
         mcpFile: '.vscode/mcp.json',
-        hooksFile: '.vscode/aies-hooks.json',
-        policyFile: '.vscode/MODEL_POLICY.md',
       };
     case 'windsurf':
       return {
         ide,
+        ...SHARED,
+        cookbookDir,
         root: '.windsurf',
         rulesFile: '.windsurfrules',
         skillsDir: '.windsurf/skills',
         skillStyle: 'flat',
         promptsDir: '.windsurf/prompts',
-        cookbookDir: '.windsurf/cookbook',
-        guidesDir: '.windsurf/guides',
         agentsDir: '.windsurf/agents',
-        mcpsDir: '.windsurf/mcps',
-        templatesDir: '.windsurf/templates',
         mcpFile: '.windsurf/mcp.json',
-        hooksFile: '.windsurf/aies-hooks.json',
-        policyFile: '.windsurf/MODEL_POLICY.md',
       };
     case 'continue':
       return {
         ide,
+        ...SHARED,
+        cookbookDir,
         root: '.continue',
         rulesFile: '.continue/aies-context.md',
         skillsDir: '.continue/skills',
         skillStyle: 'flat',
         promptsDir: '.continue/prompts',
-        cookbookDir: '.continue/cookbook',
-        guidesDir: '.continue/guides',
         agentsDir: '.continue/agents',
-        mcpsDir: '.continue/mcps',
-        templatesDir: '.continue/templates',
         mcpFile: '.continue/mcp.json',
-        hooksFile: '.continue/aies-hooks.json',
-        policyFile: '.continue/MODEL_POLICY.md',
       };
     default:
-      return layoutFor('vscode');
+      return layoutFor('vscode', opts);
   }
 }
-export function describeInstallLayout(ide) {
-  const L = layoutFor(ide);
+export function describeInstallLayout(ide, opts = {}) {
+  const L = layoutFor(ide, opts);
   return {
-    rootFiles: ['AIES.md', 'implementation_plan.md', 'CLAUDE.md', 'AGENTS.md', 'copilot-instructions.md'],
+    rootFiles: [
+      'AIES.md',
+      'implementation_plan.md',
+      'CLAUDE.md',
+      'AGENTS.md',
+      'copilot-instructions.md',
+      'MODEL_POLICY.md',
+      'aies-hooks.json',
+    ],
     ideRoot: L.root,
+    ideOnly: [L.promptsDir, L.skillsDir, L.agentsDir],
+    sharedRoot: [L.cookbookDir, L.guidesDir, L.mcpsDir, L.templatesDir],
     rulesFile: L.rulesFile,
     skillsDir: L.skillsDir,
     promptsDir: L.promptsDir,
@@ -125,8 +133,10 @@ export function describeInstallLayout(ide) {
     guidesDir: L.guidesDir,
     agentsDir: L.agentsDir,
     mcpsDir: L.mcpsDir,
+    templatesDir: L.templatesDir,
     mcpFile: L.mcpFile,
     policyFile: L.policyFile,
+    hooksFile: L.hooksFile,
   };
 }

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@grvmithas/create-aies-kit",
-  "version": "1.1.0",
+  "version": "1.3.0",
   "description": "Scaffold a complete AIES (AI Engineering Standard) harness into IDE-native paths — prompts, skills, cookbook, agents, MCP stubs, AGENTS.md.",
   "license": "MIT",
   "type": "module",