opengstack 0.13.7 → 0.13.9

package/skills/browse/test/watch.test.ts

@@ -0,0 +1,129 @@
+/**
+ * Tests for watch mode state machine in BrowserManager.
+ *
+ * Pure unit tests — no browser needed. Just instantiate BrowserManager
+ * and test the watch state methods (startWatch, stopWatch, addWatchSnapshot,
+ * isWatching).
+ */
+
+import { describe, test, expect } from 'bun:test';
+import { BrowserManager } from '../src/browser-manager';
+
+describe('watch mode — state machine', () => {
+  test('isWatching returns false by default', () => {
+    const bm = new BrowserManager();
+    expect(bm.isWatching()).toBe(false);
+  });
+
+  test('startWatch sets isWatching to true', () => {
+    const bm = new BrowserManager();
+    bm.startWatch();
+    expect(bm.isWatching()).toBe(true);
+  });
+
+  test('stopWatch clears isWatching and returns snapshots', () => {
+    const bm = new BrowserManager();
+    bm.startWatch();
+    bm.addWatchSnapshot('snapshot-1');
+    bm.addWatchSnapshot('snapshot-2');
+
+    const result = bm.stopWatch();
+    expect(bm.isWatching()).toBe(false);
+    expect(result.snapshots).toEqual(['snapshot-1', 'snapshot-2']);
+    expect(result.snapshots.length).toBe(2);
+  });
+
+  test('stopWatch returns correct duration (approximately)', async () => {
+    const bm = new BrowserManager();
+    bm.startWatch();
+
+    // Wait ~50ms to get a measurable duration
+    await new Promise(resolve => setTimeout(resolve, 50));
+
+    const result = bm.stopWatch();
+    // Duration should be at least 40ms (allowing for timer imprecision)
+    expect(result.duration).toBeGreaterThanOrEqual(40);
+    // And less than 5 seconds (sanity check)
+    expect(result.duration).toBeLessThan(5000);
+  });
+
+  test('addWatchSnapshot stores snapshots', () => {
+    const bm = new BrowserManager();
+    bm.startWatch();
+
+    bm.addWatchSnapshot('page A content');
+    bm.addWatchSnapshot('page B content');
+    bm.addWatchSnapshot('page C content');
+
+    const result = bm.stopWatch();
+    expect(result.snapshots.length).toBe(3);
+    expect(result.snapshots[0]).toBe('page A content');
+    expect(result.snapshots[1]).toBe('page B content');
+    expect(result.snapshots[2]).toBe('page C content');
+  });
+
+  test('stopWatch resets snapshots for next cycle', () => {
+    const bm = new BrowserManager();
+
+    // First cycle
+    bm.startWatch();
+    bm.addWatchSnapshot('first-cycle-snapshot');
+    const result1 = bm.stopWatch();
+    expect(result1.snapshots.length).toBe(1);
+
+    // Second cycle — should start fresh
+    bm.startWatch();
+    const result2 = bm.stopWatch();
+    expect(result2.snapshots.length).toBe(0);
+  });
+
+  test('multiple start/stop cycles work correctly', () => {
+    const bm = new BrowserManager();
+
+    // Cycle 1
+    bm.startWatch();
+    expect(bm.isWatching()).toBe(true);
+    bm.addWatchSnapshot('snap-1');
+    const r1 = bm.stopWatch();
+    expect(bm.isWatching()).toBe(false);
+    expect(r1.snapshots).toEqual(['snap-1']);
+
+    // Cycle 2
+    bm.startWatch();
+    expect(bm.isWatching()).toBe(true);
+    bm.addWatchSnapshot('snap-2a');
+    bm.addWatchSnapshot('snap-2b');
+    const r2 = bm.stopWatch();
+    expect(bm.isWatching()).toBe(false);
+    expect(r2.snapshots).toEqual(['snap-2a', 'snap-2b']);
+
+    // Cycle 3 — no snapshots added
+    bm.startWatch();
+    expect(bm.isWatching()).toBe(true);
+    const r3 = bm.stopWatch();
+    expect(bm.isWatching()).toBe(false);
+    expect(r3.snapshots).toEqual([]);
+  });
+
+  test('stopWatch clears watchInterval if set', () => {
+    const bm = new BrowserManager();
+    bm.startWatch();
+
+    // Simulate an interval being set (as the server does)
+    bm.watchInterval = setInterval(() => {}, 100000);
+    expect(bm.watchInterval).not.toBeNull();
+
+    bm.stopWatch();
+    expect(bm.watchInterval).toBeNull();
+  });
+
+  test('stopWatch without startWatch returns empty results', () => {
+    const bm = new BrowserManager();
+
+    // Calling stopWatch without startWatch should not throw
+    const result = bm.stopWatch();
+    expect(result.snapshots).toEqual([]);
+    expect(result.duration).toBeLessThanOrEqual(Date.now()); // duration = now - 0
+    expect(bm.isWatching()).toBe(false);
+  });
+});

