name	kb
description	Complete knowledge base management rules; read when ~init command or knowledge base missing; includes creation, synchronization, audit, context acquisition rules

Knowledge Base Management - Complete Rules

Knowledge Base Architecture

File Structure:

helloagents/              # HelloAGENTS workspace (SSOT)
├── CHANGELOG.md          # Version history (Keep a Changelog)
├── project.md            # Technical conventions
├── wiki/                 # Core documentation
│   ├── overview.md       # Project overview
│   ├── arch.md           # Architecture design
│   ├── api.md            # API manual
│   ├── data.md           # Data models
│   └── modules/<module>.md
├── plan/                 # Change workspace
│   └── YYYYMMDDHHMM_<feature>/
│       ├── why.md        # Change proposal
│       ├── how.md        # Technical design
│       └── task.md       # Task list
└── history/              # Completed changes archive
    ├── index.md
    └── YYYY-MM/YYYYMMDDHHMM_<feature>/

Path Conventions:

In this ruleset, plan/, wiki/, history/ all refer to complete paths under helloagents/
All knowledge base files MUST be created under the helloagents/ directory

Core Terminology Details

SSOT (Single Source of Truth): Single source of truth (knowledge level), refers to knowledge base
- Note: When SSOT conflicts with code, SSOT is considered "outdated" and needs updating based on code (execution facts)
Knowledge Base: Complete project documentation collection (CHANGELOG.md, project.md, wiki/*)
EHRB (Extreme High-Risk Behavior): Extreme high-risk behavior
ADR (Architecture Decision Record): Architecture decision record
MRE (Minimal Reproducible Example): Minimal reproducible example
Solution Package: Complete solution unit
- Directory structure: YYYYMMDDHHMM_<feature>/
- Required files: why.md + how.md + task.md
- Completeness check: Required files exist, non-empty, task.md has at least 1 task item

Quality Check Dimensions

Completeness: Whether required files and sections exist
Format: Whether Mermaid charts/Markdown format is correct
Consistency: Whether API signatures/data models consistent with code
Security: Whether contains sensitive information (keys/PII)

Issue Grading:

Minor (can continue): Missing non-critical files, non-standard format, outdated descriptions
Severe (needs handling): Core files missing, seriously out of sync (>30%), contains sensitive information

Project Context Acquisition Strategy

**Step 1: Check knowledge base first (if exists)** - Core files: `project.md`, `wiki/overview.md`, `wiki/arch.md` - Select as needed: `wiki/modules/.md`, `wiki/api.md`, `wiki/data.md`

Step 2: Knowledge base doesn't exist/insufficient info → Comprehensive codebase scan

Use Glob to get file structure
Use Grep to search key information
Acquire: Architecture, tech stack, module structure, technical constraints

Knowledge Base Synchronization Rules

**Trigger Timing:** After code changes, MUST immediately synchronize knowledge base updates

Step 1 - Module Specification Update:

Read current solution package plan/YYYYMMDDHHMM_<feature>/why.md Core Scenarios section (read before migration)
Extract requirements and scenarios (requirements need to mark owning module)
Update wiki/modules/<module>.md Specifications section
- Does not exist → Append
- Already exists → Update

Step 2 - Update by Change Type:

API changes → Update wiki/api.md
Data model changes → Update wiki/data.md
Architecture changes/new modules → Update wiki/arch.md
Module index changes → Update wiki/overview.md
Technical convention changes → Update project.md

Step 3 - ADR Maintenance (if includes architecture decisions):

Extract ADR information (read from plan/YYYYMMDDHHMM_<feature>/how.md Architecture Decision ADR section before migration)
Append to Major Architecture Decisions table in wiki/arch.md
Link to history/YYYY-MM/YYYYMMDDHHMM_<feature>/how.md#adr-xxx
Note: The history/ link written at this time is a pre-calculated path

Step 4 - Cleanup:

Delete outdated information, deprecated APIs, removed modules

Step 5 - Defect Retrospective (fix scenario specific):

Add "Known Issues" or "Notes" in module documentation
Record root cause, fix solution, prevention measures

Knowledge Base Missing Handling

**STEP 1: Check if core files exist** - `CHANGELOG.md`, `project.md`, `wiki/*.md`

STEP 2: Knowledge base does not exist Handle by phase:

Requirements Analysis Phase:
  - Only flag issue, don't create knowledge base
  - Prompt in summary "Knowledge base missing, recommend executing ~init command first"

Solution Design/Development Implementation Phase:
  - Comprehensively scan codebase and create complete knowledge base:
    - Root directory: CHANGELOG.md, project.md
    - wiki/: overview.md, arch.md, api.md, data.md
    - wiki/modules/: <module>.md (each module)
    - Large projects (determined per G4) batch process (≤20 modules per batch)

STEP 3: Knowledge base exists

Execute quality pre-check:
  Severe issues → Comprehensively scan and rebuild (Solution Design/Development Implementation phase)
  Minor issues → Continue flow

Legacy Solution Handling

User Selection Migration Flow

**Applicable Scenario:** Batch processing flow after user responds "confirm migration"

Step 1 - User selects migration scope:

List all legacy solution packages, ask user to choose:

Detected X legacy solution packages, please select migration method:
- Enter "all" → Migrate all legacy solution packages
- Enter solution package numbers (e.g., 1, 1,3, 1-3) → Migrate specified solution packages
- Enter "cancel" → Keep all legacy solution packages

Solution package list:
[1] 202511201300_logout
[2] 202511201400_profile
[3] 202511201500_settings

User Response Handling:

"all" → Migrate all
Single number (e.g., 1) → Migrate 1st
Multiple numbers (e.g., 1,3) → Migrate specified
Number range (e.g., 1-3) → Migrate 1st to 3rd
"cancel" → Keep all
Other input → Ask again

Step 2 - Migrate selected solution packages one by one:

for each selected solution package:
  1. Update task status: All task statuses update to [-]
     Add at top: > **Status:** Not executed (user cleanup)

  2. Migrate to history directory:
     - Move from plan/ to history/YYYY-MM/
     - YYYY-MM extracted from solution package directory name
     - Name conflict: Force overwrite

  3. Update history index: history/index.md (mark "not executed")

Step 3 - Output migration summary:

✅ Migrated X solution packages to history/:
  - 202511201300_logout → history/2025-11/202511201300_logout/
  - 202511201500_settings → history/2025-11/202511201500_settings/
📦 Remaining Y solution packages kept in plan/:
  - 202511201400_profile

Legacy Solution Scan and Reminder Mechanism

**Trigger Timing:** - After solution package creation: Solution Design complete, Planning command complete, Lightweight iteration complete - After solution package migration: Development Implementation complete, Execution command complete, Full authorization command complete

Scan Logic:

Scan all solution package directories under plan/ directory
Exclude solution package executed this time (read CURRENT_PACKAGE variable)
Clear CURRENT_PACKAGE variable
Remaining solution packages are legacy solutions

Output Position: Auto-inject to end slot of G6.1 output format

Output Format:

📦 plan/Legacy Solutions: Detected X legacy solution packages ([list]), do you need to migrate to history?

List format: YYYYMMDDHHMM_ (one per line, max 5, show "...and X more" if exceeds)

User Response:

Confirm migration → Execute batch migration flow
Refuse/ignore → Keep in plan/ directory

~init / ~wiki Command Completion Summary Format

Strictly follow G6.1 unified output format:

✅【HelloAGENTS】- Knowledge Base Command Complete

- 📚 Knowledge base status: [Created/Updated/Rebuilt]
- 📊 Operation summary: Scanned X modules, created/updated Y documents
- 🔍 Quality check: [Check results, if issues exist]

────
📁 Changes:
  - {knowledge base files}
  - helloagents/CHANGELOG.md
  - helloagents/project.md
  ...

🔄 Next Steps: Knowledge base operation complete, can proceed with other tasks

kb

Install Skill

SKILL.md