hoangnb24/using-khuym

using-khuym

Bootstrap meta-skill. Load this first in Khuym repos. It checks onboarding, reads runtime state, selects the next skill, and protects the human approval gates.

For full routing tables, go-mode detail, communication standards, and file maps, open references/routing-and-contracts.md.

Plugin Onboarding

Before normal bootstrap, verify Node.js and repo onboarding.

1. Run node --version.
   • If missing or too old, stop and tell the user Khuym requires Node.js 18+.
2. From this skill directory, run:

   node scripts/onboard_khuym.mjs --repo-root <repo-root>
   

3. Inspect the JSON result.
   • status = "up_to_date": continue.
   • status = "warning" in details.dependency_warning: continue in degraded mode, but report affected skills and this exact split:
     • Missing commands: ...
     • Missing MCP server configuration: ...
   • missing/stale onboarding: summarize changes, ask before applying, then run with --apply after approval.
   • requires_confirmation = true: explain that existing compact_prompt will be preserved unless the user explicitly approves replacement.
   • Only pass --allow-compact-prompt-replace after explicit approval.

Onboarding manages root AGENTS.md, repo-local .codex/ guardrails, .khuym/onboarding.json, .khuym/state.json, and the local reservation helper. If onboarding is not complete, do not continue into the rest of the Khuym workflow.

Session Scout

After onboarding succeeds, run the read-only scout whenever available:

node .codex/khuym_status.mjs --json

Use it to orient on onboarding health, gkg readiness, .khuym/state.json, .khuym/HANDOFF.json, and recommended next reads.

For active worker coordination, inspect reservations:

node .codex/khuym_reservations.mjs list --active-only --json

If .khuym/HANDOFF.json exists, surface it to the user and wait for confirmation before resuming.

gkg Readiness

Treat gkg as a first-class discovery dependency for supported repos.

• Unsupported repo: document the fallback and use grep/file inspection.
• Supported repo + server not reachable: run gkg index <repo-root> and gkg server start before planning.
• Supported repo + project not indexed: reindex, then start the server.
• Supported repo + ready: downstream skills should use gkg MCP tools as the default architecture-discovery path.

Use the scout's supported_languages and primary_supported_language fields instead of guessing.

Dependency Declaration Contract

Every packaged Khuym skill must declare one of three dependency states:

1. Command-backed: declare each required CLI under metadata.dependencies.<dependency-id> with kind: command, command, truthful missing_effect, and reason.
2. MCP-backed: declare each required MCP server under metadata.dependencies.<dependency-id> with kind: mcp_server, server_names, config_sources, truthful missing_effect, and reason.
3. Dependency-free: declare metadata.dependencies: [].

Use dependency IDs as mapping keys instead of YAML arrays of objects:

metadata:
  dependencies:
    beads-cli:
      kind: command
      command: br
      missing_effect: unavailable
      reason: The skill reads and updates beads.

If the normal operator path uses both a CLI and MCP server for the same product, declare both separately. For example, using-khuym depends on gkg CLI readiness commands and the gkg MCP server for architecture discovery.

Do not leave a packaged skill with an undeclared dependency posture.

When changing packaged Khuym skills, keep docs and live dependency reporting aligned by running:

node plugins/khuym/skills/using-khuym/scripts/test_onboard_khuym.mjs
bash scripts/check-markdown-links.sh plugins/khuym/skills/using-khuym/SKILL.md
bash scripts/sync-skills.sh --dry-run

Skill Chain

khuym:using-khuym
  -> khuym:exploring
  -> khuym:planning
  -> khuym:validating
  -> khuym:swarming
  -> khuym:executing
  -> khuym:reviewing
  -> khuym:compounding

Supporting skills:

• khuym:writing-khuym-skills: improve or create Khuym skills.
• khuym:debugging: root-cause blocked beads and execution failures.
• khuym:gkg: codebase intelligence after gkg readiness is green.

Routing Summary

• Vague/new feature: khuym:exploring
• Research task with clear scope: khuym:planning
• Small clear fix: khuym:planning in small_change mode
• Review request: khuym:reviewing
• Capture learnings: khuym:compounding
• Improve Khuym itself: khuym:writing-khuym-skills
• Agent stuck/error: khuym:debugging
• /go or full pipeline: go mode
• Resume: read .khuym/HANDOFF.json, present state, wait for user confirmation

When in doubt, invoke khuym:exploring first.

Modes

• small_change: at most 3 files, no API/data model change, low risk, no gray areas. Still run planning and validating.
• standard_feature: normal default Khuym chain; use a phase plan or epic map, whichever explains the work honestly.
• high_risk_feature: cross-cutting or hard-to-reverse work; default to epic map, feasibility proof, explicit spikes, and slower approval.

Go Mode Gates

Go mode chains all skills but still has exactly four human gates:

1. After exploring: approve CONTEXT.md before planning.
2. After whole-feature planning: approve the work shape, phase plan, or epic map before current-story/work prep.
3. After validating: approve feasibility-validated current work before swarming.
4. After reviewing: P1 findings block merge; if no P1s, approve merge.

Never skip these gates. Load references/go-mode-pipeline.md for the full sequence.

Priority Rules

1. P1 review findings always block.
2. Context budget always applies; around 65%, write .khuym/HANDOFF.json and pause.
3. CONTEXT.md is the source of truth.
4. Gate 3 is the critical execution approval gate.
5. Spike failures halt the pipeline and return to planning.
6. Never skip validating.
7. history/learnings/critical-patterns.md is mandatory context before planning or executing.

Runtime Files

• .khuym/onboarding.json: onboarding status and managed versions
• .khuym/state.json: runtime state for agents, tools, and humans
• .khuym/HANDOFF.json: pause/resume data
• .khuym/reservations.json: local file reservations
• .codex/khuym_status.mjs: read-only scout
• .codex/khuym_reservations.mjs: reservation helper
• history/<feature>/CONTEXT.md: locked decisions and source of truth
• .beads/: Beads task graph

Handoff Contract

Each skill reads upstream artifacts and writes for downstream:

• exploring writes CONTEXT.md
• planning writes discovery, approach, work shape, epic map or phase plan, and current-story/work artifacts
• validating verifies repo reality, feasibility evidence, spike results, and current story/work readiness
• swarming launches and supervises workers
• executing closes one verified bead
• reviewing returns P1/P2/P3 findings
• compounding captures learnings

Every skill ends with an explicit handoff: [Outcome]. Invoke [next-skill] skill.

Red Flags

• jumping from exploring to swarming
• writing code before CONTEXT.md exists
• skipping validating
• ignoring locked decisions
• reservation leaks
• closing beads without acceptance verification
• commits without bead ids
• continuing while P1 findings are open
• stale state.json after phase transitions
• resuming without reading and surfacing HANDOFF.json