package/skills/careful/bin/check-careful.sh

@@ -0,0 +1,112 @@
+#!/usr/bin/env bash
+# check-careful.sh — PreToolUse hook for /careful skill
+# Reads JSON from stdin, checks Bash command for destructive patterns.
+# Returns {"permissionDecision":"ask","message":"..."} to warn, or {} to allow.
+set -euo pipefail
+
+# Read stdin (JSON with tool_input)
+INPUT=$(cat)
+
+# Extract the "command" field value from tool_input
+# Try grep/sed first (handles 99% of cases), fall back to Python for escaped quotes
+CMD=$(printf '%s' "$INPUT" | grep -o '"command"[[:space:]]*:[[:space:]]*"[^"]*"' | head -1 | sed 's/.*:[[:space:]]*"//;s/"$//' || true)
+
+# Python fallback if grep returned empty (e.g., escaped quotes in command)
+if [ -z "$CMD" ]; then
+  CMD=$(printf '%s' "$INPUT" | python3 -c 'import sys,json; print(json.loads(sys.stdin.read()).get("tool_input",{}).get("command",""))' 2>/dev/null || true)
+fi
+
+# If we still couldn't extract a command, allow
+if [ -z "$CMD" ]; then
+  echo '{}'
+  exit 0
+fi
+
+# Normalize: lowercase for case-insensitive SQL matching
+CMD_LOWER=$(printf '%s' "$CMD" | tr '[:upper:]' '[:lower:]')
+
+# --- Check for safe exceptions (rm -rf of build artifacts) ---
+if printf '%s' "$CMD" | grep -qE 'rm\s+(-[a-zA-Z]*r[a-zA-Z]*\s+|--recursive\s+)' 2>/dev/null; then
+  SAFE_ONLY=true
+  RM_ARGS=$(printf '%s' "$CMD" | sed -E 's/.*rm\s+(-[a-zA-Z]+\s+)*//;s/--recursive\s*//')
+  for target in $RM_ARGS; do
+    case "$target" in
+      */node_modules|node_modules|*/\.next|\.next|*/dist|dist|*/__pycache__|__pycache__|*/\.cache|\.cache|*/build|build|*/\.turbo|\.turbo|*/coverage|coverage)
+        ;; # safe target
+      -*)
+        ;; # flag, skip
+      *)
+        SAFE_ONLY=false
+        break
+        ;;
+    esac
+  done
+  if [ "$SAFE_ONLY" = true ]; then
+    echo '{}'
+    exit 0
+  fi
+fi
+
+# --- Destructive pattern checks ---
+WARN=""
+PATTERN=""
+
+# rm -rf / rm -r / rm --recursive
+if printf '%s' "$CMD" | grep -qE 'rm\s+(-[a-zA-Z]*r|--recursive)' 2>/dev/null; then
+  WARN="Destructive: recursive delete (rm -r). This permanently removes files."
+  PATTERN="rm_recursive"
+fi
+
+# DROP TABLE / DROP DATABASE
+if [ -z "$WARN" ] && printf '%s' "$CMD_LOWER" | grep -qE 'drop\s+(table|database)' 2>/dev/null; then
+  WARN="Destructive: SQL DROP detected. This permanently deletes database objects."
+  PATTERN="drop_table"
+fi
+
+# TRUNCATE
+if [ -z "$WARN" ] && printf '%s' "$CMD_LOWER" | grep -qE '\btruncate\b' 2>/dev/null; then
+  WARN="Destructive: SQL TRUNCATE detected. This deletes all rows from a table."
+  PATTERN="truncate"
+fi
+
+# git push --force / git push -f
+if [ -z "$WARN" ] && printf '%s' "$CMD" | grep -qE 'git\s+push\s+.*(-f\b|--force)' 2>/dev/null; then
+  WARN="Destructive: git force-push rewrites remote history. Other contributors may lose work."
+  PATTERN="git_force_push"
+fi
+
+# git reset --hard
+if [ -z "$WARN" ] && printf '%s' "$CMD" | grep -qE 'git\s+reset\s+--hard' 2>/dev/null; then
+  WARN="Destructive: git reset --hard discards all uncommitted changes."
+  PATTERN="git_reset_hard"
+fi
+
+# git checkout . / git restore .
+if [ -z "$WARN" ] && printf '%s' "$CMD" | grep -qE 'git\s+(checkout|restore)\s+\.' 2>/dev/null; then
+  WARN="Destructive: discards all uncommitted changes in the working tree."
+  PATTERN="git_discard"
+fi
+
+# kubectl delete
+if [ -z "$WARN" ] && printf '%s' "$CMD" | grep -qE 'kubectl\s+delete' 2>/dev/null; then
+  WARN="Destructive: kubectl delete removes Kubernetes resources. May impact production."
+  PATTERN="kubectl_delete"
+fi
+
+# docker rm -f / docker system prune
+if [ -z "$WARN" ] && printf '%s' "$CMD" | grep -qE 'docker\s+(rm\s+-f|system\s+prune)' 2>/dev/null; then
+  WARN="Destructive: Docker force-remove or prune. May delete running containers or cached images."
+  PATTERN="docker_destructive"
+fi
+
+# --- Output ---
+if [ -n "$WARN" ]; then
+  # Log hook fire event (pattern name only, never command content)
+  mkdir -p ~/.gstack/analytics 2>/dev/null || true
+  echo '{"event":"hook_fire","skill":"careful","pattern":"'"$PATTERN"'","ts":"'$(date -u +%Y-%m-%dT%H:%M:%SZ)'","repo":"'$(basename "$(git rev-parse --show-toplevel 2>/dev/null)" 2>/dev/null || echo "unknown")'"}' >> ~/.gstack/analytics/skill-usage.jsonl 2>/dev/null || true
+
+  WARN_ESCAPED=$(printf '%s' "$WARN" | sed 's/"/\\"/g')
+  printf '{"permissionDecision":"ask","message":"[careful] %s"}\n' "$WARN_ESCAPED"
+else
+  echo '{}'
+fi

