You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
@codeassembly/kb can validate and manage stores but cannot create one. The only provisioning today is provision-codeassembly-event-store.sh, a bespoke bash script hardcoded to a single store (codeassembly) and living in a consumer package rather than the library. "Copy the script and edit the hardcoded name" is exactly the drift-prone pattern this effort exists to remove, and the script has already drifted from the package: it installs a schema template that diverges from the package's own defaultSchema (with extra event fields no code reads), and it registers stores with hand-rolled awk/grep that requires kbs: to be the last top-level key.
Context
The package already holds the canonical sources a create command needs:
defaultSchema is the bundled schema every store inherits when it declares no .kb/schema.yaml; the static template under agents/templates/ is a second, drifted copy.
defaultKbConfig supplies the effective .kb/config.yaml defaults; config.yaml field-merges, so a store works with the file absent.
tag-aliases.yaml is optional and additive; absent, it loads as an empty map.
The kb.yaml registry has a typed schema and loader but no write path — registration is genuinely new.
A store's .kb/schema.yaml replaces the bundled default outright (no merge), so a store that wants to customize its schema needs the full default in hand to edit. That is why kb create materializes a schema seed rather than leaving the store to inherit silently. The generic kb-* skills hardcode the record types and required fields they read and write, so the materialized seed must faithfully reproduce the default record types; validating edited schemas against that skill contract is tracked separately in #746.
Two layout facts constrain the scaffold: capture-event writes events to a fixed content/events/, while kb-add writes assertions to an agent-chosen topical folder under content/. There is no content/assertions/ convention.
Proposed solution
Add a kb create command, available as both a CLI subcommand and a library export consistent with check, that scaffolds a new store in the current directory and registers it:
Scaffold .kb/schema.yaml (serialized from defaultSchema, with a header explaining the override-and-inherit contract and warning against removing the default record types or required fields), .kb/config.yaml (a fully-commented stub whose documented defaults are rendered from defaultKbConfig), .kb/tag-aliases.yaml (an empty aliases: {} skeleton with guidance), and the content/ and content/events/ directories. Stub values are generated from the in-package constants so they cannot drift.
Register the store in ~/.agents/kb.yaml through kb-core's registry schema, preserving existing comments. The name defaults to the directory name; --name overrides it and --no-register scaffolds without registering.
Refuse to clobber: an existing .kb/ or an already-registered name is an error, not an overwrite. No --force for now.
Retire the bespoke script and the drifted template: delete provision-codeassembly-event-store.sh and the agents/templates/codeassembly-event-store/ template, whose behavior kb create now covers from the package's canonical sources.
Dropped from the original scope: parameterizing the schema by record-type set (no current store needs a restricted vocabulary; an over-broad schema is inert, and the "both" case is just the inherited default), and scaffolding a .kb/templates/ directory (no code reads it).
Acceptance criteria
Must have
kb create scaffolds a new store: .kb/schema.yaml, .kb/config.yaml, .kb/tag-aliases.yaml, and the content/ and content/events/ directories.
The scaffolded schema.yaml, config.yaml, and tag-aliases.yaml are generated from the in-package constants and parse back to defaultSchema, defaultKbConfig, and an empty alias map respectively.
The store is registered in ~/.agents/kb.yaml through kb-core's registry schema, preserving existing comments; --name and --no-register are supported.
kb create refuses to clobber: an existing .kb/ or an already-registered name produces an error rather than an overwrite.
provision-codeassembly-event-store.sh and the agents/templates/codeassembly-event-store/ template are removed.
kb create is available as both a CLI subcommand and a library export, consistent with check.
New and modified behavior is covered by tests.
kb help text and the package README document kb create, its flags, and the scaffolded layout.
Problem
@codeassembly/kbcan validate and manage stores but cannot create one. The only provisioning today isprovision-codeassembly-event-store.sh, a bespoke bash script hardcoded to a single store (codeassembly) and living in a consumer package rather than the library. "Copy the script and edit the hardcoded name" is exactly the drift-prone pattern this effort exists to remove, and the script has already drifted from the package: it installs a schema template that diverges from the package's owndefaultSchema(with extra event fields no code reads), and it registers stores with hand-rolled awk/grep that requireskbs:to be the last top-level key.Context
The package already holds the canonical sources a create command needs:
defaultSchemais the bundled schema every store inherits when it declares no.kb/schema.yaml; the static template underagents/templates/is a second, drifted copy.defaultKbConfigsupplies the effective.kb/config.yamldefaults;config.yamlfield-merges, so a store works with the file absent.tag-aliases.yamlis optional and additive; absent, it loads as an empty map.kb.yamlregistry has a typed schema and loader but no write path — registration is genuinely new.A store's
.kb/schema.yamlreplaces the bundled default outright (no merge), so a store that wants to customize its schema needs the full default in hand to edit. That is whykb creatematerializes a schema seed rather than leaving the store to inherit silently. The generickb-*skills hardcode the record types and required fields they read and write, so the materialized seed must faithfully reproduce the default record types; validating edited schemas against that skill contract is tracked separately in #746.Two layout facts constrain the scaffold:
capture-eventwrites events to a fixedcontent/events/, whilekb-addwrites assertions to an agent-chosen topical folder undercontent/. There is nocontent/assertions/convention.Proposed solution
Add a
kb createcommand, available as both a CLI subcommand and a library export consistent withcheck, that scaffolds a new store in the current directory and registers it:.kb/schema.yaml(serialized fromdefaultSchema, with a header explaining the override-and-inherit contract and warning against removing the default record types or required fields),.kb/config.yaml(a fully-commented stub whose documented defaults are rendered fromdefaultKbConfig),.kb/tag-aliases.yaml(an emptyaliases: {}skeleton with guidance), and thecontent/andcontent/events/directories. Stub values are generated from the in-package constants so they cannot drift.~/.agents/kb.yamlthrough kb-core's registry schema, preserving existing comments. The name defaults to the directory name;--nameoverrides it and--no-registerscaffolds without registering..kb/or an already-registered name is an error, not an overwrite. No--forcefor now.provision-codeassembly-event-store.shand theagents/templates/codeassembly-event-store/template, whose behaviorkb createnow covers from the package's canonical sources.Dropped from the original scope: parameterizing the schema by record-type set (no current store needs a restricted vocabulary; an over-broad schema is inert, and the "both" case is just the inherited default), and scaffolding a
.kb/templates/directory (no code reads it).Acceptance criteria
Must have
kb createscaffolds a new store:.kb/schema.yaml,.kb/config.yaml,.kb/tag-aliases.yaml, and thecontent/andcontent/events/directories.schema.yaml,config.yaml, andtag-aliases.yamlare generated from the in-package constants and parse back todefaultSchema,defaultKbConfig, and an empty alias map respectively.~/.agents/kb.yamlthrough kb-core's registry schema, preserving existing comments;--nameand--no-registerare supported.kb createrefuses to clobber: an existing.kb/or an already-registered name produces an error rather than an overwrite.provision-codeassembly-event-store.shand theagents/templates/codeassembly-event-store/template are removed.kb createis available as both a CLI subcommand and a library export, consistent withcheck.kbhelp text and the package README documentkb create, its flags, and the scaffolded layout.Dependencies
kb checkCLI/config surface,.kb/config.yaml, and the registry schema/loader) and Relocate substrate event records to content/events/ and document the fix-tag convention #716 (thecontent/events/layout and the record-type-aware schema).