kb

name	kb
description	Manage long-lived `.sopify/` knowledge, including bootstrap, progressive materialization, reads, retention, and knowledge_sync policy.

Knowledge Base Management

KB owns long-lived knowledge. It does not make Analyze, Design, or Develop decisions, and it does not manage the active plan, handoff, receipts, or finalize directly. Document structures come from Templates; protocol state is managed through sopify_writer.

Directory responsibilities

.sopify/
├── project.md              # reusable technical conventions
├── user/                   # long-term preferences and raw feedback
├── blueprint/              # long-term goals, design boundaries, open work, and index
├── plan/                   # current plan semantic files
├── history/                # archived plans and index
└── state/                  # local protocol state

blueprint/README.md keeps only status, maintenance guidance, current goal, current focus, and reading links. Put detailed content in the relevant blueprint file.

Bootstrap and progressive materialization

kb_init: full creates project.md, user/preferences.md, user/feedback.jsonl, and the four blueprint files on first use. It does not pre-create plan content, history, or empty directories.

kb_init: progressive is the default:

• First real project use: create project.md, user/preferences.md, and blueprint/README.md.
• First plan lifecycle: add blueprint/background.md, blueprint/design.md, blueprint/tasks.md, and the current plan directory.
• First explicit ~go finalize: let the protocol flow create history/index.md and the archive directory.
• First explicit long-term feedback: create user/feedback.jsonl when needed.

Knowledge context reads

The host completes the governing Protocol entry for a managed plan, handoff, and receipts before invoking KB. This section defines only KB's long-lived context order:

1. project.md
2. user/preferences.md
3. blueprint/README.md
4. Relevant parts of blueprint/background.md, design.md, and tasks.md

Consult and quick fix do not fail when deep blueprint files are absent. Read history/ only for trace-back or finalize.

Retention and updates

Keep information only when it remains useful across tasks:

• project.md: reusable technical conventions.
• background.md: long-term goals, scope, and non-goals.
• design.md: module, host, directory, and consumption contracts.
• tasks.md: unfinished long-term work and explicit deferrals with a revisit condition.
• preferences.md: explicit long-term user preferences.

Do not store one-off implementation details, current-plan task breakdowns, temporary tradeoffs, completed tasks, or copies of history content. When code and documentation conflict, verify the code and then correct the documentation. Current user instructions override historical preferences.

knowledge_sync

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

• skip: do not inspect that file for this plan.
• review: decide whether it needs an update before finalize.
• required: update it before the delivery candidate; block finalize while incomplete.

KB applies the plan's sync policy without changing the plan lifecycle. Update the narrowest long-lived location and avoid duplicating the same content across files.

Output

After bootstrap or sync, state the actual result, list Changes, and end with Next:. Use Changes: 0 files when nothing changed.