waypoint-skills 1.3.0

package/packages/skills/wp/reference.md

@@ -0,0 +1,411 @@
+# wp Reference
+
+Authoritative bootstrap lives in [SKILL.md](SKILL.md). Part of **Waypoint Skills** (repo: `waypoint.sk`).
+
+**Framework version:** 1.3.0 (multi-instance + git worktrees)
+
+## Directory Layout (v1.3)
+
+```
+.wp/
+├── registry.md
+├── agents/orchestrator.md
+├── skills/{_index.md,caveman-wire.md}
+├── hooks/{run-assertions.sh,mission-worktree-bootstrap.sh}
+├── archive/<mid>-YYYY-MM-DD-HHMM/
+└── instances/
+    └── <mid>/
+        ├── instance_meta.md
+        ├── mission_profile.md
+        ├── validation_contract.md
+        ├── active_plan.md
+        ├── mission_control.md
+        └── handoffs/
+```
+
+## Phase 1 — Bootstrap Templates
+
+### registry.md
+
+```markdown
+# Mission Registry
+
+| mid | objective | phase | pause | worktree_root | updated |
+|-----|-----------|-------|-------|---------------|---------|
+| default | | Scope | no | [project_root] | [ISO date] |
+```
+
+Update row on instance bootstrap, phase change, pause/resume, abort (remove row).
+
+### instance_meta.md
+
+```markdown
+# Instance Meta
+
+**mid:** [id]
+**framework_version:** 1.3.0
+**project_root:** [absolute path to git repo]
+**worktree_root:** [absolute path — code edits happen here]
+**branch:** mission/[mid] | main (default)
+**worktree_parent:** [path or —]
+**provisioned_at:** [ISO date]
+```
+
+For `default` or `--no-worktree`: `worktree_root` equals `project_root`, `branch: —`.
+
+### mission_profile.md
+
+```markdown
+# Mission Profile
+
+**mid:** [id]
+**Objective:**
+
+**Success definition:**
+
+## In scope
+
+-
+
+## Out of scope
+
+-
+
+## Technical boundaries
+- **Allowed paths:**
+- **Forbidden paths:**
+
+## Constraints
+
+- **Implementation:** ponytail full (reuse before write; YAGNI; shortest diff)
+- **Inter-agent comms:** caveman wire (see `.wp/skills/caveman-wire.md`)
+- **Code root:** [worktree_root from instance_meta.md]
+
+## Open questions
+
+-
+```
+
+### validation_contract.md
+
+```markdown
+# Validation Contract
+
+**mid:** [id]
+**Status:** draft
+**Approved:** no
+
+## Assertions
+
+| ID | Behavior (implementation-agnostic) | Verification method |
+|----|-----------------------------------|---------------------|
+| A-01 | | |
+
+## Approval
+
+Set `Approved: yes` only after user confirms with `approve contract` or equivalent.
+```
+
+### active_plan.md
+
+```markdown
+# Active Plan
+
+**mid:** [id]
+**Status:** current task — | blocked — no
+
+## Tasks
+
+### Task 1: [title]
+- **Status:** pending
+- **Assertions:** A-01
+- **Dependencies:** none
+- **Done when:**
+
+## Plan Changelog
+
+| Date | Change | Reason |
+|------|--------|--------|
+```
+
+### mission_control.md
+
+```markdown
+# Mission Control
+
+**framework_version:** 1.3.0
+**mid:** [id]
+**bootstrapped_at:** [ISO date]
+**orchestrator_source:** ~/.cursor/agents/orchestrator.md
+**Mission:** [from mission_profile.md objective]
+**worktree_root:** [from instance_meta.md]
+**Started:** [ISO date]
+**Last updated:** [ISO date]
+**Pause:** inactive
+
+## Dashboard
+
+| Metric | Value |
+|--------|-------|
+| Tasks complete | 0 / 0 |
+| Feature completion | 0% |
+| Cumulative tokens (known) | 0 |
+| Validation follow-up tasks | 0 |
+| Current task | — |
+| Blocked | no |
+
+## Validation Follow-ups
+
+| Task ID | Created | Reason | Source report |
+|---------|---------|--------|---------------|
+
+## Token / Caching Log
+
+| Date | Agent | Session notes | Tokens | Caching notes |
+|------|-------|---------------|--------|---------------|
+
+## Ledger
+
+Append-only event log (newest at bottom).
+```
+
+### skills/_index.md
+
+```markdown
+# Mission Skills Index
+
+Mandatory for all mission agents:
+
+| Skill | Path | Use |
+|-------|------|-----|
+| caveman-wire | .wp/skills/caveman-wire.md | Inter-agent handoffs, reports, ledger |
+| caveman (full) | ~/.cursor/skills/caveman/SKILL.md | Style reference |
+| ponytail (full) | ~/.cursor/skills/ponytail/SKILL.md | Worker implementation; orchestrator planning |
+```
+
+## Legacy Migration (v1.2 → v1.3)
+
+Run once when flat files exist at `.wp/` root.
+
+**Rename first:** if `.missions/` exists and `.wp/` does not, `mv .missions .wp` and update `.gitignore` (see SKILL.md §1b2).
+
+```bash
+set -euo pipefail
+MID=default
+INST=".wp/instances/$MID"
+LEGACY_PROFILE=".wp/mission_profile.md"
+
+[[ -f "$LEGACY_PROFILE" && ! -d "$INST" ]] || exit 0
+
+mkdir -p "$INST/handoffs"
+for f in mission_profile validation_contract active_plan mission_control; do
+  [[ -f ".wp/${f}.md" ]] && mv ".wp/${f}.md" "$INST/"
+done
+[[ -d .wp/handoffs ]] && mv .wp/handoffs/* "$INST/handoffs/" 2>/dev/null || true
+rmdir .wp/handoffs 2>/dev/null || true
+
+# instance_meta for default (no worktree)
+PROJECT_ROOT="$(pwd)"
+cat >"$INST/instance_meta.md" <<EOF
+# Instance Meta
+
+**mid:** default
+**framework_version:** 1.3.0
+**project_root:** ${PROJECT_ROOT}
+**worktree_root:** ${PROJECT_ROOT}
+**branch:** —
+**worktree_parent:** —
+**provisioned_at:** $(date -u +%Y-%m-%dT%H:%M:%SZ)
+EOF
+
+# Bump framework version in control file
+sed -i.bak 's/framework_version:.*/framework_version:** 1.3.0/' "$INST/mission_control.md" 2>/dev/null \
+  || sed -i '' 's/framework_version:.*/framework_version:** 1.3.0/' "$INST/mission_control.md"
+rm -f "$INST/mission_control.md.bak"
+
+echo "Migrated legacy .wp/ → instances/default/"
+```
+
+Then seed or update `registry.md` with the `default` row.
+
+## Worktree Policy
+
+| mid | Worktree | Code edits in |
+|-----|----------|---------------|
+| `default` | none (unless user overrides) | `project_root` |
+| any other `@id` | `../<ProjectName>-missions/<mid>/` | `worktree_root` |
+| `--no-worktree` | none | `project_root` |
+
+Worktree bootstrap:
+
+```bash
+.wp/hooks/mission-worktree-bootstrap.sh \
+  --project-root "$(pwd)" \
+  --mid "$MID" \
+  --meta-out ".wp/instances/$MID/instance_meta.md"
+```
+
+The script symlinks `.wp` from project root into the worktree so instance state stays centralized.
+
+**gitignore** (recommend on first worktree):
+
+```bash
+PN="$(basename "$(pwd)")"
+grep -qxF "${PN}-missions/" .gitignore 2>/dev/null || echo "${PN}-missions/" >> .gitignore
+```
+
+## gitignore Rules
+
+```bash
+grep -qxF '.wp/' .gitignore 2>/dev/null || echo '.wp/' >> .gitignore
+```
+
+## Objective Extraction Examples
+
+| User input | mid | Objective |
+|------------|-----|-----------|
+| `/wp add checkout emails` | default | `add checkout emails` |
+| `/wp @api-payments add Stripe webhooks` | api-payments | `add Stripe webhooks` |
+| `wp: --id=web-ui checkout page` | web-ui | `checkout page` |
+| `wp: @api status` | api | lifecycle → status |
+| `wp: list` | — | lifecycle → list |
+| `wp: resume @api-payments` | api-payments | lifecycle → resume |
+
+## Phase Detection (full, per instance)
+
+| Signal | Phase |
+|--------|-------|
+| `Pause: active` in `wp_root/mission_control.md` | Paused |
+| mission_profile Objective empty | Scope |
+| Profile filled; contract Approved: no | Contract |
+| Approved: yes; no ### Task sections | Plan |
+| One task in_progress; no handoff for it | Delegation |
+| feature_[ID]_log.md or validation_[ID]_report.md for current task | Negotiation |
+| All tasks complete | Complete |
+
+## Resume Summary Template
+
+```markdown
+## Mission resumed — [Phase] (@[mid])
+
+**Objective:** [from mission_profile.md]
+**Instance:** [mid]
+**Worktree:** [worktree_root]
+**Framework:** v[framework_version]
+**Last activity:** [from ledger or active_plan changelog]
+**Current task:** [N — title] ([status])
+**Gate:** [CLEAR | BLOCK | pending | —]
+**Next:** [single concrete action]
+
+[Phase-appropriate content — do NOT restart Scope unless user pivoted]
+```
+
+## Scope Phase — First Reply Template
+
+```markdown
+## Scope Phase — [objective summary] (@[mid])
+
+Framework initialized (or resumed at **[phase]**).
+Worktree: [worktree_root]
+
+To define scope before we write a validation contract:
+
+1. [Success definition]
+2. [Non-goals / out of scope]
+3. [Constraints — stack, timeline, forbidden approaches]
+
+**Draft scope** (edit as needed):
+- In scope: …
+- Out of scope: …
+- Allowed paths: …
+- Forbidden paths: …
+```
+
+## Empty Objective Help
+
+```markdown
+## Mission — needs objective
+
+Provide: `wp: [@id] [what you want built or fixed]`
+
+**Lifecycle commands:**
+- `wp: list` — all active instances
+- `wp: status` — all instances (or `wp: @id status`)
+- `wp: resume [@id]` — continue instance
+- `wp: pause [@id]` — halt instance loop
+- `wp: abort [@id]` — archive instance
+- `wp: pivot: [new objective]` — change direction within instance
+
+**Parallel missions:** use distinct `@id` per chat tab; each non-default id gets its own git worktree.
+```
+
+## Multi-Instance Status Dashboard
+
+```markdown
+## Mission Registry
+
+| mid | phase | pause | objective | worktree |
+|-----|-------|-------|-----------|----------|
+| default | Delegation | no | … | [project root] |
+| api-payments | Contract | no | … | …/HerbalTech-missions/api-payments |
+```
+
+## orchestrator.md Missing
+
+1. Copy from `~/.cursor/agents/orchestrator.md` if present
+2. Else Task → `orchestrator` subagent with hand-off payload from SKILL.md
+
+## Verification Hooks (optional)
+
+Offer to copy from `~/.cursor/hooks/`:
+
+- `verification-checkpoint-on-handoff.sh`
+- `verification-checkpoint-on-validation-report.sh`
+- `verification-checkpoint-gate-plan.sh`
+- `lib/verification-checkpoint-common.sh`
+
+Project-local runner: `.wp/hooks/run-assertions.sh`
+
+## Archive on abort (per instance)
+
+```bash
+MID="api-payments"
+ARCHIVE=".wp/archive/${MID}-$(date +%Y-%m-%d-%H%M)"
+INST=".wp/instances/${MID}"
+
+mkdir -p "$ARCHIVE"
+mv "$INST" "$ARCHIVE/"
+
+# Optional: remove worktree (confirm with user first)
+# META worktree path from archived instance_meta.md
+# git worktree remove "$WORKTREE_PATH"
+# git branch -D "mission/${MID}"  # only if merged/abandoned
+
+# Remove row from registry.md
+```
+
+Framework shell (`agents/`, `skills/`, `hooks/`, `registry.md`) stays in place.
+
+## Subagent Return Format (caveman wire)
+
+```markdown
+## Subagent Summary
+role: worker|validator|explore|shell
+mid: [id]
+status: complete|blocked|partial
+artifacts: [paths under wp_root]
+gate: CLEAR|BLOCK|—
+block: [none|one line]
+worktree: [path if worker]
+```
+
+## Ponytail in Mission
+
+| Phase | Ponytail rule |
+|-------|---------------|
+| Scope | Ask: feature need exist? defer speculative work |
+| Plan | Fewest tasks; no scaffolding "for later" |
+| Worker | Full ladder in **worktree_root** |
+| Validator | Reject over-engineered tests that shape to implementation |
+
+Worker handoff `skip:` field documents YAGNI deferrals.

