Waykit

Product lifecycle for coding agents- Grill, spec, TDD, ship, learn

Give your coding agents a release bar. Waykit provides the full product and software delivery lifecycle, from Spec to Test to Release, plus the feedback loops that make every session better than the last.

Site: waykit.dev. Start in the docs:

• Feature lifecycle. Grill, spec, TDD, XFN, audit, release. EDD (alpha) sits here when tools are the change.
• Quality loops. CI, RUM, Lighthouse and Sonar file Linear tickets. Hygiene then the work picker turns them into draft PRs.
• Jobs for today. Debug vs feature, a fat context, a tool call. Pick one and run it.

The CLI is wk. Same AGENTS.md, same skills, MCP composed into Cursor, Claude Code, GitHub Copilot and Antigravity. Hosts.

Install

curl -fsSL https://raw.githubusercontent.com/mzworthington/waykit/main/install.sh | sh
wk init . --mcp default --hook

macOS / Linux; needs git and Node 22+. Already cloned this repo? Run ./install.sh from the checkout. If wk is not found, add ~/.local/bin to PATH.

Then start here in 10 minutes.

Used on our own product repos

Waykit is not only this kit. First-party checkouts run the thin handshake, kit MCP and wk align. Open AGENTS.md if you want to see a consumer in the wild.

Product	What it is	What to look at
ArchLens	Architecture canvas and CLI	Hexagonal @archlens/core, TDD for parsers, sparse ADRs
RoMini	Screen-free NFC audio player on a Pi	Parent dashboard maps tags. Hexagon, TDD, bedtime-script skill
steerco	Executive steering workspace	In-app docs, Cloudflare Pages, handover under steerco/
React Cloudflare template	Greenfield product starter	The handshake wk init writes, already aligned so clones inherit it
GPIO build monitor	Pi LEDs and a Cloudflare Worker status UI	Python plus Pulumi. Default MCP for agents; cloudflare-ops only when the Worker is the job

More on the site: used in.

---

What do I use this for today?

Job in front of you	Do this
Never installed Waykit	Install, then start here in 10 minutes
Typo, bug, or failed job	agent-debug + light XFN if UI/auth/SLO. wk debug-board <project> "<symptom>". Not grill → spec.
Starting a product feature	Orchestrator lifecycle (grill → PRD if bet → stories → spec → TDD + XFN → audit → release → confirm/kill)
Always-on rules are too fat	wk measure-context then wk check
Owned repos missing README / license / templates	wk doctor --owned --scan <dev-dir>
App repo drifted from the Waykit handshake	wk align . (--write fills host pointers; wk mcp default --project for kit MCP). Fleet: wk align --owned --scan <dev-dir>. Product PRs can call the reusable align-consumer workflow.
Quality-loop Cursor Automations	wk loops status / wk loops setup --write
Which kit am I running?	wk version (--check warns if origin is weeks ahead; does not pull)
Agent picked the wrong tool / made-up args	Write a JSONL case → wk eval run --suite evals/edd/demo.yaml --model scripted
Gate a prompt or schema change	wk eval ci --suite evals/edd/demo.yaml --threshold-routing 95 --out out/reports
Promote a prod miss into the suite	wk eval shadow --infile evals/edd/examples/prod-turns.jsonl --sample 1 --seed 1 --out out/shadow-fails.jsonl

Tangible proof on the site: before / after · interactive demo · jobs for today.

Teaching suite: evals/edd/demo.yaml (before-after write-up). CI seed: architecture_routing. Live golden: evals/edd/goldens.

---

Lifecycle plus learning loops

Pillar	Outcome
Lifecycle skills	Grill → spec → TDD short loop → XFN → security → release via agent-* roles
Architecture	Hexagonal + DDD + vertical slices + clean code (CODING_PHILOSOPHY.md; applicability/opt-out included)
Learning loops	Behavior catalog, XFN gates, evals for tool calls, prod misses back into the suite
One rules file	AGENTS.md is the handshake; wk export-rules copies one host-pointer stub to each IDE entry point
MCP catalog	One profile composed into Cursor, Claude, Copilot and Antigravity config files (mcps/, docs/hosts.md)
Context budget	Always-on bootstrap under ~8KB; wk measure-context / wk check (docs/kit.md)
Security audit	Prompt injection, secrets, entropy, unpinned skills (wk audit)

