Skip to content

knowledge-workflow.md

Latest commit

 

History

History
211 lines (161 loc) · 7.35 KB

knowledge-workflow.md

File metadata and controls

211 lines (161 loc) · 7.35 KB
Raw

Knowledge workflow

The @ui-engine/knowledge package treats reusable lessons as code. Records, playbooks, and skill drafts live as markdown under packages/knowledge/. A small CLI (ui-engine-knowledge) validates the schema, generates record stubs, exports skill drafts, and provides offline semantic retrieval over the corpus.

Hierarchy

packages/knowledge/
├── records/        atomic lessons; one markdown file per lesson
├── playbooks/      curated workflows that cite proven records
├── skill-drafts/   Codex-skill-ready folders that cite records
└── .knowledge-index/   embeddings cache (gitignored, regenerable)
  • A record is the smallest unit. It captures one observation, one rule, and the procedure + evidence that justify it.
  • A playbook turns one or more proven records into a workflow an agent can follow without re-deriving the rules.
  • A skill draft is a folder containing SKILL.md (with name + description frontmatter) plus any supporting files. It must cite at least one record.

Record schema

Every record has YAML frontmatter and six required H2 sections.

---
id: kg-YYYYMMDD-<slug>          # required, unique
date: YYYY-MM-DD                # required
area: asset-generation | slicing | ui-composition | canvas-engine | verification
type: lesson | failure | prompt-pattern | decision | workflow
status: experimental | proven | deprecated
applies_to:                     # required; free-form strings
  - <path-or-concept>
promote_to:                     # required; "playbook:<slug>" or "skill:<slug>"
  - playbook:<slug>
verification:                   # required; commands or browser checks
  - npm run knowledge:check
tags:                           # optional; cross-cutting labels
  - <tag>
applies_to_genres:              # optional; e.g. [turn-based]
  - turn-based
applies_to_themes:              # optional; e.g. [roman-spqr]
  - roman-spqr
applies_to_packages:            # optional; package slugs without scope
  - theme-roman-spqr
---

Required sections, in order: Context, Observation, Rule, Procedure, Evidence, Skill Note.

status: proven requires at least one entry under verification:.

applies_to_packages entries must reference existing packages under packages/* (validation reads each packages/*/package.json name field and strips the @ui-engine/ scope).

A record with the optional fields present but all four left empty triggers a WARN ("likely under-categorized"). Fill at least one of tags, applies_to_genres, applies_to_themes, or applies_to_packages.

Tag vocabulary

Used in the M2 backfill — extend as needed and document new tags here.

Tag When to use
verification Captures evidence about how to verify changes (browser, build, screenshots).
browser Lesson is browser-specific (rendering, computed styles, viewport).
ai-prompt Affects prompts sent to image-gen / LLM systems.
agent-workflow Rule that AI agents (or human collaborators) should apply during their workflow — e.g., verification gates, hand-off protocols.
chroma-key Touches green-screen / chroma-key alpha workflows.
slicing Touches the slicer pipeline (scripts/hud-assets/*).
asset-generation Touches assets/*_generated_*.png or prompt templates.
9-slice Touches 9-slice composition or skin definitions.
ui-composition Touches how widgets compose, layout, or overlay.
layout Touches layout math (safe zones, paddings, breakpoints).
live-text Touches HTML/canvas live text rendered over generated art.
react React-only concern (not the canvas widgets).
deferred Lesson is about deliberately disabling broken work.
fallback Documents a deterministic fallback used in place of an asset.

Common tasks

Add a new record

npm run knowledge:new -- <slug>

Creates packages/knowledge/records/kg-YYYYMMDD-<slug>.md from the stub. Edit the frontmatter and sections. Set status: experimental until a verification command or browser check is recorded.

Validate the corpus

npm run knowledge:check

Runs all schema checks and cross-reference checks. Exits non-zero on any error. Warnings (e.g., under-categorized records) print but do not fail.

Build / refresh the embeddings index

npm run knowledge:index

Walks records, playbooks, and skill drafts, generates a 384-dimensional embedding per entry with Xenova/all-MiniLM-L6-v2, and writes the cache to packages/knowledge/.knowledge-index/embeddings.json. Run this whenever record or playbook bodies change. The cache is gitignored.

Semantic retrieval

npm run knowledge:retrieve -- "<query>"

Loads the cached index, embeds the query with the same model, and prints the top-K matches by cosine similarity. Defaults to top-5; override with --top-k <n>. Filter by entry type with --types record,playbook,skill.

Example:

$ npm run knowledge:retrieve -- "chroma key removal"

Query: chroma key removal

rank  score   type      id
-----------------------------------------------------------
   1  0.4106  record    kg-20260514-mission-banner-chroma-derived
        title: mission banner chroma derived
        path:  packages/knowledge/records/kg-20260514-mission-banner-chroma-derived.md
   2  0.3690  record    kg-20260514-decision-card-frame-assets
   ...

Programmatic equivalent for agents:

import { retrieve } from '@ui-engine/knowledge';

const hits = await retrieve('chroma key removal', { topK: 3 });

Index lifecycle

The index is purely derivative — it depends on every markdown body and on the embedding model, but on nothing else.

  • Regenerate after editing any record, playbook, or skill draft body.
  • Regenerate after upgrading @xenova/transformers or switching models.
  • The cache directory packages/knowledge/.knowledge-index/ is gitignored. Whether to commit the cache is an open question (see plan §Open questions). Default: do not commit.

Export skill drafts to .tmp/

npm run knowledge:export-skills

Validates first, then copies each skill-drafts/<name>/ into .tmp/knowledge-skills/<name>/, plus a manifest.json. Lets you preview or manually install the skills without making $CODEX_HOME the source of truth.

Capture from a session (placeholder)

npm run knowledge:capture -- --from-conversation <file>

Currently a stub. The intent is to consume a conversation summary and emit a record draft. Tracked as future work; see plan §Future.

CLI reference

The package exposes a single binary, ui-engine-knowledge, with subcommands:

ui-engine-knowledge check                   Validate the corpus.
ui-engine-knowledge new <slug>              Create a record stub.
ui-engine-knowledge retrieve "<query>"      Top-K semantic search.
ui-engine-knowledge index                   Build / refresh embeddings.
ui-engine-knowledge export-skills           Stage skill drafts to .tmp/.
ui-engine-knowledge capture --from-conversation <file>
                                            Stub: not yet implemented.

Common flags: --knowledge-dir <dir>, --json, --top-k <n>, --types record,playbook,skill.

Library surface

import {
  retrieve,
  buildIndex,
  validateKnowledge,
  createRecordStub,
} from '@ui-engine/knowledge';

See packages/knowledge/src/index.ts for the full export list and types.