package/scripts/detect-platform.sh

@@ -0,0 +1,32 @@
+#!/usr/bin/env bash
+# Detect AI assistant platforms with install paths on this machine.
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=lib/common.sh
+source "${SCRIPT_DIR}/lib/common.sh"
+
+command -v jq >/dev/null 2>&1 || die "jq required"
+
+echo "Waypoint Skills — platform detection"
+echo ""
+
+printf "%-14s %-8s %-40s %s\n" "PLATFORM" "FOUND?" "GLOBAL" "LOCAL (cwd)"
+for p in $(list_platforms); do
+  gb="$(platform_config "$p" global_base)"
+  lb="$(platform_config "$p" local_base)"
+  found="no"
+  [[ -n "$gb" && "$gb" != "null" && -d "$(expand_path "$gb")" ]] && found="yes"
+  [[ "$found" == "no" && -n "$lb" && "$lb" != "null" && -d "$(expand_path "$lb")" ]] && found="yes"
+  label="$(platform_config "$p" label)"
+  printf "%-14s %-8s %-40s %s\n" "$p" "$found" "${gb:-—}" "${lb:-—} ($label)"
+done
+
+echo ""
+installed="$(detect_installed_platforms | tr '\n' ' ')"
+if [[ -n "${installed// /}" ]]; then
+  echo "Detected: $installed"
+  echo "Install all detected: ./scripts/install.sh --platform auto --global"
+else
+  echo "No platform config dirs found. Install a target assistant first, or use --platform <name>."
+fi