package/skills/cso/ACKNOWLEDGEMENTS.md

@@ -0,0 +1,14 @@
+# Acknowledgements
+
+/cso v2 was informed by research across the security audit landscape. Credits to:
+
+- **[Sentry Security Review](https://github.com/getsentry/skills)** — The confidence-based reporting system (only HIGH confidence findings get reported) and the "research before reporting" methodology (trace data flow, check upstream validation) validated our 8/10 daily confidence gate. TimOnWeb rated it the only security skill worth installing out of 5 tested.
+- **[Trail of Bits Skills](https://github.com/trailofbits/skills)** — The audit-context-building methodology (build a mental model before hunting bugs) directly inspired Phase 0. Their variant analysis concept (found one vuln? Search the whole codebase for the same pattern) inspired Phase 12's variant analysis step.
+- **[Shannon by Keygraph](https://github.com/KeygraphHQ/shannon)** — Autonomous AI pentester achieving 96.15% on the XBOW benchmark (100/104 exploits). Validated that AI can do real security testing, not just checklist scanning. Our Phase 12 active verification is the static-analysis version of what Shannon does live.
+- **[afiqiqmal/claude-security-audit](https://github.com/afiqiqmal/claude-security-audit)** — The AI/LLM-specific security checks (prompt injection, RAG poisoning, tool calling permissions) inspired Phase 7. Their framework-level auto-detection (detecting "Next.js" not just "Node/TypeScript") inspired Phase 0's framework detection step.
+- **[Snyk ToxicSkills Research](https://snyk.io/blog/toxicskills-malicious-ai-agent-skills-clawhub/)** — The finding that 36% of AI agent skills have security flaws and 13.4% are malicious inspired Phase 8 (Skill Supply Chain scanning).
+- **[Daniel Miessler's Personal AI Infrastructure](https://github.com/danielmiessler/Personal_AI_Infrastructure)** — The incident response playbooks and protection file concept informed the remediation and LLM security phases.
+- **[McGo/claude-code-security-audit](https://github.com/McGo/claude-code-security-audit)** — The idea of generating shareable reports and actionable epics informed our report format evolution.
+- **[Claude Code Security Pack](https://dev.to/myougatheaxo/automate-owasp-security-audits-with-claude-code-security-pack-4mah)** — Modular approach (separate /security-audit, /secret-scanner, /deps-check skills) validated that these are distinct concerns. Our unified approach sacrifices modularity for cross-phase reasoning.
+- **[Anthropic Claude Code Security](https://www.anthropic.com/news/claude-code-security)** — Multi-stage verification and confidence scoring validated our parallel finding verification approach. Found 500+ zero-days in open source.
+- **[@gus_argon](https://x.com/gus_aragon/status/2035841289602904360)** — Identified critical v1 blind spots: no stack detection (runs all-language patterns), uses bash grep instead of Claude Code's Grep tool, `| head -20` truncates results silently, and preamble bloat. These directly shaped v2's stack-first approach and Grep tool mandate.

package/skills/freeze/bin/check-freeze.sh

@@ -0,0 +1,79 @@
+#!/usr/bin/env bash
+# check-freeze.sh — PreToolUse hook for /freeze skill
+# Reads JSON from stdin, checks if file_path is within the freeze boundary.
+# Returns {"permissionDecision":"deny","message":"..."} to block, or {} to allow.
+set -euo pipefail
+
+# Read stdin
+INPUT=$(cat)
+
+# Locate the freeze directory state file
+STATE_DIR="${CLAUDE_PLUGIN_DATA:-$HOME/.gstack}"
+FREEZE_FILE="$STATE_DIR/freeze-dir.txt"
+
+# If no freeze file exists, allow everything (not yet configured)
+if [ ! -f "$FREEZE_FILE" ]; then
+  echo '{}'
+  exit 0
+fi
+
+FREEZE_DIR=$(tr -d '[:space:]' < "$FREEZE_FILE")
+
+# If freeze dir is empty, allow
+if [ -z "$FREEZE_DIR" ]; then
+  echo '{}'
+  exit 0
+fi
+
+# Extract file_path from tool_input JSON
+# Try grep/sed first, fall back to Python for escaped quotes
+FILE_PATH=$(printf '%s' "$INPUT" | grep -o '"file_path"[[:space:]]*:[[:space:]]*"[^"]*"' | head -1 | sed 's/.*:[[:space:]]*"//;s/"$//' || true)
+
+# Python fallback if grep returned empty
+if [ -z "$FILE_PATH" ]; then
+  FILE_PATH=$(printf '%s' "$INPUT" | python3 -c 'import sys,json; print(json.loads(sys.stdin.read()).get("tool_input",{}).get("file_path",""))' 2>/dev/null || true)
+fi
+
+# If we couldn't extract a file path, allow (don't block on parse failure)
+if [ -z "$FILE_PATH" ]; then
+  echo '{}'
+  exit 0
+fi
+
+# Resolve file_path to absolute if it isn't already
+case "$FILE_PATH" in
+  /*) ;; # already absolute
+  *)
+    FILE_PATH="$(pwd)/$FILE_PATH"
+    ;;
+esac
+
+# Normalize: remove double slashes and trailing slash
+FILE_PATH=$(printf '%s' "$FILE_PATH" | sed 's|/\+|/|g;s|/$||')
+
+# Resolve symlinks and .. sequences (POSIX-portable, works on macOS)
+_resolve_path() {
+  local _dir _base
+  _dir="$(dirname "$1")"
+  _base="$(basename "$1")"
+  _dir="$(cd "$_dir" 2>/dev/null && pwd -P || printf '%s' "$_dir")"
+  printf '%s/%s' "$_dir" "$_base"
+}
+FILE_PATH=$(_resolve_path "$FILE_PATH")
+FREEZE_DIR=$(_resolve_path "$FREEZE_DIR")
+
+# Check: does the file path start with the freeze directory?
+case "$FILE_PATH" in
+  "${FREEZE_DIR}/"*|"${FREEZE_DIR}")
+    # Inside freeze boundary — allow
+    echo '{}'
+    ;;
+  *)
+    # Outside freeze boundary — deny
+    # Log hook fire event
+    mkdir -p ~/.gstack/analytics 2>/dev/null || true
+    echo '{"event":"hook_fire","skill":"freeze","pattern":"boundary_deny","ts":"'$(date -u +%Y-%m-%dT%H:%M:%SZ)'","repo":"'$(basename "$(git rev-parse --show-toplevel 2>/dev/null)" 2>/dev/null || echo "unknown")'"}' >> ~/.gstack/analytics/skill-usage.jsonl 2>/dev/null || true
+
+    printf '{"permissionDecision":"deny","message":"[freeze] Blocked: %s is outside the freeze boundary (%s). Only edits within the frozen directory are allowed."}\n' "$FILE_PATH" "$FREEZE_DIR"
+    ;;
+esac

package/skills/qa/references/issue-taxonomy.md

@@ -0,0 +1,85 @@
+# QA Issue Taxonomy
+
+## Severity Levels
+
+| Severity | Definition | Examples |
+|----------|------------|----------|
+| **critical** | Blocks a core workflow, causes data loss, or crashes the app | Form submit causes error page, checkout flow broken, data deleted without confirmation |
+| **high** | Major feature broken or unusable, no workaround | Search returns wrong results, file upload silently fails, auth redirect loop |
+| **medium** | Feature works but with noticeable problems, workaround exists | Slow page load (>5s), form validation missing but submit still works, layout broken on mobile only |
+| **low** | Minor cosmetic or polish issue | Typo in footer, 1px alignment issue, hover state inconsistent |
+
+## Categories
+
+### 1. Visual/UI
+- Layout breaks (overlapping elements, clipped text, horizontal scrollbar)
+- Broken or missing images
+- Incorrect z-index (elements appearing behind others)
+- Font/color inconsistencies
+- Animation glitches (jank, incomplete transitions)
+- Alignment issues (off-grid, uneven spacing)
+- Dark mode / theme issues
+
+### 2. Functional
+- Broken links (404, wrong destination)
+- Dead buttons (click does nothing)
+- Form validation (missing, wrong, bypassed)
+- Incorrect redirects
+- State not persisting (data lost on refresh, back button)
+- Race conditions (double-submit, stale data)
+- Search returning wrong or no results
+
+### 3. UX
+- Confusing navigation (no breadcrumbs, dead ends)
+- Missing loading indicators (user doesn't know something is happening)
+- Slow interactions (>500ms with no feedback)
+- Unclear error messages ("Something went wrong" with no detail)
+- No confirmation before destructive actions
+- Inconsistent interaction patterns across pages
+- Dead ends (no way back, no next action)
+
+### 4. Content
+- Typos and grammar errors
+- Outdated or incorrect text
+- Placeholder / lorem ipsum text left in
+- Truncated text (cut off without ellipsis or "more")
+- Wrong labels on buttons or form fields
+- Missing or unhelpful empty states
+
+### 5. Performance
+- Slow page loads (>3 seconds)
+- Janky scrolling (dropped frames)
+- Layout shifts (content jumping after load)
+- Excessive network requests (>50 on a single page)
+- Large unoptimized images
+- Blocking JavaScript (page unresponsive during load)
+
+### 6. Console/Errors
+- JavaScript exceptions (uncaught errors)
+- Failed network requests (4xx, 5xx)
+- Deprecation warnings (upcoming breakage)
+- CORS errors
+- Mixed content warnings (HTTP resources on HTTPS)
+- CSP violations
+
+### 7. Accessibility
+- Missing alt text on images
+- Unlabeled form inputs
+- Keyboard navigation broken (can't tab to elements)
+- Focus traps (can't escape a modal or dropdown)
+- Missing or incorrect ARIA attributes
+- Insufficient color contrast
+- Content not reachable by screen reader
+
+## Per-Page Exploration Checklist
+
+For each page visited during a QA session:
+
+1. **Visual scan** — Take annotated screenshot (`snapshot -i -a -o`). Look for layout issues, broken images, alignment.
+2. **Interactive elements** — Click every button, link, and control. Does each do what it says?
+3. **Forms** — Fill and submit. Test empty submission, invalid data, edge cases (long text, special characters).
+4. **Navigation** — Check all paths in/out. Breadcrumbs, back button, deep links, mobile menu.
+5. **States** — Check empty state, loading state, error state, full/overflow state.
+6. **Console** — Run `console --errors` after interactions. Any new JS errors or failed requests?
+7. **Responsiveness** — If relevant, check mobile and tablet viewports.
+8. **Auth boundaries** — What happens when logged out? Different user roles?

package/skills/qa/templates/qa-report-template.md

@@ -0,0 +1,126 @@
+# QA Report: {APP_NAME}
+
+| Field | Value |
+|-------|-------|
+| **Date** | {DATE} |
+| **URL** | {URL} |
+| **Branch** | {BRANCH} |
+| **Commit** | {COMMIT_SHA} ({COMMIT_DATE}) |
+| **PR** | {PR_NUMBER} ({PR_URL}) or "—" |
+| **Tier** | Quick / Standard / Exhaustive |
+| **Scope** | {SCOPE or "Full app"} |
+| **Duration** | {DURATION} |
+| **Pages visited** | {COUNT} |
+| **Screenshots** | {COUNT} |
+| **Framework** | {DETECTED or "Unknown"} |
+| **Index** | [All QA runs](./index.md) |
+
+## Health Score: {SCORE}/100
+
+| Category | Score |
+|----------|-------|
+| Console | {0-100} |
+| Links | {0-100} |
+| Visual | {0-100} |
+| Functional | {0-100} |
+| UX | {0-100} |
+| Performance | {0-100} |
+| Accessibility | {0-100} |
+
+## Top 3 Things to Fix
+
+1. **{ISSUE-NNN}: {title}** — {one-line description}
+2. **{ISSUE-NNN}: {title}** — {one-line description}
+3. **{ISSUE-NNN}: {title}** — {one-line description}
+
+## Console Health
+
+| Error | Count | First seen |
+|-------|-------|------------|
+| {error message} | {N} | {URL} |
+
+## Summary
+
+| Severity | Count |
+|----------|-------|
+| Critical | 0 |
+| High | 0 |
+| Medium | 0 |
+| Low | 0 |
+| **Total** | **0** |
+
+## Issues
+
+### ISSUE-001: {Short title}
+
+| Field | Value |
+|-------|-------|
+| **Severity** | critical / high / medium / low |
+| **Category** | visual / functional / ux / content / performance / console / accessibility |
+| **URL** | {page URL} |
+
+**Description:** {What is wrong, expected vs actual.}
+
+**Repro Steps:**
+
+1. Navigate to {URL}
+   ![Step 1](screenshots/issue-001-step-1.png)
+2. {Action}
+   ![Step 2](screenshots/issue-001-step-2.png)
+3. **Observe:** {what goes wrong}
+   ![Result](screenshots/issue-001-result.png)
+
+---
+
+## Fixes Applied (if applicable)
+
+| Issue | Fix Status | Commit | Files Changed |
+|-------|-----------|--------|---------------|
+| ISSUE-NNN | verified / best-effort / reverted / deferred | {SHA} | {files} |
+
+### Before/After Evidence
+
+#### ISSUE-NNN: {title}
+**Before:** ![Before](screenshots/issue-NNN-before.png)
+**After:** ![After](screenshots/issue-NNN-after.png)
+
+---
+
+## Regression Tests
+
+| Issue | Test File | Status | Description |
+|-------|-----------|--------|-------------|
+| ISSUE-NNN | path/to/test | committed / deferred / skipped | description |
+
+### Deferred Tests
+
+#### ISSUE-NNN: {title}
+**Precondition:** {setup state that triggers the bug}
+**Action:** {what the user does}
+**Expected:** {correct behavior}
+**Why deferred:** {reason}
+
+---
+
+## Ship Readiness
+
+| Metric | Value |
+|--------|-------|
+| Health score | {before} → {after} ({delta}) |
+| Issues found | N |
+| Fixes applied | N (verified: X, best-effort: Y, reverted: Z) |
+| Deferred | N |
+
+**PR Summary:** "QA found N issues, fixed M, health score X → Y."
+
+---
+
+## Regression (if applicable)
+
+| Metric | Baseline | Current | Delta |
+|--------|----------|---------|-------|
+| Health score | {N} | {N} | {+/-N} |
+| Issues | {N} | {N} | {+/-N} |
+
+**Fixed since baseline:** {list}
+**New since baseline:** {list}

package/skills/review/TODOS-format.md

@@ -0,0 +1,62 @@
+# TODOS.md Format Reference
+
+Shared reference for the canonical TODOS.md format. Referenced by `/ship` (Step 5.5) and `/plan-ceo-review` (TODOS.md updates section) to ensure consistent TODO item structure.
+
+---
+
+## File Structure
+
+```markdown
+# TODOS
+
+## <Skill/Component>     ← e.g., ## Browse, ## Ship, ## Review, ## Infrastructure
+<items sorted P0 first, then P1, P2, P3, P4>
+
+## Completed
+<finished items with completion annotation>
+```
+
+**Sections:** Organize by skill or component (`## Browse`, `## Ship`, `## Review`, `## QA`, `## Retro`, `## Infrastructure`). Within each section, sort items by priority (P0 at top).
+
+---
+
+## TODO Item Format
+
+Each item is an H3 under its section:
+
+```markdown
+### <Title>
+
+**What:** One-line description of the work.
+
+**Why:** The concrete problem it solves or value it unlocks.
+
+**Context:** Enough detail that someone picking this up in 3 months understands the motivation, the current state, and where to start.
+
+**Effort:** S / M / L / XL
+**Priority:** P0 / P1 / P2 / P3 / P4
+**Depends on:** <prerequisites, or "None">
+```
+
+**Required fields:** What, Why, Context, Effort, Priority
+**Optional fields:** Depends on, Blocked by
+
+---
+
+## Priority Definitions
+
+- **P0** — Blocking: must be done before next release
+- **P1** — Critical: should be done this cycle
+- **P2** — Important: do when P0/P1 are clear
+- **P3** — Nice-to-have: revisit after adoption/usage data
+- **P4** — Someday: good idea, no urgency
+
+---
+
+## Completed Item Format
+
+When an item is completed, move it to the `## Completed` section preserving its original content and appending:
+
+```markdown
+**Completed:** vX.Y.Z (YYYY-MM-DD)
+```