waypoint-skills 1.3.0

package/packages/skills/waypoint/SKILL.md

@@ -0,0 +1,67 @@
+---
+name: waypoint
+description: >-
+  Install and manage Waypoint Skills across AI assistants (Cursor, Claude, Codex,
+  Antigravity, Copilot). Use when user asks to install waypoint.sk, bootstrap wp
+  framework, run waypoint doctor, or verify skills installation.
+---
+
+# Waypoint Skills (install skill)
+
+Install [waypoint.sk](https://github.com/quenginedev/waypoint.sk) into any supported AI assistant.
+
+## Supported platforms
+
+Cursor, Claude Code, Codex, Antigravity, GitHub Copilot, Gemini CLI — see `docs/PLATFORMS.md`.
+
+## Install (agent executes)
+
+**Recommended — full framework (skills + agents + rules + hooks):**
+
+```bash
+npx waypoint-skills install -y
+npx waypoint-skills install --platform cursor --global
+npx waypoint-skills install --platform claude --global
+```
+
+**Skills only** via [skills CLI](https://skills.sh):
+
+```bash
+npx skills add quenginedev/waypoint.sk -g -y
+npx skills add quenginedev/waypoint.sk --skill wp --skill ponytail -g -y
+npx skills add quenginedev/waypoint.sk --list
+```
+
+**From git clone or curl:**
+
+```bash
+git clone https://github.com/quenginedev/waypoint.sk.git
+cd waypoint.sk && npx waypoint-skills install -y
+
+curl -fsSL https://raw.githubusercontent.com/quenginedev/waypoint.sk/main/scripts/install.sh | bash -s -- --platform auto --global
+```
+
+## Bootstrap wp in cwd git project
+
+```bash
+npx waypoint-skills bootstrap
+npx waypoint-skills bootstrap --mid api-payments
+```
+
+Then: `/wp [objective]` or `wp: list`
+
+## Verify
+
+```bash
+npx waypoint-skills doctor
+npx waypoint-skills status --platform cursor --global
+npx waypoint-skills instances
+```
+
+## Manifest
+
+`manifest.json` — platforms, skills (`wp`, `caveman`, `ponytail`, `waypoint`, taste skills), agents, rules.
+
+## Flow reference
+
+`docs/WAYPOINT-FLOW.md`

package/packages/skills/wp/SKILL.md

@@ -0,0 +1,330 @@
+---
+name: wp
+description: >-
+  Intercepts /wp, wp:, and run wp: prompts; bootstraps .wp/
+  framework state with per-instance namespacing and git worktrees; routes to
+  Orchestrator subagent. Part of Waypoint Skills. Supports lifecycle commands
+  (list, status, pause, abort, pivot, resume) scoped by instance id.
+---
+
+# wp (Waypoint Skills router)
+
+## Skill: wp
+
+**Trigger keywords** (message starts with, case-insensitive):
+
+| Prefix | Objective |
+|--------|-----------|
+| `/wp` | remainder after prefix (optional space or `:`) |
+| `/wp:` | remainder after prefix |
+| `wp:` | remainder after prefix |
+| `wp ` | remainder after prefix |
+| `run wp:` | remainder after prefix |
+
+**Mission ID** (optional, parsed before objective):
+
+| Syntax | Example | `mid` |
+|--------|---------|-------|
+| `@<id>` prefix | `/wp @api-payments add Stripe webhooks` | `api-payments` |
+| `--id=<id>` flag | `wp: --id=web-checkout checkout success page` | `web-checkout` |
+| omitted | `/wp add checkout emails` | `default` |
+
+**ID rules:** lowercase `[a-z0-9][a-z0-9-]*` only. Invalid ID → ask user to fix.
+
+**Flags** (strip from objective before routing):
+
+| Flag | Effect |
+|------|--------|
+| `--foreground` | Orchestrator Task runs blocking (default for `resume`) |
+| `--no-worktree` | Instance uses `project_root` instead of git worktree (only for `default` or explicit opt-out) |
+
+**Do not activate** on incidental phrases like "the mission of this refactor is…" unless prefixed with `/wp` or `wp:`.
+
+**Lifecycle commands** (objective exact match after ID/flag strip, case-insensitive):
+
+| Command | Action |
+|---------|--------|
+| `list` | Read-only — all instances from `registry.md`; no bootstrap, no orchestrator |
+| `status` | Read-only dashboard — all instances if no `@id`; one instance if `@id` present |
+| `resume` | Route to Orchestrator for scoped `mid` (no re-scope) |
+| `pause` | Write pause marker to instance `mission_control.md`; halt that instance's loop |
+| `abort` | Archive instance to `.wp/archive/<mid>-YYYY-MM-DD-HHMM/`; confirm with user |
+| `pivot: [new objective]` | Ask: resume / archive+restart / append epic **within scoped `mid`** |
+
+If objective is empty after stripping prefix, show the lifecycle help block (table above + `wp: [@id] [objective]`).
+
+## Objective
+
+Bootstrap `.wp/` framework shell when missing, bootstrap **per-instance** state under `.wp/instances/<mid>/`, provision **git worktree** for non-`default` missions, then **delegate to the Orchestrator subagent via Task** — never adopt Orchestrator persona inline. Preserve parent context for routing only.
+
+## Workspace Precondition
+
+Before Phase 1:
+
+1. Confirm workspace is the **target project root** (not home `~` unless user explicitly confirmed).
+2. If unclear, ask the user or call `move_agent_to_root` on the project path.
+3. Never bootstrap `.wp/` in home without explicit confirmation.
+
+## Multi-Mission Concurrency (v1.3)
+
+| Rule | Policy |
+|------|--------|
+| State isolation | One `wp_root` per `mid`; never write sibling instances |
+| Orchestrator loops | One active orchestrator loop per `mid` |
+| Worker git isolation | Each non-`default` `mid` gets its own git worktree; workers run in `worktree_root` |
+| Parallel OK | `list`/`status`, explore subagents, scope/contract dialogue in separate chats |
+| Parallel blocked | Two workers in the **same** worktree simultaneously |
+
+**Path constants** (compute on every invocation):
+
+```
+project_root     = absolute workspace root (git repo)
+mid              = parsed mission id (default: default)
+wp_root    = .wp/instances/<mid>/
+worktree_root    = from instance_meta.md, or project_root for default/--no-worktree
+```
+
+## Phase 1: Deterministic Environment Bootstrap
+
+Run when `.wp/` shell is missing, or when `wp_root` for this `mid` is missing. All steps **idempotent**.
+
+### 1a — Framework shell directories
+
+```
+.wp/
+├── registry.md
+├── agents/
+├── skills/
+├── hooks/
+└── instances/
+    └── <mid>/
+        ├── instance_meta.md
+        ├── mission_profile.md
+        ├── validation_contract.md
+        ├── active_plan.md
+        ├── mission_control.md
+        └── handoffs/
+```
+
+Shared framework lives at `.wp/{agents,skills,hooks}/`. Per-mission state lives only under `.wp/instances/<mid>/`.
+
+### 1b — gitignore
+
+Append `.wp/` only if not already listed. Ensure trailing newline before append.
+
+```bash
+grep -qxF '.wp/' .gitignore 2>/dev/null || echo '.wp/' >> .gitignore
+```
+
+If no `.gitignore` exists, create one containing exactly `.wp/`.
+
+Recommend appending worktree parent to gitignore when first worktree created:
+
+```bash
+# e.g. HerbalTech-missions/ sibling directory
+grep -qxF '${PROJECT_NAME}-missions/' .gitignore 2>/dev/null || echo '${PROJECT_NAME}-missions/' >> .gitignore
+```
+
+### 1b2 — Rename legacy `.missions/` → `.wp/` (run once)
+
+If `.missions/` exists and `.wp/` does not:
+
+```bash
+mv .missions .wp
+grep -qxF '.wp/' .gitignore 2>/dev/null || echo '.wp/' >> .gitignore
+sed -i.bak '/^\.missions\//d' .gitignore 2>/dev/null || sed -i '' '/^\.missions\//d' .gitignore
+rm -f .gitignore.bak
+```
+
+### 1c — Legacy migration (v1.2 → v1.3, run once)
+
+If flat v1.2 files exist at `.wp/*.md` or `.wp/handoffs/` and `.wp/instances/default/` does not exist:
+
+1. Create `.wp/instances/default/handoffs/`
+2. Move `mission_profile.md`, `validation_contract.md`, `active_plan.md`, `mission_control.md` → `instances/default/`
+3. Move `.wp/handoffs/*` → `instances/default/handoffs/`
+4. Bump `framework_version` to `1.3.0` in migrated `mission_control.md`
+5. Register `default` in `registry.md` (see reference.md)
+
+Do not move `agents/`, `skills/`, `hooks/`, or `archive/`.
+
+### 1d — Instance state files (templates in reference.md)
+
+| File | When missing |
+|------|--------------|
+| `.wp/registry.md` | Seed from template |
+| `.wp/instances/<mid>/instance_meta.md` | Seed with worktree metadata |
+| `.wp/instances/<mid>/mission_profile.md` | Seed from template |
+| `.wp/instances/<mid>/validation_contract.md` | Seed from template |
+| `.wp/instances/<mid>/active_plan.md` | Seed from template |
+| `.wp/instances/<mid>/mission_control.md` | Seed (`framework_version: 1.3.0`) |
+
+### 1e — Framework seeds (shared, idempotent)
+
+| File | Action |
+|------|--------|
+| `.wp/agents/orchestrator.md` | Copy `packages/agents/orchestrator.md` |
+| `.wp/hooks/run-assertions.sh` | Copy `packages/hooks/templates/run-assertions.sh` (chmod +x) |
+| `.wp/hooks/mission-worktree-bootstrap.sh` | Copy `packages/hooks/templates/mission-worktree-bootstrap.sh` (chmod +x) |
+| `.wp/skills/_index.md` | Seed from template |
+| `.wp/skills/caveman-wire.md` | Copy `packages/skills/wp/caveman-wire.md` |
+
+### 1f — Git worktree provisioning
+
+For `mid != default` and no `--no-worktree`:
+
+```bash
+.wp/hooks/mission-worktree-bootstrap.sh \
+  --project-root "$project_root" \
+  --mid "$mid" \
+  --meta-out ".wp/instances/$mid/instance_meta.md"
+```
+
+On success, record `worktree_root` in `instance_meta.md` and `registry.md`. Call `move_agent_to_root` on `worktree_root` when the current chat should continue in the worktree.
+
+For `mid == default` or `--no-worktree`: `worktree_root = project_root`; no worktree created.
+
+### 1g — Registry update
+
+After instance bootstrap, append or update row in `.wp/registry.md` (see reference.md).
+
+### 1h — Optional verification hooks
+
+If the project uses Cursor hooks and user has not declined: offer verification-checkpoint hooks from `~/.cursor/hooks/verification-checkpoint-*.sh`.
+
+### Bootstrap confirmation
+
+Print once when framework shell or new instance was created:
+
+```
+🚀 Waypoint Skills v1.3 initialized. Instance `<mid>` at `.wp/instances/<mid>/`.
+   Worktree: [path | project root]
+```
+
+## Phase 2: Orchestration Routing
+
+**Default: Task delegation** — invoke `orchestrator` subagent via Task tool.
+
+Do **not** adopt Orchestrator persona inline unless Task is unavailable.
+
+### Hand-off payload
+
+Use **caveman wire** format (see `.wp/skills/caveman-wire.md`):
+
+```markdown
+## Wire Hand-off
+
+obj: [verbatim user objective]
+mid: [mission id]
+boot: initialized|existing
+project_root: [absolute path to git repo]
+wp_root: .wp/instances/<mid>/
+worktree_root: [absolute path — where workers edit code]
+phase: [Scope|Contract|Plan|Delegation|Negotiation|Complete|Paused]
+pause: yes|no
+bg: yes|no
+style: caveman wire between agents; normal prose to user
+impl: ponytail full — reuse codebase before new code
+instr: current phase only; multi-tool/MCP → Task subagents; compact wire returns; all paths relative to wp_root unless code edits (worktree_root)
+```
+
+**Background policy:** `bg: yes` (Task `run_in_background: true`) for **new** instance starts. `bg: no` for `resume`, `--foreground`, or when user is in active negotiation on this `mid`.
+
+### Conflict handling (scoped to `mid`)
+
+| Situation | Action |
+|-----------|--------|
+| Same `mid`, new objective differs from `mission_profile.md` | Ask: **Resume** \| **Archive and restart** \| **Append as new epic** |
+| New `mid` | Create instance + worktree; register; do **not** touch other instances |
+| No `mid`, `default` active, user sends different objective | Ask: continue `default` or start `wp: @new-id …` |
+
+Never silently overwrite another instance's `mission_profile.md`.
+
+### Phase detection (per instance)
+
+Read from `wp_root` (not framework root):
+
+| Signal | Phase |
+|--------|-------|
+| `mission_control.md` has `pause: active` | Paused |
+| `mission_profile.md` mostly empty / only template | Scope |
+| Profile filled; contract lacks `approved: yes` | Contract |
+| Contract approved; plan empty or no tasks | Plan |
+| Exactly one task `in_progress`, no pending handoff review | Delegation |
+| Handoff or validation report exists for current task | Negotiation |
+| All tasks `complete` | Complete |
+
+On resume, Orchestrator opens with **Resume Summary** — never restart Scope unless user pivoted/archived.
+
+## Execution Order
+
+```
+1. Parse trigger + flags + mid + objective (or lifecycle command)
+2. Workspace precondition check
+3. Lifecycle command? → handle and stop (except resume → step 7)
+4. Phase 1a–1e: framework shell bootstrap if .wp/ missing
+5. Legacy migration (1c) if needed
+6. Phase 1d–1g: instance bootstrap + worktree for this mid
+7. Ensure orchestrator.md + seeds exist (idempotent)
+8. Phase detection from wp_root state
+9. Task → orchestrator subagent with hand-off payload (background per policy)
+```
+
+Never write application code in bootstrap/routing. Never skip gitignore isolation.
+
+## Mission Pipeline (Orchestrator owns after hand-off)
+
+```
+Scope → Contract (user approves) → Plan → Worker → Validator → Bookkeeping → next task
+                              ↑                                    |
+                              └──── BLOCK / revise-contract ───────┘
+```
+
+| After | Invoke via Task subagent |
+|-------|--------------------------|
+| Task assignment | `worker` (payload includes `worktree_root`, `wp_root`, `mid`) |
+| Worker handoff | `validator` (same `mid` + `wp_root`) |
+| Task status transition | `mission-control-bookkeeping` skill |
+| Reusable insight | `encode-skill` |
+
+## Approval Gates
+
+**Scope exit:** User confirms scope (`approve scope`, `scope lgtm`, or explicit edits + confirmation).
+
+**Contract exit:** Contract is NOT approved until user replies `approve contract`, `contract lgtm`, or edits + explicit confirmation. Orchestrator sets `Approved: yes` in `wp_root/validation_contract.md` only after user approval.
+
+## Mandatory Mission Skills
+
+### 1. Caveman — inter-agent state (mandatory)
+
+All agent-to-agent communication uses **caveman wire** per `.wp/skills/caveman-wire.md`. Handoffs live under `wp_root/handoffs/`.
+
+### 2. Ponytail — implementation (mandatory for worker)
+
+Worker and plan tasks follow **ponytail full** (`~/.cursor/skills/ponytail/SKILL.md`). Workers edit code in `worktree_root` only.
+
+## Context Preservation (mandatory)
+
+| Role | Delegates to | Keeps in context |
+|------|--------------|------------------|
+| wp skill / router | `orchestrator` via Task | objective, mid, phase, worktree_root |
+| orchestrator | `worker`, `validator`, `explore`, `shell` | plan state for this `mid` only |
+| worker | `explore`, `shell` for heavy Observe | single task; **worktree_root** for edits |
+| validator | `shell`, scrutiny, browser subagents | gate signal; same `mid` as worker |
+
+## Related Artifacts
+
+| Skill / agent | Role |
+|---------------|------|
+| `caveman-wire.md` / `caveman` skill | Inter-agent compressed state |
+| `ponytail` skill | Minimal implementation, reuse-first |
+| `wp` subagent | Isolated bootstrap + route via Task |
+| `orchestrator` subagent | Planning, delegation loop per instance |
+| `worker` subagent | Single-task implementation in worktree |
+| `validator` subagent | Assertion verification gate |
+| mission-control-bookkeeping | Ledger after task transitions |
+| `mission-worktree-bootstrap.sh` | Git worktree provisioning |
+
+## Additional Resources
+
+Templates, migration, worktree policy: [reference.md](reference.md)

package/packages/skills/wp/caveman-wire.md

@@ -0,0 +1,148 @@
+# Caveman Wire Protocol
+
+Inter-agent state in `.wp/instances/<mid>/` uses **caveman wire** — ultra-compressed, full technical accuracy, ~75% fewer tokens than prose handoffs.
+
+Applies to: orchestrator ↔ worker ↔ validator ↔ bookkeeping payloads, `wp_root/handoffs/*.md`, `Subagent Summary` blocks, mission_control ledger lines.
+
+**Not** for user-facing scope dialogue (normal prose unless user wants caveman). **Yes** for all agent-to-agent artifacts.
+
+Read full style rules: `~/.cursor/skills/caveman/SKILL.md`. Wire default: **caveman full**. Wire only: **caveman ultra**.
+
+## Path Conventions (v1.3)
+
+Every wire payload includes instance context:
+
+```markdown
+mid: [mission id]
+wp_root: .wp/instances/<mid>/
+worktree_root: [absolute path — application code edits]
+project_root: [absolute path — git repo anchor]
+```
+
+- **Handoffs / validation reports / plan artifacts:** under `wp_root`
+- **Application code edits:** under `worktree_root` only
+- Never write sibling instance paths
+
+## Wire Rules
+
+- Drop articles, filler, hedging. Fragments OK.
+- Pattern: `[thing] [action] [reason]. [next].`
+- Code paths, assertion IDs, exit codes, gate signals: **verbatim exact**
+- No tool-call narration, no emoji, no decorative tables in wire blocks
+- Errors: shortest decisive line only
+- User language preserved if present in source artifact
+
+## Hand-off Payload (orchestrator → worker)
+
+```markdown
+## Wire Hand-off
+
+mid: [id]
+obj: [task N title]
+assert: A-01,A-02
+bound-ok: src/mail/,src/api/
+bound-no: migrations/,infra/
+worktree_root: [absolute path]
+wp_root: .wp/instances/<mid>/
+out: .wp/instances/<mid>/handoffs/feature_[ID]_log.md
+impl: ponytail full — reuse before write
+style: caveman wire handoff
+```
+
+## Router → Orchestrator Payload
+
+```markdown
+## Wire Hand-off
+
+obj: [verbatim user objective]
+mid: [id]
+boot: initialized|existing
+project_root: [abs path]
+wp_root: .wp/instances/<mid>/
+worktree_root: [abs path]
+phase: [Scope|Contract|Plan|Delegation|Negotiation|Complete|Paused]
+pause: yes|no
+bg: yes|no
+style: caveman wire between agents; normal prose to user
+impl: ponytail full
+instr: current phase only; multi-tool → Task subagents; wire returns only
+```
+
+## Worker Handoff (`feature_[ID]_log.md`)
+
+```markdown
+# Wire T[N] [slug]
+
+mid: [id]
+status: complete|partial|blocked
+assert: A-01,A-02
+done: [files changed, behavior shipped — fragments]
+skip: [deferred or none]
+cmd: [cmd] → [exit]|...
+git: clean|dirty [scope]
+worktree: [path]
+arch: [issue or none]
+eval: A-01 met|A-02 partial
+rec: accept|modify-plan|revise-contract
+why: [one line max]
+```
+
+## Validator Report (`validation_[ID]_report.md`)
+
+```markdown
+# Wire Val T[N]
+
+mid: [id]
+gate: CLEAR|BLOCK
+handoff: feature_[ID]_log.md
+assert: A-01 pass|A-02 fail
+cmd: [cmd] → [exit]|...
+worktree: [path verified]
+runtime: [journey result fragment or deferred]
+fail: A-02 expected X got Y → worker-fix
+rec: clear|block
+```
+
+## Subagent Summary (return to parent)
+
+```markdown
+## Subagent Summary
+role: worker|validator|explore|shell
+mid: [id]
+status: complete|blocked|partial
+artifacts: [paths]
+gate: CLEAR|BLOCK|—
+block: [none|one line]
+worktree: [path if applicable]
+```
+
+## Ledger Line (`mission_control.md`)
+
+```markdown
+### [ISO] T[N]: [title]
+mid: [id]
+trans: in_progress→complete
+gate: CLEAR
+pct: 66.7
+follow: none
+note: [one fragment]
+```
+
+## State Pointer (orchestrator resume)
+
+```markdown
+mid: [id]
+phase: Delegation
+task: T2 in_progress
+last: feature_1_log CLEAR
+next: delegate worker T2
+worktree: [path]
+```
+
+## Auto-Clarity Exception
+
+Use full sentences (not wire) when:
+- Security / irreversible ops need user confirm
+- Ambiguous fragment would misroute next agent
+
+Resume wire after clear.