package/scripts/install.sh

@@ -0,0 +1,123 @@
+#!/usr/bin/env bash
+# Install Waypoint Skills into AI assistant config (Cursor, Claude, Codex, Antigravity, …)
+#
+# Usage:
+#   ./scripts/install.sh [--platform NAME|auto|all] [--global|--local] [--copy] [--from PATH|URL]
+#   curl -fsSL https://raw.githubusercontent.com/USER/waypoint.sk/main/scripts/install.sh | bash -s -- --platform auto --global
+#
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=lib/common.sh
+source "${SCRIPT_DIR}/lib/common.sh"
+
+SCOPE="global"
+MODE="symlink"
+FROM=""
+PLATFORM="auto"
+REPO_ROOT=""
+
+usage() {
+  cat <<'EOF'
+Waypoint Skills installer
+
+Usage: install.sh [options]
+
+Options:
+  --platform NAME  cursor | claude | codex | antigravity | copilot | gemini_cli | auto | all
+                   auto = install to detected platforms (default)
+  --global         User-level config (default)
+  --local          Project-level config in current directory
+  --copy           Copy files instead of symlinking
+  --from PATH      Source repo path or git URL
+  -h, --help       Show help
+
+Examples:
+  ./scripts/install.sh --platform auto --global
+  ./scripts/install.sh --platform claude --global
+  ./scripts/install.sh --platform cursor --local --copy
+  ./scripts/detect-platform.sh
+EOF
+  exit "${1:-0}"
+}
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --platform) PLATFORM="$2"; shift 2 ;;
+    --global) SCOPE="global"; shift ;;
+    --local) SCOPE="local"; shift ;;
+    --copy) MODE="copy"; shift ;;
+    --from) FROM="$2"; shift 2 ;;
+    -h|--help) usage 0 ;;
+    *) die "Unknown option: $1 (try --help)" ;;
+  esac
+done
+
+REPO_ROOT="$(cd "${SCRIPT_DIR}/.." && pwd)"
+
+if [[ -n "$FROM" ]]; then
+  if [[ "$FROM" =~ ^https?:// || "$FROM" =~ ^git@ ]]; then
+    TMPDIR="$(mktemp -d)"
+    trap 'rm -rf "$TMPDIR"' EXIT
+    log "cloning $FROM ..."
+    git clone --depth 1 "$FROM" "$TMPDIR/waypoint.sk"
+    REPO_ROOT="$TMPDIR/waypoint.sk"
+    WAYPOINT_REPO_ROOT="$REPO_ROOT"
+  elif [[ -d "$FROM" ]]; then
+    REPO_ROOT="$(cd "$FROM" && pwd)"
+    WAYPOINT_REPO_ROOT="$REPO_ROOT"
+  else
+    die "--from path not found: $FROM"
+  fi
+fi
+
+command -v jq >/dev/null 2>&1 || die "jq required (brew install jq / apt install jq)"
+
+resolve_platforms() {
+  case "$PLATFORM" in
+    auto)
+      detect_installed_platforms
+      ;;
+    all)
+      list_platforms
+      ;;
+    *)
+      list_platforms | grep -qxF "$PLATFORM" || die "Unknown platform: $PLATFORM"
+      echo "$PLATFORM"
+      ;;
+  esac
+}
+
+PLATFORMS="$(resolve_platforms)"
+[[ -n "${PLATFORMS// /}" ]] || die "No platforms to install. Run ./scripts/detect-platform.sh or pass --platform <name>."
+
+INSTALLED=()
+while IFS= read -r p; do
+  [[ -z "$p" ]] && continue
+  base="$(install_platform "$p" "$SCOPE" "$MODE" "$REPO_ROOT")"
+  INSTALLED+=("$p → $base")
+done <<< "$PLATFORMS"
+
+chmod +x "${REPO_ROOT}/scripts/waypoint" "${REPO_ROOT}/scripts/install.sh" \
+  "${REPO_ROOT}/scripts/uninstall.sh" "${REPO_ROOT}/scripts/detect-platform.sh" 2>/dev/null || true
+
+cat <<EOF
+
+✅ Waypoint Skills installed (scope=${SCOPE}, mode=${MODE})
+
+$(printf '  %s\n' "${INSTALLED[@]}")
+
+Skills: wp, caveman, ponytail, waypoint, impeccable, design-taste-frontend, gpt-taste, stitch-design-taste
+Trigger: /wp [objective]   or   wp: list | status | resume
+
+CLI:
+  npx waypoint-skills install -y
+  npx waypoint-skills doctor
+  npx waypoint-skills bootstrap
+
+Skills only:
+  npx skills add quenginedev/waypoint.sk -g -y
+
+Docs: docs/PLATFORMS.md, docs/WAYPOINT-FLOW.md
+
+EOF