diff --git a/README.md b/README.md index 37a48c1..2fd17af 100644 --- a/README.md +++ b/README.md @@ -11,3 +11,23 @@ Individual projects opt into recipes by copying or referencing them. |----------|--------|-------------| | Automated Code Review | [automated-code-review/](automated-code-review/) | Automated code review patterns | | Claude Agents | [claude/agents/implementation-planner/](claude/agents/implementation-planner/) | Claude Code agent that creates 4-hour task breakdown implementation plans from feature requirements and posts them to GitHub issues | +| Claude Agents | [claude/agents/implementation-executor/](claude/agents/implementation-executor/) | Claude Code agent that executes an existing implementation plan from a GitHub issue — implementing tasks sequentially, committing after each, and opening a PR | +| Claude Agents | [claude/agents/business-analyst/](claude/agents/business-analyst/) | Claude Code agent that refines raw or ambiguous feature requests into clear, business-aligned, non-technical requirement documents | +| Claude Agents | [claude/agents/knowledge-base-manager/](claude/agents/knowledge-base-manager/) | Claude Code agent that syncs the project knowledge base with GitHub issue state — the only agent with write access to KB files | +| Knowledge Base | [knowledge-base/](knowledge-base/) | Hybrid project-local KB starter kit with numbered-flat Tier 1 files, advanced context modules, scaffolding, and validation | + +## Hybrid Knowledge Base + +The current KB model is a hybrid starter kit: +- `engineering-recipes` owns the reusable contract, templates, scaffold tools, and validation helpers. +- Each project owns its instantiated KB inside its own repo. +- Tier 1 is small and required. +- Tier 2 is optional and loaded on demand. +- The default structure is numbered-flat so agents can read sections selectively and update Tier 1 reliably. +- Validation is explicit and lightweight after setup. + +Start with [knowledge-base/README.md](knowledge-base/README.md). + +Key KB rollout documents: +- [knowledge-base/KB-CONTRACT-V1-PILOT-SCOPE.md](knowledge-base/KB-CONTRACT-V1-PILOT-SCOPE.md) +- [knowledge-base/ADOPTION-GUIDE.md](knowledge-base/ADOPTION-GUIDE.md) diff --git a/claude/README.md b/claude/README.md index 187ecb6..dba6f6c 100644 --- a/claude/README.md +++ b/claude/README.md @@ -9,40 +9,83 @@ This directory contains reusable, templatized Claude Code agents that can be set | [implementation-planner](agents/implementation-planner/) | Translates feature requests into phased implementation plans using the 4-hour task theory and posts them as GitHub issue comments. | | [implementation-executor](agents/implementation-executor/) | Takes an existing implementation plan from a GitHub issue and executes it — implementing each task sequentially, committing after each, pushing, and opening a PR. | | [business-analyst](agents/business-analyst/) | Refines raw or ambiguous requests into clear, business-aligned, non-technical requirement documents with explicit scope and acceptance criteria. | +| [knowledge-base-manager](agents/knowledge-base-manager/) | Syncs the project knowledge base with GitHub issue activity — the only agent with write access to the KB. | + +## Knowledge Base Contract + +These agents now prefer the numbered-flat hybrid KB contract: +- entry file: `knowledge-base/00-master.md` +- runtime config: `knowledge-base/.kb-config.yml` +- core files: `01-business-flows.md`, `02-architecture.md`, `03-risk-model.md`, `04-active-sprint.md` +- consumer agents remain read-only when using the KB +- `knowledge-base-manager` is the only write-enabled KB automation flow + +Older numbered-tree and legacy-flat KB layouts remain supported as fallbacks. ## Setting Up Agents in Your Project -> **Important:** Run the prompt below from your project's root directory so that Claude can access and review your project structure, tech stack, and conventions to automatically fill in placeholders. +> Run the install steps from your project's root directory so the agent can inspect that project directly. -### Steps +1. Copy the relevant agent markdown file into `.claude/agents/` in the target project. +2. If the target project uses the hybrid knowledge base, also install the KB starter kit from [`knowledge-base/`](../knowledge-base/). +3. Register the agents in the project's root `CLAUDE.md` if needed. -1. Open Claude Code in your project directory. -2. Copy and paste the prompt below. -3. Claude will review your codebase, set up the agent files, and ask you about anything it can't infer on its own. +## Copy-Paste Install Prompt -### Prompt +Paste the following prompt into your coding agent session from the target project's root directory: -``` -I want to set up Claude Code agents from the engineering-recipes repo into this project. +```text +I want to set up Claude Code agents from the `https://github.com/anuragk16/engineering-recipes` repo into this project. + +Source repo: read the `claude/agents/` directory and each agent's README. + +Follow these steps exactly: -Source repo: https://github.com/ColoredCow/engineering-recipes (browse the `claude/agents/` directory for all available agents and their README). +1. Explore this project's codebase shallowly: + - README + - top-level config files + - top-level directory structure + - existing `CLAUDE.md` if present -For each agent found there: +2. Ensure `.claude/agents/` exists in this project. + - Create it if missing. -1. Read the agent's template file and its README (which contains the placeholder reference and example values). -2. Copy the agent template to `.claude/agents/.md` in this project. -3. Replace all `{{PLACEHOLDER}}` values with project-specific values by: - a. First, explore this project's codebase — look at the directory structure, config files, package.json/requirements.txt, existing patterns, test setup, and conventions to infer as many placeholder values as possible. - b. For any placeholder you cannot confidently determine from the codebase, ask me before proceeding. Present what you've inferred so far and ask only about the ones you're unsure of. -4. If the agent template has optional sections that don't apply to this project (e.g., Multi-Repository Context for a single-repo project), remove them. -5. Register all set-up agents in this project's CLAUDE.md under a "Custom Agents" section. Create CLAUDE.md if it doesn't exist. Do NOT mention how to invoke them (no Task tool, no Skill tool, no slash commands) — Claude Code handles invocation automatically based on the agent's description frontmatter. Example format (markdown): - ## Custom Agents - Custom agents are defined in `.claude/agents/`. They are automatically invoked based on your request. +3. Copy the relevant agent templates from the source repo into `.claude/agents/`: + - `implementation-planner` + - `implementation-executor` + - `business-analyst` + - `knowledge-base-manager` if this project will use the knowledge base - | Agent | When to Use | - |-------|-------------| - | implementation-planner | When the user asks for an implementation plan, technical breakdown, or task planning for a feature or issue. | - +4. For each copied agent: + - Read the agent template and README + - Replace `{{PLACEHOLDER}}` values only when they can be inferred confidently from this codebase + - If a value cannot be inferred confidently, stop and ask me only about the unresolved placeholders + - Remove optional sections that clearly do not apply to this project -After setup, show me a summary of what was configured and any values you'd recommend I review or adjust. +5. Check whether this project already has a hybrid knowledge base: + - `knowledge-base/00-master.md` + - `knowledge-base/.kb-config.yml` + If it does, keep the KB-aware instructions in the agents. + If it does not, leave the agent KB guidance intact because the agents already degrade gracefully when no KB exists. + +6. Update the project root `CLAUDE.md`: + - If it does not exist, create it + - Add a `Custom Agents` section if missing + - Register the installed agents in a table + - Add or preserve the `Knowledge Base` section only if this project has a KB or I ask you to install one + +7. At the end, show me: + - which agents were installed + - which placeholders were inferred + - which placeholders still need input + - whether `CLAUDE.md` was created or updated ``` + +### Recommended Order + +1. Install the hybrid KB starter kit first if the project needs structured AI context. +2. Then run the agent installation prompt. + +This keeps the downstream `CLAUDE.md` and KB-aware agent behavior aligned from the start. + +For KB installation guidance, start with [knowledge-base/README.md](../knowledge-base/README.md). diff --git a/claude/agents/business-analyst/business-analyst.md b/claude/agents/business-analyst/business-analyst.md index 618bad0..a07b9de 100644 --- a/claude/agents/business-analyst/business-analyst.md +++ b/claude/agents/business-analyst/business-analyst.md @@ -31,6 +31,23 @@ memory: project You are an expert business analyst for {{PROJECT_NAME}}. +## Knowledge Base Context + +Before reasoning about requirements, check for a project knowledge base: + +1. Prefer the numbered entry file at `knowledge-base/00-master.md`. + - If the numbered-flat section files do **not** exist, fall back to the numbered-tree layout. + - If neither numbered layout exists, fall back to `knowledge-base/00-index.md`. + - If no entry file exists: skip this entire section and proceed normally. +2. Read the detected entry file first. +3. If `knowledge-base/.kb-config.yml` exists, use it to confirm whether advanced modules are enabled, but do not load them unless the task requires them. +4. Prefer `knowledge-base/01-business-flows.md` when it exists and is complete. +5. If the project still uses the numbered-tree layout, fall back to `knowledge-base/01-business-flows/00-index.md`. +6. If the project still uses the legacy flat layout, fall back to `knowledge-base/business-flows.md`. +7. Skip any KB file that is clearly incomplete or still full of placeholders / `TODO:` content. +8. Use the loaded context to align your requirement language and business terminology with established project flows. If the knowledge base conflicts with explicit instructions in the user's prompt, **the user's prompt takes precedence**. +9. Do **not** write to or modify any knowledge base file. + ## Domain Context {{DOMAIN_CONTEXT}} diff --git a/claude/agents/implementation-executor/implementation-executor.md b/claude/agents/implementation-executor/implementation-executor.md index ca697b2..3653554 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 @@ -9,6 +9,23 @@ memory: project You are an expert software engineer and disciplined executor. You take structured implementation plans and turn them into production-ready code — methodically, one task at a time, with clean commits and a well-formed pull request at the end. +## Knowledge Base Context + +Before reading the implementation plan or exploring the codebase, check for a project knowledge base: + +1. Prefer the numbered entry file at `knowledge-base/00-master.md`. + - If the numbered-flat section files do **not** exist, fall back to the numbered-tree layout. + - If neither numbered layout exists, fall back to `knowledge-base/00-index.md`. + - If no entry file exists: skip this entire section and proceed normally. +2. Read the detected entry file first. +3. If `knowledge-base/.kb-config.yml` exists, treat it as the runtime source of truth for enabled modules and loading defaults. +4. Prefer `knowledge-base/02-architecture.md` when it exists and is complete. +5. If the project still uses the numbered-tree layout, fall back to `knowledge-base/02-architecture/00-index.md`. +6. If the project still uses the legacy flat layout, fall back to `knowledge-base/architecture.md`. +7. Skip any KB file that is clearly incomplete or still full of placeholders / `TODO:` content. +8. Use the loaded context to align your implementation with established architectural patterns, layer boundaries, and naming conventions. If the knowledge base conflicts with the user's prompt or the implementation plan, **those always take precedence**. +9. Do **not** write to or modify any knowledge base file. + ## Pre-requisites You **must** receive an implementation plan before you can start. The plan is typically: diff --git a/claude/agents/implementation-planner/implementation-planner.md b/claude/agents/implementation-planner/implementation-planner.md index 7e5d6c7..13d7f4c 100644 --- a/claude/agents/implementation-planner/implementation-planner.md +++ b/claude/agents/implementation-planner/implementation-planner.md @@ -9,6 +9,32 @@ memory: project You are an elite software architect and technical lead with deep expertise in {{TECH_STACK}} and agile task decomposition. You specialize in translating high-level business requirements into precise, actionable implementation plans that developers can immediately start working on. You have extensive experience with the 4-hour task theory — the principle that every development task should be broken down into chunks that take no more than 4 hours to complete, ensuring clarity, measurability, and momentum. +## Knowledge Base Context + +Before exploring the codebase or reasoning about the implementation, check for a project knowledge base: + +1. Prefer the numbered-flat entry file at `knowledge-base/00-master.md`. + - If the numbered-flat section files do **not** exist, fall back to the numbered-tree layout. + - If neither numbered layout exists, fall back to the legacy flat entry file at `knowledge-base/00-index.md`. + - If no entry file exists: skip this entire section and proceed normally. +2. Read the detected entry file first. +3. If `knowledge-base/.kb-config.yml` exists, treat it as the runtime source of truth for enabled modules and loading defaults. +4. For planning work, prefer these numbered-flat files when present and complete: + - `knowledge-base/01-business-flows.md` + - `knowledge-base/02-architecture.md` + - `knowledge-base/04-active-sprint.md` +5. If the project is still on the numbered-tree layout, fall back to: + - `knowledge-base/01-business-flows/00-index.md` + - `knowledge-base/02-architecture/00-index.md` + - `knowledge-base/04-active-sprint/00-index.md` +6. If the project is still on the legacy flat layout, fall back to: + - `knowledge-base/business-flows.md` + - `knowledge-base/architecture.md` + - `knowledge-base/active-sprint.md` +7. Skip any KB file that is clearly incomplete or still full of placeholders / `TODO:` content. +8. Use the loaded context to inform your plan. If the knowledge base conflicts with explicit instructions in the user's prompt, **the user's prompt takes precedence**. +9. Do **not** write to or modify any knowledge base file. + ## Multi-Repository Context {{PROJECT_NAME}} consists of separate repositories. When a feature involves changes across repos: diff --git a/claude/agents/knowledge-base-manager/README.md b/claude/agents/knowledge-base-manager/README.md new file mode 100644 index 0000000..6a9c142 --- /dev/null +++ b/claude/agents/knowledge-base-manager/README.md @@ -0,0 +1,86 @@ +# 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 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 + +- 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. + +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`: + +```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. | +``` + +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/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: + +``` +> 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..8c627dc --- /dev/null +++ b/claude/agents/knowledge-base-manager/knowledge-base-manager.md @@ -0,0 +1,203 @@ +--- +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 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 numbered-flat hybrid contract: + - entry file: `knowledge-base/00-master.md` + - sprint file: `knowledge-base/04-active-sprint.md` + - runtime config: `knowledge-base/.kb-config.yml` +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` +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 + +- `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` +- `update the architecture knowledge base` +- `update the risk model knowledge base` +- `update the business flows knowledge base` + +--- + +## 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 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.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. + +--- + +### Step 4b: Non-Sprint KB Edits + +If the user explicitly asks you to edit a Tier 1 or Tier 2 KB file: + +1. Detect the best available KB layout. +2. Update only the requested file(s). +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. + +--- + +### 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. +- 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 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.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. + +--- + +### Step 7: Report + +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 (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 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. +- **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. + +--- + +# Persistent Agent Memory + +You have a persistent memory directory at `.claude/agent-memory/knowledge-base-manager/` (relative to the project root). Its contents persist across conversations. + +Use it to track project-specific patterns — GitHub label conventions used for state detection, PR naming formats, recurring issue classifications — so your state detection improves over time. + +Guidelines: +- `MEMORY.md` is always loaded into your system prompt — lines after 200 will be truncated, so keep it concise +- Create separate topic files for detailed notes and link to them from MEMORY.md +- Organize memory semantically by topic, not chronologically +- Use the Write and Edit tools to update your memory files + +## MEMORY.md + +Your MEMORY.md is currently empty. As you work, record this project's GitHub label conventions, issue state detection patterns, and any recurring knowledge base structures you observe. diff --git a/knowledge-base/ADOPTION-GUIDE.md b/knowledge-base/ADOPTION-GUIDE.md new file mode 100644 index 0000000..f6decc5 --- /dev/null +++ b/knowledge-base/ADOPTION-GUIDE.md @@ -0,0 +1,134 @@ +# 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 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. +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 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. + +## 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 +- 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/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 new file mode 100644 index 0000000..ae171ad --- /dev/null +++ b/knowledge-base/GOVERNANCE.md @@ -0,0 +1,61 @@ +# Hybrid KB Governance + +## Ownership + +- 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 + +### Non-breaking changes +Examples: +- clarifying wording +- adding examples +- improving scripts without changing file contract +- adding optional Tier 2 modules in a backward-compatible way + +These can be released within the current major version. + +### Breaking changes +Examples: +- renaming required files +- changing `.kb-config.yml` required keys +- changing the required Tier 1 set +- changing the entry-point rule + +These require a new major KB contract version and an explicit migration note. + +## Versioning Rules + +- Current contract: `v1` +- Contract version is documented in `knowledge-base/SPEC.md` +- Downstream projects should pin to the contract they installed until they intentionally migrate + +## Approval Rules + +The following changes require maintainer review in `engineering-recipes`: +- changes to Tier 1 required files +- changes to the read contract +- 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 + +1. Review the spec diff first. +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. Run the KB validator after structural KB changes. + +## Recommended Maintainer Checklist + +- Is the change adding default token cost? +- Is the change backward-compatible with legacy projects where claimed? +- 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 new file mode 100644 index 0000000..5310ac3 --- /dev/null +++ b/knowledge-base/README.md @@ -0,0 +1,159 @@ +# Hybrid Knowledge Base + +This directory contains the V1 hybrid knowledge-base starter kit for project-local AI context. + +## What This Recipe Provides + +- 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 + +## Canonical V1 Layout + +New projects should use the numbered-flat layout below inside their own repo: + +```text +knowledge-base/ +├── 00-master.md +├── 01-business-flows.md +├── 02-architecture.md +├── 03-risk-model.md +├── 04-active-sprint.md +├── .kb-config.yml +├── 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-master.md` +- `01-business-flows.md` +- `02-architecture.md` +- `03-risk-model.md` +- `04-active-sprint.md` + +### Tier 2: Optional +- `advanced/decision-log.md` +- `advanced/incident-log.md` +- `advanced/feature-history.md` +- `advanced/integration-map.md` +- `advanced/metrics.md` +- `advanced/known-constraints.md` + +## Source of Truth + +- Runtime source of truth: `knowledge-base/.kb-config.yml` +- Human-facing adapter guidance: project root `CLAUDE.md` + +## Quick Start + +### One command scaffold + +```bash +python3 knowledge-base/scripts/scaffold_hybrid_kb.py /path/to/target-project \ + --enable decision-log,incident-log \ + --install-kb-manager \ + --install-kb-process +``` + +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 +python3 knowledge-base/scripts/validate_hybrid_kb.py /path/to/target-project +``` + +### Use the install prompt + +See [prompts/install-hybrid-kb.md](prompts/install-hybrid-kb.md). + +## Validation After Setup + +The starter kit copies `validate_hybrid_kb.py` into the target project's `knowledge-base/scripts/` directory. + +Run this from the target project root after installation: + +```bash +python3 knowledge-base/scripts/validate_hybrid_kb.py . +``` + +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 +- 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 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 + +- `00-master.md` stays small and cheap to read. +- 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: + +### 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` + +### Legacy flat +- `00-index.md` +- `business-flows.md` +- `architecture.md` +- `risks.md` +- `active-sprint.md` + +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 a reusable workflow file: +- [project-files/KB-PROCESS.md](project-files/KB-PROCESS.md) + +This is not part of the strict KB file contract, but it makes KB updates part of normal delivery. diff --git a/knowledge-base/REVIEW-CHECKLIST.md b/knowledge-base/REVIEW-CHECKLIST.md new file mode 100644 index 0000000..dbd467c --- /dev/null +++ b/knowledge-base/REVIEW-CHECKLIST.md @@ -0,0 +1,17 @@ +# Hybrid KB Review Checklist + +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? +- If automation changed, does it remain safe on repeated runs? +- If legacy support changed, is the compatibility impact documented? diff --git a/knowledge-base/SPEC-RECONCILIATION.md b/knowledge-base/SPEC-RECONCILIATION.md new file mode 100644 index 0000000..62032dc --- /dev/null +++ b/knowledge-base/SPEC-RECONCILIATION.md @@ -0,0 +1,77 @@ +# Hybrid KB Spec Reconciliation + +## Purpose + +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 | Older states | Hybrid V1 target | Decision | +|---|---|---|---| +| 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 | + +## Frozen Outcomes + +### Layout +- **Canonical:** numbered-flat layout. +- **Reason:** preserves scoped reads while keeping writes simple and reliable. + +### Entry file +- **Canonical:** `knowledge-base/00-master.md`. +- **Compatibility:** agents may still fall back to `knowledge-base/00-index.md` for older projects. + +### 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. + +### 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-flat hybrid contract. +- Generate `.kb-config.yml` and append KB rules to the project root `CLAUDE.md`. + +### 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 still support the layout. +- Migration can happen later by renaming files into the numbered-flat scheme. + +## Agent Behavior Differences + +| Agent | Older compatibility behavior | Hybrid V1 behavior | +|---|---|---| +| `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-flat layout +- Tier 1 and Tier 2 templates +- `.kb-config.yml` contract +- scaffold prompt and reusable scripts +- agent documentation updates +- KB validation helper + +Not implemented in this repo: +- direct migration of Sneha or IAGES repositories +- automatic sprint sync or scheduling diff --git a/knowledge-base/SPEC.md b/knowledge-base/SPEC.md new file mode 100644 index 0000000..543f299 --- /dev/null +++ b/knowledge-base/SPEC.md @@ -0,0 +1,199 @@ +# Hybrid KB Specification v1 + +## Status +- Version: `1` +- Date: `2026-03-07` +- State: `Current` + +## Goal + +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. +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. 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 + +```text +knowledge-base/ +├── 00-master.md +├── 01-business-flows.md +├── 02-architecture.md +├── 03-risk-model.md +├── 04-active-sprint.md +├── .kb-config.yml +├── 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-master.md` +- `01-business-flows.md` +- `02-architecture.md` +- `03-risk-model.md` +- `04-active-sprint.md` + +### Tier 2: Optional +- `advanced/decision-log.md` +- `advanced/incident-log.md` +- `advanced/feature-history.md` +- `advanced/integration-map.md` +- `advanced/metrics.md` +- `advanced/known-constraints.md` + +## File Ownership + +| File | Owner | Notes | +|---|---|---| +| `00-master.md` | Human | Keep concise; update when KB structure or project metadata changes | +| `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 + +### Entry-point rule +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. + +### Default loading map + +| Task | Files | +|---|---| +| 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.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. + +### Graceful degradation rule +If `knowledge-base/` or the entry file does not exist, agents proceed without KB-aware behavior. + +## Write Contract + +1. Only the designated KB maintenance flow may write automated updates. +2. This starter kit ships scaffold + validation only. +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. + +## `.kb-config.yml` Contract + +Minimum supported keys: +- `version` +- `project.name` +- `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 +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` + +New installs must use the numbered-flat layout. + +## Maintenance Cadence + +Recommended default: +- update Tier 1 when project reality changes +- 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 + +## Operational Workflow Expectations + +- every task should make an explicit KB impact decision +- 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 +2. IAGES backend pilot +3. Additional projects after contract validation + +## Review Checklist + +- Is the change Tier 1 or Tier 2? +- Does it increase default token cost? +- 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/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..6f9a4cb --- /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 + +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 new file mode 100644 index 0000000..265176d --- /dev/null +++ b/knowledge-base/prompts/install-hybrid-kb.md @@ -0,0 +1,109 @@ +# Install Hybrid Knowledge Base + +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 `https://github.com/anuragk16/engineering-recipes` repository into this project. + +Source directory to read from: +- `knowledge-base/templates/` +- `knowledge-base/templates/advanced/` +- `knowledge-base/templates/.kb-config.yml` +- `knowledge-base/templates/CLAUDE.section.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` +- `claude/agents/knowledge-base-manager/README.md` + +Follow these steps exactly: + +1. Explore this project shallowly: + - README + - top-level config files + - 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 which files already exist, which are missing, and whether this looks like a partial install. + - Ask how to proceed before making changes. +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 + - 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. +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` + - `advanced/feature-history.md` + - `advanced/integration-map.md` + - `advanced/metrics.md` + - `advanced/known-constraints.md` +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 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. + - Use `--install-kb-manager` if this project uses Claude agents. + - 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` + - `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. 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. +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. +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. +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. +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 + - placeholders left unresolved + - 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 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 new file mode 100644 index 0000000..75592f1 --- /dev/null +++ b/knowledge-base/scripts/scaffold_hybrid_kb.py @@ -0,0 +1,246 @@ +#!/usr/bin/env python3 +from __future__ import annotations + +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", + "02-architecture.md", + "03-risk-model.md", + "04-active-sprint.md", + ".kb-config.yml", +] +ADVANCED_MAP = { + "decision-log": "advanced/decision-log.md", + "incident-log": "advanced/incident-log.md", + "feature-history": "advanced/feature-history.md", + "integration-map": "advanced/integration-map.md", + "metrics": "advanced/metrics.md", + "known-constraints": "advanced/known-constraints.md", +} +OPTIONAL_PROJECT_FILES = { + "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: + if dest.exists() and not overwrite: + return f"skip {dest}" + dest.parent.mkdir(parents=True, exist_ok=True) + shutil.copy2(src, dest) + return f"write {dest}" + + +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" + 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(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_enabled = True + new_lines.append("enabled_tier2:") + if enabled: + for module in enabled: + new_lines.append(f" - {module}") + else: + new_lines.append(" # Add optional module keys here when enabled for the project.") + continue + if in_enabled: + if stripped.startswith("-") or stripped.startswith("#"): + continue + if stripped and not line.startswith(" "): + in_enabled = False + else: + continue + + if stripped == "incident_response:" and line.startswith(" "): + in_incident = True + new_lines.append(line) + 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}" + + +def main() -> int: + parser = argparse.ArgumentParser(description="Scaffold the hybrid knowledge base into a target project") + parser.add_argument("project_root", help="Path to the target project root") + parser.add_argument( + "--enable", + default="", + 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-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() + if not project_root.exists(): + print(f"error: project root not found: {project_root}", file=sys.stderr) + return 1 + + kb_root = project_root / "knowledge-base" + (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] + if unknown: + print(f"error: unknown Tier 2 modules: {', '.join(unknown)}", file=sys.stderr) + return 1 + + token_replacements = { + "{{LAST_REVIEWED_DATE}}": date.today().isoformat(), + } + actions: list[str] = [] + for rel in CORE_FILES: + 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] + 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_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.extend(ensure_claude_guidance(project_root, args.install_kb_manager)) + + print("Hybrid KB scaffold summary:") + for action in actions: + 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"- 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 + + +if __name__ == "__main__": + raise SystemExit(main()) diff --git a/knowledge-base/scripts/validate_hybrid_kb.py b/knowledge-base/scripts/validate_hybrid_kb.py new file mode 100644 index 0000000..7b4bc70 --- /dev/null +++ b/knowledge-base/scripts/validate_hybrid_kb.py @@ -0,0 +1,537 @@ +#!/usr/bin/env python3 +from __future__ import annotations + +import argparse +import re +from collections import defaultdict +from datetime import date +from pathlib import Path + +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", + "knowledge-base/03-risk-model/00-index.md", + "knowledge-base/04-active-sprint/00-index.md", + "knowledge-base/.kb-config.yml", +] +LEGACY_FLAT_REQUIRED = [ + "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", +] +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", + "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", +} +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", +] +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 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 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 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" + 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 + + +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_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 [], 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}") + + 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", 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", 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", 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", 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" + ) + + 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 + + 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 + + +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..daa0df3 --- /dev/null +++ b/knowledge-base/templates/.kb-config.yml @@ -0,0 +1,55 @@ +version: 1 +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: + 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: + - 00-master.md + - 01-business-flows.md + - 02-architecture.md + - 03-risk-model.md + - 04-active-sprint.md + incident_response: + - 03-risk-model.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: + - 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 new file mode 100644 index 0000000..f50bb46 --- /dev/null +++ b/knowledge-base/templates/00-master.md @@ -0,0 +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}} + +## Purpose + +Single entry point for the project knowledge base. Agents always read this file first, then load only the KB files needed for the task. + +## 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 new file mode 100644 index 0000000..0410da7 --- /dev/null +++ b/knowledge-base/templates/01-business-flows.md @@ -0,0 +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}} + +## Purpose + +Capture the user-facing flows, business rules, approvals, and glossary terms that engineering and QA should not rediscover from code alone. + +## 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_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}} + +### 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 new file mode 100644 index 0000000..c1495df --- /dev/null +++ b/knowledge-base/templates/02-architecture.md @@ -0,0 +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}} + +## 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}} | + +### Ownership boundaries + +| 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}} | + +### Integration points + +| System | Purpose | Contract | Notes | +|---|---|---|---| +| {{SYSTEM_1}} | {{PURPOSE_1}} | {{CONTRACT_1}} | {{NOTES_4}} | + +### 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 new file mode 100644 index 0000000..acaecd4 --- /dev/null +++ b/knowledge-base/templates/03-risk-model.md @@ -0,0 +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}} + +## Purpose + +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 | + +### Fragile areas + +| Area | Known issue pattern | Mitigation | +|---|---|---| +| {{AREA_1}} | {{PATTERN_1}} | {{MITIGATION_1}} | + +### Example + +- 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. + +## 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 + +- 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 new file mode 100644 index 0000000..cab0f33 --- /dev/null +++ b/knowledge-base/templates/04-active-sprint.md @@ -0,0 +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}} + +## Purpose + +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 + +| 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}} | + +### 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 new file mode 100644 index 0000000..0595566 --- /dev/null +++ b/knowledge-base/templates/CLAUDE.section.md @@ -0,0 +1,21 @@ +## Knowledge Base + +This project stores structured context in `knowledge-base/`. + +### Reading Rules +- 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 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 new file mode 100644 index 0000000..81bc92a --- /dev/null +++ b/knowledge-base/templates/README.md @@ -0,0 +1,36 @@ +# Templates + +These templates are copied into downstream projects. + +## Core templates +- `00-master.md` +- `01-business-flows.md` +- `02-architecture.md` +- `03-risk-model.md` +- `04-active-sprint.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 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. +- 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 new file mode 100644 index 0000000..47fc738 --- /dev/null +++ b/knowledge-base/templates/advanced/decision-log.md @@ -0,0 +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 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 + +### {{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 new file mode 100644 index 0000000..819b20d --- /dev/null +++ b/knowledge-base/templates/advanced/feature-history.md @@ -0,0 +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 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 new file mode 100644 index 0000000..af5841c --- /dev/null +++ b/knowledge-base/templates/advanced/incident-log.md @@ -0,0 +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 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 new file mode 100644 index 0000000..d2642a4 --- /dev/null +++ b/knowledge-base/templates/advanced/integration-map.md @@ -0,0 +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 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 new file mode 100644 index 0000000..b3e84e9 --- /dev/null +++ b/knowledge-base/templates/advanced/known-constraints.md @@ -0,0 +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 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 new file mode 100644 index 0000000..1d504ef --- /dev/null +++ b/knowledge-base/templates/advanced/metrics.md @@ -0,0 +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 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 |