From 9ddc17b22815446081a562e27fe4bec9696b4b9c Mon Sep 17 00:00:00 2001
From: luke <fiorini@gmail.com>
Date: Mon, 9 Feb 2026 05:06:13 +0000
Subject: [PATCH] Add docs index and per-skill docs, link from main README

---
 README.md              | 24 ++++++++++++++----------
 docs/CREATE-PLAN.md    | 27 +++++++++++++++++++++++++++
 docs/README.md         |  9 +++++++++
 docs/WEB-AUTOMATION.md | 33 +++++++++++++++++++++++++++++++++
 4 files changed, 83 insertions(+), 10 deletions(-)
 create mode 100644 docs/CREATE-PLAN.md
 create mode 100644 docs/README.md
 create mode 100644 docs/WEB-AUTOMATION.md

diff --git a/README.md b/README.md
index 9087f84..1bef6b8 100644
--- a/README.md
+++ b/README.md
@@ -15,7 +15,10 @@ This repo is organized similarly to `obra/superpowers` and is designed to scale
 ai-coding-skills/
 ├── README.md
 ├── docs/
-│   └── INSTALL.md
+│   ├── README.md
+│   ├── INSTALL.md
+│   ├── CREATE-PLAN.md
+│   └── WEB-AUTOMATION.md
 ├── skills/
 │   ├── _template/
 │   │   └── SKILL.md
@@ -38,16 +41,17 @@ ai-coding-skills/
 
 ## Skills
 
-| Skill | Agent Variant | Purpose | Status |
-|---|---|---|---|
-| create-plan | codex | Structured planning with milestones + runbook-first execution workflow | Ready |
-| create-plan | claude-code | Structured planning with milestones + runbook-first execution workflow | Ready |
-| create-plan | opencode | Structured planning with milestones + runbook-first execution workflow | Ready |
-| web-automation | codex | Playwright + Camoufox browsing/scraping/auth automation | Ready |
-| web-automation | claude-code | Playwright + Camoufox browsing/scraping/auth automation | Ready |
-| web-automation | opencode | Playwright + Camoufox browsing/scraping/auth automation | Ready |
+| Skill | Agent Variant | Purpose | Status | Docs |
+|---|---|---|---|---|
+| create-plan | codex | Structured planning with milestones + runbook-first execution workflow | Ready | [CREATE-PLAN](docs/CREATE-PLAN.md) |
+| create-plan | claude-code | Structured planning with milestones + runbook-first execution workflow | Ready | [CREATE-PLAN](docs/CREATE-PLAN.md) |
+| create-plan | opencode | Structured planning with milestones + runbook-first execution workflow | Ready | [CREATE-PLAN](docs/CREATE-PLAN.md) |
+| web-automation | codex | Playwright + Camoufox browsing/scraping/auth automation | Ready | [WEB-AUTOMATION](docs/WEB-AUTOMATION.md) |
+| web-automation | claude-code | Playwright + Camoufox browsing/scraping/auth automation | Ready | [WEB-AUTOMATION](docs/WEB-AUTOMATION.md) |
+| web-automation | opencode | Playwright + Camoufox browsing/scraping/auth automation | Ready | [WEB-AUTOMATION](docs/WEB-AUTOMATION.md) |
 
-See install instructions: `docs/INSTALL.md`
+- Docs index: `docs/README.md`
+- Install guide: `docs/INSTALL.md`
 
 ## Compatibility Policy
 
diff --git a/docs/CREATE-PLAN.md b/docs/CREATE-PLAN.md
new file mode 100644
index 0000000..f92c0b6
--- /dev/null
+++ b/docs/CREATE-PLAN.md
@@ -0,0 +1,27 @@
+# CREATE-PLAN
+
+## Purpose
+
+Create structured implementation plans with milestone and story tracking.
+
+## Key Behavior
+
+- Requires Superpowers dependencies (`brainstorming`, `writing-plans`).
+- Creates plans under `ai_plan/YYYY-MM-DD-<short-title>/`.
+- Ensures `/ai_plan/` is in `.gitignore`.
+- Commits `.gitignore` update locally when added.
+- Produces:
+  - `original-plan.md`
+  - `final-transcript.md`
+  - `milestone-plan.md`
+  - `story-tracker.md`
+  - `continuation-runbook.md`
+
+## Execution Workflow Rules
+
+- Read runbook first.
+- Complete one milestone at a time.
+- Lint/typecheck/test (changed files first).
+- Commit (do not push), ask for feedback, apply feedback, commit again.
+- Move to next milestone only after approval.
+- Ask permission before final push.
diff --git a/docs/README.md b/docs/README.md
new file mode 100644
index 0000000..c19ff25
--- /dev/null
+++ b/docs/README.md
@@ -0,0 +1,9 @@
+# Skills Documentation
+
+This directory contains user-facing docs for each skill.
+
+## Index
+
+- [CREATE-PLAN.md](./CREATE-PLAN.md) — Planning workflow, milestones, feedback loop, and `ai_plan/` conventions.
+- [WEB-AUTOMATION.md](./WEB-AUTOMATION.md) — Playwright + Camoufox setup, dependency checks, and usage examples.
+- [INSTALL.md](./INSTALL.md) — Installation guide for all supported agent variants.
diff --git a/docs/WEB-AUTOMATION.md b/docs/WEB-AUTOMATION.md
new file mode 100644
index 0000000..88fb3ff
--- /dev/null
+++ b/docs/WEB-AUTOMATION.md
@@ -0,0 +1,33 @@
+# WEB-AUTOMATION
+
+## Purpose
+
+Automate browsing and scraping with Playwright + Camoufox.
+
+## Requirements
+
+- Node.js 20+
+- pnpm
+- `playwright-core`
+- `camoufox-js`
+
+## Setup Summary
+
+1. Install skill files for your agent.
+2. `cd .../skills/web-automation/scripts`
+3. `pnpm install`
+4. `pnpm add playwright-core camoufox-js`
+5. `npx camoufox-js fetch`
+
+## Dependency Checks
+
+```bash
+node -e "require.resolve('playwright-core/package.json');require.resolve('camoufox-js/package.json');console.log('OK: playwright-core + camoufox-js installed')"
+node -e "const fs=require('fs');const t=fs.readFileSync('browse.ts','utf8');if(!/camoufox-js/.test(t)){throw new Error('browse.ts is not configured for Camoufox')}console.log('OK: Camoufox integration detected in browse.ts')"
+```
+
+## Usage Examples
+
+- Browse: `npx tsx browse.ts --url "https://example.com"`
+- Scrape: `npx tsx scrape.ts --url "https://example.com" --mode main --output page.md`
+- Auth: `npx tsx auth.ts --url "https://example.com/login"`