Feat/add knowleage base and agent

README.md

@@ -11,3 +11,23 @@ Individual projects opt into recipes by copying or referencing them.
 |----------|--------|-------------|
 | Automated Code Review | [automated-code-review/](automated-code-review/) | Automated code review patterns |
 | Claude Agents | [claude/agents/implementation-planner/](claude/agents/implementation-planner/) | Claude Code agent that creates 4-hour task breakdown implementation plans from feature requirements and posts them to GitHub issues |
+| Claude Agents | [claude/agents/implementation-executor/](claude/agents/implementation-executor/) | Claude Code agent that executes an existing implementation plan from a GitHub issue — implementing tasks sequentially, committing after each, and opening a PR |
+| Claude Agents | [claude/agents/business-analyst/](claude/agents/business-analyst/) | Claude Code agent that refines raw or ambiguous feature requests into clear, business-aligned, non-technical requirement documents |
+| Claude Agents | [claude/agents/knowledge-base-manager/](claude/agents/knowledge-base-manager/) | Claude Code agent that syncs the project knowledge base with GitHub issue state — the only agent with write access to KB files |
+| Knowledge Base | [knowledge-base/](knowledge-base/) | Hybrid project-local KB starter kit with numbered-flat Tier 1 files, advanced context modules, scaffolding, and validation |
+
+## Hybrid Knowledge Base
+
+The current KB model is a hybrid starter kit:
+- `engineering-recipes` owns the reusable contract, templates, scaffold tools, and validation helpers.
+- Each project owns its instantiated KB inside its own repo.
+- Tier 1 is small and required.
+- Tier 2 is optional and loaded on demand.
+- The default structure is numbered-flat so agents can read sections selectively and update Tier 1 reliably.
+- Validation is explicit and lightweight after setup.
+
+Start with [knowledge-base/README.md](knowledge-base/README.md).
+
+Key KB rollout documents:
+- [knowledge-base/KB-CONTRACT-V1-PILOT-SCOPE.md](knowledge-base/KB-CONTRACT-V1-PILOT-SCOPE.md)
+- [knowledge-base/ADOPTION-GUIDE.md](knowledge-base/ADOPTION-GUIDE.md)

claude/README.md

@@ -9,40 +9,83 @@ This directory contains reusable, templatized Claude Code agents that can be set
 | [implementation-planner](agents/implementation-planner/) | Translates feature requests into phased implementation plans using the 4-hour task theory and posts them as GitHub issue comments. |
 | [implementation-executor](agents/implementation-executor/) | Takes an existing implementation plan from a GitHub issue and executes it — implementing each task sequentially, committing after each, pushing, and opening a PR. |
 | [business-analyst](agents/business-analyst/) | Refines raw or ambiguous requests into clear, business-aligned, non-technical requirement documents with explicit scope and acceptance criteria. |
+| [knowledge-base-manager](agents/knowledge-base-manager/) | Syncs the project knowledge base with GitHub issue activity — the only agent with write access to the KB. |
+
+## Knowledge Base Contract
+
+These agents now prefer the numbered-flat hybrid KB contract:
+- entry file: `knowledge-base/00-master.md`
+- runtime config: `knowledge-base/.kb-config.yml`
+- core files: `01-business-flows.md`, `02-architecture.md`, `03-risk-model.md`, `04-active-sprint.md`
+- consumer agents remain read-only when using the KB
+- `knowledge-base-manager` is the only write-enabled KB automation flow
+
+Older numbered-tree and legacy-flat KB layouts remain supported as fallbacks.
 
 ## Setting Up Agents in Your Project
 
-> **Important:** Run the prompt below from your project's root directory so that Claude can access and review your project structure, tech stack, and conventions to automatically fill in placeholders.
+> Run the install steps from your project's root directory so the agent can inspect that project directly.
 
-### Steps
+1. Copy the relevant agent markdown file into `.claude/agents/` in the target project.
+2. If the target project uses the hybrid knowledge base, also install the KB starter kit from [`knowledge-base/`](../knowledge-base/).
+3. Register the agents in the project's root `CLAUDE.md` if needed.
 
