kb - SKILL.md Agent Skill

name: kb description: Knowledge base management skill; read during KB operations; includes init, update, sync strategies

Knowledge Base Management - V2 Rules

Goal: manage the V2 layers in .sopify/ so long-lived knowledge, the active plan, and finalized archives stay clearly separated.

Knowledge Base Structure

.sopify/
├── blueprint/
│   ├── README.md           # Pure index page with index-required sections only
│   ├── background.md       # Long-term goals, scope, non-goals
│   ├── design.md           # Module / host / directory / consumption contracts
│   └── tasks.md            # Unfinished long-term items and explicit deferrals
├── project.md              # Project technical conventions
├── user/
│   ├── preferences.md      # Long-term user preferences
│   └── feedback.jsonl      # Raw feedback events
├── plan/
│   └── YYYYMMDD_feature/   # Current active plan
├── history/
│   ├── index.md            # Archive index
│   └── YYYY-MM/
└── state/                  # Runtime machine truth

Initialization Strategy

Full mode (`kb_init: full`)

Create on the first bootstrap:

Create:
  - .sopify/project.md
  - .sopify/user/preferences.md
  - .sopify/user/feedback.jsonl
  - .sopify/blueprint/README.md
  - .sopify/blueprint/background.md
  - .sopify/blueprint/design.md
  - .sopify/blueprint/tasks.md

Notes:

Do not pre-create plan/ content.
Do not pre-create history/index.md or any archive.

Progressive mode (`kb_init: progressive`) [default]

Materialize by lifecycle:

First real-project trigger:
  - .sopify/project.md
  - .sopify/user/preferences.md
  - .sopify/blueprint/README.md

First plan lifecycle:
  - .sopify/blueprint/background.md
  - .sopify/blueprint/design.md
  - .sopify/blueprint/tasks.md
  - .sopify/plan/YYYYMMDD_feature/

First explicit ~go finalize:
  - .sopify/history/index.md
  - .sopify/history/YYYY-MM/YYYYMMDD_feature/

First explicit long-term preference:
  - .sopify/user/feedback.jsonl

Read Order

project.md
user/preferences.md
blueprint/README.md
blueprint/background.md
blueprint/design.md
blueprint/tasks.md
active_plan = current_plan.path + current_plan.files

Rules:

consult / clarification routes prefer L0/L1 and must not require deep blueprint files
planning / develop may enter L2 active plan
history/ is not the default long-lived context source; read it only for finalize lookups or human traceability

Update Rules

L0 Index Guardrails

blueprint/README.md keeps only status / maintenance / current goal / current focus / read next.
Do not write absolute workspace paths, long-form architecture prose, or formal contract bodies into blueprint/README.md.
If extra long-lived topic docs exist at the blueprint/ root, blueprint/README.md must list them explicitly.

`blueprint/tasks.md` Boundaries

Keep only unfinished long-term items and explicit deferrals.
[x] completed items must not remain in blueprint/tasks.md.

Must update

project.md: reusable technical conventions changed
blueprint/background.md: long-term goals, scope, or non-goals changed
blueprint/design.md: module, host, directory, or consumption contracts changed
blueprint/tasks.md: unfinished long-term items or explicit deferrals changed
user/preferences.md: the user explicitly stated a long-term preference

Must not be written into long-lived knowledge

one-off implementation details
short-term task breakdown from the current plan
temporary tradeoffs that belong only to this task
completed task checklists lingering in blueprint/tasks.md
copying history body text back into blueprint

`knowledge_sync` Sync Contract

knowledge_sync:
  project: skip|review|required
  background: skip|review|required
  design: skip|review|required
  tasks: skip|review|required

Execution rules:

skip: no sync required for this round
review: at least review before finalize
required: finalize must block until updated

Conflict Handling

code vs docs: code is the source of truth, then update docs
current task vs long-term preference: current explicit task > user/preferences.md > default rules

Output Format

Initialization complete:

[{BRAND_NAME}] Knowledge Base Init ✓

Created: {N} files
Strategy: {full/progressive}

---
Changes: {N} files
  - .sopify/project.md
  - .sopify/blueprint/README.md
  - ...

Next: KB is ready

Sync complete:

[{BRAND_NAME}] Knowledge Base Sync ✓

Updated: {N} files

---
Changes: {N} files
  - .sopify/project.md
  - .sopify/blueprint/design.md
  - ...

Next: Docs updated

kb