Kyber

Helmsman framework for agent-driven planning, tasks, roadmaps, and project context. Framework source: theBull/kyber (main).

Framework vs consumer — sibling only

Two different things share the word “kyber”:

	Path	Git repo	Contains
Framework	~/Development/kyber/ (sibling)	theBull/kyber	framework/, .agents/skills/
Consumer instance	<project>/.kyber/ (inside project)	your project repo	library/, config/

Do not clone the framework repo into <project>/.kyber/ — that path is reserved for generated context in the project repo. Nesting collides names and git ownership; one framework clone cannot serve multiple projects.

~/Development/
  kyber/           ← clone framework here (once)
  my-app/.kyber/    ← instance data only (library/, config/)
  other-app/.kyber/

Setup

git clone git@github.com:theBull/kyber.git ~/Development/kyber   # sibling, not inside the project
git clone <your-project-remote> ~/Development/my-app

Open a multi-root workspace — add both the consumer project and kyber as folders (e.g. my-app.code-workspace with ../kyber).

Layout

This repo (framework):

framework/
  modules/
    core/ lifecycle/ rice/ library/ plan/ task/ initiative/ roadmap/
    extensions/ config/ doctor/ business/
  README.md

Consumer (<project>/.kyber/):

library/
  plan/ task/ initiative/ strategy/   # active artifacts (flat)
  archive/                            # retired plan/task (lifecycle)
  <PROJECT> INDEX.md                  # generated registry (e.g. KYBER INDEX.md)
config/                               # calibration + instruction overrides
extensions/                           # optional net-new modules

Daily workflow

1. Edit framework in kyber workspace → /k publish (or git commit → git push)
2. On other machine: git pull in ~/Development/kyber
3. Consumer library stays in your project git under .kyber/library/

Scripts (--root = consumer repo)

# Resolve paths
node framework/modules/library/scripts/resolve-root.mjs --root ~/Development/my-app

# Regenerate library/<PROJECT> INDEX.md
node framework/modules/library/scripts/refresh-index.mjs --root ~/Development/my-app --apply

# Status emoji + link sync
node framework/modules/plan/scripts/sync-status-filenames.mjs --root ~/Development/my-app --apply

Agent skills

Canonical entrypoints: .agents/skills/kyber/ (/kyber) and .agents/skills/k/ (/k). Portable agentskills.io layout.

IDE	How kyber skills load
Cursor / VS Code	Add kyber as a folder in <project>.code-workspace (path ../kyber relative to the consumer root)
Claude Code	Include the kyber repo on the project path (--add-dir ~/Development/kyber or monorepo layout)

Skills read framework/modules/core/MODULE.md (dispatcher) and framework/modules/<element>/MODULE.md. Consumer setup: /kyber config lists .kyber/config/ artifacts. Module ### config scaffolds calibration or instruction overrides (replaces retired overrides/). business/<PROJECT> BUSINESS.md via business module. No consumer bootstrap — do not duplicate skills into <project>/.cursor/.

Framework health: /kyber doctor or /k doctor — audits modules and writes framework/modules/doctor/HEALTH.md.