kb-setup

Stars10

Forks1

UpdatedJune 19, 2026 at 20:27

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.

Installation

Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.

Source

wlfghdr

wlfghdr/agentic-kb

View GitHub Repository View Creator Repositories

Download

Related occupationsSOC

Based on SOC occupation classification

Computer Occupations, All OtherComputer and Mathematical Occupations·SOC 15-1299

File Explorer

41 files

SKILL.md

readonly

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.md
README.md
.kb-log/
.nojekyll when the layer will publish HTML
index.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.root
workspace.user
workspace.anchor-layer
workspace.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:

# before substitution
workspace:
  anchor-layer: <KB_NAME placeholder>

# after confirmation
workspace:
  anchor-layer: alice-personal

# if the user deliberately defers VMG text
vision: "<VMG_VISION placeholder>"  # follow-up task required before setup is complete

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

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

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

Phase 1 — Workspace and harness facts (short admin, frontloaded)

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.

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.md
README.md
.kb-log/
.nojekyll when the layer will publish HTML
index.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/

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.root
workspace.user
workspace.anchor-layer
workspace.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

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.

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

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."

"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.

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`)

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."

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.

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

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:

# before substitution
workspace:
  anchor-layer: <KB_NAME placeholder>

# after confirmation
workspace:
  anchor-layer: alice-personal

# if the user deliberately defers VMG text
vision: "<VMG_VISION placeholder>"  # follow-up task required before setup is complete

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

kb-setup

More from this repository

More from this repository

Skill: KB Setup

Scope boundary — install vs. init

When to invoke

Interactive question flow

Phase 1 — Workspace and harness facts (short admin, frontloaded)

Phase 2 — Context and goals (open-ended)

Phase 3 — Proposed plan (system shows, user adjusts)

Phase 4 — Confirm and scaffold

What setup does after confirmation

Step 1 — Prerequisites

Step 2 — Create or onboard repos

Step 3 — Scaffold each layer according to features

Step 4 — Write the anchor-layer config

Step 4b — Configure tracker backbone setup artifacts

Step 5 — Configure harnesses

Step 6 — Verify

Step 7 — First win + next-steps shortlist

Migration mode

Idempotency

Safety

Placeholder mapping

Post-write placeholder check

References

Changelog

Skill: KB Setup

Scope boundary — install vs. init

When to invoke

Interactive question flow

Phase 1 — Workspace and harness facts (short admin, frontloaded)

Phase 2 — Context and goals (open-ended)

Phase 3 — Proposed plan (system shows, user adjusts)

Phase 4 — Confirm and scaffold

What setup does after confirmation

Step 1 — Prerequisites

Step 2 — Create or onboard repos

Step 3 — Scaffold each layer according to features

Step 4 — Write the anchor-layer config

Step 4b — Configure tracker backbone setup artifacts

Step 5 — Configure harnesses

Step 6 — Verify

Step 7 — First win + next-steps shortlist

Migration mode

Idempotency

Safety

Placeholder mapping

Post-write placeholder check

References

Changelog