From 41a6fd602e0ae0b368218ff9a04b583cf7f5f1f5 Mon Sep 17 00:00:00 2001 From: Anurag Kumawat Date: Sat, 28 Feb 2026 10:56:27 +0530 Subject: [PATCH 01/16] feat: Initial implementation of knowleage base --- knowledge-base/00-master.md | 19 +++ knowledge-base/01-business-flows/00-index.md | 85 ++++++++++++ knowledge-base/02-architecture/00-index.md | 129 +++++++++++++++++++ knowledge-base/03-risk-model/00-index.md | 105 +++++++++++++++ knowledge-base/04-active-sprint/00-index.md | 84 ++++++++++++ knowledge-base/README.md | 117 +++++++++++++++++ 6 files changed, 539 insertions(+) create mode 100644 knowledge-base/00-master.md create mode 100644 knowledge-base/01-business-flows/00-index.md create mode 100644 knowledge-base/02-architecture/00-index.md create mode 100644 knowledge-base/03-risk-model/00-index.md create mode 100644 knowledge-base/04-active-sprint/00-index.md create mode 100644 knowledge-base/README.md diff --git a/knowledge-base/00-master.md b/knowledge-base/00-master.md new file mode 100644 index 0000000..cbb3aa6 --- /dev/null +++ b/knowledge-base/00-master.md @@ -0,0 +1,19 @@ + + +# Knowledge Base: {{PROJECT_NAME}} + +**Last Updated:** {{LAST_UPDATED_DATE}} +**Tech Stack:** {{TECH_STACK}} + +## Sections + +| Section | File | Summary | +|---------|------|---------| +| Business Flows | `01-business-flows/00-index.md` | Core user journeys and business process flows for {{PROJECT_NAME}} | +| Architecture | `02-architecture/00-index.md` | Architectural patterns, tech stack decisions, and integration rules | +| Risk Model | `03-risk-model/00-index.md` | Risk classification rules, sensitive areas, and change impact guidance | +| Active Sprint | `04-active-sprint/00-index.md` | Current sprint goal, active issues, and progress tracking | diff --git a/knowledge-base/01-business-flows/00-index.md b/knowledge-base/01-business-flows/00-index.md new file mode 100644 index 0000000..3189bbd --- /dev/null +++ b/knowledge-base/01-business-flows/00-index.md @@ -0,0 +1,85 @@ + + +# Business Flows: {{PROJECT_NAME}} + +**Domain:** {{BUSINESS_DOMAIN}} +**Primary Users:** {{PRIMARY_USER_ROLES}} + +--- + +## Flow Index + +| Flow ID | Flow Name | Initiator | Outcome | +|---------|-----------|-----------|---------| +| BF-01 | {{FLOW_NAME_1}} | {{INITIATOR_1}} | {{OUTCOME_1}} | +| BF-02 | {{FLOW_NAME_2}} | {{INITIATOR_2}} | {{OUTCOME_2}} | + + + +--- + +## Flow Details + +### BF-01: {{FLOW_NAME_1}} + +**Initiator:** {{INITIATOR_1}} +**Trigger:** {{TRIGGER_CONDITION_1}} +**Expected Outcome:** {{OUTCOME_1}} + +**Steps:** +1. {{STEP_1}} +2. {{STEP_2}} +3. {{STEP_3}} + +**Business Rules:** +- {{BUSINESS_RULE_1}} +- {{BUSINESS_RULE_2}} + +**Edge Cases / Exceptions:** +- {{EDGE_CASE_1}} + +--- + + + +--- + + diff --git a/knowledge-base/02-architecture/00-index.md b/knowledge-base/02-architecture/00-index.md new file mode 100644 index 0000000..e7e47a0 --- /dev/null +++ b/knowledge-base/02-architecture/00-index.md @@ -0,0 +1,129 @@ + + +# Architecture: {{PROJECT_NAME}} + +--- + +## Tech Stack + +| Layer | Technology | Version | +|-------|-----------|---------| +| {{LAYER_1}} | {{TECH_1}} | {{VERSION_1}} | +| {{LAYER_2}} | {{TECH_2}} | {{VERSION_2}} | +| {{LAYER_3}} | {{TECH_3}} | {{VERSION_3}} | + + + +--- + +## Directory Structure + +``` +{{PROJECT_ROOT}}/ +├── {{DIR_1}}/ # {{DIR_1_PURPOSE}} +├── {{DIR_2}}/ # {{DIR_2_PURPOSE}} +└── {{DIR_3}}/ # {{DIR_3_PURPOSE}} +``` + + + +--- + +## Established Patterns + +### Naming Conventions +- {{NAMING_RULE_1}} +- {{NAMING_RULE_2}} + +### File Organization Rules +- {{FILE_ORG_RULE_1}} +- {{FILE_ORG_RULE_2}} + +### API Design Rules +- {{API_RULE_1}} +- {{API_RULE_2}} + + + +--- + +## Layer Responsibilities + +| Layer | Responsibility | Must NOT Contain | +|-------|---------------|-----------------| +| {{LAYER_A}} | {{RESPONSIBILITY_A}} | {{FORBIDDEN_A}} | +| {{LAYER_B}} | {{RESPONSIBILITY_B}} | {{FORBIDDEN_B}} | + + + +--- + +## External Integrations + +| System | Purpose | Auth Method | +|--------|---------|-------------| +| {{EXT_SYSTEM_1}} | {{PURPOSE_1}} | {{AUTH_1}} | + + + +--- + +## Architectural Rules (Non-Negotiable) + +- {{ARCH_RULE_1}} +- {{ARCH_RULE_2}} + + + +--- + + diff --git a/knowledge-base/03-risk-model/00-index.md b/knowledge-base/03-risk-model/00-index.md new file mode 100644 index 0000000..2cc3f78 --- /dev/null +++ b/knowledge-base/03-risk-model/00-index.md @@ -0,0 +1,105 @@ + + +# Risk Model: {{PROJECT_NAME}} + +--- + +## Risk Classification + +| Area / Module | Risk Level | Reason | Required Review Gate | +|---------------|-----------|--------|---------------------| +| {{MODULE_1}} | High | {{REASON_1}} | {{GATE_1}} | +| {{MODULE_2}} | Medium | {{REASON_2}} | {{GATE_2}} | +| {{MODULE_3}} | Low | {{REASON_3}} | None | + + + +--- + +## What Makes a Change High-Risk + +A change is classified as **High Risk** if it meets any of the following conditions: + +- {{HIGH_RISK_CONDITION_1}} +- {{HIGH_RISK_CONDITION_2}} +- {{HIGH_RISK_CONDITION_3}} + + + +--- + +## Required Actions by Risk Level + +| Risk Level | Required Actions | +|-----------|-----------------| +| High | {{HIGH_REQUIRED_ACTIONS}} | +| Medium | {{MEDIUM_REQUIRED_ACTIONS}} | +| Low | Standard PR review | + + + +--- + +## Known Fragile Areas + +Areas with a history of regressions or incidents that require extra care: + +| Area | Known Issue Pattern | Mitigation | +|------|--------------------|-----------| +| {{FRAGILE_AREA_1}} | {{ISSUE_PATTERN_1}} | {{MITIGATION_1}} | + + + +--- + +## Sensitive Data Handling Rules + +- {{SENSITIVE_DATA_RULE_1}} +- {{SENSITIVE_DATA_RULE_2}} + + + +--- + + diff --git a/knowledge-base/04-active-sprint/00-index.md b/knowledge-base/04-active-sprint/00-index.md new file mode 100644 index 0000000..42271df --- /dev/null +++ b/knowledge-base/04-active-sprint/00-index.md @@ -0,0 +1,84 @@ + + +# Active Sprint: {{PROJECT_NAME}} + +**Sprint:** {{SPRINT_NAME_OR_NUMBER}} +**Sprint Goal:** {{SPRINT_GOAL}} +**Period:** {{SPRINT_START_DATE}} → {{SPRINT_END_DATE}} + +--- + +## Active Issues + +| Issue | Title | Assignee | Status | Notes | +|-------|-------|----------|--------|-------| +| #{{ISSUE_NUMBER_1}} | {{ISSUE_TITLE_1}} | {{ASSIGNEE_1}} | {{STATUS_1}} | {{PROGRESS_NOTE_1}} | +| #{{ISSUE_NUMBER_2}} | {{ISSUE_TITLE_2}} | {{ASSIGNEE_2}} | {{STATUS_2}} | {{PROGRESS_NOTE_2}} | + + + +--- + +## Blocked Items + +| Issue | Blocker | Owner | +|-------|---------|-------| +| #{{BLOCKED_ISSUE}} | {{BLOCKER_DESCRIPTION}} | {{BLOCKER_OWNER}} | + + + +--- + +## Completed This Sprint + +| Issue | Title | Completed On | +|-------|-------|-------------| +| #{{DONE_ISSUE_1}} | {{DONE_TITLE_1}} | {{DONE_DATE_1}} | + + + +--- + + diff --git a/knowledge-base/README.md b/knowledge-base/README.md new file mode 100644 index 0000000..93921c0 --- /dev/null +++ b/knowledge-base/README.md @@ -0,0 +1,117 @@ +# Knowledge Base Templates + +This directory contains reusable, templatized knowledge base files that can be installed into any project with a single prompt. The knowledge base gives Claude agents structured, project-specific context — business flows, architecture rules, risk classification, and sprint state — without hallucination. + +## Available Templates + +| Template | Description | +|----------|-------------| +| [00-master.md](00-master.md) | Lightweight index listing all sections. The only file agents are required to read on every run. | +| [01-business-flows/00-index.md](01-business-flows/00-index.md) | Core user journeys and business process flows. Used by the `business-analyst` agent. | +| [02-architecture/00-index.md](02-architecture/00-index.md) | Tech stack, directory structure, layer responsibilities, and architectural rules. Used by `implementation-planner` and `implementation-executor`. | +| [03-risk-model/00-index.md](03-risk-model/00-index.md) | Risk classification of modules, high-risk change conditions, and sensitive data rules. Used by the `code-reviewer` agent. | +| [04-active-sprint/00-index.md](04-active-sprint/00-index.md) | Current sprint goal, active issues, blocked items, and completed work. Updated by the `knowledge-base-manager` agent. | + +## Setting Up the Knowledge Base 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. + +### Steps + +1. Open Claude Code in your project directory. +2. Copy and paste the prompt below. +3. Claude will explore your codebase, install the knowledge base files, and ask you about anything it cannot infer on its own. + +### Prompt + +``` +I want to set up the AI knowledge base from the engineering-recipes repo into this project. + +Source repo: https://github.com/ColoredCow/engineering-recipes (read the `knowledge-base/` directory for all template files). + +Follow these steps exactly: + +1. Explore this project's codebase shallowly — read the README, top-level config files (package.json, composer.json, pyproject.toml, .env.example, etc.), top-level directory structure, and the 5 most recent git commits. + +2. Check if `docs/knowledge-base/` already exists in this project. + - If it exists: stop and ask me how to proceed before making any changes. + - If it does not exist: continue. + +3. Read each template file from the source repo's `knowledge-base/` directory: + - `00-master.md` + - `01-business-flows/00-index.md` + - `02-architecture/00-index.md` + - `03-risk-model/00-index.md` + - `04-active-sprint/00-index.md` + +4. Copy each template to the same relative path under `docs/knowledge-base/` in this project. + +5. Replace all `{{PLACEHOLDER}}` values with project-specific values: + a. Infer as many values as possible from your codebase exploration in step 1. + b. For any placeholder you cannot confidently determine, ask me before proceeding. Present what you've inferred so far and ask only about the ones you're unsure of. + c. Never guess. Never leave a `TODO:` annotation that you could have answered from the codebase. + +6. Add the following "Knowledge Base" section to this project's root `CLAUDE.md`: + - If `CLAUDE.md` does not exist: create it and write the section below as the full content. + - If `CLAUDE.md` exists but has no "Knowledge Base" section: append the section below at the end. + - If a "Knowledge Base" section already exists: skip — do not duplicate. + + The section to add: + + --- + + ## Knowledge Base + + This project has a knowledge base at `docs/knowledge-base/`. All agents that consume + the knowledge base must follow the rules below. + + ### Reading Rules + + **Step 1 — Always read `docs/knowledge-base/00-master.md` first.** + This is the index file. It lists all sections with one-line summaries. Based on + the task at hand, decide which section files to load next. Never load all sections + at once. + + **Step 2 — Load only the sections mapped to your agent role (see table below).** + Do not load sections outside your mapping. If a task genuinely requires information + from an out-of-mapping section, rely only on what the user has provided in their prompt. + + **Step 3 — Apply the No Assumptions rule.** + Before using any section file, scan it for unfilled `TODO:` placeholders. If a section + contains one or more `TODO:` lines, skip that section entirely. Do not infer, guess, or + fabricate context from incomplete data. Proceed with only what is fully populated. + + ### Agent-to-Section Mapping + + | Agent | Sections to Load | + |-------|-----------------| + | implementation-planner | `02-architecture/00-index.md`, `04-active-sprint/00-index.md` | + | implementation-executor | `02-architecture/00-index.md` | + | business-analyst | `01-business-flows/00-index.md` | + | knowledge-base-manager | All sections (read + write access) | + + ### No Disturbance Rule + + The knowledge base is **read-only** for all agents except `knowledge-base-manager`. + No consuming agent may write to, modify, or delete knowledge base files. + + If the user provides explicit context in their prompt that differs from what the + knowledge base says, **the user's prompt always takes precedence**. The knowledge + base is supplementary context, not an override. + + Knowledge base content never changes an agent's core behavior or output format — + it only adds project-specific awareness on top of existing behavior. + + ### Graceful Degradation + + If `docs/knowledge-base/` does not exist, or `docs/knowledge-base/00-master.md` + is missing or empty, proceed exactly as you would without a knowledge base. + No error. No assumption. No behavioral change. + + --- + +7. After setup is complete, show me a summary of: + - Which `{{PLACEHOLDER}}` values were inferred and what they were set to + - Which `TODO:` items remain and need manual input from me + - Whether `CLAUDE.md` was created or appended to +``` From 88f99e3e15c278439e71bc907190346e05884a57 Mon Sep 17 00:00:00 2001 From: Anurag Kumawat Date: Sat, 28 Feb 2026 18:51:03 +0530 Subject: [PATCH 02/16] fix --- README.md | 4 + claude/README.md | 1 + .../business-analyst/business-analyst.md | 12 ++ .../implementation-executor.md | 12 ++ .../implementation-planner.md | 13 ++ .../agents/knowledge-base-manager/README.md | 70 +++++++ .../knowledge-base-manager.md | 174 ++++++++++++++++++ knowledge-base/README.md | 10 +- 8 files changed, 291 insertions(+), 5 deletions(-) create mode 100644 claude/agents/knowledge-base-manager/README.md create mode 100644 claude/agents/knowledge-base-manager/knowledge-base-manager.md diff --git a/README.md b/README.md index 37a48c1..8c06e10 100644 --- a/README.md +++ b/README.md @@ -11,3 +11,7 @@ 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 the knowledge base | +| Knowledge Base | [knowledge-base/](knowledge-base/) | Templatized AI knowledge base that installs into any project with a single prompt, giving agents structured project context (business flows, architecture, risk model, active sprint) | diff --git a/claude/README.md b/claude/README.md index 187ecb6..a8eb3a9 100644 --- a/claude/README.md +++ b/claude/README.md @@ -9,6 +9,7 @@ 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 knowledge base. No placeholders to configure. | ## Setting Up Agents in Your Project diff --git a/claude/agents/business-analyst/business-analyst.md b/claude/agents/business-analyst/business-analyst.md index 618bad0..2d6b76f 100644 --- a/claude/agents/business-analyst/business-analyst.md +++ b/claude/agents/business-analyst/business-analyst.md @@ -31,6 +31,18 @@ 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. Check if `knowledge-base/00-master.md` exists. + - If it does **not** exist: skip this entire section and proceed normally. +2. Read `knowledge-base/00-master.md`. +3. Load the following section — but **only** if it does not contain unfilled `TODO:` placeholders (skip if it has one or more `TODO:` lines): + - `knowledge-base/01-business-flows/00-index.md` +4. 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**. +5. Do **not** write to or modify any knowledge base file. + ## Domain Context {{DOMAIN_CONTEXT}} diff --git a/claude/agents/implementation-executor/implementation-executor.md b/claude/agents/implementation-executor/implementation-executor.md index ca697b2..9b2c163 100644 --- a/claude/agents/implementation-executor/implementation-executor.md +++ b/claude/agents/implementation-executor/implementation-executor.md @@ -9,6 +9,18 @@ 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. Check if `knowledge-base/00-master.md` exists. + - If it does **not** exist: skip this entire section and proceed normally. +2. Read `knowledge-base/00-master.md`. +3. Load the following section — but **only** if it does not contain unfilled `TODO:` placeholders (skip if it has one or more `TODO:` lines): + - `knowledge-base/02-architecture/00-index.md` +4. 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**. +5. 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: diff --git a/claude/agents/implementation-planner/implementation-planner.md b/claude/agents/implementation-planner/implementation-planner.md index 7e5d6c7..a2d8117 100644 --- a/claude/agents/implementation-planner/implementation-planner.md +++ b/claude/agents/implementation-planner/implementation-planner.md @@ -9,6 +9,19 @@ 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. Check if `knowledge-base/00-master.md` exists. + - If it does **not** exist: skip this entire section and proceed normally. +2. Read `knowledge-base/00-master.md`. +3. Load the following sections — but **only** if they do not contain unfilled `TODO:` placeholders (skip any section that has one or more `TODO:` lines): + - `knowledge-base/02-architecture/00-index.md` + - `knowledge-base/04-active-sprint/00-index.md` +4. Use the loaded context to inform your plan — architectural rules, established patterns, and sprint priorities. If the knowledge base conflicts with explicit instructions in the user's prompt, **the user's prompt takes precedence**. +5. 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: diff --git a/claude/agents/knowledge-base-manager/README.md b/claude/agents/knowledge-base-manager/README.md new file mode 100644 index 0000000..d72711d --- /dev/null +++ b/claude/agents/knowledge-base-manager/README.md @@ -0,0 +1,70 @@ +# Knowledge Base Manager Agent + +A Claude Code agent that keeps the project knowledge base in sync with GitHub issue activity. It is the **only** agent with write access to the knowledge base — all other agents are read-only consumers. + +## What It Does + +- Fetches GitHub issue data in a tiered, token-efficient order (title + state first, body only if needed, PR only if in-review or done) +- Maps each issue to one of four states: Backlog, In Progress, In Review, Done/Closed +- Updates `knowledge-base/04-active-sprint/00-index.md` without duplicating existing entries +- Optionally promotes significant architectural decisions or risk learnings to the relevant KB sections when an issue is closed +- Handles bulk syncs (all open issues) and targeted updates (single issue URL or number) + +## Prerequisites + +- GitHub CLI (`gh`) must be installed and authenticated: `gh auth status` +- The project knowledge base must be set up at `knowledge-base/` (via the bootstrap prompt in [knowledge-base/README.md](../../knowledge-base/README.md)) + +## Setup + +### 1. Copy the agent file + +```bash +cp knowledge-base-manager.md /.claude/agents/knowledge-base-manager.md +``` + +No placeholders to replace — this agent has no `{{PLACEHOLDER}}` values. It works with any project's knowledge base structure out of the box. + +### 2. Register in your project's CLAUDE.md + +The bootstrap installation prompt (see `knowledge-base/README.md`) adds this automatically. If registering manually, add to your project's `CLAUDE.md`: + +```markdown +## Custom Agents + +| Agent | When to Use | +|-------|-------------| +| `knowledge-base-manager` | When the user wants to update the knowledge base from a GitHub issue, sync the active sprint, or reflect recent GitHub activity in the KB. | +``` + +## Usage + +Once set up, trigger the agent with natural language: + +``` +> update the knowledge base for this issue: https://github.com/org/repo/issues/42 +> update active sprint items in the knowledge base +> sync knowledge base with recent GitHub activity +> issue #88 is now in review — update the KB +``` + +## Issue State Mapping + +| GitHub State | Action | +|---|---| +| **Backlog** — open, no assignee, no in-progress label | Add to Active Issues table with status `Backlog` | +| **In Progress** — open with assignee or in-progress label | Add/update Active Issues row with status `In Progress` | +| **In Review** — has a linked open PR or review label | Update Active Issues row to `In Review`, link the PR | +| **Done / Closed** — issue state is `CLOSED` | Move from Active Issues to Completed This Sprint | + +## Token Efficiency + +The agent fetches GitHub data in a prioritized order and stops as soon as it has enough context: + +1. Issue title + labels + state + assignees (always fetched) +2. Issue body (only if Tier 1 is insufficient) +3. Linked PR search (only if state is In Review or Done) +4. Issue comments (only if Tier 3 returned nothing) +5. PR diffs / code analysis — **never fetched** unless the user explicitly requests it + +Most updates complete using only Tier 1 or Tier 1 + 2. diff --git a/claude/agents/knowledge-base-manager/knowledge-base-manager.md b/claude/agents/knowledge-base-manager/knowledge-base-manager.md new file mode 100644 index 0000000..0fdda3a --- /dev/null +++ b/claude/agents/knowledge-base-manager/knowledge-base-manager.md @@ -0,0 +1,174 @@ +--- +name: knowledge-base-manager +description: "Use this agent when the user wants to update the project knowledge base from a GitHub issue, sync the active sprint, or reflect recent GitHub activity in the KB. This is the only agent with write access to knowledge base files.\n\nExamples:\n\n- Example 1:\n user: \"update the knowledge base for this issue: https://github.com/org/repo/issues/42\"\n assistant: \"Let me launch the knowledge-base-manager agent to fetch the issue and update the relevant KB sections.\"\n \n\n- Example 2:\n user: \"sync knowledge base with recent GitHub activity\"\n assistant: \"I'll use the knowledge-base-manager agent to check open issues and sync the active sprint.\"\n \n\n- Example 3:\n user: \"update active sprint items in the knowledge base\"\n assistant: \"Let me use the knowledge-base-manager agent to refresh the active sprint section.\"\n \n\n- Example 4:\n user: \"issue #88 is now in review — update the KB\"\n assistant: \"I'll launch the knowledge-base-manager agent to update the sprint entry for issue #88.\"\n " + +model: sonnet +color: purple +memory: project +--- + +You are the sole maintainer of this project's AI knowledge base. You have full read and write access to all files under `knowledge-base/`. All other agents are strictly read-only. Your job is to keep the knowledge base accurate, deduplicated, and well-formatted after every GitHub issue state change. + +## Supported Prompt Patterns + +- `update the knowledge base for this issue: ` +- `update active sprint items in the knowledge base` +- `sync knowledge base with recent GitHub activity` +- `issue # is now — update the KB` + +--- + +## Step-by-Step Process + +### Step 1: Identify the Issue(s) + +- If a GitHub issue URL or number was provided, extract the issue number(s). +- If the user asked for a general sync (`update active sprint`, `sync with recent activity`): + ```bash + gh issue list --state open --limit 30 --json number,title,labels,assignees,state + ``` + Process each open issue against the current active sprint file. Also fetch recently closed issues to mark completions: + ```bash + gh issue list --state closed --limit 10 --json number,title,state,closedAt + ``` +- If no issue can be identified, use `AskUserQuestion` to ask the user for the GitHub issue URL or number before proceeding. + +--- + +### Step 2: Fetch Issue Data (Tiered — Stop When You Have Enough) + +Fetch GitHub data in order. Stop as soon as you have enough context to determine the issue state and act. + +**Tier 1 — Always fetch:** +```bash +gh issue view --json number,title,labels,state,assignees,milestone +``` + +**Tier 2 — Fetch if Tier 1 is insufficient to understand context:** +```bash +gh issue view --json body +``` + +**Tier 3 — Fetch only if issue state is In Review or Done/Closed:** +```bash +gh pr list --search "closes # OR fixes #" --json number,title,state,url +``` + +**Tier 4 — Fetch only if Tier 3 returned no results:** +```bash +gh issue view --json comments --jq '.comments[-5:]' +``` + +**Tier 5 — Never fetch unless explicitly requested by the user:** +- PR diffs or full code analysis. + +--- + +### Step 3: Determine Issue State + +Map the fetched data to one of four states: + +| State | Criteria | +|-------|---------| +| **Backlog** | Issue is open, no assignee, no in-progress or review label | +| **In Progress** | Issue is open with an assignee, or has a label matching `in progress`, `doing`, or `wip` | +| **In Review** | Issue has a linked open PR, or has a label matching `in review`, `review`, or `needs review` | +| **Done / Closed** | Issue `state` is `CLOSED` | + +If the data is ambiguous after Tier 2, use `AskUserQuestion` to ask the user which state applies. Never guess. + +--- + +### Step 4: Understand the File Structure Before Writing + +The knowledge base uses two types of files. You must never confuse them: + +| File type | Role | Write rule | +|-----------|------|-----------| +| `04-active-sprint/00-index.md` | **Content file** — the sprint tracking table lives here | Write sprint rows directly into this file | +| `01-business-flows/00-index.md` | **Index file** — lists flow names and links to individual flow files in the same folder | Only update the index table; never append flow content here | +| `02-architecture/00-index.md` | **Index file** — lists architectural decisions and links to individual decision files in the same folder | Only update the index table; never append decision content here | +| `03-risk-model/00-index.md` | **Index file** — lists risks and links to individual risk files in the same folder | Only update the index table; never append risk content here | + +**Rule:** Content (detailed descriptions, decision records, risk write-ups) lives in individual named files inside each section folder — not in `00-index.md`. The `00-index.md` for every section except `04-active-sprint` is a reference table only. + +Before making any edit to the sprint file, read `knowledge-base/04-active-sprint/00-index.md` in full. Locate any existing row for the issue number. This prevents duplication and tells you whether an update or an insert is needed. + +--- + +### Step 5: Act Based on State + +#### Backlog +- Add the issue to the **Active Issues** table if not already present. +- Set: Status = `Backlog`, Assignee = `—`, Notes = `—`. +- No other files are modified. + +#### In Progress +- If the issue already has a row in Active Issues: update Status to `In Progress`, set the Assignee to the GitHub username(s), add a brief progress note if available from the issue body. +- If the issue is not yet in the table: insert a new row. +- No other files are modified. + +#### In Review +- Update the issue's Active Issues row: set Status to `In Review`. +- In the Notes column, add the linked PR reference (e.g., `PR #88 open`). If no PR was found, write `In Review — PR link pending`. +- No other files are modified. + +#### Done / Closed +- Move the issue row from **Active Issues** to **Completed This Sprint**. + - Set `Completed On` to the issue's `closedAt` date, or today's date if unavailable. +- If the issue never appeared in Active Issues, insert it directly into Completed. +- **Optional promotion:** If the closed issue introduced a significant architectural decision or a risk/learning worth preserving long-term, promote it using this two-step process: + 1. **Create a new named file** inside the relevant section folder. Use a kebab-case filename derived from the issue title (e.g., `knowledge-base/02-architecture/payment-gateway-integration.md` or `knowledge-base/03-risk-model/bulk-delete-risks.md`). Write the decision or risk detail into that file. + 2. **Add a reference row** to the section's `00-index.md` pointing to the new file. Do not write any content into `00-index.md` itself — only add the index row. + + Only promote when the issue body or linked PR description **explicitly** describes a system-level decision or risk. Do not infer or fabricate. If unsure, skip promotion. + +--- + +### Step 6: Write Changes + +- Edit only the lines that need to change. Do not rewrite entire files. +- Preserve existing table alignment, column widths, and comment blocks. +- Never remove ` # Business Flows: {{PROJECT_NAME}} @@ -23,63 +25,21 @@ ## Flow Index -| Flow ID | Flow Name | Initiator | Outcome | -|---------|-----------|-----------|---------| -| BF-01 | {{FLOW_NAME_1}} | {{INITIATOR_1}} | {{OUTCOME_1}} | -| BF-02 | {{FLOW_NAME_2}} | {{INITIATOR_2}} | {{OUTCOME_2}} | - - - ---- - -## Flow Details - -### BF-01: {{FLOW_NAME_1}} - -**Initiator:** {{INITIATOR_1}} -**Trigger:** {{TRIGGER_CONDITION_1}} -**Expected Outcome:** {{OUTCOME_1}} - -**Steps:** -1. {{STEP_1}} -2. {{STEP_2}} -3. {{STEP_3}} +| Flow ID | Flow Name | Initiator | Outcome | File | +|---------|-----------|-----------|---------|------| +| BF-01 | {{FLOW_NAME_1}} | {{INITIATOR_1}} | {{OUTCOME_1}} | [bf-01-{{flow-slug-1}}.md](bf-01-{{flow-slug-1}}.md) | +| BF-02 | {{FLOW_NAME_2}} | {{INITIATOR_2}} | {{OUTCOME_2}} | [bf-02-{{flow-slug-2}}.md](bf-02-{{flow-slug-2}}.md) | -**Business Rules:** -- {{BUSINESS_RULE_1}} -- {{BUSINESS_RULE_2}} - -**Edge Cases / Exceptions:** -- {{EDGE_CASE_1}} - ---- - - + --- From 3a5a2066541ff4cc6c1bd3fde4caf4fa2e03a6a8 Mon Sep 17 00:00:00 2001 From: Anurag Kumawat Date: Fri, 6 Mar 2026 17:02:22 +0530 Subject: [PATCH 06/16] hybrid kb --- README.md | 15 +- claude/README.md | 44 ++--- .../business-analyst/business-analyst.md | 17 +- .../implementation-executor.md | 17 +- .../implementation-planner.md | 20 +- .../agents/knowledge-base-manager/README.md | 5 +- .../knowledge-base-manager.md | 65 ++++--- knowledge-base/GOVERNANCE.md | 58 ++++++ knowledge-base/README.md | 177 ++++++++---------- knowledge-base/REVIEW-CHECKLIST.md | 13 ++ knowledge-base/SPEC-RECONCILIATION.md | 80 ++++++++ knowledge-base/SPEC.md | 144 ++++++++++++++ knowledge-base/prompts/install-hybrid-kb.md | 43 +++++ .../scaffold_hybrid_kb.cpython-313.pyc | Bin 0 -> 7154 bytes .../sync_active_sprint.cpython-313.pyc | Bin 0 -> 9217 bytes .../validate_hybrid_kb.cpython-313.pyc | Bin 0 -> 4014 bytes knowledge-base/scripts/scaffold_hybrid_kb.py | 157 ++++++++++++++++ knowledge-base/scripts/sync_active_sprint.py | 146 +++++++++++++++ knowledge-base/scripts/validate_hybrid_kb.py | 88 +++++++++ knowledge-base/templates/.kb-config.yml | 34 ++++ knowledge-base/templates/00-index.md | 35 ++++ knowledge-base/templates/CLAUDE.section.md | 13 ++ knowledge-base/templates/README.md | 25 +++ knowledge-base/templates/active-sprint.md | 38 ++++ .../templates/advanced/decision-log.md | 16 ++ .../templates/advanced/feature-history.md | 11 ++ .../templates/advanced/incident-log.md | 11 ++ .../templates/advanced/integration-map.md | 8 + .../templates/advanced/known-constraints.md | 8 + knowledge-base/templates/advanced/metrics.md | 9 + knowledge-base/templates/architecture.md | 38 ++++ knowledge-base/templates/business-flows.md | 41 ++++ knowledge-base/templates/risks.md | 23 +++ .../workflows/sync-active-sprint.yml | 36 ++++ 34 files changed, 1255 insertions(+), 180 deletions(-) create mode 100644 knowledge-base/GOVERNANCE.md create mode 100644 knowledge-base/REVIEW-CHECKLIST.md create mode 100644 knowledge-base/SPEC-RECONCILIATION.md create mode 100644 knowledge-base/SPEC.md create mode 100644 knowledge-base/prompts/install-hybrid-kb.md create mode 100644 knowledge-base/scripts/__pycache__/scaffold_hybrid_kb.cpython-313.pyc create mode 100644 knowledge-base/scripts/__pycache__/sync_active_sprint.cpython-313.pyc create mode 100644 knowledge-base/scripts/__pycache__/validate_hybrid_kb.cpython-313.pyc create mode 100755 knowledge-base/scripts/scaffold_hybrid_kb.py create mode 100755 knowledge-base/scripts/sync_active_sprint.py create mode 100755 knowledge-base/scripts/validate_hybrid_kb.py create mode 100644 knowledge-base/templates/.kb-config.yml create mode 100644 knowledge-base/templates/00-index.md create mode 100644 knowledge-base/templates/CLAUDE.section.md create mode 100644 knowledge-base/templates/README.md create mode 100644 knowledge-base/templates/active-sprint.md create mode 100644 knowledge-base/templates/advanced/decision-log.md create mode 100644 knowledge-base/templates/advanced/feature-history.md create mode 100644 knowledge-base/templates/advanced/incident-log.md create mode 100644 knowledge-base/templates/advanced/integration-map.md create mode 100644 knowledge-base/templates/advanced/known-constraints.md create mode 100644 knowledge-base/templates/advanced/metrics.md create mode 100644 knowledge-base/templates/architecture.md create mode 100644 knowledge-base/templates/business-flows.md create mode 100644 knowledge-base/templates/risks.md create mode 100644 knowledge-base/workflows/sync-active-sprint.yml diff --git a/README.md b/README.md index 8c06e10..122fcfe 100644 --- a/README.md +++ b/README.md @@ -13,5 +13,16 @@ Individual projects opt into recipes by copying or referencing them. | 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 the knowledge base | -| Knowledge Base | [knowledge-base/](knowledge-base/) | Templatized AI knowledge base that installs into any project with a single prompt, giving agents structured project context (business flows, architecture, risk model, active sprint) | +| 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 flat-file templates, config, validation, and sprint-sync automation | + +## Hybrid Knowledge Base + +The current KB model is a hybrid starter kit: +- `engineering-recipes` owns the reusable contract, templates, scaffold tools, and automation 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. +- `active-sprint.md` is the primary automation target. + +Start with [knowledge-base/README.md](knowledge-base/README.md). diff --git a/claude/README.md b/claude/README.md index a1e324b..050451d 100644 --- a/claude/README.md +++ b/claude/README.md @@ -9,41 +9,23 @@ 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 knowledge base. No placeholders to configure. | +| [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. | -## 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. - -### Steps +## Knowledge Base Contract -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. +These agents now prefer the hybrid flat-file KB contract: +- entry file: `knowledge-base/00-index.md` +- runtime config: `knowledge-base/.kb-config.yml` +- core files: `architecture.md`, `business-flows.md`, `active-sprint.md`, `risks.md` -### Prompt +Legacy numbered KB layouts remain supported as a fallback for older projects. -``` -I want to set up Claude Code agents from the engineering-recipes repo into this project. - -Source repo: https://github.com/anuragk16/engineering-recipes (browse the `claude/agents/` directory for all available agents and their README). - -For each agent found there: +## Setting Up Agents in Your Project -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/.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. +> Run the install steps from your project's root directory so the agent can inspect that project directly. - | Agent | When to Use | - |-------|-------------| - | implementation-planner | When the user asks for an implementation plan, technical breakdown, or task planning for a feature or issue. | - +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. -After setup, show me a summary of what was configured and any values you'd recommend I review or adjust. -``` +For KB installation guidance, start with [knowledge-base/README.md](../knowledge-base/README.md). diff --git a/claude/agents/business-analyst/business-analyst.md b/claude/agents/business-analyst/business-analyst.md index 2d6b76f..0966bdc 100644 --- a/claude/agents/business-analyst/business-analyst.md +++ b/claude/agents/business-analyst/business-analyst.md @@ -35,13 +35,16 @@ You are an expert business analyst for {{PROJECT_NAME}}. Before reasoning about requirements, check for a project knowledge base: -1. Check if `knowledge-base/00-master.md` exists. - - If it does **not** exist: skip this entire section and proceed normally. -2. Read `knowledge-base/00-master.md`. -3. Load the following section — but **only** if it does not contain unfilled `TODO:` placeholders (skip if it has one or more `TODO:` lines): - - `knowledge-base/01-business-flows/00-index.md` -4. 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**. -5. Do **not** write to or modify any knowledge base file. +1. Prefer the hybrid entry file at `knowledge-base/00-index.md`. + - If it does **not** exist, fall back to `knowledge-base/00-master.md`. + - If neither 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/business-flows.md` when it exists and is complete. +5. If the project still uses the legacy layout, fall back to `knowledge-base/01-business-flows/00-index.md`. +6. Skip any KB file that is clearly incomplete or still full of placeholders / `TODO:` content. +7. 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**. +8. Do **not** write to or modify any knowledge base file. ## Domain Context diff --git a/claude/agents/implementation-executor/implementation-executor.md b/claude/agents/implementation-executor/implementation-executor.md index 9b2c163..584bd37 100644 --- a/claude/agents/implementation-executor/implementation-executor.md +++ b/claude/agents/implementation-executor/implementation-executor.md @@ -13,13 +13,16 @@ You are an expert software engineer and disciplined executor. You take structure Before reading the implementation plan or exploring the codebase, check for a project knowledge base: -1. Check if `knowledge-base/00-master.md` exists. - - If it does **not** exist: skip this entire section and proceed normally. -2. Read `knowledge-base/00-master.md`. -3. Load the following section — but **only** if it does not contain unfilled `TODO:` placeholders (skip if it has one or more `TODO:` lines): - - `knowledge-base/02-architecture/00-index.md` -4. 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**. -5. Do **not** write to or modify any knowledge base file. +1. Prefer the hybrid entry file at `knowledge-base/00-index.md`. + - If it does **not** exist, fall back to `knowledge-base/00-master.md`. + - If neither 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/architecture.md` when it exists and is complete. +5. If the project still uses the legacy layout, fall back to `knowledge-base/02-architecture/00-index.md`. +6. Skip any KB file that is clearly incomplete or still full of placeholders / `TODO:` content. +7. 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**. +8. Do **not** write to or modify any knowledge base file. ## Pre-requisites diff --git a/claude/agents/implementation-planner/implementation-planner.md b/claude/agents/implementation-planner/implementation-planner.md index a2d8117..1c6d6d7 100644 --- a/claude/agents/implementation-planner/implementation-planner.md +++ b/claude/agents/implementation-planner/implementation-planner.md @@ -13,14 +13,22 @@ You are an elite software architect and technical lead with deep expertise in {{ Before exploring the codebase or reasoning about the implementation, check for a project knowledge base: -1. Check if `knowledge-base/00-master.md` exists. - - If it does **not** exist: skip this entire section and proceed normally. -2. Read `knowledge-base/00-master.md`. -3. Load the following sections — but **only** if they do not contain unfilled `TODO:` placeholders (skip any section that has one or more `TODO:` lines): +1. Prefer the hybrid entry file at `knowledge-base/00-index.md`. + - If it does **not** exist, fall back to the legacy entry file at `knowledge-base/00-master.md`. + - If neither 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 hybrid files when present and complete: + - `knowledge-base/business-flows.md` + - `knowledge-base/architecture.md` + - `knowledge-base/active-sprint.md` +5. If the project is still on the legacy 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` -4. Use the loaded context to inform your plan — architectural rules, established patterns, and sprint priorities. If the knowledge base conflicts with explicit instructions in the user's prompt, **the user's prompt takes precedence**. -5. Do **not** write to or modify any knowledge base file. +6. Skip any KB file that is clearly incomplete or still full of placeholders / `TODO:` content. +7. 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**. +8. Do **not** write to or modify any knowledge base file. ## Multi-Repository Context diff --git a/claude/agents/knowledge-base-manager/README.md b/claude/agents/knowledge-base-manager/README.md index d72711d..7faf10b 100644 --- a/claude/agents/knowledge-base-manager/README.md +++ b/claude/agents/knowledge-base-manager/README.md @@ -6,7 +6,8 @@ A Claude Code agent that keeps the project knowledge base in sync with GitHub is - Fetches GitHub issue data in a tiered, token-efficient order (title + state first, body only if needed, PR only if in-review or done) - Maps each issue to one of four states: Backlog, In Progress, In Review, Done/Closed -- Updates `knowledge-base/04-active-sprint/00-index.md` without duplicating existing entries +- Updates the canonical sprint file at `knowledge-base/active-sprint.md` without duplicating existing entries +- Falls back to `knowledge-base/04-active-sprint/00-index.md` for legacy projects still on the numbered layout - Optionally promotes significant architectural decisions or risk learnings to the relevant KB sections when an issue is closed - Handles bulk syncs (all open issues) and targeted updates (single issue URL or number) @@ -37,6 +38,8 @@ The bootstrap installation prompt (see `knowledge-base/README.md`) adds this aut | `knowledge-base-manager` | When the user wants to update the knowledge base from a GitHub issue, sync the active sprint, or reflect recent GitHub activity in the KB. | ``` +If the project uses the hybrid KB contract, `knowledge-base/.kb-config.yml` is the runtime source of truth and the manager should prefer flat files over the legacy numbered layout. + ## Usage Once set up, trigger the agent with natural language: diff --git a/claude/agents/knowledge-base-manager/knowledge-base-manager.md b/claude/agents/knowledge-base-manager/knowledge-base-manager.md index 1123107..60228ea 100644 --- a/claude/agents/knowledge-base-manager/knowledge-base-manager.md +++ b/claude/agents/knowledge-base-manager/knowledge-base-manager.md @@ -7,7 +7,21 @@ color: purple memory: project --- -You are the sole maintainer of this project's AI knowledge base. You have full read and write access to all files under `knowledge-base/`. All other agents are strictly read-only. Your job is to keep the knowledge base accurate, deduplicated, and well-formatted after every GitHub issue state change. +You are the sole maintainer of this project's AI knowledge base. You have full read and write access to files under `knowledge-base/`. All other agents are strictly read-only. Your job is to keep the knowledge base accurate, deduplicated, and well-formatted after every GitHub issue state change. + +## KB Contract Detection + +Before writing anything: + +1. Prefer the hybrid flat-file contract: + - entry file: `knowledge-base/00-index.md` + - sprint file: `knowledge-base/active-sprint.md` + - runtime config: `knowledge-base/.kb-config.yml` +2. If the hybrid contract is absent, fall back to the legacy numbered layout: + - `knowledge-base/00-master.md` + - `knowledge-base/04-active-sprint/00-index.md` +3. If neither contract is present, stop and tell the user that the knowledge base has not been set up yet. +4. Treat `active-sprint` as the primary automation target. Do not rewrite human-owned architecture or business-flow content unless the user explicitly asks you to do so. ## Supported Prompt Patterns @@ -87,34 +101,23 @@ The knowledge base uses two types of files. You must never confuse them: | File type | Role | Write rule | |-----------|------|-----------| -| `04-active-sprint/00-index.md` | **Content file** — the sprint tracking table lives here | Write sprint rows directly into this file | -| `01-business-flows/00-index.md` | **Index file** — one row per flow, linking to individual flow files | Only add/update a row in the index table; **never write flow details here** | -| `02-architecture/00-index.md` | **Index file** — one row per decision, linking to individual decision files | Only add/update a row in the index table; never write decision content here | -| `03-risk-model/00-index.md` | **Index file** — one row per risk, linking to individual risk files | Only add/update a row in the index table; never write risk content here | - -**Rule:** All content (flow details, decision records, risk write-ups) lives in individual named files inside each section folder — never in `00-index.md`. The `00-index.md` for every section except `04-active-sprint` is a reference table only. +| `active-sprint.md` | **Canonical V1 content file** — the sprint tracking table lives here | Write or regenerate auto-managed sprint sections here | +| `04-active-sprint/00-index.md` | **Legacy sprint file** | Only use when the canonical V1 sprint file is absent | +| `business-flows.md`, `architecture.md`, `risks.md` | Human-owned Tier 1 KB files | Do not rewrite automatically unless the user explicitly requests it | +| `advanced/*.md` | Optional Tier 2 files | Append only when the user asks or when the workflow explicitly calls for it | -**Business flows naming convention:** Individual flow files are named `bf-XX-.md` (e.g., `bf-03-password-reset.md`). - -Before making any edit to the sprint file, read `knowledge-base/04-active-sprint/00-index.md` in full. Locate any existing row for the issue number. This prevents duplication and tells you whether an update or an insert is needed. +Before making any sprint edit, read the target sprint file in full. Locate any existing row or generated section entry for the issue number. This prevents duplication and tells you whether to update or regenerate. --- -### Step 4b: Adding or Updating a Business Flow (Non-Issue Prompt) - -If the user asks you to add, document, or update business flow content (not triggered by a GitHub issue state change), follow this two-step process: - -1. **Create or update the individual flow file:** - - Check if a `bf-XX-.md` file already exists in `knowledge-base/01-business-flows/` for this flow. - - If it does not exist: determine the next available BF ID by reading `00-index.md`, then create `knowledge-base/01-business-flows/bf-XX-.md`. Write the flow details (steps, business rules, edge cases) into this file only. - - If it already exists: update only the changed sections within that file. - - Never write flow steps, business rules, or any narrative content into `00-index.md`. +### Step 4b: Non-Sprint KB Edits -2. **Update the index:** - - Add or update exactly one row in `knowledge-base/01-business-flows/00-index.md` for this flow: Flow ID, Flow Name, Initiator, Outcome, and a relative link to the flow file. - - Do not modify any other row in the index. +If the user explicitly asks you to edit a human-owned KB file: -**Token efficiency note:** When a consuming agent (e.g., business-analyst) needs to read business flows, it reads `00-index.md` first to see what flows exist, then loads only the specific `bf-XX-*.md` file(s) relevant to its task. Keeping `00-index.md` as a pure index is what makes this selective loading possible. +1. Detect whether the project uses the hybrid flat-file contract or the legacy numbered layout. +2. Update only the requested file(s). +3. Prefer append-only edits for Tier 2 logs such as `advanced/decision-log.md` and `advanced/incident-log.md`. +4. Do not refactor or rewrite unrelated KB content while making the requested change. --- @@ -149,12 +152,12 @@ If the user asks you to add, document, or update business flow content (not trig ### Step 6: Write Changes -- Edit only the lines that need to change. Do not rewrite entire files. -- Preserve existing table alignment, column widths, and comment blocks. -- Never remove `" +ACTIVE_END = "" +BLOCKERS_START = "" +BLOCKERS_END = "" +DONE_START = "" +DONE_END = "" + + +@dataclass +class IssueRow: + number: int + title: str + status: str + assignee: str + note: str + + +@dataclass +class DoneRow: + ref: str + title: str + completed_on: str + + +def run_gh(args: list[str]) -> list[dict]: + result = subprocess.run(["gh", *args], check=True, capture_output=True, text=True) + return json.loads(result.stdout) + + +def detect_status(issue: dict) -> str: + if issue.get("state") == "CLOSED": + return "Done" + labels = {label["name"].lower() for label in issue.get("labels", [])} + if any(label in labels for label in {"in review", "review", "needs review"}): + return "In Review" + if issue.get("assignees") or any(label in labels for label in {"in progress", "doing", "wip"}): + return "In Progress" + return "Backlog" + + +def replace_section(text: str, start: str, end: str, body: str) -> str: + if start not in text or end not in text: + raise ValueError(f"markers not found: {start} / {end}") + prefix, rest = text.split(start, 1) + _, suffix = rest.split(end, 1) + return prefix + start + "\n" + body.rstrip() + "\n" + end + suffix + + +def render_active(rows: list[IssueRow]) -> str: + lines = ["| Issue | Title | Status | Assignee | Note |", "|---|---|---|---|---|"] + for row in rows: + lines.append(f"| #{row.number} | {row.title} | {row.status} | {row.assignee} | {row.note} |") + return "\n".join(lines) + + +def render_blockers(rows: list[IssueRow]) -> str: + lines = ["| Issue | Blocker | Owner |", "|---|---|---|"] + for row in rows: + lines.append(f"| #{row.number} | {row.note or 'Label / blocker details missing'} | {row.assignee} |") + return "\n".join(lines) + + +def render_done(rows: list[DoneRow]) -> str: + lines = ["| Issue / PR | Title | Completed On |", "|---|---|---|"] + for row in rows: + lines.append(f"| {row.ref} | {row.title} | {row.completed_on} |") + return "\n".join(lines) + + +def choose_sprint_file(project_root: Path) -> Path: + canonical = project_root / "knowledge-base/active-sprint.md" + legacy = project_root / "knowledge-base/04-active-sprint/00-index.md" + if canonical.exists(): + return canonical + if legacy.exists(): + return legacy + raise FileNotFoundError("No sprint file found in canonical or legacy location") + + +def main() -> int: + parser = argparse.ArgumentParser(description="Sync the active sprint file from GitHub issues") + parser.add_argument("project_root", help="Path to the target project root") + parser.add_argument("--repo", required=True, help="GitHub repository in owner/name format") + parser.add_argument("--open-limit", type=int, default=30) + parser.add_argument("--closed-limit", type=int, default=10) + args = parser.parse_args() + + project_root = Path(args.project_root).resolve() + sprint_file = choose_sprint_file(project_root) + + open_issues = run_gh([ + "issue", "list", + "--repo", args.repo, + "--state", "open", + "--limit", str(args.open_limit), + "--json", "number,title,labels,assignees,state", + ]) + closed_issues = run_gh([ + "issue", "list", + "--repo", args.repo, + "--state", "closed", + "--limit", str(args.closed_limit), + "--json", "number,title,closedAt", + ]) + + active_rows = [] + blocker_rows = [] + for issue in open_issues: + status = detect_status(issue) + assignees = issue.get("assignees", []) + assignee = ", ".join(person["login"] for person in assignees) if assignees else "—" + labels = {label["name"].lower() for label in issue.get("labels", [])} + note = "" + if "blocked" in labels or "on hold" in labels: + note = "Blocked / on hold" + blocker_rows.append(IssueRow(issue["number"], issue["title"], status, assignee, note)) + active_rows.append(IssueRow(issue["number"], issue["title"], status, assignee, note or "—")) + + done_rows = [DoneRow(f"#{issue['number']}", issue["title"], issue.get("closedAt", "")[:10] or "—") for issue in closed_issues] + + text = sprint_file.read_text() + text = replace_section(text, ACTIVE_START, ACTIVE_END, render_active(active_rows)) + text = replace_section(text, BLOCKERS_START, BLOCKERS_END, render_blockers(blocker_rows)) + text = replace_section(text, DONE_START, DONE_END, render_done(done_rows)) + sprint_file.write_text(text) + + print(f"updated {sprint_file}") + return 0 + + +if __name__ == "__main__": + try: + raise SystemExit(main()) + except subprocess.CalledProcessError as exc: + print(exc.stderr or str(exc), file=sys.stderr) + raise SystemExit(exc.returncode) diff --git a/knowledge-base/scripts/validate_hybrid_kb.py b/knowledge-base/scripts/validate_hybrid_kb.py new file mode 100755 index 0000000..83eedcc --- /dev/null +++ b/knowledge-base/scripts/validate_hybrid_kb.py @@ -0,0 +1,88 @@ +#!/usr/bin/env python3 +from __future__ import annotations + +import argparse +import sys +from pathlib import Path + +REQUIRED_FILES = [ + "knowledge-base/00-index.md", + "knowledge-base/architecture.md", + "knowledge-base/business-flows.md", + "knowledge-base/active-sprint.md", + "knowledge-base/risks.md", + "knowledge-base/.kb-config.yml", +] +OPTIONAL_BY_KEY = { + "decision-log": "knowledge-base/advanced/decision-log.md", + "incident-log": "knowledge-base/advanced/incident-log.md", + "feature-history": "knowledge-base/advanced/feature-history.md", + "integration-map": "knowledge-base/advanced/integration-map.md", + "metrics": "knowledge-base/advanced/metrics.md", + "known-constraints": "knowledge-base/advanced/known-constraints.md", +} + + +def read_enabled_tier2(config_path: Path) -> list[str]: + enabled = [] + in_block = False + for raw in config_path.read_text().splitlines(): + line = raw.rstrip() + stripped = line.strip() + if stripped == "enabled_tier2:": + in_block = True + continue + if in_block: + if stripped.startswith("-"): + enabled.append(stripped[1:].strip()) + continue + if stripped and not raw.startswith(" "): + break + return enabled + + +def main() -> int: + parser = argparse.ArgumentParser(description="Validate a hybrid KB installation") + parser.add_argument("project_root", help="Path to the target project root") + args = parser.parse_args() + + root = Path(args.project_root).resolve() + errors = [] + + for rel in REQUIRED_FILES: + path = root / rel + if not path.exists(): + errors.append(f"missing required file: {rel}") + + config_path = root / "knowledge-base/.kb-config.yml" + if config_path.exists(): + contents = config_path.read_text() + for key in ["version:", "source_of_truth:", "loading_defaults:", "auto_update:"]: + if key not in contents: + errors.append(f"missing config key: {key.rstrip(':')}") + for module in read_enabled_tier2(config_path): + rel = OPTIONAL_BY_KEY.get(module) + if rel is None: + errors.append(f"unknown enabled Tier 2 module in config: {module}") + elif not (root / rel).exists(): + errors.append(f"enabled Tier 2 file missing: {rel}") + + entry = root / "knowledge-base/00-index.md" + if entry.exists(): + entry_text = entry.read_text() + for ref in ["architecture.md", "business-flows.md", "active-sprint.md", "risks.md"]: + if ref not in entry_text: + errors.append(f"entry file does not reference: {ref}") + + if errors: + print("Hybrid KB validation failed:") + for error in errors: + print(f"- {error}") + return 1 + + print("Hybrid KB validation passed.") + return 0 + + +if __name__ == "__main__": + raise SystemExit(main()) diff --git a/knowledge-base/templates/.kb-config.yml b/knowledge-base/templates/.kb-config.yml new file mode 100644 index 0000000..9f3bc32 --- /dev/null +++ b/knowledge-base/templates/.kb-config.yml @@ -0,0 +1,34 @@ +version: 1 +source_of_truth: kb-config +project: + name: "{{PROJECT_NAME}}" + summary: "{{PROJECT_SUMMARY}}" +enabled_tier2: + # Add optional module keys here when enabled for the project. +loading_defaults: + code_review: + - architecture.md + - risks.md + planning: + - business-flows.md + - architecture.md + - active-sprint.md + sprint_work: + - active-sprint.md + onboarding: + - 00-index.md + - architecture.md + - business-flows.md + - active-sprint.md + - risks.md + incident_response: + - risks.md + - advanced/incident-log.md +auto_update: + active_sprint: + mode: hybrid + schedule: weekly + owner: knowledge-base-manager +compatibility: + legacy_entrypoint: knowledge-base/00-master.md + legacy_sprint_file: knowledge-base/04-active-sprint/00-index.md diff --git a/knowledge-base/templates/00-index.md b/knowledge-base/templates/00-index.md new file mode 100644 index 0000000..be916e8 --- /dev/null +++ b/knowledge-base/templates/00-index.md @@ -0,0 +1,35 @@ +# Knowledge Base Index: {{PROJECT_NAME}} + +## Purpose +This is the only required first read for agents. Keep it short. + +## Project Snapshot +- Project: {{PROJECT_NAME}} +- One-line summary: {{PROJECT_SUMMARY}} +- Primary stack: {{PRIMARY_STACK}} +- Owners: {{PROJECT_OWNERS}} +- KB version: 1 + +## Files +- `architecture.md`: System boundaries, module map, and non-negotiable architecture rules. +- `business-flows.md`: Core user journeys and business rules that affect implementation. +- `active-sprint.md`: Current delivery state, active work, blockers, and recently completed items. +- `risks.md`: Known technical, operational, and security-sensitive risks. +- `advanced/decision-log.md`: Optional. Append-only architecture and product decisions. +- `advanced/incident-log.md`: Optional. Append-only incident summaries and prevention notes. +- `advanced/feature-history.md`: Optional. Shipped feature history and notable outcomes. +- `advanced/integration-map.md`: Optional. External systems, auth methods, and failure surfaces. +- `advanced/metrics.md`: Optional. Baseline metrics and SLO/SLA context. +- `advanced/known-constraints.md`: Optional. Hard technical, contractual, or regulatory constraints. + +## Loading Rules +- Code review: load `architecture.md`, `risks.md` +- Planning: load `business-flows.md`, `architecture.md`, `active-sprint.md` +- Sprint work: load `active-sprint.md` +- Onboarding: load all Tier 1 files +- Incident response: load `risks.md`, then `advanced/incident-log.md` if enabled + +## Writing Rules +- Treat KB content as read-only unless you are the designated KB maintenance flow. +- Prefer `.kb-config.yml` as the runtime source of truth for enabled advanced modules. +- If this flat-file contract is absent, legacy projects may still use `00-master.md` and the numbered directories. diff --git a/knowledge-base/templates/CLAUDE.section.md b/knowledge-base/templates/CLAUDE.section.md new file mode 100644 index 0000000..750c733 --- /dev/null +++ b/knowledge-base/templates/CLAUDE.section.md @@ -0,0 +1,13 @@ +## Knowledge Base + +This project stores structured context in `knowledge-base/`. + +### Reading Rules +- Read `knowledge-base/00-index.md` first. +- If `knowledge-base/.kb-config.yml` exists, use it as the source of truth for enabled modules and loading defaults. +- Load only the files needed for the current task. +- Treat KB files as read-only unless you are the designated KB maintenance flow. +- If the flat-file KB does not exist, you may fall back to the legacy numbered layout if present. + +### Graceful Degradation +If no knowledge base exists, proceed normally without KB-aware behavior. diff --git a/knowledge-base/templates/README.md b/knowledge-base/templates/README.md new file mode 100644 index 0000000..09e9170 --- /dev/null +++ b/knowledge-base/templates/README.md @@ -0,0 +1,25 @@ +# Templates + +These templates are copied into downstream projects. + +## Core templates +- `00-index.md` +- `architecture.md` +- `business-flows.md` +- `active-sprint.md` +- `risks.md` +- `.kb-config.yml` +- `CLAUDE.section.md` + +## Optional advanced templates +- `advanced/decision-log.md` +- `advanced/incident-log.md` +- `advanced/feature-history.md` +- `advanced/integration-map.md` +- `advanced/metrics.md` +- `advanced/known-constraints.md` + +## Authoring rules +- Keep Tier 1 concise and task-oriented. +- Treat Tier 2 as opt-in and mostly append-only. +- Keep KB content plain Markdown plus lightweight config. diff --git a/knowledge-base/templates/active-sprint.md b/knowledge-base/templates/active-sprint.md new file mode 100644 index 0000000..89f87fc --- /dev/null +++ b/knowledge-base/templates/active-sprint.md @@ -0,0 +1,38 @@ +# Active Sprint: {{PROJECT_NAME}} + +## Purpose +Track current delivery state with minimal maintenance. This is the primary automation target. + +## Ownership +- Default owner: KB sync automation +- Human review: engineering or delivery lead + +## Sprint Snapshot +- Sprint / cycle: {{SPRINT_NAME}} +- Goal: {{SPRINT_GOAL}} +- Period: {{SPRINT_PERIOD}} +- Update mode: see `.kb-config.yml` + +## Manual Notes +- {{MANUAL_NOTE_1}} + +## Active Items + +| Issue | Title | Status | Assignee | Note | +|---|---|---|---|---| +| #{{ISSUE_1}} | {{ISSUE_TITLE_1}} | {{ISSUE_STATUS_1}} | {{ISSUE_ASSIGNEE_1}} | {{ISSUE_NOTE_1}} | + + +## Blockers + +| Issue | Blocker | Owner | +|---|---|---| +| #{{BLOCKED_ISSUE_1}} | {{BLOCKER_1}} | {{BLOCKER_OWNER_1}} | + + +## Recently Completed + +| Issue / PR | Title | Completed On | +|---|---|---| +| #{{DONE_1}} | {{DONE_TITLE_1}} | {{DONE_DATE_1}} | + diff --git a/knowledge-base/templates/advanced/decision-log.md b/knowledge-base/templates/advanced/decision-log.md new file mode 100644 index 0000000..e7e7dd9 --- /dev/null +++ b/knowledge-base/templates/advanced/decision-log.md @@ -0,0 +1,16 @@ +# Decision Log: {{PROJECT_NAME}} + +## Purpose +Append-only record of notable architecture or product decisions. + +## Rules +- Append newest entries at the top +- Keep each entry under 6 bullets +- Record context, decision, and trade-off only + +## Entry Template +### {{DATE}}: {{DECISION_TITLE}} +- Context: {{DECISION_CONTEXT}} +- Decision: {{DECISION_TAKEN}} +- Trade-off: {{DECISION_TRADEOFF}} +- Follow-up: {{DECISION_FOLLOWUP}} diff --git a/knowledge-base/templates/advanced/feature-history.md b/knowledge-base/templates/advanced/feature-history.md new file mode 100644 index 0000000..f094bac --- /dev/null +++ b/knowledge-base/templates/advanced/feature-history.md @@ -0,0 +1,11 @@ +# Feature History: {{PROJECT_NAME}} + +## Purpose +Compact record of meaningful shipped features and their outcomes. + +## Entry Template +### {{DATE}}: {{FEATURE_NAME}} +- Intent: {{FEATURE_INTENT}} +- Scope shipped: {{FEATURE_SCOPE}} +- Outcome: {{FEATURE_OUTCOME}} +- Follow-up: {{FEATURE_FOLLOWUP}} diff --git a/knowledge-base/templates/advanced/incident-log.md b/knowledge-base/templates/advanced/incident-log.md new file mode 100644 index 0000000..195a32a --- /dev/null +++ b/knowledge-base/templates/advanced/incident-log.md @@ -0,0 +1,11 @@ +# Incident Log: {{PROJECT_NAME}} + +## Purpose +Append-only record of incidents, regressions, or reliability events that should inform future work. + +## Entry Template +### {{DATE}}: {{INCIDENT_TITLE}} +- Symptom: {{INCIDENT_SYMPTOM}} +- Root cause: {{INCIDENT_ROOT_CAUSE}} +- Fix: {{INCIDENT_FIX}} +- Prevention: {{INCIDENT_PREVENTION}} diff --git a/knowledge-base/templates/advanced/integration-map.md b/knowledge-base/templates/advanced/integration-map.md new file mode 100644 index 0000000..c43854f --- /dev/null +++ b/knowledge-base/templates/advanced/integration-map.md @@ -0,0 +1,8 @@ +# Integration Map: {{PROJECT_NAME}} + +## Purpose +List only the external systems and cross-boundary dependencies that materially affect reliability or implementation. + +| System | Purpose | Auth | Failure mode | Fallback / Owner | +|---|---|---|---|---| +| {{SYSTEM_1}} | {{PURPOSE_1}} | {{AUTH_1}} | {{FAILURE_1}} | {{FALLBACK_1}} | diff --git a/knowledge-base/templates/advanced/known-constraints.md b/knowledge-base/templates/advanced/known-constraints.md new file mode 100644 index 0000000..5066cc1 --- /dev/null +++ b/knowledge-base/templates/advanced/known-constraints.md @@ -0,0 +1,8 @@ +# Known Constraints: {{PROJECT_NAME}} + +## Purpose +Document hard constraints that should not be rediscovered repeatedly. + +- {{CONSTRAINT_1}} +- {{CONSTRAINT_2}} +- {{CONSTRAINT_3}} diff --git a/knowledge-base/templates/advanced/metrics.md b/knowledge-base/templates/advanced/metrics.md new file mode 100644 index 0000000..d330536 --- /dev/null +++ b/knowledge-base/templates/advanced/metrics.md @@ -0,0 +1,9 @@ +# Metrics: {{PROJECT_NAME}} + +## Purpose +Capture a few baseline metrics so teams and agents understand normal operating context. + +| Metric | Baseline | Trend | Notes | +|---|---|---|---| +| {{METRIC_1}} | {{BASELINE_1}} | {{TREND_1}} | {{NOTES_1}} | +| {{METRIC_2}} | {{BASELINE_2}} | {{TREND_2}} | {{NOTES_2}} | diff --git a/knowledge-base/templates/architecture.md b/knowledge-base/templates/architecture.md new file mode 100644 index 0000000..490fcec --- /dev/null +++ b/knowledge-base/templates/architecture.md @@ -0,0 +1,38 @@ +# Architecture: {{PROJECT_NAME}} + +## Purpose +Capture the current architectural shape in a compact, implementation-facing format. + +## Brevity Rules +- Target: under 250 lines +- Prefer tables and short bullets +- Do not paste full schemas or long narratives + +## Stack Summary +| Layer | Technology | Notes | +|---|---|---| +| Frontend | {{FRONTEND_TECH}} | {{FRONTEND_NOTES}} | +| Backend | {{BACKEND_TECH}} | {{BACKEND_NOTES}} | +| Data | {{DATA_TECH}} | {{DATA_NOTES}} | +| Infra / Runtime | {{INFRA_TECH}} | {{INFRA_NOTES}} | + +## Module Map +| Module / Directory | Responsibility | Must Not Contain | +|---|---|---| +| {{MODULE_1}} | {{RESPONSIBILITY_1}} | {{FORBIDDEN_1}} | +| {{MODULE_2}} | {{RESPONSIBILITY_2}} | {{FORBIDDEN_2}} | +| {{MODULE_3}} | {{RESPONSIBILITY_3}} | {{FORBIDDEN_3}} | + +## Integration Points +| System | Purpose | Auth / Trust Boundary | +|---|---|---| +| {{INTEGRATION_1}} | {{PURPOSE_1}} | {{AUTH_1}} | + +## Non-Negotiable Rules +- {{ARCH_RULE_1}} +- {{ARCH_RULE_2}} +- {{ARCH_RULE_3}} + +## Example Entry Style +- Good: "Business logic lives in services; controllers stay thin." +- Bad: multi-paragraph history of why services exist. diff --git a/knowledge-base/templates/business-flows.md b/knowledge-base/templates/business-flows.md new file mode 100644 index 0000000..203f00e --- /dev/null +++ b/knowledge-base/templates/business-flows.md @@ -0,0 +1,41 @@ +# Business Flows: {{PROJECT_NAME}} + +## Purpose +Describe the core user journeys and business rules that materially affect implementation and review. + +## Brevity Rules +- Target: under 200 lines +- Use numbered flows, not prose essays +- Include only flows that change engineering decisions + +## Roles +- {{ROLE_1}} +- {{ROLE_2}} +- {{ROLE_3}} + +## Core Flows +### BF-01: {{FLOW_NAME_1}} +- Initiator: {{FLOW_INITIATOR_1}} +- Outcome: {{FLOW_OUTCOME_1}} +- Steps: + 1. {{FLOW_STEP_1A}} + 2. {{FLOW_STEP_1B}} + 3. {{FLOW_STEP_1C}} +- Business rules: + - {{FLOW_RULE_1A}} + - {{FLOW_RULE_1B}} + +### BF-02: {{FLOW_NAME_2}} +- Initiator: {{FLOW_INITIATOR_2}} +- Outcome: {{FLOW_OUTCOME_2}} +- Steps: + 1. {{FLOW_STEP_2A}} + 2. {{FLOW_STEP_2B}} + 3. {{FLOW_STEP_2C}} +- Business rules: + - {{FLOW_RULE_2A}} + - {{FLOW_RULE_2B}} + +## Example Entry Style +- Good: short numbered steps with explicit roles and outcome. +- Bad: implementation details, endpoint names, or DB schema notes. diff --git a/knowledge-base/templates/risks.md b/knowledge-base/templates/risks.md new file mode 100644 index 0000000..37dc81a --- /dev/null +++ b/knowledge-base/templates/risks.md @@ -0,0 +1,23 @@ +# Risks: {{PROJECT_NAME}} + +## Purpose +Capture the small set of risks that should influence planning, implementation, testing, and review. + +## Brevity Rules +- Target: under 150 lines +- Keep this list curated +- Prefer actionable risk statements over generic warnings + +## Risk Register +| Risk ID | Area | Level | Why it matters | Required caution | +|---|---|---|---|---| +| R-01 | {{RISK_AREA_1}} | {{RISK_LEVEL_1}} | {{RISK_REASON_1}} | {{RISK_CAUTION_1}} | +| R-02 | {{RISK_AREA_2}} | {{RISK_LEVEL_2}} | {{RISK_REASON_2}} | {{RISK_CAUTION_2}} | + +## Security / Sensitive Data Rules +- {{SENSITIVE_RULE_1}} +- {{SENSITIVE_RULE_2}} + +## Example Entry Style +- Good: "Auth/session changes are high risk because they affect all users and rollback is hard." +- Bad: generic "security is important" statements. diff --git a/knowledge-base/workflows/sync-active-sprint.yml b/knowledge-base/workflows/sync-active-sprint.yml new file mode 100644 index 0000000..69c9b39 --- /dev/null +++ b/knowledge-base/workflows/sync-active-sprint.yml @@ -0,0 +1,36 @@ +name: Sync Active Sprint + +on: + workflow_dispatch: + schedule: + - cron: "0 9 * * 1" + +jobs: + sync: + runs-on: ubuntu-latest + permissions: + issues: read + pull-requests: read + contents: write + steps: + - uses: actions/checkout@v4 + - uses: actions/setup-python@v5 + with: + python-version: "3.11" + - name: Authenticate gh + env: + GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} + run: gh auth status + - name: Sync sprint file + env: + GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} + run: | + python knowledge-base/scripts/sync_active_sprint.py . --repo ${{ github.repository }} + - name: Commit changes + run: | + git config user.name github-actions + git config user.email github-actions@github.com + git diff --quiet && exit 0 + git add knowledge-base/active-sprint.md knowledge-base/04-active-sprint/00-index.md || true + git commit -m "chore: sync active sprint" + git push From d9359b5385bf1ca00352f763c0c482fbd97a5b11 Mon Sep 17 00:00:00 2001 From: Anurag Kumawat Date: Fri, 6 Mar 2026 17:17:03 +0530 Subject: [PATCH 07/16] fix --- claude/README.md | 58 +++++++++++++++++++++ knowledge-base/prompts/install-hybrid-kb.md | 2 +- 2 files changed, 59 insertions(+), 1 deletion(-) diff --git a/claude/README.md b/claude/README.md index 050451d..1bbbc14 100644 --- a/claude/README.md +++ b/claude/README.md @@ -28,4 +28,62 @@ Legacy numbered KB layouts remain supported as a fallback for older projects. 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. +## Copy-Paste Install Prompt + +Paste the following prompt into your coding agent session from the target project's root directory: + +```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: + +1. Explore this project's codebase shallowly: + - README + - top-level config files + - top-level directory structure + - existing `CLAUDE.md` if present + +2. Ensure `.claude/agents/` exists in this project. + - Create it if missing. + +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 + +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 + +5. Check whether this project already has a hybrid knowledge base: + - `knowledge-base/00-index.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). diff --git a/knowledge-base/prompts/install-hybrid-kb.md b/knowledge-base/prompts/install-hybrid-kb.md index 6002eb3..3d825f9 100644 --- a/knowledge-base/prompts/install-hybrid-kb.md +++ b/knowledge-base/prompts/install-hybrid-kb.md @@ -3,7 +3,7 @@ Paste the following prompt into the target project's coding agent session from the project root. ```text -I want to install the hybrid knowledge base starter kit from the `engineering-recipes` repository into this project. +I want to install the hybrid knowledge base starter kit from the `https://github.com/anuragk16/engineering-recipes` repository into this project. Source directory to read from: - `knowledge-base/templates/` From ba9babbdb71f5e3a47472502f108ba662fe7b94c Mon Sep 17 00:00:00 2001 From: Anurag Kumawat Date: Fri, 6 Mar 2026 19:18:50 +0530 Subject: [PATCH 08/16] removed the workflow --- knowledge-base/README.md | 8 ++-- knowledge-base/SPEC-RECONCILIATION.md | 10 ++--- knowledge-base/SPEC.md | 6 +-- knowledge-base/prompts/install-hybrid-kb.md | 15 +++++++- .../scaffold_hybrid_kb.cpython-313.pyc | Bin 7154 -> 6682 bytes knowledge-base/scripts/scaffold_hybrid_kb.py | 15 -------- .../workflows/sync-active-sprint.yml | 36 ------------------ 7 files changed, 25 insertions(+), 65 deletions(-) delete mode 100644 knowledge-base/workflows/sync-active-sprint.yml diff --git a/knowledge-base/README.md b/knowledge-base/README.md index b147886..23b0db2 100644 --- a/knowledge-base/README.md +++ b/knowledge-base/README.md @@ -11,7 +11,7 @@ This directory contains the V1 hybrid knowledge-base starter kit for project-loc - Tier 1 and Tier 2 templates under [`templates/`](templates/) - A scaffold script for installing the KB into another project - A validation script for checking a KB installation -- An active sprint sync script and example workflow template +- An active sprint sync script for manual or agent-driven updates - A copy-paste install prompt for agent-based setup ## Canonical V1 Layout @@ -63,8 +63,7 @@ knowledge-base/ ```bash python knowledge-base/scripts/scaffold_hybrid_kb.py /path/to/target-project \ - --enable decision-log,incident-log \ - --with-workflow + --enable decision-log,incident-log ``` ### Validate an installed KB @@ -89,7 +88,8 @@ python knowledge-base/scripts/sync_active_sprint.py /path/to/project --repo owne ### Scheduled sync -See [workflows/sync-active-sprint.yml](workflows/sync-active-sprint.yml) for a weekly + manual-dispatch example, or install it directly with `--with-workflow`. +No workflow template is shipped in `engineering-recipes`. +If a downstream project wants scheduled sync, it should add its own automation around `knowledge-base/scripts/sync_active_sprint.py`. ## Legacy Compatibility diff --git a/knowledge-base/SPEC-RECONCILIATION.md b/knowledge-base/SPEC-RECONCILIATION.md index adc77d0..78e62f4 100644 --- a/knowledge-base/SPEC-RECONCILIATION.md +++ b/knowledge-base/SPEC-RECONCILIATION.md @@ -14,7 +14,7 @@ This note reconciles the pre-existing `engineering-recipes` knowledge-base recip | Runtime contract | Mostly documented in `CLAUDE.md` | `.kb-config.yml` plus mirrored `CLAUDE.md` guidance | `.kb-config.yml` is source of truth; `CLAUDE.md` mirrors read rules | | Sprint file | `04-active-sprint/00-index.md` | `active-sprint.md` | Standardize on `active-sprint.md`; updater supports legacy fallback | | Advanced memory | Not formalized as optional modules | Tier 2 optional modules | Add as explicit optional templates | -| Automation | Agent-only guidance | Agent plus reusable updater script/workflow | Implement reusable script and workflow template | +| Automation | Agent-only guidance | Agent plus reusable updater script | Implement reusable sync script; downstream projects may add their own scheduling | ## Decision Gates and Frozen Outcomes @@ -41,9 +41,9 @@ This note reconciles the pre-existing `engineering-recipes` knowledge-base recip - **Follow-up:** frontend can be added after backend validation. ### DG-6: Automation cadence -- **Decision:** hybrid cadence. -- **Supported modes:** on-demand sync, scheduled weekly sync, and workflow dispatch. -- **V1 default recommendation:** on-demand plus weekly scheduled sync. +- **Decision:** manual / agent-driven cadence. +- **Supported modes in this repo:** on-demand sync via script or KB maintenance agent. +- **Note:** downstream projects may add their own scheduling separately. ## Migration Impact @@ -73,7 +73,7 @@ Implemented in this repo: - `.kb-config.yml` contract - scaffold prompt and reusable scripts - agent documentation updates -- updater workflow template +- manual sprint sync helper Not implemented in this repo: - direct migration of Sneha or IAGES repositories diff --git a/knowledge-base/SPEC.md b/knowledge-base/SPEC.md index 96e089d..765963d 100644 --- a/knowledge-base/SPEC.md +++ b/knowledge-base/SPEC.md @@ -123,11 +123,11 @@ Sprint sync helpers may write to legacy sprint files only when the canonical V1 Supported V1 modes: - `on-demand` -- `scheduled` -- `hybrid` +- `manual` +- `agent-driven` Recommended default: -- `hybrid` with weekly schedule plus manual dispatch. +- `on-demand` via script or KB maintenance agent. ## Rollout Order diff --git a/knowledge-base/prompts/install-hybrid-kb.md b/knowledge-base/prompts/install-hybrid-kb.md index 3d825f9..4a7cc2b 100644 --- a/knowledge-base/prompts/install-hybrid-kb.md +++ b/knowledge-base/prompts/install-hybrid-kb.md @@ -12,6 +12,8 @@ Source directory to read from: - `knowledge-base/templates/CLAUDE.section.md` - `knowledge-base/scripts/validate_hybrid_kb.py` - `knowledge-base/scripts/sync_active_sprint.py` +- `claude/agents/knowledge-base-manager/knowledge-base-manager.md` +- `claude/agents/knowledge-base-manager/README.md` Follow these steps exactly: @@ -31,13 +33,22 @@ Follow these steps exactly: - `.kb-config.yml` 4. Enable Tier 2 files only if the project clearly needs them or I explicitly ask for them. 5. Copy the reusable helper scripts into `knowledge-base/scripts/`. -6. If this project wants scheduled sprint automation, also copy the workflow template to `.github/workflows/sync-active-sprint.yml`. +6. Check whether `.claude/agents/knowledge-base-manager.md` already exists. + - If it does not exist: + - create `.claude/agents/` if needed + - copy `claude/agents/knowledge-base-manager/knowledge-base-manager.md` into `.claude/agents/knowledge-base-manager.md` + - If it already exists: do not overwrite it silently. Mention that it already exists in your summary. 7. Replace placeholders only when you can infer values confidently from the codebase. 8. If a value cannot be inferred confidently, leave the placeholder unchanged and list it in your summary. Do not guess. 9. Add the `Knowledge Base` section from `CLAUDE.section.md` to the project root `CLAUDE.md` if it is not already present. -10. At the end, show me: +10. Ensure the project root `CLAUDE.md` has a `Custom Agents` section that includes `knowledge-base-manager`. + - If the section is missing, create it. + - If the section exists but does not list `knowledge-base-manager`, add it. + - Do not duplicate an existing entry. +11. At the end, show me: - files created - placeholders inferred - placeholders left unresolved - Tier 2 modules enabled + - whether `knowledge-base-manager` agent was installed or already existed ``` diff --git a/knowledge-base/scripts/__pycache__/scaffold_hybrid_kb.cpython-313.pyc b/knowledge-base/scripts/__pycache__/scaffold_hybrid_kb.cpython-313.pyc index 622ce5622293f3c2f76c18770c0042f64095ee65..d280dc1239bf731588ae29405c68c3590126c7b1 100644 GIT binary patch delta 1188 zcmZ8g&2Jk;6rb5$uN{AFyjg$6&IgH5%$>cS3A!cYrXq) zSoWomp6-3Cd`W4T-%<-y;~%P<&m@ud;+E}n!7>}IT6fnn9joCs+cr$&+*uy*e?rr} z&;5CsX8BLS0v+R#kWG{P-B8-Mgdt14d!ad+O{3eu@2LgQlL?_u>OTHknDdV!cjahR z;&-*_^V$VzlI#yxB^DFMwB@S2C8Ye%n9fEn&`DCITPc2D9^s!x4QlXjqTkDLmf(k4 z(f?1T-gnwEMNw+(5^uy3@pGq{sxnK7Evmjni9d+V(DQsspP^~Ku20ZWep^2$XE4=g z`fPseM(lJI%bwN|WsW&0){$&w5AoE?jq^YCSLg&^8#&2d!gYtC+1d767Q78j*Ybjn z+s2Bz(B*fGaV;l#YHd(e5zD_Y3N*@pG3F&0;?KvoQOO7Ki$@bU=lQ{M+AYkaiIJ}Z zP22Tk=N-pW9e39P03p*;ExT54S)R}7w3;rQ5nQ;qvR%Bkyt-m;6w5FtsNiyGYt>x4 za&?u#StLMQ1aGLax>3GbtRR^XV~thI>rZ4^|!_Gmq}!P^;;!_;!h>Y?VqC zD2ef=fNNw5aYMKn0c8QA4E=@-T63NMI+`69&uvi7zzYZM-EPae4ExB5=kGk=nM{Qr nWj3B&ppnNmB}(|t;UhWybI>@h@a;#z><>!zu}qXv5PALv)~*w$ delta 1432 zcmYjR%}*Og6yNc#*PpvyV;g^9!WO8&3dW&=@R2WEFf9RM^cNe z$+<*od#TVIQZ<{)A8*PnCW0U+QRejG^nF~1A~_&2`G+)oyV z@L&835UPJ+iLsy?|7;%z7x0O_OelFr&^$>fll7Wo7=RG|(HS&#@c5+@12fKx9zi6z zxS%k}%1oBQBUUedVz%K&!l$g1HQ`lPpU*vMl9{cJtOrv1d$Yl1$U5M!Vd zSH)jhKMde&uDIolUVrME0U(H9N>^l%zI2-9yEu3@$zNvhb$0;&AlZ99XcJ(Fh9V)m z=pTk#7{WJsmyH>Y)g?o9P3yBGJf1~RJ%&-_FU2EPC>sHZTG~mYkCE#ijJ!4-t>G~ z)APlmtlv{*^-;dGT~uXl8x_jBtnHRJs|X^`RFQgP36<`&t=evuuYcy5C* zp7&1GWTG%ENYyGu;#8tDb8B-3tL0~m4=;1{DSoV2+GPSfkSXWS`q8l8kKnacDd0*GH3A*CYHc(+( zSIYU4il&K1a}to>87M$`Tq$2DqctL~P|_j()|at0t-+?Nt0^SwfBIg4xYhZ}5+q;K z>iSarTzu{Hy_UL<<%xzg(Uihp?KY&rgDVZ`^6}(yLt1W1-e=;z_}0P+;@>Q9v%euX z&|j-%0pm)6e+_X~qmh4!1{Q8`M>a3TK4FpLjz)QchE-AMo)jfwMLt4A9EHwvsZ}y= zy;3O}JW};4DwF=`D8eE6oO6dtc>)n0(aS`9d_-`Bh#TvRpms&JaOEy?? z@FD@jt|*&T;#pM`#8S>I1rLRr_%INj`Iw3#0fTGxB}M0H3K int: default="", help="Comma-separated Tier 2 modules to enable (decision-log,incident-log,feature-history,integration-map,metrics,known-constraints)", ) - parser.add_argument( - "--with-workflow", - action="store_true", - help="Install the example sprint sync workflow into .github/workflows/", - ) parser.add_argument("--overwrite", action="store_true", help="Overwrite existing KB files") args = parser.parse_args() @@ -131,15 +125,6 @@ def main() -> int: ) ) - if args.with_workflow: - actions.append( - copy_file( - WORKFLOW_ROOT / "sync-active-sprint.yml", - project_root / ".github" / "workflows" / "sync-active-sprint.yml", - args.overwrite, - ) - ) - actions.append(configure_kb_config(kb_root / ".kb-config.yml", enabled)) actions.append(ensure_claude_section(project_root)) diff --git a/knowledge-base/workflows/sync-active-sprint.yml b/knowledge-base/workflows/sync-active-sprint.yml deleted file mode 100644 index 69c9b39..0000000 --- a/knowledge-base/workflows/sync-active-sprint.yml +++ /dev/null @@ -1,36 +0,0 @@ -name: Sync Active Sprint - -on: - workflow_dispatch: - schedule: - - cron: "0 9 * * 1" - -jobs: - sync: - runs-on: ubuntu-latest - permissions: - issues: read - pull-requests: read - contents: write - steps: - - uses: actions/checkout@v4 - - uses: actions/setup-python@v5 - with: - python-version: "3.11" - - name: Authenticate gh - env: - GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} - run: gh auth status - - name: Sync sprint file - env: - GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} - run: | - python knowledge-base/scripts/sync_active_sprint.py . --repo ${{ github.repository }} - - name: Commit changes - run: | - git config user.name github-actions - git config user.email github-actions@github.com - git diff --quiet && exit 0 - git add knowledge-base/active-sprint.md knowledge-base/04-active-sprint/00-index.md || true - git commit -m "chore: sync active sprint" - git push From 30b38987194ff3ed31a8dbf2a714c3b6e3b7f232 Mon Sep 17 00:00:00 2001 From: Anurag Kumawat Date: Fri, 6 Mar 2026 19:24:56 +0530 Subject: [PATCH 09/16] removed the sync active sprint --- README.md | 6 +- .../knowledge-base-manager.md | 2 +- knowledge-base/GOVERNANCE.md | 2 +- knowledge-base/README.md | 25 +-- knowledge-base/SPEC-RECONCILIATION.md | 8 +- knowledge-base/SPEC.md | 19 +-- knowledge-base/prompts/install-hybrid-kb.md | 3 +- .../scaffold_hybrid_kb.cpython-313.pyc | Bin 6682 -> 0 bytes .../sync_active_sprint.cpython-313.pyc | Bin 9217 -> 0 bytes .../validate_hybrid_kb.cpython-313.pyc | Bin 4014 -> 0 bytes knowledge-base/scripts/scaffold_hybrid_kb.py | 2 +- knowledge-base/scripts/sync_active_sprint.py | 146 ------------------ knowledge-base/scripts/validate_hybrid_kb.py | 2 +- knowledge-base/templates/.kb-config.yml | 5 - 14 files changed, 36 insertions(+), 184 deletions(-) delete mode 100644 knowledge-base/scripts/__pycache__/scaffold_hybrid_kb.cpython-313.pyc delete mode 100644 knowledge-base/scripts/__pycache__/sync_active_sprint.cpython-313.pyc delete mode 100644 knowledge-base/scripts/__pycache__/validate_hybrid_kb.cpython-313.pyc delete mode 100755 knowledge-base/scripts/sync_active_sprint.py diff --git a/README.md b/README.md index 122fcfe..fb9d860 100644 --- a/README.md +++ b/README.md @@ -14,15 +14,15 @@ Individual projects opt into recipes by copying or referencing them. | 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 flat-file templates, config, validation, and sprint-sync automation | +| Knowledge Base | [knowledge-base/](knowledge-base/) | Hybrid project-local KB starter kit with flat-file templates, config, 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 automation helpers. +- `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. -- `active-sprint.md` is the primary automation target. +- Validation is explicit and lightweight after setup. Start with [knowledge-base/README.md](knowledge-base/README.md). diff --git a/claude/agents/knowledge-base-manager/knowledge-base-manager.md b/claude/agents/knowledge-base-manager/knowledge-base-manager.md index 60228ea..bc4bb7b 100644 --- a/claude/agents/knowledge-base-manager/knowledge-base-manager.md +++ b/claude/agents/knowledge-base-manager/knowledge-base-manager.md @@ -104,7 +104,7 @@ The knowledge base uses two types of files. You must never confuse them: | `active-sprint.md` | **Canonical V1 content file** — the sprint tracking table lives here | Write or regenerate auto-managed sprint sections here | | `04-active-sprint/00-index.md` | **Legacy sprint file** | Only use when the canonical V1 sprint file is absent | | `business-flows.md`, `architecture.md`, `risks.md` | Human-owned Tier 1 KB files | Do not rewrite automatically unless the user explicitly requests it | -| `advanced/*.md` | Optional Tier 2 files | Append only when the user asks or when the workflow explicitly calls for it | +| `advanced/*.md` | Optional Tier 2 files | Append only when the user asks or when the project explicitly uses a maintenance process for them | Before making any sprint edit, read the target sprint file in full. Locate any existing row or generated section entry for the issue number. This prevents duplication and tells you whether to update or regenerate. diff --git a/knowledge-base/GOVERNANCE.md b/knowledge-base/GOVERNANCE.md index a7c4f46..beb51ca 100644 --- a/knowledge-base/GOVERNANCE.md +++ b/knowledge-base/GOVERNANCE.md @@ -47,7 +47,7 @@ The following changes require maintainer review in `engineering-recipes`: 2. Check whether the change is breaking or non-breaking. 3. Run the KB validator after applying changes. 4. Update the project root `CLAUDE.md` guidance if the adapter contract changed. -5. For sprint automation changes, test in a branch before scheduling. +5. Run the KB validator after structural KB changes. ## Recommended Maintainer Checklist diff --git a/knowledge-base/README.md b/knowledge-base/README.md index 23b0db2..d2477b5 100644 --- a/knowledge-base/README.md +++ b/knowledge-base/README.md @@ -11,7 +11,6 @@ This directory contains the V1 hybrid knowledge-base starter kit for project-loc - Tier 1 and Tier 2 templates under [`templates/`](templates/) - A scaffold script for installing the KB into another project - A validation script for checking a KB installation -- An active sprint sync script for manual or agent-driven updates - A copy-paste install prompt for agent-based setup ## Canonical V1 Layout @@ -66,6 +65,13 @@ python knowledge-base/scripts/scaffold_hybrid_kb.py /path/to/target-project \ --enable decision-log,incident-log ``` +After setup, move into the target project root and validate the KB: + +```bash +cd /path/to/target-project +python3 knowledge-base/scripts/validate_hybrid_kb.py . +``` + ### Validate an installed KB ```bash @@ -76,20 +82,21 @@ python knowledge-base/scripts/validate_hybrid_kb.py /path/to/target-project See [prompts/install-hybrid-kb.md](prompts/install-hybrid-kb.md). -## Sprint Automation +## Validation After Setup -`active-sprint.md` is the main automation target. +The starter kit copies `validate_hybrid_kb.py` into the target project's `knowledge-base/scripts/` directory. -### Manual sync +Run this from the target project root after installation: ```bash -python knowledge-base/scripts/sync_active_sprint.py /path/to/project --repo owner/name +python3 knowledge-base/scripts/validate_hybrid_kb.py . ``` -### Scheduled sync - -No workflow template is shipped in `engineering-recipes`. -If a downstream project wants scheduled sync, it should add its own automation around `knowledge-base/scripts/sync_active_sprint.py`. +The validator checks: +- required Tier 1 files exist +- `.kb-config.yml` has the minimum contract keys +- `00-index.md` references the Tier 1 files +- enabled Tier 2 modules in config have matching files ## Legacy Compatibility diff --git a/knowledge-base/SPEC-RECONCILIATION.md b/knowledge-base/SPEC-RECONCILIATION.md index 78e62f4..7bdc349 100644 --- a/knowledge-base/SPEC-RECONCILIATION.md +++ b/knowledge-base/SPEC-RECONCILIATION.md @@ -14,7 +14,7 @@ This note reconciles the pre-existing `engineering-recipes` knowledge-base recip | Runtime contract | Mostly documented in `CLAUDE.md` | `.kb-config.yml` plus mirrored `CLAUDE.md` guidance | `.kb-config.yml` is source of truth; `CLAUDE.md` mirrors read rules | | Sprint file | `04-active-sprint/00-index.md` | `active-sprint.md` | Standardize on `active-sprint.md`; updater supports legacy fallback | | Advanced memory | Not formalized as optional modules | Tier 2 optional modules | Add as explicit optional templates | -| Automation | Agent-only guidance | Agent plus reusable updater script | Implement reusable sync script; downstream projects may add their own scheduling | +| Automation | Agent-only guidance | Manual validation plus project-specific maintenance flow | Do not ship sync automation in the starter kit | ## Decision Gates and Frozen Outcomes @@ -42,8 +42,8 @@ This note reconciles the pre-existing `engineering-recipes` knowledge-base recip ### DG-6: Automation cadence - **Decision:** manual / agent-driven cadence. -- **Supported modes in this repo:** on-demand sync via script or KB maintenance agent. -- **Note:** downstream projects may add their own scheduling separately. +- **Supported modes in this repo:** scaffold + validate only. +- **Note:** downstream projects may implement their own maintenance flow separately. ## Migration Impact @@ -73,7 +73,7 @@ Implemented in this repo: - `.kb-config.yml` contract - scaffold prompt and reusable scripts - agent documentation updates -- manual sprint sync helper +- KB validation helper Not implemented in this repo: - direct migration of Sneha or IAGES repositories diff --git a/knowledge-base/SPEC.md b/knowledge-base/SPEC.md index 765963d..2b4872f 100644 --- a/knowledge-base/SPEC.md +++ b/knowledge-base/SPEC.md @@ -15,7 +15,7 @@ Provide a project-local, token-efficient knowledge base that is easy to scaffold 2. Small default footprint: Tier 1 is required and intentionally compact. 3. Optional advanced depth: Tier 2 is opt-in per project. 4. Deterministic reads: agents read the entry file first, then load only mapped files. -5. Minimal write surface: `active-sprint.md` is the main automation target. +5. Minimal maintenance surface: Tier 1 stays small and predictable. 6. Tool agnostic content: KB content stays plain Markdown plus lightweight config. ## Canonical Project Layout @@ -62,7 +62,7 @@ knowledge-base/ | `architecture.md` | Human | Update on major architecture changes | | `business-flows.md` | Human | Update when business flows materially change | | `risks.md` | Human | Update during reviews, incidents, or notable risk discovery | -| `active-sprint.md` | Automation with human review | Primary auto-managed file | +| `active-sprint.md` | Human or project-specific process | Current delivery state file | | Tier 2 append-only logs | Human or semi-automated | Prefer append-only entries | ## Read Contract @@ -92,7 +92,7 @@ If `knowledge-base/` or the entry file does not exist, agents proceed without KB ## Write Contract 1. Only the designated KB maintenance flow may write automated updates. -2. `active-sprint.md` is the default automation target. +2. This starter kit does not ship a sprint sync script or workflow. 3. Tier 2 logs should prefer append-only updates. 4. Agents that consume KB context remain read-only. @@ -103,8 +103,6 @@ Minimum supported keys: - `project.name` - `enabled_tier2` - `loading_defaults` -- `auto_update.active_sprint.mode` -- `auto_update.active_sprint.schedule` ## Compatibility Rules @@ -119,15 +117,12 @@ Agents and helpers may support these legacy files: ### Legacy write support Sprint sync helpers may write to legacy sprint files only when the canonical V1 sprint file is absent. -## Automation Cadence - -Supported V1 modes: -- `on-demand` -- `manual` -- `agent-driven` +## Maintenance Cadence Recommended default: -- `on-demand` via script or KB maintenance agent. +- update Tier 1 when project reality changes +- use append-only updates for Tier 2 logs where possible +- run the KB validator after setup or structural changes ## Rollout Order diff --git a/knowledge-base/prompts/install-hybrid-kb.md b/knowledge-base/prompts/install-hybrid-kb.md index 4a7cc2b..bebdd34 100644 --- a/knowledge-base/prompts/install-hybrid-kb.md +++ b/knowledge-base/prompts/install-hybrid-kb.md @@ -11,7 +11,6 @@ Source directory to read from: - `knowledge-base/templates/.kb-config.yml` - `knowledge-base/templates/CLAUDE.section.md` - `knowledge-base/scripts/validate_hybrid_kb.py` -- `knowledge-base/scripts/sync_active_sprint.py` - `claude/agents/knowledge-base-manager/knowledge-base-manager.md` - `claude/agents/knowledge-base-manager/README.md` @@ -51,4 +50,6 @@ Follow these steps exactly: - placeholders left unresolved - Tier 2 modules enabled - whether `knowledge-base-manager` agent was installed or already existed + - the exact validation command I should run from this project's root: + `python3 knowledge-base/scripts/validate_hybrid_kb.py .` ``` diff --git a/knowledge-base/scripts/__pycache__/scaffold_hybrid_kb.cpython-313.pyc b/knowledge-base/scripts/__pycache__/scaffold_hybrid_kb.cpython-313.pyc deleted file mode 100644 index d280dc1239bf731588ae29405c68c3590126c7b1..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 6682 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 diff --git a/knowledge-base/scripts/__pycache__/validate_hybrid_kb.cpython-313.pyc b/knowledge-base/scripts/__pycache__/validate_hybrid_kb.cpython-313.pyc deleted file mode 100644 index 0cb65809758d65d6581bf72d00e6e221153fcdfd..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 4014 zcma)9O>h&*74DHnKi1#Kl7+A__TU(7xsbiaumNRvQ~cQccrmO7QGiJ%V`*#;mPbm@ z$k+qBB~FOi19-P6IHkxT6_OLF9G2rAsmeu)h&2qPHdVW+)ZXks<*=u`9%*bNFh!T$ z-P8U0z1RJ|_oJ77zXw74-8X-hZg>&;o_tu%Ri98Vi!iy1IK)xo=oE!1mdtJAHf%FT zJGR4UAE!?_u!BWIh@(HFu#Va>TJyUQ^%Z~ zyP6d$S_f}La0CPeeb85cLx72)_uc9$c`f5y*QiiJ`S!;cReY$}i z6G2Ys?FdmX7hv@+AXKI}O17m?ax;}liq_GWgcHrpLS`79_zEG}p0Xz$%`_VvWI9DB z8(y@T%HkqBQVz~$qMt_KL9*?19HEr0zd@X_A$0mfSaBpl#K@>xmE5+5|27$76%4M%K@*0C+vJlMGYWwPYc``9w@MmB zs>;xUkd-omD)O^SQ&`IIb5n!)B_m{N`r2i1J22~jf8`I*6_FkY7LV&pTk(X>bkvyM z3e#I<_SBf+3NyUIjFjv;6S}S4(!RW2qV;g}USc`%^+zSQ?hTiteN}It9^Fwo@yyru zoi|)Ms58+T(^Fx39*oqOz6#T)2c!1_%Yplg52=T?``2sT!&3)&u!~vmK&j1b*}uFW~GP%{dO)00-~HolH%xqZ`m`=A+kTSqMu)j%aS{zGMTh zwoeAEeelqI;Gy(|-Z=OJ@w8;CwYM=^r(eTvmx=Z829-7AoGChhMr@Wo;3@l29pN_4 zWy*1;obM&)5y)^RBNpe4(b7nU%n5gZcp$qk-24T2iRp*%I^c(I)2$`tPDVHQSToLJ zY1^dvP+jv$f?Knt);$^I{u<=AOcFesExFU0ZH%cFi!+IH>1|tT=1sLU$sR_iZkP9Z zD-usmZOPsDhE0C6ZWF(06Hm(XUUI;eK>044c)0+)4d6reUHIF3*n~;>nr_ZEbhED` z?q>*1c3ZE?1+6z_!OkEHFf02v?YE}Nn1f8tL9jBR%9Xm&WI}8AYcgr zDZ^&PY+j4bOA3@uGb|Q=Tad7rVW*|6m|!u9wJ}`Clai-vx$VL$2Rzank0^anoM(n*!pHg7<{7ybXzr_)(zztUNY~_ zW^$s!Ld6PCGA&{eYCBM)^MsjCh!q+s1|Ef-7C@U!LbJtLOyb}cWO+eR#LOTjK{*yQ z++dHqfECdQ9L6(+d60dUd}6~VWHLPLnrnu~BqHAmhI#{G;?#xG0PIfFTK_T0%c6Nf+Lk6h%(M=u(7K!o8ii{V(n zaGH{^K@(X9O%MX?FwS8GGO?I7Xp*OKh{$(?X;e@dcEFy7vu-oPVZNZ@F^76l04Jwm z-DE>lsi$tM$J+@vdLD{P{BxM@g@5HS#LXgl;g8h(y?^)jmWR(({HfxYPJ3!}v_ePk z2g>n@GMS#yy{$EGXT{rD^>!7H{orNp(6!*MN^n=z+f(xnRJ;RK@804u-Om)q{=@7f z2|RpDgXGPGZ(qB0?e^ziey;mMw@=?XUG5xtbo9}Ia>t<+Ut-OLf?cZ~6pohL4^~14 zi{rX0RCBdgTQ*S89>|N~FIQ8K_1E)`>oToPL}tcO6{`9$WLG=!dHTBYtFQP#tFOkLob} z1RsV|05YUpf^OALQPjUt&-aLVjy(TF+y6_uLbhUHHH0Fc=xrbC(WBPVI1ulZeJ tTakIy#!%r`z5SGb^*n`WUrDRl+n;&bmd|~CzUt{L)19k!M0c37{|~#~#%llo diff --git a/knowledge-base/scripts/scaffold_hybrid_kb.py b/knowledge-base/scripts/scaffold_hybrid_kb.py index f8e1b51..26fede0 100755 --- a/knowledge-base/scripts/scaffold_hybrid_kb.py +++ b/knowledge-base/scripts/scaffold_hybrid_kb.py @@ -28,7 +28,6 @@ CLAUDE_SECTION = TEMPLATES / "CLAUDE.section.md" SUPPORT_SCRIPTS = [ "validate_hybrid_kb.py", - "sync_active_sprint.py", ] @@ -135,6 +134,7 @@ def main() -> int: print(f"- enabled Tier 2: {', '.join(enabled)}") else: print("- enabled Tier 2: none") + print("- validate from the project root with: python3 knowledge-base/scripts/validate_hybrid_kb.py .") return 0 diff --git a/knowledge-base/scripts/sync_active_sprint.py b/knowledge-base/scripts/sync_active_sprint.py deleted file mode 100755 index 7a82416..0000000 --- a/knowledge-base/scripts/sync_active_sprint.py +++ /dev/null @@ -1,146 +0,0 @@ -#!/usr/bin/env python3 -from __future__ import annotations - -import argparse -import json -import subprocess -import sys -from dataclasses import dataclass -from pathlib import Path - -ACTIVE_START = "" -ACTIVE_END = "" -BLOCKERS_START = "" -BLOCKERS_END = "" -DONE_START = "" -DONE_END = "" - - -@dataclass -class IssueRow: - number: int - title: str - status: str - assignee: str - note: str - - -@dataclass -class DoneRow: - ref: str - title: str - completed_on: str - - -def run_gh(args: list[str]) -> list[dict]: - result = subprocess.run(["gh", *args], check=True, capture_output=True, text=True) - return json.loads(result.stdout) - - -def detect_status(issue: dict) -> str: - if issue.get("state") == "CLOSED": - return "Done" - labels = {label["name"].lower() for label in issue.get("labels", [])} - if any(label in labels for label in {"in review", "review", "needs review"}): - return "In Review" - if issue.get("assignees") or any(label in labels for label in {"in progress", "doing", "wip"}): - return "In Progress" - return "Backlog" - - -def replace_section(text: str, start: str, end: str, body: str) -> str: - if start not in text or end not in text: - raise ValueError(f"markers not found: {start} / {end}") - prefix, rest = text.split(start, 1) - _, suffix = rest.split(end, 1) - return prefix + start + "\n" + body.rstrip() + "\n" + end + suffix - - -def render_active(rows: list[IssueRow]) -> str: - lines = ["| Issue | Title | Status | Assignee | Note |", "|---|---|---|---|---|"] - for row in rows: - lines.append(f"| #{row.number} | {row.title} | {row.status} | {row.assignee} | {row.note} |") - return "\n".join(lines) - - -def render_blockers(rows: list[IssueRow]) -> str: - lines = ["| Issue | Blocker | Owner |", "|---|---|---|"] - for row in rows: - lines.append(f"| #{row.number} | {row.note or 'Label / blocker details missing'} | {row.assignee} |") - return "\n".join(lines) - - -def render_done(rows: list[DoneRow]) -> str: - lines = ["| Issue / PR | Title | Completed On |", "|---|---|---|"] - for row in rows: - lines.append(f"| {row.ref} | {row.title} | {row.completed_on} |") - return "\n".join(lines) - - -def choose_sprint_file(project_root: Path) -> Path: - canonical = project_root / "knowledge-base/active-sprint.md" - legacy = project_root / "knowledge-base/04-active-sprint/00-index.md" - if canonical.exists(): - return canonical - if legacy.exists(): - return legacy - raise FileNotFoundError("No sprint file found in canonical or legacy location") - - -def main() -> int: - parser = argparse.ArgumentParser(description="Sync the active sprint file from GitHub issues") - parser.add_argument("project_root", help="Path to the target project root") - parser.add_argument("--repo", required=True, help="GitHub repository in owner/name format") - parser.add_argument("--open-limit", type=int, default=30) - parser.add_argument("--closed-limit", type=int, default=10) - args = parser.parse_args() - - project_root = Path(args.project_root).resolve() - sprint_file = choose_sprint_file(project_root) - - open_issues = run_gh([ - "issue", "list", - "--repo", args.repo, - "--state", "open", - "--limit", str(args.open_limit), - "--json", "number,title,labels,assignees,state", - ]) - closed_issues = run_gh([ - "issue", "list", - "--repo", args.repo, - "--state", "closed", - "--limit", str(args.closed_limit), - "--json", "number,title,closedAt", - ]) - - active_rows = [] - blocker_rows = [] - for issue in open_issues: - status = detect_status(issue) - assignees = issue.get("assignees", []) - assignee = ", ".join(person["login"] for person in assignees) if assignees else "—" - labels = {label["name"].lower() for label in issue.get("labels", [])} - note = "" - if "blocked" in labels or "on hold" in labels: - note = "Blocked / on hold" - blocker_rows.append(IssueRow(issue["number"], issue["title"], status, assignee, note)) - active_rows.append(IssueRow(issue["number"], issue["title"], status, assignee, note or "—")) - - done_rows = [DoneRow(f"#{issue['number']}", issue["title"], issue.get("closedAt", "")[:10] or "—") for issue in closed_issues] - - text = sprint_file.read_text() - text = replace_section(text, ACTIVE_START, ACTIVE_END, render_active(active_rows)) - text = replace_section(text, BLOCKERS_START, BLOCKERS_END, render_blockers(blocker_rows)) - text = replace_section(text, DONE_START, DONE_END, render_done(done_rows)) - sprint_file.write_text(text) - - print(f"updated {sprint_file}") - return 0 - - -if __name__ == "__main__": - try: - raise SystemExit(main()) - except subprocess.CalledProcessError as exc: - print(exc.stderr or str(exc), file=sys.stderr) - raise SystemExit(exc.returncode) diff --git a/knowledge-base/scripts/validate_hybrid_kb.py b/knowledge-base/scripts/validate_hybrid_kb.py index 83eedcc..53caa1b 100755 --- a/knowledge-base/scripts/validate_hybrid_kb.py +++ b/knowledge-base/scripts/validate_hybrid_kb.py @@ -57,7 +57,7 @@ def main() -> int: config_path = root / "knowledge-base/.kb-config.yml" if config_path.exists(): contents = config_path.read_text() - for key in ["version:", "source_of_truth:", "loading_defaults:", "auto_update:"]: + for key in ["version:", "source_of_truth:", "loading_defaults:"]: if key not in contents: errors.append(f"missing config key: {key.rstrip(':')}") for module in read_enabled_tier2(config_path): diff --git a/knowledge-base/templates/.kb-config.yml b/knowledge-base/templates/.kb-config.yml index 9f3bc32..7a5729b 100644 --- a/knowledge-base/templates/.kb-config.yml +++ b/knowledge-base/templates/.kb-config.yml @@ -24,11 +24,6 @@ loading_defaults: incident_response: - risks.md - advanced/incident-log.md -auto_update: - active_sprint: - mode: hybrid - schedule: weekly - owner: knowledge-base-manager compatibility: legacy_entrypoint: knowledge-base/00-master.md legacy_sprint_file: knowledge-base/04-active-sprint/00-index.md From df842f552a9d5090648329473b0d6c2a4e0318ac Mon Sep 17 00:00:00 2001 From: Anurag Kumawat Date: Fri, 6 Mar 2026 20:11:56 +0530 Subject: [PATCH 10/16] refined prompt --- knowledge-base/prompts/install-hybrid-kb.md | 38 ++++++++++++++++----- 1 file changed, 30 insertions(+), 8 deletions(-) diff --git a/knowledge-base/prompts/install-hybrid-kb.md b/knowledge-base/prompts/install-hybrid-kb.md index bebdd34..6cd2898 100644 --- a/knowledge-base/prompts/install-hybrid-kb.md +++ b/knowledge-base/prompts/install-hybrid-kb.md @@ -30,24 +30,46 @@ Follow these steps exactly: - `active-sprint.md` - `risks.md` - `.kb-config.yml` -4. Enable Tier 2 files only if the project clearly needs them or I explicitly ask for them. -5. Copy the reusable helper scripts into `knowledge-base/scripts/`. -6. Check whether `.claude/agents/knowledge-base-manager.md` already exists. +4. Evaluate whether Tier 2 is needed for this project. + - Use evidence only from the codebase and project docs. + - Consider Tier 2 justified only when the project shows real complexity such as: + - recurring incidents or fragile areas + - multiple external integrations + - long-lived architecture decisions worth preserving + - hard technical or business constraints + - meaningful shipped feature history that would help onboarding + - If Tier 2 does NOT appear justified, recommend Tier 1 only. +5. If Tier 2 may be useful, present a recommendation table before creating any Tier 2 files. + For each optional file below, mark one of: `Recommend`, `Optional`, `Do Not Recommend`, and give a one-line reason. + - `advanced/decision-log.md` + - `advanced/incident-log.md` + - `advanced/feature-history.md` + - `advanced/integration-map.md` + - `advanced/metrics.md` + - `advanced/known-constraints.md` +6. Ask me whether I want Tier 2 for this project. + - If I say no: continue with Tier 1 only. + - If I say yes: ask me to confirm exactly which Tier 2 files to include, using your recommendations as the default suggestion. + - Do not create any Tier 2 files until I confirm the selection. +7. Copy the reusable helper scripts into `knowledge-base/scripts/`. +8. Check whether `.claude/agents/knowledge-base-manager.md` already exists. - If it does not exist: - create `.claude/agents/` if needed - copy `claude/agents/knowledge-base-manager/knowledge-base-manager.md` into `.claude/agents/knowledge-base-manager.md` - If it already exists: do not overwrite it silently. Mention that it already exists in your summary. -7. Replace placeholders only when you can infer values confidently from the codebase. -8. If a value cannot be inferred confidently, leave the placeholder unchanged and list it in your summary. Do not guess. -9. Add the `Knowledge Base` section from `CLAUDE.section.md` to the project root `CLAUDE.md` if it is not already present. -10. Ensure the project root `CLAUDE.md` has a `Custom Agents` section that includes `knowledge-base-manager`. +9. Replace placeholders only when you can infer values confidently from the codebase. +10. If a value cannot be inferred confidently, leave the placeholder unchanged and list it in your summary. Do not guess. +11. Add the `Knowledge Base` section from `CLAUDE.section.md` to the project root `CLAUDE.md` if it is not already present. +12. Ensure the project root `CLAUDE.md` has a `Custom Agents` section that includes `knowledge-base-manager`. - If the section is missing, create it. - If the section exists but does not list `knowledge-base-manager`, add it. - Do not duplicate an existing entry. -11. At the end, show me: +13. At the end, show me: - files created - placeholders inferred - placeholders left unresolved + - whether Tier 2 was recommended + - which Tier 2 files were recommended vs not recommended - Tier 2 modules enabled - whether `knowledge-base-manager` agent was installed or already existed - the exact validation command I should run from this project's root: From 5b8f2b103617b9db13e873a5d781c4f6b4aaa477 Mon Sep 17 00:00:00 2001 From: Anurag Kumawat Date: Sat, 7 Mar 2026 10:48:56 +0530 Subject: [PATCH 11/16] fixed --- README.md | 3 +- claude/README.md | 10 +- .../business-analyst/business-analyst.md | 8 +- .../implementation-executor.md | 10 +- .../implementation-planner.md | 14 +-- .../agents/knowledge-base-manager/README.md | 8 +- .../knowledge-base-manager.md | 54 ++++----- knowledge-base/README.md | 76 +++++++------ knowledge-base/SPEC-RECONCILIATION.md | 55 +++++---- knowledge-base/SPEC.md | 96 +++++++++------- knowledge-base/prompts/install-hybrid-kb.md | 12 +- knowledge-base/scripts/scaffold_hybrid_kb.py | 18 +-- knowledge-base/scripts/validate_hybrid_kb.py | 104 +++++++++++++----- knowledge-base/templates/.kb-config.yml | 28 ++--- knowledge-base/templates/00-index.md | 35 ------ knowledge-base/{ => templates}/00-master.md | 0 .../01-business-flows/00-index.md | 0 .../02-architecture/00-index.md | 0 .../{ => templates}/03-risk-model/00-index.md | 0 .../04-active-sprint/00-index.md | 0 knowledge-base/templates/CLAUDE.section.md | 4 +- knowledge-base/templates/README.md | 13 ++- knowledge-base/templates/active-sprint.md | 38 ------- knowledge-base/templates/architecture.md | 38 ------- knowledge-base/templates/business-flows.md | 41 ------- knowledge-base/templates/risks.md | 23 ---- 26 files changed, 292 insertions(+), 396 deletions(-) delete mode 100644 knowledge-base/templates/00-index.md rename knowledge-base/{ => templates}/00-master.md (100%) rename knowledge-base/{ => templates}/01-business-flows/00-index.md (100%) rename knowledge-base/{ => templates}/02-architecture/00-index.md (100%) rename knowledge-base/{ => templates}/03-risk-model/00-index.md (100%) rename knowledge-base/{ => templates}/04-active-sprint/00-index.md (100%) delete mode 100644 knowledge-base/templates/active-sprint.md delete mode 100644 knowledge-base/templates/architecture.md delete mode 100644 knowledge-base/templates/business-flows.md delete mode 100644 knowledge-base/templates/risks.md diff --git a/README.md b/README.md index fb9d860..a9688d3 100644 --- a/README.md +++ b/README.md @@ -14,7 +14,7 @@ Individual projects opt into recipes by copying or referencing them. | 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 flat-file templates, config, scaffolding, and validation | +| Knowledge Base | [knowledge-base/](knowledge-base/) | Hybrid project-local KB starter kit with numbered tree templates, config, scaffolding, and validation | ## Hybrid Knowledge Base @@ -23,6 +23,7 @@ The current KB model is a hybrid starter kit: - 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 a numbered tree so agents can read only the narrow section they need. - Validation is explicit and lightweight after setup. Start with [knowledge-base/README.md](knowledge-base/README.md). diff --git a/claude/README.md b/claude/README.md index 1bbbc14..0460973 100644 --- a/claude/README.md +++ b/claude/README.md @@ -13,12 +13,12 @@ This directory contains reusable, templatized Claude Code agents that can be set ## Knowledge Base Contract -These agents now prefer the hybrid flat-file KB contract: -- entry file: `knowledge-base/00-index.md` +These agents now prefer the numbered hybrid KB contract: +- entry file: `knowledge-base/00-master.md` - runtime config: `knowledge-base/.kb-config.yml` -- core files: `architecture.md`, `business-flows.md`, `active-sprint.md`, `risks.md` +- core files: `01-business-flows/00-index.md`, `02-architecture/00-index.md`, `03-risk-model/00-index.md`, `04-active-sprint/00-index.md` -Legacy numbered KB layouts remain supported as a fallback for older projects. +Projects created during the temporary flat-layout phase remain supported as a fallback. ## Setting Up Agents in Your Project @@ -61,7 +61,7 @@ Follow these steps exactly: - Remove optional sections that clearly do not apply to this project 5. Check whether this project already has a hybrid knowledge base: - - `knowledge-base/00-index.md` + - `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. diff --git a/claude/agents/business-analyst/business-analyst.md b/claude/agents/business-analyst/business-analyst.md index 0966bdc..a53d89a 100644 --- a/claude/agents/business-analyst/business-analyst.md +++ b/claude/agents/business-analyst/business-analyst.md @@ -35,13 +35,13 @@ You are an expert business analyst for {{PROJECT_NAME}}. Before reasoning about requirements, check for a project knowledge base: -1. Prefer the hybrid entry file at `knowledge-base/00-index.md`. - - If it does **not** exist, fall back to `knowledge-base/00-master.md`. +1. Prefer the numbered entry file at `knowledge-base/00-master.md`. + - If it does **not** exist, fall back to `knowledge-base/00-index.md`. - If neither 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/business-flows.md` when it exists and is complete. -5. If the project still uses the legacy layout, fall back to `knowledge-base/01-business-flows/00-index.md`. +4. Prefer `knowledge-base/01-business-flows/00-index.md` when it exists and is complete. +5. If the project still uses the flat compatibility layout, fall back to `knowledge-base/business-flows.md`. 6. Skip any KB file that is clearly incomplete or still full of placeholders / `TODO:` content. 7. 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**. 8. Do **not** write to or modify any knowledge base file. diff --git a/claude/agents/implementation-executor/implementation-executor.md b/claude/agents/implementation-executor/implementation-executor.md index 584bd37..7e8805d 100644 --- a/claude/agents/implementation-executor/implementation-executor.md +++ b/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 \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 \n\n- Example 3:\n user: \"Start coding the plan from this comment: \"\n assistant: \"Let me launch the implementation-executor to build this out.\"\n \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 " +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 \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 \n\n- Example 3:\n user: \"Start coding the plan from this comment: \"\n assistant: \"Let me launch the implementation-executor to build this out.\"\n \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 " model: sonnet color: blue @@ -13,13 +13,13 @@ You are an expert software engineer and disciplined executor. You take structure Before reading the implementation plan or exploring the codebase, check for a project knowledge base: -1. Prefer the hybrid entry file at `knowledge-base/00-index.md`. - - If it does **not** exist, fall back to `knowledge-base/00-master.md`. +1. Prefer the numbered entry file at `knowledge-base/00-master.md`. + - If it does **not** exist, fall back to `knowledge-base/00-index.md`. - If neither 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/architecture.md` when it exists and is complete. -5. If the project still uses the legacy layout, fall back to `knowledge-base/02-architecture/00-index.md`. +4. Prefer `knowledge-base/02-architecture/00-index.md` when it exists and is complete. +5. If the project still uses the flat compatibility layout, fall back to `knowledge-base/architecture.md`. 6. Skip any KB file that is clearly incomplete or still full of placeholders / `TODO:` content. 7. 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**. 8. Do **not** write to or modify any knowledge base file. diff --git a/claude/agents/implementation-planner/implementation-planner.md b/claude/agents/implementation-planner/implementation-planner.md index 1c6d6d7..59b0ca1 100644 --- a/claude/agents/implementation-planner/implementation-planner.md +++ b/claude/agents/implementation-planner/implementation-planner.md @@ -13,19 +13,19 @@ You are an elite software architect and technical lead with deep expertise in {{ Before exploring the codebase or reasoning about the implementation, check for a project knowledge base: -1. Prefer the hybrid entry file at `knowledge-base/00-index.md`. - - If it does **not** exist, fall back to the legacy entry file at `knowledge-base/00-master.md`. +1. Prefer the numbered entry file at `knowledge-base/00-master.md`. + - If it does **not** exist, fall back to the compatibility entry file at `knowledge-base/00-index.md`. - If neither 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 hybrid files when present and complete: - - `knowledge-base/business-flows.md` - - `knowledge-base/architecture.md` - - `knowledge-base/active-sprint.md` -5. If the project is still on the legacy layout, fall back to: +4. For planning work, prefer these numbered files when present and complete: - `knowledge-base/01-business-flows/00-index.md` - `knowledge-base/02-architecture/00-index.md` - `knowledge-base/04-active-sprint/00-index.md` +5. If the project is still on the flat compatibility layout, fall back to: + - `knowledge-base/business-flows.md` + - `knowledge-base/architecture.md` + - `knowledge-base/active-sprint.md` 6. Skip any KB file that is clearly incomplete or still full of placeholders / `TODO:` content. 7. 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**. 8. Do **not** write to or modify any knowledge base file. diff --git a/claude/agents/knowledge-base-manager/README.md b/claude/agents/knowledge-base-manager/README.md index 7faf10b..73bd836 100644 --- a/claude/agents/knowledge-base-manager/README.md +++ b/claude/agents/knowledge-base-manager/README.md @@ -6,9 +6,9 @@ A Claude Code agent that keeps the project knowledge base in sync with GitHub is - Fetches GitHub issue data in a tiered, token-efficient order (title + state first, body only if needed, PR only if in-review or done) - Maps each issue to one of four states: Backlog, In Progress, In Review, Done/Closed -- Updates the canonical sprint file at `knowledge-base/active-sprint.md` without duplicating existing entries -- Falls back to `knowledge-base/04-active-sprint/00-index.md` for legacy projects still on the numbered layout -- Optionally promotes significant architectural decisions or risk learnings to the relevant KB sections when an issue is closed +- Updates the canonical sprint file at `knowledge-base/04-active-sprint/00-index.md` without duplicating existing entries +- Falls back to `knowledge-base/active-sprint.md` for projects still on the flat compatibility layout +- Optionally promotes significant architectural decisions or risk learnings to the relevant numbered section folders when an issue is closed - Handles bulk syncs (all open issues) and targeted updates (single issue URL or number) ## Prerequisites @@ -38,7 +38,7 @@ The bootstrap installation prompt (see `knowledge-base/README.md`) adds this aut | `knowledge-base-manager` | When the user wants to update the knowledge base from a GitHub issue, sync the active sprint, or reflect recent GitHub activity in the KB. | ``` -If the project uses the hybrid KB contract, `knowledge-base/.kb-config.yml` is the runtime source of truth and the manager should prefer flat files over the legacy numbered layout. +If the project uses the hybrid KB contract, `knowledge-base/.kb-config.yml` is the runtime source of truth and the manager should prefer the numbered layout over the flat compatibility layout. ## Usage diff --git a/claude/agents/knowledge-base-manager/knowledge-base-manager.md b/claude/agents/knowledge-base-manager/knowledge-base-manager.md index bc4bb7b..75e3908 100644 --- a/claude/agents/knowledge-base-manager/knowledge-base-manager.md +++ b/claude/agents/knowledge-base-manager/knowledge-base-manager.md @@ -13,15 +13,15 @@ You are the sole maintainer of this project's AI knowledge base. You have full r Before writing anything: -1. Prefer the hybrid flat-file contract: - - entry file: `knowledge-base/00-index.md` - - sprint file: `knowledge-base/active-sprint.md` +1. Prefer the numbered hybrid contract: + - entry file: `knowledge-base/00-master.md` + - sprint file: `knowledge-base/04-active-sprint/00-index.md` - runtime config: `knowledge-base/.kb-config.yml` -2. If the hybrid contract is absent, fall back to the legacy numbered layout: - - `knowledge-base/00-master.md` - - `knowledge-base/04-active-sprint/00-index.md` +2. If the numbered contract is absent, fall back to the flat compatibility layout: + - `knowledge-base/00-index.md` + - `knowledge-base/active-sprint.md` 3. If neither contract is present, stop and tell the user that the knowledge base has not been set up yet. -4. Treat `active-sprint` as the primary automation target. Do not rewrite human-owned architecture or business-flow content unless the user explicitly asks you to do so. +4. Treat the sprint section as the primary automation target. Do not rewrite human-owned architecture or business-flow content unless the user explicitly asks you to do so. ## Supported Prompt Patterns @@ -43,7 +43,7 @@ Before writing anything: ```bash gh issue list --state open --limit 30 --json number,title,labels,assignees,state ``` - Process each open issue against the current active sprint file. Also fetch recently closed issues to mark completions: + Process each open issue against the current sprint file. Also fetch recently closed issues to mark completions: ```bash gh issue list --state closed --limit 10 --json number,title,state,closedAt ``` @@ -101,12 +101,13 @@ The knowledge base uses two types of files. You must never confuse them: | File type | Role | Write rule | |-----------|------|-----------| -| `active-sprint.md` | **Canonical V1 content file** — the sprint tracking table lives here | Write or regenerate auto-managed sprint sections here | -| `04-active-sprint/00-index.md` | **Legacy sprint file** | Only use when the canonical V1 sprint file is absent | -| `business-flows.md`, `architecture.md`, `risks.md` | Human-owned Tier 1 KB files | Do not rewrite automatically unless the user explicitly requests it | +| `04-active-sprint/00-index.md` | **Canonical V1 sprint file** | Update the sprint tables here | +| `00-master.md` and other section `00-index.md` files | Tier 1 section indexes | Keep concise; link out to deeper child files when detail grows | +| `01-business-flows/*.md`, `02-architecture/*.md`, `03-risk-model/*.md` | Section detail files | Create new files here when adding durable flow, architecture, or risk detail | | `advanced/*.md` | Optional Tier 2 files | Append only when the user asks or when the project explicitly uses a maintenance process for them | +| `active-sprint.md` | Flat compatibility sprint file | Use only when the numbered sprint file is absent | -Before making any sprint edit, read the target sprint file in full. Locate any existing row or generated section entry for the issue number. This prevents duplication and tells you whether to update or regenerate. +Before making any sprint edit, read the target sprint file in full. Locate any existing row for the issue number. This prevents duplication and tells you whether to update or insert. --- @@ -114,10 +115,13 @@ Before making any sprint edit, read the target sprint file in full. Locate any e If the user explicitly asks you to edit a human-owned KB file: -1. Detect whether the project uses the hybrid flat-file contract or the legacy numbered layout. +1. Detect whether the project uses the numbered contract or the flat compatibility layout. 2. Update only the requested file(s). -3. Prefer append-only edits for Tier 2 logs such as `advanced/decision-log.md` and `advanced/incident-log.md`. -4. Do not refactor or rewrite unrelated KB content while making the requested change. +3. For numbered projects, prefer this pattern: + - create a new named detail file inside the relevant section folder + - add a concise index reference in that section's `00-index.md` +4. Prefer append-only edits for Tier 2 logs such as `advanced/decision-log.md` and `advanced/incident-log.md`. +5. Do not refactor or rewrite unrelated KB content while making the requested change. --- @@ -142,22 +146,22 @@ If the user explicitly asks you to edit a human-owned KB file: - Move the issue row from **Active Issues** to **Completed This Sprint**. - Set `Completed On` to the issue's `closedAt` date, or today's date if unavailable. - If the issue never appeared in Active Issues, insert it directly into Completed. -- **Optional promotion:** If the closed issue introduced a significant architectural decision or a risk/learning worth preserving long-term, promote it using this two-step process: - 1. **Create a new named file** inside the relevant section folder. Use a kebab-case filename derived from the issue title (e.g., `knowledge-base/02-architecture/payment-gateway-integration.md` or `knowledge-base/03-risk-model/bulk-delete-risks.md`). Write the decision or risk detail into that file. - 2. **Add a reference row** to the section's `00-index.md` pointing to the new file. Do not write any content into `00-index.md` itself — only add the index row. +- **Optional promotion:** If the closed issue introduced a significant business flow, architectural decision, or risk/learning worth preserving long-term, promote it using this two-step process: + 1. **Create a new named file** inside the relevant numbered section folder. Use a kebab-case filename derived from the issue title (for example `knowledge-base/02-architecture/payment-gateway-integration.md` or `knowledge-base/03-risk-model/bulk-delete-risks.md`). Write the durable detail into that file. + 2. **Add a reference row** to the section's `00-index.md` pointing to the new file. - Only promote when the issue body or linked PR description **explicitly** describes a system-level decision or risk. Do not infer or fabricate. If unsure, skip promotion. + Only promote when the issue body or linked PR description **explicitly** describes a system-level decision, a reusable business flow, or a durable risk. Do not infer or fabricate. If unsure, skip promotion. --- ### Step 6: Write Changes -- Edit only the lines that need to change. Do not rewrite entire files unless you are regenerating the auto-managed sections inside the sprint file. +- Edit only the lines that need to change. Do not rewrite entire files unless the user explicitly asks for a restructure. - Preserve existing table alignment, comment blocks, and marker comments. - Never remove template guidance unless the user explicitly asks. - Never fill or remove unresolved placeholders unless the user explicitly confirms the missing value. -- **Canonical V1 sprint file:** update `knowledge-base/active-sprint.md`. -- **Legacy fallback:** update `knowledge-base/04-active-sprint/00-index.md` only when the canonical V1 sprint file is absent. +- **Canonical V1 sprint file:** update `knowledge-base/04-active-sprint/00-index.md`. +- **Compatibility fallback:** update `knowledge-base/active-sprint.md` only when the numbered sprint file is absent. --- @@ -167,18 +171,18 @@ After writing, report: - Which issue(s) were processed - Which state was detected for each - Which files were updated and exactly what changed -- Any issues skipped and why (e.g., already up to date, state unchanged) +- Any issues skipped and why (for example already up to date or state unchanged) --- ## Important Rules - **This agent is the only agent that writes to the knowledge base.** Never instruct another agent to edit KB files. -- **Prefer the hybrid flat-file contract.** Only use the legacy numbered layout when the flat-file contract is absent. +- **Prefer the numbered hybrid contract.** Only use the flat compatibility layout when the numbered layout is absent. - **Never duplicate.** Always read the target file before writing. If the issue is already in the correct state, do nothing and report it as already up to date. - **Never guess state.** If Tier 1 data is ambiguous, move to the next tier. If still ambiguous, ask. - **Preserve `TODO:` placeholders.** Never remove or fill them. -- **Graceful handling of missing KB.** If neither the hybrid entry file nor the legacy entry file exists, inform the user that the knowledge base has not been set up yet and stop. +- **Graceful handling of missing KB.** If neither the numbered entry file nor the flat compatibility entry file exists, inform the user that the knowledge base has not been set up yet and stop. --- diff --git a/knowledge-base/README.md b/knowledge-base/README.md index d2477b5..6889b02 100644 --- a/knowledge-base/README.md +++ b/knowledge-base/README.md @@ -5,7 +5,7 @@ This directory contains the V1 hybrid knowledge-base starter kit for project-loc ## What This Recipe Provides - A versioned KB contract: [SPEC.md](SPEC.md) -- A reconciliation note against the legacy numbered layout: [SPEC-RECONCILIATION.md](SPEC-RECONCILIATION.md) +- A reconciliation note against the temporary flat-layout phase: [SPEC-RECONCILIATION.md](SPEC-RECONCILIATION.md) - Governance rules: [GOVERNANCE.md](GOVERNANCE.md) - Review checklist: [REVIEW-CHECKLIST.md](REVIEW-CHECKLIST.md) - Tier 1 and Tier 2 templates under [`templates/`](templates/) @@ -15,33 +15,39 @@ This directory contains the V1 hybrid knowledge-base starter kit for project-loc ## Canonical V1 Layout -New projects should use the flat-file layout below inside their own repo: +New projects should use the numbered tree layout below inside their own repo: ```text knowledge-base/ -├── 00-index.md -├── architecture.md -├── business-flows.md -├── active-sprint.md -├── risks.md +├── 00-master.md +├── 01-business-flows/ +│ └── 00-index.md +├── 02-architecture/ +│ └── 00-index.md +├── 03-risk-model/ +│ └── 00-index.md +├── 04-active-sprint/ +│ └── 00-index.md ├── .kb-config.yml -└── advanced/ - ├── decision-log.md - ├── incident-log.md - ├── feature-history.md - ├── integration-map.md - ├── metrics.md - └── known-constraints.md +├── advanced/ +│ ├── decision-log.md +│ ├── incident-log.md +│ ├── feature-history.md +│ ├── integration-map.md +│ ├── metrics.md +│ └── known-constraints.md +└── scripts/ + └── validate_hybrid_kb.py ``` ## Tiers ### Tier 1: Required -- `00-index.md` -- `architecture.md` -- `business-flows.md` -- `active-sprint.md` -- `risks.md` +- `00-master.md` +- `01-business-flows/00-index.md` +- `02-architecture/00-index.md` +- `03-risk-model/00-index.md` +- `04-active-sprint/00-index.md` ### Tier 2: Optional - `advanced/decision-log.md` @@ -61,7 +67,7 @@ knowledge-base/ ### One command scaffold ```bash -python knowledge-base/scripts/scaffold_hybrid_kb.py /path/to/target-project \ +python3 knowledge-base/scripts/scaffold_hybrid_kb.py /path/to/target-project \ --enable decision-log,incident-log ``` @@ -75,7 +81,7 @@ python3 knowledge-base/scripts/validate_hybrid_kb.py . ### Validate an installed KB ```bash -python knowledge-base/scripts/validate_hybrid_kb.py /path/to/target-project +python3 knowledge-base/scripts/validate_hybrid_kb.py /path/to/target-project ``` ### Use the install prompt @@ -95,17 +101,25 @@ python3 knowledge-base/scripts/validate_hybrid_kb.py . The validator checks: - required Tier 1 files exist - `.kb-config.yml` has the minimum contract keys -- `00-index.md` references the Tier 1 files +- `00-master.md` references the numbered Tier 1 section files - enabled Tier 2 modules in config have matching files +- flat-layout projects created during the temporary phase still validate as compatibility installs -## Legacy Compatibility +## Why The Numbered Tree Layout -This repo previously used a numbered layout: -- `00-master.md` -- `01-business-flows/00-index.md` -- `02-architecture/00-index.md` -- `03-risk-model/00-index.md` -- `04-active-sprint/00-index.md` +- `00-master.md` stays small and cheap to read. +- Section `00-index.md` files stay concise and task-focused. +- Deeper details can live in child files inside the matching numbered folder. +- Agents can load only the one section they need instead of pulling broad narrative files. + +## Flat-Layout Compatibility + +Some projects may still have the temporary flat layout: +- `00-index.md` +- `business-flows.md` +- `architecture.md` +- `risks.md` +- `active-sprint.md` -That layout remains supported as a temporary compatibility path for existing projects. -New projects should use the flat-file hybrid contract. +That layout remains readable and valid as a temporary compatibility path for projects created during the transition. +New projects should use the numbered tree contract. diff --git a/knowledge-base/SPEC-RECONCILIATION.md b/knowledge-base/SPEC-RECONCILIATION.md index 7bdc349..9289575 100644 --- a/knowledge-base/SPEC-RECONCILIATION.md +++ b/knowledge-base/SPEC-RECONCILIATION.md @@ -2,73 +2,72 @@ ## Purpose -This note reconciles the pre-existing `engineering-recipes` knowledge-base recipe with the hybrid model defined in the March 6, 2026 review and follow-up Google Doc. +This note reconciles the pre-existing `engineering-recipes` numbered knowledge-base recipe with the temporary flat-layout phase introduced during the hybrid KB work. ## Current vs Target | Area | Current repo state | Hybrid V1 target | Decision | |---|---|---|---| -| Core layout | Numbered directories under `knowledge-base/` | Flat project-local files under `knowledge-base/` | Support both temporarily; new installs use flat layout | -| Entry file | `knowledge-base/00-master.md` | `knowledge-base/00-index.md` | Standardize on `00-index.md`; keep `00-master.md` as legacy alias | -| Section files | `01-business-flows/00-index.md`, etc. | `business-flows.md`, `architecture.md`, `risks.md`, `active-sprint.md` | New installs use flat files | -| Runtime contract | Mostly documented in `CLAUDE.md` | `.kb-config.yml` plus mirrored `CLAUDE.md` guidance | `.kb-config.yml` is source of truth; `CLAUDE.md` mirrors read rules | -| Sprint file | `04-active-sprint/00-index.md` | `active-sprint.md` | Standardize on `active-sprint.md`; updater supports legacy fallback | -| Advanced memory | Not formalized as optional modules | Tier 2 optional modules | Add as explicit optional templates | -| Automation | Agent-only guidance | Manual validation plus project-specific maintenance flow | Do not ship sync automation in the starter kit | +| Core layout | Both numbered and flat artifacts exist in repo history | Numbered directories under `knowledge-base/` | New installs use numbered layout; flat layout is compatibility only | +| Entry file | `knowledge-base/00-master.md` and temporary `00-index.md` references | `knowledge-base/00-master.md` | Standardize on `00-master.md`; `00-index.md` is compatibility only | +| Section files | Numbered section directories plus temporary flat section files | `01-business-flows/00-index.md`, `02-architecture/00-index.md`, `03-risk-model/00-index.md`, `04-active-sprint/00-index.md` | New installs use numbered section directories | +| Runtime contract | Mostly documented in `CLAUDE.md` plus `.kb-config.yml` | `.kb-config.yml` plus mirrored `CLAUDE.md` guidance | `.kb-config.yml` is source of truth; `CLAUDE.md` mirrors read rules | +| Sprint file | `04-active-sprint/00-index.md` and temporary `active-sprint.md` references | `04-active-sprint/00-index.md` | Standardize on numbered sprint file | +| Advanced memory | Optional modules under `advanced/` | Optional modules under `advanced/` | Keep as explicit optional templates | +| Automation | Manual validation only | Manual validation only | Do not ship sync automation in the starter kit | ## Decision Gates and Frozen Outcomes ### DG-1: Canonical file structure -- **Decision:** Support both temporarily with a migration path. -- **V1 canonical for new projects:** flat files under `knowledge-base/`. -- **Legacy support:** numbered-directory layout remains readable by updated agents. +- **Decision:** Numbered tree layout is canonical. +- **V1 canonical for new projects:** numbered directories under `knowledge-base/`. +- **Compatibility support:** flat-file layout remains readable for projects scaffolded during the temporary transition. ### DG-2: Canonical entry-point name -- **Decision:** Standardize on `knowledge-base/00-index.md`. -- **Legacy support:** agents may fall back to `knowledge-base/00-master.md` when needed. +- **Decision:** Standardize on `knowledge-base/00-master.md`. +- **Compatibility support:** agents may fall back to `knowledge-base/00-index.md` when needed. ### DG-3: Agent loading contract source of truth - **Decision:** Use both, with `.kb-config.yml` as the source of truth. - **Role of `CLAUDE.md`:** human-readable and tool-specific adapter guidance only. ### DG-4: Sprint file naming and scope -- **Decision:** Adopt `knowledge-base/active-sprint.md` as the V1 canonical sprint file. -- **Legacy support:** updater and agents may fall back to `knowledge-base/04-active-sprint/00-index.md`. +- **Decision:** Adopt `knowledge-base/04-active-sprint/00-index.md` as the V1 canonical sprint file. +- **Compatibility support:** agents may fall back to `knowledge-base/active-sprint.md`. ### DG-5: Pilot scope for IAGES - **Decision:** Pilot IAGES backend first. -- **Reason:** it already has agent configuration and is the smaller org-level validation unit for the hybrid contract. +- **Reason:** it already has agent configuration and is the smaller org-level validation unit for the KB contract. - **Follow-up:** frontend can be added after backend validation. ### DG-6: Automation cadence - **Decision:** manual / agent-driven cadence. - **Supported modes in this repo:** scaffold + validate only. -- **Note:** downstream projects may implement their own maintenance flow separately. ## Migration Impact ### For new projects -- Use the flat-file hybrid contract only. +- Use the numbered hybrid contract. - Generate `.kb-config.yml` and append KB rules to the project root `CLAUDE.md`. -### For existing projects on the numbered layout +### For projects created during the flat-layout phase - No forced rewrite in V1. -- Updated agents and updater scripts support the legacy structure. -- Migration to the flat-file structure is optional and can happen project-by-project. +- Updated agents and validator support the flat structure. +- Migration to the numbered structure can happen project-by-project. ## Agent Behavior Differences -| Agent | Legacy behavior | Hybrid V1 behavior | +| Agent | Compatibility behavior | Hybrid V1 behavior | |---|---|---| -| `implementation-planner` | Reads `00-master.md` and specific numbered sections | Reads `00-index.md`, follows `.kb-config.yml`, falls back to legacy if needed | -| `implementation-executor` | Reads legacy architecture section | Reads `architecture.md`, falls back to legacy architecture section | -| `business-analyst` | Reads legacy business-flows section | Reads `business-flows.md`, falls back to legacy business-flows section | -| `knowledge-base-manager` | Writes sprint rows into legacy sprint file | Prefers `active-sprint.md`, supports legacy fallback | +| `implementation-planner` | Reads flat `00-index.md` and flat section files when numbered files are absent | Reads `00-master.md`, follows `.kb-config.yml`, loads numbered sections first | +| `implementation-executor` | Reads flat `architecture.md` when numbered file is absent | Reads `02-architecture/00-index.md` | +| `business-analyst` | Reads flat `business-flows.md` when numbered file is absent | Reads `01-business-flows/00-index.md` | +| `knowledge-base-manager` | Supports flat `active-sprint.md` as fallback | Prefers `04-active-sprint/00-index.md` and creates detail files inside numbered folders when needed | ## Scope of This Implementation Implemented in this repo: -- V1 hybrid spec +- V1 hybrid spec using numbered layout - Tier 1 and Tier 2 templates - `.kb-config.yml` contract - scaffold prompt and reusable scripts @@ -77,4 +76,4 @@ Implemented in this repo: Not implemented in this repo: - direct migration of Sneha or IAGES repositories -- production GitHub auth and scheduling in downstream repos +- automatic sprint sync or scheduling diff --git a/knowledge-base/SPEC.md b/knowledge-base/SPEC.md index 2b4872f..115ad30 100644 --- a/knowledge-base/SPEC.md +++ b/knowledge-base/SPEC.md @@ -2,7 +2,7 @@ ## Status - Version: `1` -- Date: `2026-03-06` +- Date: `2026-03-07` - State: `Current` ## Goal @@ -15,36 +15,42 @@ Provide a project-local, token-efficient knowledge base that is easy to scaffold 2. Small default footprint: Tier 1 is required and intentionally compact. 3. Optional advanced depth: Tier 2 is opt-in per project. 4. Deterministic reads: agents read the entry file first, then load only mapped files. -5. Minimal maintenance surface: Tier 1 stays small and predictable. +5. Tree layout for cheaper reads: index files stay small, while deeper detail lives in child files loaded only when needed. 6. Tool agnostic content: KB content stays plain Markdown plus lightweight config. ## Canonical Project Layout ```text knowledge-base/ -├── 00-index.md -├── architecture.md -├── business-flows.md -├── active-sprint.md -├── risks.md +├── 00-master.md +├── 01-business-flows/ +│ └── 00-index.md +├── 02-architecture/ +│ └── 00-index.md +├── 03-risk-model/ +│ └── 00-index.md +├── 04-active-sprint/ +│ └── 00-index.md ├── .kb-config.yml -└── advanced/ - ├── decision-log.md - ├── incident-log.md - ├── feature-history.md - ├── integration-map.md - ├── metrics.md - └── known-constraints.md +├── advanced/ +│ ├── decision-log.md +│ ├── incident-log.md +│ ├── feature-history.md +│ ├── integration-map.md +│ ├── metrics.md +│ └── known-constraints.md +└── scripts/ + └── validate_hybrid_kb.py ``` ## Tier Model ### Tier 1: Required -- `00-index.md` -- `architecture.md` -- `business-flows.md` -- `active-sprint.md` -- `risks.md` +- `00-master.md` +- `01-business-flows/00-index.md` +- `02-architecture/00-index.md` +- `03-risk-model/00-index.md` +- `04-active-sprint/00-index.md` ### Tier 2: Optional - `advanced/decision-log.md` @@ -58,17 +64,17 @@ knowledge-base/ | File | Owner | Notes | |---|---|---| -| `00-index.md` | Human | Keep concise; update when KB structure or project metadata changes | -| `architecture.md` | Human | Update on major architecture changes | -| `business-flows.md` | Human | Update when business flows materially change | -| `risks.md` | Human | Update during reviews, incidents, or notable risk discovery | -| `active-sprint.md` | Human or project-specific process | Current delivery state file | +| `00-master.md` | Human | Keep concise; update when KB structure or project metadata changes | +| `01-business-flows/00-index.md` | Human | Keep as an index only; flow detail belongs in child files in `01-business-flows/` | +| `02-architecture/00-index.md` | Human | Keep as an index/summary; detailed design notes belong in child files in `02-architecture/` | +| `03-risk-model/00-index.md` | Human | Keep as an index/summary; detailed risk notes belong in child files in `03-risk-model/` | +| `04-active-sprint/00-index.md` | Human or project-specific process | Current delivery state file | | Tier 2 append-only logs | Human or semi-automated | Prefer append-only entries | ## Read Contract ### Entry-point rule -Agents read `knowledge-base/00-index.md` first. +Agents read `knowledge-base/00-master.md` first. ### Config rule If `knowledge-base/.kb-config.yml` exists, it is the runtime source of truth for enabled modules and loading defaults. @@ -77,11 +83,14 @@ If `knowledge-base/.kb-config.yml` exists, it is the runtime source of truth for | Task | Files | |---|---| -| Code review | `architecture.md`, `risks.md` | -| Planning | `business-flows.md`, `architecture.md`, `active-sprint.md` | -| Sprint work | `active-sprint.md` | +| Code review | `02-architecture/00-index.md`, `03-risk-model/00-index.md` | +| Planning | `01-business-flows/00-index.md`, `02-architecture/00-index.md`, `04-active-sprint/00-index.md` | +| Sprint work | `04-active-sprint/00-index.md` | | Onboarding | All Tier 1 files | -| Incident response | `risks.md`, `advanced/incident-log.md` when enabled | +| Incident response | `03-risk-model/00-index.md`, `advanced/incident-log.md` when enabled | + +### Section expansion rule +If more detail is needed, agents should open child files inside the relevant numbered directory rather than loading unrelated sections. ### No-assumptions rule If a relevant file is missing or clearly incomplete, agents skip it and continue with available context. They do not fabricate missing context. @@ -92,9 +101,10 @@ If `knowledge-base/` or the entry file does not exist, agents proceed without KB ## Write Contract 1. Only the designated KB maintenance flow may write automated updates. -2. This starter kit does not ship a sprint sync script or workflow. -3. Tier 2 logs should prefer append-only updates. -4. Agents that consume KB context remain read-only. +2. This starter kit ships scaffold + validation only. +3. New section detail should be written into child files inside the matching numbered directory, then linked from that section's `00-index.md`. +4. Tier 2 logs should prefer append-only updates. +5. Agents that consume KB context remain read-only. ## `.kb-config.yml` Contract @@ -106,21 +116,22 @@ Minimum supported keys: ## Compatibility Rules -### Legacy read support -Agents and helpers may support these legacy files: -- `knowledge-base/00-master.md` -- `knowledge-base/01-business-flows/00-index.md` -- `knowledge-base/02-architecture/00-index.md` -- `knowledge-base/03-risk-model/00-index.md` -- `knowledge-base/04-active-sprint/00-index.md` +### Flat-layout read support +Agents and helpers may support these flat-layout files when the numbered layout is absent: +- `knowledge-base/00-index.md` +- `knowledge-base/business-flows.md` +- `knowledge-base/architecture.md` +- `knowledge-base/risks.md` +- `knowledge-base/active-sprint.md` -### Legacy write support -Sprint sync helpers may write to legacy sprint files only when the canonical V1 sprint file is absent. +### Flat-layout migration support +Projects created during the flat-layout phase may remain readable until migrated. New installs must use the numbered layout. ## Maintenance Cadence Recommended default: - update Tier 1 when project reality changes +- add child files under a numbered section when detail grows beyond the index - use append-only updates for Tier 2 logs where possible - run the KB validator after setup or structural changes @@ -134,6 +145,7 @@ Recommended default: - Is the change Tier 1 or Tier 2? - Does it increase default token cost? -- Is the file still concise and scannable? +- Is the relevant index file still concise and scannable? +- Does detailed content live in the correct section directory? - Is ownership clear? - Does the change preserve tool-agnostic plain-text content? diff --git a/knowledge-base/prompts/install-hybrid-kb.md b/knowledge-base/prompts/install-hybrid-kb.md index 6cd2898..34be4aa 100644 --- a/knowledge-base/prompts/install-hybrid-kb.md +++ b/knowledge-base/prompts/install-hybrid-kb.md @@ -23,12 +23,12 @@ Follow these steps exactly: - the 5 most recent git commits 2. Check whether `knowledge-base/` already exists. - If it exists, do not overwrite files silently. Show me what exists and ask how to proceed. -3. Create `knowledge-base/` using the flat-file hybrid contract: - - `00-index.md` - - `architecture.md` - - `business-flows.md` - - `active-sprint.md` - - `risks.md` +3. Create `knowledge-base/` using the numbered hybrid contract: + - `00-master.md` + - `01-business-flows/00-index.md` + - `02-architecture/00-index.md` + - `03-risk-model/00-index.md` + - `04-active-sprint/00-index.md` - `.kb-config.yml` 4. Evaluate whether Tier 2 is needed for this project. - Use evidence only from the codebase and project docs. diff --git a/knowledge-base/scripts/scaffold_hybrid_kb.py b/knowledge-base/scripts/scaffold_hybrid_kb.py index 26fede0..11dd64b 100755 --- a/knowledge-base/scripts/scaffold_hybrid_kb.py +++ b/knowledge-base/scripts/scaffold_hybrid_kb.py @@ -10,11 +10,11 @@ TEMPLATES = ROOT / "knowledge-base" / "templates" SCRIPT_ROOT = ROOT / "knowledge-base" / "scripts" CORE_FILES = [ - "00-index.md", - "architecture.md", - "business-flows.md", - "active-sprint.md", - "risks.md", + "00-master.md", + "01-business-flows/00-index.md", + "02-architecture/00-index.md", + "03-risk-model/00-index.md", + "04-active-sprint/00-index.md", ".kb-config.yml", ] ADVANCED_MAP = { @@ -116,13 +116,7 @@ def main() -> int: actions.append(copy_file(TEMPLATES / rel, kb_root / rel, args.overwrite)) for script_name in SUPPORT_SCRIPTS: - actions.append( - copy_file( - SCRIPT_ROOT / script_name, - kb_root / "scripts" / script_name, - args.overwrite, - ) - ) + actions.append(copy_file(SCRIPT_ROOT / script_name, kb_root / "scripts" / script_name, args.overwrite)) actions.append(configure_kb_config(kb_root / ".kb-config.yml", enabled)) actions.append(ensure_claude_section(project_root)) diff --git a/knowledge-base/scripts/validate_hybrid_kb.py b/knowledge-base/scripts/validate_hybrid_kb.py index 53caa1b..4b3ddc3 100755 --- a/knowledge-base/scripts/validate_hybrid_kb.py +++ b/knowledge-base/scripts/validate_hybrid_kb.py @@ -2,10 +2,17 @@ from __future__ import annotations import argparse -import sys from pathlib import Path -REQUIRED_FILES = [ +TREE_REQUIRED = [ + "knowledge-base/00-master.md", + "knowledge-base/01-business-flows/00-index.md", + "knowledge-base/02-architecture/00-index.md", + "knowledge-base/03-risk-model/00-index.md", + "knowledge-base/04-active-sprint/00-index.md", + "knowledge-base/.kb-config.yml", +] +FLAT_REQUIRED = [ "knowledge-base/00-index.md", "knowledge-base/architecture.md", "knowledge-base/business-flows.md", @@ -21,14 +28,25 @@ "metrics": "knowledge-base/advanced/metrics.md", "known-constraints": "knowledge-base/advanced/known-constraints.md", } +TREE_ENTRY_REFS = [ + "01-business-flows/00-index.md", + "02-architecture/00-index.md", + "03-risk-model/00-index.md", + "04-active-sprint/00-index.md", +] +FLAT_ENTRY_REFS = [ + "architecture.md", + "business-flows.md", + "active-sprint.md", + "risks.md", +] def read_enabled_tier2(config_path: Path) -> list[str]: enabled = [] in_block = False for raw in config_path.read_text().splitlines(): - line = raw.rstrip() - stripped = line.strip() + stripped = raw.strip() if stripped == "enabled_tier2:": in_block = True continue @@ -41,38 +59,66 @@ def read_enabled_tier2(config_path: Path) -> list[str]: return enabled +def detect_layout(root: Path) -> str | None: + tree_entry = root / "knowledge-base/00-master.md" + flat_entry = root / "knowledge-base/00-index.md" + if tree_entry.exists(): + return "tree" + if flat_entry.exists(): + return "flat" + return None + + +def validate_required(root: Path, required: list[str], errors: list[str]) -> None: + for rel in required: + if not (root / rel).exists(): + errors.append(f"missing required file: {rel}") + + +def validate_config(root: Path, errors: list[str]) -> None: + config_path = root / "knowledge-base/.kb-config.yml" + if not config_path.exists(): + return + contents = config_path.read_text() + for key in ["version:", "source_of_truth:", "loading_defaults:"]: + if key not in contents: + errors.append(f"missing config key: {key.rstrip(':')}") + for module in read_enabled_tier2(config_path): + rel = OPTIONAL_BY_KEY.get(module) + if rel is None: + errors.append(f"unknown enabled Tier 2 module in config: {module}") + elif not (root / rel).exists(): + errors.append(f"enabled Tier 2 file missing: {rel}") + + +def validate_entry(entry: Path, refs: list[str], errors: list[str]) -> None: + if not entry.exists(): + return + entry_text = entry.read_text() + for ref in refs: + if ref not in entry_text: + errors.append(f"entry file does not reference: {ref}") + + def main() -> int: parser = argparse.ArgumentParser(description="Validate a hybrid KB installation") parser.add_argument("project_root", help="Path to the target project root") args = parser.parse_args() root = Path(args.project_root).resolve() - errors = [] + errors: list[str] = [] + layout = detect_layout(root) - for rel in REQUIRED_FILES: - path = root / rel - if not path.exists(): - errors.append(f"missing required file: {rel}") + if layout == "tree": + validate_required(root, TREE_REQUIRED, errors) + validate_entry(root / "knowledge-base/00-master.md", TREE_ENTRY_REFS, errors) + elif layout == "flat": + validate_required(root, FLAT_REQUIRED, errors) + validate_entry(root / "knowledge-base/00-index.md", FLAT_ENTRY_REFS, errors) + else: + errors.append("knowledge base entry file not found: expected knowledge-base/00-master.md or knowledge-base/00-index.md") - config_path = root / "knowledge-base/.kb-config.yml" - if config_path.exists(): - contents = config_path.read_text() - for key in ["version:", "source_of_truth:", "loading_defaults:"]: - if key not in contents: - errors.append(f"missing config key: {key.rstrip(':')}") - for module in read_enabled_tier2(config_path): - rel = OPTIONAL_BY_KEY.get(module) - if rel is None: - errors.append(f"unknown enabled Tier 2 module in config: {module}") - elif not (root / rel).exists(): - errors.append(f"enabled Tier 2 file missing: {rel}") - - entry = root / "knowledge-base/00-index.md" - if entry.exists(): - entry_text = entry.read_text() - for ref in ["architecture.md", "business-flows.md", "active-sprint.md", "risks.md"]: - if ref not in entry_text: - errors.append(f"entry file does not reference: {ref}") + validate_config(root, errors) if errors: print("Hybrid KB validation failed:") @@ -80,7 +126,7 @@ def main() -> int: print(f"- {error}") return 1 - print("Hybrid KB validation passed.") + print(f"Hybrid KB validation passed ({layout} layout).") return 0 diff --git a/knowledge-base/templates/.kb-config.yml b/knowledge-base/templates/.kb-config.yml index 7a5729b..76e3dce 100644 --- a/knowledge-base/templates/.kb-config.yml +++ b/knowledge-base/templates/.kb-config.yml @@ -7,23 +7,23 @@ enabled_tier2: # Add optional module keys here when enabled for the project. loading_defaults: code_review: - - architecture.md - - risks.md + - 02-architecture/00-index.md + - 03-risk-model/00-index.md planning: - - business-flows.md - - architecture.md - - active-sprint.md + - 01-business-flows/00-index.md + - 02-architecture/00-index.md + - 04-active-sprint/00-index.md sprint_work: - - active-sprint.md + - 04-active-sprint/00-index.md onboarding: - - 00-index.md - - architecture.md - - business-flows.md - - active-sprint.md - - risks.md + - 00-master.md + - 01-business-flows/00-index.md + - 02-architecture/00-index.md + - 03-risk-model/00-index.md + - 04-active-sprint/00-index.md incident_response: - - risks.md + - 03-risk-model/00-index.md - advanced/incident-log.md compatibility: - legacy_entrypoint: knowledge-base/00-master.md - legacy_sprint_file: knowledge-base/04-active-sprint/00-index.md + flat_entrypoint: knowledge-base/00-index.md + flat_sprint_file: knowledge-base/active-sprint.md diff --git a/knowledge-base/templates/00-index.md b/knowledge-base/templates/00-index.md deleted file mode 100644 index be916e8..0000000 --- a/knowledge-base/templates/00-index.md +++ /dev/null @@ -1,35 +0,0 @@ -# Knowledge Base Index: {{PROJECT_NAME}} - -## Purpose -This is the only required first read for agents. Keep it short. - -## Project Snapshot -- Project: {{PROJECT_NAME}} -- One-line summary: {{PROJECT_SUMMARY}} -- Primary stack: {{PRIMARY_STACK}} -- Owners: {{PROJECT_OWNERS}} -- KB version: 1 - -## Files -- `architecture.md`: System boundaries, module map, and non-negotiable architecture rules. -- `business-flows.md`: Core user journeys and business rules that affect implementation. -- `active-sprint.md`: Current delivery state, active work, blockers, and recently completed items. -- `risks.md`: Known technical, operational, and security-sensitive risks. -- `advanced/decision-log.md`: Optional. Append-only architecture and product decisions. -- `advanced/incident-log.md`: Optional. Append-only incident summaries and prevention notes. -- `advanced/feature-history.md`: Optional. Shipped feature history and notable outcomes. -- `advanced/integration-map.md`: Optional. External systems, auth methods, and failure surfaces. -- `advanced/metrics.md`: Optional. Baseline metrics and SLO/SLA context. -- `advanced/known-constraints.md`: Optional. Hard technical, contractual, or regulatory constraints. - -## Loading Rules -- Code review: load `architecture.md`, `risks.md` -- Planning: load `business-flows.md`, `architecture.md`, `active-sprint.md` -- Sprint work: load `active-sprint.md` -- Onboarding: load all Tier 1 files -- Incident response: load `risks.md`, then `advanced/incident-log.md` if enabled - -## Writing Rules -- Treat KB content as read-only unless you are the designated KB maintenance flow. -- Prefer `.kb-config.yml` as the runtime source of truth for enabled advanced modules. -- If this flat-file contract is absent, legacy projects may still use `00-master.md` and the numbered directories. diff --git a/knowledge-base/00-master.md b/knowledge-base/templates/00-master.md similarity index 100% rename from knowledge-base/00-master.md rename to knowledge-base/templates/00-master.md diff --git a/knowledge-base/01-business-flows/00-index.md b/knowledge-base/templates/01-business-flows/00-index.md similarity index 100% rename from knowledge-base/01-business-flows/00-index.md rename to knowledge-base/templates/01-business-flows/00-index.md diff --git a/knowledge-base/02-architecture/00-index.md b/knowledge-base/templates/02-architecture/00-index.md similarity index 100% rename from knowledge-base/02-architecture/00-index.md rename to knowledge-base/templates/02-architecture/00-index.md diff --git a/knowledge-base/03-risk-model/00-index.md b/knowledge-base/templates/03-risk-model/00-index.md similarity index 100% rename from knowledge-base/03-risk-model/00-index.md rename to knowledge-base/templates/03-risk-model/00-index.md diff --git a/knowledge-base/04-active-sprint/00-index.md b/knowledge-base/templates/04-active-sprint/00-index.md similarity index 100% rename from knowledge-base/04-active-sprint/00-index.md rename to knowledge-base/templates/04-active-sprint/00-index.md diff --git a/knowledge-base/templates/CLAUDE.section.md b/knowledge-base/templates/CLAUDE.section.md index 750c733..d6ed4e3 100644 --- a/knowledge-base/templates/CLAUDE.section.md +++ b/knowledge-base/templates/CLAUDE.section.md @@ -3,11 +3,11 @@ This project stores structured context in `knowledge-base/`. ### Reading Rules -- Read `knowledge-base/00-index.md` first. +- Read `knowledge-base/00-master.md` first. - If `knowledge-base/.kb-config.yml` exists, use it as the source of truth for enabled modules and loading defaults. - Load only the files needed for the current task. - Treat KB files as read-only unless you are the designated KB maintenance flow. -- If the flat-file KB does not exist, you may fall back to the legacy numbered layout if present. +- If the numbered KB does not exist, you may fall back to the flat-file layout if present. ### Graceful Degradation If no knowledge base exists, proceed normally without KB-aware behavior. diff --git a/knowledge-base/templates/README.md b/knowledge-base/templates/README.md index 09e9170..f08d48a 100644 --- a/knowledge-base/templates/README.md +++ b/knowledge-base/templates/README.md @@ -3,11 +3,11 @@ These templates are copied into downstream projects. ## Core templates -- `00-index.md` -- `architecture.md` -- `business-flows.md` -- `active-sprint.md` -- `risks.md` +- `00-master.md` +- `01-business-flows/00-index.md` +- `02-architecture/00-index.md` +- `03-risk-model/00-index.md` +- `04-active-sprint/00-index.md` - `.kb-config.yml` - `CLAUDE.section.md` @@ -20,6 +20,7 @@ These templates are copied into downstream projects. - `advanced/known-constraints.md` ## Authoring rules -- Keep Tier 1 concise and task-oriented. +- Keep the section index files concise and task-oriented. +- Put section detail into child files inside the matching numbered directory. - Treat Tier 2 as opt-in and mostly append-only. - Keep KB content plain Markdown plus lightweight config. diff --git a/knowledge-base/templates/active-sprint.md b/knowledge-base/templates/active-sprint.md deleted file mode 100644 index 89f87fc..0000000 --- a/knowledge-base/templates/active-sprint.md +++ /dev/null @@ -1,38 +0,0 @@ -# Active Sprint: {{PROJECT_NAME}} - -## Purpose -Track current delivery state with minimal maintenance. This is the primary automation target. - -## Ownership -- Default owner: KB sync automation -- Human review: engineering or delivery lead - -## Sprint Snapshot -- Sprint / cycle: {{SPRINT_NAME}} -- Goal: {{SPRINT_GOAL}} -- Period: {{SPRINT_PERIOD}} -- Update mode: see `.kb-config.yml` - -## Manual Notes -- {{MANUAL_NOTE_1}} - -## Active Items - -| Issue | Title | Status | Assignee | Note | -|---|---|---|---|---| -| #{{ISSUE_1}} | {{ISSUE_TITLE_1}} | {{ISSUE_STATUS_1}} | {{ISSUE_ASSIGNEE_1}} | {{ISSUE_NOTE_1}} | - - -## Blockers - -| Issue | Blocker | Owner | -|---|---|---| -| #{{BLOCKED_ISSUE_1}} | {{BLOCKER_1}} | {{BLOCKER_OWNER_1}} | - - -## Recently Completed - -| Issue / PR | Title | Completed On | -|---|---|---| -| #{{DONE_1}} | {{DONE_TITLE_1}} | {{DONE_DATE_1}} | - diff --git a/knowledge-base/templates/architecture.md b/knowledge-base/templates/architecture.md deleted file mode 100644 index 490fcec..0000000 --- a/knowledge-base/templates/architecture.md +++ /dev/null @@ -1,38 +0,0 @@ -# Architecture: {{PROJECT_NAME}} - -## Purpose -Capture the current architectural shape in a compact, implementation-facing format. - -## Brevity Rules -- Target: under 250 lines -- Prefer tables and short bullets -- Do not paste full schemas or long narratives - -## Stack Summary -| Layer | Technology | Notes | -|---|---|---| -| Frontend | {{FRONTEND_TECH}} | {{FRONTEND_NOTES}} | -| Backend | {{BACKEND_TECH}} | {{BACKEND_NOTES}} | -| Data | {{DATA_TECH}} | {{DATA_NOTES}} | -| Infra / Runtime | {{INFRA_TECH}} | {{INFRA_NOTES}} | - -## Module Map -| Module / Directory | Responsibility | Must Not Contain | -|---|---|---| -| {{MODULE_1}} | {{RESPONSIBILITY_1}} | {{FORBIDDEN_1}} | -| {{MODULE_2}} | {{RESPONSIBILITY_2}} | {{FORBIDDEN_2}} | -| {{MODULE_3}} | {{RESPONSIBILITY_3}} | {{FORBIDDEN_3}} | - -## Integration Points -| System | Purpose | Auth / Trust Boundary | -|---|---|---| -| {{INTEGRATION_1}} | {{PURPOSE_1}} | {{AUTH_1}} | - -## Non-Negotiable Rules -- {{ARCH_RULE_1}} -- {{ARCH_RULE_2}} -- {{ARCH_RULE_3}} - -## Example Entry Style -- Good: "Business logic lives in services; controllers stay thin." -- Bad: multi-paragraph history of why services exist. diff --git a/knowledge-base/templates/business-flows.md b/knowledge-base/templates/business-flows.md deleted file mode 100644 index 203f00e..0000000 --- a/knowledge-base/templates/business-flows.md +++ /dev/null @@ -1,41 +0,0 @@ -# Business Flows: {{PROJECT_NAME}} - -## Purpose -Describe the core user journeys and business rules that materially affect implementation and review. - -## Brevity Rules -- Target: under 200 lines -- Use numbered flows, not prose essays -- Include only flows that change engineering decisions - -## Roles -- {{ROLE_1}} -- {{ROLE_2}} -- {{ROLE_3}} - -## Core Flows -### BF-01: {{FLOW_NAME_1}} -- Initiator: {{FLOW_INITIATOR_1}} -- Outcome: {{FLOW_OUTCOME_1}} -- Steps: - 1. {{FLOW_STEP_1A}} - 2. {{FLOW_STEP_1B}} - 3. {{FLOW_STEP_1C}} -- Business rules: - - {{FLOW_RULE_1A}} - - {{FLOW_RULE_1B}} - -### BF-02: {{FLOW_NAME_2}} -- Initiator: {{FLOW_INITIATOR_2}} -- Outcome: {{FLOW_OUTCOME_2}} -- Steps: - 1. {{FLOW_STEP_2A}} - 2. {{FLOW_STEP_2B}} - 3. {{FLOW_STEP_2C}} -- Business rules: - - {{FLOW_RULE_2A}} - - {{FLOW_RULE_2B}} - -## Example Entry Style -- Good: short numbered steps with explicit roles and outcome. -- Bad: implementation details, endpoint names, or DB schema notes. diff --git a/knowledge-base/templates/risks.md b/knowledge-base/templates/risks.md deleted file mode 100644 index 37dc81a..0000000 --- a/knowledge-base/templates/risks.md +++ /dev/null @@ -1,23 +0,0 @@ -# Risks: {{PROJECT_NAME}} - -## Purpose -Capture the small set of risks that should influence planning, implementation, testing, and review. - -## Brevity Rules -- Target: under 150 lines -- Keep this list curated -- Prefer actionable risk statements over generic warnings - -## Risk Register -| Risk ID | Area | Level | Why it matters | Required caution | -|---|---|---|---|---| -| R-01 | {{RISK_AREA_1}} | {{RISK_LEVEL_1}} | {{RISK_REASON_1}} | {{RISK_CAUTION_1}} | -| R-02 | {{RISK_AREA_2}} | {{RISK_LEVEL_2}} | {{RISK_REASON_2}} | {{RISK_CAUTION_2}} | - -## Security / Sensitive Data Rules -- {{SENSITIVE_RULE_1}} -- {{SENSITIVE_RULE_2}} - -## Example Entry Style -- Good: "Auth/session changes are high risk because they affect all users and rollback is hard." -- Bad: generic "security is important" statements. From ab0fcbc89228e8689244a73c3fc1a173bbfdc1a8 Mon Sep 17 00:00:00 2001 From: Anurag Kumawat Date: Sat, 7 Mar 2026 12:05:11 +0530 Subject: [PATCH 12/16] updated --- README.md | 4 +- claude/README.md | 6 +- .../business-analyst/business-analyst.md | 16 ++- .../implementation-executor.md | 16 ++- .../implementation-planner.md | 21 +-- .../agents/knowledge-base-manager/README.md | 12 +- .../knowledge-base-manager.md | 56 ++++---- knowledge-base/README.md | 53 +++---- knowledge-base/SPEC-RECONCILIATION.md | 78 ++++++----- knowledge-base/SPEC.md | 64 ++++----- knowledge-base/prompts/install-hybrid-kb.md | 16 ++- .../scaffold_hybrid_kb.cpython-313.pyc | Bin 0 -> 6786 bytes .../validate_hybrid_kb.cpython-313.pyc | Bin 0 -> 6323 bytes knowledge-base/scripts/scaffold_hybrid_kb.py | 8 +- knowledge-base/scripts/validate_hybrid_kb.py | 53 ++++--- knowledge-base/templates/.kb-config.yml | 31 +++-- knowledge-base/templates/00-master.md | 9 +- knowledge-base/templates/01-business-flows.md | 40 ++++++ .../templates/01-business-flows/00-index.md | 45 ------ knowledge-base/templates/02-architecture.md | 41 ++++++ .../templates/02-architecture/00-index.md | 129 ------------------ knowledge-base/templates/03-risk-model.md | 38 ++++++ .../templates/03-risk-model/00-index.md | 105 -------------- knowledge-base/templates/04-active-sprint.md | 32 +++++ .../templates/04-active-sprint/00-index.md | 84 ------------ knowledge-base/templates/CLAUDE.section.md | 2 +- knowledge-base/templates/README.md | 12 +- 27 files changed, 400 insertions(+), 571 deletions(-) create mode 100644 knowledge-base/scripts/__pycache__/scaffold_hybrid_kb.cpython-313.pyc create mode 100644 knowledge-base/scripts/__pycache__/validate_hybrid_kb.cpython-313.pyc create mode 100644 knowledge-base/templates/01-business-flows.md delete mode 100644 knowledge-base/templates/01-business-flows/00-index.md create mode 100644 knowledge-base/templates/02-architecture.md delete mode 100644 knowledge-base/templates/02-architecture/00-index.md create mode 100644 knowledge-base/templates/03-risk-model.md delete mode 100644 knowledge-base/templates/03-risk-model/00-index.md create mode 100644 knowledge-base/templates/04-active-sprint.md delete mode 100644 knowledge-base/templates/04-active-sprint/00-index.md diff --git a/README.md b/README.md index a9688d3..44f6682 100644 --- a/README.md +++ b/README.md @@ -14,7 +14,7 @@ Individual projects opt into recipes by copying or referencing them. | 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 tree templates, config, scaffolding, and validation | +| 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 @@ -23,7 +23,7 @@ The current KB model is a hybrid starter kit: - 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 a numbered tree so agents can read only the narrow section they need. +- 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). diff --git a/claude/README.md b/claude/README.md index 0460973..6192766 100644 --- a/claude/README.md +++ b/claude/README.md @@ -13,12 +13,12 @@ This directory contains reusable, templatized Claude Code agents that can be set ## Knowledge Base Contract -These agents now prefer the numbered hybrid KB 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/00-index.md`, `02-architecture/00-index.md`, `03-risk-model/00-index.md`, `04-active-sprint/00-index.md` +- core files: `01-business-flows.md`, `02-architecture.md`, `03-risk-model.md`, `04-active-sprint.md` -Projects created during the temporary flat-layout phase remain supported as a fallback. +Older numbered-tree and legacy-flat KB layouts remain supported as fallbacks. ## Setting Up Agents in Your Project diff --git a/claude/agents/business-analyst/business-analyst.md b/claude/agents/business-analyst/business-analyst.md index a53d89a..a07b9de 100644 --- a/claude/agents/business-analyst/business-analyst.md +++ b/claude/agents/business-analyst/business-analyst.md @@ -36,15 +36,17 @@ You are an expert business analyst for {{PROJECT_NAME}}. Before reasoning about requirements, check for a project knowledge base: 1. Prefer the numbered entry file at `knowledge-base/00-master.md`. - - If it does **not** exist, fall back to `knowledge-base/00-index.md`. - - If neither exists: skip this entire section and proceed normally. + - 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/00-index.md` when it exists and is complete. -5. If the project still uses the flat compatibility layout, fall back to `knowledge-base/business-flows.md`. -6. Skip any KB file that is clearly incomplete or still full of placeholders / `TODO:` content. -7. 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**. -8. Do **not** write to or modify any knowledge base file. +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 diff --git a/claude/agents/implementation-executor/implementation-executor.md b/claude/agents/implementation-executor/implementation-executor.md index 7e8805d..3653554 100644 --- a/claude/agents/implementation-executor/implementation-executor.md +++ b/claude/agents/implementation-executor/implementation-executor.md @@ -14,15 +14,17 @@ You are an expert software engineer and disciplined executor. You take structure 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 it does **not** exist, fall back to `knowledge-base/00-index.md`. - - If neither exists: skip this entire section and proceed normally. + - 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/00-index.md` when it exists and is complete. -5. If the project still uses the flat compatibility layout, fall back to `knowledge-base/architecture.md`. -6. Skip any KB file that is clearly incomplete or still full of placeholders / `TODO:` content. -7. 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**. -8. Do **not** write to or modify any knowledge base file. +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 diff --git a/claude/agents/implementation-planner/implementation-planner.md b/claude/agents/implementation-planner/implementation-planner.md index 59b0ca1..13d7f4c 100644 --- a/claude/agents/implementation-planner/implementation-planner.md +++ b/claude/agents/implementation-planner/implementation-planner.md @@ -13,22 +13,27 @@ You are an elite software architect and technical lead with deep expertise in {{ Before exploring the codebase or reasoning about the implementation, check for a project knowledge base: -1. Prefer the numbered entry file at `knowledge-base/00-master.md`. - - If it does **not** exist, fall back to the compatibility entry file at `knowledge-base/00-index.md`. - - If neither exists: skip this entire section and proceed normally. +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 files when present and complete: +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` -5. If the project is still on the flat compatibility layout, fall back to: +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` -6. Skip any KB file that is clearly incomplete or still full of placeholders / `TODO:` content. -7. 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**. -8. Do **not** write to or modify any knowledge base file. +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 diff --git a/claude/agents/knowledge-base-manager/README.md b/claude/agents/knowledge-base-manager/README.md index 73bd836..4349a9c 100644 --- a/claude/agents/knowledge-base-manager/README.md +++ b/claude/agents/knowledge-base-manager/README.md @@ -6,10 +6,10 @@ A Claude Code agent that keeps the project knowledge base in sync with GitHub is - Fetches GitHub issue data in a tiered, token-efficient order (title + state first, body only if needed, PR only if in-review or done) - Maps each issue to one of four states: Backlog, In Progress, In Review, Done/Closed -- Updates the canonical sprint file at `knowledge-base/04-active-sprint/00-index.md` without duplicating existing entries -- Falls back to `knowledge-base/active-sprint.md` for projects still on the flat compatibility layout -- Optionally promotes significant architectural decisions or risk learnings to the relevant numbered section folders when an issue is closed -- Handles bulk syncs (all open issues) and targeted updates (single issue URL or number) +- Updates the canonical sprint file at `knowledge-base/04-active-sprint.md` without duplicating existing entries +- Falls back to `knowledge-base/04-active-sprint/00-index.md` for older numbered-tree projects and to `knowledge-base/active-sprint.md` for legacy flat projects +- Updates single-file Tier 1 sections when the user explicitly asks for KB changes outside the sprint file +- Appends to advanced files when deeper historical context is requested ## Prerequisites @@ -28,7 +28,7 @@ No placeholders to replace — this agent has no `{{PLACEHOLDER}}` values. It wo ### 2. Register in your project's CLAUDE.md -The bootstrap installation prompt (see `knowledge-base/README.md`) adds this automatically. If registering manually, add to your project's `CLAUDE.md`: +The bootstrap installation prompt adds this automatically. If registering manually, add to your project's `CLAUDE.md`: ```markdown ## Custom Agents @@ -38,7 +38,7 @@ The bootstrap installation prompt (see `knowledge-base/README.md`) adds this aut | `knowledge-base-manager` | When the user wants to update the knowledge base from a GitHub issue, sync the active sprint, or reflect recent GitHub activity in the KB. | ``` -If the project uses the hybrid KB contract, `knowledge-base/.kb-config.yml` is the runtime source of truth and the manager should prefer the numbered layout over the flat compatibility layout. +If the project uses the hybrid KB contract, `knowledge-base/.kb-config.yml` is the runtime source of truth and the manager should prefer the numbered-flat layout over the older layouts. ## Usage diff --git a/claude/agents/knowledge-base-manager/knowledge-base-manager.md b/claude/agents/knowledge-base-manager/knowledge-base-manager.md index 75e3908..8c627dc 100644 --- a/claude/agents/knowledge-base-manager/knowledge-base-manager.md +++ b/claude/agents/knowledge-base-manager/knowledge-base-manager.md @@ -13,15 +13,18 @@ You are the sole maintainer of this project's AI knowledge base. You have full r Before writing anything: -1. Prefer the numbered hybrid contract: +1. Prefer the numbered-flat hybrid contract: - entry file: `knowledge-base/00-master.md` - - sprint file: `knowledge-base/04-active-sprint/00-index.md` + - sprint file: `knowledge-base/04-active-sprint.md` - runtime config: `knowledge-base/.kb-config.yml` -2. If the numbered contract is absent, fall back to the flat compatibility layout: +2. If the numbered-flat contract is absent, fall back to the older numbered-tree layout: + - `knowledge-base/00-master.md` + - `knowledge-base/04-active-sprint/00-index.md` +3. If neither numbered layout exists, fall back to the legacy flat layout: - `knowledge-base/00-index.md` - `knowledge-base/active-sprint.md` -3. If neither contract is present, stop and tell the user that the knowledge base has not been set up yet. -4. Treat the sprint section as the primary automation target. Do not rewrite human-owned architecture or business-flow content unless the user explicitly asks you to do so. +4. If no contract is present, stop and tell the user that the knowledge base has not been set up yet. +5. Treat `04-active-sprint.md` as the primary automation target. Do not rewrite other Tier 1 files unless the user explicitly asks you to do so. ## Supported Prompt Patterns @@ -29,8 +32,9 @@ Before writing anything: - `update active sprint items in the knowledge base` - `sync knowledge base with recent GitHub activity` - `issue # is now — update the KB` -- `add a business flow for to the knowledge base` -- `document the flow in the knowledge base` +- `update the architecture knowledge base` +- `update the risk model knowledge base` +- `update the business flows knowledge base` --- @@ -101,11 +105,11 @@ The knowledge base uses two types of files. You must never confuse them: | File type | Role | Write rule | |-----------|------|-----------| -| `04-active-sprint/00-index.md` | **Canonical V1 sprint file** | Update the sprint tables here | -| `00-master.md` and other section `00-index.md` files | Tier 1 section indexes | Keep concise; link out to deeper child files when detail grows | -| `01-business-flows/*.md`, `02-architecture/*.md`, `03-risk-model/*.md` | Section detail files | Create new files here when adding durable flow, architecture, or risk detail | -| `advanced/*.md` | Optional Tier 2 files | Append only when the user asks or when the project explicitly uses a maintenance process for them | -| `active-sprint.md` | Flat compatibility sprint file | Use only when the numbered sprint file is absent | +| `04-active-sprint.md` | **Canonical V1 sprint file** | Update the sprint tables here | +| `00-master.md`, `01-business-flows.md`, `02-architecture.md`, `03-risk-model.md` | Canonical Tier 1 section files | Update directly when the user explicitly asks for those sections | +| `advanced/*.md` | Optional Tier 2 files | Append or update only when the user asks, or when the project explicitly uses them | +| `04-active-sprint/00-index.md` | Numbered-tree compatibility sprint file | Use only when canonical `04-active-sprint.md` is absent | +| `active-sprint.md` | Legacy flat compatibility sprint file | Use only when neither numbered sprint file exists | Before making any sprint edit, read the target sprint file in full. Locate any existing row for the issue number. This prevents duplication and tells you whether to update or insert. @@ -113,13 +117,11 @@ Before making any sprint edit, read the target sprint file in full. Locate any e ### Step 4b: Non-Sprint KB Edits -If the user explicitly asks you to edit a human-owned KB file: +If the user explicitly asks you to edit a Tier 1 or Tier 2 KB file: -1. Detect whether the project uses the numbered contract or the flat compatibility layout. +1. Detect the best available KB layout. 2. Update only the requested file(s). -3. For numbered projects, prefer this pattern: - - create a new named detail file inside the relevant section folder - - add a concise index reference in that section's `00-index.md` +3. Prefer direct edits to the canonical Tier 1 section file over creating new child files. 4. Prefer append-only edits for Tier 2 logs such as `advanced/decision-log.md` and `advanced/incident-log.md`. 5. Do not refactor or rewrite unrelated KB content while making the requested change. @@ -139,29 +141,26 @@ If the user explicitly asks you to edit a human-owned KB file: #### In Review - Update the issue's Active Issues row: set Status to `In Review`. -- In the Notes column, add the linked PR reference (e.g., `PR #88 open`). If no PR was found, write `In Review — PR link pending`. +- In the Notes column, add the linked PR reference (e.g., `PR #88 open`). If no PR was found, write `In Review - PR link pending`. - No other files are modified. #### Done / Closed - Move the issue row from **Active Issues** to **Completed This Sprint**. - Set `Completed On` to the issue's `closedAt` date, or today's date if unavailable. - If the issue never appeared in Active Issues, insert it directly into Completed. -- **Optional promotion:** If the closed issue introduced a significant business flow, architectural decision, or risk/learning worth preserving long-term, promote it using this two-step process: - 1. **Create a new named file** inside the relevant numbered section folder. Use a kebab-case filename derived from the issue title (for example `knowledge-base/02-architecture/payment-gateway-integration.md` or `knowledge-base/03-risk-model/bulk-delete-risks.md`). Write the durable detail into that file. - 2. **Add a reference row** to the section's `00-index.md` pointing to the new file. - - Only promote when the issue body or linked PR description **explicitly** describes a system-level decision, a reusable business flow, or a durable risk. Do not infer or fabricate. If unsure, skip promotion. +- If the user explicitly asks to preserve a long-term learning from the issue, update the relevant advanced file or Tier 1 section directly. Do not create new child files by default. --- ### Step 6: Write Changes -- Edit only the lines that need to change. Do not rewrite entire files unless the user explicitly asks for a restructure. +- Edit only the lines that need to change. Do not rewrite unrelated KB files. - Preserve existing table alignment, comment blocks, and marker comments. - Never remove template guidance unless the user explicitly asks. - Never fill or remove unresolved placeholders unless the user explicitly confirms the missing value. -- **Canonical V1 sprint file:** update `knowledge-base/04-active-sprint/00-index.md`. -- **Compatibility fallback:** update `knowledge-base/active-sprint.md` only when the numbered sprint file is absent. +- **Canonical V1 sprint file:** update `knowledge-base/04-active-sprint.md`. +- **Numbered-tree fallback:** update `knowledge-base/04-active-sprint/00-index.md` only when canonical V1 sprint file is absent. +- **Legacy flat fallback:** update `knowledge-base/active-sprint.md` only when neither numbered sprint file exists. --- @@ -178,11 +177,12 @@ After writing, report: ## Important Rules - **This agent is the only agent that writes to the knowledge base.** Never instruct another agent to edit KB files. -- **Prefer the numbered hybrid contract.** Only use the flat compatibility layout when the numbered layout is absent. +- **Prefer the numbered-flat hybrid contract.** Only use the older layouts when the canonical layout is absent. - **Never duplicate.** Always read the target file before writing. If the issue is already in the correct state, do nothing and report it as already up to date. - **Never guess state.** If Tier 1 data is ambiguous, move to the next tier. If still ambiguous, ask. - **Preserve `TODO:` placeholders.** Never remove or fill them. -- **Graceful handling of missing KB.** If neither the numbered entry file nor the flat compatibility entry file exists, inform the user that the knowledge base has not been set up yet and stop. +- **Do not create new child files by default.** Use the main Tier 1 section files or advanced files unless the user explicitly asks for a deeper split. +- **Graceful handling of missing KB.** If no supported KB layout exists, inform the user that the knowledge base has not been set up yet and stop. --- diff --git a/knowledge-base/README.md b/knowledge-base/README.md index 6889b02..4863c8c 100644 --- a/knowledge-base/README.md +++ b/knowledge-base/README.md @@ -5,7 +5,7 @@ This directory contains the V1 hybrid knowledge-base starter kit for project-loc ## What This Recipe Provides - A versioned KB contract: [SPEC.md](SPEC.md) -- A reconciliation note against the temporary flat-layout phase: [SPEC-RECONCILIATION.md](SPEC-RECONCILIATION.md) +- A reconciliation note across older layouts: [SPEC-RECONCILIATION.md](SPEC-RECONCILIATION.md) - Governance rules: [GOVERNANCE.md](GOVERNANCE.md) - Review checklist: [REVIEW-CHECKLIST.md](REVIEW-CHECKLIST.md) - Tier 1 and Tier 2 templates under [`templates/`](templates/) @@ -15,19 +15,15 @@ This directory contains the V1 hybrid knowledge-base starter kit for project-loc ## Canonical V1 Layout -New projects should use the numbered tree layout below inside their own repo: +New projects should use the numbered-flat layout below inside their own repo: ```text knowledge-base/ ├── 00-master.md -├── 01-business-flows/ -│ └── 00-index.md -├── 02-architecture/ -│ └── 00-index.md -├── 03-risk-model/ -│ └── 00-index.md -├── 04-active-sprint/ -│ └── 00-index.md +├── 01-business-flows.md +├── 02-architecture.md +├── 03-risk-model.md +├── 04-active-sprint.md ├── .kb-config.yml ├── advanced/ │ ├── decision-log.md @@ -44,10 +40,10 @@ knowledge-base/ ### Tier 1: Required - `00-master.md` -- `01-business-flows/00-index.md` -- `02-architecture/00-index.md` -- `03-risk-model/00-index.md` -- `04-active-sprint/00-index.md` +- `01-business-flows.md` +- `02-architecture.md` +- `03-risk-model.md` +- `04-active-sprint.md` ### Tier 2: Optional - `advanced/decision-log.md` @@ -101,25 +97,34 @@ python3 knowledge-base/scripts/validate_hybrid_kb.py . The validator checks: - required Tier 1 files exist - `.kb-config.yml` has the minimum contract keys -- `00-master.md` references the numbered Tier 1 section files +- `00-master.md` references the numbered-flat Tier 1 files - enabled Tier 2 modules in config have matching files -- flat-layout projects created during the temporary phase still validate as compatibility installs +- older numbered-tree and legacy-flat projects still validate as compatibility installs -## Why The Numbered Tree Layout +## Why The Numbered-Flat Layout - `00-master.md` stays small and cheap to read. -- Section `00-index.md` files stay concise and task-focused. -- Deeper details can live in child files inside the matching numbered folder. -- Agents can load only the one section they need instead of pulling broad narrative files. +- Tier 1 section files are separate, so agents do not need to load the full KB. +- Tier 1 section files are single write targets, so KB updates are more reliable than index-plus-child-file trees. +- Tier 2 remains optional for deeper historical context. + +## Compatibility Support + +Older projects may still use one of these layouts: -## Flat-Layout Compatibility +### Numbered tree +- `00-master.md` +- `01-business-flows/00-index.md` +- `02-architecture/00-index.md` +- `03-risk-model/00-index.md` +- `04-active-sprint/00-index.md` -Some projects may still have the temporary flat layout: +### Legacy flat - `00-index.md` - `business-flows.md` - `architecture.md` - `risks.md` - `active-sprint.md` -That layout remains readable and valid as a temporary compatibility path for projects created during the transition. -New projects should use the numbered tree contract. +Those layouts remain readable and valid as temporary compatibility paths for existing projects. +New projects should use the numbered-flat contract. diff --git a/knowledge-base/SPEC-RECONCILIATION.md b/knowledge-base/SPEC-RECONCILIATION.md index 9289575..62032dc 100644 --- a/knowledge-base/SPEC-RECONCILIATION.md +++ b/knowledge-base/SPEC-RECONCILIATION.md @@ -2,72 +2,70 @@ ## Purpose -This note reconciles the pre-existing `engineering-recipes` numbered knowledge-base recipe with the temporary flat-layout phase introduced during the hybrid KB work. +This note reconciles three KB layouts that now exist in project history: +- the original numbered-tree layout +- the temporary unnumbered flat layout +- the current numbered-flat layout ## Current vs Target -| Area | Current repo state | Hybrid V1 target | Decision | +| Area | Older states | Hybrid V1 target | Decision | |---|---|---|---| -| Core layout | Both numbered and flat artifacts exist in repo history | Numbered directories under `knowledge-base/` | New installs use numbered layout; flat layout is compatibility only | -| Entry file | `knowledge-base/00-master.md` and temporary `00-index.md` references | `knowledge-base/00-master.md` | Standardize on `00-master.md`; `00-index.md` is compatibility only | -| Section files | Numbered section directories plus temporary flat section files | `01-business-flows/00-index.md`, `02-architecture/00-index.md`, `03-risk-model/00-index.md`, `04-active-sprint/00-index.md` | New installs use numbered section directories | -| Runtime contract | Mostly documented in `CLAUDE.md` plus `.kb-config.yml` | `.kb-config.yml` plus mirrored `CLAUDE.md` guidance | `.kb-config.yml` is source of truth; `CLAUDE.md` mirrors read rules | -| Sprint file | `04-active-sprint/00-index.md` and temporary `active-sprint.md` references | `04-active-sprint/00-index.md` | Standardize on numbered sprint file | +| Core layout | Numbered-tree and temporary flat layouts both existed | Numbered flat files under `knowledge-base/` | New installs use numbered-flat layout | +| Entry file | `knowledge-base/00-master.md` and temporary `00-index.md` | `knowledge-base/00-master.md` | Standardize on `00-master.md` | +| Section files | `01-business-flows/00-index.md` or `business-flows.md` style files | `01-business-flows.md`, `02-architecture.md`, `03-risk-model.md`, `04-active-sprint.md` | One file per Tier 1 section | +| Runtime contract | `CLAUDE.md` guidance plus `.kb-config.yml` | `.kb-config.yml` plus mirrored `CLAUDE.md` guidance | `.kb-config.yml` remains source of truth | +| Sprint file | `04-active-sprint/00-index.md` or `active-sprint.md` | `04-active-sprint.md` | Standardize on numbered-flat sprint file | | Advanced memory | Optional modules under `advanced/` | Optional modules under `advanced/` | Keep as explicit optional templates | | Automation | Manual validation only | Manual validation only | Do not ship sync automation in the starter kit | -## Decision Gates and Frozen Outcomes +## Frozen Outcomes -### DG-1: Canonical file structure -- **Decision:** Numbered tree layout is canonical. -- **V1 canonical for new projects:** numbered directories under `knowledge-base/`. -- **Compatibility support:** flat-file layout remains readable for projects scaffolded during the temporary transition. +### Layout +- **Canonical:** numbered-flat layout. +- **Reason:** preserves scoped reads while keeping writes simple and reliable. -### DG-2: Canonical entry-point name -- **Decision:** Standardize on `knowledge-base/00-master.md`. -- **Compatibility support:** agents may fall back to `knowledge-base/00-index.md` when needed. +### Entry file +- **Canonical:** `knowledge-base/00-master.md`. +- **Compatibility:** agents may still fall back to `knowledge-base/00-index.md` for older projects. -### DG-3: Agent loading contract source of truth -- **Decision:** Use both, with `.kb-config.yml` as the source of truth. -- **Role of `CLAUDE.md`:** human-readable and tool-specific adapter guidance only. +### Tier 1 write model +- **Decision:** one main file per Tier 1 section. +- **Reason:** the KB manager updates single-file sections more reliably than index-plus-child-file structures. -### DG-4: Sprint file naming and scope -- **Decision:** Adopt `knowledge-base/04-active-sprint/00-index.md` as the V1 canonical sprint file. -- **Compatibility support:** agents may fall back to `knowledge-base/active-sprint.md`. - -### DG-5: Pilot scope for IAGES -- **Decision:** Pilot IAGES backend first. -- **Reason:** it already has agent configuration and is the smaller org-level validation unit for the KB contract. -- **Follow-up:** frontend can be added after backend validation. - -### DG-6: Automation cadence -- **Decision:** manual / agent-driven cadence. -- **Supported modes in this repo:** scaffold + validate only. +### Compatibility support +- **Numbered-tree:** supported as read/write fallback for older projects. +- **Legacy flat:** supported as read/write fallback for projects created during the temporary flat phase. ## Migration Impact ### For new projects -- Use the numbered hybrid contract. +- Use the numbered-flat hybrid contract. - Generate `.kb-config.yml` and append KB rules to the project root `CLAUDE.md`. -### For projects created during the flat-layout phase +### For projects on the numbered-tree layout +- No forced rewrite in V1. +- Updated agents and validator still support the tree structure. +- Migration can happen later by merging section content into numbered-flat files. + +### For projects on the legacy flat layout - No forced rewrite in V1. -- Updated agents and validator support the flat structure. -- Migration to the numbered structure can happen project-by-project. +- Updated agents and validator still support the layout. +- Migration can happen later by renaming files into the numbered-flat scheme. ## Agent Behavior Differences -| Agent | Compatibility behavior | Hybrid V1 behavior | +| Agent | Older compatibility behavior | Hybrid V1 behavior | |---|---|---| -| `implementation-planner` | Reads flat `00-index.md` and flat section files when numbered files are absent | Reads `00-master.md`, follows `.kb-config.yml`, loads numbered sections first | -| `implementation-executor` | Reads flat `architecture.md` when numbered file is absent | Reads `02-architecture/00-index.md` | -| `business-analyst` | Reads flat `business-flows.md` when numbered file is absent | Reads `01-business-flows/00-index.md` | -| `knowledge-base-manager` | Supports flat `active-sprint.md` as fallback | Prefers `04-active-sprint/00-index.md` and creates detail files inside numbered folders when needed | +| `implementation-planner` | Falls back to tree or legacy-flat section files when needed | Reads `00-master.md`, then loads numbered-flat section files | +| `implementation-executor` | Falls back to tree or legacy-flat architecture files | Reads `02-architecture.md` | +| `business-analyst` | Falls back to tree or legacy-flat business files | Reads `01-business-flows.md` | +| `knowledge-base-manager` | Supports older tree/flat write targets as fallback | Prefers `04-active-sprint.md` and single-file Tier 1 updates | ## Scope of This Implementation Implemented in this repo: -- V1 hybrid spec using numbered layout +- V1 hybrid spec using numbered-flat layout - Tier 1 and Tier 2 templates - `.kb-config.yml` contract - scaffold prompt and reusable scripts diff --git a/knowledge-base/SPEC.md b/knowledge-base/SPEC.md index 115ad30..8180a0c 100644 --- a/knowledge-base/SPEC.md +++ b/knowledge-base/SPEC.md @@ -15,7 +15,7 @@ Provide a project-local, token-efficient knowledge base that is easy to scaffold 2. Small default footprint: Tier 1 is required and intentionally compact. 3. Optional advanced depth: Tier 2 is opt-in per project. 4. Deterministic reads: agents read the entry file first, then load only mapped files. -5. Tree layout for cheaper reads: index files stay small, while deeper detail lives in child files loaded only when needed. +5. Reliable writes over deep structure: Tier 1 uses one file per section so KB updates remain predictable. 6. Tool agnostic content: KB content stays plain Markdown plus lightweight config. ## Canonical Project Layout @@ -23,14 +23,10 @@ Provide a project-local, token-efficient knowledge base that is easy to scaffold ```text knowledge-base/ ├── 00-master.md -├── 01-business-flows/ -│ └── 00-index.md -├── 02-architecture/ -│ └── 00-index.md -├── 03-risk-model/ -│ └── 00-index.md -├── 04-active-sprint/ -│ └── 00-index.md +├── 01-business-flows.md +├── 02-architecture.md +├── 03-risk-model.md +├── 04-active-sprint.md ├── .kb-config.yml ├── advanced/ │ ├── decision-log.md @@ -47,10 +43,10 @@ knowledge-base/ ### Tier 1: Required - `00-master.md` -- `01-business-flows/00-index.md` -- `02-architecture/00-index.md` -- `03-risk-model/00-index.md` -- `04-active-sprint/00-index.md` +- `01-business-flows.md` +- `02-architecture.md` +- `03-risk-model.md` +- `04-active-sprint.md` ### Tier 2: Optional - `advanced/decision-log.md` @@ -65,10 +61,10 @@ knowledge-base/ | File | Owner | Notes | |---|---|---| | `00-master.md` | Human | Keep concise; update when KB structure or project metadata changes | -| `01-business-flows/00-index.md` | Human | Keep as an index only; flow detail belongs in child files in `01-business-flows/` | -| `02-architecture/00-index.md` | Human | Keep as an index/summary; detailed design notes belong in child files in `02-architecture/` | -| `03-risk-model/00-index.md` | Human | Keep as an index/summary; detailed risk notes belong in child files in `03-risk-model/` | -| `04-active-sprint/00-index.md` | Human or project-specific process | Current delivery state file | +| `01-business-flows.md` | Human or guided KB maintenance | Main business context file | +| `02-architecture.md` | Human or guided KB maintenance | Main architecture/context file | +| `03-risk-model.md` | Human or guided KB maintenance | Main risk and review guidance file | +| `04-active-sprint.md` | Human or project-specific process | Main volatile delivery-state file | | Tier 2 append-only logs | Human or semi-automated | Prefer append-only entries | ## Read Contract @@ -83,14 +79,11 @@ If `knowledge-base/.kb-config.yml` exists, it is the runtime source of truth for | Task | Files | |---|---| -| Code review | `02-architecture/00-index.md`, `03-risk-model/00-index.md` | -| Planning | `01-business-flows/00-index.md`, `02-architecture/00-index.md`, `04-active-sprint/00-index.md` | -| Sprint work | `04-active-sprint/00-index.md` | +| Code review | `02-architecture.md`, `03-risk-model.md` | +| Planning | `01-business-flows.md`, `02-architecture.md`, `04-active-sprint.md` | +| Sprint work | `04-active-sprint.md` | | Onboarding | All Tier 1 files | -| Incident response | `03-risk-model/00-index.md`, `advanced/incident-log.md` when enabled | - -### Section expansion rule -If more detail is needed, agents should open child files inside the relevant numbered directory rather than loading unrelated sections. +| Incident response | `03-risk-model.md`, `advanced/incident-log.md` when enabled | ### No-assumptions rule If a relevant file is missing or clearly incomplete, agents skip it and continue with available context. They do not fabricate missing context. @@ -102,7 +95,7 @@ If `knowledge-base/` or the entry file does not exist, agents proceed without KB 1. Only the designated KB maintenance flow may write automated updates. 2. This starter kit ships scaffold + validation only. -3. New section detail should be written into child files inside the matching numbered directory, then linked from that section's `00-index.md`. +3. Tier 1 section files are the default write targets. Do not require automatic child-file creation for routine updates. 4. Tier 2 logs should prefer append-only updates. 5. Agents that consume KB context remain read-only. @@ -116,22 +109,29 @@ Minimum supported keys: ## Compatibility Rules -### Flat-layout read support -Agents and helpers may support these flat-layout files when the numbered layout is absent: +### Numbered-tree support +Agents and helpers may support these older numbered-tree files when the canonical numbered-flat layout is absent: +- `knowledge-base/00-master.md` +- `knowledge-base/01-business-flows/00-index.md` +- `knowledge-base/02-architecture/00-index.md` +- `knowledge-base/03-risk-model/00-index.md` +- `knowledge-base/04-active-sprint/00-index.md` + +### Legacy flat support +Agents and helpers may also support these temporary flat-layout files when the canonical numbered-flat layout is absent: - `knowledge-base/00-index.md` - `knowledge-base/business-flows.md` - `knowledge-base/architecture.md` - `knowledge-base/risks.md` - `knowledge-base/active-sprint.md` -### Flat-layout migration support -Projects created during the flat-layout phase may remain readable until migrated. New installs must use the numbered layout. +New installs must use the numbered-flat layout. ## Maintenance Cadence Recommended default: - update Tier 1 when project reality changes -- add child files under a numbered section when detail grows beyond the index +- keep Tier 1 concise enough for routine agent reads - use append-only updates for Tier 2 logs where possible - run the KB validator after setup or structural changes @@ -145,7 +145,7 @@ Recommended default: - Is the change Tier 1 or Tier 2? - Does it increase default token cost? -- Is the relevant index file still concise and scannable? -- Does detailed content live in the correct section directory? +- Is the relevant Tier 1 file still concise and scannable? +- Is the change write-friendly for the KB manager? - Is ownership clear? - Does the change preserve tool-agnostic plain-text content? diff --git a/knowledge-base/prompts/install-hybrid-kb.md b/knowledge-base/prompts/install-hybrid-kb.md index 34be4aa..72de5df 100644 --- a/knowledge-base/prompts/install-hybrid-kb.md +++ b/knowledge-base/prompts/install-hybrid-kb.md @@ -22,14 +22,18 @@ Follow these steps exactly: - top-level directory structure - the 5 most recent git commits 2. Check whether `knowledge-base/` already exists. - - If it exists, do not overwrite files silently. Show me what exists and ask how to proceed. -3. Create `knowledge-base/` using the numbered hybrid contract: + - If it exists, do not overwrite files silently. + - Show me which files already exist, which are missing, and whether this looks like a partial install. + - Ask how to proceed before making changes. +3. Create `knowledge-base/` using the numbered flat hybrid contract: - `00-master.md` - - `01-business-flows/00-index.md` - - `02-architecture/00-index.md` - - `03-risk-model/00-index.md` - - `04-active-sprint/00-index.md` + - `01-business-flows.md` + - `02-architecture.md` + - `03-risk-model.md` + - `04-active-sprint.md` - `.kb-config.yml` + - create `advanced/` only if Tier 2 files are selected + - create `scripts/` for helper scripts 4. Evaluate whether Tier 2 is needed for this project. - Use evidence only from the codebase and project docs. - Consider Tier 2 justified only when the project shows real complexity such as: diff --git a/knowledge-base/scripts/__pycache__/scaffold_hybrid_kb.cpython-313.pyc b/knowledge-base/scripts/__pycache__/scaffold_hybrid_kb.cpython-313.pyc new file mode 100644 index 0000000000000000000000000000000000000000..ddac1cfb991a5109613e66a97439c8469ada8104 GIT binary patch literal 6786 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 literal 0 HcmV?d00001 diff --git a/knowledge-base/scripts/scaffold_hybrid_kb.py b/knowledge-base/scripts/scaffold_hybrid_kb.py index 11dd64b..a992461 100755 --- a/knowledge-base/scripts/scaffold_hybrid_kb.py +++ b/knowledge-base/scripts/scaffold_hybrid_kb.py @@ -11,10 +11,10 @@ SCRIPT_ROOT = ROOT / "knowledge-base" / "scripts" CORE_FILES = [ "00-master.md", - "01-business-flows/00-index.md", - "02-architecture/00-index.md", - "03-risk-model/00-index.md", - "04-active-sprint/00-index.md", + "01-business-flows.md", + "02-architecture.md", + "03-risk-model.md", + "04-active-sprint.md", ".kb-config.yml", ] ADVANCED_MAP = { diff --git a/knowledge-base/scripts/validate_hybrid_kb.py b/knowledge-base/scripts/validate_hybrid_kb.py index 4b3ddc3..8fb30d3 100755 --- a/knowledge-base/scripts/validate_hybrid_kb.py +++ b/knowledge-base/scripts/validate_hybrid_kb.py @@ -4,7 +4,15 @@ import argparse from pathlib import Path -TREE_REQUIRED = [ +NUMBERED_FLAT_REQUIRED = [ + "knowledge-base/00-master.md", + "knowledge-base/01-business-flows.md", + "knowledge-base/02-architecture.md", + "knowledge-base/03-risk-model.md", + "knowledge-base/04-active-sprint.md", + "knowledge-base/.kb-config.yml", +] +NUMBERED_TREE_REQUIRED = [ "knowledge-base/00-master.md", "knowledge-base/01-business-flows/00-index.md", "knowledge-base/02-architecture/00-index.md", @@ -12,7 +20,7 @@ "knowledge-base/04-active-sprint/00-index.md", "knowledge-base/.kb-config.yml", ] -FLAT_REQUIRED = [ +LEGACY_FLAT_REQUIRED = [ "knowledge-base/00-index.md", "knowledge-base/architecture.md", "knowledge-base/business-flows.md", @@ -28,13 +36,19 @@ "metrics": "knowledge-base/advanced/metrics.md", "known-constraints": "knowledge-base/advanced/known-constraints.md", } -TREE_ENTRY_REFS = [ +NUMBERED_FLAT_ENTRY_REFS = [ + "01-business-flows.md", + "02-architecture.md", + "03-risk-model.md", + "04-active-sprint.md", +] +NUMBERED_TREE_ENTRY_REFS = [ "01-business-flows/00-index.md", "02-architecture/00-index.md", "03-risk-model/00-index.md", "04-active-sprint/00-index.md", ] -FLAT_ENTRY_REFS = [ +LEGACY_FLAT_ENTRY_REFS = [ "architecture.md", "business-flows.md", "active-sprint.md", @@ -60,12 +74,12 @@ def read_enabled_tier2(config_path: Path) -> list[str]: def detect_layout(root: Path) -> str | None: - tree_entry = root / "knowledge-base/00-master.md" - flat_entry = root / "knowledge-base/00-index.md" - if tree_entry.exists(): - return "tree" - if flat_entry.exists(): - return "flat" + if (root / "knowledge-base/01-business-flows.md").exists(): + return "numbered-flat" + if (root / "knowledge-base/01-business-flows/00-index.md").exists(): + return "numbered-tree" + if (root / "knowledge-base/00-index.md").exists(): + return "legacy-flat" return None @@ -109,14 +123,19 @@ def main() -> int: errors: list[str] = [] layout = detect_layout(root) - if layout == "tree": - validate_required(root, TREE_REQUIRED, errors) - validate_entry(root / "knowledge-base/00-master.md", TREE_ENTRY_REFS, errors) - elif layout == "flat": - validate_required(root, FLAT_REQUIRED, errors) - validate_entry(root / "knowledge-base/00-index.md", FLAT_ENTRY_REFS, errors) + if layout == "numbered-flat": + validate_required(root, NUMBERED_FLAT_REQUIRED, errors) + validate_entry(root / "knowledge-base/00-master.md", NUMBERED_FLAT_ENTRY_REFS, errors) + elif layout == "numbered-tree": + validate_required(root, NUMBERED_TREE_REQUIRED, errors) + validate_entry(root / "knowledge-base/00-master.md", NUMBERED_TREE_ENTRY_REFS, errors) + elif layout == "legacy-flat": + validate_required(root, LEGACY_FLAT_REQUIRED, errors) + validate_entry(root / "knowledge-base/00-index.md", LEGACY_FLAT_ENTRY_REFS, errors) else: - errors.append("knowledge base entry file not found: expected knowledge-base/00-master.md or knowledge-base/00-index.md") + errors.append( + "knowledge base entry file not found: expected knowledge-base/00-master.md or knowledge-base/00-index.md" + ) validate_config(root, errors) diff --git a/knowledge-base/templates/.kb-config.yml b/knowledge-base/templates/.kb-config.yml index 76e3dce..89b071a 100644 --- a/knowledge-base/templates/.kb-config.yml +++ b/knowledge-base/templates/.kb-config.yml @@ -7,23 +7,28 @@ enabled_tier2: # Add optional module keys here when enabled for the project. loading_defaults: code_review: - - 02-architecture/00-index.md - - 03-risk-model/00-index.md + - 02-architecture.md + - 03-risk-model.md planning: - - 01-business-flows/00-index.md - - 02-architecture/00-index.md - - 04-active-sprint/00-index.md + - 01-business-flows.md + - 02-architecture.md + - 04-active-sprint.md sprint_work: - - 04-active-sprint/00-index.md + - 04-active-sprint.md onboarding: - 00-master.md - - 01-business-flows/00-index.md - - 02-architecture/00-index.md - - 03-risk-model/00-index.md - - 04-active-sprint/00-index.md + - 01-business-flows.md + - 02-architecture.md + - 03-risk-model.md + - 04-active-sprint.md incident_response: - - 03-risk-model/00-index.md + - 03-risk-model.md - advanced/incident-log.md compatibility: - flat_entrypoint: knowledge-base/00-index.md - flat_sprint_file: knowledge-base/active-sprint.md + numbered_tree_entrypoint: knowledge-base/00-master.md + numbered_tree_files: + - knowledge-base/01-business-flows/00-index.md + - knowledge-base/02-architecture/00-index.md + - knowledge-base/03-risk-model/00-index.md + - knowledge-base/04-active-sprint/00-index.md + legacy_flat_entrypoint: knowledge-base/00-index.md diff --git a/knowledge-base/templates/00-master.md b/knowledge-base/templates/00-master.md index cbb3aa6..a854886 100644 --- a/knowledge-base/templates/00-master.md +++ b/knowledge-base/templates/00-master.md @@ -13,7 +13,8 @@ | Section | File | Summary | |---------|------|---------| -| Business Flows | `01-business-flows/00-index.md` | Core user journeys and business process flows for {{PROJECT_NAME}} | -| Architecture | `02-architecture/00-index.md` | Architectural patterns, tech stack decisions, and integration rules | -| Risk Model | `03-risk-model/00-index.md` | Risk classification rules, sensitive areas, and change impact guidance | -| Active Sprint | `04-active-sprint/00-index.md` | Current sprint goal, active issues, and progress tracking | +| Business Flows | `01-business-flows.md` | Core user journeys, flows, and business rules for {{PROJECT_NAME}} | +| Architecture | `02-architecture.md` | Architectural patterns, boundaries, integrations, and implementation constraints | +| Risk Model | `03-risk-model.md` | Risk classification, fragile areas, and review/testing expectations | +| Active Sprint | `04-active-sprint.md` | Current sprint goal, active issues, blockers, and recent completions | +| Advanced Memory | `advanced/` | Optional logs and historical context loaded only when needed | diff --git a/knowledge-base/templates/01-business-flows.md b/knowledge-base/templates/01-business-flows.md new file mode 100644 index 0000000..725c83b --- /dev/null +++ b/knowledge-base/templates/01-business-flows.md @@ -0,0 +1,40 @@ + + +# Business Flows: {{PROJECT_NAME}} + +**Domain:** {{BUSINESS_DOMAIN}} +**Primary Users:** {{PRIMARY_USER_ROLES}} + +## Core Flows + +| Flow ID | Flow Name | Initiator | Outcome | Notes | +|---------|-----------|-----------|---------|-------| +| BF-01 | {{FLOW_NAME_1}} | {{INITIATOR_1}} | {{OUTCOME_1}} | {{NOTES_1}} | +| BF-02 | {{FLOW_NAME_2}} | {{INITIATOR_2}} | {{OUTCOME_2}} | {{NOTES_2}} | + + + +## Flow Summaries + +### {{FLOW_NAME_1}} +- Trigger: {{TRIGGER_1}} +- Main path: {{MAIN_PATH_1}} +- Edge cases: {{EDGE_CASES_1}} +- Important business rule: {{BUSINESS_RULE_1}} + +### {{FLOW_NAME_2}} +- Trigger: {{TRIGGER_2}} +- Main path: {{MAIN_PATH_2}} +- Edge cases: {{EDGE_CASES_2}} +- Important business rule: {{BUSINESS_RULE_2}} + +## Cross-Cutting Rules +- {{CROSS_RULE_1}} +- {{CROSS_RULE_2}} + + diff --git a/knowledge-base/templates/01-business-flows/00-index.md b/knowledge-base/templates/01-business-flows/00-index.md deleted file mode 100644 index 102279f..0000000 --- a/knowledge-base/templates/01-business-flows/00-index.md +++ /dev/null @@ -1,45 +0,0 @@ - - -# Business Flows: {{PROJECT_NAME}} - -**Domain:** {{BUSINESS_DOMAIN}} -**Primary Users:** {{PRIMARY_USER_ROLES}} - ---- - -## Flow Index - -| Flow ID | Flow Name | Initiator | Outcome | File | -|---------|-----------|-----------|---------|------| -| BF-01 | {{FLOW_NAME_1}} | {{INITIATOR_1}} | {{OUTCOME_1}} | [bf-01-{{flow-slug-1}}.md](bf-01-{{flow-slug-1}}.md) | -| BF-02 | {{FLOW_NAME_2}} | {{INITIATOR_2}} | {{OUTCOME_2}} | [bf-02-{{flow-slug-2}}.md](bf-02-{{flow-slug-2}}.md) | - - - ---- - - diff --git a/knowledge-base/templates/02-architecture.md b/knowledge-base/templates/02-architecture.md new file mode 100644 index 0000000..59c1728 --- /dev/null +++ b/knowledge-base/templates/02-architecture.md @@ -0,0 +1,41 @@ + + +# Architecture: {{PROJECT_NAME}} + +## Tech Stack + +| Layer | Technology | Version | Notes | +|-------|------------|---------|-------| +| {{LAYER_1}} | {{TECH_1}} | {{VERSION_1}} | {{NOTES_1}} | +| {{LAYER_2}} | {{TECH_2}} | {{VERSION_2}} | {{NOTES_2}} | +| {{LAYER_3}} | {{TECH_3}} | {{VERSION_3}} | {{NOTES_3}} | + +## Directory Structure + +| Path | Responsibility | Must Not Contain | +|------|----------------|------------------| +| `{{DIR_1}}` | {{RESPONSIBILITY_1}} | {{FORBIDDEN_1}} | +| `{{DIR_2}}` | {{RESPONSIBILITY_2}} | {{FORBIDDEN_2}} | +| `{{DIR_3}}` | {{RESPONSIBILITY_3}} | {{FORBIDDEN_3}} | + +## Established Patterns +- {{PATTERN_1}} +- {{PATTERN_2}} +- {{PATTERN_3}} + +## Integration Points + +| System | Purpose | Contract | Notes | +|--------|---------|----------|-------| +| {{SYSTEM_1}} | {{PURPOSE_1}} | {{CONTRACT_1}} | {{NOTES_4}} | + +## Non-Negotiable Rules +- {{RULE_1}} +- {{RULE_2}} +- {{RULE_3}} + + diff --git a/knowledge-base/templates/02-architecture/00-index.md b/knowledge-base/templates/02-architecture/00-index.md deleted file mode 100644 index e7e47a0..0000000 --- a/knowledge-base/templates/02-architecture/00-index.md +++ /dev/null @@ -1,129 +0,0 @@ - - -# Architecture: {{PROJECT_NAME}} - ---- - -## Tech Stack - -| Layer | Technology | Version | -|-------|-----------|---------| -| {{LAYER_1}} | {{TECH_1}} | {{VERSION_1}} | -| {{LAYER_2}} | {{TECH_2}} | {{VERSION_2}} | -| {{LAYER_3}} | {{TECH_3}} | {{VERSION_3}} | - - - ---- - -## Directory Structure - -``` -{{PROJECT_ROOT}}/ -├── {{DIR_1}}/ # {{DIR_1_PURPOSE}} -├── {{DIR_2}}/ # {{DIR_2_PURPOSE}} -└── {{DIR_3}}/ # {{DIR_3_PURPOSE}} -``` - - - ---- - -## Established Patterns - -### Naming Conventions -- {{NAMING_RULE_1}} -- {{NAMING_RULE_2}} - -### File Organization Rules -- {{FILE_ORG_RULE_1}} -- {{FILE_ORG_RULE_2}} - -### API Design Rules -- {{API_RULE_1}} -- {{API_RULE_2}} - - - ---- - -## Layer Responsibilities - -| Layer | Responsibility | Must NOT Contain | -|-------|---------------|-----------------| -| {{LAYER_A}} | {{RESPONSIBILITY_A}} | {{FORBIDDEN_A}} | -| {{LAYER_B}} | {{RESPONSIBILITY_B}} | {{FORBIDDEN_B}} | - - - ---- - -## External Integrations - -| System | Purpose | Auth Method | -|--------|---------|-------------| -| {{EXT_SYSTEM_1}} | {{PURPOSE_1}} | {{AUTH_1}} | - - - ---- - -## Architectural Rules (Non-Negotiable) - -- {{ARCH_RULE_1}} -- {{ARCH_RULE_2}} - - - ---- - - diff --git a/knowledge-base/templates/03-risk-model.md b/knowledge-base/templates/03-risk-model.md new file mode 100644 index 0000000..11ca5a5 --- /dev/null +++ b/knowledge-base/templates/03-risk-model.md @@ -0,0 +1,38 @@ + + +# Risk Model: {{PROJECT_NAME}} + +## Risk Classification + +| Area / Module | Risk Level | Reason | Required Review Gate | +|---------------|------------|--------|----------------------| +| {{MODULE_1}} | High | {{REASON_1}} | {{GATE_1}} | +| {{MODULE_2}} | Medium | {{REASON_2}} | {{GATE_2}} | +| {{MODULE_3}} | Low | {{REASON_3}} | Standard PR review | + +## High-Risk Change Triggers +- {{TRIGGER_1}} +- {{TRIGGER_2}} +- {{TRIGGER_3}} + +## Required Actions By Risk Level + +| Risk Level | Required Actions | +|------------|------------------| +| High | {{HIGH_ACTIONS}} | +| Medium | {{MEDIUM_ACTIONS}} | +| Low | Standard PR review | + +## Known Fragile Areas + +| Area | Known Issue Pattern | Mitigation | +|------|---------------------|------------| +| {{AREA_1}} | {{PATTERN_1}} | {{MITIGATION_1}} | + +## Sensitive Data Rules +- {{DATA_RULE_1}} +- {{DATA_RULE_2}} diff --git a/knowledge-base/templates/03-risk-model/00-index.md b/knowledge-base/templates/03-risk-model/00-index.md deleted file mode 100644 index 2cc3f78..0000000 --- a/knowledge-base/templates/03-risk-model/00-index.md +++ /dev/null @@ -1,105 +0,0 @@ - - -# Risk Model: {{PROJECT_NAME}} - ---- - -## Risk Classification - -| Area / Module | Risk Level | Reason | Required Review Gate | -|---------------|-----------|--------|---------------------| -| {{MODULE_1}} | High | {{REASON_1}} | {{GATE_1}} | -| {{MODULE_2}} | Medium | {{REASON_2}} | {{GATE_2}} | -| {{MODULE_3}} | Low | {{REASON_3}} | None | - - - ---- - -## What Makes a Change High-Risk - -A change is classified as **High Risk** if it meets any of the following conditions: - -- {{HIGH_RISK_CONDITION_1}} -- {{HIGH_RISK_CONDITION_2}} -- {{HIGH_RISK_CONDITION_3}} - - - ---- - -## Required Actions by Risk Level - -| Risk Level | Required Actions | -|-----------|-----------------| -| High | {{HIGH_REQUIRED_ACTIONS}} | -| Medium | {{MEDIUM_REQUIRED_ACTIONS}} | -| Low | Standard PR review | - - - ---- - -## Known Fragile Areas - -Areas with a history of regressions or incidents that require extra care: - -| Area | Known Issue Pattern | Mitigation | -|------|--------------------|-----------| -| {{FRAGILE_AREA_1}} | {{ISSUE_PATTERN_1}} | {{MITIGATION_1}} | - - - ---- - -## Sensitive Data Handling Rules - -- {{SENSITIVE_DATA_RULE_1}} -- {{SENSITIVE_DATA_RULE_2}} - - - ---- - - diff --git a/knowledge-base/templates/04-active-sprint.md b/knowledge-base/templates/04-active-sprint.md new file mode 100644 index 0000000..2143d7d --- /dev/null +++ b/knowledge-base/templates/04-active-sprint.md @@ -0,0 +1,32 @@ + + +# Active Sprint: {{PROJECT_NAME}} + +**Sprint:** {{SPRINT_NAME_OR_NUMBER}} +**Sprint Goal:** {{SPRINT_GOAL}} +**Period:** {{SPRINT_START_DATE}} → {{SPRINT_END_DATE}} + +## Active Issues + +| Issue | Title | Assignee | Status | Notes | +|-------|-------|----------|--------|-------| +| #{{ISSUE_NUMBER_1}} | {{ISSUE_TITLE_1}} | {{ASSIGNEE_1}} | {{STATUS_1}} | {{PROGRESS_NOTE_1}} | +| #{{ISSUE_NUMBER_2}} | {{ISSUE_TITLE_2}} | {{ASSIGNEE_2}} | {{STATUS_2}} | {{PROGRESS_NOTE_2}} | + +## Blocked Items + +| Issue | Blocker | Owner | +|-------|---------|-------| +| #{{BLOCKED_ISSUE}} | {{BLOCKER_DESCRIPTION}} | {{BLOCKER_OWNER}} | + +## Completed This Sprint + +| Issue | Title | Completed On | +|-------|-------|--------------| +| #{{DONE_ISSUE_1}} | {{DONE_TITLE_1}} | {{DONE_DATE_1}} | + + diff --git a/knowledge-base/templates/04-active-sprint/00-index.md b/knowledge-base/templates/04-active-sprint/00-index.md deleted file mode 100644 index 42271df..0000000 --- a/knowledge-base/templates/04-active-sprint/00-index.md +++ /dev/null @@ -1,84 +0,0 @@ - - -# Active Sprint: {{PROJECT_NAME}} - -**Sprint:** {{SPRINT_NAME_OR_NUMBER}} -**Sprint Goal:** {{SPRINT_GOAL}} -**Period:** {{SPRINT_START_DATE}} → {{SPRINT_END_DATE}} - ---- - -## Active Issues - -| Issue | Title | Assignee | Status | Notes | -|-------|-------|----------|--------|-------| -| #{{ISSUE_NUMBER_1}} | {{ISSUE_TITLE_1}} | {{ASSIGNEE_1}} | {{STATUS_1}} | {{PROGRESS_NOTE_1}} | -| #{{ISSUE_NUMBER_2}} | {{ISSUE_TITLE_2}} | {{ASSIGNEE_2}} | {{STATUS_2}} | {{PROGRESS_NOTE_2}} | - - - ---- - -## Blocked Items - -| Issue | Blocker | Owner | -|-------|---------|-------| -| #{{BLOCKED_ISSUE}} | {{BLOCKER_DESCRIPTION}} | {{BLOCKER_OWNER}} | - - - ---- - -## Completed This Sprint - -| Issue | Title | Completed On | -|-------|-------|-------------| -| #{{DONE_ISSUE_1}} | {{DONE_TITLE_1}} | {{DONE_DATE_1}} | - - - ---- - - diff --git a/knowledge-base/templates/CLAUDE.section.md b/knowledge-base/templates/CLAUDE.section.md index d6ed4e3..31a0cdb 100644 --- a/knowledge-base/templates/CLAUDE.section.md +++ b/knowledge-base/templates/CLAUDE.section.md @@ -7,7 +7,7 @@ This project stores structured context in `knowledge-base/`. - If `knowledge-base/.kb-config.yml` exists, use it as the source of truth for enabled modules and loading defaults. - Load only the files needed for the current task. - Treat KB files as read-only unless you are the designated KB maintenance flow. -- If the numbered KB does not exist, you may fall back to the flat-file layout if present. +- If the numbered flat KB does not exist, you may fall back to the older numbered tree layout or the legacy flat layout if present. ### Graceful Degradation If no knowledge base exists, proceed normally without KB-aware behavior. diff --git a/knowledge-base/templates/README.md b/knowledge-base/templates/README.md index f08d48a..bb5b7c8 100644 --- a/knowledge-base/templates/README.md +++ b/knowledge-base/templates/README.md @@ -4,10 +4,10 @@ These templates are copied into downstream projects. ## Core templates - `00-master.md` -- `01-business-flows/00-index.md` -- `02-architecture/00-index.md` -- `03-risk-model/00-index.md` -- `04-active-sprint/00-index.md` +- `01-business-flows.md` +- `02-architecture.md` +- `03-risk-model.md` +- `04-active-sprint.md` - `.kb-config.yml` - `CLAUDE.section.md` @@ -20,7 +20,7 @@ These templates are copied into downstream projects. - `advanced/known-constraints.md` ## Authoring rules -- Keep the section index files concise and task-oriented. -- Put section detail into child files inside the matching numbered directory. +- Keep Tier 1 section files concise but directly useful. +- Do not force child-file creation for routine KB updates. - Treat Tier 2 as opt-in and mostly append-only. - Keep KB content plain Markdown plus lightweight config. From 67eb629a62911005a3635fcf0076c948fe59a44e Mon Sep 17 00:00:00 2001 From: Anurag Kumawat Date: Sat, 7 Mar 2026 15:38:45 +0530 Subject: [PATCH 13/16] updated prompt --- knowledge-base/prompts/install-hybrid-kb.md | 53 +++++++++++++-------- 1 file changed, 32 insertions(+), 21 deletions(-) diff --git a/knowledge-base/prompts/install-hybrid-kb.md b/knowledge-base/prompts/install-hybrid-kb.md index 72de5df..ecf61b9 100644 --- a/knowledge-base/prompts/install-hybrid-kb.md +++ b/knowledge-base/prompts/install-hybrid-kb.md @@ -10,6 +10,7 @@ Source directory to read from: - `knowledge-base/templates/advanced/` - `knowledge-base/templates/.kb-config.yml` - `knowledge-base/templates/CLAUDE.section.md` +- `knowledge-base/scripts/scaffold_hybrid_kb.py` - `knowledge-base/scripts/validate_hybrid_kb.py` - `claude/agents/knowledge-base-manager/knowledge-base-manager.md` - `claude/agents/knowledge-base-manager/README.md` @@ -25,16 +26,7 @@ Follow these steps exactly: - If it exists, do not overwrite files silently. - Show me which files already exist, which are missing, and whether this looks like a partial install. - Ask how to proceed before making changes. -3. Create `knowledge-base/` using the numbered flat hybrid contract: - - `00-master.md` - - `01-business-flows.md` - - `02-architecture.md` - - `03-risk-model.md` - - `04-active-sprint.md` - - `.kb-config.yml` - - create `advanced/` only if Tier 2 files are selected - - create `scripts/` for helper scripts -4. Evaluate whether Tier 2 is needed for this project. +3. Evaluate whether Tier 2 is needed for this project before installing anything. - Use evidence only from the codebase and project docs. - Consider Tier 2 justified only when the project shows real complexity such as: - recurring incidents or fragile areas @@ -43,7 +35,7 @@ Follow these steps exactly: - hard technical or business constraints - meaningful shipped feature history that would help onboarding - If Tier 2 does NOT appear justified, recommend Tier 1 only. -5. If Tier 2 may be useful, present a recommendation table before creating any Tier 2 files. +4. If Tier 2 may be useful, present a recommendation table before creating any Tier 2 files. For each optional file below, mark one of: `Recommend`, `Optional`, `Do Not Recommend`, and give a one-line reason. - `advanced/decision-log.md` - `advanced/incident-log.md` @@ -51,31 +43,50 @@ Follow these steps exactly: - `advanced/integration-map.md` - `advanced/metrics.md` - `advanced/known-constraints.md` -6. Ask me whether I want Tier 2 for this project. +5. Ask me whether I want Tier 2 for this project. - If I say no: continue with Tier 1 only. - If I say yes: ask me to confirm exactly which Tier 2 files to include, using your recommendations as the default suggestion. - - Do not create any Tier 2 files until I confirm the selection. -7. Copy the reusable helper scripts into `knowledge-base/scripts/`. -8. Check whether `.claude/agents/knowledge-base-manager.md` already exists. + - Do not install any Tier 2 files until I confirm the selection. +6. Install the starter kit by running the reusable scaffold script from the source repo instead of manually recreating the template files. + - Prefer running `knowledge-base/scripts/scaffold_hybrid_kb.py` from the source repo against this project root. + - Use `--enable` only for the Tier 2 modules I confirmed. + - Only fall back to manual file copying if the scaffold script cannot be run. + - The install must create the numbered flat hybrid contract: + - `00-master.md` + - `01-business-flows.md` + - `02-architecture.md` + - `03-risk-model.md` + - `04-active-sprint.md` + - `.kb-config.yml` + - `advanced/` only when Tier 2 modules are selected + - `scripts/` for helper scripts +7. After scaffolding, replace placeholders only when you can infer values confidently from the codebase. + - Do not rewrite the entire KB templates. + - Fill only the fields you can justify from project evidence. + - Keep the rest of the starter-kit structure intact. +8. If a value cannot be inferred confidently, leave the placeholder unchanged and list it in your summary. Do not guess. +9. Check whether `.claude/agents/knowledge-base-manager.md` already exists. - If it does not exist: - create `.claude/agents/` if needed - copy `claude/agents/knowledge-base-manager/knowledge-base-manager.md` into `.claude/agents/knowledge-base-manager.md` - If it already exists: do not overwrite it silently. Mention that it already exists in your summary. -9. Replace placeholders only when you can infer values confidently from the codebase. -10. If a value cannot be inferred confidently, leave the placeholder unchanged and list it in your summary. Do not guess. -11. Add the `Knowledge Base` section from `CLAUDE.section.md` to the project root `CLAUDE.md` if it is not already present. -12. Ensure the project root `CLAUDE.md` has a `Custom Agents` section that includes `knowledge-base-manager`. +10. Add the `Knowledge Base` section from `CLAUDE.section.md` to the project root `CLAUDE.md` if it is not already present. +11. Ensure the project root `CLAUDE.md` has a `Custom Agents` section that includes `knowledge-base-manager`. - If the section is missing, create it. - If the section exists but does not list `knowledge-base-manager`, add it. - Do not duplicate an existing entry. +12. Run the installed validator from this project's root: + - `python3 knowledge-base/scripts/validate_hybrid_kb.py .` + - If validation fails, show me the errors and stop. 13. At the end, show me: - files created + - whether the scaffold script was used or whether you had to fall back to manual copying - placeholders inferred - placeholders left unresolved - whether Tier 2 was recommended - which Tier 2 files were recommended vs not recommended - Tier 2 modules enabled - whether `knowledge-base-manager` agent was installed or already existed - - the exact validation command I should run from this project's root: - `python3 knowledge-base/scripts/validate_hybrid_kb.py .` + - the exact scaffold command that was run + - the exact validation command that was run ``` From 93a40f0d71a81ee8e0d44b9c36d969bbaa1f062c Mon Sep 17 00:00:00 2001 From: Anurag Kumawat Date: Mon, 9 Mar 2026 10:22:53 +0530 Subject: [PATCH 14/16] Review changes for the process --- README.md | 4 + claude/README.md | 2 + .../agents/knowledge-base-manager/README.md | 14 + knowledge-base/ADOPTION-GUIDE.md | 132 +++++ knowledge-base/GOVERNANCE.md | 3 + knowledge-base/KB-CONTRACT-V1-PILOT-SCOPE.md | 40 ++ knowledge-base/README.md | 21 +- knowledge-base/REVIEW-CHECKLIST.md | 4 + knowledge-base/SPEC.md | 48 ++ knowledge-base/project-files/KB-PROCESS.md | 57 +++ knowledge-base/project-files/README.md | 7 + knowledge-base/prompts/install-hybrid-kb.md | 34 +- knowledge-base/scripts/scaffold_hybrid_kb.py | 181 +++++-- knowledge-base/scripts/validate_hybrid_kb.py | 480 ++++++++++++++++-- knowledge-base/templates/.kb-config.yml | 23 +- knowledge-base/templates/00-master.md | 96 +++- knowledge-base/templates/01-business-flows.md | 77 ++- knowledge-base/templates/02-architecture.md | 81 ++- knowledge-base/templates/03-risk-model.md | 82 ++- knowledge-base/templates/04-active-sprint.md | 81 ++- knowledge-base/templates/CLAUDE.section.md | 8 + knowledge-base/templates/README.md | 10 + .../templates/advanced/decision-log.md | 48 +- .../templates/advanced/feature-history.md | 45 +- .../templates/advanced/incident-log.md | 45 +- .../templates/advanced/integration-map.md | 42 +- .../templates/advanced/known-constraints.md | 38 +- knowledge-base/templates/advanced/metrics.md | 40 +- 28 files changed, 1543 insertions(+), 200 deletions(-) create mode 100644 knowledge-base/ADOPTION-GUIDE.md create mode 100644 knowledge-base/KB-CONTRACT-V1-PILOT-SCOPE.md create mode 100644 knowledge-base/project-files/KB-PROCESS.md create mode 100644 knowledge-base/project-files/README.md mode change 100755 => 100644 knowledge-base/scripts/scaffold_hybrid_kb.py mode change 100755 => 100644 knowledge-base/scripts/validate_hybrid_kb.py diff --git a/README.md b/README.md index 44f6682..2fd17af 100644 --- a/README.md +++ b/README.md @@ -27,3 +27,7 @@ The current KB model is a hybrid starter kit: - 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) diff --git a/claude/README.md b/claude/README.md index 6192766..dba6f6c 100644 --- a/claude/README.md +++ b/claude/README.md @@ -17,6 +17,8 @@ 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. diff --git a/claude/agents/knowledge-base-manager/README.md b/claude/agents/knowledge-base-manager/README.md index 4349a9c..17314d8 100644 --- a/claude/agents/knowledge-base-manager/README.md +++ b/claude/agents/knowledge-base-manager/README.md @@ -26,6 +26,12 @@ cp knowledge-base-manager.md /.claude/agents/knowledge-base-manage No placeholders to replace — this agent has no `{{PLACEHOLDER}}` values. It works with any project's knowledge base structure out of the box. +If you are using the KB scaffold script from `engineering-recipes`, prefer: + +```bash +python3 knowledge-base/scripts/scaffold_hybrid_kb.py /path/to/target-project --install-kb-manager +``` + ### 2. Register in your project's CLAUDE.md The bootstrap installation prompt adds this automatically. If registering manually, add to your project's `CLAUDE.md`: @@ -40,6 +46,14 @@ The bootstrap installation prompt adds this automatically. If registering manual If the project uses the hybrid KB contract, `knowledge-base/.kb-config.yml` is the runtime source of truth and the manager should prefer the numbered-flat layout over the older layouts. +## Recommended Workflow Assets + +For downstream teams, pair this agent with: +- `knowledge-base/project-files/pull_request_template.md` +- `knowledge-base/project-files/KB-PROCESS.md` + +Those assets make the "KB impact" decision part of the delivery workflow instead of a manual reminder. + ## Usage Once set up, trigger the agent with natural language: diff --git a/knowledge-base/ADOPTION-GUIDE.md b/knowledge-base/ADOPTION-GUIDE.md new file mode 100644 index 0000000..bf4feb7 --- /dev/null +++ b/knowledge-base/ADOPTION-GUIDE.md @@ -0,0 +1,132 @@ +# Hybrid KB Adoption Guide + +Use this guide when rolling the hybrid KB into a downstream project. It assumes the v1 contract in [SPEC.md](SPEC.md) and the pilot boundaries in [KB-CONTRACT-V1-PILOT-SCOPE.md](KB-CONTRACT-V1-PILOT-SCOPE.md). + +## Operating Model + +- `engineering-recipes` owns the contract, templates, scaffold tooling, validator, and agent definitions. +- Each project owns its local `knowledge-base/` directory and the truth inside it. +- Tier 1 is the small, required baseline. +- Tier 2 is optional and should be enabled only when the project needs it. +- Consumer agents read KB first and remain read-only. +- `knowledge-base-manager` is the only automated KB writer. + +## Source Repo Deliverables + +This repo now provides: +- the versioned KB contract +- metadata-enabled KB templates +- a validator that checks structure, front matter, headings, freshness, and owner links +- a scaffold script that can install the KB, KB manager, and optional workflow assets +- reusable downstream workflow files for KB-aware PR review and delivery rules + +## Project Install Checklist + +1. Scaffold the KB into the target project. +2. Complete `knowledge-base/.kb-config.yml`. +3. Assign named owners for business flows, architecture, risk model, active sprint, and overall KB process. +4. Add the KB guidance section to the project root `CLAUDE.md`. +5. Install `knowledge-base-manager` if the project uses Claude agents. +6. Run `python3 knowledge-base/scripts/validate_hybrid_kb.py .` from the project root. + +## Canonical Baseline + +Populate Tier 1 in this order: +1. `00-master.md`: project summary, objectives, stage, file map, role-based reading paths, and known KB gaps +2. `01-business-flows.md`: core workflows, business rules, edge cases, and glossary terms +3. `02-architecture.md`: major modules, integration boundaries, data flow, and non-negotiable rules +4. `03-risk-model.md`: critical flows, fragile modules, release risks, and review/test expectations +5. `04-active-sprint.md`: current sprint state seeded from the issue tracker + +Enable Tier 2 only when it is justified: +- `decision-log.md` +- `incident-log.md` +- `feature-history.md` +- `integration-map.md` +- `metrics.md` +- `known-constraints.md` + +## Update Trigger Matrix + +| Trigger | Update target | +|---|---| +| business behavior changes | `01-business-flows.md` | +| architecture or boundary changes | `02-architecture.md` | +| regression or release risk discovery | `03-risk-model.md` | +| issue state movement | `04-active-sprint.md` | +| significant trade-off or decision | `advanced/decision-log.md` | +| incident or root cause learning | `advanced/incident-log.md` | +| feature evolution worth preserving | `advanced/feature-history.md` | +| external integration detail change | `advanced/integration-map.md` | +| measurable operational learning | `advanced/metrics.md` | +| recurring limitation or debt | `advanced/known-constraints.md` | + +## Delivery Workflow Rules + +- Every task must make an explicit KB impact decision before it is considered done. +- KB impact belongs in the PR template, not in memory. +- Reviewers should check code and KB consistency together when KB impact is marked. +- The KB manager should keep `04-active-sprint.md` current, but other Tier 1 files should still be reviewed by human owners. + +## Ownership Model + +Recommended default owners: +- business flows: PM or BA +- architecture: tech lead +- risk model: QA lead with tech lead support +- active sprint: engineering lead or KB manager workflow owner +- Tier 2 logs: domain-specific owners +- overall KB process: project lead or engineering manager + +Front matter `owners` fields should reference keys from `.kb-config.yml` so validation can confirm the links. + +## AI Usage Contract + +- Read `knowledge-base/00-master.md` first. +- If `.kb-config.yml` exists, use it as the runtime source of truth. +- Load only the files needed for the task. +- If KB content is missing or obviously incomplete, do not fabricate facts. +- Consumer agents remain read-only. +- Only `knowledge-base-manager` may automate KB writes. +- Keep Tier 1 concise enough for routine reads. + +## Maintenance Cadence + +- Daily: sync sprint state and check open KB-impact work +- Weekly: review KB gaps during sprint review or planning +- Monthly: review Tier 1 freshness and ownership validity +- Quarterly: review contract adoption, Tier 2 usage, and token cost + +## 30-Day Rollout Backlog + +### Week 1 +- freeze pilot scope +- finalize starter kit +- add metadata front matter and section schema +- strengthen the validator +- package KB manager installation + +### Week 2 +- install KB in pilot project 1 +- complete `.kb-config.yml` +- assign owners +- update root `CLAUDE.md` +- populate the Tier 1 baseline + +### Week 3 +- install KB-aware PR template +- add KB issue labels +- publish/update the project KB process doc +- run the first real update flows and remove friction + +### Week 4 +- install KB in pilot project 2 +- compare pilot learnings +- finalize org SOP +- prepare demo/training material + +## Related Assets + +- [project-files/pull_request_template.md](project-files/pull_request_template.md) +- [project-files/KB-PROCESS.md](project-files/KB-PROCESS.md) +- [prompts/install-hybrid-kb.md](prompts/install-hybrid-kb.md) diff --git a/knowledge-base/GOVERNANCE.md b/knowledge-base/GOVERNANCE.md index beb51ca..ae171ad 100644 --- a/knowledge-base/GOVERNANCE.md +++ b/knowledge-base/GOVERNANCE.md @@ -5,6 +5,7 @@ - Contract owner: maintainers of `engineering-recipes` - Project KB owner: the downstream project team - Default automation owner: `knowledge-base-manager` flow or equivalent project-maintained automation +- Pilot scope reference: [KB-CONTRACT-V1-PILOT-SCOPE.md](KB-CONTRACT-V1-PILOT-SCOPE.md) ## Change Classes @@ -40,6 +41,7 @@ The following changes require maintainer review in `engineering-recipes`: - changes to `.kb-config.yml` schema - changes to sprint sync behavior - addition of new Tier 2 module types +- changes that make the validator reject previously valid v1 installs ## Upgrade Rules For Downstream Projects @@ -56,3 +58,4 @@ The following changes require maintainer review in `engineering-recipes`: - Does the change keep Tier 1 concise? - Is ownership still clear after the change? - Is migration guidance included if needed? +- Does the change preserve the v1 pilot freeze on required files, entrypoint, and minimum config keys? diff --git a/knowledge-base/KB-CONTRACT-V1-PILOT-SCOPE.md b/knowledge-base/KB-CONTRACT-V1-PILOT-SCOPE.md new file mode 100644 index 0000000..03ebd75 --- /dev/null +++ b/knowledge-base/KB-CONTRACT-V1-PILOT-SCOPE.md @@ -0,0 +1,40 @@ +# KB Contract V1 Pilot Scope + +## Frozen In The Pilot + +These items are locked for the v1 pilot: +- required Tier 1 files remain `00-master.md`, `01-business-flows.md`, `02-architecture.md`, `03-risk-model.md`, `04-active-sprint.md` +- the entry-point rule remains `knowledge-base/00-master.md` +- `.kb-config.yml` minimum required keys remain `version`, `project.name`, `enabled_tier2`, and `loading_defaults` +- the canonical new-install layout remains numbered-flat + +## Adjustable During The Pilot + +These changes are safe within v1: +- better templates and examples +- stronger validators and scaffold helpers +- clearer ownership and freshness guidance +- downstream install docs and workflow assets +- optional Tier 2 additions that stay backward-compatible + +## Explicitly Out Of Scope During The Pilot + +Do not make these changes during the pilot without a new major contract version: +- renaming required Tier 1 files +- changing the required Tier 1 set +- changing the entry-point rule +- changing the required `.kb-config.yml` keys + +## Approval Model + +- Contract owner: maintainers of `engineering-recipes` +- Required approvers for contract-level changes: repository maintainers +- Breaking changes require: maintainer review, migration guidance, and a new major contract version + +## Pilot Goal + +Make the KB repeatable in real project repos without redesigning the contract: +- every project starts from the same foundation +- ownership and review are explicit +- KB impact is checked as part of normal delivery +- AI agents read KB first and stay read-only unless they are the KB manager diff --git a/knowledge-base/README.md b/knowledge-base/README.md index 4863c8c..d08ff36 100644 --- a/knowledge-base/README.md +++ b/knowledge-base/README.md @@ -7,8 +7,11 @@ This directory contains the V1 hybrid knowledge-base starter kit for project-loc - A versioned KB contract: [SPEC.md](SPEC.md) - A reconciliation note across older layouts: [SPEC-RECONCILIATION.md](SPEC-RECONCILIATION.md) - Governance rules: [GOVERNANCE.md](GOVERNANCE.md) +- Pilot scope note: [KB-CONTRACT-V1-PILOT-SCOPE.md](KB-CONTRACT-V1-PILOT-SCOPE.md) +- Adoption guide: [ADOPTION-GUIDE.md](ADOPTION-GUIDE.md) - Review checklist: [REVIEW-CHECKLIST.md](REVIEW-CHECKLIST.md) - Tier 1 and Tier 2 templates under [`templates/`](templates/) +- Downstream workflow assets under [`project-files/`](project-files/) - A scaffold script for installing the KB into another project - A validation script for checking a KB installation - A copy-paste install prompt for agent-based setup @@ -64,7 +67,10 @@ knowledge-base/ ```bash python3 knowledge-base/scripts/scaffold_hybrid_kb.py /path/to/target-project \ - --enable decision-log,incident-log + --enable decision-log,incident-log \ + --install-kb-manager \ + --install-pr-template \ + --install-kb-process ``` After setup, move into the target project root and validate the KB: @@ -98,9 +104,14 @@ The validator checks: - required Tier 1 files exist - `.kb-config.yml` has the minimum contract keys - `00-master.md` references the numbered-flat Tier 1 files +- canonical Tier 1 files contain front matter and the required shared headings +- front matter freshness and owner links can be evaluated +- append-only logs use a recognizable entry format - enabled Tier 2 modules in config have matching files - older numbered-tree and legacy-flat projects still validate as compatibility installs +Warnings are used for freshness, owner-link, and duplication hygiene issues so a fresh scaffold can pass before the project is fully populated. + ## Why The Numbered-Flat Layout - `00-master.md` stays small and cheap to read. @@ -128,3 +139,11 @@ Older projects may still use one of these layouts: Those layouts remain readable and valid as temporary compatibility paths for existing projects. New projects should use the numbered-flat contract. + +## Recommended Downstream Workflow Assets + +For downstream project repos, the starter kit also ships reusable workflow files: +- [project-files/pull_request_template.md](project-files/pull_request_template.md) +- [project-files/KB-PROCESS.md](project-files/KB-PROCESS.md) + +These are not part of the strict KB file contract, but they make KB updates part of normal delivery. diff --git a/knowledge-base/REVIEW-CHECKLIST.md b/knowledge-base/REVIEW-CHECKLIST.md index d2e032a..dbd467c 100644 --- a/knowledge-base/REVIEW-CHECKLIST.md +++ b/knowledge-base/REVIEW-CHECKLIST.md @@ -5,7 +5,11 @@ Use this checklist for KB template, script, or spec changes. - Does this change belong in Tier 1 or Tier 2? - If Tier 1, is it truly required for every project? - Does it increase the default read set or token cost? +- Does it preserve the frozen v1 pilot contract? - Is the file still concise and scannable? +- Do canonical templates include the shared section headings? +- Do KB content templates include the expected front matter fields? +- If owners or freshness rules changed, is `.kb-config.yml` still sufficient to validate them? - Is ownership clear: human, automation, or mixed with explicit review? - Does the change preserve tool-agnostic plain Markdown content? - If config changed, was `.kb-config.yml` compatibility considered? diff --git a/knowledge-base/SPEC.md b/knowledge-base/SPEC.md index 8180a0c..ab0a2eb 100644 --- a/knowledge-base/SPEC.md +++ b/knowledge-base/SPEC.md @@ -9,6 +9,8 @@ Provide a project-local, token-efficient knowledge base that is easy to scaffold, easy to maintain, and reusable across projects of different stacks and domains. +This contract is frozen for the v1 pilot as described in [KB-CONTRACT-V1-PILOT-SCOPE.md](KB-CONTRACT-V1-PILOT-SCOPE.md). + ## Design Principles 1. Project-local storage: each project owns its own `knowledge-base/` directory. @@ -107,6 +109,44 @@ Minimum supported keys: - `enabled_tier2` - `loading_defaults` +Recommended extension keys: +- `source_of_truth` +- `project.summary` +- `project.domain` +- `project.repo_type` +- `owners` +- `review` +- `agent_policy` + +## Metadata Contract For Markdown KB Files + +Canonical numbered-flat KB files should include YAML front matter with these fields: +- `id` +- `title` +- `owners` +- `audiences` +- `last_reviewed` +- `review_cycle_days` +- `confidence` +- `change_frequency` +- `source_refs` +- `tags` + +Front matter `owners` should reference keys or named values defined in `.kb-config.yml` when the project provides an `owners` block. + +## Tier 1 Section Schema + +Each canonical Tier 1 file should use the same top-level section pattern: +1. `Purpose` +2. `Scope` +3. `What is true today` +4. `Key rules` +5. `Known gaps / uncertainty` +6. `Linked evidence` +7. `Next review trigger` + +The section content can be file-specific, but the top-level headings should remain consistent so agents and validators can reason about the files deterministically. + ## Compatibility Rules ### Numbered-tree support @@ -135,6 +175,14 @@ Recommended default: - use append-only updates for Tier 2 logs where possible - run the KB validator after setup or structural changes +## Operational Workflow Expectations + +- every task should make an explicit KB impact decision +- KB-aware PR review should check code and KB alignment together +- `04-active-sprint.md` is the default automation target +- business, architecture, risk, and sprint each need named owners in the downstream project +- missing KB context must not be fabricated by agents + ## Rollout Order 1. Sneha pilot diff --git a/knowledge-base/project-files/KB-PROCESS.md b/knowledge-base/project-files/KB-PROCESS.md new file mode 100644 index 0000000..f9b2120 --- /dev/null +++ b/knowledge-base/project-files/KB-PROCESS.md @@ -0,0 +1,57 @@ +# Knowledge Base Process + +Use this file in downstream projects as the working agreement for KB maintenance. + +## Definition Of Done + +- Every task requires a KB impact decision. +- If KB impact exists, the relevant KB file must be updated before merge. +- `knowledge-base-manager` keeps sprint state current, but human owners still approve truth for business, architecture, and risk files. + +## Update Trigger Matrix + +| Trigger | File | +|---|---| +| business behavior change | `knowledge-base/01-business-flows.md` | +| architecture or module boundary change | `knowledge-base/02-architecture.md` | +| risk or regression discovery | `knowledge-base/03-risk-model.md` | +| issue state change | `knowledge-base/04-active-sprint.md` | +| decision or trade-off | `knowledge-base/advanced/decision-log.md` | +| incident or root cause | `knowledge-base/advanced/incident-log.md` | +| feature evolution | `knowledge-base/advanced/feature-history.md` | +| external integration detail | `knowledge-base/advanced/integration-map.md` | +| measurable operational learning | `knowledge-base/advanced/metrics.md` | +| recurring limitation or debt | `knowledge-base/advanced/known-constraints.md` | + +## Recommended Issue Labels + +- `kb:update-required` +- `kb:business` +- `kb:architecture` +- `kb:risk` +- `kb:decision` +- `kb:incident` +- `kb:sprint` + +## Ownership Template + +| Area | Named owner | +|---|---| +| business flows | {{BUSINESS_OWNER}} | +| architecture | {{ARCHITECTURE_OWNER}} | +| risk model | {{RISK_OWNER}} | +| active sprint | {{SPRINT_OWNER}} | +| KB process | {{KB_PROCESS_OWNER}} | + +## Review Paths + +- architecture change: engineer drafts, tech lead reviews, validator runs, merge +- business flow change: PM or BA drafts, QA or tech cross-checks, validator runs, merge +- incident learning: responder drafts, QA or tech lead reviews, merge + +## Maintenance Cadence + +- daily: sprint sync and KB-impact triage +- weekly: review KB gaps in sprint review or planning +- monthly: review Tier 1 freshness and owners +- quarterly: review contract adoption and Tier 2 usage diff --git a/knowledge-base/project-files/README.md b/knowledge-base/project-files/README.md new file mode 100644 index 0000000..f8cddfd --- /dev/null +++ b/knowledge-base/project-files/README.md @@ -0,0 +1,7 @@ +# Project Workflow Files + +These files are optional downstream assets that make the KB part of normal delivery: + +- `KB-PROCESS.md`: trigger matrix, ownership, labels, and definition-of-done guidance + +They are not part of the strict KB file contract, but the scaffold script can install them into downstream repos. diff --git a/knowledge-base/prompts/install-hybrid-kb.md b/knowledge-base/prompts/install-hybrid-kb.md index ecf61b9..a8fec73 100644 --- a/knowledge-base/prompts/install-hybrid-kb.md +++ b/knowledge-base/prompts/install-hybrid-kb.md @@ -10,6 +10,8 @@ Source directory to read from: - `knowledge-base/templates/advanced/` - `knowledge-base/templates/.kb-config.yml` - `knowledge-base/templates/CLAUDE.section.md` +- `knowledge-base/project-files/pull_request_template.md` +- `knowledge-base/project-files/KB-PROCESS.md` - `knowledge-base/scripts/scaffold_hybrid_kb.py` - `knowledge-base/scripts/validate_hybrid_kb.py` - `claude/agents/knowledge-base-manager/knowledge-base-manager.md` @@ -50,6 +52,9 @@ Follow these steps exactly: 6. Install the starter kit by running the reusable scaffold script from the source repo instead of manually recreating the template files. - Prefer running `knowledge-base/scripts/scaffold_hybrid_kb.py` from the source repo against this project root. - Use `--enable` only for the Tier 2 modules I confirmed. + - Use `--install-kb-manager` if this project uses Claude agents. + - Use `--install-pr-template` if this project does not already have a PR template. + - Use `--install-kb-process` if this project does not already have a KB workflow doc. - Only fall back to manual file copying if the scaffold script cannot be run. - The install must create the numbered flat hybrid contract: - `00-master.md` @@ -60,25 +65,38 @@ Follow these steps exactly: - `.kb-config.yml` - `advanced/` only when Tier 2 modules are selected - `scripts/` for helper scripts -7. After scaffolding, replace placeholders only when you can infer values confidently from the codebase. +7. Complete the project-level ownership and policy fields in `knowledge-base/.kb-config.yml`. + - Fill at least the named owners for: + - `kb_process` + - `business_flows` + - `architecture` + - `risk_model` + - `active_sprint` + - Keep `agent_policy` aligned with the KB contract: + - consumers are read-only + - only `knowledge-base-manager` automates writes +8. After scaffolding, replace placeholders only when you can infer values confidently from the codebase. - Do not rewrite the entire KB templates. - Fill only the fields you can justify from project evidence. - Keep the rest of the starter-kit structure intact. -8. If a value cannot be inferred confidently, leave the placeholder unchanged and list it in your summary. Do not guess. -9. Check whether `.claude/agents/knowledge-base-manager.md` already exists. +9. If a value cannot be inferred confidently, leave the placeholder unchanged and list it in your summary. Do not guess. +10. Check whether `.claude/agents/knowledge-base-manager.md` already exists. - If it does not exist: - create `.claude/agents/` if needed - copy `claude/agents/knowledge-base-manager/knowledge-base-manager.md` into `.claude/agents/knowledge-base-manager.md` - If it already exists: do not overwrite it silently. Mention that it already exists in your summary. -10. Add the `Knowledge Base` section from `CLAUDE.section.md` to the project root `CLAUDE.md` if it is not already present. -11. Ensure the project root `CLAUDE.md` has a `Custom Agents` section that includes `knowledge-base-manager`. +11. Add the `Knowledge Base` section from `CLAUDE.section.md` to the project root `CLAUDE.md` if it is not already present. +12. Ensure the project root `CLAUDE.md` has a `Custom Agents` section that includes `knowledge-base-manager`. - If the section is missing, create it. - If the section exists but does not list `knowledge-base-manager`, add it. - Do not duplicate an existing entry. -12. Run the installed validator from this project's root: +13. If the project does not already have a KB-aware PR template, copy `knowledge-base/project-files/pull_request_template.md` to `.github/pull_request_template.md`. +14. If the project does not already have a KB workflow doc, copy `knowledge-base/project-files/KB-PROCESS.md` to `docs/kb-process.md`. +15. Run the installed validator from this project's root: - `python3 knowledge-base/scripts/validate_hybrid_kb.py .` - If validation fails, show me the errors and stop. -13. At the end, show me: + - If validation passes with warnings, summarize the warnings and which ones are expected placeholders vs real setup gaps. +16. At the end, show me: - files created - whether the scaffold script was used or whether you had to fall back to manual copying - placeholders inferred @@ -86,7 +104,9 @@ Follow these steps exactly: - whether Tier 2 was recommended - which Tier 2 files were recommended vs not recommended - Tier 2 modules enabled + - owners assigned in `.kb-config.yml` - whether `knowledge-base-manager` agent was installed or already existed + - whether the PR template and KB process doc were installed - the exact scaffold command that was run - the exact validation command that was run ``` diff --git a/knowledge-base/scripts/scaffold_hybrid_kb.py b/knowledge-base/scripts/scaffold_hybrid_kb.py old mode 100755 new mode 100644 index a992461..15cf66d --- a/knowledge-base/scripts/scaffold_hybrid_kb.py +++ b/knowledge-base/scripts/scaffold_hybrid_kb.py @@ -4,11 +4,14 @@ import argparse import shutil import sys +from datetime import date from pathlib import Path ROOT = Path(__file__).resolve().parents[2] TEMPLATES = ROOT / "knowledge-base" / "templates" SCRIPT_ROOT = ROOT / "knowledge-base" / "scripts" +PROJECT_FILES_ROOT = ROOT / "knowledge-base" / "project-files" +KB_MANAGER_AGENT = ROOT / "claude" / "agents" / "knowledge-base-manager" / "knowledge-base-manager.md" CORE_FILES = [ "00-master.md", "01-business-flows.md", @@ -25,10 +28,18 @@ "metrics": "advanced/metrics.md", "known-constraints": "advanced/known-constraints.md", } +OPTIONAL_PROJECT_FILES = { + "pr_template": (PROJECT_FILES_ROOT / "pull_request_template.md", Path(".github/pull_request_template.md")), + "kb_process": (PROJECT_FILES_ROOT / "KB-PROCESS.md", Path("docs/kb-process.md")), +} CLAUDE_SECTION = TEMPLATES / "CLAUDE.section.md" SUPPORT_SCRIPTS = [ "validate_hybrid_kb.py", ] +KB_MANAGER_DESCRIPTION = ( + "- `knowledge-base-manager`: When the user wants to sync the KB from issue or sprint activity, " + "or update KB sections with the designated write-enabled flow." +) def copy_file(src: Path, dest: Path, overwrite: bool) -> str: @@ -39,29 +50,91 @@ def copy_file(src: Path, dest: Path, overwrite: bool) -> str: return f"write {dest}" -def ensure_claude_section(project_root: Path) -> str: +def replace_tokens(path: Path, replacements: dict[str, str]) -> None: + text = path.read_text(encoding="utf-8") + updated = text + for old, new in replacements.items(): + updated = updated.replace(old, new) + if updated != text: + path.write_text(updated, encoding="utf-8") + + +def append_section(lines: list[str], heading: str, content: list[str]) -> list[str]: + if any(line.strip() == heading for line in lines): + return lines + if lines and lines[-1].strip(): + lines.append("") + return lines + content + + +def append_to_section(lines: list[str], heading: str, content: list[str]) -> list[str]: + start = None + for index, line in enumerate(lines): + if line.strip() == heading: + start = index + break + if start is None: + return append_section(lines, heading, [heading, ""] + content) + + end = len(lines) + for index in range(start + 1, len(lines)): + if lines[index].startswith("## "): + end = index + break + + insertion = content[:] + if end > start + 1 and lines[end - 1].strip(): + insertion = [""] + insertion + return lines[:end] + insertion + lines[end:] + + +def section_contains(lines: list[str], heading: str, needle: str) -> bool: + start = None + for index, line in enumerate(lines): + if line.strip() == heading: + start = index + break + if start is None: + return False + + end = len(lines) + for index in range(start + 1, len(lines)): + if lines[index].startswith("## "): + end = index + break + return needle in "\n".join(lines[start:end]) + + +def ensure_claude_guidance(project_root: Path, install_kb_manager: bool) -> list[str]: claude_path = project_root / "CLAUDE.md" - section = CLAUDE_SECTION.read_text() - if claude_path.exists(): - existing = claude_path.read_text() - if "## Knowledge Base" in existing: - return f"skip {claude_path}" - claude_path.write_text(existing.rstrip() + "\n\n" + section) - return f"append {claude_path}" - claude_path.write_text(section) - return f"create {claude_path}" + existing_lines = claude_path.read_text(encoding="utf-8").splitlines() if claude_path.exists() else [] + actions: list[str] = [] + + kb_section = CLAUDE_SECTION.read_text(encoding="utf-8").rstrip().splitlines() + updated_lines = append_section(existing_lines[:], "## Knowledge Base", kb_section) + if updated_lines != existing_lines: + actions.append(f"update {claude_path}") + else: + actions.append(f"skip {claude_path}") + + if install_kb_manager: + if not section_contains(updated_lines, "## Custom Agents", "`knowledge-base-manager`"): + updated_lines = append_to_section(updated_lines, "## Custom Agents", [KB_MANAGER_DESCRIPTION]) + actions[-1] = f"update {claude_path}" + + claude_path.write_text("\n".join(updated_lines).rstrip() + "\n", encoding="utf-8") + return actions def configure_kb_config(config_path: Path, enabled: list[str]) -> str: - lines = config_path.read_text().splitlines() - new_lines = [] - in_block = False - inserted = False + lines = config_path.read_text(encoding="utf-8").splitlines() + new_lines: list[str] = [] + in_enabled = False + in_incident = False for line in lines: stripped = line.strip() if stripped == "enabled_tier2:": - in_block = True - inserted = True + in_enabled = True new_lines.append("enabled_tier2:") if enabled: for module in enabled: @@ -69,16 +142,34 @@ def configure_kb_config(config_path: Path, enabled: list[str]) -> str: else: new_lines.append(" # Add optional module keys here when enabled for the project.") continue - if in_block: + if in_enabled: if stripped.startswith("-") or stripped.startswith("#"): continue if stripped and not line.startswith(" "): - in_block = False - if not in_block: + in_enabled = False + else: + continue + + if stripped == "incident_response:" and line.startswith(" "): + in_incident = True new_lines.append(line) - if not inserted: - raise ValueError(f"enabled_tier2 block not found in {config_path}") - config_path.write_text("\n".join(new_lines) + "\n") + new_lines.append(" - 03-risk-model.md") + if "incident-log" in enabled: + new_lines.append(" - advanced/incident-log.md") + else: + new_lines.append(" # Add advanced/incident-log.md when incident-log is enabled.") + continue + if in_incident: + if stripped.startswith("-") or stripped.startswith("#"): + continue + if stripped and not line.startswith(" "): + in_incident = False + else: + continue + + new_lines.append(line) + + config_path.write_text("\n".join(new_lines).rstrip() + "\n", encoding="utf-8") return f"configure {config_path}" @@ -90,7 +181,10 @@ def main() -> int: default="", help="Comma-separated Tier 2 modules to enable (decision-log,incident-log,feature-history,integration-map,metrics,known-constraints)", ) - parser.add_argument("--overwrite", action="store_true", help="Overwrite existing KB files") + parser.add_argument("--install-kb-manager", action="store_true", help="Install the write-enabled KB manager agent") + parser.add_argument("--install-pr-template", action="store_true", help="Install the KB-aware PR template") + parser.add_argument("--install-kb-process", action="store_true", help="Install the KB working-agreement doc") + parser.add_argument("--overwrite", action="store_true", help="Overwrite existing files") args = parser.parse_args() project_root = Path(args.project_root).resolve() @@ -99,7 +193,8 @@ def main() -> int: return 1 kb_root = project_root / "knowledge-base" - kb_root.mkdir(exist_ok=True) + (kb_root / "advanced").mkdir(parents=True, exist_ok=True) + (kb_root / "scripts").mkdir(parents=True, exist_ok=True) enabled = [item.strip() for item in args.enable.split(",") if item.strip()] unknown = [item for item in enabled if item not in ADVANCED_MAP] @@ -107,27 +202,49 @@ def main() -> int: print(f"error: unknown Tier 2 modules: {', '.join(unknown)}", file=sys.stderr) return 1 - actions = [] + token_replacements = { + "{{LAST_REVIEWED_DATE}}": date.today().isoformat(), + } + actions: list[str] = [] for rel in CORE_FILES: - actions.append(copy_file(TEMPLATES / rel, kb_root / rel, args.overwrite)) + destination = kb_root / rel + actions.append(copy_file(TEMPLATES / rel, destination, args.overwrite)) + if destination.suffix == ".md" and actions[-1].startswith("write "): + replace_tokens(destination, token_replacements) for module in enabled: rel = ADVANCED_MAP[module] - actions.append(copy_file(TEMPLATES / rel, kb_root / rel, args.overwrite)) + destination = kb_root / rel + actions.append(copy_file(TEMPLATES / rel, destination, args.overwrite)) + if actions[-1].startswith("write "): + replace_tokens(destination, token_replacements) for script_name in SUPPORT_SCRIPTS: actions.append(copy_file(SCRIPT_ROOT / script_name, kb_root / "scripts" / script_name, args.overwrite)) + if args.install_kb_manager: + actions.append( + copy_file(KB_MANAGER_AGENT, project_root / ".claude" / "agents" / "knowledge-base-manager.md", args.overwrite) + ) + + if args.install_pr_template: + src, dest = OPTIONAL_PROJECT_FILES["pr_template"] + actions.append(copy_file(src, project_root / dest, args.overwrite)) + + if args.install_kb_process: + src, dest = OPTIONAL_PROJECT_FILES["kb_process"] + actions.append(copy_file(src, project_root / dest, args.overwrite)) + actions.append(configure_kb_config(kb_root / ".kb-config.yml", enabled)) - actions.append(ensure_claude_section(project_root)) + actions.extend(ensure_claude_guidance(project_root, args.install_kb_manager)) print("Hybrid KB scaffold summary:") for action in actions: print(f"- {action}") - if enabled: - print(f"- enabled Tier 2: {', '.join(enabled)}") - else: - print("- enabled Tier 2: none") + print(f"- enabled Tier 2: {', '.join(enabled) if enabled else 'none'}") + print(f"- KB manager installed: {'yes' if args.install_kb_manager else 'no'}") + print(f"- PR template installed: {'yes' if args.install_pr_template else 'no'}") + print(f"- KB process doc installed: {'yes' if args.install_kb_process else 'no'}") print("- validate from the project root with: python3 knowledge-base/scripts/validate_hybrid_kb.py .") return 0 diff --git a/knowledge-base/scripts/validate_hybrid_kb.py b/knowledge-base/scripts/validate_hybrid_kb.py old mode 100755 new mode 100644 index 8fb30d3..7b4bc70 --- a/knowledge-base/scripts/validate_hybrid_kb.py +++ b/knowledge-base/scripts/validate_hybrid_kb.py @@ -2,6 +2,9 @@ from __future__ import annotations import argparse +import re +from collections import defaultdict +from datetime import date from pathlib import Path NUMBERED_FLAT_REQUIRED = [ @@ -28,6 +31,13 @@ "knowledge-base/risks.md", "knowledge-base/.kb-config.yml", ] +TIER1_CANONICAL_FILES = [ + "knowledge-base/00-master.md", + "knowledge-base/01-business-flows.md", + "knowledge-base/02-architecture.md", + "knowledge-base/03-risk-model.md", + "knowledge-base/04-active-sprint.md", +] OPTIONAL_BY_KEY = { "decision-log": "knowledge-base/advanced/decision-log.md", "incident-log": "knowledge-base/advanced/incident-log.md", @@ -36,43 +46,199 @@ "metrics": "knowledge-base/advanced/metrics.md", "known-constraints": "knowledge-base/advanced/known-constraints.md", } -NUMBERED_FLAT_ENTRY_REFS = [ - "01-business-flows.md", - "02-architecture.md", - "03-risk-model.md", - "04-active-sprint.md", -] -NUMBERED_TREE_ENTRY_REFS = [ - "01-business-flows/00-index.md", - "02-architecture/00-index.md", - "03-risk-model/00-index.md", - "04-active-sprint/00-index.md", +ENTRY_REFS_BY_LAYOUT = { + "numbered-flat": [ + "01-business-flows.md", + "02-architecture.md", + "03-risk-model.md", + "04-active-sprint.md", + ], + "numbered-tree": [ + "01-business-flows/00-index.md", + "02-architecture/00-index.md", + "03-risk-model/00-index.md", + "04-active-sprint/00-index.md", + ], + "legacy-flat": [ + "architecture.md", + "business-flows.md", + "active-sprint.md", + "risks.md", + ], +} +REQUIRED_TIER1_HEADINGS = [ + "Purpose", + "Scope", + "What is true today", + "Key rules", + "Known gaps / uncertainty", + "Linked evidence", + "Next review trigger", ] -LEGACY_FLAT_ENTRY_REFS = [ - "architecture.md", - "business-flows.md", - "active-sprint.md", - "risks.md", +FRONT_MATTER_FIELDS = [ + "id", + "title", + "owners", + "audiences", + "last_reviewed", + "review_cycle_days", + "confidence", + "change_frequency", + "source_refs", + "tags", ] +TIER1_MAX_LINES = { + "knowledge-base/00-master.md": 180, + "knowledge-base/01-business-flows.md": 240, + "knowledge-base/02-architecture.md": 240, + "knowledge-base/03-risk-model.md": 220, + "knowledge-base/04-active-sprint.md": 260, +} +APPEND_ONLY_LOGS = { + "knowledge-base/advanced/decision-log.md", + "knowledge-base/advanced/incident-log.md", + "knowledge-base/advanced/feature-history.md", +} +SECTION_HEADING_PATTERN = re.compile(r"^##\s+(.+?)\s*$", re.MULTILINE) +ENTRY_HEADING_PATTERN = re.compile(r"^###\s+(.+?)\s*$", re.MULTILINE) +ISO_DATE_PREFIX_PATTERN = re.compile(r"^(?P\d{4}-\d{2}-\d{2}):") -def read_enabled_tier2(config_path: Path) -> list[str]: - enabled = [] - in_block = False - for raw in config_path.read_text().splitlines(): +def strip_quotes(value: str) -> str: + value = value.strip() + if (value.startswith('"') and value.endswith('"')) or (value.startswith("'") and value.endswith("'")): + return value[1:-1] + return value + + +def read_text(path: Path) -> str: + return path.read_text(encoding="utf-8") + + +def parse_top_level_yaml(lines: list[str]) -> dict[str, object]: + parsed: dict[str, object] = {} + current_list_key: str | None = None + for raw in lines: stripped = raw.strip() - if stripped == "enabled_tier2:": - in_block = True + if not stripped or stripped.startswith("#"): + continue + if raw.startswith(" - ") and current_list_key: + value = strip_quotes(raw.strip()[2:].strip()) + existing = parsed.setdefault(current_list_key, []) + if isinstance(existing, list): + existing.append(value) + continue + if raw.startswith(" "): + current_list_key = None + continue + if ":" not in raw: + current_list_key = None + continue + key, value = raw.split(":", 1) + key = key.strip() + value = value.strip() + if value == "": + parsed[key] = [] + current_list_key = key + elif value == "[]": + parsed[key] = [] + current_list_key = None + elif value.startswith("[") and value.endswith("]"): + items = [strip_quotes(item.strip()) for item in value[1:-1].split(",") if item.strip()] + parsed[key] = items + current_list_key = None + else: + parsed[key] = strip_quotes(value) + current_list_key = None + return parsed + + +def split_front_matter(text: str) -> tuple[dict[str, object] | None, str]: + if not text.startswith("---\n"): + return None, text + end = text.find("\n---\n", 4) + if end == -1: + return None, text + front_matter_lines = text[4:end].splitlines() + body = text[end + 5 :] + return parse_top_level_yaml(front_matter_lines), body + + +def get_block_lines(lines: list[str], key: str) -> list[str]: + block: list[str] = [] + in_block = False + prefix = f"{key}:" + for raw in lines: + if not in_block: + if raw.startswith(prefix): + in_block = True continue - if in_block: - if stripped.startswith("-"): - enabled.append(stripped[1:].strip()) - continue - if stripped and not raw.startswith(" "): - break + if raw.strip() and not raw.startswith(" "): + break + block.append(raw) + return block + + +def read_enabled_tier2(config_path: Path) -> list[str]: + lines = read_text(config_path).splitlines() + enabled: list[str] = [] + for raw in get_block_lines(lines, "enabled_tier2"): + stripped = raw.strip() + if stripped.startswith("- "): + enabled.append(stripped[2:].strip()) return enabled +def read_loading_default_refs(config_path: Path) -> list[str]: + lines = read_text(config_path).splitlines() + refs: list[str] = [] + for raw in get_block_lines(lines, "loading_defaults"): + stripped = raw.strip() + if stripped.startswith("- "): + refs.append(stripped[2:].strip()) + return refs + + +def read_loading_default_groups(config_path: Path) -> set[str]: + lines = read_text(config_path).splitlines() + groups: set[str] = set() + for raw in get_block_lines(lines, "loading_defaults"): + stripped = raw.strip() + if stripped.endswith(":") and not stripped.startswith("- "): + groups.add(stripped[:-1]) + return groups + + +def read_owner_identifiers(config_path: Path) -> set[str]: + lines = read_text(config_path).splitlines() + identifiers: set[str] = set() + for raw in get_block_lines(lines, "owners"): + stripped = raw.strip() + if not stripped or stripped.startswith("#") or ":" not in stripped: + continue + key, value = stripped.split(":", 1) + identifiers.add(key.strip()) + scalar = strip_quotes(value.strip()) + if scalar: + identifiers.add(scalar) + return identifiers + + +def has_required_config_keys(config_path: Path, errors: list[str]) -> None: + text = read_text(config_path) + if not re.search(r"(?m)^version:\s*", text): + errors.append("missing config key: version") + if not re.search(r"(?m)^enabled_tier2:\s*", text): + errors.append("missing config key: enabled_tier2") + if not re.search(r"(?m)^loading_defaults:\s*", text): + errors.append("missing config key: loading_defaults") + + project_lines = get_block_lines(text.splitlines(), "project") + has_project_name = any(line.strip().startswith("name:") for line in project_lines) + if not has_project_name: + errors.append("missing config key: project.name") + + def detect_layout(root: Path) -> str | None: if (root / "knowledge-base/01-business-flows.md").exists(): return "numbered-flat" @@ -89,63 +255,281 @@ def validate_required(root: Path, required: list[str], errors: list[str]) -> Non errors.append(f"missing required file: {rel}") -def validate_config(root: Path, errors: list[str]) -> None: +def validate_entry(entry: Path, refs: list[str], errors: list[str]) -> None: + if not entry.exists(): + return + entry_text = read_text(entry) + for ref in refs: + if ref not in entry_text: + errors.append(f"entry file does not reference: {ref}") + + +def validate_front_matter( + path: Path, + owner_identifiers: set[str], + errors: list[str], + warnings: list[str], + strict_freshness: bool, +) -> dict[str, object] | None: + front_matter, body = split_front_matter(read_text(path)) + rel = path.as_posix().split("/knowledge-base/", 1)[-1] + rel = f"knowledge-base/{rel}" + + if front_matter is None: + errors.append(f"missing front matter: {rel}") + return None + + for field in FRONT_MATTER_FIELDS: + if field not in front_matter: + errors.append(f"missing front matter field in {rel}: {field}") + + owners = front_matter.get("owners", []) + if isinstance(owners, str): + owners = [owners] + if not isinstance(owners, list) or not owners: + errors.append(f"front matter owners must be a non-empty list in {rel}") + elif owner_identifiers: + for owner in owners: + if owner not in owner_identifiers: + warnings.append(f"owner reference not found in .kb-config.yml for {rel}: {owner}") + + audiences = front_matter.get("audiences", []) + if isinstance(audiences, str): + audiences = [audiences] + if not isinstance(audiences, list) or not audiences: + errors.append(f"front matter audiences must be a non-empty list in {rel}") + + last_reviewed = str(front_matter.get("last_reviewed", "")).strip() + cycle_raw = str(front_matter.get("review_cycle_days", "")).strip() + if "{{" in last_reviewed or not last_reviewed: + warnings.append(f"last_reviewed is still a placeholder or missing in {rel}") + else: + try: + reviewed_on = date.fromisoformat(last_reviewed) + review_cycle_days = int(cycle_raw) + age_days = (date.today() - reviewed_on).days + if age_days > review_cycle_days: + message = f"stale last_reviewed in {rel}: {last_reviewed} is {age_days} days old" + if strict_freshness: + errors.append(message) + else: + warnings.append(message) + except ValueError: + warnings.append(f"could not parse freshness metadata in {rel}") + + if body.strip() == "": + warnings.append(f"file body is empty after front matter: {rel}") + return front_matter + + +def validate_tier1_headings(path: Path, errors: list[str]) -> None: + _, body = split_front_matter(read_text(path)) + headings = SECTION_HEADING_PATTERN.findall(body) + normalized = [heading.strip().lower() for heading in headings] + last_index = -1 + for required in REQUIRED_TIER1_HEADINGS: + try: + current_index = normalized.index(required.lower()) + except ValueError: + rel = path.as_posix().split("/knowledge-base/", 1)[-1] + errors.append(f"missing required heading in knowledge-base/{rel}: {required}") + continue + if current_index < last_index: + rel = path.as_posix().split("/knowledge-base/", 1)[-1] + errors.append(f"required headings out of order in knowledge-base/{rel}: {required}") + return + last_index = current_index + + +def validate_tier1_size(path: Path, warnings: list[str]) -> None: + _, body = split_front_matter(read_text(path)) + non_empty_lines = [line for line in body.splitlines() if line.strip()] + rel = path.as_posix().split("/knowledge-base/", 1)[-1] + rel = f"knowledge-base/{rel}" + if len(non_empty_lines) < 12: + warnings.append(f"{rel} looks undersized; confirm it has enough project truth to be useful") + max_lines = TIER1_MAX_LINES.get(rel) + if max_lines and len(non_empty_lines) > max_lines: + warnings.append(f"{rel} exceeds the recommended Tier 1 size budget ({len(non_empty_lines)} > {max_lines})") + + +def collect_canonical_claims(path: Path) -> list[str]: + _, body = split_front_matter(read_text(path)) + claims: list[str] = [] + capture = False + for raw in body.splitlines(): + stripped = raw.strip() + if stripped.lower() == "## what is true today": + capture = True + continue + if capture and stripped.startswith("## "): + break + if not capture or not stripped.startswith("- "): + continue + if "{{" in stripped or stripped.lower().startswith("- example:"): + continue + normalized = " ".join(stripped[2:].split()) + if len(normalized) >= 30: + claims.append(normalized) + return claims + + +def validate_append_only_log(path: Path, errors: list[str], warnings: list[str]) -> None: + _, body = split_front_matter(read_text(path)) + rel = path.as_posix().split("/knowledge-base/", 1)[-1] + rel = f"knowledge-base/{rel}" + entry_titles = ENTRY_HEADING_PATTERN.findall(body) + if not entry_titles: + errors.append(f"append-only log has no entries or entry template headings: {rel}") + return + + parsed_dates: list[date] = [] + for title in entry_titles: + if title.startswith("{{DATE}}:"): + continue + match = ISO_DATE_PREFIX_PATTERN.match(title) + if not match: + warnings.append(f"append-only log entry heading should start with YYYY-MM-DD in {rel}: {title}") + continue + try: + parsed_dates.append(date.fromisoformat(match.group("date"))) + except ValueError: + warnings.append(f"append-only log entry has an invalid date in {rel}: {title}") + if parsed_dates != sorted(parsed_dates, reverse=True): + warnings.append(f"append-only log entries are not newest-first in {rel}") + + +def validate_config( + root: Path, + layout: str, + errors: list[str], + warnings: list[str], +) -> tuple[list[str], set[str]]: config_path = root / "knowledge-base/.kb-config.yml" if not config_path.exists(): - return - contents = config_path.read_text() - for key in ["version:", "source_of_truth:", "loading_defaults:"]: - if key not in contents: - errors.append(f"missing config key: {key.rstrip(':')}") - for module in read_enabled_tier2(config_path): + return [], set() + + has_required_config_keys(config_path, errors) + enabled = read_enabled_tier2(config_path) + owner_identifiers = read_owner_identifiers(config_path) + + if not owner_identifiers: + warnings.append("no owners block found in knowledge-base/.kb-config.yml; owner-link validation will be limited") + + for module in enabled: rel = OPTIONAL_BY_KEY.get(module) if rel is None: errors.append(f"unknown enabled Tier 2 module in config: {module}") elif not (root / rel).exists(): errors.append(f"enabled Tier 2 file missing: {rel}") + loading_groups = read_loading_default_groups(config_path) + for group in ["code_review", "planning", "sprint_work", "onboarding", "incident_response"]: + if group not in loading_groups: + warnings.append(f"missing recommended loading_defaults group: {group}") -def validate_entry(entry: Path, refs: list[str], errors: list[str]) -> None: - if not entry.exists(): - return - entry_text = entry.read_text() - for ref in refs: - if ref not in entry_text: - errors.append(f"entry file does not reference: {ref}") + if layout == "numbered-flat": + for ref in read_loading_default_refs(config_path): + target = root / "knowledge-base" / ref + if not target.exists(): + errors.append(f"loading_defaults references a missing file: knowledge-base/{ref}") + + for module, rel in OPTIONAL_BY_KEY.items(): + if (root / rel).exists() and module not in enabled: + warnings.append(f"optional KB file exists but is not enabled in config: {rel}") + + return enabled, owner_identifiers + + +def validate_canonical_layout( + root: Path, + owner_identifiers: set[str], + errors: list[str], + warnings: list[str], + strict_freshness: bool, +) -> None: + duplicate_claims: dict[str, set[str]] = defaultdict(set) + + for rel in TIER1_CANONICAL_FILES: + path = root / rel + validate_front_matter(path, owner_identifiers, errors, warnings, strict_freshness) + validate_tier1_headings(path, errors) + validate_tier1_size(path, warnings) + for claim in collect_canonical_claims(path): + duplicate_claims[claim].add(rel) + + for claim, files in duplicate_claims.items(): + if len(files) > 1: + joined_files = ", ".join(sorted(files)) + warnings.append(f"possible duplicate canonical claim across Tier 1 files ({joined_files}): {claim}") + + for rel in OPTIONAL_BY_KEY.values(): + path = root / rel + if not path.exists(): + continue + validate_front_matter(path, owner_identifiers, errors, warnings, strict_freshness) + if rel in APPEND_ONLY_LOGS: + validate_append_only_log(path, errors, warnings) def main() -> int: parser = argparse.ArgumentParser(description="Validate a hybrid KB installation") - parser.add_argument("project_root", help="Path to the target project root") + parser.add_argument("project_root", nargs="?", default=".", help="Path to the target project root") + parser.add_argument( + "--strict-freshness", + action="store_true", + help="Treat stale last_reviewed metadata as a validation error instead of a warning", + ) args = parser.parse_args() root = Path(args.project_root).resolve() errors: list[str] = [] + warnings: list[str] = [] layout = detect_layout(root) if layout == "numbered-flat": validate_required(root, NUMBERED_FLAT_REQUIRED, errors) - validate_entry(root / "knowledge-base/00-master.md", NUMBERED_FLAT_ENTRY_REFS, errors) + validate_entry(root / "knowledge-base/00-master.md", ENTRY_REFS_BY_LAYOUT[layout], errors) elif layout == "numbered-tree": validate_required(root, NUMBERED_TREE_REQUIRED, errors) - validate_entry(root / "knowledge-base/00-master.md", NUMBERED_TREE_ENTRY_REFS, errors) + validate_entry(root / "knowledge-base/00-master.md", ENTRY_REFS_BY_LAYOUT[layout], errors) + warnings.append("deep Tier 1 schema validation is skipped for numbered-tree compatibility installs") elif layout == "legacy-flat": validate_required(root, LEGACY_FLAT_REQUIRED, errors) - validate_entry(root / "knowledge-base/00-index.md", LEGACY_FLAT_ENTRY_REFS, errors) + validate_entry(root / "knowledge-base/00-index.md", ENTRY_REFS_BY_LAYOUT[layout], errors) + warnings.append("deep Tier 1 schema validation is skipped for legacy-flat compatibility installs") else: errors.append( "knowledge base entry file not found: expected knowledge-base/00-master.md or knowledge-base/00-index.md" ) - validate_config(root, errors) + enabled_tier2, owner_identifiers = validate_config(root, layout or "", errors, warnings) + + if layout == "numbered-flat" and not errors: + validate_canonical_layout( + root, + owner_identifiers, + errors, + warnings, + args.strict_freshness, + ) if errors: print("Hybrid KB validation failed:") for error in errors: print(f"- {error}") + if warnings: + print("\nWarnings:") + for warning in warnings: + print(f"- {warning}") return 1 - print(f"Hybrid KB validation passed ({layout} layout).") + if warnings: + print(f"Hybrid KB validation passed ({layout} layout) with {len(warnings)} warning(s):") + for warning in warnings: + print(f"- {warning}") + else: + print(f"Hybrid KB validation passed ({layout} layout).") return 0 diff --git a/knowledge-base/templates/.kb-config.yml b/knowledge-base/templates/.kb-config.yml index 89b071a..daa0df3 100644 --- a/knowledge-base/templates/.kb-config.yml +++ b/knowledge-base/templates/.kb-config.yml @@ -3,6 +3,8 @@ source_of_truth: kb-config project: name: "{{PROJECT_NAME}}" summary: "{{PROJECT_SUMMARY}}" + domain: "{{PROJECT_DOMAIN}}" + repo_type: "{{REPO_TYPE}}" enabled_tier2: # Add optional module keys here when enabled for the project. loading_defaults: @@ -23,7 +25,26 @@ loading_defaults: - 04-active-sprint.md incident_response: - 03-risk-model.md - - advanced/incident-log.md + # Add advanced/incident-log.md when incident-log is enabled. +owners: + kb_process: "knowledge-base-owner" + business_flows: "product-owner" + architecture: "tech-lead" + risk_model: "qa-lead" + active_sprint: "engineering-lead" + decision_log: "tech-lead" + incident_log: "qa-lead" + feature_history: "product-owner" + integration_map: "tech-lead" + metrics: "engineering-manager" + known_constraints: "tech-lead" +review: + tier1_days: 30 + tier2_days: 90 +agent_policy: + allow_auto_writes: true + kb_writer_agent: knowledge-base-manager + consumers_read_only: true compatibility: numbered_tree_entrypoint: knowledge-base/00-master.md numbered_tree_files: diff --git a/knowledge-base/templates/00-master.md b/knowledge-base/templates/00-master.md index a854886..f50bb46 100644 --- a/knowledge-base/templates/00-master.md +++ b/knowledge-base/templates/00-master.md @@ -1,20 +1,86 @@ - +--- +id: kb.master +title: Knowledge Base Master +owners: + - kb_process +audiences: + - engineering + - product + - qa +last_reviewed: "{{LAST_REVIEWED_DATE}}" +review_cycle_days: 30 +confidence: high +change_frequency: high +source_refs: [] +tags: + - tier1 + - routing +--- # Knowledge Base: {{PROJECT_NAME}} -**Last Updated:** {{LAST_UPDATED_DATE}} -**Tech Stack:** {{TECH_STACK}} +## Purpose -## Sections +Single entry point for the project knowledge base. Agents always read this file first, then load only the KB files needed for the task. -| Section | File | Summary | -|---------|------|---------| -| Business Flows | `01-business-flows.md` | Core user journeys, flows, and business rules for {{PROJECT_NAME}} | -| Architecture | `02-architecture.md` | Architectural patterns, boundaries, integrations, and implementation constraints | -| Risk Model | `03-risk-model.md` | Risk classification, fragile areas, and review/testing expectations | -| Active Sprint | `04-active-sprint.md` | Current sprint goal, active issues, blockers, and recent completions | -| Advanced Memory | `advanced/` | Optional logs and historical context loaded only when needed | +## Scope + +This file routes readers to the right KB sections, captures the current project snapshot, and records missing KB areas. It does not replace the detailed Tier 1 files. + +## What is true today + +### Project summary + +{{PROJECT_ONE_PARAGRAPH_SUMMARY}} + +### Current snapshot + +- Objectives: {{PROJECT_OBJECTIVES}} +- System stage: {{SYSTEM_STAGE}} +- Primary surfaces: {{PRIMARY_SURFACES}} +- Runtime source of truth: `knowledge-base/.kb-config.yml` + +### Role-based reading paths + +| Role / task | Read first | Then read | +|---|---|---| +| Planning | `00-master.md` | `01-business-flows.md`, `02-architecture.md`, `04-active-sprint.md` | +| Code review | `00-master.md` | `02-architecture.md`, `03-risk-model.md` | +| Onboarding | `00-master.md` | all Tier 1 files | +| Incident response | `00-master.md` | `03-risk-model.md`, `advanced/incident-log.md` when enabled | + +### KB file map + +| File | When to read it | Owner key | +|---|---|---| +| `01-business-flows.md` | user journeys, rules, approvals, glossary | `business_flows` | +| `02-architecture.md` | architecture, boundaries, integrations, non-negotiables | `architecture` | +| `03-risk-model.md` | fragile areas, release risk, review expectations | `risk_model` | +| `04-active-sprint.md` | current delivery state and sprint sync | `active_sprint` | + +### Example + +- A planner working on a new feature should start here, then load business flows, architecture, and active sprint before reading code. + +## Key rules + +- Read this file before any other KB file. +- Follow `knowledge-base/.kb-config.yml` for enabled modules and loading defaults. +- Consumer agents are read-only; only `knowledge-base-manager` may automate KB writes. +- If a relevant KB section is missing or clearly incomplete, do not fabricate facts. +- Keep this file small and move detail into linked Tier 1 or Tier 2 files. + +## Known gaps / uncertainty + +- Missing sections: {{KNOWN_MISSING_SECTIONS}} +- Open questions: {{OPEN_QUESTIONS}} + +## Linked evidence + +- Product brief: {{PRODUCT_BRIEF_LINK}} +- Architecture overview: {{ARCHITECTURE_OVERVIEW_LINK}} +- Sprint board or issue query: {{SPRINT_BOARD_LINK}} + +## Next review trigger + +- Review this file when the KB map, ownership model, system stage, or reading paths change. diff --git a/knowledge-base/templates/01-business-flows.md b/knowledge-base/templates/01-business-flows.md index 725c83b..0410da7 100644 --- a/knowledge-base/templates/01-business-flows.md +++ b/knowledge-base/templates/01-business-flows.md @@ -1,40 +1,79 @@ - +--- +id: kb.business-flows +title: Business Flows +owners: + - business_flows +audiences: + - product + - engineering + - qa +last_reviewed: "{{LAST_REVIEWED_DATE}}" +review_cycle_days: 30 +confidence: high +change_frequency: medium +source_refs: [] +tags: + - tier1 + - business +--- # Business Flows: {{PROJECT_NAME}} -**Domain:** {{BUSINESS_DOMAIN}} -**Primary Users:** {{PRIMARY_USER_ROLES}} +## Purpose -## Core Flows +Capture the user-facing flows, business rules, approvals, and glossary terms that engineering and QA should not rediscover from code alone. -| Flow ID | Flow Name | Initiator | Outcome | Notes | -|---------|-----------|-----------|---------|-------| +## Scope + +Use this file for high-value workflows and business truth. Keep implementation details, UI mechanics, and technical trade-offs out unless they directly affect business behavior. + +## What is true today + +### Core flows + +| Flow ID | Flow name | Initiator | Outcome | Notes | +|---|---|---|---|---| | BF-01 | {{FLOW_NAME_1}} | {{INITIATOR_1}} | {{OUTCOME_1}} | {{NOTES_1}} | | BF-02 | {{FLOW_NAME_2}} | {{INITIATOR_2}} | {{OUTCOME_2}} | {{NOTES_2}} | - +### Workflow details -## Flow Summaries +#### {{FLOW_NAME_1}} -### {{FLOW_NAME_1}} - Trigger: {{TRIGGER_1}} - Main path: {{MAIN_PATH_1}} - Edge cases: {{EDGE_CASES_1}} - Important business rule: {{BUSINESS_RULE_1}} -### {{FLOW_NAME_2}} +#### {{FLOW_NAME_2}} + - Trigger: {{TRIGGER_2}} - Main path: {{MAIN_PATH_2}} - Edge cases: {{EDGE_CASES_2}} - Important business rule: {{BUSINESS_RULE_2}} -## Cross-Cutting Rules -- {{CROSS_RULE_1}} -- {{CROSS_RULE_2}} +### Example + +- Example: "Learner submits assessment" should name the trigger, the happy path, approval logic, and what happens if the submission is incomplete. + +## Key rules + +- Prefer business language over technical design language. +- Keep the highest-value workflows in this file; move history into Tier 2 if needed. +- Update this file whenever business behavior or approval logic changes. +- Add glossary terms when the same business word is repeatedly misunderstood. + +## Known gaps / uncertainty + +- Missing workflows: {{MISSING_WORKFLOWS}} +- Unresolved business questions: {{OPEN_BUSINESS_QUESTIONS}} + +## Linked evidence + +- Product requirement doc: {{PRD_LINK}} +- Acceptance criteria source: {{ACCEPTANCE_CRITERIA_LINK}} +- Process or SOP reference: {{PROCESS_DOC_LINK}} + +## Next review trigger - +- Review this file when a feature changes user behavior, approval logic, role interactions, or business terminology. diff --git a/knowledge-base/templates/02-architecture.md b/knowledge-base/templates/02-architecture.md index 59c1728..c1495df 100644 --- a/knowledge-base/templates/02-architecture.md +++ b/knowledge-base/templates/02-architecture.md @@ -1,41 +1,78 @@ - +--- +id: kb.architecture +title: Architecture +owners: + - architecture +audiences: + - engineering + - qa + - product +last_reviewed: "{{LAST_REVIEWED_DATE}}" +review_cycle_days: 30 +confidence: high +change_frequency: medium +source_refs: [] +tags: + - tier1 + - architecture +--- # Architecture: {{PROJECT_NAME}} -## Tech Stack +## Purpose + +Describe the current system boundaries, modules, integration points, and non-negotiable engineering rules that should shape implementation and review. + +## Scope + +Use this file for architecture that is true today. Keep long historical reasoning and deep decision history in Tier 2 logs such as `advanced/decision-log.md`. + +## What is true today + +### Tech stack | Layer | Technology | Version | Notes | -|-------|------------|---------|-------| +|---|---|---|---| | {{LAYER_1}} | {{TECH_1}} | {{VERSION_1}} | {{NOTES_1}} | | {{LAYER_2}} | {{TECH_2}} | {{VERSION_2}} | {{NOTES_2}} | | {{LAYER_3}} | {{TECH_3}} | {{VERSION_3}} | {{NOTES_3}} | -## Directory Structure +### Ownership boundaries -| Path | Responsibility | Must Not Contain | -|------|----------------|------------------| +| Path or module | Responsibility | Must not contain | +|---|---|---| | `{{DIR_1}}` | {{RESPONSIBILITY_1}} | {{FORBIDDEN_1}} | | `{{DIR_2}}` | {{RESPONSIBILITY_2}} | {{FORBIDDEN_2}} | | `{{DIR_3}}` | {{RESPONSIBILITY_3}} | {{FORBIDDEN_3}} | -## Established Patterns -- {{PATTERN_1}} -- {{PATTERN_2}} -- {{PATTERN_3}} - -## Integration Points +### Integration points | System | Purpose | Contract | Notes | -|--------|---------|----------|-------| +|---|---|---|---| | {{SYSTEM_1}} | {{PURPOSE_1}} | {{CONTRACT_1}} | {{NOTES_4}} | -## Non-Negotiable Rules -- {{RULE_1}} -- {{RULE_2}} -- {{RULE_3}} +### Example + +- Example: "Permissions are enforced in the service layer, not in controllers" is the kind of non-negotiable architectural rule that belongs here. + +## Key rules + +- Document what is true in production or the mainline branch today, not a proposed future state. +- Keep module boundaries and sensitive paths explicit. +- Update this file whenever system responsibilities, data flow, caching strategy, integrations, or permission boundaries change. +- Link major trade-offs to `advanced/decision-log.md` when that file is enabled. + +## Known gaps / uncertainty + +- Areas needing a deeper map: {{ARCHITECTURE_GAPS}} +- Open technical questions: {{OPEN_TECHNICAL_QUESTIONS}} + +## Linked evidence + +- ADR or decision record: {{ADR_LINK}} +- System diagram: {{SYSTEM_DIAGRAM_LINK}} +- Integration contract docs: {{INTEGRATION_DOC_LINK}} + +## Next review trigger - +- Review this file when a service boundary, integration, schema strategy, data flow, or non-negotiable engineering rule changes. diff --git a/knowledge-base/templates/03-risk-model.md b/knowledge-base/templates/03-risk-model.md index 11ca5a5..acaecd4 100644 --- a/knowledge-base/templates/03-risk-model.md +++ b/knowledge-base/templates/03-risk-model.md @@ -1,38 +1,70 @@ - +--- +id: kb.risk-model +title: Risk Model +owners: + - risk_model +audiences: + - engineering + - qa + - product +last_reviewed: "{{LAST_REVIEWED_DATE}}" +review_cycle_days: 30 +confidence: high +change_frequency: medium +source_refs: [] +tags: + - tier1 + - risk +--- # Risk Model: {{PROJECT_NAME}} -## Risk Classification +## Purpose -| Area / Module | Risk Level | Reason | Required Review Gate | -|---------------|------------|--------|----------------------| +Capture the flows, modules, and release conditions most likely to create regressions, operational incidents, or high-cost review mistakes. + +## Scope + +Use this file for actionable risk guidance that should influence implementation, review, testing, and incident response. Keep sprint-specific status in `04-active-sprint.md`. + +## What is true today + +### Risk classification + +| Area or module | Risk level | Reason | Required review gate | +|---|---|---|---| | {{MODULE_1}} | High | {{REASON_1}} | {{GATE_1}} | | {{MODULE_2}} | Medium | {{REASON_2}} | {{GATE_2}} | | {{MODULE_3}} | Low | {{REASON_3}} | Standard PR review | -## High-Risk Change Triggers -- {{TRIGGER_1}} -- {{TRIGGER_2}} -- {{TRIGGER_3}} +### Fragile areas -## Required Actions By Risk Level +| Area | Known issue pattern | Mitigation | +|---|---|---| +| {{AREA_1}} | {{PATTERN_1}} | {{MITIGATION_1}} | -| Risk Level | Required Actions | -|------------|------------------| -| High | {{HIGH_ACTIONS}} | -| Medium | {{MEDIUM_ACTIONS}} | -| Low | Standard PR review | +### Example -## Known Fragile Areas +- Example: "Enrollment state transitions must have integration coverage because repeated regressions have escaped unit tests" is the level of concrete risk guidance this file should keep. -| Area | Known Issue Pattern | Mitigation | -|------|---------------------|------------| -| {{AREA_1}} | {{PATTERN_1}} | {{MITIGATION_1}} | +## Key rules + +- Update this file when a bug, incident, or review failure reveals new fragility. +- Define the minimum review and test expectation for high-risk areas. +- Record security-sensitive or compliance-sensitive paths explicitly. +- Keep risk statements concrete enough that reviewers can act on them. + +## Known gaps / uncertainty + +- Missing risk coverage: {{MISSING_RISK_AREAS}} +- Open release concerns: {{OPEN_RELEASE_CONCERNS}} + +## Linked evidence + +- Incident or RCA doc: {{INCIDENT_DOC_LINK}} +- Test strategy doc: {{TEST_STRATEGY_LINK}} +- Security or compliance reference: {{SECURITY_DOC_LINK}} + +## Next review trigger -## Sensitive Data Rules -- {{DATA_RULE_1}} -- {{DATA_RULE_2}} +- Review this file when recurring regressions appear, an incident occurs, a critical flow changes, or release criteria need tighter coverage. diff --git a/knowledge-base/templates/04-active-sprint.md b/knowledge-base/templates/04-active-sprint.md index 2143d7d..cab0f33 100644 --- a/knowledge-base/templates/04-active-sprint.md +++ b/knowledge-base/templates/04-active-sprint.md @@ -1,32 +1,81 @@ - +--- +id: kb.active-sprint +title: Active Sprint +owners: + - active_sprint +audiences: + - engineering + - product + - qa +last_reviewed: "{{LAST_REVIEWED_DATE}}" +review_cycle_days: 7 +confidence: medium +change_frequency: high +source_refs: [] +tags: + - tier1 + - sprint +--- # Active Sprint: {{PROJECT_NAME}} -**Sprint:** {{SPRINT_NAME_OR_NUMBER}} -**Sprint Goal:** {{SPRINT_GOAL}} -**Period:** {{SPRINT_START_DATE}} → {{SPRINT_END_DATE}} +## Purpose -## Active Issues +Track the current sprint goal, active work, blockers, and recent completions so planning and execution agents do not need to reconstruct current delivery state from scratch. + +## Scope + +This file is the canonical volatile Tier 1 file. Keep it focused on the current sprint or active delivery window. Archive long-running history into project systems of record or Tier 2 if needed. + +## What is true today + +### Sprint summary + +- Sprint: {{SPRINT_NAME_OR_NUMBER}} +- Sprint goal: {{SPRINT_GOAL}} +- Period: {{SPRINT_START_DATE}} to {{SPRINT_END_DATE}} + +### Active issues | Issue | Title | Assignee | Status | Notes | -|-------|-------|----------|--------|-------| +|---|---|---|---|---| | #{{ISSUE_NUMBER_1}} | {{ISSUE_TITLE_1}} | {{ASSIGNEE_1}} | {{STATUS_1}} | {{PROGRESS_NOTE_1}} | | #{{ISSUE_NUMBER_2}} | {{ISSUE_TITLE_2}} | {{ASSIGNEE_2}} | {{STATUS_2}} | {{PROGRESS_NOTE_2}} | -## Blocked Items +### Blocked items | Issue | Blocker | Owner | -|-------|---------|-------| +|---|---|---| | #{{BLOCKED_ISSUE}} | {{BLOCKER_DESCRIPTION}} | {{BLOCKER_OWNER}} | -## Completed This Sprint +### Completed this sprint -| Issue | Title | Completed On | -|-------|-------|--------------| +| Issue | Title | Completed on | +|---|---|---| | #{{DONE_ISSUE_1}} | {{DONE_TITLE_1}} | {{DONE_DATE_1}} | - +### Example + +- Example: when issue `#123` moves from active work to review, update the existing row instead of inserting a duplicate issue entry. + +## Key rules + +- Keep this file current; it is the default KB automation target. +- Update issue rows in place to avoid duplicates. +- Move completed work into the completion table when it is done or closed. +- Keep notes short, factual, and tied to visible sprint state. + +## Known gaps / uncertainty + +- Missing issue context: {{MISSING_SPRINT_CONTEXT}} +- Unresolved blockers: {{OPEN_BLOCKERS}} + +## Linked evidence + +- Sprint board: {{SPRINT_BOARD_LINK}} +- Delivery issue query: {{ISSUE_QUERY_LINK}} +- Sprint review notes: {{SPRINT_REVIEW_LINK}} + +## Next review trigger + +- Review this file whenever issue state changes, blockers appear, sprint scope changes, or the sprint window rolls over. diff --git a/knowledge-base/templates/CLAUDE.section.md b/knowledge-base/templates/CLAUDE.section.md index 31a0cdb..0595566 100644 --- a/knowledge-base/templates/CLAUDE.section.md +++ b/knowledge-base/templates/CLAUDE.section.md @@ -9,5 +9,13 @@ This project stores structured context in `knowledge-base/`. - Treat KB files as read-only unless you are the designated KB maintenance flow. - If the numbered flat KB does not exist, you may fall back to the older numbered tree layout or the legacy flat layout if present. +### Write Policy +- Consumer agents are read-only. +- Only `knowledge-base-manager` may automate KB writes. +- If KB context is missing or clearly incomplete, do not fabricate facts. + +### Delivery Rule +- Every task must make an explicit KB impact decision before it is considered done. + ### Graceful Degradation If no knowledge base exists, proceed normally without KB-aware behavior. diff --git a/knowledge-base/templates/README.md b/knowledge-base/templates/README.md index bb5b7c8..81bc92a 100644 --- a/knowledge-base/templates/README.md +++ b/knowledge-base/templates/README.md @@ -24,3 +24,13 @@ These templates are copied into downstream projects. - Do not force child-file creation for routine KB updates. - Treat Tier 2 as opt-in and mostly append-only. - Keep KB content plain Markdown plus lightweight config. +- Canonical KB content templates should include front matter metadata. +- Canonical Tier 1 templates should keep the shared top-level section schema: + - `Purpose` + - `Scope` + - `What is true today` + - `Key rules` + - `Known gaps / uncertainty` + - `Linked evidence` + - `Next review trigger` +- `CLAUDE.section.md` is a helper snippet, not a KB content file, so it does not use front matter. diff --git a/knowledge-base/templates/advanced/decision-log.md b/knowledge-base/templates/advanced/decision-log.md index e7e7dd9..47fc738 100644 --- a/knowledge-base/templates/advanced/decision-log.md +++ b/knowledge-base/templates/advanced/decision-log.md @@ -1,16 +1,52 @@ +--- +id: kb.decision-log +title: Decision Log +owners: + - decision_log +audiences: + - engineering + - product + - qa +last_reviewed: "{{LAST_REVIEWED_DATE}}" +review_cycle_days: 90 +confidence: medium +change_frequency: medium +source_refs: [] +tags: + - tier2 + - decision-log +--- + # Decision Log: {{PROJECT_NAME}} ## Purpose -Append-only record of notable architecture or product decisions. -## Rules -- Append newest entries at the top -- Keep each entry under 6 bullets -- Record context, decision, and trade-off only +Append-only record of meaningful architecture or product decisions that should remain discoverable after the immediate implementation work is over. + +## Scope + +Capture decisions that changed system boundaries, delivery risk, or business behavior. Skip trivial implementation details. + +## Update rules + +- Append newest entries at the top. +- Keep each entry under 6 bullets. +- Record context, decision, trade-off, and follow-up. + +## Entry template -## Entry Template ### {{DATE}}: {{DECISION_TITLE}} + - Context: {{DECISION_CONTEXT}} - Decision: {{DECISION_TAKEN}} - Trade-off: {{DECISION_TRADEOFF}} - Follow-up: {{DECISION_FOLLOWUP}} + +## Example entry + +### 2026-03-07: Cache read-heavy report queries for five minutes + +- Context: The report endpoint was timing out under repeated staff queries. +- Decision: Add a short-lived cache around the aggregated report response. +- Trade-off: Metrics may be slightly stale for a few minutes. +- Follow-up: Revisit cache invalidation if staff workflows become real-time. diff --git a/knowledge-base/templates/advanced/feature-history.md b/knowledge-base/templates/advanced/feature-history.md index f094bac..819b20d 100644 --- a/knowledge-base/templates/advanced/feature-history.md +++ b/knowledge-base/templates/advanced/feature-history.md @@ -1,11 +1,52 @@ +--- +id: kb.feature-history +title: Feature History +owners: + - feature_history +audiences: + - product + - engineering + - qa +last_reviewed: "{{LAST_REVIEWED_DATE}}" +review_cycle_days: 90 +confidence: medium +change_frequency: medium +source_refs: [] +tags: + - tier2 + - feature-history +--- + # Feature History: {{PROJECT_NAME}} ## Purpose -Compact record of meaningful shipped features and their outcomes. -## Entry Template +Compact record of meaningful shipped features and what changed in the product because of them. + +## Scope + +Use this file for features that materially affect onboarding, requirement refinement, or support conversations. Skip minor UI cleanups and internal-only refactors. + +## Update rules + +- Add the newest shipped feature at the top. +- Focus on intent, shipped scope, observed outcome, and follow-up. +- Keep entries short enough to scan during onboarding. + +## Entry template + ### {{DATE}}: {{FEATURE_NAME}} + - Intent: {{FEATURE_INTENT}} - Scope shipped: {{FEATURE_SCOPE}} - Outcome: {{FEATURE_OUTCOME}} - Follow-up: {{FEATURE_FOLLOWUP}} + +## Example entry + +### 2026-03-07: Bulk learner import + +- Intent: Reduce manual onboarding work for partner staff. +- Scope shipped: CSV upload with validation and per-row error reporting. +- Outcome: Staff onboarding time dropped and support requests moved to data-quality issues. +- Follow-up: Add saved import mappings if the same CSV shape repeats. diff --git a/knowledge-base/templates/advanced/incident-log.md b/knowledge-base/templates/advanced/incident-log.md index 195a32a..af5841c 100644 --- a/knowledge-base/templates/advanced/incident-log.md +++ b/knowledge-base/templates/advanced/incident-log.md @@ -1,11 +1,52 @@ +--- +id: kb.incident-log +title: Incident Log +owners: + - incident_log +audiences: + - engineering + - qa + - product +last_reviewed: "{{LAST_REVIEWED_DATE}}" +review_cycle_days: 90 +confidence: medium +change_frequency: medium +source_refs: [] +tags: + - tier2 + - incident-log +--- + # Incident Log: {{PROJECT_NAME}} ## Purpose -Append-only record of incidents, regressions, or reliability events that should inform future work. -## Entry Template +Append-only record of incidents, regressions, or reliability events that should inform future work and reduce repeat failures. + +## Scope + +Capture events that changed detection, prevention, or recovery expectations. Skip transient noise that taught the team nothing durable. + +## Update rules + +- Append newest incidents at the top. +- Record symptom, root cause, fix, and prevention. +- Link the incident to risk model updates when the learning changes future review or test expectations. + +## Entry template + ### {{DATE}}: {{INCIDENT_TITLE}} + - Symptom: {{INCIDENT_SYMPTOM}} - Root cause: {{INCIDENT_ROOT_CAUSE}} - Fix: {{INCIDENT_FIX}} - Prevention: {{INCIDENT_PREVENTION}} + +## Example entry + +### 2026-03-07: Background sync stopped processing retry jobs + +- Symptom: Retry queues grew for two hours and learner notifications were delayed. +- Root cause: A scheduler change removed the retry worker from one environment. +- Fix: Restore the worker and replay the queued jobs. +- Prevention: Add a deployment smoke check that confirms every required worker is running. diff --git a/knowledge-base/templates/advanced/integration-map.md b/knowledge-base/templates/advanced/integration-map.md index c43854f..d2642a4 100644 --- a/knowledge-base/templates/advanced/integration-map.md +++ b/knowledge-base/templates/advanced/integration-map.md @@ -1,8 +1,46 @@ +--- +id: kb.integration-map +title: Integration Map +owners: + - integration_map +audiences: + - engineering + - qa + - product +last_reviewed: "{{LAST_REVIEWED_DATE}}" +review_cycle_days: 90 +confidence: medium +change_frequency: medium +source_refs: [] +tags: + - tier2 + - integration-map +--- + # Integration Map: {{PROJECT_NAME}} ## Purpose -List only the external systems and cross-boundary dependencies that materially affect reliability or implementation. -| System | Purpose | Auth | Failure mode | Fallback / Owner | +List the external systems and cross-boundary dependencies that materially affect implementation, delivery risk, or incident response. + +## Scope + +Only keep integrations that matter to reliability or delivery. Skip purely internal calls that are already obvious from the main architecture file. + +## Update rules + +- Update this file when a new external dependency is added or a contract changes. +- Keep auth, failure mode, and fallback ownership explicit. +- Link deeper technical details from outside this file if needed. + +## Integration table + +| System | Purpose | Auth | Failure mode | Fallback or owner | |---|---|---|---|---| | {{SYSTEM_1}} | {{PURPOSE_1}} | {{AUTH_1}} | {{FAILURE_1}} | {{FALLBACK_1}} | + +## Example + +| System | Purpose | Auth | Failure mode | Fallback or owner | +|---|---|---|---|---| +| Payment gateway | Collect course fees | API key + webhook signing | Delayed webhook confirmation | Finance ops + retry job | diff --git a/knowledge-base/templates/advanced/known-constraints.md b/knowledge-base/templates/advanced/known-constraints.md index 5066cc1..b3e84e9 100644 --- a/knowledge-base/templates/advanced/known-constraints.md +++ b/knowledge-base/templates/advanced/known-constraints.md @@ -1,8 +1,44 @@ +--- +id: kb.known-constraints +title: Known Constraints +owners: + - known_constraints +audiences: + - engineering + - product + - qa +last_reviewed: "{{LAST_REVIEWED_DATE}}" +review_cycle_days: 90 +confidence: medium +change_frequency: low +source_refs: [] +tags: + - tier2 + - constraints +--- + # Known Constraints: {{PROJECT_NAME}} ## Purpose -Document hard constraints that should not be rediscovered repeatedly. + +Document hard technical, business, or operational constraints that teams should not have to rediscover repeatedly. + +## Scope + +Keep only durable constraints here. Temporary sprint blockers belong in `04-active-sprint.md`. + +## Update rules + +- Add constraints that materially shape implementation choices. +- State the constraint and why it exists. +- Remove constraints only when the underlying limitation is genuinely gone. + +## Constraint list - {{CONSTRAINT_1}} - {{CONSTRAINT_2}} - {{CONSTRAINT_3}} + +## Example + +- Course completion data must be retained for audit purposes even if a learner account is later deactivated. diff --git a/knowledge-base/templates/advanced/metrics.md b/knowledge-base/templates/advanced/metrics.md index d330536..1d504ef 100644 --- a/knowledge-base/templates/advanced/metrics.md +++ b/knowledge-base/templates/advanced/metrics.md @@ -1,9 +1,47 @@ +--- +id: kb.metrics +title: Metrics +owners: + - metrics +audiences: + - engineering + - product + - qa +last_reviewed: "{{LAST_REVIEWED_DATE}}" +review_cycle_days: 90 +confidence: medium +change_frequency: low +source_refs: [] +tags: + - tier2 + - metrics +--- + # Metrics: {{PROJECT_NAME}} ## Purpose -Capture a few baseline metrics so teams and agents understand normal operating context. + +Capture a small set of baseline product or operational metrics so teams and agents understand normal operating context before reacting to change. + +## Scope + +Keep only metrics that materially affect prioritization, delivery risk, or support expectations. + +## Update rules + +- Prefer a few stable metrics over a long dashboard export. +- Record the current baseline, directional trend, and any caveats. +- Link the source report or dashboard in `source_refs` when possible. + +## Metric table | Metric | Baseline | Trend | Notes | |---|---|---|---| | {{METRIC_1}} | {{BASELINE_1}} | {{TREND_1}} | {{NOTES_1}} | | {{METRIC_2}} | {{BASELINE_2}} | {{TREND_2}} | {{NOTES_2}} | + +## Example + +| Metric | Baseline | Trend | Notes | +|---|---|---|---| +| Weekly learner submissions | 2,400 | rising | Peaks after partner training days | From 742bea8fc1ead1fb26c8bcf2398469c5ed94f030 Mon Sep 17 00:00:00 2001 From: Anurag Kumawat Date: Mon, 9 Mar 2026 10:49:05 +0530 Subject: [PATCH 15/16] removed the template --- claude/agents/knowledge-base-manager/README.md | 1 - knowledge-base/ADOPTION-GUIDE.md | 6 ++---- knowledge-base/README.md | 2 -- knowledge-base/SPEC.md | 2 +- knowledge-base/project-files/README.md | 2 +- knowledge-base/prompts/install-hybrid-kb.md | 11 ++++------- knowledge-base/scripts/scaffold_hybrid_kb.py | 7 ------- 7 files changed, 8 insertions(+), 23 deletions(-) diff --git a/claude/agents/knowledge-base-manager/README.md b/claude/agents/knowledge-base-manager/README.md index 17314d8..6a9c142 100644 --- a/claude/agents/knowledge-base-manager/README.md +++ b/claude/agents/knowledge-base-manager/README.md @@ -49,7 +49,6 @@ If the project uses the hybrid KB contract, `knowledge-base/.kb-config.yml` is t ## Recommended Workflow Assets For downstream teams, pair this agent with: -- `knowledge-base/project-files/pull_request_template.md` - `knowledge-base/project-files/KB-PROCESS.md` Those assets make the "KB impact" decision part of the delivery workflow instead of a manual reminder. diff --git a/knowledge-base/ADOPTION-GUIDE.md b/knowledge-base/ADOPTION-GUIDE.md index bf4feb7..afe15ab 100644 --- a/knowledge-base/ADOPTION-GUIDE.md +++ b/knowledge-base/ADOPTION-GUIDE.md @@ -18,7 +18,7 @@ This repo now provides: - metadata-enabled KB templates - a validator that checks structure, front matter, headings, freshness, and owner links - a scaffold script that can install the KB, KB manager, and optional workflow assets -- reusable downstream workflow files for KB-aware PR review and delivery rules +- a reusable downstream workflow file for KB delivery rules ## Project Install Checklist @@ -64,7 +64,7 @@ Enable Tier 2 only when it is justified: ## Delivery Workflow Rules - Every task must make an explicit KB impact decision before it is considered done. -- KB impact belongs in the PR template, not in memory. +- KB impact belongs in the documented delivery workflow, not in memory. - Reviewers should check code and KB consistency together when KB impact is marked. - The KB manager should keep `04-active-sprint.md` current, but other Tier 1 files should still be reviewed by human owners. @@ -114,7 +114,6 @@ Front matter `owners` fields should reference keys from `.kb-config.yml` so vali - populate the Tier 1 baseline ### Week 3 -- install KB-aware PR template - add KB issue labels - publish/update the project KB process doc - run the first real update flows and remove friction @@ -127,6 +126,5 @@ Front matter `owners` fields should reference keys from `.kb-config.yml` so vali ## Related Assets -- [project-files/pull_request_template.md](project-files/pull_request_template.md) - [project-files/KB-PROCESS.md](project-files/KB-PROCESS.md) - [prompts/install-hybrid-kb.md](prompts/install-hybrid-kb.md) diff --git a/knowledge-base/README.md b/knowledge-base/README.md index d08ff36..ee89c75 100644 --- a/knowledge-base/README.md +++ b/knowledge-base/README.md @@ -69,7 +69,6 @@ knowledge-base/ python3 knowledge-base/scripts/scaffold_hybrid_kb.py /path/to/target-project \ --enable decision-log,incident-log \ --install-kb-manager \ - --install-pr-template \ --install-kb-process ``` @@ -143,7 +142,6 @@ New projects should use the numbered-flat contract. ## Recommended Downstream Workflow Assets For downstream project repos, the starter kit also ships reusable workflow files: -- [project-files/pull_request_template.md](project-files/pull_request_template.md) - [project-files/KB-PROCESS.md](project-files/KB-PROCESS.md) These are not part of the strict KB file contract, but they make KB updates part of normal delivery. diff --git a/knowledge-base/SPEC.md b/knowledge-base/SPEC.md index ab0a2eb..543f299 100644 --- a/knowledge-base/SPEC.md +++ b/knowledge-base/SPEC.md @@ -178,7 +178,7 @@ Recommended default: ## Operational Workflow Expectations - every task should make an explicit KB impact decision -- KB-aware PR review should check code and KB alignment together +- review should check code and KB alignment together - `04-active-sprint.md` is the default automation target - business, architecture, risk, and sprint each need named owners in the downstream project - missing KB context must not be fabricated by agents diff --git a/knowledge-base/project-files/README.md b/knowledge-base/project-files/README.md index f8cddfd..6f9a4cb 100644 --- a/knowledge-base/project-files/README.md +++ b/knowledge-base/project-files/README.md @@ -4,4 +4,4 @@ These files are optional downstream assets that make the KB part of normal deliv - `KB-PROCESS.md`: trigger matrix, ownership, labels, and definition-of-done guidance -They are not part of the strict KB file contract, but the scaffold script can install them into downstream repos. +It is not part of the strict KB file contract, but the scaffold script can install it into downstream repos. diff --git a/knowledge-base/prompts/install-hybrid-kb.md b/knowledge-base/prompts/install-hybrid-kb.md index a8fec73..265176d 100644 --- a/knowledge-base/prompts/install-hybrid-kb.md +++ b/knowledge-base/prompts/install-hybrid-kb.md @@ -10,7 +10,6 @@ Source directory to read from: - `knowledge-base/templates/advanced/` - `knowledge-base/templates/.kb-config.yml` - `knowledge-base/templates/CLAUDE.section.md` -- `knowledge-base/project-files/pull_request_template.md` - `knowledge-base/project-files/KB-PROCESS.md` - `knowledge-base/scripts/scaffold_hybrid_kb.py` - `knowledge-base/scripts/validate_hybrid_kb.py` @@ -53,7 +52,6 @@ Follow these steps exactly: - Prefer running `knowledge-base/scripts/scaffold_hybrid_kb.py` from the source repo against this project root. - Use `--enable` only for the Tier 2 modules I confirmed. - Use `--install-kb-manager` if this project uses Claude agents. - - Use `--install-pr-template` if this project does not already have a PR template. - Use `--install-kb-process` if this project does not already have a KB workflow doc. - Only fall back to manual file copying if the scaffold script cannot be run. - The install must create the numbered flat hybrid contract: @@ -90,13 +88,12 @@ Follow these steps exactly: - If the section is missing, create it. - If the section exists but does not list `knowledge-base-manager`, add it. - Do not duplicate an existing entry. -13. If the project does not already have a KB-aware PR template, copy `knowledge-base/project-files/pull_request_template.md` to `.github/pull_request_template.md`. -14. If the project does not already have a KB workflow doc, copy `knowledge-base/project-files/KB-PROCESS.md` to `docs/kb-process.md`. -15. Run the installed validator from this project's root: +13. If the project does not already have a KB workflow doc, copy `knowledge-base/project-files/KB-PROCESS.md` to `docs/kb-process.md`. +14. Run the installed validator from this project's root: - `python3 knowledge-base/scripts/validate_hybrid_kb.py .` - If validation fails, show me the errors and stop. - If validation passes with warnings, summarize the warnings and which ones are expected placeholders vs real setup gaps. -16. At the end, show me: +15. At the end, show me: - files created - whether the scaffold script was used or whether you had to fall back to manual copying - placeholders inferred @@ -106,7 +103,7 @@ Follow these steps exactly: - Tier 2 modules enabled - owners assigned in `.kb-config.yml` - whether `knowledge-base-manager` agent was installed or already existed - - whether the PR template and KB process doc were installed + - whether the KB process doc was installed - the exact scaffold command that was run - the exact validation command that was run ``` diff --git a/knowledge-base/scripts/scaffold_hybrid_kb.py b/knowledge-base/scripts/scaffold_hybrid_kb.py index 15cf66d..75592f1 100644 --- a/knowledge-base/scripts/scaffold_hybrid_kb.py +++ b/knowledge-base/scripts/scaffold_hybrid_kb.py @@ -29,7 +29,6 @@ "known-constraints": "advanced/known-constraints.md", } OPTIONAL_PROJECT_FILES = { - "pr_template": (PROJECT_FILES_ROOT / "pull_request_template.md", Path(".github/pull_request_template.md")), "kb_process": (PROJECT_FILES_ROOT / "KB-PROCESS.md", Path("docs/kb-process.md")), } CLAUDE_SECTION = TEMPLATES / "CLAUDE.section.md" @@ -182,7 +181,6 @@ def main() -> int: help="Comma-separated Tier 2 modules to enable (decision-log,incident-log,feature-history,integration-map,metrics,known-constraints)", ) parser.add_argument("--install-kb-manager", action="store_true", help="Install the write-enabled KB manager agent") - parser.add_argument("--install-pr-template", action="store_true", help="Install the KB-aware PR template") parser.add_argument("--install-kb-process", action="store_true", help="Install the KB working-agreement doc") parser.add_argument("--overwrite", action="store_true", help="Overwrite existing files") args = parser.parse_args() @@ -227,10 +225,6 @@ def main() -> int: copy_file(KB_MANAGER_AGENT, project_root / ".claude" / "agents" / "knowledge-base-manager.md", args.overwrite) ) - if args.install_pr_template: - src, dest = OPTIONAL_PROJECT_FILES["pr_template"] - actions.append(copy_file(src, project_root / dest, args.overwrite)) - if args.install_kb_process: src, dest = OPTIONAL_PROJECT_FILES["kb_process"] actions.append(copy_file(src, project_root / dest, args.overwrite)) @@ -243,7 +237,6 @@ def main() -> int: print(f"- {action}") print(f"- enabled Tier 2: {', '.join(enabled) if enabled else 'none'}") print(f"- KB manager installed: {'yes' if args.install_kb_manager else 'no'}") - print(f"- PR template installed: {'yes' if args.install_pr_template else 'no'}") print(f"- KB process doc installed: {'yes' if args.install_kb_process else 'no'}") print("- validate from the project root with: python3 knowledge-base/scripts/validate_hybrid_kb.py .") return 0 From b8c19fb0a4129dbb821475a53dfea4299c15b332 Mon Sep 17 00:00:00 2001 From: Anurag Kumawat Date: Mon, 9 Mar 2026 10:54:47 +0530 Subject: [PATCH 16/16] fix --- knowledge-base/ADOPTION-GUIDE.md | 6 ++++- knowledge-base/README.md | 22 ++++++++++++++---- .../scaffold_hybrid_kb.cpython-313.pyc | Bin 6786 -> 0 bytes .../validate_hybrid_kb.cpython-313.pyc | Bin 6323 -> 0 bytes 4 files changed, 22 insertions(+), 6 deletions(-) delete mode 100644 knowledge-base/scripts/__pycache__/scaffold_hybrid_kb.cpython-313.pyc delete mode 100644 knowledge-base/scripts/__pycache__/validate_hybrid_kb.cpython-313.pyc diff --git a/knowledge-base/ADOPTION-GUIDE.md b/knowledge-base/ADOPTION-GUIDE.md index afe15ab..f6decc5 100644 --- a/knowledge-base/ADOPTION-GUIDE.md +++ b/knowledge-base/ADOPTION-GUIDE.md @@ -16,10 +16,14 @@ Use this guide when rolling the hybrid KB into a downstream project. It assumes This repo now provides: - the versioned KB contract - metadata-enabled KB templates -- a validator that checks structure, front matter, headings, freshness, and owner links +- a validator that checks contract structure, metadata, loading references, and KB hygiene for canonical numbered-flat installs - a scaffold script that can install the KB, KB manager, and optional workflow assets - a reusable downstream workflow file for KB delivery rules +Compatibility note: +- numbered-tree and legacy-flat installs still validate for required files, entry references, config, and enabled Tier 2 modules +- deep checks such as front matter, shared Tier 1 headings, size budgets, and duplicate-claim hygiene apply only to the canonical numbered-flat layout + ## Project Install Checklist 1. Scaffold the KB into the target project. diff --git a/knowledge-base/README.md b/knowledge-base/README.md index ee89c75..5310ac3 100644 --- a/knowledge-base/README.md +++ b/knowledge-base/README.md @@ -99,17 +99,29 @@ Run this from the target project root after installation: python3 knowledge-base/scripts/validate_hybrid_kb.py . ``` -The validator checks: +The validator has two levels of coverage. + +For canonical numbered-flat installs, it checks: - required Tier 1 files exist - `.kb-config.yml` has the minimum contract keys - `00-master.md` references the numbered-flat Tier 1 files +- `loading_defaults` file references resolve correctly - canonical Tier 1 files contain front matter and the required shared headings - front matter freshness and owner links can be evaluated +- Tier 1 files stay within recommended size budgets - append-only logs use a recognizable entry format - enabled Tier 2 modules in config have matching files -- older numbered-tree and legacy-flat projects still validate as compatibility installs +- duplicate canonical claims and other KB hygiene issues can be flagged as warnings + +For numbered-tree and legacy-flat compatibility installs, it checks: +- required files for the compatibility layout exist +- the entry file references the expected compatibility files +- `.kb-config.yml` still validates +- enabled Tier 2 modules in config have matching files + +Deep schema checks such as front matter, shared Tier 1 headings, size budgets, and duplicate-claim hygiene are skipped for compatibility layouts. -Warnings are used for freshness, owner-link, and duplication hygiene issues so a fresh scaffold can pass before the project is fully populated. +Warnings are used by default for freshness, owner-link, size-budget, and duplication hygiene issues so a fresh scaffold can pass before the project is fully populated. Use `--strict-freshness` if stale `last_reviewed` metadata should fail validation. ## Why The Numbered-Flat Layout @@ -141,7 +153,7 @@ New projects should use the numbered-flat contract. ## Recommended Downstream Workflow Assets -For downstream project repos, the starter kit also ships reusable workflow files: +For downstream project repos, the starter kit also ships a reusable workflow file: - [project-files/KB-PROCESS.md](project-files/KB-PROCESS.md) -These are not part of the strict KB file contract, but they make KB updates part of normal delivery. +This is not part of the strict KB file contract, but it makes KB updates part of normal delivery. diff --git a/knowledge-base/scripts/__pycache__/scaffold_hybrid_kb.cpython-313.pyc b/knowledge-base/scripts/__pycache__/scaffold_hybrid_kb.cpython-313.pyc deleted file mode 100644 index ddac1cfb991a5109613e66a97439c8469ada8104..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 6786 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