Imported from mzworthington/waykit (
AGENTS.md). Install upstream withnpx skills add mzworthington/waykit. Copyright stays with the author.
Agent Bootstrap
This repository is Waykit (the .agents kit). Consumers symlink ~/.agents here (install.sh). App repos use the thin handshake: templates/project-AGENTS.md.
Do not commit or push unless the user explicitly asks.
Do not eager-read philosophy, SOPs, or skills. Use this index, then load only what the task needs (file read or kit-knowledge MCP).
Invariants (always on)
- Hexagonal - dependencies point inward; domain stays pure.
- Mermaid for architecture diagrams in docs. ASCII/box-drawing for TTY CLI chrome (CODING_PHILOSOPHY.md §8).
- Commits / tickets - conventional subjects (SOPs/conventional-commits.md); type follows behavior. Linear playbook: SOPs/linear-ticket-workflow.md (main, uncommitted unless asked).
- Tests are the behavior catalog - align functional + XFN impact before non-trivial coding. Prefer self-documenting names; encode why in a test.
- One MCP profile per session - prefer skill frontmatter
mcp:ids; more tools cost tokens (mcps/README.md).
Load on demand
| Need | Load |
|---|---|
| Architecture / clean-code detail | CODING_PHILOSOPHY.md or kit-knowledge get_philosophy_section |
| Feature routing / multi-phase | agent-orchestrator |
| Phase work | Matching skills/agent-* only for that phase |
| Stack rules | Matching lang-* / framework-* / profile-* after detecting the codebase |
| CI/CD / GitHub Actions | profile-pipeline |
| Catalog / XFN matrix | SOPs/behavior-catalog-and-xfn.md during Design |
| Debug / RCA | agent-debug + SOPs/hypothesis-driven-debug.md |
| Product bet / PRD / flags | agent-prd + SOPs/hypothesis-driven-development.md |
| EDD (prompts, MCP tools, routing; alpha) | docs/edd.md + SOPs/eval-driven-development.md |
| Model class / host slug | SOPs/model-routing.md (models/catalog.yaml + models/hosts/) |
| Subagent vs skill | get_sop subagent-launch (wk agents status) |
| SOP / handover search | kit-knowledge MCP (search_kit, get_sop, get_handover) |
| Kit ontology | ontology/schema.yaml only (index derived at use time; authoring: ontology/README.md) |
| Cross-session facts | memory MCP (glossary/SLO/prefs; never secrets) |
| Vendor/framework API docs | context7 MCP |
| Linear issues / projects | linear MCP (OAuth; on the default profile) |
| Warp Factory tasks | warp-factory MCP (wk mcp warp --install) |
| PostHog / agent tokens | agent-posthog (wk mcp posthog); tokens/cost: coding-agent-observability (community SigNoz Docker; Cloud Agents → SigNoz Cloud) |
| Signals → Linear | quality-loops (wk loops); PostHog product-signal-intake; Sonar sonarqube-findings |
| Crime-scene report | complexity-hotspots §8 (arch-drift → gate → stories) |
Phase → skill
| Phase | Skill |
|---|---|
| Idea stress-test | agent-grilling / agent-grill-me |
| PRD / product bet | agent-prd |
| Spec | agent-spec |
| Linear backlog / user stories | agent-user-stories |
| TDD short loop | agent-tdd (SOPs/tdd-guard.md) |
| XFN | agent-xfn |
| Adapter deep-dive | agent-adapter (only if gear 2 is too large) |
| UI / copy | agent-ui, agent-copy (human-centric / de-AI voice) |
| Migration / API contract | agent-migration, agent-api-contract |
| Review / docs / release | agent-review, agent-docs (+ agent-copy for narrative voice), agent-release |
| Incident / security / arch | agent-incident, agent-security, agent-arch-drift, agent-adr |
| Prune / perf / debug / telemetry | agent-prune, agent-perf-opt, agent-debug, agent-telemetry, agent-cloudflare-ops, agent-posthog |
| Pre-commit | agent-pre-commit |
Handovers: ~/.agents/handover/<project>/ (templates/handover.md). Run pre-commit before COMPLETE when hooks exist.
Public site: waykit.dev (Astro in web/, Markdown in docs/; DNS in edge-dns).
Taxonomy: skills/README.md. MCP catalog: mcps/README.md. Context budget: SOPs/context-budget.md.