Aksk Bootstrap

AKSK Bootstrap

Goal

Per-user global setup (skill plus deterministic JS script). Prepares the machine for per-repo init. Reuses the finalized kit templates and adopt-openspec-openwiki curation-contract semantics; never replaces OpenWiki-owned content.

The skill is the orchestrator; the JS script is the deterministic executor. Other skills (learning-distill, docs-lint, task-closeout) reuse its preconditions.

Bootstrap (orchestrator)

EXECUTE lane — run locally

node .agents/skills/aksk-bootstrap/scripts/bootstrap-global.mjs  # global lane (interactive) [repo-root] [--force]

Global lane (non-interactive; skill is interactive) (idempotent by detection):

1. Verify CLIs — Node >= 22, openspec/openwiki on PATH (npm i -g @fission-ai/openspec@^1.11.0 openwiki@^0.4.3 if missing, caret from references/versions.json via versionsFromPackageJson()); skip any tool already present at a compatible version; verify openwiki resolves before MCP registration.
2. Verify skills — ensure ~/.agents/skills/<name>/SKILL.md plus current host's dir; if missing npx skills add <source> -g -a <agent> — <source> is the positional <package> arg (e.g. Hypercubed/Agent-Knowledge-Starter-Kit or Hypercubed/Agent-Knowledge-Starter-Kit#develop) and <agent> is the detected host (opencode, codex, claude, or *; use npx skills add <source> -g --all as shorthand for universal ~/.agents/skills) — positional first because -a consumes the next token, so npx skills add -g -a <source> incorrectly treats <source> as the -a value and yields Missing required argument: source (versions from references/versions.json, @latest only when unpinned; npx required, no clone fallback); e.g. npx skills add Hypercubed/Agent-Knowledge-Starter-Kit#develop -g -a opencode or npx skills add Hypercubed/Agent-Knowledge-Starter-Kit -g --all — for the kit and for langchain-ai/openwiki --full-depth when that lifecycle skill is needed, otherwise openwiki integrations install <self-reported> when that host is in codex|claude|opencode (skill+MCP+receipt atomically) else fallback npx add-mcp "openwiki mcp --host <self-reported>" -g -a <self-reported> --name openwiki (command form; equivalent --args form npx add-mcp openwiki -g -a <self-reported> --args mcp --args --host --args <self-reported> --name openwiki) — bare npx add-mcp openwiki omits mcp --host and yields ["npx","-y","openwiki"] → MCP -32000 Connection closed; openwiki mcp --host <self-reported> is the non-add-mcp alternative. OpenSpec skills spread is the second verb: bootstrap-global.mjs probes ~/.agents/skills/openspec-*/SKILL.md (+ host mirrors) and npx skills list -g, then runs npx skills add fission-ai/openspec -g --all -y when missing (source pinned as fission-ai/openspec-skills in references/versions.json, bare id when unpinned; skips when present). Per-repo steps now live in aksk-init. Never half-install: failed step prints exact remaining commands and exits clean without partial state from that step.

INSTRUCT lane — no local execution bridge

When any step cannot run locally (no npm, no write, sandboxed worker), the script prints the exact remaining commands and exits clean. The skill then surfaces those commands verbatim as the answer.

INSTRUCT lane — run these commands manually (versions from `references/versions.json`, caret-pinned):
  npm i -g @fission-ai/openspec@^1.11.0 openwiki@^0.4.3
  openwiki integrations install codex

No partial state from the failed step is left behind; completed steps remain.

Idempotency

Re-running on a fully bootstrapped fixture changes nothing; re-running on a partially bootstrapped fixture completes only missing steps (detection-driven).

Peer-tool verification

Standalone:

node .agents/skills/aksk-bootstrap/scripts/check_peer_tools.mjs openspec openwiki

From Python (sibling skills may import; import from this scripts directory):

import { requireBinaries } from "./check_peer_tools.mjs";
requireBinaries(["openspec", "openwiki"]); // exits 2 with install commands if absent

Only known peer tools are accepted (openspec, openwiki); any other name exits 2 with an error naming the unknown tool rather than attempting a PATH lookup.

Behavior contract:

• Checks PATH resolution only; never attempts installation.
• On missing tools, prints one error per tool plus the exact install commands (npm i -g @fission-ai/openspec@^1.11.0, npm i -g openwiki@^0.4.3 with caret from references/versions.json, falling back to @latest if unpinned) and exits 2.

Related

• Curation semantics consumed at distill time are specified by the distill-routing capability; contract attachment semantics by the wiki-contract capability.
• Design and lane ladder for openwiki integrations install are tracked in openspec/changes/aksk-bootstrap-system/.