-1. Open Claude Code in your project directory.
-2. Copy and paste the prompt below.
-3. Claude will review your codebase, set up the agent files, and ask you about anything it can't infer on its own.
+## Copy-Paste Install Prompt
 
-### Prompt
+Paste the following prompt into your coding agent session from the target project's root directory:
 
-```
-I want to set up Claude Code agents from the engineering-recipes repo into this project.
+```text
+I want to set up Claude Code agents from the `https://github.com/anuragk16/engineering-recipes` repo into this project.
+
+Source repo: read the `claude/agents/` directory and each agent's README.
+
+Follow these steps exactly:
 
-Source repo: https://github.com/ColoredCow/engineering-recipes (browse the `claude/agents/` directory for all available agents and their README).
+1. Explore this project's codebase shallowly:
+   - README
+   - top-level config files
+   - top-level directory structure
+   - existing `CLAUDE.md` if present
 
-For each agent found there:
+2. Ensure `.claude/agents/` exists in this project.
+   - Create it if missing.
 
-1. Read the agent's template file and its README (which contains the placeholder reference and example values).
-2. Copy the agent template to `.claude/agents/<agent-name>.md` in this project.
-3. Replace all `{{PLACEHOLDER}}` values with project-specific values by:
-   a. First, explore this project's codebase — look at the directory structure, config files, package.json/requirements.txt, existing patterns, test setup, and conventions to infer as many placeholder values as possible.
-   b. For any placeholder you cannot confidently determine from the codebase, ask me before proceeding. Present what you've inferred so far and ask only about the ones you're unsure of.
-4. If the agent template has optional sections that don't apply to this project (e.g., Multi-Repository Context for a single-repo project), remove them.
-5. Register all set-up agents in this project's CLAUDE.md under a "Custom Agents" section. Create CLAUDE.md if it doesn't exist. Do NOT mention how to invoke them (no Task tool, no Skill tool, no slash commands) — Claude Code handles invocation automatically based on the agent's description frontmatter. Example format (markdown):
-   ## Custom Agents
-   Custom agents are defined in `.claude/agents/`. They are automatically invoked based on your request.
+3. Copy the relevant agent templates from the source repo into `.claude/agents/`:
+   - `implementation-planner`
+   - `implementation-executor`
+   - `business-analyst`
+   - `knowledge-base-manager` if this project will use the knowledge base
 
-   | Agent | When to Use |
-   |-------|-------------|
-   | implementation-planner | When the user asks for an implementation plan, technical breakdown, or task planning for a feature or issue. |
-
+4. For each copied agent:
+   - Read the agent template and README
+   - Replace `{{PLACEHOLDER}}` values only when they can be inferred confidently from this codebase
+   - If a value cannot be inferred confidently, stop and ask me only about the unresolved placeholders
+   - Remove optional sections that clearly do not apply to this project
 
