| name | kb-setup |
| description | Interactive onboarding wizard that scaffolds an agentic-kb workspace around a flexible layer graph. Asks the user about their context, goals, audience, sources, and desired outputs first, derives a proposed layer graph and feature set including tracker-backed primitive ownership and product-management roadmap/journey placement when relevant, then creates or onboards layer repos, writes the anchor-layer config, configures documented harness workflows, and generates the required templates, indexes, tracker setup artifacts, and HTML style references. |
| version | 6.3.2 |
| triggers | ["/kb setup","setup kb","init kb","init knowledge","onboard kb","bootstrap workspace","create kb","scaffold knowledge base","set up agentic-kb","start agentic-kb","first time using kb"] |
| tools | ["run_in_terminal","read_file","create_file","replace_string_in_file","multi_replace_string_in_file","list_dir","file_search","grep_search","semantic_search","manage_todo_list","vscode_askQuestions","fetch_webpage","memory"] |
| requires | [] |
| author | agentic-kb contributors |
| homepage | https://github.com/wlfghdr/agentic-kb |
| license | Apache-2.0 |
Skill: KB Setup
This skill is the single entry point for bootstrapping an agentic-kb workspace. It is idempotent: reruns add missing pieces, propose graph extensions, and never overwrite existing material without confirmation.
Scope boundary — install vs. init
This skill initializes the user's KB workspace. It does not distribute itself.
Two concerns, two tools:
| Concern | Who handles it | When |
|---|
Get kb-management + kb-setup + kb-operator into the harness | Marketplace install or scripts/install.py | Before this skill runs |
| Scaffold the user's layer repos, config, and workspace indexes | This skill | When the user types /kb setup |
When to invoke
- The user types
/kb setup.
- The user says they want to set up, bootstrap, or onboard a KB workspace.
kb-management detects no .kb-config/layers.yaml in the current workspace and the user tries any /kb command.
Interactive question flow
The interview is goal-oriented, not feature-list-driven. Phase 1 collects the minimum admin facts the wizard cannot infer (workspace root and harness — frontloaded so the user knows where files will land before they invest in long answers); phase 2 asks the user about their world in their own language; phase 3 shows a derived plan and lets the user adjust before anything is written.
Ask each block in order. Stop and wait after each block for the user's answer before proceeding. Never ask the user to enumerate layers, features, contributor-mode flags, or scopes in phase 2 — those are derived in phase 3 and only adjusted there.
Phase 1 — Workspace and harness facts (short admin, frontloaded)
This phase runs first so the user always knows which directory the scaffold will land in and which harness will host /kb before they invest in open-ended answers. Wrong harness or wrong workspace root caught here is a one-line fix; caught after phase 2 it is sunk-cost frustration.
- Workspace root — absolute path; default current directory. Confirm with the user before continuing if the current directory looks accidental (e.g.
~/Downloads, a non-git directory the user did not expect).
- IDE targets — multi-select from
claude-code, vscode, opencode, codex, gemini, kiro. Used by scripts/install.py to decide where harness hooks are written (.claude/commands/, .github/prompts/, .agents/skills/, etc.). The right answer here prevents a silent "No KB detected" later.
- Discovery pass — scan the workspace for existing KB repos, harness hooks, and likely layer candidates. Also probe for repo-as-OS structures (e.g.
work/signals/, work/missions/, org/<layer>/, CONFIG.yaml, CODEOWNERS with policy directories). If a repo-as-OS structure is detected, surface it before phase 3 so the proposal can reuse existing repos and propose bridge defaults instead of inventing parallel structure.
Phase 2 — Context and goals (open-ended)
Question count continues from phase 1 (Q4–Q11 global numbering, as listed in the placeholder mapping section below).
- Who you are — name, role, and one sentence about the work you actually do day to day. Used for
foundation/me.md and contributor directories.
- What you're trying to track or decide — open prose. The wizard extracts themes (3–5 keywords) and workstream candidates from this answer; do not ask for keywords or workstream names directly.
- Why now — what triggered this setup? "Too many directions to keep track of", "leadership keeps asking for status", "starting a new quarter", "team is drifting", etc. Used to bias which artifacts (briefings, weekly status, progress reports, roadmaps) the proposed plan emphasizes.
- Who else needs to see what — describe the audience in plain words: "just me", "me and one team", "two teams plus an org-unit lead", "a whole company". Used to derive layer count, scopes, and role boundaries (which higher layers should be
consumer rather than contributor).
- Where information feeds in — describe the sources the user already reads from: product repos, issue trackers, dashboards, recurring meetings, stakeholder reports, exports. Also listen for whether any issue tracker is already the operational backbone for decisions, tasks, feature intake, roadmap items, or team commitments. Used to derive
connections: and primitive-storage: per layer and to decide whether the lean export-backed roadmap path applies.
- What you want out — describe the artifacts that would actually save time: morning briefing, weekly status to share with a boss, presentations, progress reports, roadmap reconciliation, journey specs, customer-value roadmaps, phase/lane plans, journey maps, or mock-backed flow specs. Used to derive enabled features (
reports, roadmaps, journeys) and dashboard panels.
- How autonomous — describe how hands-on or hands-off the user wants the agent: "I want to confirm everything", "process the obvious stuff and ask me on edge cases", "run on its own and tell me what changed". Mapped to automation levels 1 (manual only), 2 (scheduled rituals/digests), or 3 (scheduled flows plus guarded auto-promote); see
references/automation-levels.md for the full contract. Note: agentic-kb does not ship a scheduler — at level 2/3 the user wires OS cron, CI, or their harness's native automation to invoke /kb.
- Operating context today, and target in 6 months — pick one bucket for today and (optionally) one for 6 months out: (a) human-only / capture discipline first — no agents in the workflow yet; goal is to get the artifact chain steady before adding any automation; (b) repo-as-OS framework already in use — the team already runs signals/missions/PRs or similar git-as-source-of-truth governance; agentic-kb slots in as the knowledge-ops layer; (c) already running AI agents in daily work — agents draft, triage, or act; goal is to ground them in shared context. This is mapped to adoption stages 1 / 2 / 3 (see
references/adoption-stages.md); answers steer the proposed scaffold scope and automation level so the user does not get a Stage-3 setup when they are starting at Stage 1, and does not get a Stage-1 setup when they are already past it.
Phase 3 — Proposed plan (system shows, user adjusts)
The wizard presents a single concrete proposal derived from phase 1 + 2. The user reviews, adjusts inline if needed, and confirms. Do not ask the user to author the plan from scratch.
- Proposed layer graph and adoption stage — show the derived layers as a single block: name, scope, role, parent, path, and enabled features per layer. Highlight which layer will be the anchor and label the proposed adoption stage (1 / 2 / 3) derived from Q11 + Q10 so the user can see at a glance whether the wizard is suggesting a capture-only scaffold, an agent-assisted scaffold, or a bounded-autonomous scaffold. Default for a new solo user starting at Stage 1: one contributor anchor layer (scope
personal), no roadmap/journey features unless Q4/Q5/Q9 explicitly call for them, automation level 1, no connections: write-back. If Q4/Q5/Q9 mention product management, sequencing, customer journeys, launch planning, portfolio status, or stakeholder roadmap communication, propose roadmaps and/or journeys on the layer whose audience owns that work and label the placement as adjustable. Default for a team already on a repo-as-OS framework: one shared contributor layer plus a connections.product-repos[] entry pointing at the existing governance repo. Ask only one yes-or-adjust question on this block; route deeper edits through targeted follow-ups (rename, add/remove a layer, flip role, change parent, change stage, move roadmaps/journeys to another layer).
- Proposed connections, primitive storage, artifacts, and automation — show the derived
connections: per layer (sources from Q8, plus any repo-as-OS product-repo detected in Q3), the primitive-storage: decision for decisions/tasks/ideas/feature intake/roadmap items (files, tracker, or hybrid), the dashboard panels and report types that match Q9 outputs, the automation level from Q10 (1 / 2 / 3 per references/automation-levels.md), and any product-management feature blocks (roadmaps, journeys) that the requested artifacts imply. For each tracker-backed primitive, show the tracker provider, repo/project/key/query parameters known so far, the configured kind/type, the supporting KB summary directory, write-back mode, and the setup artifacts to generate. For each roadmap/journey block, show the chosen owning layer, source inputs, output directories, and whether the first proof path is export-backed or live-adapter-backed. For every multi-user layer, also surface the default artifact visibility per enabled primitive (e.g. "findings, ideas, topics → contributor-scoped; decisions, tasks, foundation, reports → shared") per docs/REFERENCE.md §1 "Two orthogonal axes", so the user can flip visibility before scaffold rather than discovering the default by surprise. Same single yes-or-adjust prompt; collect provider-specific missing values through targeted follow-ups instead of adding a new global interview phase.
- Proposed graduation criteria for the next stage — name the 2–3 concrete things the user would need before safely advancing to the next adoption stage (e.g. "≥ 4 weeks of clean
.kb-log/ entries, one cross-layer promote completed, foundation/vmg.md confirmed by stakeholders" before turning on automation level 2). The user can accept, edit, or skip this block; it is informational and does not block scaffold.
- HTML artifact styling — builtin, website-derived, or template-based corporate design. Default to
builtin when Q3 does not mention external branding constraints.
Phase 4 — Confirm and scaffold
- Final confirmation — restate the chosen plan in one short summary: number of layers, anchor, audiences, adoption stage, automation level, IDE targets, which primitives are file-backed vs tracker-backed, where files will land, and which tracker setup package will be generated. Proceed to "What setup does after confirmation" only after explicit yes.
If the user wants to skip phase 2 entirely and author the plan directly, accept that and route to a compact expert path: ask the layer list with name/scope/role/parent/features/marketplace per layer, anchor, workstreams, automation, styling, IDE targets. Phase 1 (workspace root, IDE targets) is never skipped — the wizard needs both before it can write anything. Document this as the legacy entry point; the goal-oriented flow is the default.
What setup does after confirmation
Step 1 — Prerequisites
Required:
| Tool | Check | Abort message if missing |
|---|
git | git --version exits 0 | Install git first |
| At least one selected harness surface | binary or writable target path exists | Install the harness first or deselect it |
Recommended:
| Tool | Why |
|---|
gh | GitHub-native publish and issue flows |
| SSH key for the user's git host | Push without password prompts |
Step 2 — Create or onboard repos
For each declared layer:
- create a new repo or onboard an existing one,
- initialize git when creating new repos,
- configure remotes only when the user asked for them,
- record the repo path in the anchor-layer
layers.yaml.
Step 3 — Scaffold each layer according to features
For every declared layer, create only the directories required by its enabled features.
Common files:
AGENTS.mdREADME.md.kb-log/.nojekyll when the layer will publish HTMLindex.html and dashboard.html
Feature directories:
inputs → _kb-inputs/ + digested/YYYY/MM/findings → _kb-references/findings/YYYY/topics → _kb-references/topics/foundation → _kb-references/foundation/notes → _kb-notes/YYYY/delivery → _kb-delivery/briefs/ + _kb-delivery/specs/operations → _kb-operations/releases/YYYY/ + _kb-operations/incidents/YYYY/ideas → _kb-ideas/ + archive/YYYY/decisions → _kb-decisions/ + archive/YYYY/tasks → _kb-tasks/ + archive/YYYY/workstreams → _kb-workstreams/reports → _kb-references/reports/roadmaps → _kb-roadmaps/journeys → _kb-journeys/
When a primitive family is configured as mode: tracker, setup still creates the supporting KB directory only for summaries, reports, backlinks, or archived context. It must not seed a competing canonical backlog or decision list that would make the file and tracker both look authoritative.
For multi-user layers, shared primitives live at the repo root and contributor-scoped primitives are created under contributor or team directories.
Step 4 — Write the anchor-layer config
Write .kb-config/layers.yaml, .kb-config/automation.yaml, and .kb-config/artifacts.yaml into the anchor layer.
The anchor config must include:
workspace.rootworkspace.userworkspace.anchor-layerworkspace.aliases- one
layers: entry per declared layer
- optional
connections, marketplace, roadmap, and journeys blocks per layer
- optional
primitive-storage blocks per layer, mapping decisions, tasks, ideas, feature intake, and roadmap items to files, tracker, or hybrid ownership
When Q4/Q5/Q9 indicate product-management work, setup should propose these blocks rather than waiting for the user to know the feature names. The user still confirms placement. The conservative default is to co-locate a roadmap scope with the journeys it cites in the same contributor-capable layer. Layered roadmaps and journeys are allowed by the layer graph, but setup should mark cross-layer roll-ups/inheritance as a later enhancement unless the user explicitly asks for an expert configuration.
Setup must propose primitive-storage instead of assuming file-backed decisions and tasks. Conservative defaults:
- personal or private layers:
files for decisions, tasks, and ideas,
- shared layers: GitHub Issues (
kind: github-issues) as the default tracker for tasks, feature intake, and roadmap items; decisions default to tracker unless the user chooses hybrid for early deliberation in files,
- shared layers where GitHub Issues is unavailable or rejected: render an explicit
files fallback with the reason in the setup summary,
- roadmap items:
tracker only when the roadmap source is already tracker-scoped; otherwise keep roadmap artifacts file-backed and read tracker data as evidence.
Step 4b — Configure tracker backbone setup artifacts
If any primitive-storage entry uses mode: tracker or mode: hybrid, setup must generate or guide the selected tracker setup package.
For GitHub-backed trackers, setup writes or proposes the GitHub governance profile described in references/github-governance-profile.md:
.github/ISSUE_TEMPLATE/config.yml,- one issue form per configured kind/type,
.github/PULL_REQUEST_TEMPLATE.md,.github/labeler.yml,.github/workflows/kb-github-governance.yml,- a repo-local
agent-skills/kb-tracker-workflow/SKILL.md (or the harness-equivalent skill location),
GITHUB_GOVERNANCE_SETUP.md with the manual checklist for native issue types, project/status fields, milestones, labels, branch protection, CODEOWNERS, parent/sub-issues, and required checks that cannot be represented fully as files.
For Jira-backed trackers, setup writes or proposes:
- the
connections.trackers[] project/query/type/status mapping,
- the
primitive-storage mapping,
- a repo-local tracker workflow skill,
- a manual checklist for project fields, workflow states, issue types, and link policy.
For any tracker provider, setup refuses to perform write-back unless writeback.enabled and the provider capabilities are explicitly confirmed. Missing CLI authentication should downgrade to file generation plus manual setup instructions, not a half-configured tracker.
Step 5 — Configure harnesses
Write only the harness hooks needed for the selected surfaces:
- VS Code →
.github/prompts/kb.prompt.md and .github/instructions/kb.instructions.md
- Claude Code →
.claude/commands/kb.md
- OpenCode →
.opencode/commands/kb.md
- Codex →
.agents/skills/kb/SKILL.md
- Gemini →
.gemini/commands/kb.toml
- Kiro →
.kiro/skills/kb/SKILL.md
Never reinstall into a surface that is already up to date unless the user asked for --force behavior.
Step 6 — Verify
Minimum verification sequence:
- scan for unresolved placeholders,
- generate
index.html and dashboard.html for every layer,
- run
/kb status in the anchor layer,
- run
/kb start-day in the anchor layer,
- if a team or org layer exists, prove one promote or digest path,
- if
roadmaps or journeys are enabled, render their dry-run outputs,
- if any tracker-backed primitive is configured, validate that each
primitive-storage.*.tracker points to a declared tracker, that required issue forms or type-mapping instructions exist for GitHub/Jira selections, and that no write-back capability is enabled without the matching confirmation gate.
Step 7 — First win + next-steps shortlist
Verification proves the scaffold is correct. It does not prove the workspace does anything yet. Step 7 closes that gap so the user leaves setup with a visible artifact and a curated 3–5 command shortlist, not with a read-only "Setup: OK" message and a flat dump of the full command surface.
7a — Optional bootstrap capture (default yes). Ask one question:
"Want to capture a first piece of material right now? Paste a URL, a file path, or short text. Skip with no if you'd rather start clean."
If the user answers with content, route it through the full kb-management flow (evaluation gate → finding under _kb-references/findings/YYYY/ or skip with logged reason → topic update if score ≥ 3 → .kb-log/ entry → regenerate index.html and dashboard.html). Emit the resulting artifact path back to the user explicitly:
"Wrote alice-personal/_kb-references/findings/2026-05-18-caches-and-invalidation.md (gate score 3/5). alice-personal/index.html updated. Open it in your browser to see your first KB artifact live."
If the user answers no or skips, write a _kb-log/setup-skipped-bootstrap.md line and continue. The capture is optional, not required for setup to count as complete.
7b — Curated next-steps shortlist. Emit a priorized 3–5 command list, derived from the chosen adoption stage (Q11) and audience (Q7). Do not paste the full command surface; pick what this user should actually try first. Suggested patterns:
| Stage × audience | Shortlist (in this order) |
|---|
| Stage 1, solo | /kb capture <text-or-URL> · /kb note meeting <topic> · /kb review · /kb start-day |
| Stage 1, multi-user | /kb capture … · /kb note meeting … · /kb decide … · /kb promote <file> <layer> · /kb end-week |
| Stage 2, solo | /kb capture … · /kb review · /kb decide … · /kb digest <layer> · /kb start-day |
| Stage 2, multi-user | /kb capture … · /kb review · /kb promote … · /kb digest … · /kb end-week |
| Stage 3 (any) | /kb status · /kb digest <layer> · /kb audit · /kb end-week (the user owns the scheduler trigger that fires the rest, per automation-levels.md) |
Adjust if Q9 ("what you want out") names roadmaps or journeys — insert /kb roadmap and/or /kb journeys after capture. Adjust if Q9 names release/incident artifacts — insert /kb release and/or /kb incident.
The shortlist is informational, not blocking. The user can always invoke any documented verb; the full surface is documented in plugins/kb/commands/kb.md and plugins/kb/skills/kb-management/references/command-reference.md.
7c — Closing message. Emit one short summary, in plain language, naming exactly what was produced and what the user should do next. Example for Stage 1 solo with a bootstrap capture:
"Setup complete. alice-personal is your anchor layer; team-observability is the contributor target for promotions. You wrote your first finding (_kb-references/findings/2026-05-18-...md), and index.html reflects it. Try these next: /kb capture <text> to file more material, /kb start-day for a morning briefing, /kb note meeting <topic> before your next sync. Run /kb status any time to see where you stand."
Adapt the wording to the actual scaffold, but keep three properties: (a) one short paragraph, not a wall of text; (b) name the actual artifact paths the user can open; (c) name 3 commands max in the closing, even if the full shortlist is longer.
7d — Ritual cadence reminder (level 1 only). If automation level is 1, append a second short paragraph naming the rituals that the user must trigger themselves and the recommended cadence. agentic-kb does not ship a scheduler (see references/automation-levels.md "Scheduler ownership") — at level 1 there is no scheduler at all, so the user is the only thing that pulls the trigger.
The closing message includes:
"Rituals are manual at level 1. Suggested cadence: /kb start-day each morning, /kb end-day before you stop, /kb end-week on Friday afternoon. /kb status is safe to run any time. If a ritual gets forgotten, the next /kb start-day reconciles missing days from .kb-log/ and git diff — but the more consistent you are early on, the cleaner the daily/weekly summaries get."
Setup also offers two optional artifacts to make the cadence stick:
- Calendar reminder snippet — on user opt-in, write
_kb-references/rituals.ics with start-day, end-day (M–F), and end-week (Fri 15:00) events the user can drop into their calendar.
- Repeat hint in
/kb status — kb-management already surfaces "missing today's start-day" under the "Rituals" triage signal (see plugins/kb/skills/kb-management/references/command-reference.md "Triage scan"). At level 1, the closing message points the user at /kb status as the explicit nudge channel.
When automation level is 2 or 3, this block is replaced by the scheduler-ownership reminder (already covered in references/automation-levels.md "Scheduler ownership"): the user owns the cron/CI/harness-native trigger that fires the scheduled rituals.
Migration mode
If the user points setup at an older fixed-ladder KB:
- analyze the current layout,
- run
/kb migrate layer-model in dry-run mode to preview the new layer graph,
- map old L1/L2/L3/L4/L5 references to named
layers: entries,
- run
/kb migrate archives in dry-run mode to preview the year-based archive moves,
- apply only after explicit confirmation.
Idempotency
Running /kb setup again:
- detects existing repos and layer declarations,
- proposes only missing or changed pieces,
- offers to add a new layer without disturbing the current graph,
- never rewrites an existing file without confirmation.
Safety
- Never overwrite existing files without explicit confirmation.
- Never create a remote repo without asking.
- Never push to a remote without asking.
- Never force personal-layer assumptions onto a team-only workspace.
Placeholder mapping
Question references in this table use the global numbering: phase 1 covers Q1–Q3 (workspace root, IDE targets, discovery pass), phase 2 covers Q4–Q11 (the open-ended context block), phase 3 covers Q12–Q15 (proposal blocks the user adjusts or accepts), phase 4 covers Q16 (final yes).
The layer-graph scaffold uses double-curly setup placeholders for these token names:
| Token name | Source |
|---|
USER_NAME | Q4 |
ROLE | Q4 (role sentence extracted from the same answer) |
THEMES | extracted from Q4/Q5 (3–5 keywords); rendered as a bullet list into foundation/me.md |
KB_NAME | anchor-layer name (derived and confirmed in phase 3 question 1, i.e. Q12) |
WORKSPACE_ROOT | Q1 |
WORKSTREAM_1_NAME, WORKSTREAM_1_THEMES | extracted from Q5 (themes) and confirmed in phase 3 question 1 (Q12) |
WORKSTREAMS | rendered list of all confirmed workstreams, including repeated workstream token groups, for personal-kb-AGENTS.md |
ADOPTION_STAGE | derived from Q11 (today bucket); used in automation.yaml and the scaffolded foundation/me.md so the chosen stage is durable, not implicit |
AUTOMATION_LEVEL | derived from Q10 + Q11 (1, 2, or 3 per references/automation-levels.md); written into automation.yaml |
TEAM_NAME, ORG_UNIT_NAME | layer name from phase 3 question 1 (Q12) when the proposal includes a shared contributor or synthesis layer; used by the team-kb-* and org-kb-* templates |
REPO_INDEX, ALIAS_INDEX, KEYWORD_LOOKUP | rendered from the discovered + confirmed repo set (Q3 + phase 3 question 1, Q12); used by workspace-AGENTS.md |
VMG_VISION, VMG_MISSION, VMG_GOALS | populated by the VMG sourcing step (URL fetch, file read, or direct text per references/setup-flow.md); placeholders survive only if the user opts to fill VMG later, in which case a backlog item is created |
DATE | today |
VERSION | 1.0 on first scaffold |
Layer-specific repeated content beyond the anchor layer is rendered from the interview answers rather than from hard-coded placeholder names.
Substitution examples:
workspace:
anchor-layer: <KB_NAME placeholder>
workspace:
anchor-layer: alice-personal
vision: "<VMG_VISION placeholder>"
The notes feature always includes general notes, meeting notes, and retros. Setup does not ask for those variants separately; it only decides whether the layer gets the notes feature at all. /kb note retro [topic] then uses the same _kb-notes/YYYY/ directory as the other note variants.
Post-write placeholder check
After writing the scaffold, scan the workspace for any remaining double-curly placeholder sequences outside the deliberate presentation-template placeholders. If any remain:
- stop,
- list the file and placeholder,
- ask for the missing value,
- re-render and rescan.
References
references/setup-flow.md — full step-by-step walkthrough with example output, including VMG sourcing and update guidance.references/github-governance-profile.md — generic GitHub issue/project/PR governance profile generated when GitHub is the tracker or repo workflow backbone.references/automation-levels.md — meaning of setup levels 1/2/3 and how they map into automation.yaml.references/adoption-stages.md — the human → agentic curve: Stage 1 (capture discipline) → Stage 2 (agent-assisted triage) → Stage 3 (bounded autonomous). Names what each stage scaffolds, the graduation criteria between stages, and how adoption stage and automation level relate.references/migration-guide.md — how to migrate an existing KB.references/troubleshooting.md — common setup issues.../../../docs/examples/first-hour.md — narrative onboarding walkthrough for new adopters (the user-facing companion to this skill).../../../docs/first-run-acceptance.md — deterministic acceptance baseline used by maintainers and team leads to verify rollout quality. Not the doc adopters read after first install — see first-hour.md for that.
Changelog
| Date | What changed | Source |
|---|
| 2026-06-17 | Version aligned to 6.3.2 (framework patch — glossary Intake term added; no behavioral change to this skill) | Version alignment |
| 2026-06-10 | Version aligned to 6.3.1 | Version alignment |
| 2026-06-02 | Version aligned to 6.3.0 and changed setup defaults so shared process/operational primitives default to GitHub Issues-backed primitive-storage, while personal/private layers stay file-backed and shared file-backed mode must be an explicit fallback | Issue #145 |
| 2026-05-25 | Version aligned to 6.2.0 | Version alignment |
| 2026-05-25 | Removed hard-coded command-surface counts from Step 7 so setup points at the canonical command reference instead of repeating a number that can drift | Issue #123 |
| 2026-05-22 | Added Step 7d "Ritual cadence reminder (level 1 only)" — when automation level is 1, the closing message names the manual ritual cadence (/kb start-day each morning, /kb end-day before stop, /kb end-week Friday afternoon) explicitly, points at /kb status as the in-tool nudge channel, and offers an optional _kb-references/rituals.ics calendar snippet. At level 2/3 the existing scheduler-ownership reminder fires instead. Closes audit finding #108 | Concept/spec gap audit |
| 2026-05-18 | Added Step 7 "First win + next-steps shortlist" — closing step after verification. Optional bootstrap capture (default yes) writes a first finding through the full evaluation gate and surfaces the artifact path back to the user; curated 3–5 command shortlist derived from adoption stage + audience replaces the implicit full-surface dump at setup end. References section now names docs/examples/first-hour.md as the user-facing companion and reframes docs/first-run-acceptance.md as the maintainer/QA baseline. Closes audit findings #99, #100, #101 | Concept/onboarding/process audit |
| 2026-05-18 | Phase order swap: phase 1 is now "Workspace and harness facts" (Q1–Q3 — workspace root, IDE targets, discovery pass), phase 2 is now "Context and goals" (Q4–Q11). Frontloads the admin block so the user knows where files will land and which harness will host /kb before investing in long answers. All cross-references and the placeholder-mapping table renumbered. Q10 ("How autonomous") now states explicitly that agentic-kb does not ship a scheduler. Phase 3 block 2 must now surface default artifact visibility per primitive per docs/REFERENCE.md §1 "Two orthogonal axes". Closes audit findings #98 and #104 | Concept/onboarding/process audit |
| 2026-05-17 | Extended onboarding to decide per-layer primitive storage (files, tracker, hybrid) for decisions, tasks, ideas, feature intake, and roadmap items; setup now treats generic GitHub/Jira type mapping, issue templates, governance CI, labeler/PR templates, manual branch-protection/project setup, and repo-local tracker workflow skills as first-class outcomes when a tracker backbone is selected | Tracker-backed onboarding design |
| 2026-05-15 | Removed literal double-curly placeholder examples from the published setup skill so GitHub Pages can build the released docs while preserving the setup-token contract for agents | Pages release fix |
| 2026-05-15 | Skill version aligned to 6.1.0. Setup now documents that notes include general, meeting, and retro variants under one feature; delivery/operations scaffold directories are explicit; roadmap/journey blocks are stable setup-proposed features instead of draft-feature blocks; and placeholder substitution examples show confirmed and deliberately deferred values | Release-readiness audit |
| 2026-05-10 | Skill version aligned to 6.0.0 for the v5 adoption-arc closeout. No behavioral changes to the four-phase interview, scaffold output, or migration flow. The setup output contract picks up the new /kb brief, /kb spec, /kb release, and /kb incident verbs because the kb-management plugin it composes ships them as canonical flows; the templated kb.prompt.md was patched in lock-step to enumerate those subcommands and to drop the retired SKILL.md rule #10c cross-reference in favor of rule 8 | v6.0.0 adoption + daily-usage gap audit |
| 2026-05-05 | v5.5.1: closed the placeholder-mapping gap that had been silently broken since the goal-oriented + adoption-stage extensions. Documented the global Q-numbering convention, listed the previously-undocumented token names the templates emit (THEMES, WORKSTREAMS, TEAM_NAME, ORG_UNIT_NAME, REPO_INDEX, ALIAS_INDEX, KEYWORD_LOOKUP, VMG_VISION, VMG_MISSION, VMG_GOALS, AUTOMATION_LEVEL), and replaced the stale "Q12" wording with phase-3-question-1 wording so the table no longer reads as off-by-one | Onboarding consistency review |
| 2026-04-30 | Version aligned to 5.5.0 after making roadmap and journey work a setup-proposed product-management surface. Setup now derives roadmap/journey features from role/goals/outputs, asks which layer owns them, and writes matching config only after confirmation | Product-management surface integration |
| 2026-04-29 | Skill version aligned to 5.4.2 after the draft-skill discoverability fix. The packaged kb.prompt.md template now routes /kb roadmap and /kb journeys to the matching draft skills with a config-block check; this skill's setup-flow contract is unchanged | v5.4.2 draft-skill discoverability fix |
| 2026-04-27 | Skill version aligned to 5.4.1 after the documentation-gap follow-up. Clarified the repo-as-OS bridge field name to connections.product-repos[] and linked the setup-flow VMG sourcing/update guidance | 5.4.1 patch release |
| 2026-04-27 | Clarified the repo-as-OS bridge wording so the proposal names the current schema field connections.product-repos[], and pointed the setup-flow reference description at the new VMG sourcing/update guidance | Documentation gap follow-up |
| 2026-04-27 | v5.4.0: added Q8 ("operating context today, and target in 6 months") to phase 1 so the wizard can bias the proposal to the team's adoption stage (1, 2, or 3) instead of forcing a Stage-3 scaffold on a Stage-1 team or vice versa; phase 2 discovery pass now also probes for repo-as-OS structures so the proposal can offer bridge defaults; phase 3 question 12 now labels the proposed scaffold with its adoption stage; phase 3 question 14 surfaces graduation criteria for the next stage. Added references/adoption-stages.md as the normative contract; subsequent question numbers renumbered. Skill version aligned to 5.4.0 | Soft-transition extension |
| 2026-04-25 | v5.2.0: replaced the feature-list-driven 12-block interview with a four-phase, goal-oriented flow. Phase 1 asks the user about their identity, what they track, why now, audience, sources, desired outputs, and autonomy preference in their own language; phase 2 collects only the workspace and harness facts that cannot be inferred; phase 3 presents one derived plan (layer graph, connections, artifacts, automation, styling) for inline adjust-or-confirm; phase 4 takes a single yes. The legacy "author the plan directly" path stays available as a compact expert mode. Q7 wording carries the automation-level contract added in #76 forward into the new flow | Goal-oriented onboarding |
| 2026-04-25 | Documented what automation levels 1/2/3 mean during setup and linked the interview step to a dedicated reference so adopters do not have to infer the contract from automation.yaml alone | Deep spec-audit follow-up |
| 2026-04-25 | Added the explicit 5.1 migration-helper handoff so setup now points legacy adopters at /kb migrate layer-model and /kb migrate archives instead of leaving those follow-ups implicit | v5.1.0 closeout release |
| 2026-04-25 | Reworked setup for 5.0.0: onboarding now discovers and scaffolds a flexible layer graph, supports team-only or multi-org adoption, writes per-layer marketplaces and connections, and scaffolds year-based archives plus notes | v5.0.0 flexible layer model |
| 2026-04-25 | Version aligned to 4.0.0 for the v4.0.0 framework release | v4.0.0 release alignment |
| 2026-04-22 | Added Codex CLI acceptance guidance and clarified the difference between first-class supported harnesses and compatible CLI workflows | Compatibility expansion |