sequenceDiagram
  autonumber
  participant O as agent-orchestrator
  participant G as agent-grilling
  participant P as agent-prd
  participant S as agent-spec
  participant T as agent-tdd
  participant X as agent-xfn
  participant Sec as agent-security
  participant Arch as agent-arch-drift
  participant Tel as agent-telemetry
  participant R as agent-release

  O->>G: Stress-test idea, contract vs bet
  O->>P: PRD / bet card when value is unproven
  O->>S: BDD spec (flag off / on / kill when flagged)
  O->>T: Inventory catalog and plan test impact
  O->>X: Cross-functional quality matrix
  O->>T: TDD short loop (gear 1 + gear 2)
  O->>X: Green apply-row XFN suites
  O->>Sec: Security and OWASP audit
  O->>Arch: Hexagonal boundaries, no drift
  O->>Tel: SLOs plus leading indicator
  O->>R: Conventional PR title, flag expiry

Loading

When the change is a prompt or tool schema, TDD includes Eval-Driven Development (alpha): write a failing eval, green the contract, gate merges with wk eval ci --threshold-routing 95. This is a routing/schema harness with a scripted merge gate, not a full EDD product. Details: docs/edd.md.

flowchart LR
  intent[Agent intent] --> edd[EDD red / green / refactor]
  edd --> ci[CI threshold gate]
  ci --> ship[Ship]
  ship --> prod[Prod OTel + shadow judge]
  prod -->|miss| edd

Loading

wk eval run --suite evals/edd/demo.yaml --model scripted
wk eval ci --suite evals/edd/demo.yaml --threshold-routing 95 --out out/reports
wk eval report --format md --out out/reports

---

After install

Optional: prove routing on the teaching suite (offline scripted driver):

wk eval run --suite evals/edd/demo.yaml --model scripted
wk eval ci --suite evals/edd/demo.yaml --threshold-routing 95 --out out/reports

Command	Purpose
wk init [dir]	Bootstrap AGENTS.md, IDE rules, MCP, pre-commit
wk doctor [dir]	Community-file check on repos you admin (--owned, --write fills gaps; --json for findings)
wk align [dir]	Consumer handshake, host pointers, kit MCP, commit-msg (--write seeds; --owned --scan for a worktree farm; --json for findings)
wk loops [status|setup]	Quality-loop Cursor Automations catalog, dashboard MCP checklist, project pack (--write fills .cursor/waykit-loops; alias automations)
wk version	Package/git describe and whether ~/.agents is this clone (--check warns if stale)
wk completion install	Write a live tab-completion stub (zsh + bash); verbs follow the current wk
wk mcp <profile>	Compose a named profile into Cursor, Claude, Copilot, and Antigravity (--install / --project)
wk check	Local quality gate (audit, evals, EDD CI, context budget; --json for findings)
wk eval run|watch|report|ci	Eval harness for agent tool routing and schemas
wk eval	Skill-trigger harness (which specialist activates)
wk audit	Security and supply-chain audit
wk validate / wk verify	Eval schema + skills layout and role line budget
wk export-rules	Copy templates/host-pointer.md → Cursor, Claude, Copilot, Gemini/Antigravity, and Windsurf filenames
wk sync	Install upstream skills from the lockfile, then refresh user kit subagent stubs
wk measure-context	Always-on context budget
wk model resolve	Capability class + host slug (models/catalog.yaml)
wk site assemble	Copy web/dist plus public Markdown into site/ (after pnpm --dir web build)
pnpm site:dev	Astro docs app (Markdown in docs/)

pnpm wk runs the CLI in this repo.

---

Docs map

Start with the path that matches what you’re trying to do:

1. Feature work: Feature lifecycle → orchestrator → behavior catalog and XFN
2. Architecture and bootstrap: Coding philosophy (incl. applicability) → ADRs → AGENTS.md
3. Skills and MCP: skills/README.md → mcps/README.md → hosts
4. Prove tool calls (EDD, alpha): demo suite → before/after → EDD guide
5. Prod feedback: EDD production telemetry (wk eval shadow + from-trace)
6. Operators: What Waykit gives you → Repo doctor → Consumer align → Used on our own product repos → Context budget
7. Live kit graph: Waykit map → author the map (wk ontology check)

Site: waykit.dev. Markdown in docs/, Astro app in web/ (pnpm site:dev). HTML routes like /docs/kit sit next to the raw .md URLs.

---

This checkout

App repos only need wk on PATH. This table is for people changing Waykit itself:

Path	Role
bin/kit, bin/kit.ts	CLI on PATH (parse → run); public name is wk
wk /src/cli/	Argv parser, help, and command dispatch
wk /src/	Implementation and unit tests, grouped by area (bootstrap/, edd/, ontology/, …)
evals/	Skill-trigger JSON suites and EDD YAML/JSONL
skills/, mcps/	Lifecycle skills and MCP catalog

pnpm install
pnpm typecheck && pnpm test && pnpm wk check
pnpm test:ci       # same + Markdown report at out/reports/unit-test-report.md (CI Summary)
pnpm check         # tests, then wk check (audit, evals, EDD CI, context budget)

Contributing: CONTRIBUTING.md. Security: SECURITY.md.

---

License

Unlicense (Public Domain).