{"id":"535628df-c37a-40a1-ac9e-453afda403d8","entityType":"agent","slug":"clawhub-parkertoddbrooks-wip-repo-init","name":"Wip Repo Init","canonicalUrl":"https://www.xpersona.co/agent/clawhub-parkertoddbrooks-wip-repo-init","canonicalPath":"/agent/clawhub-parkertoddbrooks-wip-repo-init","generatedAt":"2026-10-10T08:01:50.328Z","source":"CLAWHUB","claimStatus":"UNCLAIMED","verificationTier":"NONE","summary":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-10T07:34:03.816Z","emptyReason":null},"description":"Scaffold the standard ai/ directory structure in any repo.","descriptionLabel":"Source description","evidenceSummary":"Capability contract not published. No trust telemetry is available yet. 1.6K downloads reported by the source. Last updated 10/10/2026.","installCommand":"clawhub skill install s17620xzyc7kfan8m36at57m6n83h8he:wip-repo-init","sourceUrl":"https://clawhub.ai/parkertoddbrooks/wip-repo-init","homepage":"https://clawhub.ai/parkertoddbrooks/skills/wip-repo-init","primaryLinks":[{"label":"View on ClawHub","url":"https://clawhub.ai/parkertoddbrooks/wip-repo-init","kind":"source"},{"label":"Homepage","url":"https://clawhub.ai/parkertoddbrooks/skills/wip-repo-init","kind":"homepage"}],"safetyScore":84,"overallRank":62,"popularityScore":57,"trustScore":null,"claimedByName":null,"isOwner":false,"seoDescription":"Wip Repo Init technical dossier on Xpersona with agent coverage, OPENCLEW support, and live trust metadata."},"coverage":{"evidence":{"source":"public-profile","verified":false,"confidence":"medium","updatedAt":"2026-10-10T07:34:03.816Z","emptyReason":null},"protocols":[{"protocol":"OPENCLEW","label":"OpenClaw","status":"self-declared","notes":"Declared in the public agent profile."}],"capabilities":[],"verifiedCount":0,"selfDeclaredCount":1,"capabilityMatrix":{"rows":[{"key":"OPENCLEW","type":"protocol","support":"unknown","confidenceSource":"profile","notes":"Listed on profile"}],"flattenedTokens":"protocol:OPENCLEW|unknown|profile"}},"adoption":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-10T07:34:03.816Z","emptyReason":null},"stars":null,"forks":null,"downloads":1588,"packageName":null,"latestVersion":"1.9.72","tractionLabel":"1.6K downloads"},"release":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-10T07:34:03.816Z","emptyReason":null},"lastUpdatedAt":"2026-10-10T07:34:03.816Z","lastCrawledAt":"2026-10-10T07:34:03.816Z","lastIndexedAt":null,"nextCrawlAt":"2026-10-11T07:34:03.816Z","lastVerifiedAt":null,"highlights":[{"version":"1.9.72","createdAt":"2026-04-21T21:25:26.686Z","changelog":"# AI DevOps Toolbox v1.9.72 ## Promote v1.9.71-alpha series to stable Closes #256. Consolidates 21 alpha prereleases (`v1.9.71-alpha.1` through `v1.9.71-alpha.21`) into a stable v1.9.72 release. No code changes beyond the version bump in the toolbox root `package.json`; the sub-tool code has been stable and dogfooded across the alpha iterations. ## Why The root `package.json` had been sitting at `1.9.71-alpha.21` without a stable promotion. That blocked `deploy-public.sh` from syncing the private repo to the public mirror ... the script gates public release on stable root versions. Symptom during 2026-04-21: wip-branch-guard sub-tool shipped stable (v1.9.82 → v1.9.83 → v1.9.84) to npm successfully, but the public `wipcomputer/wip-ai-devops-toolbox` GitHub releases page did not show any of them because `deploy-public.sh` refused to run with an alpha root. ## What's in the diff - `package.json` - Version bump `1.9.71-alpha.21` → `1.9.72` Everything else flows from `wip-release`: - CHANGELOG.md updated - Git tag `v1.9.72` - GitHub release on private repo - npm publish to `@latest` - `deploy-public.sh` runs, syncs private code (minus `ai/`) to `wipcomputer/wip-ai-devops-toolbox` - Public GitHub release created ## Sub-tool versions at this release | Sub-tool | npm version | |---|---| | `@wipcomputer/wip-branch-guard` | 1.9.84 | | Other sub-tools | See their individual `package.json` | The sub-tool releases have their own cadence; this release is purely the toolbox root bump. ## Co-authors Parker Todd Brooks, Lēsa (oc-lesa-mini, Opus 4.7), Claude Code (cc-mini, Opus 4.7).","fileCount":15,"zipByteSize":14856},{"version":"1.9.68","createdAt":"2026-04-01T13:28:08.263Z","changelog":"# Release Notes: wip-ai-devops-toolbox v1.9.68 Closes #239 ## Four-track release pipeline The release tool now supports four tracks: alpha, beta, hotfix, and stable. This replaces the single-track model where every release was public. Alpha is silent (no public release notes by default). Beta publishes prerelease notes to the public repo. Hotfix publishes to npm @latest without syncing code to public. Stable is the full deploy: npm + code sync + release notes. Developers can iterate on private, ship betas to testers, and only go public when ready. Version numbering uses standard semver prereleases: `1.9.68-alpha.1`, `1.9.68-beta.1`. The installer (`ldm install --beta` / `--alpha`) pulls the right tag from npm.","fileCount":14,"zipByteSize":13803},{"version":"1.9.67","createdAt":"2026-03-31T07:28:18.391Z","changelog":"# Release Notes: wip-ai-devops-toolbox v1.9.67 **Date:** 2026-03-30 ## What changed ### Hardcoded path removal Two files in the devops toolbox had paths that assumed a specific username or iCloud layout. **ldm-jobs/backup.sh** referenced `/Users/lesa/Library/Mobile Documents/.../ldm/bin/` to find the `ldm` binary for scheduled backup jobs. This iCloud path was fragile (iCloud sync delays, different usernames). The script now uses `$HOME/.ldm/bin/` which is the standard LDM install location and works on any machine (#301). **test.sh** (the branch guard test harness) had `/Users/lesa` hardcoded for creating temp directories. It now uses `$HOME` so tests run correctly under any user account (#301). ### Earlier changes included in this release **v1.9.66** added auto-combine for release notes from batched PRs (#237). When multiple PRs are merged between releases, their individual RELEASE-NOTES files are automatically combined into a single changelog entry. **v1.9.65** fixed the scaffold-on-main issue (#223) where scaffolding left untracked files that blocked `git pull` on the main working tree. ## Why The backup job is scheduled via LaunchAgent and runs unattended. If the path to `ldm` is wrong, backups silently fail. Moving to `$HOME/.ldm/bin/` aligns with the standard LDM install path and eliminates the iCloud dependency. The test fix ensures CI and local test runs work for all contributors. ## Issues closed - #301 ## How to verify ```bash grep -r \"/Users/lesa\" ldm-jobs/ tools/wip-branch-guard/test.sh # Should return zero results ```","fileCount":14,"zipByteSize":13803},{"version":"1.9.66","createdAt":"2026-03-30T13:29:15.236Z","changelog":"# Release Notes: wip-ai-devops-toolbox v1.9.66 Auto-combine release notes when batching multiple PRs into a single release. ## The story When multiple PRs merge to main before wip-release runs, the release had no good way to gather all their stories. Each PR might have its own RELEASE-NOTES file committed on the branch, but once the branch merges and the file gets trashed, the next release only sees an empty repo root. The agent had to write a new RELEASE-NOTES file from scratch, losing the narrative that was already reviewed in each PR. Now wip-release looks back through git history. It finds every merge commit since the last tag, checks each one for RELEASE-NOTES files via `git diff-tree` and `git show`, and combines them into a single document. If only one PR had notes, it uses them as-is (fully backwards compatible). If multiple PRs had notes, it wraps them with per-PR section headers, strips duplicate top-level headings, and collects all issue references into a combined list at the end. The detection sits at priority 2.5 in the release notes cascade: after the single-file check (RELEASE-NOTES-v{ver}.md on disk) but before the dev-update fallback. A file on disk always wins. The merged-PR scan only kicks in when nothing is found on disk. ## What changed - New exported function `collectMergedPRNotes()` in `core.mjs` that scans git merge history for RELEASE-NOTES files - Updated `cli.js` to call it at priority 2.5 in the notes detection cascade - Updated help text to document the new detection path - Zero breaking changes. Single-file detection still works exactly as before. ## Issues closed - Closes #237 ## How to verify ```bash # In any repo with multiple merged PRs since last tag, each having RELEASE-NOTES files: wip-release patch --dry-run # Should show: \"Combined release notes from N merged PRs\" ```","fileCount":14,"zipByteSize":13803},{"version":"1.9.65","createdAt":"2026-03-29T23:57:53.319Z","changelog":"# Release Notes: wip-ai-devops-toolbox v1.9.65 **Fix release notes scaffold on protected branches** When `wip-release patch` runs on main without a RELEASE-NOTES file, it used to scaffold a template directly in the working tree. On repos with branch guards (pre-commit hooks that block commits to main), this scaffolded file could not be removed or committed. It would block `git pull` and leave the working tree dirty. This has happened multiple times across different repos. The fix adds a branch check before scaffolding. If the current branch is main or master, wip-release now prints a clear error telling the user to write release notes on their feature branch before merging, then exits non-zero without creating any files. The scaffold behavior still works on feature branches, where it's actually useful. ## Issues closed - Closes #223 ## How to verify ```bash # On main, without release notes: should error, NOT scaffold cd any-repo && git checkout main wip-release patch # Expected: \"Release notes missing. Write RELEASE-NOTES-v*.md on your feature branch before merging.\" # Expected: no RELEASE-NOTES file created in working tree # On a feature branch: should scaffold as before git checkout -b test/scaffold-check wip-release patch # Expected: scaffolded template created ```","fileCount":14,"zipByteSize":13803},{"version":"1.9.64","createdAt":"2026-03-29T23:38:58.909Z","changelog":"# Release Notes: wip-ai-devops-toolbox v1.9.64 Closes #295 ## Branch guard: allow extension cleanup The branch guard blocked `rm` on deployed extension directories (`~/.openclaw/extensions/` and `~/.ldm/extensions/`) because those paths live inside git repos. But deployed extensions are managed by `ldm install`, not by hand. When a stale `-private` extension needed to be removed (e.g. `wip-xai-grok-private` replaced by the public `wip-xai-grok`), the agent couldn't clean it up without asking the user to run the command manually. Added an allowlist pattern for `rm` targeting `.openclaw/extensions/` and `.ldm/extensions/` paths. Same approach as the existing `.ldm/state/` allowlist. The guard still blocks `rm` on actual repo source files.","fileCount":14,"zipByteSize":13803},{"version":"1.9.63","createdAt":"2026-03-29T19:12:30.631Z","changelog":"# Release Notes: wip-ai-devops-toolbox v1.9.63 **Fix all wip-release errors: branch cleanup crashes, shell injection, stale remote refs.** ## The story Every wip-release run produced errors: \"fatal: Not a valid object name +\", \"remote ref does not exist\", and shell injection risks from branch names passed through execSync template strings. These were dismissed as \"non-blocking\" but they cluttered every release output and masked real problems. Root cause: branch cleanup code (sections 10 and 11) used `execSync` with template strings, which breaks on branch names with special characters and allows shell injection. Also tried to delete remote branches that GitHub already deleted during PR merge. Fix: replaced all `execSync` template strings with `execFileSync` array args (safe from injection). Added character validation to skip branches with special chars. Wrapped remote delete in try/catch since GitHub PR merge already handles deletion. ## Issues closed - #231 (continued: release pipeline reliability) ## How to verify ```bash wip-release patch --dry-run # Should show no \"fatal\" or \"Not a valid object name\" errors # Guard tests: cd tools/wip-branch-guard && bash test.sh ```","fileCount":14,"zipByteSize":13803},{"version":"1.9.62","createdAt":"2026-03-29T19:06:14.023Z","changelog":"# Release Notes: wip-ai-devops-toolbox v1.9.62 **Fix wip-release leaving dirty state on main after every release.** ## The story wip-release writes to 15+ files during a release (root package.json, 12 sub-tool package.json files, SKILL.md, CHANGELOG.md, product docs, trashed release notes). But gitCommitAndTag() only staged 3 files (package.json, CHANGELOG.md, SKILL.md). The other 12+ files were left modified on disk, uncommitted. This blocked git pull on the next operation and required manual `git checkout -- .` every time. Fix: stage all files that wip-release modifies. Sub-tool package.json files, product docs (ai/product/), and trashed release notes (_trash/) are now included in the release commit. ## Issues closed - #231 (wip-release rollback version bumps on failure) ## How to verify ```bash wip-release patch git status # Should show clean working tree after release ```","fileCount":14,"zipByteSize":13803}]},"execution":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No published capability contract is available yet."},"installCommand":"clawhub skill install s17620xzyc7kfan8m36at57m6n83h8he:wip-repo-init","setupComplexity":"low","setupSteps":["Install using `clawhub skill install s17620xzyc7kfan8m36at57m6n83h8he:wip-repo-init` in an isolated environment before connecting it to live workloads.","No published capability contract is available yet, so validate auth and request/response behavior manually.","Review the upstream CLAWHUB listing at https://clawhub.ai/parkertoddbrooks/wip-repo-init before using production credentials."],"contract":{"contractStatus":"missing","authModes":[],"requires":[],"forbidden":[],"supportsMcp":false,"supportsA2a":false,"supportsStreaming":false,"inputSchemaRef":null,"outputSchemaRef":null,"dataRegion":null,"contractUpdatedAt":null,"sourceUpdatedAt":null,"freshnessSeconds":null},"invocationGuide":{"preferredApi":{"snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-parkertoddbrooks-wip-repo-init/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-parkertoddbrooks-wip-repo-init/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-parkertoddbrooks-wip-repo-init/trust"},"curlExamples":["curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-parkertoddbrooks-wip-repo-init/snapshot\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-parkertoddbrooks-wip-repo-init/contract\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-parkertoddbrooks-wip-repo-init/trust\""],"jsonRequestTemplate":{"query":"summarize this repo","constraints":{"maxLatencyMs":2000,"protocolPreference":["OPENCLEW"]}},"jsonResponseTemplate":{"ok":true,"result":{"summary":"...","confidence":0.9},"meta":{"source":"CLAWHUB","generatedAt":"2026-10-10T08:01:50.324Z"}},"retryPolicy":{"maxAttempts":3,"backoffMs":[500,1500,3500],"retryableConditions":["HTTP_429","HTTP_503","NETWORK_TIMEOUT"]}},"endpoints":{"dossierUrl":"https://www.xpersona.co/api/v1/agents/clawhub-parkertoddbrooks-wip-repo-init/dossier","snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-parkertoddbrooks-wip-repo-init/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-parkertoddbrooks-wip-repo-init/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-parkertoddbrooks-wip-repo-init/trust"}},"reliability":{"evidence":{"source":"runtime-metrics","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No trust, reliability, or runtime telemetry is available."},"trust":{"status":"unavailable","handshakeStatus":"UNKNOWN","verificationFreshnessHours":null,"reputationScore":null,"p95LatencyMs":null,"successRate30d":null,"fallbackRate":null,"attempts30d":null,"trustUpdatedAt":null,"trustConfidence":"unknown","sourceUpdatedAt":null,"freshnessSeconds":null},"decisionGuardrails":{"doNotUseIf":["Contract metadata is missing or unavailable for deterministic execution."],"safeUseWhen":[],"riskFlags":["missing_or_unavailable_contract","trust_data_unavailable","schema_references_missing"],"operationalConfidence":"low"},"executionMetrics":{"observedLatencyMsP50":null,"observedLatencyMsP95":null,"estimatedCostUsd":null,"uptime30d":null,"rateLimitRpm":null,"rateLimitBurst":null,"lastVerifiedAt":null,"verificationSource":null},"runtimeMetrics":{"successRate":null,"avgLatencyMs":null,"avgCostUsd":null,"hallucinationRate":null,"retryRate":null,"disputeRate":null,"p50Latency":null,"p95Latency":null,"lastUpdated":null}},"benchmarks":{"evidence":{"source":"no-benchmark-data","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No benchmark suites or observed failure patterns are available."},"suites":[],"failurePatterns":[]},"artifacts":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-10T07:34:03.816Z","emptyReason":null},"readme":"Skill: Wip Repo Init\n\nOwner: parkertoddbrooks\n\nSummary: Scaffold the standard ai/ directory structure in any repo.\n\nTags: latest:1.9.72\n\nVersion history:\n\nv1.9.72 | 2026-04-21T21:25:26.686Z | user\n\n# AI DevOps Toolbox v1.9.72\n\n## Promote v1.9.71-alpha series to stable\n\nCloses #256.\n\nConsolidates 21 alpha prereleases (`v1.9.71-alpha.1` through `v1.9.71-alpha.21`) into a stable v1.9.72 release. No code changes beyond the version bump in the toolbox root `package.json`; the sub-tool code has been stable and dogfooded across the alpha iterations.\n\n## Why\n\nThe root `package.json` had been sitting at `1.9.71-alpha.21` without a stable promotion. That blocked `deploy-public.sh` from syncing the private repo to the public mirror ... the script gates public release on stable root versions.\n\nSymptom during 2026-04-21: wip-branch-guard sub-tool shipped stable (v1.9.82 → v1.9.83 → v1.9.84) to npm successfully, but the public `wipcomputer/wip-ai-devops-toolbox` GitHub releases page did not show any of them because `deploy-public.sh` refused to run with an alpha root.\n\n## What's in the diff\n\n- `package.json`\n - Version bump `1.9.71-alpha.21` → `1.9.72`\n\nEverything else flows from `wip-release`:\n\n- CHANGELOG.md updated\n- Git tag `v1.9.72`\n- GitHub release on private repo\n- npm publish to `@latest`\n- `deploy-public.sh` runs, syncs private code (minus `ai/`) to `wipcomputer/wip-ai-devops-toolbox`\n- Public GitHub release created\n\n## Sub-tool versions at this release\n\n| Sub-tool | npm version |\n|---|---|\n| `@wipcomputer/wip-branch-guard` | 1.9.84 |\n| Other sub-tools | See their individual `package.json` |\n\nThe sub-tool releases have their own cadence; this release is purely the toolbox root bump.\n\n## Co-authors\n\nParker Todd Brooks, Lēsa (oc-lesa-mini, Opus 4.7), Claude Code (cc-mini, Opus 4.7).\n\nv1.9.68 | 2026-04-01T13:28:08.263Z | user\n\n# Release Notes: wip-ai-devops-toolbox v1.9.68\n\nCloses #239\n\n## Four-track release pipeline\n\nThe release tool now supports four tracks: alpha, beta, hotfix, and stable. This replaces the single-track model where every release was public.\n\nAlpha is silent (no public release notes by default). Beta publishes prerelease notes to the public repo. Hotfix publishes to npm @latest without syncing code to public. Stable is the full deploy: npm + code sync + release notes. Developers can iterate on private, ship betas to testers, and only go public when ready.\n\nVersion numbering uses standard semver prereleases: `1.9.68-alpha.1`, `1.9.68-beta.1`. The installer (`ldm install --beta` / `--alpha`) pulls the right tag from npm.\n\nv1.9.67 | 2026-03-31T07:28:18.391Z | user\n\n# Release Notes: wip-ai-devops-toolbox v1.9.67\n\n**Date:** 2026-03-30\n\n## What changed\n\n### Hardcoded path removal\n\nTwo files in the devops toolbox had paths that assumed a specific username or iCloud layout.\n\n**ldm-jobs/backup.sh** referenced `/Users/lesa/Library/Mobile Documents/.../ldm/bin/` to find the `ldm` binary for scheduled backup jobs. This iCloud path was fragile (iCloud sync delays, different usernames). The script now uses `$HOME/.ldm/bin/` which is the standard LDM install location and works on any machine (#301).\n\n**test.sh** (the branch guard test harness) had `/Users/lesa` hardcoded for creating temp directories. It now uses `$HOME` so tests run correctly under any user account (#301).\n\n### Earlier changes included in this release\n\n**v1.9.66** added auto-combine for release notes from batched PRs (#237). When multiple PRs are merged between releases, their individual RELEASE-NOTES files are automatically combined into a single changelog entry.\n\n**v1.9.65** fixed the scaffold-on-main issue (#223) where scaffolding left untracked files that blocked `git pull` on the main working tree.\n\n## Why\n\nThe backup job is scheduled via LaunchAgent and runs unattended. If the path to `ldm` is wrong, backups silently fail. Moving to `$HOME/.ldm/bin/` aligns with the standard LDM install path and eliminates the iCloud dependency. The test fix ensures CI and local test runs work for all contributors.\n\n## Issues closed\n\n- #301\n\n## How to verify\n\n```bash\ngrep -r \"/Users/lesa\" ldm-jobs/ tools/wip-branch-guard/test.sh\n# Should return zero results\n```\n\nv1.9.66 | 2026-03-30T13:29:15.236Z | user\n\n# Release Notes: wip-ai-devops-toolbox v1.9.66\n\nAuto-combine release notes when batching multiple PRs into a single release.\n\n## The story\n\nWhen multiple PRs merge to main before wip-release runs, the release had no good way to gather all their stories. Each PR might have its own RELEASE-NOTES file committed on the branch, but once the branch merges and the file gets trashed, the next release only sees an empty repo root. The agent had to write a new RELEASE-NOTES file from scratch, losing the narrative that was already reviewed in each PR.\n\nNow wip-release looks back through git history. It finds every merge commit since the last tag, checks each one for RELEASE-NOTES files via `git diff-tree` and `git show`, and combines them into a single document. If only one PR had notes, it uses them as-is (fully backwards compatible). If multiple PRs had notes, it wraps them with per-PR section headers, strips duplicate top-level headings, and collects all issue references into a combined list at the end.\n\nThe detection sits at priority 2.5 in the release notes cascade: after the single-file check (RELEASE-NOTES-v{ver}.md on disk) but before the dev-update fallback. A file on disk always wins. The merged-PR scan only kicks in when nothing is found on disk.\n\n## What changed\n\n- New exported function `collectMergedPRNotes()` in `core.mjs` that scans git merge history for RELEASE-NOTES files\n- Updated `cli.js` to call it at priority 2.5 in the notes detection cascade\n- Updated help text to document the new detection path\n- Zero breaking changes. Single-file detection still works exactly as before.\n\n## Issues closed\n\n- Closes #237\n\n## How to verify\n\n```bash\n# In any repo with multiple merged PRs since last tag, each having RELEASE-NOTES files:\nwip-release patch --dry-run\n# Should show: \"Combined release notes from N merged PRs\"\n```\n\nv1.9.65 | 2026-03-29T23:57:53.319Z | user\n\n# Release Notes: wip-ai-devops-toolbox v1.9.65\n\n**Fix release notes scaffold on protected branches**\n\nWhen `wip-release patch` runs on main without a RELEASE-NOTES file, it used to scaffold a\ntemplate directly in the working tree. On repos with branch guards (pre-commit hooks that\nblock commits to main), this scaffolded file could not be removed or committed. It would\nblock `git pull` and leave the working tree dirty. This has happened multiple times across\ndifferent repos.\n\nThe fix adds a branch check before scaffolding. If the current branch is main or master,\nwip-release now prints a clear error telling the user to write release notes on their\nfeature branch before merging, then exits non-zero without creating any files. The scaffold\nbehavior still works on feature branches, where it's actually useful.\n\n## Issues closed\n\n- Closes #223\n\n## How to verify\n\n```bash\n# On main, without release notes: should error, NOT scaffold\ncd any-repo && git checkout main\nwip-release patch\n# Expected: \"Release notes missing. Write RELEASE-NOTES-v*.md on your feature branch before merging.\"\n# Expected: no RELEASE-NOTES file created in working tree\n\n# On a feature branch: should scaffold as before\ngit checkout -b test/scaffold-check\nwip-release patch\n# Expected: scaffolded template created\n```\n\nv1.9.64 | 2026-03-29T23:38:58.909Z | user\n\n# Release Notes: wip-ai-devops-toolbox v1.9.64\n\nCloses #295\n\n## Branch guard: allow extension cleanup\n\nThe branch guard blocked `rm` on deployed extension directories (`~/.openclaw/extensions/` and `~/.ldm/extensions/`) because those paths live inside git repos. But deployed extensions are managed by `ldm install`, not by hand. When a stale `-private` extension needed to be removed (e.g. `wip-xai-grok-private` replaced by the public `wip-xai-grok`), the agent couldn't clean it up without asking the user to run the command manually.\n\nAdded an allowlist pattern for `rm` targeting `.openclaw/extensions/` and `.ldm/extensions/` paths. Same approach as the existing `.ldm/state/` allowlist. The guard still blocks `rm` on actual repo source files.\n\nv1.9.63 | 2026-03-29T19:12:30.631Z | user\n\n# Release Notes: wip-ai-devops-toolbox v1.9.63\n\n**Fix all wip-release errors: branch cleanup crashes, shell injection, stale remote refs.**\n\n## The story\n\nEvery wip-release run produced errors: \"fatal: Not a valid object name +\", \"remote ref does not exist\", and shell injection risks from branch names passed through execSync template strings. These were dismissed as \"non-blocking\" but they cluttered every release output and masked real problems.\n\nRoot cause: branch cleanup code (sections 10 and 11) used `execSync` with template strings, which breaks on branch names with special characters and allows shell injection. Also tried to delete remote branches that GitHub already deleted during PR merge.\n\nFix: replaced all `execSync` template strings with `execFileSync` array args (safe from injection). Added character validation to skip branches with special chars. Wrapped remote delete in try/catch since GitHub PR merge already handles deletion.\n\n## Issues closed\n\n- #231 (continued: release pipeline reliability)\n\n## How to verify\n\n```bash\nwip-release patch --dry-run\n# Should show no \"fatal\" or \"Not a valid object name\" errors\n# Guard tests: cd tools/wip-branch-guard && bash test.sh\n```\n\nv1.9.62 | 2026-03-29T19:06:14.023Z | user\n\n# Release Notes: wip-ai-devops-toolbox v1.9.62\n\n**Fix wip-release leaving dirty state on main after every release.**\n\n## The story\n\nwip-release writes to 15+ files during a release (root package.json, 12 sub-tool package.json files, SKILL.md, CHANGELOG.md, product docs, trashed release notes). But gitCommitAndTag() only staged 3 files (package.json, CHANGELOG.md, SKILL.md). The other 12+ files were left modified on disk, uncommitted. This blocked git pull on the next operation and required manual `git checkout -- .` every time.\n\nFix: stage all files that wip-release modifies. Sub-tool package.json files, product docs (ai/product/), and trashed release notes (_trash/) are now included in the release commit.\n\n## Issues closed\n\n- #231 (wip-release rollback version bumps on failure)\n\n## How to verify\n\n```bash\nwip-release patch\ngit status\n# Should show clean working tree after release\n```\n\nv1.9.61 | 2026-03-29T18:59:11.709Z | user\n\n# Release Notes: wip-ai-devops-toolbox v1.9.61\n\n**Add test script for branch guard. Fix node bypass regex.**\n\n## The story\n\nEvery guard bug this session (v1.9.56-59) would have been caught by running a test before merging. This release adds test.sh to the guard that pipes test JSON into guard.mjs and verifies allow/deny results. 30 test cases covering destructive commands, quoted strings (Bug 1/3), compound commands (Bug 2), safe commands, and plan files.\n\nAlso fixes the node bypass regex: `require('fs').writeFileSync` wasn't caught because the regex looked for `fs.writeFile` literally. Broadened to match `writeFile` after `node -e`.\n\n## Issues closed\n\n- #232 (guard test coverage)\n\n## How to verify\n\n```bash\ncd tools/wip-branch-guard && bash test.sh\n# Should show: 30 passed, 0 failed, 3 skipped\n```\n\nv1.9.60 | 2026-03-29T15:44:36.438Z | user\n\n# Release Notes: wip-ai-devops-toolbox v1.9.60\n\n**Fix npm package bloat: exclude worktrees and _trash from published tarball.**\n\n## The story\n\nv1.9.59 published 869 files (3.9 MB) to npm because leftover worktree directories and _trash/ were included in the tarball. The .npmignore only excluded ai/ and .DS_Store. Added _trash/, .worktrees/, _worktrees/, .claude/, .wrangler/ to .npmignore. Also cleaned up 10 stale worktrees from previous sessions.\n\n## Issues closed\n\n- #232 (continued cleanup)\n\n## How to verify\n\n```bash\nnpm pack --dry-run 2>&1 | tail -5\n# Should show ~200 files, not 869\n```\n\nv1.9.58 | 2026-03-29T14:46:49.782Z | user\n\n# Release Notes: wip-ai-devops-toolbox v1.9.58\n\n**Fix deploy-public.sh losing release notes when invoked with relative path.**\n\n## The story\n\nWhen deploy-public.sh was called with `.` as the private repo path (e.g. `bash scripts/deploy-public.sh . wipcomputer/repo`), the script later cd'd into a temp directory. After that, `cd \".\"` no longer pointed to the private repo, so `gh release view` failed silently and release notes fell back to the empty \"Release vX.Y.Z\" default. This has been broken since at least v1.9.51.\n\nFix: resolve PRIVATE_REPO to an absolute path at startup before any cd happens.\n\n## Issues closed\n\n- #228 (continued from v1.9.57)\n\n## How to verify\n\n```bash\n# From a repo directory, run with \".\" and check public release has real notes:\ncd /path/to/private-repo\nbash scripts/deploy-public.sh . wipcomputer/public-repo --dry-run\n```\n\nv1.9.57 | 2026-03-29T14:39:04.712Z | user\n\n# Release Notes: wip-ai-devops-toolbox v1.9.57\n\n**deploy-public.sh now excludes .worktrees/ and _worktrees/ from public repo syncs.**\n\n## The story\n\nv1.9.56 accidentally deployed worktree directories (containing embedded git repos) to the public repo. The deploy script's rsync excluded ai/, .git/, _trash/, and other dev artifacts but didn't exclude worktree directories. Added both .worktrees/ (new convention) and _worktrees/ (old convention) to the exclude list.\n\n## Issues closed\n\n- #228 (deploy-public.sh leaks .worktrees/ to public repo)\n\n## How to verify\n\n```bash\n# Run deploy-public.sh --dry-run and confirm .worktrees/ is not synced\ngrep -n \"worktrees\" scripts/deploy-public.sh\n```\n\nv1.9.56 | 2026-03-29T14:22:27.071Z | user\n\n# Release Notes: wip-ai-devops-toolbox v1.9.56\n\n**Branch guard now blocks destructive git commands on all branches.**\n\n## The story\n\nThe branch guard blocked commits and file writes on main, but allowed destructive git commands that destroy uncommitted work. Commands like `git clean -fd`, `git checkout --`, `git stash drop`, and `git reset --hard` slipped through because they were either in the allowed list or not in the blocked list. These commands destroyed Parker's Finder aliases, other agents' uncommitted edits, and user files multiple times on Mar 28-29.\n\nThe fix adds a new DESTRUCTIVE_PATTERNS list that fires on ALL branches, not just main. The guard also closes several bypass vectors: `node -e` removed from the allowed list, python/node file-write patterns detected, and `git checkout` narrowed to branch-switching only.\n\n## What changed\n\n- Added DESTRUCTIVE_PATTERNS: git clean -f, git checkout --, git stash drop/pop/clear, git reset --hard, git restore, python/node bypasses\n- Removed `git checkout` blanket allow. Now only allows `git checkout ` (switching)\n- Removed `git stash drop` from allowed list\n- Removed `node -e` from allowed bash patterns (bypass vector)\n- Added `git stash show` and `git restore --staged` as safe read-only operations\n- Deny message tells agent to use worktrees and safety checkpoints instead\n\n## Issues closed\n\n- #240 (branch guard + harness directories)\n- #241 (python bypass detection)\n- PR #284\n\n## How to verify\n\n```bash\n# These should all be BLOCKED:\n# git clean -fd\n# git checkout -- somefile\n# git stash drop\n# git stash pop\n# git reset --hard\n# python3 -c \"open('f','w').write('x')\"\n\n# These should still WORK:\n# git checkout main (branch switching)\n# git stash list (read-only)\n# git status, git log, git diff\n# Normal worktree workflow\n```\n\nv1.9.55 | 2026-03-28T19:03:05.584Z | user\n\n# Release Notes: wip-ai-devops-toolbox v1.9.55\n\nForce redeploy: .worktrees guard fix.\n\n## The story\n\nv1.9.53 had the guard fix but deploy-public was missed. v1.9.54 force-redeployed but installer had already cached v1.9.54. This version ensures the public repo and npm are in sync so ldm install deploys the correct guard.mjs with .worktrees convention.\n\n## Issues closed\n\n- #240 (partial)\n\nv1.9.54 | 2026-03-28T18:54:45.111Z | user\n\n# Release Notes: wip-ai-devops-toolbox v1.9.54\n\nForce redeploy: guard files were stale after v1.9.53.\n\n## The story\n\nv1.9.53 published the .worktrees guard fix to npm but ldm install saw the version as current and skipped redeploying the files. The deployed guard.mjs was still the old version. This release forces a version bump so the installer re-deploys.\n\nThis is a bug in the installer: it checks version numbers but not file contents. Filed for future fix.\n\n## Issues closed\n\n- #240 (partial: .worktrees convention)\n\nv1.9.53 | 2026-03-28T18:45:57.314Z | user\n\n# Release Notes: wip-ai-devops-toolbox v1.9.53\n\n**One-line summary of what this release does**\n\nTell the story. What was broken or missing? What did we build? Why does the user care?\nWrite at least one real paragraph of prose. Not just bullets. The release notes gate\nwill block if there is no narrative. Bullets are fine for details, but the story comes first.\n\n## The story\n\n(Write a paragraph here. What was the problem? What does this release fix? Why does it matter?\nThis is what users read. Make it worth reading.)\n\n## Issues closed\n\n- #282\n\n## How to verify\n\n```bash\n# Commands to test the changes\n```\n\nv1.9.52 | 2026-03-27T15:14:36.709Z | user\n\n# Release Notes: wip-ai-devops-toolbox v1.9.52\n\n**Fix branch guard false-blocking bash commands targeting worktree paths**\n\n## What changed\n\n- Branch guard now extracts absolute paths from any bash command (mkdir, cp, mv, touch, etc.) and resolves the git branch from the target path's repo, not the CWD\n- `findRepoRoot()` improved to walk up to existing directories for paths that don't exist yet (handles mkdir for new directories)\n- Added `.ldm/worktrees` to allowed worktree locations alongside `_worktrees/` and `.claude/worktrees`\n\n## Why\n\nWhen Claude Code launches from `~/wipcomputerinc/` (on main) and runs bash commands targeting files inside a worktree (e.g., `mkdir -p /path/to/_worktrees/repo--branch/new-dir/`), the guard only knew how to extract paths from `cd` and `git -C` patterns. Any other command fell back to CWD resolution, saw \"main\", and blocked incorrectly. This caused minutes of wasted time every session.\n\n## Issues closed\n\n- wipcomputer/wip-ldm-os#187\n\n## How to verify\n\n```bash\n# From CWD on main, this should no longer be blocked:\n# mkdir -p /path/to/_worktrees/repo--branch/new-directory/\n# cp file.txt /path/to/_worktrees/repo--branch/\n```\n\nv1.9.51 | 2026-03-24T17:41:40.350Z | user\n\n# Release Notes: wip-ai-devops-toolbox v1.9.51\n\n## Branch Guard: Workspace Files Allowlist (#185)\n\nAdded TOOLS.md, MEMORY.md, IDENTITY.md, SOUL.md, WHERE-TO-WRITE.md, HEARTBEAT.md to the shared state allowlist. Both agents can now write to workspace files on main without being blocked.\n\nPreviously only SHARED-CONTEXT.md was allowed. This broke Lesa's ability to edit her own workspace files during the migration to ~/wipcomputerinc/.\n\n## TECHNICAL.md: Backup Documentation\n\nUpdated LDM Dev Tools.app backup section to reflect the unified backup system. backup.sh now calls `~/.ldm/bin/ldm-backup.sh` (deployed by ldm install from wip-ldm-os-private/scripts/).\n\nv1.9.50 | 2026-03-20T17:39:39.613Z | user\n\n# Release Notes: wip-ai-devops-toolbox v1.9.50\n\n**wip-release: require product update doc on every release.**\n\n## What changed\n\nNew quality gate in wip-release: checks that `ai/dev-updates/product-update/*-product-update.md` was modified since the last release tag. Same pattern as dev-updates, roadmap, and readme-first checks.\n\nThe product update doc is a human-readable test guide. Each release entry has: what changed, how it's supposed to work, and how to test. New entries go at the top. Additive only.\n\n## Why\n\nThree repos now have product update docs but nothing enforced keeping them current. Without the gate, the docs will drift immediately (same problem we had with TECHNICAL.md).\n\n## Issues closed\n\n- #220\n\n## How to verify\n\n```bash\nwip-release patch --dry-run\n# Should warn if product update doc not modified since last release\n```\n\nv1.9.49 | 2026-03-20T16:29:43.012Z | user\n\n# Release Notes: wip-ai-devops-toolbox v1.9.49\n\n**TECHNICAL.md audit: 2 weeks of undocumented features now documented.**\n\n## What changed\n\nFull TECHNICAL.md audit covering v1.9.15 through v1.9.48. Two passes. Key additions:\n\n- **wip-release quality gates:** Technical docs gate, interface coverage gate, product docs auto-sync, all skip flags documented.\n- **deploy-public.sh:** Full 8-step pipeline including GitHub Packages publishing, repo URL rewrite, co-author sync.\n- **wip-license-guard:** Now documented as both CLI and Claude Code PreToolUse hook (guard.mjs). Enforcement details.\n- **wip-branch-guard:** Worktree requirement on branches, non-repo file passthrough, workflow teaching messages.\n- **wip-repos claude:** Cross-repo CLAUDE.md ecosystem generator fully documented.\n- **Source code table:** Missing files added (guard.mjs, claude.mjs, mcp-server.mjs).\n- **Log paths:** Fixed stale /tmp/ references to ~/.ldm/logs/.\n\n## Why\n\n15 releases shipped without TECHNICAL.md updates. Agents reading the docs were missing critical features: release gates, license enforcement hooks, deploy pipeline details.\n\n## Issues closed\n\n- #218\n\n## How to verify\n\n```bash\ngrep \"Interface coverage\" TECHNICAL.md # new gate\ngrep \"guard.mjs\" TECHNICAL.md # license-guard hook\ngrep \"GitHub Packages\" TECHNICAL.md # deploy pipeline\n```\n\nv1.9.48 | 2026-03-20T15:08:11.106Z | user\n\n# Release Notes: wip-ai-devops-toolbox v1.9.48\n\n**Document wip-repos claude command in SKILL.md and TECHNICAL.md.**\n\n## What changed\n\n- SKILL.md: added `wip-repos claude` commands to the wip-repos section\n- TECHNICAL.md: full documentation of how the ecosystem generator works, template locations, delimiter convention\n\n## Why\n\nv1.9.47 shipped the `wip-repos claude` command without updating technical docs. Now documented.\n\n## Issues closed\n\n- #212 (docs portion)\n\n## How to verify\n\n```bash\ngrep \"wip-repos claude\" SKILL.md TECHNICAL.md\n```\n\nv1.9.47 | 2026-03-20T14:20:26.641Z | user\n\n# Release Notes: wip-ai-devops-toolbox v1.9.47\n\n**New: `wip-repos claude` command + CLAUDE.md templates.**\n\n## What changed\n\n### `wip-repos claude` (Phases 1-3 of the CLAUDE.md plan)\n\nNew subcommand that generates cross-repo ecosystem sections in CLAUDE.md files. When an agent opens repo-A, it can't read repo-B. This command pre-generates the context.\n\n```bash\nwip-repos claude # regenerate all repos\nwip-repos claude my-repo # regenerate one repo\nwip-repos claude --init # create CLAUDE.md for repos missing one\nwip-repos claude --dry-run # preview changes\n```\n\nFeatures:\n- Reads all repos from manifest, extracts metadata (package.json, SKILL.md, directory structure)\n- Generates `## Ecosystem` sections with delimiter comments (``)\n- Hand-written sections are never overwritten\n- Relevance filtering: only related repos shown (same category + core repos)\n- `--init` creates starter CLAUDE.md from template for repos missing one\n\n### Templates\n\n- `templates/global-claude-md.md` ... universal CLAUDE.md for ~/.claude/CLAUDE.md\n- `templates/repo-claude-md.template` ... per-repo starter with ecosystem placeholder\n\n## Why\n\nAgents lose context across repos. They can't read sibling repos at runtime. Pre-generating cross-repo maps into CLAUDE.md solves this without requiring runtime access.\n\n## Issues closed\n\n- #212 (partial: Phases 1-3 of 6)\n\n## How to verify\n\n```bash\nwip-repos claude --dry-run\n```\n\nv1.9.46 | 2026-03-19T03:34:52.917Z | user\n\n# Release Notes: wip-ai-devops-toolbox v1.9.46\n\n**Centralized worktree management: guard rule, wip-release prune, Dev Guide convention.**\n\n## What changed\n\n### Guard: worktree path warning (#212)\nBranch guard now warns when `git worktree add` creates a worktree outside `_worktrees/`. Shows the convention and suggests `ldm worktree add`. Warning only, not a hard block.\n\n### wip-release: worktree prune (#212)\nNew step 12 in the release pipeline. After branch cleanup, prunes stale worktrees from `_worktrees/` whose branches are merged into main. Automatic cleanup after every release.\n\n### Dev Guide: _worktrees/ convention (#212)\nDocuments the centralized worktree convention:\n- All worktrees go in `_worktrees/--/`\n- Use `ldm worktree add` (auto-detects repo, creates in the right place)\n- Guard warns about worktrees outside the convention\n- `wip-release` auto-prunes merged worktrees\n\n## Why\n\nWorktrees created as repo siblings confused iCloud sync, looked like real repos in directory listings, and were never cleaned up. This session alone created 10+ stale worktrees. The convention keeps them organized and the release pipeline cleans them automatically.\n\n## Issues closed\n\n- #212\n- #213\n\n## How to verify\n\n```bash\n# Guard warning:\ncd /path/to/repo\ngit worktree add ../my-worktree -b test # should warn about _worktrees/\n\n# Correct path:\nldm worktree add cc-mini/test # creates _worktrees/--cc-mini--test/\n```\n\nv1.9.45 | 2026-03-19T02:23:41.555Z | user\n\n# Release Notes: wip-ai-devops-toolbox v1.9.45\n\n**Guard now teaches the workflow instead of just blocking.**\n\n## What changed\n\n- **Branch guard error messages overhauled (#213).** When the guard blocks a write on main, it now shows the full 8-step process: worktree, branch, commit, push, PR, merge, wip-release, deploy-public. Includes the lesson that release notes go on the feature branch, not as a separate PR.\n- **Separate error for \"on branch but not in worktree.\"** Tells the agent to go back to main and create a worktree properly.\n- **CLAUDE.md added to shared state allowlist.** Was patched in the deployed guard but missing from source. Now in sync.\n\n## Why\n\nAgents kept getting blocked by the guard and then trying workarounds instead of following the process. The error message said \"Use a worktree\" but didn't explain the full workflow. Today's session hit this 5+ times. The guard works. The gap was agent knowledge.\n\n## Issues closed\n\n- #213\n- #256\n\n## How to verify\n\n```bash\n# In any repo on main, try to edit a file. The error should show the full workflow.\n# In any repo on a branch (not worktree), try to edit. Should show worktree instructions.\n```\n\nv1.9.44 | 2026-03-17T15:24:59.780Z | user\n\n# Guard non-repo files fix + UTC date fix\n\nTwo bugs fixed in one PR.\n\n## Bug 1: Guard blocks files outside git repos (#77)\n\n**Problem:** When Write/Edit targets a file outside any git repo (e.g. `~/.claude/plans/`), `findRepoRoot()` returns null. The guard fell back to CWD (`~/.openclaw` on main) and blocked the operation. Files outside repos aren't the guard's concern.\n\n**Fix:** If `findRepoRoot(filePath)` returns null for Write/Edit operations, allow immediately. The guard only protects git repos from direct-on-main edits.\n\n**File:** `tools/wip-branch-guard/guard.mjs`\n\n## Bug 2: UTC date mismatch in wip-release\n\n**Problem:** Dev-update files are named with local date (e.g. `2026-03-16--cc-mini--...md`). But `new Date().toISOString().split('T')[0]` returns UTC date. After midnight UTC (4 PM PST), the dates diverge. Release notes gate fails to find today's dev-update.\n\n**Fix:** Replaced all three instances of `toISOString()` date extraction with explicit local date construction using `getFullYear()/getMonth()/getDate()`.\n\n**Files:**\n- `tools/wip-release/cli.js` (line 80, dev-update detection)\n- `tools/wip-release/core.mjs` (line 92, CHANGELOG date)\n- `tools/wip-release/core.mjs` (line 582, product docs sync date)\n\nv1.9.43 | 2026-03-17T14:49:09.342Z | user\n\n# Guard non-repo files fix + UTC date fix\n\nTwo bugs fixed in one PR.\n\n## Bug 1: Guard blocks files outside git repos (#77)\n\n**Problem:** When Write/Edit targets a file outside any git repo (e.g. `~/.claude/plans/`), `findRepoRoot()` returns null. The guard fell back to CWD (`~/.openclaw` on main) and blocked the operation. Files outside repos aren't the guard's concern.\n\n**Fix:** If `findRepoRoot(filePath)` returns null for Write/Edit operations, allow immediately. The guard only protects git repos from direct-on-main edits.\n\n**File:** `tools/wip-branch-guard/guard.mjs`\n\n## Bug 2: UTC date mismatch in wip-release\n\n**Problem:** Dev-update files are named with local date (e.g. `2026-03-16--cc-mini--...md`). But `new Date().toISOString().split('T')[0]` returns UTC date. After midnight UTC (4 PM PST), the dates diverge. Release notes gate fails to find today's dev-update.\n\n**Fix:** Replaced all three instances of `toISOString()` date extraction with explicit local date construction using `getFullYear()/getMonth()/getDate()`.\n\n**Files:**\n- `tools/wip-release/cli.js` (line 80, dev-update detection)\n- `tools/wip-release/core.mjs` (line 92, CHANGELOG date)\n- `tools/wip-release/core.mjs` (line 582, product docs sync date)\n\nv1.9.42 | 2026-03-17T13:52:32.722Z | user\n\n# Guard non-repo files fix + UTC date fix\n\nTwo bugs fixed in one PR.\n\n## Bug 1: Guard blocks files outside git repos (#77)\n\n**Problem:** When Write/Edit targets a file outside any git repo (e.g. `~/.claude/plans/`), `findRepoRoot()` returns null. The guard fell back to CWD (`~/.openclaw` on main) and blocked the operation. Files outside repos aren't the guard's concern.\n\n**Fix:** If `findRepoRoot(filePath)` returns null for Write/Edit operations, allow immediately. The guard only protects git repos from direct-on-main edits.\n\n**File:** `tools/wip-branch-guard/guard.mjs`\n\n## Bug 2: UTC date mismatch in wip-release\n\n**Problem:** Dev-update files are named with local date (e.g. `2026-03-16--cc-mini--...md`). But `new Date().toISOString().split('T')[0]` returns UTC date. After midnight UTC (4 PM PST), the dates diverge. Release notes gate fails to find today's dev-update.\n\n**Fix:** Replaced all three instances of `toISOString()` date extraction with explicit local date construction using `getFullYear()/getMonth()/getDate()`.\n\n**Files:**\n- `tools/wip-release/cli.js` (line 80, dev-update detection)\n- `tools/wip-release/core.mjs` (line 92, CHANGELOG date)\n- `tools/wip-release/core.mjs` (line 582, product docs sync date)\n\nv1.9.41 | 2026-03-17T13:40:29.509Z | user\n\n# Doc enforcement gates for wip-release\n\n**Date:** 2026-03-16\n**Closes:** #117, #128\n\n## What changed\n\nTwo new pre-release gates in wip-release:\n\n**Technical Docs Gate (#117):** When source code (*.mjs, *.js, *.ts) changed since the last release tag, checks that SKILL.md or TECHNICAL.md was also modified. Catches code shipping without doc updates. Warns on patch, blocks on minor/major. Skip with `--skip-tech-docs-check`.\n\n**Interface Coverage Gate (#128):** For toolbox repos, scans each tool in tools/*/ for actual interfaces (CLI, Module, MCP, OC Plugin, Skill, CC Hook) and compares to the coverage table in README.md and SKILL.md. Reports: tools missing from table, interfaces detected but not marked Y, interfaces marked Y but not detected, tool count mismatches. Warns on patch, blocks on minor/major. Skip with `--skip-coverage-check`.\n\nBoth follow the same pattern as existing gates (checkProductDocs, checkStaleBranches). Both run in real and dry-run modes.\n\n## Why\n\nSource code was shipping without doc updates constantly. SKILL.md and TECHNICAL.md fell behind the code. Interface coverage tables drifted from reality. These gates catch it before release instead of after.\n\nv1.9.40 | 2026-03-16T22:22:37.281Z | user\n\n# Auto-sync product docs version/date on release\n\n**Date:** 2026-03-16\n**Closes:** #202\n\n## What changed\n\nwip-release now auto-updates version and date lines in product docs before the release commit. No more stale \"Current version: v1.9.1\" when you're shipping v1.9.39.\n\nFiles updated automatically:\n- `ai/product/plans-prds/roadmap.md`: \"Current version\" and \"Last updated\"\n- `ai/product/readme-first-product.md`: \"Last updated\" and \"What's Built (as of vX.Y.Z)\"\n\nRuns between changelog update and git commit (step 3.75). Only touches files that exist. Only updates lines that match the expected patterns.\n\n## Why\n\nThese files were stale from v1.9.1 through v1.9.39 (8 days, 38 releases). Nobody remembered to update them. The existing product docs gate warned about it but couldn't fix it. Now it fixes itself.\n\nv1.9.39 | 2026-03-16T22:06:25.489Z | user\n\n# Wire license-guard as Claude Code PreToolUse hook\n\n**Date:** 2026-03-16\n**Closes:** #130\n\n## What changed\n\nlicense-guard now registers as a Claude Code PreToolUse hook on install. Previously the hook code existed (hook.mjs) but was never wired into the deploy system. Now:\n\n- Renamed hook.mjs to guard.mjs (matches file-guard/branch-guard convention that LDM OS deploy.mjs expects)\n- Added `claudeCode.hook` config to package.json (event: PreToolUse, matcher: Bash, timeout: 5)\n- On next `ldm install`, the hook auto-registers in ~/.claude/settings.json\n\nThe hook blocks git commit and git push when license compliance fails:\n- LICENSE file missing\n- Copyright doesn't match .license-guard.json config\n- CLA.md missing\n- README.md missing ## License section\n- MIT+AGPL config but LICENSE or README only mentions MIT\n\nRepos without .license-guard.json are not affected (the hook silently passes).\n\n## Also done\n\n- Updated plan statuses: license guard Phase 1 complete, bootstrap LDM OS complete\n- Bootstrap LDM OS was already shipped in install.js (lines 740-812)\n\nv1.9.38 | 2026-03-16T21:56:37.161Z | user\n\n# GitHub Packages publish from public repo\n\n**Date:** 2026-03-16\n**Closes:** #193\n\n## What changed\n\n`deploy-public.sh` now publishes to GitHub Packages from the public repo clone after the npm publish step. Previously, GitHub Packages were only published from the private repo during `wip-release`, so they showed on the private repo's Packages tab. Users couldn't see them.\n\nNow packages show on the public repo's Packages tab where users expect to find them. Uses `gh auth token` for authentication (already available from the gh CLI).\n\n## Why\n\nThe Packages tab on public repos was empty. Users visiting wipcomputer/wip-ldm-os or wipcomputer/wip-ai-devops-toolbox saw no packages even though they were published. The packages existed but were linked to the private repo.\n\nv1.9.37 | 2026-03-16T21:32:06.695Z | user\n\n# GitHub Packages publish from public repo\n\n**Date:** 2026-03-16\n**Closes:** #193\n\n## What changed\n\n`deploy-public.sh` now publishes to GitHub Packages from the public repo clone after the npm publish step. Previously, GitHub Packages were only published from the private repo during `wip-release`, so they showed on the private repo's Packages tab. Users couldn't see them.\n\nNow packages show on the public repo's Packages tab where users expect to find them. Uses `gh auth token` for authentication (already available from the gh CLI).\n\n## Why\n\nThe Packages tab on public repos was empty. Users visiting wipcomputer/wip-ldm-os or wipcomputer/wip-ai-devops-toolbox saw no packages even though they were published. The packages existed but were linked to the private repo.\n\nv1.9.36 | 2026-03-16T18:21:32.521Z | user\n\n# GitHub Packages publish from public repo\n\n**Date:** 2026-03-16\n**Closes:** #193\n\n## What changed\n\n`deploy-public.sh` now publishes to GitHub Packages from the public repo clone after the npm publish step. Previously, GitHub Packages were only published from the private repo during `wip-release`, so they showed on the private repo's Packages tab. Users couldn't see them.\n\nNow packages show on the public repo's Packages tab where users expect to find them. Uses `gh auth token` for authentication (already available from the gh CLI).\n\n## Why\n\nThe Packages tab on public repos was empty. Users visiting wipcomputer/wip-ldm-os or wipcomputer/wip-ai-devops-toolbox saw no packages even though they were published. The packages existed but were linked to the private repo.\n\nv1.9.35 | 2026-03-16T18:02:12.978Z | user\n\n# GitHub Packages publish from public repo\n\n**Date:** 2026-03-16\n**Closes:** #193\n\n## What changed\n\n`deploy-public.sh` now publishes to GitHub Packages from the public repo clone after the npm publish step. Previously, GitHub Packages were only published from the private repo during `wip-release`, so they showed on the private repo's Packages tab. Users couldn't see them.\n\nNow packages show on the public repo's Packages tab where users expect to find them. Uses `gh auth token` for authentication (already available from the gh CLI).\n\n## Why\n\nThe Packages tab on public repos was empty. Users visiting wipcomputer/wip-ldm-os or wipcomputer/wip-ai-devops-toolbox saw no packages even though they were published. The packages existed but were linked to the private repo.\n\nv1.9.34 | 2026-03-16T16:33:10.662Z | user\n\n# GitHub Packages publish from public repo\n\n**Date:** 2026-03-16\n**Closes:** #193\n\n## What changed\n\n`deploy-public.sh` now publishes to GitHub Packages from the public repo clone after the npm publish step. Previously, GitHub Packages were only published from the private repo during `wip-release`, so they showed on the private repo's Packages tab. Users couldn't see them.\n\nNow packages show on the public repo's Packages tab where users expect to find them. Uses `gh auth token` for authentication (already available from the gh CLI).\n\n## Why\n\nThe Packages tab on public repos was empty. Users visiting wipcomputer/wip-ldm-os or wipcomputer/wip-ai-devops-toolbox saw no packages even though they were published. The packages existed but were linked to the private repo.\n\nv1.9.33 | 2026-03-15T23:16:27.104Z | user\n\n# --version on all CLIs + issue cleanup\n\n**Date:** 2026-03-15\n**Closes:** #190, #191, #169, #123, #119\n\n## What changed\n\nAll 7 CLI tools now support `--version` and `-v`. Each reads its own `package.json` and prints the version. Previously, `wip-release --version` printed the help text instead of a version number.\n\nTools updated: wip-release, wip-repos, wip-license-guard, wip-repo-permissions, wip-repo-init, wip-readme-format, wip-file-guard, wip-branch-guard.\n\nwip-license-guard also got a proper README (#169) with all commands, config format, and integration docs.\n\n## Issues closed\n\n- #190: wip-release --version should work\n- #191: enforce --version on all CLI tools\n- #169: wip-license-guard needs its own README\n- #123: Merge/Deploy/Install conflated (enforced across v1.9.25-v1.9.30)\n- #119: All destructive tools must have --dry-run (all confirmed)\n\nv1.9.32 | 2026-03-15T23:14:59.379Z | user\n\n# --version on all CLIs + issue cleanup\n\n**Date:** 2026-03-15\n**Closes:** #190, #191, #169, #123, #119\n\n## What changed\n\nAll 7 CLI tools now support `--version` and `-v`. Each reads its own `package.json` and prints the version. Previously, `wip-release --version` printed the help text instead of a version number.\n\nTools updated: wip-release, wip-repos, wip-license-guard, wip-repo-permissions, wip-repo-init, wip-readme-format, wip-file-guard, wip-branch-guard.\n\nwip-license-guard also got a proper README (#169) with all commands, config format, and integration docs.\n\n## Issues closed\n\n- #190: wip-release --version should work\n- #191: enforce --version on all CLI tools\n- #169: wip-license-guard needs its own README\n- #123: Merge/Deploy/Install conflated (enforced across v1.9.25-v1.9.30)\n- #119: All destructive tools must have --dry-run (all confirmed)\n\nv1.9.31 | 2026-03-15T22:54:24.935Z | user\n\n# Release Notes: wip-ai-devops-toolbox v1.9.31\n\nBranch guard no longer blocks global npm operations on main.\n\n## What changed\n\nMoved `npm install -g` and `npm link` from BLOCKED_BASH_PATTERNS to ALLOWED_BASH_PATTERNS in `wip-branch-guard/guard.mjs`. Global npm operations modify `/opt/homebrew/`, not the repo. Local `npm install` (no -g flag) remains blocked.\n\n## Why\n\nDuring LDM OS v0.4.0 dogfood, a CC session couldn't run `npm install -g @wipcomputer/wip-ldm-os@0.4.0` even after Parker explicitly said \"install.\" The guard was too aggressive. Original intent (issue #137) was to block repo writes on main, not system-level package installs.\n\n## Issues closed\n\n- Closes #188 (branch guard blocks npm install -g)\n- Cross-ref: wipcomputer/wip-ldm-os#44\n\n## How to verify\n\n```bash\n# On main branch, these should now succeed:\nnpm install -g @wipcomputer/wip-ldm-os@0.4.0\nnpm link\n# This should still be blocked on main:\nnpm install\n```\n\nv1.9.30 | 2026-03-15T22:17:49.080Z | user\n\n# Release notes must be a file on disk\n\n**Date:** 2026-03-15\n\n## What changed\n\nwip-release no longer accepts the `--notes` flag. Release notes MUST come from a file on disk:\n\n1. `RELEASE-NOTES-v{version}.md` in repo root (auto-detected)\n2. `ai/dev-updates/YYYY-MM-DD--description.md` (auto-detected)\n3. `--notes-file=path` (explicit file path)\n\nIf no file exists, the release is blocked. The gate scaffolds a template (`RELEASE-NOTES-v{version}.md`) so the agent has something to fill in.\n\n## Why\n\nThe `--notes` flag was the root cause of every bad release note. Agents passed one-liners like `--notes=\"fix bug\"` and the gate let them through. Even after we added length checks and changelog detection, agents found ways around it. The flag was an escape hatch that undermined the entire system.\n\nThe file-on-disk requirement solves three problems:\n1. **Reviewability.** The file is on the branch. It shows up in the PR diff. Parker can read and approve the release notes before merge.\n2. **Quality.** Writing a file forces the agent to think about what changed and why. A flag encourages one-liners.\n3. **History.** The file is committed to git. The release notes are part of the repo history, not a transient CLI argument.\n\n## What agents need to do\n\nBefore running `wip-release`:\n1. Write `RELEASE-NOTES-v{version}.md` or `ai/dev-updates/YYYY-MM-DD--description.md`\n2. Commit it on the branch\n3. The file shows up in the PR for review\n4. After merge to main, `wip-release` auto-detects it\n\nIf the agent forgets, `wip-release` blocks and scaffolds a template.\n\nv1.9.29 | 2026-03-15T22:14:35.010Z | user\n\n# Release notes must be a file on disk\n\n**Date:** 2026-03-15\n\n## What changed\n\nwip-release no longer accepts the `--notes` flag. Release notes MUST come from a file on disk:\n\n1. `RELEASE-NOTES-v{version}.md` in repo root (auto-detected)\n2. `ai/dev-updates/YYYY-MM-DD--description.md` (auto-detected)\n3. `--notes-file=path` (explicit file path)\n\nIf no file exists, the release is blocked. The gate scaffolds a template (`RELEASE-NOTES-v{version}.md`) so the agent has something to fill in.\n\n## Why\n\nThe `--notes` flag was the root cause of every bad release note. Agents passed one-liners like `--notes=\"fix bug\"` and the gate let them through. Even after we added length checks and changelog detection, agents found ways around it. The flag was an escape hatch that undermined the entire system.\n\nThe file-on-disk requirement solves three problems:\n1. **Reviewability.** The file is on the branch. It shows up in the PR diff. Parker can read and approve the release notes before merge.\n2. **Quality.** Writing a file forces the agent to think about what changed and why. A flag encourages one-liners.\n3. **History.** The file is committed to git. The release notes are part of the repo history, not a transient CLI argument.\n\n## What agents need to do\n\nBefore running `wip-release`:\n1. Write `RELEASE-NOTES-v{version}.md` or `ai/dev-updates/YYYY-MM-DD--description.md`\n2. Commit it on the branch\n3. The file shows up in the PR for review\n4. After merge to main, `wip-release` auto-detects it\n\nIf the agent forgets, `wip-release` blocks and scaffolds a template.\n\nv1.9.28 | 2026-03-15T19:02:59.529Z | user\n\n# Release Notes Quality Gate\n\n**Date:** 2026-03-15\n\n## What changed\n\nwip-release now blocks ALL releases (patch, minor, major) if the release notes are bad. Previously, patch releases only warned. Now they block.\n\nThe gate checks:\n- Notes must be at least 50 characters\n- Notes can't look like a changelog entry (\"fix: ...\", \"add: ...\", \"update: ...\")\n- Minor/major still require a file (not --notes flag)\n\nIf the gate blocks, it tells you exactly how to fix it: write a RELEASE-NOTES file, write a dev update, or use --notes with at least 50 chars of real description.\n\n## Why\n\nRelease notes were consistently garbage. One-liner --notes flags like \"Fix bug\" or \"Update docs\" sailed through on patch releases. The warnings were ignored by both humans and agents. Every release page on GitHub had thin, useless notes that didn't explain what changed or why.\n\n## Also in this release\n\n- wip-repo-init templates renamed from ai/ to templates/ so they ship with npm install (deploy-public.sh was stripping them)\n- SKILL.md restart notice after install (hooks need session restart)\n- SPEC.md and TECHNICAL.md updated with all 17 tools and LDM OS links\n- Branch guard matcher fix (catches Bash + NotebookEdit)\n- Forced Git Worktrees and Branch Guard sections added to SKILL.md\n\nv1.9.27 | 2026-03-15T17:32:12.415Z | user\n\n# Release Notes Quality Gate\n\n**Date:** 2026-03-15\n\n## What changed\n\nwip-release now blocks ALL releases (patch, minor, major) if the release notes are bad. Previously, patch releases only warned. Now they block.\n\nThe gate checks:\n- Notes must be at least 50 characters\n- Notes can't look like a changelog entry (\"fix: ...\", \"add: ...\", \"update: ...\")\n- Minor/major still require a file (not --notes flag)\n\nIf the gate blocks, it tells you exactly how to fix it: write a RELEASE-NOTES file, write a dev update, or use --notes with at least 50 chars of real description.\n\n## Why\n\nRelease notes were consistently garbage. One-liner --notes flags like \"Fix bug\" or \"Update docs\" sailed through on patch releases. The warnings were ignored by both humans and agents. Every release page on GitHub had thin, useless notes that didn't explain what changed or why.\n\n## Also in this release\n\n- wip-repo-init templates renamed from ai/ to templates/ so they ship with npm install (deploy-public.sh was stripping them)\n- SKILL.md restart notice after install (hooks need session restart)\n- SPEC.md and TECHNICAL.md updated with all 17 tools and LDM OS links\n- Branch guard matcher fix (catches Bash + NotebookEdit)\n- Forced Git Worktrees and Branch Guard sections added to SKILL.md\n\nv1.9.26 | 2026-03-15T16:17:06.817Z | user\n\nAdd restart notice after install/update. Hooks need session restart to take effect.\n\nv1.9.25 | 2026-03-14T17:29:48.521Z | user\n\nFix branch guard matcher (catches Bash + NotebookEdit). Add Forced Git Worktrees and Branch Guard sections to SKILL.md. Update SPEC.md and TECHNICAL.md with all 17 tools and LDM OS links.\n\nv1.9.24 | 2026-03-14T17:05:52.354Z | user\n\nNumber tools in dry run and already-installed lists. Dogfood iteration.\n\nv1.9.23 | 2026-03-14T17:02:03.360Z | user\n\nForce verbatim tool list display. AI must show all 17 tools with descriptions, never summarize.\n\nv1.9.22 | 2026-03-14T16:54:57.489Z | user\n\nAll 17 tools listed with descriptions. New section order: Setup, Infrastructure, Repo Management, License, Release. Conversational prompt.\n\nv1.9.21 | 2026-03-14T16:42:18.325Z | user\n\nAdd Already Installed section with tool descriptions. Dogfood fix.\n\nv1.9.20 | 2026-03-14T16:27:39.495Z | user\n\nMake root package publishable. npm install -g @wipcomputer/wip-ai-devops-toolbox now installs all 12 CLI tools.\n\nv1.9.19 | 2026-03-14T16:17:08.334Z | user\n\nAdd websiteRepo to .publish-skill.json. Auto-publish SKILL.md to website on release. Fix install prompt URLs to use wip- prefix.\n\nArchive index:\n\nArchive v1.9.72: 15 files, 14856 bytes\n\nFiles: init.mjs (4779b), package.json (260b), README.md (1011b), skill-card.md (1725b), SKILL.md (2435b), templates/_sort/README.md (573b), templates/_trash/README.md (702b), templates/dev-updates/README.md (1512b), templates/product/notes/README.md (662b), templates/product/plans-prds/roadmap.md (2276b), templates/product/plans-prds/todos/README.md (2103b), templates/product/product-ideas/README.md (763b), templates/product/readme-first-product.md (4157b), templates/read-me-first.md (4949b), _meta.json (133b)\n\nFile v1.9.72:SKILL.md\n\n---\nname: wip-repo-init\ndescription: Scaffold the standard ai/ directory structure in any repo.\nlicense: MIT\ninterface: [cli, skill]\nmetadata:\n display-name: \"Repo Init\"\n version: \"1.0.0\"\n homepage: \"https://github.com/wipcomputer/wip-ai-devops-toolbox\"\n author: \"Parker Todd Brooks\"\n category: repo-management\n capabilities:\n - scaffold-ai-dir\n - template-copy\n requires:\n bins: [node]\n openclaw:\n requires:\n bins: [node]\n install:\n - id: node\n kind: node\n package: \"@wipcomputer/wip-repo-init\"\n bins: [wip-repo-init]\n label: \"Install via npm\"\n emoji: \"📁\"\ncompatibility: Requires node. Node.js 18+.\n---\n\n# Repo Init\n\nScaffolds the standard `ai/` directory structure in any repo.\n\n## Commands\n\n```\nwip-repo-init /path/to/repo # scaffold ai/ in a repo\nwip-repo-init /path/to/repo --dry-run # preview without changes\nwip-repo-init /path/to/repo --yes # skip confirmation prompt\n```\n\n## What happens\n\n**New repo (no ai/ folder):** Creates the full standard structure with all READMEs explaining what goes where.\n\n**Existing repo (ai/ folder exists):** Shows you what will happen and asks for confirmation. If you say yes:\n1. Moves your current `ai/` contents to `ai/_sort/ai_old/`\n2. Scaffolds the new standard structure\n3. You sort files from `ai_old/` into the new structure at your own pace\n\nNothing is deleted. Your old files are all in `ai/_sort/ai_old/`.\n\n## The standard ai/ structure\n\n```\nai/\n read-me-first.md <- explains everything, links to all sections\n _sort/ <- holding pen for files that need sorting\n _trash/ <- archive (never delete, move here)\n dev-updates/ <- engineering changelog, auto-detected by wip-release\n product/\n readme-first-product.md <- the product bible\n notes/ <- freeform notes, research\n plans-prds/ <- plans with lifecycle stages\n roadmap.md <- prioritized roadmap\n current/ <- plans being built now\n upcoming/ <- plans that are next\n archive-complete/ <- plans that shipped\n todos/ <- per-agent todo files\n product-ideas/ <- ideas that aren't plans yet\n```\n\nEvery folder has a `_trash/` subfolder. Every section has a README explaining what it is, what goes in it, and how to maintain it.\n\n## Interfaces\n\nCLI, Skill\n\nFile v1.9.72:README.md\n\n###### WIP Computer\n\n# Repo Init\n\nScaffold the standard `ai/` directory in any repo. Plans, notes, ideas, dev updates, todos. One command.\n\n## What it does\n\n- **New repo:** Creates the full `ai/` directory structure\n- **Existing repo:** Moves old `ai/` contents to `ai/_sort/ai_old/` so you can sort at your own pace\n- Nothing is deleted\n\n## The `ai/` directory\n\n```\nai/\n plan/ architecture plans, roadmaps\n dev-updates/ what was built, session logs\n todos/\n PUNCHLIST.md blockers to ship\n inboxes/ per-agent action items\n notes/ research, references, raw conversation logs\n```\n\nThe `ai/` folder is the development process. It is not part of the published product. Public repos exclude it via deploy-public.sh.\n\n## Usage\n\n```bash\nnode tools/wip-repo-init/init.mjs /path/to/repo\n```\n\n## Interfaces\n\n- **CLI**: Run from terminal\n- **Skill**: SKILL.md for agent instructions\n\n## Part of [AI DevOps Toolbox](https://github.com/wipcomputer/wip-ai-devops-toolbox)\n\nFile v1.9.72:templates/_sort/README.md\n\n# _sort/\n\nThe holding pen. Files that need to be looked at and filed somewhere.\n\n## What Goes Here\n\n- iCloud duplicates or randomly placed files that need sorting\n- Files you're not sure where to put yet\n- Anything that needs a human to look at it and decide where it belongs\n\n## Rules\n\n- **Not trash.** `_sort/` is for files you want to review. `_trash/` is for files you're done with.\n- **Don't let it pile up.** Check this folder periodically. File things or trash them.\n- **Agents:** If you don't know where a file goes, put it in `_sort/`. A human will sort it later.\n\nFile v1.9.72:templates/_trash/README.md\n\n# _trash/\n\nThe archive. Files that are done, replaced, or consumed. Never delete anything. Move it here.\n\n## What Goes Here\n\n- Superseded plans (replaced by a newer version)\n- Consumed release notes (already used by `wip-release`)\n- Abandoned drafts\n- Anything you're done with but might need to reference later\n\n## Rules\n\n- **This is not garbage.** It's the archive. Everything in git history is recoverable, but `_trash/` keeps things findable without digging through commits.\n- **Subfolders have their own `_trash/`.** Use the nearest one. `dev-updates/_trash/` for old dev updates, `product/notes/_trash/` for old notes, etc.\n- **Never delete files from the repo.** Move them to `_trash/` instead.\n\nFile v1.9.72:templates/dev-updates/README.md\n\n# dev-updates/\n\nOne file per significant change. Written as you work, auto-detected by `wip-release`.\n\n## What This Folder Is\n\nDev updates are the engineering changelog. Every time you do significant work (ship a feature, fix a bug, change architecture), write a dev update. `wip-release` picks up today's dev updates and uses them as release notes.\n\nThis is not a place for plans or ideas. It's a record of what was built and why.\n\n## Naming Convention\n\n```\nYYYY-MM-DD--HH-MM--agent--description.md\n```\n\nExamples:\n- `2026-03-11--09-30--cc-mini--fix-hook-duplicates.md`\n- `2026-03-10--14-00--lesa-mini--add-voice-call-support.md`\n\n## File Format\n\n```markdown\n# Short title of what changed\n\n**Date:** YYYY-MM-DD HH:MM TZ\n**Author:** Agent Name (agent-id)\n\n## Problem\n\nWhat was broken or missing.\n\n## Fix / What Changed\n\nWhat you did and why.\n\n## Files changed\n\n- `path/to/file.js` ... what changed in it\n\nCloses #issue-number (if applicable)\n```\n\n## Rules\n\n- **Write them as you work.** Don't batch them at the end. Each significant change gets its own file.\n- **One file per change.** Not one file per day. If you fix two unrelated bugs, write two files.\n- **Include the \"why.\"** \"Fixed X\" is a commit message. A dev update explains why it was broken and why the fix works.\n- **Reference issues.** If there's a GitHub issue, add `Closes #N` at the bottom.\n- **Consumed files go to `_trash/`.** `wip-release` doesn't move them automatically, but the release notes files it generates do get trashed after release.\n\nFile v1.9.72:templates/product/notes/README.md\n\n# notes/\n\nFreeform notes, research, and observations. Anything that's useful context but isn't a plan, idea, or dev update.\n\n## What Goes Here\n\n- Research notes (\"I looked into X and found...\")\n- Meeting notes or conversation summaries\n- Technical investigations\n- Context that multiple plans reference\n- Anything that doesn't fit in `plans-prds/` or `product-ideas/`\n\n## Naming\n\nNo strict convention. Use descriptive names:\n\n```\nYYYY-MM-DD--agent--topic.md\n```\n\nExample: `2026-03-10--cc-mini--readme-standard-and-universal-installer-vision.md`\n\n## Rules\n\n- **Not a plan?** Put it here, not in `plans-prds/`.\n- **Done with it?** Move to `_trash/`. Don't delete.\n\nFile v1.9.72:templates/product/plans-prds/todos/README.md\n\n# todos/\n\nOne todo file per person or agent. Three sections per file: To Do, Done, Deprecated.\n\n## What This Folder Is\n\nTodos that are specific to this repo. Each person or agent who works on this repo gets one file. The file tracks what they need to do, what they've done, and what got dropped.\n\nFor cross-repo work or bigger items, use GitHub Issues. Todos here are for repo-scoped tasks that don't need the overhead of an issue.\n\n## Files\n\nOne file per person/agent. Name it `[Name]-todo.md`.\n\nExample:\n\n| File | Who |\n|------|-----|\n| `Parker-todo.md` | Parker (human tasks: reviews, credentials, approvals) |\n| `CC-Mini-todo.md` | Claude Code on Mac Mini (code, builds, deploys) |\n\nCreate the file when that person/agent first has work to do. No empty placeholder files.\n\n## File Format\n\n```markdown\n# [Name] Todos\n\n**Last updated:** YYYY-MM-DD\n\n## To Do\n\n- [ ] Task description\n- [ ] Task description (blocked by: reason)\n\n## Done\n\n- [x] Task description (YYYY-MM-DD)\n- [x] Task description (YYYY-MM-DD)\n\n## Deprecated\n\n- ~~Task description~~ ... reason. (YYYY-MM-DD)\n```\n\n## Rules\n\n- **Never delete anything.** Items move between sections, never off the page.\n- **To Do** ... work that needs to happen.\n- **Done** ... completed work. Check the box, add the date.\n- **Deprecated** ... planned but no longer needed. Strikethrough, add the reason and date. Not the same as Done. Done means it shipped. Deprecated means the requirement changed.\n- **Update the date** at the top of the file every time you edit it.\n- **One file per person/agent.** No dated files, no subfolders, no inboxes.\n- **Blocked items** stay in To Do with a `(blocked by: reason)` note. Don't move them to a separate section.\n\n## When to Use Todos vs GitHub Issues\n\n| Use | When |\n|-----|------|\n| **Todo file** | Quick tasks, repo-scoped work, things you'll do this session or this week |\n| **GitHub Issue** | Bugs, feature requests, cross-repo work, things that need tracking or discussion |\n\nBoth is fine. File an issue AND add a todo that references it. The todo is your personal checklist. The issue is the team's record.\n\nFile v1.9.72:templates/product/product-ideas/README.md\n\n# product-ideas/\n\nIdeas that aren't plans yet. The incubator.\n\n## What Goes Here\n\nAn idea is something you want to build but haven't committed to. It doesn't have tasks, timelines, or priorities. It's a \"what if\" or \"we should.\"\n\nWhen an idea is ready to become a plan, move it to `../plans-prds/upcoming/` and flesh it out with tasks and priorities.\n\n## Format\n\nNo strict format. But a good idea file usually has:\n\n- **What it is** (one paragraph)\n- **Why it matters** (what problem it solves)\n- **Open questions** (what you'd need to figure out)\n- **External references** (links, reviews, research)\n\n## Rules\n\n- **Not ready to plan?** It stays here.\n- **Ready to plan?** Move to `../plans-prds/upcoming/`.\n- **Killed?** Move to `_trash/` with a note about why.\n\nFile v1.9.72:_meta.json\n\n{\n \"ownerId\": \"kn7b4mj57xb02gqhvjzgzkxq557zz95h\",\n \"slug\": \"wip-repo-init\",\n \"version\": \"1.9.72\",\n \"publishedAt\": 1776806726686\n}\n\nFile v1.9.72:skill-card.md\n\n## Description:\n\nScaffold the standard ai/ directory structure in any repo.\n\nThis skill is ready for commercial/non-commercial use.\n\n## Publisher:\n\n[parkertoddbrooks](https://clawhub.ai/user/parkertoddbrooks)\n\n### License/Terms of Use:\n\nMIT\n\n## Use Case:\n\nDevelopers and engineering teams use this skill to create or normalize an ai/ workspace for plans, notes, development updates, todos, and product documentation inside a repository.\n\n### Deployment Geography for Use:\n\nGlobal\n\n## Known Risks and Mitigations:\n\nRisk: Running the tool on a repository with an existing ai/ folder reorganizes that folder by moving current contents under ai/_sort/ai_old/.\n\nMitigation: Use --dry-run first on existing repositories, and avoid --yes unless you are comfortable with the planned move.\n\n## Reference(s):\n\n- [ClawHub skill page](https://clawhub.ai/parkertoddbrooks/skills/wip-repo-init)\n- [AI DevOps Toolbox](https://github.com/wipcomputer/wip-ai-devops-toolbox)\n- [Skill definition](SKILL.md)\n- [README](README.md)\n\n## Skill Output:\n\n**Output Type(s):** [Files, Markdown, Shell commands, Configuration instructions]\n\n**Output Format:** [Generated repository files and Markdown templates, with CLI guidance for command-line use]\n\n**Output Parameters:** [1D]\n\n**Other Properties Related to Output:** [Requires Node.js 18+; supports dry-run preview and confirmation controls for existing ai/ folders.]\n\n## Skill Version(s):\n\n1.9.72 (source: server release metadata)\n\n## Ethical Considerations:\n\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment.\n\nFile v1.9.72:templates/product/plans-prds/roadmap.md\n\n# [Product Name] ... Roadmap\n\n**Last updated:** YYYY-MM-DD\n**Current version:** vX.Y.Z\n\nItems are either **Upcoming**, **Done**, or **Deprecated**. Never delete. Always move.\n\n---\n\n## What This File Is\n\nThe prioritized roadmap for this product. Three sections:\n\n- **Upcoming** ... work that's planned, ordered by priority. Top = most important.\n- **Done** ... shipped work. Moved here with a date when it's released.\n- **Deprecated** ... planned work that's no longer needed. Strikethrough, add the reason and date. Not the same as Done. Done means it shipped. Deprecated means the plan changed.\n\n**Keep it honest.** If something isn't going to happen, deprecate it. Don't leave dead items in Upcoming.\n\n**Keep it prioritized.** Upcoming items have priority numbers. When priorities shift, renumber them. The order is the strategy.\n\n---\n\n## Vision\n\n_One paragraph. Where is this product going? Not the feature list. The north star._\n\n---\n\n## Upcoming\n\n### Priority 1 ... [Feature/Epic Name]\n\n_What it is and why it matters in 1-2 sentences._\n\n- [ ] Task one\n- [ ] Task two\n- [ ] Task three\n\n### Priority 2 ... [Feature/Epic Name]\n\n_What it is and why it matters._\n\n- [ ] Task one\n- [ ] Task two\n\n_Add more priorities as needed. Number them. The number is the priority._\n\n---\n\n## Done\n\n### [Feature Name] (YYYY-MM-DD)\n\n- [x] What shipped\n- [x] What shipped\n\n_Move items here when they're released. Include the date. Keep the checkbox format so it's clear what was planned vs what actually shipped._\n\n---\n\n## Deprecated\n\n- ~~[Feature that was planned]~~ ... reason it was dropped. (YYYY-MM-DD)\n\n_Deprecated is not a graveyard. It's a record of decisions. When someone asks \"why didn't we build X?\" the answer is here._\n\n---\n\n## How to Update This File\n\n- **Shipped a feature?** Move it from Upcoming to Done. Add the date. Check the boxes.\n- **Dropped a plan?** Move it to Deprecated. Strikethrough, add the reason and date.\n- **New idea that's ready to plan?** Add to Upcoming with a priority number. Renumber if needed.\n- **Idea that's NOT ready to plan?** Put it in `../product-ideas/` instead. The roadmap is for committed work.\n- **Priorities shifted?** Renumber the Upcoming section. The order matters.\n- **Always update** \"Last updated\" and \"Current version\" at the top.\n\nFile v1.9.72:templates/product/readme-first-product.md\n\n# [Product Name] ... Read Me First\n\n**Last updated:** YYYY-MM-DD\n**Status:** Living document. Read this before any plan, build, or PR.\n\n---\n\n## What This File Is\n\nThis is the product bible for this repo. It answers: what is this thing, why does it exist, how does it work, and what's the current state. Every person and agent working on this repo reads this first.\n\n**Keep it current.** Update it when the architecture changes, when major features ship, when the mental model shifts. If this file is stale, the team is working from bad context.\n\n**Keep it honest.** Don't describe the aspirational version. Describe what's built and what's missing. Plans go in `plans-prds/`. This file is ground truth.\n\n---\n\n## This Folder\n\n```\nproduct/\n readme-first-product.md <- you're here (the product bible)\n _trash/\n notes/ <- freeform notes, research, observations\n plans-prds/ <- plans with lifecycle stages\n roadmap.md <- the prioritized roadmap\n current/ <- plans being built right now\n upcoming/ <- plans that are next\n archive-complete/ <- plans that shipped\n todos/ <- per-agent task lists\n _sort/ <- plans that need categorizing\n _trash/\n product-ideas/ <- ideas that aren't plans yet\n```\n\n**Navigate:**\n- **Want to know what's planned?** Read `plans-prds/roadmap.md`.\n- **Want to know what's being built right now?** Look in `plans-prds/current/`.\n- **Have an idea?** Write it up in `product-ideas/`.\n- **Ready to turn an idea into a plan?** Move it from `product-ideas/` to `plans-prds/upcoming/` (or `current/` if starting now).\n\n**Plan lifecycle:**\n```\nproduct-ideas/ -> upcoming/ -> current/ -> archive-complete/\n (idea) (planned) (building) (shipped)\n```\n\n---\n\n## What [Product Name] Is\n\n_One paragraph. What it does in human words. Not what it is technically. What problem it solves and for whom._\n\n---\n\n## Core Concepts\n\n_The 3-5 mental models someone needs to understand this product. Not implementation details. The \"aha\" moments that make everything else make sense._\n\n_Example: \"Raw files are ground truth. Databases are indexes. If anything breaks, rebuild from raw files.\"_\n\n_Example: \"One agent per harness per machine. That's the identity unit.\"_\n\n---\n\n## How It Works\n\n_The architecture at a level a new contributor can follow. Diagrams are fine. ASCII art is fine. The goal is: someone reads this section and can navigate the codebase without asking questions._\n\n_Include:_\n- _High-level data flow_\n- _Key components and what they do_\n- _Where state lives (databases, config files, etc.)_\n- _What talks to what_\n\n---\n\n## Key Source Files\n\n_Table of the important files and what they do. Not every file. The ones a new contributor needs to find their way._\n\n| File | What It Does |\n|------|-------------|\n| `src/core.ts` | _description_ |\n| `src/cli.ts` | _description_ |\n\n---\n\n## What's Built (as of vX.Y.Z)\n\n_Bullet list of what actually works right now. Update the version and date when this section changes._\n\n---\n\n## What's Missing\n\n_Bullet list of known gaps, limitations, and unfinished work. This is not the roadmap (that's in `plans-prds/roadmap.md`). This is the honest answer to \"what doesn't work yet?\"_\n\n---\n\n## Key Documents\n\n_Links to the important plans, PRDs, and references. Relative paths within `ai/product/`._\n\n| Document | Location |\n|----------|----------|\n| **This file** | `readme-first-product.md` |\n| **Roadmap** | `plans-prds/roadmap.md` |\n\n---\n\n## Principles\n\n_The non-negotiable rules for this product. The things that override convenience. 5-10 max._\n\n1. _Principle one._\n2. _Principle two._\n\n---\n\n## How to Update This File\n\n- **New major feature shipped?** Update \"What's Built\" and \"What's Missing.\"\n- **Architecture changed?** Update \"How It Works\" and \"Key Source Files.\"\n- **New mental model?** Update \"Core Concepts.\"\n- **New principle?** Add to \"Principles.\"\n- **Always update** the \"Last updated\" date at the top.\n- **Never delete sections.** If a section is empty, leave the heading. It reminds the team to fill it in.\n\nArchive v1.9.68: 14 files, 13803 bytes\n\nFiles: init.mjs (4779b), package.json (260b), README.md (1011b), SKILL.md (2435b), templates/_sort/README.md (573b), templates/_trash/README.md (702b), templates/dev-updates/README.md (1512b), templates/product/notes/README.md (662b), templates/product/plans-prds/roadmap.md (2276b), templates/product/plans-prds/todos/README.md (2103b), templates/product/product-ideas/README.md (763b), templates/product/readme-first-product.md (4157b), templates/read-me-first.md (4949b), _meta.json (133b)\n\nFile v1.9.68:SKILL.md\n\n---\nname: wip-repo-init\ndescription: Scaffold the standard ai/ directory structure in any repo.\nlicense: MIT\ninterface: [cli, skill]\nmetadata:\n display-name: \"Repo Init\"\n version: \"1.0.0\"\n homepage: \"https://github.com/wipcomputer/wip-ai-devops-toolbox\"\n author: \"Parker Todd Brooks\"\n category: repo-management\n capabilities:\n - scaffold-ai-dir\n - template-copy\n requires:\n bins: [node]\n openclaw:\n requires:\n bins: [node]\n install:\n - id: node\n kind: node\n package: \"@wipcomputer/wip-repo-init\"\n bins: [wip-repo-init]\n label: \"Install via npm\"\n emoji: \"📁\"\ncompatibility: Requires node. Node.js 18+.\n---\n\n# Repo Init\n\nScaffolds the standard `ai/` directory structure in any repo.\n\n## Commands\n\n```\nwip-repo-init /path/to/repo # scaffold ai/ in a repo\nwip-repo-init /path/to/repo --dry-run # preview without changes\nwip-repo-init /path/to/repo --yes # skip confirmation prompt\n```\n\n## What happens\n\n**New repo (no ai/ folder):** Creates the full standard structure with all READMEs explaining what goes where.\n\n**Existing repo (ai/ folder exists):** Shows you what will happen and asks for confirmation. If you say yes:\n1. Moves your current `ai/` contents to `ai/_sort/ai_old/`\n2. Scaffolds the new standard structure\n3. You sort files from `ai_old/` into the new structure at your own pace\n\nNothing is deleted. Your old files are all in `ai/_sort/ai_old/`.\n\n## The standard ai/ structure\n\n```\nai/\n read-me-first.md <- explains everything, links to all sections\n _sort/ <- holding pen for files that need sorting\n _trash/ <- archive (never delete, move here)\n dev-updates/ <- engineering changelog, auto-detected by wip-release\n product/\n readme-first-product.md <- the product bible\n notes/ <- freeform notes, research\n plans-prds/ <- plans with lifecycle stages\n roadmap.md <- prioritized roadmap\n current/ <- plans being built now\n upcoming/ <- plans that are next\n archive-complete/ <- plans that shipped\n todos/ <- per-agent todo files\n product-ideas/ <- ideas that aren't plans yet\n```\n\nEvery folder has a `_trash/` subfolder. Every section has a README explaining what it is, what goes in it, and how to maintain it.\n\n## Interfaces\n\nCLI, Skill\n\nFile v1.9.68:README.md\n\n###### WIP Computer\n\n# Repo Init\n\nScaffold the standard `ai/` directory in any repo. Plans, notes, ideas, dev updates, todos. One command.\n\n## What it does\n\n- **New repo:** Creates the full `ai/` directory structure\n- **Existing repo:** Moves old `ai/` contents to `ai/_sort/ai_old/` so you can sort at your own pace\n- Nothing is deleted\n\n## The `ai/` directory\n\n```\nai/\n plan/ architecture plans, roadmaps\n dev-updates/ what was built, session logs\n todos/\n PUNCHLIST.md blockers to ship\n inboxes/ per-agent action items\n notes/ research, references, raw conversation logs\n```\n\nThe `ai/` folder is the development process. It is not part of the published product. Public repos exclude it via deploy-public.sh.\n\n## Usage\n\n```bash\nnode tools/wip-repo-init/init.mjs /path/to/repo\n```\n\n## Interfaces\n\n- **CLI**: Run from terminal\n- **Skill**: SKILL.md for agent instructions\n\n## Part of [AI DevOps Toolbox](https://github.com/wipcomputer/wip-ai-devops-toolbox)\n\nFile v1.9.68:templates/_sort/README.md\n\n# _sort/\n\nThe holding pen. Files that need to be looked at and filed somewhere.\n\n## What Goes Here\n\n- iCloud duplicates or randomly placed files that need sorting\n- Files you're not sure where to put yet\n- Anything that needs a human to look at it and decide where it belongs\n\n## Rules\n\n- **Not trash.** `_sort/` is for files you want to review. `_trash/` is for files you're done with.\n- **Don't let it pile up.** Check this folder periodically. File things or trash them.\n- **Agents:** If you don't know where a file goes, put it in `_sort/`. A human will sort it later.\n\nFile v1.9.68:templates/_trash/README.md\n\n# _trash/\n\nThe archive. Files that are done, replaced, or consumed. Never delete anything. Move it here.\n\n## What Goes Here\n\n- Superseded plans (replaced by a newer version)\n- Consumed release notes (already used by `wip-release`)\n- Abandoned drafts\n- Anything you're done with but might need to reference later\n\n## Rules\n\n- **This is not garbage.** It's the archive. Everything in git history is recoverable, but `_trash/` keeps things findable without digging through commits.\n- **Subfolders have their own `_trash/`.** Use the nearest one. `dev-updates/_trash/` for old dev updates, `product/notes/_trash/` for old notes, etc.\n- **Never delete files from the repo.** Move them to `_trash/` instead.\n\nFile v1.9.68:templates/dev-updates/README.md\n\n# dev-updates/\n\nOne file per significant change. Written as you work, auto-detected by `wip-release`.\n\n## What This Folder Is\n\nDev updates are the engineering changelog. Every time you do significant work (ship a feature, fix a bug, change architecture), write a dev update. `wip-release` picks up today's dev updates and uses them as release notes.\n\nThis is not a place for plans or ideas. It's a record of what was built and why.\n\n## Naming Convention\n\n```\nYYYY-MM-DD--HH-MM--agent--description.md\n```\n\nExamples:\n- `2026-03-11--09-30--cc-mini--fix-hook-duplicates.md`\n- `2026-03-10--14-00--lesa-mini--add-voice-call-support.md`\n\n## File Format\n\n```markdown\n# Short title of what changed\n\n**Date:** YYYY-MM-DD HH:MM TZ\n**Author:** Agent Name (agent-id)\n\n## Problem\n\nWhat was broken or missing.\n\n## Fix / What Changed\n\nWhat you did and why.\n\n## Files changed\n\n- `path/to/file.js` ... what changed in it\n\nCloses #issue-number (if applicable)\n```\n\n## Rules\n\n- **Write them as you work.** Don't batch them at the end. Each significant change gets its own file.\n- **One file per change.** Not one file per day. If you fix two unrelated bugs, write two files.\n- **Include the \"why.\"** \"Fixed X\" is a commit message. A dev update explains why it was broken and why the fix works.\n- **Reference issues.** If there's a GitHub issue, add `Closes #N` at the bottom.\n- **Consumed files go to `_trash/`.** `wip-release` doesn't move them automatically, but the release notes files it generates do get trashed after release.\n\nFile v1.9.68:templates/product/notes/README.md\n\n# notes/\n\nFreeform notes, research, and observations. Anything that's useful context but isn't a plan, idea, or dev update.\n\n## What Goes Here\n\n- Research notes (\"I looked into X and found...\")\n- Meeting notes or conversation summaries\n- Technical investigations\n- Context that multiple plans reference\n- Anything that doesn't fit in `plans-prds/` or `product-ideas/`\n\n## Naming\n\nNo strict convention. Use descriptive names:\n\n```\nYYYY-MM-DD--agent--topic.md\n```\n\nExample: `2026-03-10--cc-mini--readme-standard-and-universal-installer-vision.md`\n\n## Rules\n\n- **Not a plan?** Put it here, not in `plans-prds/`.\n- **Done with it?** Move to `_trash/`. Don't delete.\n\nFile v1.9.68:templates/product/plans-prds/todos/README.md\n\n# todos/\n\nOne todo file per person or agent. Three sections per file: To Do, Done, Deprecated.\n\n## What This Folder Is\n\nTodos that are specific to this repo. Each person or agent who works on this repo gets one file. The file tracks what they need to do, what they've done, and what got dropped.\n\nFor cross-repo work or bigger items, use GitHub Issues. Todos here are for repo-scoped tasks that don't need the overhead of an issue.\n\n## Files\n\nOne file per person/agent. Name it `[Name]-todo.md`.\n\nExample:\n\n| File | Who |\n|------|-----|\n| `Parker-todo.md` | Parker (human tasks: reviews, credentials, approvals) |\n| `CC-Mini-todo.md` | Claude Code on Mac Mini (code, builds, deploys) |\n\nCreate the file when that person/agent first has work to do. No empty placeholder files.\n\n## File Format\n\n```markdown\n# [Name] Todos\n\n**Last updated:** YYYY-MM-DD\n\n## To Do\n\n- [ ] Task description\n- [ ] Task description (blocked by: reason)\n\n## Done\n\n- [x] Task description (YYYY-MM-DD)\n- [x] Task description (YYYY-MM-DD)\n\n## Deprecated\n\n- ~~Task description~~ ... reason. (YYYY-MM-DD)\n```\n\n## Rules\n\n- **Never delete anything.** Items move between sections, never off the page.\n- **To Do** ... work that needs to happen.\n- **Done** ... completed work. Check the box, add the date.\n- **Deprecated** ... planned but no longer needed. Strikethrough, add the reason and date. Not the same as Done. Done means it shipped. Deprecated means the requirement changed.\n- **Update the date** at the top of the file every time you edit it.\n- **One file per person/agent.** No dated files, no subfolders, no inboxes.\n- **Blocked items** stay in To Do with a `(blocked by: reason)` note. Don't move them to a separate section.\n\n## When to Use Todos vs GitHub Issues\n\n| Use | When |\n|-----|------|\n| **Todo file** | Quick tasks, repo-scoped work, things you'll do this session or this week |\n| **GitHub Issue** | Bugs, feature requests, cross-repo work, things that need tracking or discussion |\n\nBoth is fine. File an issue AND add a todo that references it. The todo is your personal checklist. The issue is the team's record.\n\nFile v1.9.68:templates/product/product-ideas/README.md\n\n# product-ideas/\n\nIdeas that aren't plans yet. The incubator.\n\n## What Goes Here\n\nAn idea is something you want to build but haven't committed to. It doesn't have tasks, timelines, or priorities. It's a \"what if\" or \"we should.\"\n\nWhen an idea is ready to become a plan, move it to `../plans-prds/upcoming/` and flesh it out with tasks and priorities.\n\n## Format\n\nNo strict format. But a good idea file usually has:\n\n- **What it is** (one paragraph)\n- **Why it matters** (what problem it solves)\n- **Open questions** (what you'd need to figure out)\n- **External references** (links, reviews, research)\n\n## Rules\n\n- **Not ready to plan?** It stays here.\n- **Ready to plan?** Move to `../plans-prds/upcoming/`.\n- **Killed?** Move to `_trash/` with a note about why.\n\nFile v1.9.68:_meta.json\n\n{\n \"ownerId\": \"kn7b4mj57xb02gqhvjzgzkxq557zz95h\",\n \"slug\": \"wip-repo-init\",\n \"version\": \"1.9.68\",\n \"publishedAt\": 1775050088263\n}\n\nFile v1.9.68:templates/product/plans-prds/roadmap.md\n\n# [Product Name] ... Roadmap\n\n**Last updated:** YYYY-MM-DD\n**Current version:** vX.Y.Z\n\nItems are either **Upcoming**, **Done**, or **Deprecated**. Never delete. Always move.\n\n---\n\n## What This File Is\n\nThe prioritized roadmap for this product. Three sections:\n\n- **Upcoming** ... work that's planned, ordered by priority. Top = most important.\n- **Done** ... shipped work. Moved here with a date when it's released.\n- **Deprecated** ... planned work that's no longer needed. Strikethrough, add the reason and date. Not the same as Done. Done means it shipped. Deprecated means the plan changed.\n\n**Keep it honest.** If something isn't going to happen, deprecate it. Don't leave dead items in Upcoming.\n\n**Keep it prioritized.** Upcoming items have priority numbers. When priorities shift, renumber them. The order is the strategy.\n\n---\n\n## Vision\n\n_One paragraph. Where is this product going? Not the feature list. The north star._\n\n---\n\n## Upcoming\n\n### Priority 1 ... [Feature/Epic Name]\n\n_What it is and why it matters in 1-2 sentences._\n\n- [ ] Task one\n- [ ] Task two\n- [ ] Task three\n\n### Priority 2 ... [Feature/Epic Name]\n\n_What it is and why it matters._\n\n- [ ] Task one\n- [ ] Task two\n\n_Add more priorities as needed. Number them. The number is the priority._\n\n---\n\n## Done\n\n### [Feature Name] (YYYY-MM-DD)\n\n- [x] What shipped\n- [x] What shipped\n\n_Move items here when they're released. Include the date. Keep the checkbox format so it's clear what was planned vs what actually shipped._\n\n---\n\n## Deprecated\n\n- ~~[Feature that was planned]~~ ... reason it was dropped. (YYYY-MM-DD)\n\n_Deprecated is not a graveyard. It's a record of decisions. When someone asks \"why didn't we build X?\" the answer is here._\n\n---\n\n## How to Update This File\n\n- **Shipped a feature?** Move it from Upcoming to Done. Add the date. Check the boxes.\n- **Dropped a plan?** Move it to Deprecated. Strikethrough, add the reason and date.\n- **New idea that's ready to plan?** Add to Upcoming with a priority number. Renumber if needed.\n- **Idea that's NOT ready to plan?** Put it in `../product-ideas/` instead. The roadmap is for committed work.\n- **Priorities shifted?** Renumber the Upcoming section. The order matters.\n- **Always update** \"Last updated\" and \"Current version\" at the top.\n\nFile v1.9.68:templates/product/readme-first-product.md\n\n# [Product Name] ... Read Me First\n\n**Last updated:** YYYY-MM-DD\n**Status:** Living document. Read this before any plan, build, or PR.\n\n---\n\n## What This File Is\n\nThis is the product bible for this repo. It answers: what is this thing, why does it exist, how does it work, and what's the current state. Every person and agent working on this repo reads this first.\n\n**Keep it current.** Update it when the architecture changes, when major features ship, when the mental model shifts. If this file is stale, the team is working from bad context.\n\n**Keep it honest.** Don't describe the aspirational version. Describe what's built and what's missing. Plans go in `plans-prds/`. This file is ground truth.\n\n---\n\n## This Folder\n\n```\nproduct/\n readme-first-product.md <- you're here (the product bible)\n _trash/\n notes/ <- freeform notes, research, observations\n plans-prds/ <- plans with lifecycle stages\n roadmap.md <- the prioritized roadmap\n current/ <- plans being built right now\n upcoming/ <- plans that are next\n archive-complete/ <- plans that shipped\n todos/ <- per-agent task lists\n _sort/ <- plans that need categorizing\n _trash/\n product-ideas/ <- ideas that aren't plans yet\n```\n\n**Navigate:**\n- **Want to know what's planned?** Read `plans-prds/roadmap.md`.\n- **Want to know what's being built right now?** Look in `plans-prds/current/`.\n- **Have an idea?** Write it up in `product-ideas/`.\n- **Ready to turn an idea into a plan?** Move it from `product-ideas/` to `plans-prds/upcoming/` (or `current/` if starting now).\n\n**Plan lifecycle:**\n```\nproduct-ideas/ -> upcoming/ -> current/ -> archive-complete/\n (idea) (planned) (building) (shipped)\n```\n\n---\n\n## What [Product Name] Is\n\n_One paragraph. What it does in human words. Not what it is technically. What problem it solves and for whom._\n\n---\n\n## Core Concepts\n\n_The 3-5 mental models someone needs to understand this product. Not implementation details. The \"aha\" moments that make everything else make sense._\n\n_Example: \"Raw files are ground truth. Databases are indexes. If anything breaks, rebuild from raw files.\"_\n\n_Example: \"One agent per harness per machine. That's the identity unit.\"_\n\n---\n\n## How It Works\n\n_The architecture at a level a new contributor can follow. Diagrams are fine. ASCII art is fine. The goal is: someone reads this section and can navigate the codebase without asking questions._\n\n_Include:_\n- _High-level data flow_\n- _Key components and what they do_\n- _Where state lives (databases, config files, etc.)_\n- _What talks to what_\n\n---\n\n## Key Source Files\n\n_Table of the important files and what they do. Not every file. The ones a new contributor needs to find their way._\n\n| File | What It Does |\n|------|-------------|\n| `src/core.ts` | _description_ |\n| `src/cli.ts` | _description_ |\n\n---\n\n## What's Built (as of vX.Y.Z)\n\n_Bullet list of what actually works right now. Update the version and date when this section changes._\n\n---\n\n## What's Missing\n\n_Bullet list of known gaps, limitations, and unfinished work. This is not the roadmap (that's in `plans-prds/roadmap.md`). This is the honest answer to \"what doesn't work yet?\"_\n\n---\n\n## Key Documents\n\n_Links to the important plans, PRDs, and references. Relative paths within `ai/product/`._\n\n| Document | Location |\n|----------|----------|\n| **This file** | `readme-first-product.md` |\n| **Roadmap** | `plans-prds/roadmap.md` |\n\n---\n\n## Principles\n\n_The non-negotiable rules for this product. The things that override convenience. 5-10 max._\n\n1. _Principle one._\n2. _Principle two._\n\n---\n\n## How to Update This File\n\n- **New major feature shipped?** Update \"What's Built\" and \"What's Missing.\"\n- **Architecture changed?** Update \"How It Works\" and \"Key Source Files.\"\n- **New mental model?** Update \"Core Concepts.\"\n- **New principle?** Add to \"Principles.\"\n- **Always update** the \"Last updated\" date at the top.\n- **Never delete sections.** If a section is empty, leave the heading. It reminds the team to fill it in.\n\nFile v1.9.68:templates/read-me-first.md\n\n# ai/ ... Read Me First\n\nThis is the working folder for the team. Plans, notes, ideas, dev updates, todos. Everything that isn't code lives here.\n\nThis folder only exists in `-private` repos. It never ships to public.\n\n## Structure\n\n```\nai/\n read-me-first.md <- you're here\n _sort/ <- stuff that hasn't been filed yet\n _trash/ <- stuff that's done or replaced (never delete, move here)\n dev-updates/ <- one file per significant change, auto-detected by wip-release\n _trash/\n product/\n readme-first-product.md <- the product bible (read this before anything else)\n _trash/\n notes/ <- freeform notes, research, observations\n _trash/\n plans-prds/ <- plans and PRDs with lifecycle stages\n roadmap.md <- prioritized roadmap (Upcoming / Done / Deprecated)\n _sort/ <- plans that haven't been categorized yet\n _trash/\n upcoming/ <- planned work (next up after current)\n current/ <- active plans being implemented right now\n archive-complete/ <- finished plans (moved here when done)\n todos/ <- per-agent todo files\n product-ideas/ <- ideas that aren't plans yet\n _trash/\n```\n\n## What's In Each Section\n\n| Location | What It Is | Read More |\n|----------|-----------|-----------|\n| [_sort/](_sort/README.md) | Holding pen. Files that need to be looked at and filed somewhere. iCloud duplicates, randomly placed files, things you're not sure about. | [_sort/README.md](_sort/README.md) |\n| [_trash/](_trash/README.md) | The archive. Files that are done, replaced, or consumed. Never delete anything, move it here. | [_trash/README.md](_trash/README.md) |\n| [dev-updates/](dev-updates/README.md) | Engineering changelog. One file per significant change. Auto-detected by `wip-release` for release notes. | [dev-updates/README.md](dev-updates/README.md) |\n| [product/readme-first-product.md](product/readme-first-product.md) | The product bible. What this product is, how it works, what's built, what's missing. Read before any plan, build, or PR. | [product/readme-first-product.md](product/readme-first-product.md) |\n| [product/notes/](product/notes/README.md) | Freeform notes, research, observations. Anything useful that isn't a plan or idea. | [product/notes/README.md](product/notes/README.md) |\n| [product/plans-prds/roadmap.md](product/plans-prds/roadmap.md) | Prioritized roadmap. Upcoming (ordered by priority), Done (with dates), Deprecated (with reasons). | [product/plans-prds/roadmap.md](product/plans-prds/roadmap.md) |\n| [product/plans-prds/todos/](product/plans-prds/todos/README.md) | Per-agent todo files. One file per person/agent. Three sections: To Do, Done, Deprecated. | [product/plans-prds/todos/README.md](product/plans-prds/todos/README.md) |\n| [product/product-ideas/](product/product-ideas/README.md) | Ideas that aren't plans yet. The incubator. Move to `plans-prds/upcoming/` when ready to commit. | [product/product-ideas/README.md](product/product-ideas/README.md) |\n\n## Rules\n\n**Never delete anything.** Move to `_trash/` in the nearest parent folder. Files in `_trash/` stay in git history and can always be recovered.\n\n**`_sort/` is the holding pen.** When something doesn't have an obvious home yet, or iCloud duplicated something, put it in `_sort/`. File it properly when you know where it goes.\n\n**`_trash/` is not garbage.** It's the archive. Completed plans go to `archive-complete/`. But notes, drafts, and superseded files go to `_trash/`. The difference: `archive-complete/` is work that shipped. `_trash/` is work that was replaced, abandoned, or consumed.\n\n## How to Use This\n\n**Starting a new feature?**\n1. Write a plan in [product/plans-prds/current/](product/plans-prds/current/)\n2. Write dev updates as you work in [dev-updates/](dev-updates/)\n3. When the plan ships, move it to [archive-complete/](product/plans-prds/archive-complete/)\n\n**Got an idea but not ready to plan?**\nPut it in [product/product-ideas/](product/product-ideas/)\n\n**Found something interesting but don't know where it goes?**\nPut it in [_sort/](_sort/) or [product/notes/](product/notes/)\n\n**Tracking work across agents?**\nUse [product/plans-prds/todos/](product/plans-prds/todos/) (one file per person/agent) or GitHub Issues\n\n## Dev Updates\n\nDev updates go in [dev-updates/](dev-updates/) with the naming convention:\n\n```\nYYYY-MM-DD--HH-MM--agent--description.md\n```\n\nExample: `2026-03-11--09-30--cc-mini--fix-hook-duplicates.md`\n\n`wip-release` auto-detects today's dev updates and uses them as release notes. Write them as you work. They're the changelog that writes itself.\n\nArchive v1.9.67: 14 files, 13803 bytes\n\nFiles: init.mjs (4779b), package.json (260b), README.md (1011b), SKILL.md (2435b), templates/_sort/README.md (573b), templates/_trash/README.md (702b), templates/dev-updates/README.md (1512b), templates/product/notes/README.md (662b), templates/product/plans-prds/roadmap.md (2276b), templates/product/plans-prds/todos/README.md (2103b), templates/product/product-ideas/README.md (763b), templates/product/readme-first-product.md (4157b), templates/read-me-first.md (4949b), _meta.json (133b)\n\nFile v1.9.67:SKILL.md\n\n---\nname: wip-repo-init\ndescription: Scaffold the standard ai/ directory structure in any repo.\nlicense: MIT\ninterface: [cli, skill]\nmetadata:\n display-name: \"Repo Init\"\n version: \"1.0.0\"\n homepage: \"https://github.com/wipcomputer/wip-ai-devops-toolbox\"\n author: \"Parker Todd Brooks\"\n category: repo-management\n capabilities:\n - scaffold-ai-dir\n - template-copy\n requires:\n bins: [node]\n openclaw:\n requires:\n bins: [node]\n install:\n - id: node\n kind: node\n package: \"@wipcomputer/wip-repo-init\"\n bins: [wip-repo-init]\n label: \"Install via npm\"\n emoji: \"📁\"\ncompatibility: Requires node. Node.js 18+.\n---\n\n# Repo Init\n\nScaffolds the standard `ai/` directory structure in any repo.\n\n## Commands\n\n```\nwip-repo-init /path/to/repo # scaffold ai/ in a repo\nwip-repo-init /path/to/repo --dry-run # preview without changes\nwip-repo-init /path/to/repo --yes # skip confirmation prompt\n```\n\n## What happens\n\n**New repo (no ai/ folder):** Creates the full standard structure with all READMEs explaining what goes where.\n\n**Existing repo (ai/ folder exists):** Shows you what will happen and asks for confirmation. If you say yes:\n1. Moves your current `ai/` contents to `ai/_sort/ai_old/`\n2. Scaffolds the new standard structure\n3. You sort files from `ai_old/` into the new structure at your own pace\n\nNothing is deleted. Your old files are all in `ai/_sort/ai_old/`.\n\n## The standard ai/ structure\n\n```\nai/\n read-me-first.md <- explains everything, links to all sections\n _sort/ <- holding pen for files that need sorting\n _trash/ <- archive (never delete, move here)\n dev-updates/ <- engineering changelog, auto-detected by wip-release\n product/\n readme-first-product.md <- the product bible\n notes/ <- freeform notes, research\n plans-prds/ <- plans with lifecycle stages\n roadmap.md <- prioritized roadmap\n current/ <- plans being built now\n upcoming/ <- plans that are next\n archive-complete/ <- plans that shipped\n todos/ <- per-agent todo files\n product-ideas/ <- ideas that aren't plans yet\n```\n\nEvery folder has a `_trash/` subfolder. Every section has a README explaining what it is, what goes in it, and how to maintain it.\n\n## Interfaces\n\nCLI, Skill\n\nFile v1.9.67:README.md\n\n###### WIP Computer\n\n# Repo Init\n\nScaffold the standard `ai/` directory in any repo. Plans, notes, ideas, dev updates, todos. One command.\n\n## What it does\n\n- **New repo:** Creates the full `ai/` directory structure\n- **Existing repo:** Moves old `ai/` contents to `ai/_sort/ai_old/` so you can sort at your own pace\n- Nothing is deleted\n\n## The `ai/` directory\n\n```\nai/\n plan/ architecture plans, roadmaps\n dev-updates/ what was built, session logs\n todos/\n PUNCHLIST.md blockers to ship\n inboxes/ per-agent action items\n notes/ research, references, raw conversation logs\n```\n\nThe `ai/` folder is the development process. It is not part of the published product. Public repos exclude it via deploy-public.sh.\n\n## Usage\n\n```bash\nnode tools/wip-repo-init/init.mjs /path/to/repo\n```\n\n## Interfaces\n\n- **CLI**: Run from terminal\n- **Skill**: SKILL.md for agent instructions\n\n## Part of [AI DevOps Toolbox](https://github.com/wipcomputer/wip-ai-devops-toolbox)\n\nFile v1.9.67:templates/_sort/README.md\n\n# _sort/\n\nThe holding pen. Files that need to be looked at and filed somewhere.\n\n## What Goes Here\n\n- iCloud duplicates or randomly placed files that need sorting\n- Files you're not sure where to put yet\n- Anything that needs a human to look at it and decide where it belongs\n\n## Rules\n\n- **Not trash.** `_sort/` is for files you want to review. `_trash/` is for files you're done with.\n- **Don't let it pile up.** Check this folder periodically. File things or trash them.\n- **Agents:** If you don't know where a file goes, put it in `_sort/`. A human will sort it later.\n\nFile v1.9.67:templates/_trash/README.md\n\n# _trash/\n\nThe archive. Files that are done, replaced, or consumed. Never delete anything. Move it here.\n\n## What Goes Here\n\n- Superseded plans (replaced by a newer version)\n- Consumed release notes (already used by `wip-release`)\n- Abandoned drafts\n- Anything you're done with but might need to reference later\n\n## Rules\n\n- **This is not garbage.** It's the archive. Everything in git history is recoverable, but `_trash/` keeps things findable without digging through commits.\n- **Subfolders have their own `_trash/`.** Use the nearest one. `dev-updates/_trash/` for old dev updates, `product/notes/_trash/` for old notes, etc.\n- **Never delete files from the repo.** Move them to `_trash/` instead.\n\nFile v1.9.67:templates/dev-updates/README.md\n\n# dev-updates/\n\nOne file per significant change. Written as you work, auto-detected by `wip-release`.\n\n## What This Folder Is\n\nDev updates are the engineering changelog. Every time you do significant work (ship a feature, fix a bug, change architecture), write a dev update. `wip-release` picks up today's dev updates and uses them as release notes.\n\nThis is not a place for plans or ideas. It's a record of what was built and why.\n\n## Naming Convention\n\n```\nYYYY-MM-DD--HH-MM--agent--description.md\n```\n\nExamples:\n- `2026-03-11--09-30--cc-mini--fix-hook-duplicates.md`\n- `2026-03-10--14-00--lesa-mini--add-voice-call-support.md`\n\n## File Format\n\n```markdown\n# Short title of what changed\n\n**Date:** YYYY-MM-DD HH:MM TZ\n**Author:** Agent Name (agent-id)\n\n## Problem\n\nWhat was broken or missing.\n\n## Fix / What Changed\n\nWhat you did and why.\n\n## Files changed\n\n- `path/to/file.js` ... what changed in it\n\nCloses #issue-number (if applicable)\n```\n\n## Rules\n\n- **Write them as you work.** Don't batch them at the end. Each significant change gets its own file.\n- **One file per change.** Not one file per day. If you fix two unrelated bugs, write two files.\n- **Include the \"why.\"** \"Fixed X\" is a commit message. A dev update explains why it was broken and why the fix works.\n- **Reference issues.** If there's a GitHub issue, add `Closes #N` at the bottom.\n- **Consumed files go to `_trash/`.** `wip-release` doesn't move them automatically, but the release notes files it generates do get trashed after release.\n\nFile v1.9.67:templates/product/notes/README.md\n\n# notes/\n\nFreeform notes, research, and observations. Anything that's useful context but isn't a plan, idea, or dev update.\n\n## What Goes Here\n\n- Research notes (\"I looked into X and found...\")\n- Meeting notes or conversation summaries\n- Technical investigations\n- Context that multiple plans reference\n- Anything that doesn't fit in `plans-prds/` or `product-ideas/`\n\n## Naming\n\nNo strict convention. Use descriptive names:\n\n```\nYYYY-MM-DD--agent--topic.md\n```\n\nExample: `2026-03-10--cc-mini--readme-standard-and-universal-installer-vision.md`\n\n## Rules\n\n- **Not a plan?** Put it here, not in `plans-prds/`.\n- **Done with it?** Move to `_trash/`. Don't delete.\n\nFile v1.9.67:templates/product/plans-prds/todos/README.md\n\n# todos/\n\nOne todo file per person or agent. Three sections per file: To Do, Done, Deprecated.\n\n## What This Folder Is\n\nTodos that are specific to this repo. Each person or agent who works on this repo gets one file. The file tracks what they need to do, what they've done, and what got dropped.\n\nFor cross-repo work or bigger items, use GitHub Issues. Todos here are for repo-scoped tasks that don't need the overhead of an issue.\n\n## Files\n\nOne file per person/agent. Name it `[Name]-todo.md`.\n\nExample:\n\n| File | Who |\n|------|-----|\n| `Parker-todo.md` | Parker (human tasks: reviews, credentials, approvals) |\n| `CC-Mini-todo.md` | Claude Code on Mac Mini (code, builds, deploys) |\n\nCreate the file when that person/agent first has work to do. No empty placeholder files.\n\n## File Format\n\n```markdown\n# [Name] Todos\n\n**Last updated:** YYYY-MM-DD\n\n## To Do\n\n- [ ] Task description\n- [ ] Task description (blocked by: reason)\n\n## Done\n\n- [x] Task description (YYYY-MM-DD)\n- [x] Task description (YYYY-MM-DD)\n\n## Deprecated\n\n- ~~Task description~~ ... reason. (YYYY-MM-DD)\n```\n\n## Rules\n\n- **Never delete anything.** Items move between sections, never off the page.\n- **To Do** ... work that needs to happen.\n- **Done** ... completed work. Check the box, add the date.\n- **Deprecated** ... planned but no longer needed. Strikethrough, add the reason and date. Not the same as Done. Done means it shipped. Deprecated means the requirement changed.\n- **Update the date** at the top of the file every time you edit it.\n- **One file per person/agent.** No dated files, no subfolders, no inboxes.\n- **Blocked items** stay in To Do with a `(blocked by: reason)` note. Don't move them to a separate section.\n\n## When to Use Todos vs GitHub Issues\n\n| Use | When |\n|-----|------|\n| **Todo file** | Quick tasks, repo-scoped work, things you'll do this session or this week |\n| **GitHub Issue** | Bugs, feature requests, cross-repo work, things that need tracking or discussion |\n\nBoth is fine. File an issue AND add a todo that references it. The todo is your personal checklist. The issue is the team's record.\n\nFile v1.9.67:templates/product/product-ideas/README.md\n\n# product-ideas/\n\nIdeas that aren't plans yet. The incubator.\n\n## What Goes Here\n\nAn idea is something you want to build but haven't committed to. It doesn't have tasks, timelines, or priorities. It's a \"what if\" or \"we should.\"\n\nWhen an idea is ready to become a plan, move it to `../plans-prds/upcoming/` and flesh it out with tasks and priorities.\n\n## Format\n\nNo strict format. But a good idea file usually has:\n\n- **What it is** (one paragraph)\n- **Why it matters** (what problem it solves)\n- **Open questions** (what you'd need to figure out)\n- **External references** (links, reviews, research)\n\n## Rules\n\n- **Not ready to plan?** It stays here.\n- **Ready to plan?** Move to `../plans-prds/upcoming/`.\n- **Killed?** Move to `_trash/` with a note about why.\n\nFile v1.9.67:_meta.json\n\n{\n \"ownerId\": \"kn7b4mj57xb02gqhvjzgzkxq557zz95h\",\n \"slug\": \"wip-repo-init\",\n \"version\": \"1.9.67\",\n \"publishedAt\": 1774942098391\n}\n\nFile v1.9.67:templates/product/plans-prds/roadmap.md\n\n# [Product Name] ... Roadmap\n\n**Last updated:** YYYY-MM-DD\n**Current version:** vX.Y.Z\n\nItems are either **Upcoming**, **Done**, or **Deprecated**. Never delete. Always move.\n\n---\n\n## What This File Is\n\nThe prioritized roadmap for this product. Three sections:\n\n- **Upcoming** ... work that's planned, ordered by priority. Top = most important.\n- **Done** ... shipped work. Moved here with a date when it's released.\n- **Deprecated** ... planned work that's no longer needed. Strikethrough, add the reason and date. Not the same as Done. Done means it shipped. Deprecated means the plan changed.\n\n**Keep it honest.** If something isn't going to happen, deprecate it. Don't leave dead items in Upcoming.\n\n**Keep it prioritized.** Upcoming items have priority numbers. When priorities shift, renumber them. The order is the strategy.\n\n---\n\n## Vision\n\n_One paragraph. Where is this product going? Not the feature list. The north star._\n\n---\n\n## Upcoming\n\n### Priority 1 ... [Feature/Epic Name]\n\n_What it is and why it matters in 1-2 sentences._\n\n- [ ] Task one\n- [ ] Task two\n- [ ] Task three\n\n### Priority 2 ... [Feature/Epic Name]\n\n_What it is and why it matters._\n\n- [ ] Task one\n- [ ] Task two\n\n_Add more priorities as needed. Number them. The number is the priority._\n\n---\n\n## Done\n\n### [Feature Name] (YYYY-MM-DD)\n\n- [x] What shipped\n- [x] What shipped\n\n_Move items here when they're released. Include the date. Keep the checkbox format so it's clear what was planned vs what actually shipped._\n\n---\n\n## Deprecated\n\n- ~~[Feature that was planned]~~ ... reason it was dropped. (YYYY-MM-DD)\n\n_Deprecated is not a graveyard. It's a record of decisions. When someone asks \"why didn't we build X?\" the answer is here._\n\n---\n\n## How to Update This File\n\n- **Shipped a feature?** Move it from Upcoming to Done. Add the date. Check the boxes.\n- **Dropped a plan?** Move it to Deprecated. Strikethrough, add the reason and date.\n- **New idea that's ready to plan?** Add to Upcoming with a priority number. Renumber if needed.\n- **Idea that's NOT ready to plan?** Put it in `../product-ideas/` instead. The roadmap is for committed work.\n- **Priorities shifted?** Renumber the Upcoming section. The order matters.\n- **Always update** \"Last updated\" and \"Current version\" at the top.\n\nFile v1.9.67:templates/product/readme-first-product.md\n\n# [Product Name] ... Read Me First\n\n**Last updated:** YYYY-MM-DD\n**Status:** Living document. Read this before any plan, build, or PR.\n\n---\n\n## What This File Is\n\nThis is the product bible for this repo. It answers: what is this thing, why does it exist, how does it work, and what's the current state. Every person and agent working on this repo reads this first.\n\n**Keep it current.** Update it when the architecture changes, when major features ship, when the mental model shifts. If this file is stale, the team is working from bad context.\n\n**Keep it honest.** Don't describe the aspirational version. Describe what's built and what's missing. Plans go in `plans-prds/`. This file is ground truth.\n\n---\n\n## This Folder\n\n```\nproduct/\n readme-first-product.md <- you're here (the product bible)\n _trash/\n notes/ <- freeform notes, research, observations\n plans-prds/ <- plans with lifecycle stages\n roadmap.md <- the prioritized roadmap\n current/ <- plans being built right now\n upcoming/ <- plans that are next\n archive-complete/ <- plans that shipped\n todos/ <- per-agent task lists\n _sort/ <- plans that need categorizing\n _trash/\n product-ideas/ <- ideas that aren't plans yet\n```\n\n**Navigate:**\n- **Want to know what's planned?** Read `plans-prds/roadmap.md`.\n- **Want to know what's being built right now?** Look in `plans-prds/current/`.\n- **Have an idea?** Write it up in `product-ideas/`.\n- **Ready to turn an idea into a plan?** Move it from `product-ideas/` to `plans-prds/upcoming/` (or `current/` if starting now).\n\n**Plan lifecycle:**\n```\nproduct-ideas/ -> upcoming/ -> current/ -> archive-complete/\n (idea) (planned) (building) (shipped)\n```\n\n---\n\n## What [Product Name] Is\n\n_One paragraph. What it does in human words. Not what it is technically. What problem it solves and for whom._\n\n---\n\n## Core Concepts\n\n_The 3-5 mental models someone needs to understand this product. Not implementation details. The \"aha\" moments that make everything else make sense._\n\n_Example: \"Raw files are ground truth. Databases are indexes. If anything breaks, rebuild from raw files.\"_\n\n_Example: \"One agent per harness per machine. That's the identity unit.\"_\n\n---\n\n## How It Works\n\n_The architecture at a level a new contributor can follow. Diagrams are fine. ASCII art is fine. The goal is: someone reads this section and can navigate the codebase without asking questions._\n\n_Include:_\n- _High-level data flow_\n- _Key components and what they do_\n- _Where state lives (databases, config files, etc.)_\n- _What talks to what_\n\n---\n\n## Key Source Files\n\n_Table of the important files and what they do. Not every file. The ones a new contributor needs to find their way._\n\n| File | What It Does |\n|------|-------------|\n| `src/core.ts` | _description_ |\n| `src/cli.ts` | _description_ |\n\n---\n\n## What's Built (as of vX.Y.Z)\n\n_Bullet list of what actually works right now. Update the version and date when this section changes._\n\n---\n\n## What's Missing\n\n_Bullet list of known gaps, limitations, and unfinished work. This is not the roadmap (that's in `plans-prds/roadmap.md`). This is the honest answer to \"what doesn't work yet?\"_\n\n---\n\n## Key Documents\n\n_Links to the important plans, PRDs, and references. Relative paths within `ai/product/`._\n\n| Document | Location |\n|----------|----------|\n| **This file** | `readme-first-product.md` |\n| **Roadmap** | `plans-prds/roadmap.md` |\n\n---\n\n## Principles\n\n_The non-negotiable rules for this product. The things that override convenience. 5-10 max._\n\n1. _Principle one._\n2. _Principle two._\n\n---\n\n## How to Update This File\n\n- **New major feature shipped?** Update \"What's Built\" and \"What's Missing.\"\n- **Architecture changed?** Update \"How It Works\" and \"Key Source Files.\"\n- **New mental model?** Update \"Core Concepts.\"\n- **New principle?** Add to \"Principles.\"\n- **Always update** the \"Last updated\" date at the top.\n- **Never delete sections.** If a section is empty, leave the heading. It reminds the team to fill it in.\n\nFile v1.9.67:templates/read-me-first.md\n\n# ai/ ... Read Me First\n\nThis is the working folder for the team. Plans, notes, ideas, dev updates, todos. Everything that isn't code lives here.\n\nThis folder only exists in `-private` repos. It never ships to public.\n\n## Structure\n\n```\nai/\n read-me-first.md <- you're here\n _sort/ <- stuff that hasn't been filed yet\n _trash/ <- stuff that's done or replaced (never delete, move here)\n dev-updates/ <- one file per significant change, auto-detected by wip-release\n _trash/\n product/\n readme-first-product.md <- the product bible (read this before anything else)\n _trash/\n notes/ <- freeform notes, research, observations\n _trash/\n plans-prds/ <- plans and PRDs with lifecycle stages\n roadmap.md <- prioritized roadmap (Upcoming / Done / Deprecated)\n _sort/ <- plans that haven't been categorized yet\n _trash/\n upcoming/ <- planned work (next up after current)\n current/ <- active plans being implemented right now\n archive-complete/ <- finished plans (moved here when done)\n todos/ <- per-agent todo files\n product-ideas/ <- ideas that aren't plans yet\n _trash/\n```\n\n## What's In Each Section\n\n| Location | What It Is | Read More |\n|----------|-----------|-----------|\n| [_sort/](_sort/README.md) | Holding pen. Files that need to be looked at and filed somewhere. iCloud duplicates, randomly placed files, things you're not sure about. | [_sort/README.md](_sort/README.md) |\n| [_trash/](_trash/README.md) | The archive. Files that are done, replaced, or consumed. Never delete anything, move it here. | [_trash/README.md](_trash/README.md) |\n| [dev-updates/](dev-updates/README.md) | Engineering changelog. One file per significant change. Auto-detected by `wip-release` for release notes. | [dev-updates/README.md](dev-updates/README.md) |\n| [product/readme-first-product.md](product/readme-first-product.md) | The product bible. What this product is, how it works, what's built, what's missing. Read before any plan, build, or PR. | [product/readme-first-product.md](product/readme-first-product.md) |\n| [product/notes/](product/notes/README.md) | Freeform notes, research, observations. Anything useful that isn't a plan or idea. | [product/notes/README.md](product/notes/README.md) |\n| [product/plans-prds/roadmap.md](product/plans-prds/roadmap.md) | Prioritized roadmap. Upcoming (ordered by priority), Done (with dates), Deprecated (with reasons). | [product/plans-prds/roadmap.md](product/plans-prds/roadmap.md) |\n| [product/plans-prds/todos/](product/plans-prds/todos/README.md) | Per-agent todo files. One file per person/agent. Three sections: To Do, Done, Deprecated. | [product/plans-prds/todos/README.md](product/plans-prds/todos/README.md) |\n| [product/product-ideas/](product/product-ideas/README.md) | Ideas that aren't plans yet. The incubator. Move to `plans-prds/upcoming/` when ready to commit. | [product/product-ideas/README.md](product/product-ideas/README.md) |\n\n## Rules\n\n**Never delete anything.** Move to `_trash/` in the nearest parent folder. Files in `_trash/` stay in git history and can always be recovered.\n\n**`_sort/` is the holding pen.** When something doesn't have an obvious home yet, or iCloud duplicated something, put it in `_sort/`. File it properly when you know where it goes.\n\n**`_trash/` is not garbage.** It's the archive. Completed plans go to `archive-complete/`. But notes, drafts, and superseded files go to `_trash/`. The difference: `archive-complete/` is work that shipped. `_trash/` is work that was replaced, abandoned, or consumed.\n\n## How to Use This\n\n**Starting a new feature?**\n1. Write a plan in [product/plans-prds/current/](product/plans-prds/current/)\n2. Write dev updates as you work in [dev-updates/](dev-updates/)\n3. When the plan ships, move it to [archive-complete/](product/plans-prds/archive-complete/)\n\n**Got an idea but not ready to plan?**\nPut it in [product/product-ideas/](product/product-ideas/)\n\n**Found something interesting but don't know where it goes?**\nPut it in [_sort/](_sort/) or [product/notes/](product/notes/)\n\n**Tracking work across agents?**\nUse [product/plans-prds/todos/](product/plans-prds/todos/) (one file per person/agent) or GitHub Issues\n\n## Dev Updates\n\nDev updates go in [dev-updates/](dev-updates/) with the naming convention:\n\n```\nYYYY-MM-DD--HH-MM--agent--description.md\n```\n\nExample: `2026-03-11--09-30--cc-mini--fix-hook-duplicates.md`\n\n`wip-release` auto-detects today's dev updates and uses them as release notes. Write them as you work. They're the changelog that writes itself.\n\nArchive v1.9.66: 14 files, 13803 bytes\n\nFiles: init.mjs (4779b), package.json (260b), README.md (1011b), SKILL.md (2435b), templates/_sort/README.md (573b), templates/_trash/README.md (702b), templates/dev-updates/README.md (1512b), templates/product/notes/README.md (662b), templates/product/plans-prds/roadmap.md (2276b), templates/product/plans-prds/todos/README.md (2103b), templates/product/product-ideas/README.md (763b), templates/product/readme-first-product.md (4157b), templates/read-me-first.md (4949b), _meta.json (133b)\n\nFile v1.9.66:SKILL.md\n\n---\nname: wip-repo-init\ndescription: Scaffold the standard ai/ directory structure in any repo.\nlicense: MIT\ninterface: [cli, skill]\nmetadata:\n display-name: \"Repo Init\"\n version: \"1.0.0\"\n homepage: \"https://github.com/wipcomputer/wip-ai-devops-toolbox\"\n author: \"Parker Todd Brooks\"\n category: repo-management\n capabilities:\n - scaffold-ai-dir\n - template-copy\n requires:\n bins: [node]\n openclaw:\n requires:\n bins: [node]\n install:\n - id: node\n kind: node\n package: \"@wipcomputer/wip-repo-init\"\n bins: [wip-repo-init]\n label: \"Install via npm\"\n emoji: \"📁\"\ncompatibility: Requires node. Node.js 18+.\n---\n\n# Repo Init\n\nScaffolds the standard `ai/` directory structure in any repo.\n\n## Commands\n\n```\nwip-repo-init /path/to/repo # scaffold ai/ in a repo\nwip-repo-init /path/to/repo --dry-run # preview without changes\nwip-repo-init /path/to/repo --yes # skip confirmation prompt\n```\n\n## What happens\n\n**New repo (no ai/ folder):** Creates the full standard structure with all READMEs explaining what goes where.\n\n**Existing repo (ai/ folder exists):** Shows you what will happen and asks for confirmation. If you say yes:\n1. Moves your current `ai/` contents to `ai/_sort/ai_old/`\n2. Scaffolds the new standard structure\n3. You sort files from `ai_old/` into the new structure at your own pace\n\nNothing is deleted. Your old files are all in `ai/_sort/ai_old/`.\n\n## The standard ai/ structure\n\n```\nai/\n read-me-first.md <- explains everything, links to all sections\n _sort/ <- holding pen for files that need sorting\n _trash/ <- archive (never delete, move here)\n dev-updates/ <- engineering changelog, auto-detected by wip-release\n product/\n readme-first-product.md <- the product bible\n notes/ <- freeform notes, research\n plans-prds/ <- plans with lifecycle stages\n roadmap.md <- prioritized roadmap\n current/ <- plans being built now\n upcoming/ <- plans that are next\n archive-complete/ <- plans that shipped\n todos/ <- per-agent todo files\n product-ideas/ <- ideas that aren't plans yet\n```\n\nEvery folder has a `_trash/` subfolder. Every section has a README explaining what it is, what goes in it, and how to maintain it.\n\n## Interfaces\n\nCLI, Skill\n\nFile v1.9.66:README.md\n\n###### WIP Computer\n\n# Repo Init\n\nScaffold the standard `ai/` directory in any repo. Plans, notes, ideas, dev updates, todos. One command.\n\n## What it does\n\n- **New repo:** Creates the full `ai/` directory structure\n- **Existing repo:** Moves old `ai/` contents to `ai/_sort/ai_old/` so you can sort at your own pace\n- Nothing is deleted\n\n## The `ai/` directory\n\n```\nai/\n plan/ architecture plans, roadmaps\n dev-updates/ what was built, session logs\n todos/\n PUNCHLIST.md blockers to ship\n inboxes/ per-agent action items\n notes/ research, references, raw conversation logs\n```\n\nThe `ai/` folder is the development process. It is not part of the published product. Public repos exclude it via deploy-public.sh.\n\n## Usage\n\n```bash\nnode tools/wip-repo-init/init.mjs /path/to/repo\n```\n\n## Interfaces\n\n- **CLI**: Run from terminal\n- **Skill**: SKILL.md for agent instructions\n\n## Part of [AI DevOps Toolbox](https://github.com/wipcomputer/wip-ai-devops-toolbox)\n\nFile v1.9.66:templates/_sort/README.md\n\n# _sort/\n\nThe holding pen. Files that need to be looked at and filed somewhere.\n\n## What Goes Here\n\n- iCloud duplicates or randomly placed files that need sorting\n- Files you're not sure where to put yet\n- Anything that needs a human to look at it and decide where it belongs\n\n## Rules\n\n- **Not trash.** `_sort/` is for files you want to review. `_trash/` is for files you're done with.\n- **Don't let it pile up.** Check this folder periodically. File things or trash them.\n- **Agents:** If you don't know where a file goes, put it in `_sort/`. A human will sort it later.\n\nFile v1.9.66:templates/_trash/README.md\n\n# _trash/\n\nThe archive. Files that are done, replaced, or consumed. Never delete anything. Move it here.\n\n## What Goes Here\n\n- Superseded plans (replaced by a newer version)\n- Consumed release notes (already used by `wip-release`)\n- Abandoned drafts\n- Anything you're done with but might need to reference later\n\n## Rules\n\n- **This is not garbage.** It's the archive. Everything in git history is recoverable, but `_trash/` keeps things findable without digging through commits.\n- **Subfolders have their own `_trash/`.** Use the nearest one. `dev-updates/_trash/` for old dev updates, `product/notes/_trash/` for old notes, etc.\n- **Never delete files from the repo.** Move them to `_trash/` instead.\n\nFile v1.9.66:templates/dev-updates/README.md\n\n# dev-updates/\n\nOne file per significant change. Written as you work, auto-detected by `wip-release`.\n\n## What This Folder Is\n\nDev updates are the engineering changelog. Every time you do significant work (ship a feature, fix a bug, change architecture), write a dev update. `wip-release` picks up today's dev updates and uses them as release notes.\n\nThis is not a place for plans or ideas. It's a record of what was built and why.\n\n## Naming Convention\n\n```\nYYYY-MM-DD--HH-MM--agent--description.md\n```\n\nExamples:\n- `2026-03-11--09-30--cc-mini--fix-hook-duplicates.md`\n- `2026-03-10--14-00--lesa-mini--add-voice-call-support.md`\n\n## File Format\n\n```markdown\n# Short title of what changed\n\n**Date:** YYYY-MM-DD HH:MM TZ\n**Author:** Agent Name (agent-id)\n\n## Problem\n\nWhat was broken or missing.\n\n## Fix / What Changed\n\nWhat you did and why.\n\n## Files changed\n\n- `path/to/file.js` ... what changed in it\n\nCloses #issue-number (if applicable)\n```\n\n## Rules\n\n- **Write them as you work.** Don't batch them at the end. Each significant change gets its own file.\n- **One file per change.** Not one file per day. If you fix two unrelated bugs, write two files.\n- **Include the \"why.\"** \"Fixed X\" is a commit message. A dev update explains why it was broken and why the fix works.\n- **Reference issues.** If there's a GitHub issue, add `Closes #N` at the bottom.\n- **Consumed files go to `_trash/`.** `wip-release` doesn't move them automatically, but the release notes files it generates do get trashed after release.\n\nFile v1.9.66:templates/product/notes/README.md\n\n# notes/\n\nFreeform notes, research, and observations. Anything that's useful context but isn't a plan, idea, or dev update.\n\n## What Goes Here\n\n- Research notes (\"I looked into X and found...\")\n- Meeting notes or conversation summaries\n- Technical investigations\n- Context that multiple plans reference\n- Anything that doesn't fit in `plans-prds/` or `product-ideas/`\n\n## Naming\n\nNo strict convention. Use descriptive names:\n\n```\nYYYY-MM-DD--agent--topic.md\n```\n\nExample: `2026-03-10--cc-mini--readme-standard-and-universal-installer-vision.md`\n\n## Rules\n\n- **Not a plan?** Put it here, not in `plans-prds/`.\n- **Done with it?** Move to `_trash/`. Don't delete.\n\nFile v1.9.66:templates/product/plans-prds/todos/README.md\n\n# todos/\n\nOne todo file per person or agent. Three sections per file: To Do, Done, Deprecated.\n\n## What This Folder Is\n\nTodos that are specific to this repo. Each person or agent who works on this repo gets one file. The file tracks what they need to do, what they've done, and what got dropped.\n\nFor cross-repo work or bigger items, use GitHub Issues. Todos here are for repo-scoped tasks that don't need the overhead of an issue.\n\n## Files\n\nOne file per person/agent. Name it `[Name]-todo.md`.\n\nExample:\n\n| File | Who |\n|------|-----|\n| `Parker-todo.md` | Parker (human tasks: reviews, credentials, approvals) |\n| `CC-Mini-todo.md` | Claude Code on Mac Mini (code, builds, deploys) |\n\nCreate the file when that person/agent first has work to do. No empty placeholder files.\n\n## File Format\n\n```markdown\n# [Name] Todos\n\n**Last updated:** YYYY-MM-DD\n\n## To Do\n\n- [ ] Task description\n- [ ] Task description (blocked by: reason)\n\n## Done\n\n- [x] Task description (YYYY-MM-DD)\n- [x] Task description (YYYY-MM-DD)\n\n## Deprecated\n\n- ~~Task description~~ ... reason. (YYYY-MM-DD)\n```\n\n## Rules\n\n- **Never delete anything.** Items move between sections, never off the page.\n- **To Do** ... work that needs to happen.\n- **Done** ... completed work. Check the box, add the date.\n- **Deprecated** ... planned but no longer needed. Strikethrough, add the reason and date. Not the same as Done. Done means it shipped. Deprecated means the requirement changed.\n- **Update the date** at the top of the file every time you edit it.\n- **One file per person/agent.** No dated files, no subfolders, no inboxes.\n- **Blocked items** stay in To Do with a `(blocked by: reason)` note. Don't move them to a separate section.\n\n## When to Use Todos vs GitHub Issues\n\n| Use | When |\n|-----|------|\n| **Todo file** | Quick tasks, repo-scoped work, things you'll do this session or this week |\n| **GitHub Issue** | Bugs, feature requests, cross-repo work, things that need tracking or discussion |\n\nBoth is fine. File an issue AND add a todo that references it. The todo is your personal checklist. The issue is the team's record.\n\nFile v1.9.66:templates/product/product-ideas/README.md\n\n# product-ideas/\n\nIdeas that aren't plans yet. The incubator.\n\n## What Goes Here\n\nAn idea is something you want to build but haven't committed to. It doesn't have tasks, timelines, or priorities. It's a \"what if\" or \"we should.\"\n\nWhen an idea is ready to become a plan, move it to `../plans-prds/upcoming/` and flesh it out with tasks and priorities.\n\n## Format\n\nNo strict format. But a good idea file usually has:\n\n- **What it is** (one paragraph)\n- **Why it matters** (what problem it solves)\n- **Open questions** (what you'd need to figure out)\n- **External references** (links, reviews, research)\n\n## Rules\n\n- **Not ready to plan?** It stays here.\n- **Ready to plan?** Move to `../plans-prds/upcoming/`.\n- **Killed?** Move to `_trash/` with a note about why.\n\nFile v1.9.66:_meta.json\n\n{\n \"ownerId\": \"kn7b4mj57xb02gqhvjzgzkxq557zz95h\",\n \"slug\": \"wip-repo-init\",\n \"version\": \"1.9.66\",\n \"publishedAt\": 1774877355236\n}\n\nFile v1.9.66:templates/product/plans-prds/roadmap.md\n\n# [Product Name] ... Roadmap\n\n**Last updated:** YYYY-MM-DD\n**Current version:** vX.Y.Z\n\nItems are either **Upcoming**, **Done**, or **Deprecated**. Never delete. Always move.\n\n---\n\n## What This File Is\n\nThe prioritized roadmap for this product. Three sections:\n\n- **Upcoming** ... work that's planned, ordered by priority. Top = most important.\n- **Done** ... shipped work. Moved here with a date when it's released.\n- **Deprecated** ... planned work that's no longer needed. Strikethrough, add the reason and date. Not the same as Done. Done means it shipped. Deprecated means the plan changed.\n\n**Keep it honest.** If something isn't going to happen, deprecate it. Don't leave dead items in Upcoming.\n\n**Keep it prioritized.** Upcoming items have priority numbers. When priorities shift, renumber them. The order is the strategy.\n\n---\n\n## Vision\n\n_One paragraph. Where is this product going? Not the feature list. The north star._\n\n---\n\n## Upcoming\n\n### Priority 1 ... [Feature/Epic Name]\n\n_What it is and why it matters in 1-2 sentences._\n\n- [ ] Task one\n- [ ] Task two\n- [ ] Task three\n\n### Priority 2 ... [Feature/Epic Name]\n\n_What it is and why it matters._\n\n- [ ] Task one\n- [ ] Task two\n\n_Add more priorities as needed. Number them. The number is the priority._\n\n---\n\n## Done\n\n### [Feature Name] (YYYY-MM-DD)\n\n- [x] What shipped\n- [x] What shipped\n\n_Move items here when they're released. Include the date. Keep the checkbox format so it's clear what was planned vs what actually shipped._\n\n---\n\n## Deprecated\n\n- ~~[Feature that was planned]~~ ... reason it was dropped. (YYYY-MM-DD)\n\n_Deprecated is not a graveyard. It's a record of decisions. When someone asks \"why didn't we build X?\" the answer is here._\n\n---\n\n## How to Update This File\n\n- **Shipped a feature?** Move it from Upcoming to Done. Add the date. Check the boxes.\n- **Dropped a plan?** Move it to Deprecated. Strikethrough, add the reason and date.\n- **New idea that's ready to plan?** Add to Upcoming with a priority number. Renumber if needed.\n- **Idea that's NOT ready to plan?** Put it in `../product-ideas/` instead. The roadmap is for committed work.\n- **Priorities shifted?** Renumber the Upcoming section. The order matters.\n- **Always update** \"Last updated\" and \"Current version\" at the top.\n\nFile v1.9.66:templates/product/readme-first-product.md\n\n# [Product Name] ... Read Me First\n\n**Last updated:** YYYY-MM-DD\n**Status:** Living document. Read this before any plan, build, or PR.\n\n---\n\n## What This File Is\n\nThis is the product bible for this repo. It answers: what is this thing, why does it exist, how does it work, and what's the current state. Every person and agent working on this repo reads this first.\n\n**Keep it current.** Update it when the architecture changes, when major features ship, when the mental model shifts. If this file is stale, the team is working from bad context.\n\n**Keep it honest.** Don't describe the aspirational version. Describe what's built and what's missing. Plans go in `plans-prds/`. This file is ground truth.\n\n---\n\n## This Folder\n\n```\nproduct/\n readme-first-product.md <- you're here (the product bible)\n _trash/\n notes/ <- freeform notes, research, observations\n plans-prds/ <- plans with lifecycle stages\n roadmap.md <- the prioritized roadmap\n current/ <- plans being built right now\n upcoming/ <- plans that are next\n archive-complete/ <- plans that shipped\n todos/ <- per-agent task lists\n _sort/ <- plans that need categorizing\n _trash/\n product-ideas/ <- ideas that aren't plans yet\n```\n\n**Navigate:**\n- **Want to know what's planned?** Read `plans-prds/roadmap.md`.\n- **Want to know what's being built right now?** Look in `plans-prds/current/`.\n- **Have an idea?** Write it up in `product-ideas/`.\n- **Ready to turn an idea into a plan?** Move it from `product-ideas/` to `plans-prds/upcoming/` (or `current/` if starting now).\n\n**Plan lifecycle:**\n```\nproduct-ideas/ -> upcoming/ -> current/ -> archive-complete/\n (idea) (planned) (building) (shipped)\n```\n\n---\n\n## What [Product Name] Is\n\n_One paragraph. What it does in human words. Not what it is technically. What problem it solves and for whom._\n\n---\n\n## Core Concepts\n\n_The 3-5 mental models someone needs to understand this product. Not implementation details. The \"aha\" moments that make everything else make sense._\n\n_Example: \"Raw files are ground truth. Databases are indexes. If anything breaks, rebuild from raw files.\"_\n\n_Example: \"One agent per harness per machine. That's the identity unit.\"_\n\n---\n\n## How It Works\n\n_The architecture at a level a new contributor can follow. Diagrams are fine. ASCII art is fine. The goal is: someone reads this section and can navigate the codebase without asking questions._\n\n_Include:_\n- _High-level data flow_\n- _Key components and what they do_\n- _Where state lives (databases, config files, etc.)_\n- _What talks to what_\n\n---\n\n## Key Source Files\n\n_Table of the important files and what they do. Not every file. The ones a new contributor needs to find their way._\n\n| File | What It Does |\n|------|-------------|\n| `src/core.ts` | _description_ |\n| `src/cli.ts` | _description_ |\n\n---\n\n## What's Built (as of vX.Y.Z)\n\n_Bullet list of what actually works right now. Update the version and date when this section changes._\n\n---\n\n## What's Missing\n\n_Bullet list of known gaps, limitations, and unfinished work. This is not the roadmap (that's in `plans-prds/roadmap.md`). This is the honest answer to \"what doesn't work yet?\"_\n\n---\n\n## Key Documents\n\n_Links to the important plans, PRDs, and references. Relative paths within `ai/product/`._\n\n| Document | Location |\n|----------|----------|\n| **This file** | `readme-first-product.md` |\n| **Roadmap** | `plans-prds/roadmap.md` |\n\n---\n\n## Principles\n\n_The non-negotiable rules for this product. The things that override convenience. 5-10 max._\n\n1. _Principle one._\n2. _Principle two._\n\n---\n\n## How to Update This File\n\n- **New major feature shipped?** Update \"What's Built\" and \"What's Missing.\"\n- **Architecture changed?** Update \"How It Works\" and \"Key Source Files.\"\n- **New mental model?** Update \"Core Concepts.\"\n- **New principle?** Add to \"Principles.\"\n- **Always update** the \"Last updated\" date at the top.\n- **Never delete sections.** If a section is empty, leave the heading. It reminds the team to fill it in.\n\nFile v1.9.66:templates/read-me-first.md\n\n# ai/ ... Read Me First\n\nThis is the working folder for the team. Plans, notes, ideas, dev updates, todos. Everything that isn't code lives here.\n\nThis folder only exists in `-private` repos. It never ships to public.\n\n## Structure\n\n```\nai/\n read-me-first.md <- you're here\n _sort/ <- stuff that hasn't been filed yet\n _trash/ <- stuff that's done or replaced (never delete, move here)\n dev-updates/ <- one file per significant change, auto-detected by wip-release\n _trash/\n product/\n readme-first-product.md <- the product bible (read this before anything else)\n _trash/\n notes/ <- freeform notes, research, observations\n _trash/\n plans-prds/ <- plans and PRDs with lifecycle stages\n roadmap.md <- prioritized roadmap (Upcoming / Done / Deprecated)\n _sort/ <- plans that haven't been categorized yet\n _trash/\n upcoming/ <- planned work (next up after current)\n current/ <- active plans being implemented right now\n archive-complete/ <- finished plans (moved here when done)\n todos/ <- per-agent todo files\n product-ideas/ <- ideas that aren't plans yet\n _trash/\n```\n\n## What's In Each Section\n\n| Location | What It Is | Read More |\n|----------|-----------|-----------|\n| [_sort/](_sort/README.md) | Holding pen. Files that need to be looked at and filed somewhere. iCloud duplicates, randomly placed files, things you're not sure about. | [_sort/README.md](_sort/README.md) |\n| [_trash/](_trash/README.md) | The archive. Files that are done, replaced, or consumed. Never delete anything, move it here. | [_trash/README.md](_trash/README.md) |\n| [dev-updates/](dev-updates/README.md) | Engineering changelog. One file per significant change. Auto-detected by `wip-release` for release notes. | [dev-updates/README.md](dev-updates/README.md) |\n| [product/readme-first-product.md](product/readme-first-product.md) | The product bible. What this product is, how it works, what's built, what's missing. Read before any plan, build, or PR. | [product/readme-first-product.md](product/readme-first-product.md) |\n| [product/notes/](product/notes/README.md) | Freeform notes, research, observations. Anything useful that isn't a plan or idea. | [product/notes/README.md](product/notes/README.md) |\n| [product/plans-prds/roadmap.md](product/plans-prds/roadmap.md) | Prioritized roadmap. Upcoming (ordered by priority), Done (with dates), Deprecated (with reasons). | [product/plans-prds/roadmap.md](product/plans-prds/roadmap.md) |\n| [product/plans-prds/todos/](product/plans-prds/todos/README.md) | Per-agent todo files. One file per person/agent. Three sections: To Do, Done, Deprecated. | [product/plans-prds/todos/README.md](product/plans-prds/todos/README.md) |\n| [product/product-ideas/](product/product-ideas/README.md) | Ideas that aren't plans yet. The incubator. Move to `plans-prds/upcoming/` when ready to commit. | [product/product-ideas/README.md](product/product-ideas/README.md) |\n\n## Rules\n\n**Never delete anything.** Move to `_trash/` in the nearest parent folder. Files in `_trash/` stay in git history and can always be recovered.\n\n**`_sort/` is the holding pen.** When something doesn't have an obvious home yet, or iCloud duplicated something, put it in `_sort/`. File it properly when you know where it goes.\n\n**`_trash/` is not garbage.** It's the archive. Completed plans go to `archive-complete/`. But notes, drafts, and superseded files go to `_trash/`. The difference: `archive-complete/` is work that shipped. `_trash/` is work that was replaced, abandoned, or consumed.\n\n## How to Use This\n\n**Starting a new feature?**\n1. Write a plan in [product/plans-prds/current/](product/plans-prds/current/)\n2. Write dev updates as you work in [dev-updates/](dev-updates/)\n3. When the plan ships, move it to [archive-complete/](product/plans-prds/archive-complete/)\n\n**Got an idea but not ready to plan?**\nPut it in [product/product-ideas/](product/product-ideas/)\n\n**Found something interesting but don't know where it goes?**\nPut it in [_sort/](_sort/) or [product/notes/](product/notes/)\n\n**Tracking work across agents?**\nUse [product/plans-prds/todos/](product/plans-prds/todos/) (one file per person/agent) or GitHub Issues\n\n## Dev Updates\n\nDev updates go in [dev-updates/](dev-updates/) with the naming convention:\n\n```\nYYYY-MM-DD--HH-MM--agent--description.md\n```\n\nExample: `2026-03-11--09-30--cc-mini--fix-hook-duplicates.md`\n\n`wip-release` auto-detects today's dev updates and uses them as release notes. Write them as you work. They're the changelog that writes itself.\n\nArchive v1.9.65: 14 files, 13803 bytes\n\nFiles: init.mjs (4779b), package.json (260b), README.md (1011b), SKILL.md (2435b), templates/_sort/README.md (573b), templates/_trash/README.md (702b), templates/dev-updates/README.md (1512b), templates/product/notes/README.md (662b), templates/product/plans-prds/roadmap.md (2276b), templates/product/plans-prds/todos/README.md (2103b), templates/product/product-ideas/README.md (763b), templates/product/readme-first-product.md (4157b), templates/read-me-first.md (4949b), _meta.json (133b)\n\nFile v1.9.65:SKILL.md\n\n---\nname: wip-repo-init\ndescription: Scaffold the standard ai/ directory structure in any repo.\nlicense: MIT\ninterface: [cli, skill]\nmetadata:\n display-name: \"Repo Init\"\n version: \"1.0.0\"\n homepage: \"https://github.com/wipcomputer/wip-ai-devops-toolbox\"\n author: \"Parker Todd Brooks\"\n category: repo-management\n capabilities:\n - scaffold-ai-dir\n - template-copy\n requires:\n bins: [node]\n openclaw:\n requires:\n bins: [node]\n install:\n - id: node\n kind: node\n package: \"@wipcomputer/wip-repo-init\"\n bins: [wip-repo-init]\n label: \"Install via npm\"\n emoji: \"📁\"\ncompatibility: Requires node. Node.js 18+.\n---\n\n# Repo Init\n\nScaffolds the standard `ai/` directory structure in any repo.\n\n## Commands\n\n```\nwip-repo-init /path/to/repo # scaffold ai/ in a repo\nwip-repo-init /path/to/repo --dry-run # preview without changes\nwip-repo-init /path/to/repo --yes # skip confirmation prompt\n```\n\n## What happens\n\n**New repo (no ai/ folder):** Creates the full standard structure with all READMEs explaining what goes where.\n\n**Existing repo (ai/ folder exists):** Shows you what will happen and asks for confirmation. If you say yes:\n1. Moves your current `ai/` contents to `ai/_sort/ai_old/`\n2. Scaffolds the new standard structure\n3. You sort files from `ai_old/` into the new structure at your own pace\n\nNothing is deleted. Your old files are all in `ai/_sort/ai_old/`.\n\n## The standard ai/ structure\n\n```\nai/\n read-me-first.md <- explains everything, links to all sections\n _sort/ <- holding pen for files that need sorting\n _trash/ <- archive (never delete, move here)\n dev-updates/ <- engineering changelog, auto-detected by wip-release\n product/\n readme-first-product.md <- the product bible\n notes/ <- freeform notes, research\n plans-prds/ <- plans with lifecycle stages\n roadmap.md <- prioritized roadmap\n current/ <- plans being built now\n upcoming/ <- plans that are next\n archive-complete/ <- plans that shipped\n todos/ <- per-agent todo files\n product-ideas/ <- ideas that aren't plans yet\n```\n\nEvery folder has a `_trash/` subfolder. Every section has a README explaining what it is, what goes in it, and how to maintain it.\n\n## Interfaces\n\nCLI, Skill\n\nFile v1.9.65:README.md\n\n###### WIP Computer\n\n# Repo Init\n\nScaffold the standard `ai/` directory in any repo. Plans, notes, ideas, dev updates, todos. One command.\n\n## What it does\n\n- **New repo:** Creates the full `ai/` directory structure\n- **Existing repo:** Moves old `ai/` contents to `ai/_sort/ai_old/` so you can sort at your own pace\n- Nothing is deleted\n\n## The `ai/` directory\n\n```\nai/\n plan/ architecture plans, roadmaps\n dev-updates/ what was built, session logs\n todos/\n PUNCHLIST.md blockers to ship\n inboxes/ per-agent action items\n notes/ research, references, raw conversation logs\n```\n\nThe `ai/` folder is the development process. It is not part of the published product. Public repos exclude it via deploy-public.sh.\n\n## Usage\n\n```bash\nnode tools/wip-repo-init/init.mjs /path/to/repo\n```\n\n## Interfaces\n\n- **CLI**: Run from terminal\n- **Skill**: SKILL.md for agent instructions\n\n## Part of [AI DevOps Toolbox](https://github.com/wipcomputer/wip-ai-devops-toolbox)\n\nFile v1.9.65:templates/_sort/README.md\n\n# _sort/\n\nThe holding pen. Files that need to be looked at and filed somewhere.\n\n## What Goes Here\n\n- iCloud duplicates or randomly placed files that need sorting\n- Files you're not sure where to put yet\n- Anything that needs a human to look at it and decide where it belongs\n\n## Rules\n\n- **Not trash.** `_sort/` is for files you want to review. `_trash/` is for files you're done with.\n- **Don't let it pile up.** Check this folder periodically. File things or trash them.\n- **Agents:** If you don't know where a file goes, put it in `_sort/`. A human will sort it later.\n\nFile v1.9.65:templates/_trash/README.md\n\n# _trash/\n\nThe archive. Files that are done, replaced, or consumed. Never delete anything. Move it here.\n\n## What Goes Here\n\n- Superseded plans (replaced by a newer version)\n- Consumed release notes (already used by `wip-release`)\n- Abandoned drafts\n- Anything you're done with but might need to reference later\n\n## Rules\n\n- **This is not garbage.** It's the archive. Everything in git history is recoverable, but `_trash/` keeps things findable without digging through commits.\n- **Subfolders have their own `_trash/`.** Use the nearest one. `dev-updates/_trash/` for old dev updates, `product/notes/_trash/` for old notes, etc.\n- **Never delete files from the repo.** Move them to `_trash/` instead.\n\nFile v1.9.65:templates/dev-updates/README.md\n\n# dev-updates/\n\nOne file per significant change. Written as you work, auto-detected by `wip-release`.\n\n## What This Folder Is\n\nDev updates are the engineering changelog. Every time you do significant work (ship a feature, fix a bug, change architecture), write a dev update. `wip-release` picks up today's dev updates and uses them as release notes.\n\nThis is not a place for plans or ideas. It's a record of what was built and why.\n\n## Naming Convention\n\n```\nYYYY-MM-DD--HH-MM--agent--description.md\n```\n\nExamples:\n- `2026-03-11--09-30--cc-mini--fix-hook-duplicates.md`\n- `2026-03-10--14-00--lesa-mini--add-voice-call-support.md`\n\n## File Format\n\n```markdown\n# Short title of what changed\n\n**Date:** YYYY-MM-DD HH:MM TZ\n**Author:** Agent Name (agent-id)\n\n## Problem\n\nWhat was broken or missing.\n\n## Fix / What Changed\n\nWhat you did and why.\n\n## Files changed\n\n- `path/to/file.js` ... what changed in it\n\nCloses #issue-number (if applicable)\n```\n\n## Rules\n\n- **Write them as you work.** Don't batch them at the end. Each significant change gets its own file.\n- **One file per change.** Not one file per day. If you fix two unrelated bugs, write two files.\n- **Include the \"why.\"** \"Fixed X\" is a commit message. A dev update explains why it was broken and why the fix works.\n- **Reference issues.** If there's a GitHub issue, add `Closes #N` at the bottom.\n- **Consumed files go to `_trash/`.** `wip-release` doesn't move them automatically, but the release notes files it generates do get trashed after release.\n\nFile v1.9.65:templates/product/notes/README.md\n\n# notes/\n\nFreeform notes, research, and observations. Anything that's useful context but isn't a plan, idea, or dev update.\n\n## What Goes Here\n\n- Research notes (\"I looked into X and found...\")\n- Meeting notes or conversation summaries\n- Technical investigations\n- Context that multiple plans reference\n- Anything that doesn't fit in `plans-prds/` or `product-ideas/`\n\n## Naming\n\nNo strict convention. Use descriptive names:\n\n```\nYYYY-MM-DD--agent--topic.md\n```\n\nExample: `2026-03-10--cc-mini--readme-standard-and-universal-installer-vision.md`\n\n## Rules\n\n- **Not a plan?** Put it here, not in `plans-prds/`.\n- **Done with it?** Move to `_trash/`. Don't delete.\n\nFile v1.9.65:templates/product/plans-prds/todos/README.md\n\n# todos/\n\nOne todo file per person or agent. Three sections per file: To Do, Done, Deprecated.\n\n## What This Folder Is\n\nTodos that are specific to this repo. Each person or agent who works on this repo gets one file. The file tracks what they need to do, what they've done, and what got dropped.\n\nFor cross-repo work or bigger items, use GitHub Issues. Todos here are for repo-scoped tasks that don't need the overhead of an issue.\n\n## Files\n\nOne file per person/agent. Name it `[Name]-todo.md`.\n\nExample:\n\n| File | Who |\n|------|-----|\n| `Parker-todo.md` | Parker (human tasks: reviews, credentials, approvals) |\n| `CC-Mini-todo.md` | Claude Code on Mac Mini (code, builds, deploys) |\n\nCreate the file when that person/agent first has work to do. No empty placeholder files.\n\n## File Format\n\n```markdown\n# [Name] Todos\n\n**Last updated:** YYYY-MM-DD\n\n## To Do\n\n- [ ] Task description\n- [ ] Task description (blocked by: reason)\n\n## Done\n\n- [x] Task description (YYYY-MM-DD)\n- [x] Task description (YYYY-MM-DD)\n\n## Deprecated\n\n- ~~Task description~~ ... reason. (YYYY-MM-DD)\n```\n\n## Rules\n\n- **Never delete anything.** Items move between sections, never off the page.\n- **To Do** ... work that needs to happen.\n- **Done** ... completed work. Check the box, add the date.\n- **Deprecated** ... planned but no longer needed. Strikethrough, add the reason and date. Not the same as Done. Done means it shipped. Deprecated means the requirement changed.\n- **Update the date** at the top of the file every time you edit it.\n- **One file per person/agent.** No dated files, no subfolders, no inboxes.\n- **Blocked items** stay in To Do with a `(blocked by: reason)` note. Don't move them to a separate section.\n\n## When to Use Todos vs GitHub Issues\n\n| Use | When |\n|-----|------|\n| **Todo file** | Quick tasks, repo-scoped work, things you'll do this session or this week |\n| **GitHub Issue** | Bugs, feature requests, cross-repo work, things that need tracking or discussion |\n\nBoth is fine. File an issue AND add a todo that references it. The todo is your personal checklist. The issue is the team's record.\n\nFile v1.9.65:templates/product/product-ideas/README.md\n\n# product-ideas/\n\nIdeas that aren't plans yet. The incubator.\n\n## What Goes Here\n\nAn idea is something you want to build but haven't committed to. It doesn't have tasks, timelines, or priorities. It's a \"what if\" or \"we should.\"\n\nWhen an idea is ready to become a plan, move it to `../plans-prds/upcoming/` and flesh it out with tasks and priorities.\n\n## Format\n\nNo strict format. But a good idea file usually has:\n\n- **What it is** (one paragraph)\n- **Why it matters** (what problem it solves)\n- **Open questions** (what you'd need to figure out)\n- **External references** (links, reviews, research)\n\n## Rules\n\n- **Not ready to plan?** It stays here.\n- **Ready to plan?** Move to `../plans-prds/upcoming/`.\n- **Killed?** Move to `_trash/` with a note about why.\n\nFile v1.9.65:_meta.json\n\n{\n \"ownerId\": \"kn7b4mj57xb02gqhvjzgzkxq557zz95h\",\n \"slug\": \"wip-repo-init\",\n \"version\": \"1.9.65\",\n \"publishedAt\": 1774828673319\n}\n\nFile v1.9.65:templates/product/plans-prds/roadmap.md\n\n# [Product Name] ... Roadmap\n\n**Last updated:** YYYY-MM-DD\n**Current version:** vX.Y.Z\n\nItems are either **Upcoming**, **Done**, or **Deprecated**. Never delete. Always move.\n\n---\n\n## What This File Is\n\nThe prioritized roadmap for this product. Three sections:\n\n- **Upcoming** ... work that's planned, ordered by priority. Top = most important.\n- **Done** ... shipped work. Moved here with a date when it's released.\n- **Deprecated** ... planned work that's no longer needed. Strikethrough, add the reason and date. Not the same as Done. Done means it shipped. Deprecated means the plan changed.\n\n**Keep it honest.** If something isn't going to happen, deprecate it. Don't leave dead items in Upcoming.\n\n**Keep it prioritized.** Upcoming items have priority numbers. When priorities shift, renumber them. The order is the strategy.\n\n---\n\n## Vision\n\n_One paragraph. Where is this product going? Not the feature list. The north star._\n\n---\n\n## Upcoming\n\n### Priority 1 ... [Feature/Epic Name]\n\n_What it is and why it matters in 1-2 sentences._\n\n- [ ] Task one\n- [ ] Task two\n- [ ] Task three\n\n### Priority 2 ... [Feature/Epic Name]\n\n_What it is and why it matters._\n\n- [ ] Task one\n- [ ] Task two\n\n_Add more priorities as needed. Number them. The number is the priority._\n\n---\n\n## Done\n\n### [Feature Name] (YYYY-MM-DD)\n\n- [x] What shipped\n- [x] What shipped\n\n_Move items here when they're released. Include the date. Keep the checkbox format so it's clear what was planned vs what actually shipped._\n\n---\n\n## Deprecated\n\n- ~~[Feature that was planned]~~ ... reason it was dropped. (YYYY-MM-DD)\n\n_Deprecated is not a graveyard. It's a record of decisions. When someone asks \"why didn't we build X?\" the answer is here._\n\n---\n\n## How to Update This File\n\n- **Shipped a feature?** Move it from Upcoming to Done. Add the date. Check the boxes.\n- **Dropped a plan?** Move it to Deprecated. Strikethrough, add the reason and date.\n- **New idea that's ready to plan?** Add to Upcoming with a priority number. Renumber if needed.\n- **Idea that's NOT ready to plan?** Put it in `../product-ideas/` instead. The roadmap is for committed work.\n- **Priorities shifted?** Renumber the Upcoming section. The order matters.\n- **Always update** \"Last updated\" and \"Current version\" at the top.\n\nFile v1.9.65:templates/product/readme-first-product.md\n\n# [Product Name] ... Read Me First\n\n**Last updated:** YYYY-MM-DD\n**Status:** Living document. Read this before any plan, build, or PR.\n\n---\n\n## What This File Is\n\nThis is the product bible for this repo. It answers: what is this thing, why does it exist, how does it work, and what's the current state. Every person and agent working on this repo reads this first.\n\n**Keep it current.** Update it when the architecture changes, when major features ship, when the mental model shifts. If this file is stale, the team is working from bad context.\n\n**Keep it honest.** Don't describe the aspirational version. Describe what's built and what's missing. Plans go in `plans-prds/`. This file is ground truth.\n\n---\n\n## This Folder\n\n```\nproduct/\n readme-first-product.md <- you're here (the product bible)\n _trash/\n notes/ <- freeform notes, research, observations\n plans-prds/ <- plans with lifecycle stages\n roadmap.md <- the prioritized roadmap\n current/ <- plans being built right now\n upcoming/ <- plans that are next\n archive-complete/ <- plans that shipped\n todos/ <- per-agent task lists\n _sort/ <- plans that need categorizing\n _trash/\n product-ideas/ <- ideas that aren't plans yet\n```\n\n**Navigate:**\n- **Want to know what's planned?** Read `plans-prds/roadmap.md`.\n- **Want to know what's being built right now?** Look in `plans-prds/current/`.\n- **Have an idea?** Write it up in `product-ideas/`.\n- **Ready to turn an idea into a plan?** Move it from `product-ideas/` to `plans-prds/upcoming/` (or `current/` if starting now).\n\n**Plan lifecycle:**\n```\nproduct-ideas/ -> upcoming/ -> current/ -> archive-complete/\n (idea) (planned) (building) (shipped)\n```\n\n---\n\n## What [Product Name] Is\n\n_One paragraph. What it does in human words. Not what it is technically. What problem it solves and for whom._\n\n---\n\n## Core Concepts\n\n_The 3-5 mental models someone needs to understand this product. Not implementation details. The \"aha\" moments that make everything else make sense._\n\n_Example: \"Raw files are ground truth. Databases are indexes. If anything breaks, rebuild from raw files.\"_\n\n_Example: \"One agent per harness per machine. That's the identity unit.\"_\n\n---\n\n## How It Works\n\n_The architecture at a level a new contributor can follow. Diagrams are fine. ASCII art is fine. The goal is: someone reads this section and can navigate the codebase without asking questions._\n\n_Include:_\n- _High-level data flow_\n- _Key components and what they do_\n- _Where state lives (databases, config files, etc.)_\n- _What talks to what_\n\n---\n\n## Key Source Files\n\n_Table of the important files and what they do. Not every file. The ones a new contributor needs to find their way._\n\n| File | What It Does |\n|------|-------------|\n| `src/core.ts` | _description_ |\n| `src/cli.ts` | _description_ |\n\n---\n\n## What's Built (as of vX.Y.Z)\n\n_Bullet list of what actually works right now. Update the version and date when this section changes._\n\n---\n\n## What's Missing\n\n_Bullet list of known gaps, limitations, and unfinished work. This is not the roadmap (that's in `plans-prds/roadmap.md`). This is the honest answer to \"what doesn't work yet?\"_\n\n---\n\n## Key Documents\n\n_Links to the important plans, PRDs, and references. Relative paths within `ai/product/`._\n\n| Document | Location |\n|----------|----------|\n| **This file** | `readme-first-product.md` |\n| **Roadmap** | `plans-prds/roadmap.md` |\n\n---\n\n## Principles\n\n_The non-negotiable rules for this product. The things that override convenience. 5-10 max._\n\n1. _Principle one._\n2. _Principle two._\n\n---\n\n## How to Update This File\n\n- **New major feature shipped?** Update \"What's Built\" and \"What's Missing.\"\n- **Architecture changed?** Update \"How It Works\" and \"Key Source Files.\"\n- **New mental model?** Update \"Core Concepts.\"\n- **New principle?** Add to \"Principles.\"\n- **Always update** the \"Last updated\" date at the top.\n- **Never delete sections.** If a section is empty, leave the heading. It reminds the team to fill it in.\n\nFile v1.9.65:templates/read-me-first.md\n\n# ai/ ... Read Me First\n\nThis is the working folder for the team. Plans, notes, ideas, dev updates, todos. Everything that isn't code lives here.\n\nThis folder only exists in `-private` repos. It never ships to public.\n\n## Structure\n\n```\nai/\n read-me-first.md <- you're here\n _sort/ <- stuff that hasn't been filed yet\n _trash/ <- stuff that's done or replaced (never delete, move here)\n dev-updates/ <- one file per significant change, auto-detected by wip-release\n _trash/\n product/\n readme-first-product.md <- the product bible (read this before anything else)\n _trash/\n notes/ <- freeform notes, research, observations\n _trash/\n plans-prds/ <- plans and PRDs with lifecycle stages\n roadmap.md <- prioritized roadmap (Upcoming / Done / Deprecated)\n _sort/ <- plans that haven't been categorized yet\n _trash/\n upcoming/ <- planned work (next up after current)\n current/ <- active plans being implemented right now\n archive-complete/ <- finished plans (moved here when done)\n todos/ <- per-agent todo files\n product-ideas/ <- ideas that aren't plans yet\n _trash/\n```\n\n## What's In Each Section\n\n| Location | What It Is | Read More |\n|----------|-----------|-----------|\n| [_sort/](_sort/README.md) | Holding pen. Files that need to be looked at and filed somewhere. iCloud duplicates, randomly placed files, things you're not sure about. | [_sort/README.md](_sort/README.md) |\n| [_trash/](_trash/README.md) | The archive. Files that are done, replaced, or consumed. Never delete anything, move it here. | [_trash/README.md](_trash/README.md) |\n| [dev-updates/](dev-updates/README.md) | Engineering changelog. One file per significant change. Auto-detected by `wip-release` for release notes. | [dev-updates/README.md](dev-updates/README.md) |\n| [product/readme-first-product.md](product/readme-first-product.md) | The product bible. What this product is, how it works, what's built, what's missing. Read before any plan, build, or PR. | [product/readme-first-product.md](product/readme-first-product.md) |\n| [product/notes/](product/notes/README.md) | Freeform notes, research, observations. Anything useful that isn't a plan or idea. | [product/notes/README.md](product/notes/README.md) |\n| [product/plans-prds/roadmap.md](product/plans-prds/roadmap.md) | Prioritized roadmap. Upcoming (ordered by priority), Done (with dates), Deprecated (with reasons). | [product/plans-prds/roadmap.md](product/plans-prds/roadmap.md) |\n| [product/plans-prds/todos/](product/plans-prds/todos/README.md) | Per-agent todo files. One file per person/agent. Three sections: To Do, Done, Deprecated. | [product/plans-prds/todos/README.md](product/plans-prds/todos/README.md) |\n| [product/product-ideas/](product/product-ideas/README.md) | Ideas that aren't plans yet. The incubator. Move to `plans-prds/upcoming/` when ready to commit. | [product/product-ideas/README.md](product/product-ideas/README.md) |\n\n## Rules\n\n**Never delete anything.** Move to `_trash/` in the nearest parent folder. Files in `_trash/` stay in git history and can always be recovered.\n\n**`_sort/` is the holding pen.** When something doesn't have an obvious home yet, or iCloud duplicated something, put it in `_sort/`. File it properly when you know where it goes.\n\n**`_trash/` is not garbage.** It's the archive. Completed plans go to `archive-complete/`. But notes, drafts, and superseded files go to `_trash/`. The difference: `archive-complete/` is work that shipped. `_trash/` is work that was replaced, abandoned, or consumed.\n\n## How to Use This\n\n**Starting a new feature?**\n1. Write a plan in [product/plans-prds/current/](product/plans-prds/current/)\n2. Write dev updates as you work in [dev-updates/](dev-updates/)\n3. When the plan ships, move it to [archive-complete/](product/plans-prds/archive-complete/)\n\n**Got an idea but not ready to plan?**\nPut it in [product/product-ideas/](product/product-ideas/)\n\n**Found something interesting but don't know where it goes?**\nPut it in [_sort/](_sort/) or [product/notes/](product/notes/)\n\n**Tracking work across agents?**\nUse [product/plans-prds/todos/](product/plans-prds/todos/) (one file per person/agent) or GitHub Issues\n\n## Dev Updates\n\nDev updates go in [dev-updates/](dev-updates/) with the naming convention:\n\n```\nYYYY-MM-DD--HH-MM--agent--description.md\n```\n\nExample: `2026-03-11--09-30--cc-mini--fix-hook-duplicates.md`\n\n`wip-release` auto-detects today's dev updates and uses them as release notes. Write them as you work. They're the changelog that writes itself.\n\nArchive v1.9.64: 14 files, 13803 bytes\n\nFiles: init.mjs (4779b), package.json (260b), README.md (1011b), SKILL.md (2435b), templates/_sort/README.md (573b), templates/_trash/README.md (702b), templates/dev-updates/README.md (1512b), templates/product/notes/README.md (662b), templates/product/plans-prds/roadmap.md (2276b), templates/product/plans-prds/todos/README.md (2103b), templates/product/product-ideas/README.md (763b), templates/product/readme-first-product.md (4157b), templates/read-me-first.md (4949b), _meta.json (133b)\n\nFile v1.9.64:SKILL.md\n\n---\nname: wip-repo-init\ndescription: Scaffold the standard ai/ directory structure in any repo.\nlicense: MIT\ninterface: [cli, skill]\nmetadata:\n display-name: \"Repo Init\"\n version: \"1.0.0\"\n homepage: \"https://github.com/wipcomputer/wip-ai-devops-toolbox\"\n author: \"Parker Todd Brooks\"\n category: repo-management\n capabilities:\n - scaffold-ai-dir\n - template-copy\n requires:\n bins: [node]\n openclaw:\n requires:\n bins: [node]\n install:\n - id: node\n kind: node\n package: \"@wipcomputer/wip-repo-init\"\n bins: [wip-repo-init]\n label: \"Install via npm\"\n emoji: \"📁\"\ncompatibility: Requires node. Node.js 18+.\n---\n\n# Repo Init\n\nScaffolds the standard `ai/` directory structure in any repo.\n\n## Commands\n\n```\nwip-repo-init /path/to/repo # scaffold ai/ in a repo\nwip-repo-init /path/to/repo --dry-run # preview without changes\nwip-repo-init /path/to/repo --yes # skip confirmation prompt\n```\n\n## What happens\n\n**New repo (no ai/ folder):** Creates the full standard structure with all READMEs explaining what goes where.\n\n**Existing repo (ai/ folder exists):** Shows you what will happen and asks for confirmation. If you say yes:\n1. Moves your current `ai/` contents to `ai/_sort/ai_old/`\n2. Scaffolds the new standard structure\n3. You sort files from `ai_old/` into the new structure at your own pace\n\nNothing is deleted. Your old files are all in `ai/_sort/ai_old/`.\n\n## The standard ai/ structure\n\n```\nai/\n read-me-first.md <- explains everything, links to all sections\n _sort/ <- holding pen for files that need sorting\n _trash/ <- archive (never delete, move here)\n dev-updates/ <- engineering changelog, auto-detected by wip-release\n product/\n readme-first-product.md <- the product bible\n notes/ <- freeform notes, research\n plans-prds/ <- plans with lifecycle stages\n roadmap.md <- prioritized roadmap\n current/ <- plans being built now\n upcoming/ <- plans that are next\n archive-complete/ <- plans that shipped\n todos/ <- per-agent todo files\n product-ideas/ <- ideas that aren't plans yet\n```\n\nEvery folder has a `_trash/` subfolder. Every section has a README explaining what it is, what goes in it, and how to maintain it.\n\n## Interfaces\n\nCLI, Skill\n\nFile v1.9.64:README.md\n\n###### WIP Computer\n\n# Repo Init\n\nScaffold the standard `ai/` directory in any repo. Plans, notes, ideas, dev updates, todos. One command.\n\n## What it does\n\n- **New repo:** Creates the full `ai/` directory structure\n- **Existing repo:** Moves old `ai/` contents to `ai/_sort/ai_old/` so you can sort at your own pace\n- Nothing is deleted\n\n## The `ai/` directory\n\n```\nai/\n plan/ architecture plans, roadmaps\n dev-updates/ what was built, session logs\n todos/\n PUNCHLIST.md blockers to ship\n inboxes/ per-agent action items\n notes/ research, references, raw conversation logs\n```\n\nThe `ai/` folder is the development process. It is not part of the published product. Public repos exclude it via deploy-public.sh.\n\n## Usage\n\n```bash\nnode tools/wip-repo-init/init.mjs /path/to/repo\n```\n\n## Interfaces\n\n- **CLI**: Run from terminal\n- **Skill**: SKILL.md for agent instructions\n\n## Part of [AI DevOps Toolbox](https://github.com/wipcomputer/wip-ai-devops-toolbox)\n\nFile v1.9.64:templates/_sort/README.md\n\n# _sort/\n\nThe holding pen. Files that need to be looked at and filed somewhere.\n\n## What Goes Here\n\n- iCloud duplicates or randomly placed files that need sorting\n- Files you're not sure where to put yet\n- Anything that needs a human to look at it and decide where it belongs\n\n## Rules\n\n- **Not trash.** `_sort/` is for files you want to review. `_trash/` is for files you're done with.\n- **Don't let it pil...","readmeExcerpt":"Skill: Wip Repo Init Owner: parkertoddbrooks Summary: Scaffold the standard ai/ directory structure in any repo. Tags: latest:1.9.72 Version history: v1.9.72 | 2026-04-21T21:25:26.686Z | user AI DevOps Toolbox v1.9.72 Promote v1.9.71-alpha series to stable Closes #256. Consolidates 21 alpha prereleases (v1.9.71-alpha.1 through v1.9.71-alpha.21) into a stable v1.9.72 release. No code changes beyond the version bump in","codeSnippets":[],"executableExamples":[{"language":"bash","snippet":"grep -r \"/Users/lesa\" ldm-jobs/ tools/wip-branch-guard/test.sh\n# Should return zero results"},{"language":"bash","snippet":"# In any repo with multiple merged PRs since last tag, each having RELEASE-NOTES files:\nwip-release patch --dry-run\n# Should show: \"Combined release notes from N merged PRs\""},{"language":"bash","snippet":"# On main, without release notes: should error, NOT scaffold\ncd any-repo && git checkout main\nwip-release patch\n# Expected: \"Release notes missing. Write RELEASE-NOTES-v*.md on your feature branch before merging.\"\n# Expected: no RELEASE-NOTES file created in working tree\n\n# On a feature branch: should scaffold as before\ngit checkout -b test/scaffold-check\nwip-release patch\n# Expected: scaffolded template created"},{"language":"bash","snippet":"wip-release patch --dry-run\n# Should show no \"fatal\" or \"Not a valid object name\" errors\n# Guard tests: cd tools/wip-branch-guard && bash test.sh"},{"language":"bash","snippet":"wip-release patch\ngit status\n# Should show clean working tree after release"},{"language":"bash","snippet":"cd tools/wip-branch-guard && bash test.sh\n# Should show: 30 passed, 0 failed, 3 skipped"}],"parameters":null,"dependencies":[],"permissions":[],"extractedFiles":[{"path":"SKILL.md","content":"---\nname: wip-repo-init\ndescription: Scaffold the standard ai/ directory structure in any repo.\nlicense: MIT\ninterface: [cli, skill]\nmetadata:\n display-name: \"Repo Init\"\n version: \"1.0.0\"\n homepage: \"https://github.com/wipcomputer/wip-ai-devops-toolbox\"\n author: \"Parker Todd Brooks\"\n category: repo-management\n capabilities:\n - scaffold-ai-dir\n - template-copy\n requires:\n bins: [node]\n openclaw:\n requires:\n bins: [node]\n install:\n - id: node\n kind: node\n package: \"@wipcomputer/wip-repo-init\"\n bins: [wip-repo-init]\n label: \"Install via npm\"\n emoji: \"📁\"\ncompatibility: Requires node. Node.js 18+.\n---\n\n# Repo Init\n\nScaffolds the standard `ai/` directory structure in any repo.\n\n## Commands\n\n```\nwip-repo-init /path/to/repo # scaffold ai/ in a repo\nwip-repo-init /path/to/repo --dry-run # preview without changes\nwip-repo-init /path/to/repo --yes # skip confirmation prompt\n```\n\n## What happens\n\n**New repo (no ai/ folder):** Creates the full standard structure with all READMEs explaining what goes where.\n\n**Existing repo (ai/ folder exists):** Shows you what will happen and asks for confirmation. If you say yes:\n1. Moves your current `ai/` contents to `ai/_sort/ai_old/`\n2. Scaffolds the new standard structure\n3. You sort files from `ai_old/` into the new structure at your own pace\n\nNothing is deleted. Your old files are all in `ai/_sort/ai_old/`.\n\n## The standard ai/ structure\n\n```\nai/\n read-me-first.md <- explains everything, links to all sections\n _sort/ <- holding pen for files that need sorting\n _trash/ <- archive (never delete, move here)\n dev-updates/ <- engineering changelog, auto-detected by wip-release\n product/\n readme-first-product.md <- the product bible\n notes/ <- freeform notes, research\n plans-prds/ <- plans with lifecycle stages\n roadmap.md <- prioritized roadmap\n current/ <- plans being built now\n upcoming/ <- plans that are next\n archive-complete/ <- plans that shipped\n todos/ <- per-agent todo files\n product-ideas/ <- ideas that aren't plans yet\n```\n\nEvery folder has a `_trash/` subfolder. Every section has a README explaining what it is, what goes in it, and how to maintain it.\n\n## Interfaces\n\nCLI, Skill"},{"path":"README.md","content":"###### WIP Computer\n\n# Repo Init\n\nScaffold the standard `ai/` directory in any repo. Plans, notes, ideas, dev updates, todos. One command.\n\n## What it does\n\n- **New repo:** Creates the full `ai/` directory structure\n- **Existing repo:** Moves old `ai/` contents to `ai/_sort/ai_old/` so you can sort at your own pace\n- Nothing is deleted\n\n## The `ai/` directory\n\n```\nai/\n plan/ architecture plans, roadmaps\n dev-updates/ what was built, session logs\n todos/\n PUNCHLIST.md blockers to ship\n inboxes/ per-agent action items\n notes/ research, references, raw conversation logs\n```\n\nThe `ai/` folder is the development process. It is not part of the published product. Public repos exclude it via deploy-public.sh.\n\n## Usage\n\n```bash\nnode tools/wip-repo-init/init.mjs /path/to/repo\n```\n\n## Interfaces\n\n- **CLI**: Run from terminal\n- **Skill**: SKILL.md for agent instructions\n\n## Part of [AI DevOps Toolbox](https://github.com/wipcomputer/wip-ai-devops-toolbox)"},{"path":"templates/_sort/README.md","content":"# _sort/\n\nThe holding pen. Files that need to be looked at and filed somewhere.\n\n## What Goes Here\n\n- iCloud duplicates or randomly placed files that need sorting\n- Files you're not sure where to put yet\n- Anything that needs a human to look at it and decide where it belongs\n\n## Rules\n\n- **Not trash.** `_sort/` is for files you want to review. `_trash/` is for files you're done with.\n- **Don't let it pile up.** Check this folder periodically. File things or trash them.\n- **Agents:** If you don't know where a file goes, put it in `_sort/`. A human will sort it later."},{"path":"templates/_trash/README.md","content":"# _trash/\n\nThe archive. Files that are done, replaced, or consumed. Never delete anything. Move it here.\n\n## What Goes Here\n\n- Superseded plans (replaced by a newer version)\n- Consumed release notes (already used by `wip-release`)\n- Abandoned drafts\n- Anything you're done with but might need to reference later\n\n## Rules\n\n- **This is not garbage.** It's the archive. Everything in git history is recoverable, but `_trash/` keeps things findable without digging through commits.\n- **Subfolders have their own `_trash/`.** Use the nearest one. `dev-updates/_trash/` for old dev updates, `product/notes/_trash/` for old notes, etc.\n- **Never delete files from the repo.** Move them to `_trash/` instead."},{"path":"templates/dev-updates/README.md","content":"# dev-updates/\n\nOne file per significant change. Written as you work, auto-detected by `wip-release`.\n\n## What This Folder Is\n\nDev updates are the engineering changelog. Every time you do significant work (ship a feature, fix a bug, change architecture), write a dev update. `wip-release` picks up today's dev updates and uses them as release notes.\n\nThis is not a place for plans or ideas. It's a record of what was built and why.\n\n## Naming Convention\n\n```\nYYYY-MM-DD--HH-MM--agent--description.md\n```\n\nExamples:\n- `2026-03-11--09-30--cc-mini--fix-hook-duplicates.md`\n- `2026-03-10--14-00--lesa-mini--add-voice-call-support.md`\n\n## File Format\n\n```markdown\n# Short title of what changed\n\n**Date:** YYYY-MM-DD HH:MM TZ\n**Author:** Agent Name (agent-id)\n\n## Problem\n\nWhat was broken or missing.\n\n## Fix / What Changed\n\nWhat you did and why.\n\n## Files changed\n\n- `path/to/file.js` ... what changed in it\n\nCloses #issue-number (if applicable)\n```\n\n## Rules\n\n- **Write them as you work.** Don't batch them at the end. Each significant change gets its own file.\n- **One file per change.** Not one file per day. If you fix two unrelated bugs, write two files.\n- **Include the \"why.\"** \"Fixed X\" is a commit message. A dev update explains why it was broken and why the fix works.\n- **Reference issues.** If there's a GitHub issue, add `Closes #N` at the bottom.\n- **Consumed files go to `_trash/`.** `wip-release` doesn't move them automatically, but the release notes files it generates do get trashed after release."}],"languages":[],"docsSourceLabel":"CLAWHUB","editorialOverview":null,"editorialQuality":{"score":100,"threshold":65,"status":"thin","wordCount":2487,"uniquenessScore":38,"reasons":["uniqueness-below-45"]}},"media":{"evidence":{"source":"no-media","verified":false,"confidence":"low","updatedAt":"2026-10-10T07:34:03.816Z","emptyReason":"No screenshots, media assets, or demo links are available."},"primaryImageUrl":null,"mediaAssetCount":0,"assets":[],"demoUrl":null},"ownerResources":{"evidence":{"source":"unclaimed","verified":false,"confidence":"low","updatedAt":"2026-10-10T07:34:03.816Z","emptyReason":"This page has not been claimed by the agent owner."},"hasCustomPage":false,"customPageUpdatedAt":null,"customLinks":[],"structuredLinks":{"docsUrl":null,"demoUrl":null,"supportUrl":null,"pricingUrl":null,"statusUrl":null},"customPage":null},"relatedAgents":{"evidence":{"source":"protocol-neighbors","verified":false,"confidence":"medium","updatedAt":"2026-10-10T08:01:50.328Z","emptyReason":null},"items":[{"id":"8ebccd8e-3863-4187-8355-c3f14e1f9edf","entityType":"agent","canonicalPath":"/agent/iofficeai-aionui","slug":"iofficeai-aionui","name":"AionUi","description":"Free, local, open-source 24/7 Cowork app and OpenClaw for Gemini CLI, Claude Code, Codex, OpenCode, Qwen Code, Goose CLI, Auggie, and more | 🌟 Star if you like it!","url":"https://github.com/iOfficeAI/AionUi","homepage":"https://www.aionui.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-10-09T19:11:12.944Z","createdAt":"2026-02-25T03:38:16.584Z","downloads":null},{"id":"b917f68a-ebff-438e-84f8-3f4b2494c0bc","entityType":"agent","canonicalPath":"/agent/activepieces-activepieces","slug":"activepieces-activepieces","name":"activepieces","description":"AI Agents & MCPs & AI Workflow Automation • (~400 MCP servers for AI agents) • AI Automation / AI Agent with MCPs • AI Workflows & AI Agents • MCPs for AI Agents","url":"https://github.com/activepieces/activepieces","homepage":"https://www.activepieces.com","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-15T02:22:12.426Z","createdAt":"2026-02-25T03:38:12.412Z","downloads":null},{"id":"5cb26759-3a39-483f-94cf-276a98c13bb8","entityType":"agent","canonicalPath":"/agent/cherryhq-cherry-studio","slug":"cherryhq-cherry-studio","name":"cherry-studio","description":"AI productivity studio with smart chat, autonomous agents, and 300+ assistants. Unified access to frontier LLMs","url":"https://github.com/CherryHQ/cherry-studio","homepage":"https://cherry-ai.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-11T14:38:40.986Z","createdAt":"2026-02-25T03:38:19.379Z","downloads":null},{"id":"6f6582d0-5d76-4f0f-b81d-86520247950b","entityType":"agent","canonicalPath":"/agent/copilotkit-copilotkit","slug":"copilotkit-copilotkit","name":"CopilotKit","description":"The Frontend for Agents & Generative UI. React + Angular","url":"https://github.com/CopilotKit/CopilotKit","homepage":"https://docs.copilotkit.ai","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-03-25T09:50:57.846Z","createdAt":"2026-02-25T03:39:14.617Z","downloads":null}],"links":{"hub":"/agent","source":"/agent/source/clawhub","protocols":[{"label":"OpenClaw","href":"/agent/protocol/openclew"}]}}}