waypoint-skills 1.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 quenginedev
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,348 @@
+# Waypoint Skills
+
+**Multi-platform agentic skills** for AI-powered assistants — Cursor, Claude Code, Codex, Antigravity, Copilot, and others. One GitHub URL installs the **wp** framework (skills, agents, rules, hooks) into whatever assistant you use.
+
+Repo: **waypoint.sk** · Display name: **Waypoint Skills**
+
+## Quick install
+
+**Recommended — npx CLI** (detects your assistants, installs skills + agents + rules):
+
+```bash
+npx waypoint-skills install -y
+```
+
+**Skills only** via [skills CLI](https://skills.sh) (no agents/rules):
+
+```bash
+npx skills add quenginedev/waypoint.sk -g -y
+npx skills add quenginedev/waypoint.sk --skill wp --skill ponytail -g -y
+```
+
+**From GitHub** (curl or clone):
+
+```bash
+# Auto-detect installed assistants and install globally
+curl -fsSL https://raw.githubusercontent.com/quenginedev/waypoint.sk/main/scripts/install.sh | bash -s -- --platform auto --global
+
+# Or clone and install
+git clone https://github.com/quenginedev/waypoint.sk.git
+cd waypoint.sk
+npx waypoint-skills install -y
+# or: ./scripts/install.sh --platform auto --global
+```
+
+**Single platform:**
+
+```bash
+./scripts/install.sh --platform claude --global
+./scripts/install.sh --platform cursor --local
+./scripts/install.sh --platform antigravity --global
+./scripts/install.sh --platform codex --global
+./scripts/install.sh --platform all --global
+```
+
+## Supported platforms
+
+| Platform | Global skills | Local skills | Agents | Rules | Hooks |
+|----------|---------------|--------------|--------|-------|-------|
+| **Cursor** | `~/.cursor/skills/` | `.cursor/skills/` | ✓ | ✓ `.mdc` | ✓ |
+| **Claude Code** | `~/.claude/skills/` | `.claude/skills/` | ✓ | — | — |
+| **Codex** | `~/.codex/skills/` | `.codex/skills/` | — | — | — |
+| **Antigravity** | `~/.gemini/antigravity/skills/` | `.agent/skills/` | — | ✓ | — |
+| **Copilot** | — | `.github/skills/` | — | — | — |
+| **Gemini CLI** | `~/.gemini/skills/` | `.gemini/skills/` | — | — | — |
+
+See [docs/PLATFORMS.md](docs/PLATFORMS.md) for paths and notes per assistant.
+
+## Packages
+
+| Skill | Trigger | Purpose |
+|-------|---------|---------|
+| **wp** | `/wp`, `wp:` | Bootstrap `.wp/`, route to orchestrator |
+| **caveman** | `caveman mode` | Compressed inter-agent communication |
+| **ponytail** | `ponytail`, `yagni` | Minimal implementation ladder |
+| **waypoint** | install, doctor | Install and manage Waypoint Skills |
+| **impeccable** | `/impeccable` | Production-grade frontend design & UI craft (Apache 2.0) |
+| **design-taste-frontend** | `/design-taste-frontend` | Anti-slop landing pages & portfolios (contextual design dials) |
+| **gpt-taste** | `/gpt-taste` | Awwwards-level GSAP motion & layout (randomized hero/bento) |
+| **stitch-design-taste** | `/stitch-design-taste` | Semantic `DESIGN.md` for Google Stitch screen generation |
+
+| Agent | Role |
+|-------|------|
+| **wp-router** | Bootstrap + router only |
+| **orchestrator** | Scope → contract → plan → delegate loop |
+| **worker** | Single-task implementation in git worktree |
+| **validator** | Adversarial assertion verification |
+
+Full reference: [docs/WAYPOINT-FLOW.md](docs/WAYPOINT-FLOW.md)
+
+---
+
+## How Waypoint Works
+
+Waypoint Skills is a **structured agent workflow** for building software with AI assistants. You install it once (skills + agents + rules), then drive work from any git project with `/wp`. The framework handles planning, serial execution, git isolation, and adversarial validation — without replacing your assistant.
+
+### End-to-end flow
+
+```mermaid
+flowchart LR
+  Install["1. Install Waypoint Skills"] --> Bootstrap["2. Bootstrap .wp/ in project"]
+  Bootstrap --> Trigger["3. /wp objective"]
+  Trigger --> Scope["4. Scope → user approves"]
+  Scope --> Contract["5. Contract → user approves"]
+  Contract --> Plan["6. Plan tasks"]
+  Plan --> Loop["7. Worker → Validator loop"]
+  Loop --> Done["8. Complete"]
+```
+
+1. **Install** — `install.sh` drops skills, agents, and rules into your assistant's native config (Cursor, Claude, Codex, Antigravity, …).
+2. **Bootstrap** — First `/wp` in a project creates `.wp/` runtime state (or run `waypoint bootstrap`).
+3. **Trigger** — `/wp [objective]` or `/wp @id [objective]` starts or resumes an instance.
+4. **Scope** — Orchestrator drafts what is in/out of scope; you reply `approve scope`.
+5. **Contract** — Behavior assertions (A-01, A-02, …) are written; you reply `approve contract`. **No app code until approved.**
+6. **Plan** — Work is split into serial tasks in `active_plan.md`.
+7. **Execute** — Worker implements one task → Validator verifies → next task (or remediation on BLOCK).
+8. **Complete** — All tasks pass validation; instance marked done.
+
+### Architecture
+
+```mermaid
+flowchart TB
+  subgraph User["You"]
+    U["/wp objective"]
+    U2["approve scope / contract"]
+  end
+
+  subgraph Router["wp Router (skill)"]
+    R1["Parse @mid + flags"]
+    R2["Bootstrap .wp/"]
+    R3["Phase detection"]
+    R4["Delegate → Orchestrator"]
+  end
+
+  subgraph State["Per-instance state (.wp/instances/mid/)"]
+    MP["mission_profile.md"]
+    VC["validation_contract.md"]
+    AP["active_plan.md"]
+    MC["mission_control.md"]
+    HO["handoffs/"]
+  end
+
+  subgraph Agents["Subagents"]
+    O["Orchestrator"]
+    W["Worker"]
+    V["Validator"]
+  end
+
+  subgraph Git["Code isolation"]
+    WT["worktree_root"]
+  end
+
+  U --> R1 --> R2 --> R3 --> R4 --> O
+  U2 --> O
+  O <--> MP & VC & AP & MC
+  O --> W --> HO
+  O --> V --> HO
+  W --> WT
+  V --> WT
+```
+
+The **wp router** only bootstraps and routes — it never writes application code. The **orchestrator** owns planning and delegation. The **worker** implements exactly one task. The **validator** adversarially checks assertions and emits `CLEAR` or `BLOCK`.
+
+### Execution pipeline
+
+```mermaid
+stateDiagram-v2
+  [*] --> Scope
+  Scope --> Contract: approve scope
+  Contract --> Plan: approve contract
+  Plan --> Delegation: tasks ready
+  Delegation --> Negotiation: worker handoff
+  Negotiation --> Delegation: gate CLEAR
+  Negotiation --> Plan: gate BLOCK
+  Delegation --> Complete: all tasks done
+```
+
+| Phase | Who runs it | What happens |
+|-------|-------------|--------------|
+| **Scope** | Orchestrator + you | Objective, in/out scope, allowed paths → `mission_profile.md` |
+| **Contract** | Orchestrator + you | Implementation-agnostic assertions → `validation_contract.md` |
+| **Plan** | Orchestrator | Serial tasks linked to assertions → `active_plan.md` |
+| **Delegation** | Orchestrator → Worker | One task `in_progress`; worker edits `worktree_root` only |
+| **Negotiation** | Orchestrator → Validator | Validator verifies contract; gate CLEAR or BLOCK |
+| **Complete** | Orchestrator | All tasks validated |
+
+### Worker → Validator loop
+
+```mermaid
+sequenceDiagram
+  participant O as Orchestrator
+  participant W as Worker
+  participant V as Validator
+  participant WT as worktree_root
+
+  O->>W: handoff (task, assertions, bounds)
+  W->>WT: implement (ponytail — minimal diff)
+  W->>O: feature_T1_log.md
+  O->>V: validate (same mid + worktree)
+  V->>WT: run checks, verify assertions
+  V->>O: validation_T1_report.md (CLEAR|BLOCK)
+  alt CLEAR
+    O->>O: next task
+  else BLOCK
+    O->>O: remediation or contract revise
+  end
+```
+
+Inter-agent messages use **caveman wire** (compressed handoffs in `.wp/instances/<mid>/handoffs/`). User-facing scope and contract dialogue stays in normal prose.
+
+### Runtime directory (`.wp/`)
+
+Every git project gets a local `.wp/` folder (gitignored):
+
+```
+.wp/
+├── registry.md              # all active instances
+├── agents/                  # orchestrator persona
+├── skills/                  # caveman-wire protocol
+├── hooks/                   # worktree + assertion scripts
+└── instances/<mid>/
+    ├── instance_meta.md     # worktree_root, branch
+    ├── mission_profile.md   # scope
+    ├── validation_contract.md
+    ├── active_plan.md       # serial tasks
+    ├── mission_control.md   # ledger, pause, metrics
+    └── handoffs/            # worker logs + validation reports
+```
+
+### Triggers and lifecycle
+
+| Input | Example | Effect |
+|-------|---------|--------|
+| `/wp` | `/wp add user auth` | Start/resume `default` instance |
+| `/wp @id` | `/wp @api-payments Stripe webhooks` | New instance + isolated git worktree |
+| `wp: list` | — | Show all instances (read-only) |
+| `wp: status` | — | Instance dashboard |
+| `wp: resume @id` | — | Continue at detected phase |
+| `wp: pause @id` | — | Halt orchestrator loop |
+| `wp: abort @id` | — | Archive instance |
+
+### Multi-instance parallelism
+
+Non-default `@id` instances get their own **git worktree** at `../<ProjectName>-missions/<mid>/`. State stays centralized in `.wp/` (symlinked into each worktree).
+
+```mermaid
+flowchart LR
+  PR["project_root + .wp/"]
+  WT1["../Project-missions/api/"]
+  WT2["../Project-missions/web/"]
+  PR --> WT1
+  PR --> WT2
+```
+
+| Rule | Policy |
+|------|--------|
+| Parallel OK | Different `@mid` → different worktrees |
+| Serial only | One worker per worktree at a time |
+| Validator | Must match worker's `mid` + `worktree_root` |
+| Isolation | Validator never reads worker chat history |
+
+### Install → first `/wp` (platform-agnostic)
+
+```mermaid
+flowchart TD
+  A["GitHub URL or clone"] --> B["install.sh --platform auto"]
+  B --> C{assistant}
+  C -->|Cursor| D["~/.cursor/skills, agents, rules"]
+  C -->|Claude| E["~/.claude/skills, agents"]
+  C -->|Codex| F["~/.codex/skills"]
+  C -->|Antigravity| G["~/.gemini/antigravity/skills"]
+  B --> H["Assistant loads wp skill"]
+  H --> I["/wp in any git repo"]
+```
+
+### Companion skills and rules
+
+| Skill / rule | Role |
+|--------------|------|
+| **wp** | Router — bootstrap `.wp/`, parse triggers, delegate |
+| **caveman** | Token-efficient inter-agent handoffs |
+| **ponytail** | YAGNI implementation ladder for workers |
+| **waypoint** | Install, doctor, bootstrap CLI |
+| **adversarial-context-isolation** | Validator runs blind to worker reasoning |
+| **serial-git-enforcement** | Clean git handoffs; one editor per worktree |
+
+### Quick start after install
+
+```text
+cd my-git-project
+/wp @feature-x build settings page
+# → approve scope
+# → approve contract
+# → orchestrator runs worker T1, validator, T2, …
+wp: status @feature-x
+```
+
+---
+
+```bash
+npx waypoint-skills doctor
+npx waypoint-skills install -y
+npx waypoint-skills status --platform cursor --global
+npx waypoint-skills bootstrap
+npx waypoint-skills bootstrap --mid api-payments
+npx waypoint-skills instances
+npx waypoint-skills instance --mid default
+npx waypoint-skills detect
+```
+
+## Start work (any supported assistant)
+
+After install, open any git project:
+
+```
+/wp implement user authentication with JWT
+/wp @api-payments add Stripe webhooks
+wp: list
+wp: status
+wp: resume @api-payments
+```
+
+Non-default `@id` instances get an isolated git worktree at `../<ProjectName>-missions/<mid>/`.
+
+## Repository layout
+
+```
+waypoint.sk/
+├── package.json            # npm package (npx waypoint-skills)
+├── cli/bin/cli.js          # Node CLI entry
+├── skills/                 # symlinks → packages/skills (npx skills add discovery)
+├── manifest.json           # platforms + package list
+├── packages/
+│   ├── skills/             # wp, caveman, ponytail, waypoint, impeccable, taste skills
+│   ├── agents/             # wp-router, orchestrator, worker, …
+│   ├── rules/
+│   └── hooks/templates/
+├── scripts/
+│   ├── install.sh
+│   ├── detect-platform.sh
+│   └── waypoint
+└── docs/
+    ├── PLATFORMS.md
+    └── WAYPOINT-FLOW.md      # extended flow reference
+```
+
+---
+
+```bash
+npx waypoint-skills uninstall --platform auto --global
+```
+
+## Framework version
+
+**1.3.0** — multi-instance namespacing + git worktrees per `@mid`.
+
+## License
+
+MIT — see individual skill frontmatter where specified.

package/README.npm.md

@@ -0,0 +1,56 @@
+# waypoint-skills
+
+Multi-platform **agentic skills** for AI assistants — Cursor, Claude Code, Codex, Antigravity, Copilot, and others. Installs the **wp** framework (skills, agents, rules, hooks).
+
+## Quick install
+
+```bash
+# Full install — skills + agents + rules + hooks (recommended)
+npx waypoint-skills install -y
+
+# Or explicit platform
+npx waypoint-skills install --platform cursor --global
+```
+
+After install, in any git project:
+
+```
+/wp implement user authentication
+wp: list
+```
+
+## Skills-only (via [skills CLI](https://skills.sh))
+
+Install individual skills without agents/rules:
+
+```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
+```
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `install` | Install to detected or chosen platforms |
+| `uninstall` | Remove installed symlinks/copies |
+| `detect` | List detected AI assistants |
+| `doctor` | Check jq, git, manifest |
+| `status` | Verify installed skills/agents/rules |
+| `bootstrap` | Create `.wp/` in current git repo |
+
+## Requirements
+
+- **bash** — install scripts
+- **jq** — platform manifest parsing (`brew install jq`)
+- **git** — wp worktrees
+
+## Links
+
+- Repo: [github.com/quenginedev/waypoint.sk](https://github.com/quenginedev/waypoint.sk)
+- Docs: [PLATFORMS.md](https://github.com/quenginedev/waypoint.sk/blob/main/docs/PLATFORMS.md)
+
+## License
+
+MIT

package/cli/bin/cli.js

@@ -0,0 +1,127 @@
+#!/usr/bin/env node
+
+/**
+ * Waypoint Skills CLI
+ *
+ * Usage:
+ *   npx waypoint-skills install [--platform auto] [--global|--local] [-y]
+ *   npx waypoint-skills doctor
+ *   npx waypoint-skills detect
+ *   npx waypoint-skills bootstrap [--mid ID]
+ *   npx waypoint-skills status
+ *   npx waypoint-skills uninstall
+ *
+ * Skills-only (via Vercel skills CLI):
+ *   npx skills add quenginedev/waypoint.sk -g -y
+ */
+
+import { readFileSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { repoRoot, waypointScript, installScript } from './lib/paths.mjs';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+const HELP = `Waypoint Skills CLI — multi-platform agentic skills (wp, agents, rules, hooks)
+
+Usage:
+  waypoint-skills install [options]   Install skills, agents, rules, hooks
+  waypoint-skills uninstall [options] Remove symlinks/copies
+  waypoint-skills detect              Show detected AI assistants
+  waypoint-skills doctor              Check prerequisites
+  waypoint-skills status [options]    Verify installed packages
+  waypoint-skills bootstrap [options] Bootstrap .wp/ in current git project
+  waypoint-skills instances           List wp instances
+  waypoint-skills instance --mid ID   Show instance state
+
+Install options (passed to install.sh):
+  --platform NAME   cursor | claude | codex | antigravity | copilot | gemini_cli | auto | all
+  --global          User-level config (default)
+  --local           Project-level config
+  --copy            Copy files instead of symlinking
+  --from PATH|URL   Source repo path or git URL
+  -y, --yes         Non-interactive (alias: --platform auto --global)
+
+Skills-only install (no agents/rules):
+  npx skills add quenginedev/waypoint.sk -g -y
+  npx skills add quenginedev/waypoint.sk --skill wp --skill ponytail -g -y
+
+Docs: https://github.com/quenginedev/waypoint.sk
+`;
+
+function version() {
+  const pkg = JSON.parse(readFileSync(join(repoRoot(), 'package.json'), 'utf8'));
+  console.log(pkg.version);
+}
+
+function runBash(scriptPath, args = []) {
+  const result = spawnSync('bash', [scriptPath, ...args], {
+    cwd: repoRoot(),
+    stdio: 'inherit',
+    env: process.env,
+  });
+  process.exit(result.status ?? 1);
+}
+
+function normalizeInstallArgs(args) {
+  const out = [...args];
+  if (out.includes('-y') || out.includes('--yes')) {
+    for (const flag of ['-y', '--yes']) {
+      const i = out.indexOf(flag);
+      if (i !== -1) out.splice(i, 1);
+    }
+    if (!out.includes('--platform')) {
+      out.push('--platform', 'auto');
+    }
+    if (!out.includes('--global') && !out.includes('--local')) {
+      out.push('--global');
+    }
+  }
+  return out;
+}
+
+async function main() {
+  const args = process.argv.slice(2);
+  const command = args[0];
+
+  if (!command || command === '--help' || command === '-h' || command === 'help') {
+    console.log(HELP);
+    process.exit(0);
+  }
+
+  if (command === '--version' || command === '-v' || command === 'version') {
+    version();
+    process.exit(0);
+  }
+
+  switch (command) {
+    case 'install':
+      runBash(installScript(), normalizeInstallArgs(args.slice(1)));
+      break;
+    case 'uninstall':
+      runBash(join(repoRoot(), 'scripts/uninstall.sh'), args.slice(1));
+      break;
+    case 'detect':
+      runBash(join(repoRoot(), 'scripts/detect-platform.sh'), args.slice(1));
+      break;
+    case 'doctor':
+    case 'status':
+    case 'bootstrap':
+    case 'instances':
+    case 'instance':
+    case 'mission-bootstrap':
+    case 'mission-list':
+    case 'mission-status':
+      runBash(waypointScript(), args);
+      break;
+    default:
+      console.error(`Unknown command: ${command}\n\nRun: npx waypoint-skills --help`);
+      process.exit(1);
+  }
+}
+
+main().catch((err) => {
+  console.error(err?.message || err);
+  process.exit(1);
+});

package/cli/bin/lib/paths.mjs

@@ -0,0 +1,31 @@
+import { existsSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+/** Package root (works from git clone or node_modules/waypoint-skills). */
+export function repoRoot() {
+  // cli/bin/lib -> cli/bin -> cli -> root
+  const root = join(__dirname, '..', '..', '..');
+  if (existsSync(join(root, 'manifest.json'))) return root;
+
+  // Fallback: walk up from cwd (dev monorepo edge case)
+  let dir = process.cwd();
+  for (let i = 0; i < 8; i += 1) {
+    if (existsSync(join(dir, 'manifest.json'))) return dir;
+    const parent = dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+
+  return root;
+}
+
+export function waypointScript() {
+  return join(repoRoot(), 'scripts/waypoint');
+}
+
+export function installScript() {
+  return join(repoRoot(), 'scripts/install.sh');
+}

package/cli/bin/postinstall.mjs

@@ -0,0 +1,25 @@
+/**
+ * Best-effort chmod for bash scripts after npm install.
+ * Non-fatal — install still works via `node cli/bin/cli.js`.
+ */
+import { chmodSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { repoRoot } from './lib/paths.mjs';
+
+const scripts = [
+  'scripts/waypoint',
+  'scripts/install.sh',
+  'scripts/uninstall.sh',
+  'scripts/detect-platform.sh',
+];
+
+for (const rel of scripts) {
+  const path = join(repoRoot(), rel);
+  if (existsSync(path)) {
+    try {
+      chmodSync(path, 0o755);
+    } catch {
+      // ignore on platforms without chmod semantics
+    }
+  }
+}