GitHub

What Waykit gives you

Waykit is the SDLC for coding agents. The rest of this page is what that install actually puts on disk: a thin handshake, on-demand skills, one MCP profile per host, a quality gate, and learning loops. Eval-driven development (alpha) is how you prove tool routing in CI; it is not the whole product and it is not a complete EDD framework.

Independent assessment (value + model-/host-agnosticism) and open follow-ups: kit-value-and-model-agnostic-review.md, kit-review-backlog.md. Host adapters: hosts.md. Feature work: Feature lifecycle (grill → stories → TDD → XFN → telemetry → confirm or kill). After a bet’s timebox, measure the leading indicator in PostHog, then stories or prune — not a separate insights role. CI, RUM, and scout alerts that should become typed Linear tickets are quality loops.

Always-on context

Agents pay for every byte in the bootstrap. Waykit keeps always-on files small and loads philosophy, SOPs, and skill bodies on demand.

SurfaceIn the always-on total?Target
AGENTS.md + project handshakeYes< ~8KB (~2k tokens)
Thin host pointers (.cursorrules, CLAUDE.md, Copilot, GEMINI.md)Printed, not summedOne pointer per session
Skill descriptions (frontmatter only)No (discovery)Fine; do not pre-load skill bodies
CODING_PHILOSOPHY.md and SOP filesNoZero on typo/debug routes unless that procedure is needed
wk measure-context

Prints a character/token estimate per file and FAIL if always-on exceeds 8KB. Re-run after editing AGENTS.md or the handshake template. wk check runs this gate last.

Agent checklist: SOPs/context-budget.md.

One MCP profile per session

Extra MCP tools compete for attention and inflate tool-schema tokens. Compose one named profile:

wk mcp default --install
wk mcp default --install --host claude
wk mcp default --project
wk mcp collab --install
wk mcp ops --install
wk mcp cloudflare-ops --install
wk mcp warp --install
wk mcp posthog --install
wk mcp sonar --install
wk mcp signoz --install

Match the profile to the skill’s mcp: frontmatter. Do not merge collab + devtools + ops into one global mcp.json. Catalog: mcps/README.md. Procedure: SOPs/mcp-library.md.

Quality gate

wk check is the local merge bar:

  1. wk audit: prompt injection, secrets, entropy, lockfile pins
  2. wk validate / wk verify: eval schemas, skills layout, and role line budget
  3. wk ontology check: live-derived graph refs (depends-on, mcp, subagent stubs)
  4. Host pointer files present (wk export-rules --check)
  5. Skill-trigger evals (registration / prompt hygiene; not a model run) and EDD wk eval ci (scripted, 95% routing)
  6. Context budget
wk check
wk check --json
wk audit
wk sync --install

wk sync installs upstream skills (Cloudflare, Vercel) from skills/external.lock.json by version tag or latest, not a guessed commit SHA. SOPs/external-skills.md.

TDD Guard hooks

wk tdd-guard install writes Cursor .cursor/hooks.json and Claude Code .claude/settings.json so Write/Edit cannot skip red. The command reads hook JSON on stdin. Procedure: TDD Guard hooks. Inspired by TDD Guard.

Repo doctor

wk doctor is the community-file check for GitHub sources you admin, not a glob over every clone. Report-only by default. --write fills missing README, license, contributing, security, and GitHub templates and never overwrites existing files. --owned --scan <dir> matches local worktrees to gh repo list --source. Forks are skipped. wk init still owns the handshake and hooks.

Guide: Repo doctor. Consumer handshake: Consumer align (including the reusable PR workflow). First-party clones: Used on our own product repos.

wk doctor
wk doctor --owned --scan ~/Documents/dev
wk doctor . --write
wk doctor . --json

Live kit graph

Skills, host subagent stubs, SOPs, MCP servers, evals, and docs are one graph derived from the files agents already edit. You do not maintain a second catalog. wk ontology check fails dangling depends-on, mcp:, and subagent→skill refs. wk ontology generate writes a gitignored index for kit-knowledge and the public map.

Browse: Waykit map. Authoring: Author the Waykit map. Decision: ADR 0005.

Commands

Day to day you operate the kit with wk. On a TTY, wk with no arguments opens a guided menu. Scripts keep the same verbs: align for handshake, doctor for community files, check for the merge bar. Skills and AGENTS.md tell the agent which path to load (debug vs feature). wk help lists the rest.

Every report command starts with ok, warn, or fail in a fixed column (fail is exit 1; warn stays exit 0). On a TTY those tokens are green / orange / red; NO_COLOR or a pipe stays plain. Details follow that line.

CommandWhat it measures or installs
wk alignConsumer handshake, host pointers, kit MCP, commit-msg (--write seeds missing AGENTS.md and pointers; --owned --scan for a worktree farm; --json for findings)
wk doctorCommunity files on owned GitHub sources (--owned, --write; --json for findings)
wk loopsQuality-loop Cursor Automations (status catalog + MCP checklist; setup --write project pack)
wk checkAudit, ontology, evals, EDD CI, context budget (--json for findings)
wk versionKit package/git describe and whether ~/.agents is this clone (--check warns if origin is weeks ahead)
wk measure-contextAlways-on bootstrap size vs 8KB
wk completion zshPrint a live tab-completion stub (wk completion install writes it once)
wk ontology checkLive graph referential integrity
wk agents generateThin host stubs under agents/ from the allowlist
wk agents installCopy stubs into ~/.cursor/agents and ~/.claude/agents (user scope)
wk agents statusLaunch vs skills-only (WK_SUBAGENTS) and the expand-kill indicator
wk agents launch-promptParent Task prompt for one allowlisted specialist
wk ontology generateWrite gitignored index for kit-knowledge and the public map
wk mcp <profile>One MCP profile into Cursor, Claude, Copilot, and Antigravity
wk auditSkills and scripts supply-chain scan
wk eval ciRouting accuracy gate (EDD)
wk syncUpstream skills from the lockfile, then refresh user kit subagent stubs

EDD loop (alpha), keys, and CI: edd.md. Host files: hosts.md.

Markdown source