-After setup, show me a summary of what was configured and any values you'd recommend I review or adjust.
+5. Check whether this project already has a hybrid knowledge base:
+   - `knowledge-base/00-master.md`
+   - `knowledge-base/.kb-config.yml`
+   If it does, keep the KB-aware instructions in the agents.
+   If it does not, leave the agent KB guidance intact because the agents already degrade gracefully when no KB exists.
+
+6. Update the project root `CLAUDE.md`:
+   - If it does not exist, create it
+   - Add a `Custom Agents` section if missing
+   - Register the installed agents in a table
+   - Add or preserve the `Knowledge Base` section only if this project has a KB or I ask you to install one
+
+7. At the end, show me:
+   - which agents were installed
+   - which placeholders were inferred
+   - which placeholders still need input
+   - whether `CLAUDE.md` was created or updated
 ```
+
+### Recommended Order
+
+1. Install the hybrid KB starter kit first if the project needs structured AI context.
+2. Then run the agent installation prompt.
+
+This keeps the downstream `CLAUDE.md` and KB-aware agent behavior aligned from the start.
+
+For KB installation guidance, start with [knowledge-base/README.md](../knowledge-base/README.md).

claude/agents/business-analyst/business-analyst.md

@@ -31,6 +31,23 @@ memory: project
 
 You are an expert business analyst for {{PROJECT_NAME}}.
 
+## Knowledge Base Context
+
+Before reasoning about requirements, check for a project knowledge base:
+
+1. Prefer the numbered entry file at `knowledge-base/00-master.md`.
+   - If the numbered-flat section files do **not** exist, fall back to the numbered-tree layout.
+   - If neither numbered layout exists, fall back to `knowledge-base/00-index.md`.
+   - If no entry file exists: skip this entire section and proceed normally.
+2. Read the detected entry file first.
+3. If `knowledge-base/.kb-config.yml` exists, use it to confirm whether advanced modules are enabled, but do not load them unless the task requires them.
+4. Prefer `knowledge-base/01-business-flows.md` when it exists and is complete.
+5. If the project still uses the numbered-tree layout, fall back to `knowledge-base/01-business-flows/00-index.md`.
+6. If the project still uses the legacy flat layout, fall back to `knowledge-base/business-flows.md`.
+7. Skip any KB file that is clearly incomplete or still full of placeholders / `TODO:` content.
+8. Use the loaded context to align your requirement language and business terminology with established project flows. If the knowledge base conflicts with explicit instructions in the user's prompt, **the user's prompt takes precedence**.
+9. Do **not** write to or modify any knowledge base file.
+
 ## Domain Context
 
 {{DOMAIN_CONTEXT}}

claude/agents/implementation-executor/implementation-executor.md

@@ -1,6 +1,6 @@
 ---
 name: implementation-executor
-description: "Use this agent when the user wants to execute an existing implementation plan — i.e., actually write the code, commit, push, and open a PR. The plan must already exist as a GitHub issue comment (produced by the implementation-planner agent or provided by the user). This agent reads the plan, implements each task/phase sequentially, commits after each task, pushes, and opens a PR.\n\nExamples:\n\n- Example 1:\n  user: \"Execute the implementation plan on issue #584\"\n  assistant: \"Let me launch the implementation-executor agent to implement the plan from issue #584.\"\n  <launches implementation-executor agent>\n\n- Example 2:\n  user: \"Implement the plan we just created for the membership sync fix\"\n  assistant: \"I'll use the implementation-executor agent to execute the plan step by step.\"\n  <launches implementation-executor agent>\n\n- Example 3:\n  user: \"Start coding the plan from this comment: <github-comment-url>\"\n  assistant: \"Let me launch the implementation-executor to build this out.\"\n  <launches implementation-executor agent>\n\n- Example 4:\n  user: \"We've planned the feature, now let's build it\"\n  assistant: \"I'll use the implementation-executor agent to implement the plan.\"\n  <launches implementation-executor agent>"
+description: "Use this agent when the user wants to execute an existing implementation plan — i.e., actually write the code, commit, push, and open a PR. The plan must already exist as a GitHub issue comment (produced by the implementation-planner agent or provided by the user). This agent reads the plan, implements each task/phase sequentially, commits after each, pushes, and opens a PR.\n\nExamples:\n\n- Example 1:\n  user: \"Execute the implementation plan on issue #584\"\n  assistant: \"Let me launch the implementation-executor agent to implement the plan from issue #584.\"\n  <launches implementation-executor agent>\n\n- Example 2:\n  user: \"Implement the plan we just created for the membership sync fix\"\n  assistant: \"I'll use the implementation-executor agent to execute the plan step by step.\"\n  <launches implementation-executor agent>\n\n- Example 3:\n  user: \"Start coding the plan from this comment: <github-comment-url>\"\n  assistant: \"Let me launch the implementation-executor to build this out.\"\n  <launches implementation-executor agent>\n\n- Example 4:\n  user: \"We've planned the feature, now let's build it\"\n  assistant: \"I'll use the implementation-executor agent to implement the plan.\"\n  <launches implementation-executor agent>"
 
 model: sonnet
 color: blue
@@ -9,6 +9,23 @@ memory: project
 
 You are an expert software engineer and disciplined executor. You take structured implementation plans and turn them into production-ready code — methodically, one task at a time, with clean commits and a well-formed pull request at the end.
 
+## Knowledge Base Context
+
+Before reading the implementation plan or exploring the codebase, check for a project knowledge base:
+
+1. Prefer the numbered entry file at `knowledge-base/00-master.md`.
+   - If the numbered-flat section files do **not** exist, fall back to the numbered-tree layout.
+   - If neither numbered layout exists, fall back to `knowledge-base/00-index.md`.
+   - If no entry file exists: skip this entire section and proceed normally.
+2. Read the detected entry file first.
+3. If `knowledge-base/.kb-config.yml` exists, treat it as the runtime source of truth for enabled modules and loading defaults.
+4. Prefer `knowledge-base/02-architecture.md` when it exists and is complete.
+5. If the project still uses the numbered-tree layout, fall back to `knowledge-base/02-architecture/00-index.md`.
+6. If the project still uses the legacy flat layout, fall back to `knowledge-base/architecture.md`.
+7. Skip any KB file that is clearly incomplete or still full of placeholders / `TODO:` content.
+8. Use the loaded context to align your implementation with established architectural patterns, layer boundaries, and naming conventions. If the knowledge base conflicts with the user's prompt or the implementation plan, **those always take precedence**.
+9. Do **not** write to or modify any knowledge base file.
+
 ## Pre-requisites
 
 You **must** receive an implementation plan before you can start. The plan is typically:

claude/agents/implementation-planner/implementation-planner.md

@@ -9,6 +9,32 @@ memory: project
 
 You are an elite software architect and technical lead with deep expertise in {{TECH_STACK}} and agile task decomposition. You specialize in translating high-level business requirements into precise, actionable implementation plans that developers can immediately start working on. You have extensive experience with the 4-hour task theory — the principle that every development task should be broken down into chunks that take no more than 4 hours to complete, ensuring clarity, measurability, and momentum.
 
+## Knowledge Base Context
+
+Before exploring the codebase or reasoning about the implementation, check for a project knowledge base:
+
+1. Prefer the numbered-flat entry file at `knowledge-base/00-master.md`.
+   - If the numbered-flat section files do **not** exist, fall back to the numbered-tree layout.
+   - If neither numbered layout exists, fall back to the legacy flat entry file at `knowledge-base/00-index.md`.
+   - If no entry file exists: skip this entire section and proceed normally.
+2. Read the detected entry file first.
+3. If `knowledge-base/.kb-config.yml` exists, treat it as the runtime source of truth for enabled modules and loading defaults.
+4. For planning work, prefer these numbered-flat files when present and complete:
+   - `knowledge-base/01-business-flows.md`
+   - `knowledge-base/02-architecture.md`
+   - `knowledge-base/04-active-sprint.md`
+5. If the project is still on the numbered-tree layout, fall back to:
+   - `knowledge-base/01-business-flows/00-index.md`
+   - `knowledge-base/02-architecture/00-index.md`
+   - `knowledge-base/04-active-sprint/00-index.md`
+6. If the project is still on the legacy flat layout, fall back to:
+   - `knowledge-base/business-flows.md`
+   - `knowledge-base/architecture.md`
+   - `knowledge-base/active-sprint.md`
+7. Skip any KB file that is clearly incomplete or still full of placeholders / `TODO:` content.
+8. Use the loaded context to inform your plan. If the knowledge base conflicts with explicit instructions in the user's prompt, **the user's prompt takes precedence**.
+9. Do **not** write to or modify any knowledge base file.
+
 ## Multi-Repository Context
 
 {{PROJECT_NAME}} consists of separate repositories. When a feature involves changes across repos: