summaryrefslogtreecommitdiff
path: root/docs
AgeCommit message (Collapse)Author
2026-09-17Merge pull request #2301 from obra/fix/invoke-scripts-via-interpreterDrew Ritter
Invoke bundled scripts through their interpreter in skill prose
2026-09-15Merge origin/dev into import/proving-it-works-skillDrew Ritter
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
2026-09-14Invoke bundled scripts through their interpreter in skill prosefix/invoke-scripts-via-interpreterJesse Vincent
Plugin packagers for other harnesses can strip executable bits from the files they ship. The Codex marketplace cache delivered the SDD helpers as 0644 (#2040), and the MiniMax Code marketplace ships its repackaged copy of our skills tree with every file at mode 600. On those installs every bare invocation in our skill prose -- `scripts/start-server.sh ...`, `scripts/review-package ...`, `./find-polluter.sh ...`, `./render-graphs.js ...` -- fails with "Permission denied", so the brainstorming visual companion, subagent-driven development, the polluter bisection helper, and render-graphs are all broken there even though the repo records the files as 100755. Spell every script invocation in skills/**/*.md through its interpreter instead: `bash` for the shell scripts (start-server.sh, stop-server.sh, sdd-workspace, task-brief, review-package, find-polluter.sh) and `node` for render-graphs.js, per each script's shebang. That form works whether or not the exec bit survived packaging. The MiniMax Code marketplace package independently applied exactly this edit to its copy of v6.2.0; this brings the same pattern upstream so every packager gets it. Nothing else in the prose changes. #2134 covers the complementary case of a script exec'ing a sibling script (task-brief and review-package calling sdd-workspace) and is still needed alongside this. Record the rationale in docs/porting-to-a-new-harness.md (Part 6 distribution notes plus an Appendix B gotcha) and add a one-line note to writing-skills' File Organization section so future skill authors don't strip the prefixes. Refs #2040, #2134.
2026-09-11docs: record consolidated movie repair verificationDrew Ritter
Complete the four-task repair plan after independent reviews and two fresh-reader reference trials. Record 66 current contract tests and 45 existing safe regressions, executable recipe failures and repairs, and the limits of those checks. Drew requested a committee and full local review after repeated PR feedback. Preserve the negative evidence, distinguish historical native runs from current mocked/text checks, and retain Drew's video viewing as final acceptance. The whole accumulated PR review and authorized existing-branch update remain the next steps; no merge is performed.
2026-09-11docs: make proof-movie recipes preserve failuresDrew Ritter
Repair the shipped Unix, logging, subtitle, cursor, narration, and recorder guidance against the literal fake-boundary failures recorded for Task 4. The primary pipeline and subtitle recipe now fail fast, measured offsets reach subtitle generation, producer logging preserves the real status under the pipefail owner, and cursor mouseup restores the released state. Document the accepted narration/cache contract, cooperative recorder cleanup limits, and the safe contracts-suite entrypoint without changing Windows recipes or the existing evidence and human-viewing gates. Include the controller-owned plan bookkeeping and record the executable RED/GREEN results while leaving independent fresh-reader trials pending. Prompt: implement Task 4 focused executable movie-guide corrections after Tasks 1-3, using writing-skills and only fake producers, text fixtures, and fake DOM execution. Verification: python3 .superpowers/review/pr2214/committee/recipe-probes.py; uv run --script tests/proving-it-works-with-a-movie/run-tests.py --suite contracts; git diff --check.
2026-09-11docs: plan consolidated movie committee repairsDrew Ritter
Drew requested a whole-PR committee review after repeated narrow fixes missed failures. Record the repair boundaries, acceptance handoff, timing and lifecycle contracts, and focused regression cases before implementation. Preserve existing artifact formats and Drew-owned video acceptance; all automated checks in this pass use mocked media boundaries.
2026-09-11docs(movie): make native Windows recorder recipes executablefeat/movie-os-compatibilityDrew Ritter
Replace the Git Bash PowerShell shorthand with complete native commands, explicit path conversion, a kept-alive serve task, bounded readiness, and run/key/watch/close examples. Use native input and sleep commands so the recipe works without a sample app. Explain empty take directories and PowerShell 5.1 embedded-quote escaping observed in native trials. The original PowerShell missing-cwd finding does not reproduce when the session is nested under the working directory; retain the successful baseline and describe explicit directory creation as setup clarity. Fresh readers exercised the final recipes on native PowerShell 5.1, PowerShell 7, and Git Bash. Preserve the failed first candidate and driver setup failures, distinguish instruction trials from full skill evaluation, and keep movie acceptance with Drew. Record Drew's approval of the normal workflow dependencies and the bounded repair plan.
2026-09-11diagnosing-superpowers: use gh for issue search and creationJesse Vincent
gh handles auth, rate limits, and JSON, and the approval gate on the exact issue text already covers posting. Keep the public-API and prefilled-link paths as fallbacks for machines without gh. Note that GitHub drops labels from reporters without push access, so the template footer is the durable marker of a skill-filed issue.
2026-09-11diagnosing-superpowers: writing review fixesJesse Vincent
Move GitHub search and prefilled-link mechanics to references/github-issues.md. State the redaction levels neutrally instead of nudging toward more data. Say that all seven analysts always run and what the quick-reference table is for. Add a title slot and a bundle slot to the issue template. Drop the duplicated human-prompts rule from request-conflicts. Prose fixes: active voice, dangling modifier, vague referents, two lists turned into tables.
2026-09-11spec: 'agreed to', not 'committed to', in the plan-adherence summaryJesse Vincent
2026-09-11diagnosing-superpowers: say 'plan step', not 'commitment'Jesse Vincent
In a transcript full of git commits, 'commitment' and 'committed to' read as version control. The plan-adherence and quality-evidence prompts now say 'agreed plan' and 'plan step'.
2026-09-11diagnosing-superpowers: drop gh; file issues through a prefilled template linkJesse Vincent
A default gh login carries the repo scope, which is write access to every repository the user can reach. The skill now searches issues through the unauthenticated public API and, instead of posting, hands the partner a prefilled new-issue link. The link uses a new diagnosis_report.md issue template so the bug and automated-issue-report labels apply regardless of the reporter's permissions. Addresses arittr's review on #2236.
2026-09-11diagnosing-superpowers: share the analyst preamble and context-safety rulesJesse Vincent
The seven analyst prompts opened with an identical 39-line block (role, inputs, context safety, return format). It now lives once in prompts/analyst-common.md and each dimension prompt points at it. The wc -lc / long-line / never-cat rule was restated in nine places; it now lives in references/context-safety.md and everything else points there. Addresses arittr's review on #2236.
2026-09-11diagnosing-superpowers: build the scrubbed bundle only on requestJesse Vincent
Never build or push a bundle unprompted. When intake names a bug report as the goal, say once that a bundle is available on request, then wait. On handover, state what the bundle contains, point at the scrub log, and say scrubbing can miss things so every file needs review before sharing. Raise the SKILL.md word budget to 1000 to fit the added rule.
2026-09-11feat: add diagnosing-superpowers skillJesse Vincent
Evidence-based diagnosis of superpowers sessions: intake with the human partner, safe transcript reading for Claude Code and Codex (discovery procedure for other harnesses), seven analyst subagents, a report with path:line evidence and a bounded superpowers-involvement line, scrubbed export bundles, approval-gated GitHub issue search/draft, and similar-session search. Includes spec, plan, structure test, and README and docs index lines. Developed RED-GREEN-REFACTOR per writing-skills: 46 scored scenario runs across five SKILL.md versions, all twelve scenarios clean against the final version, micro-tests control 5/5 to skill 0/5 on both baseline-failing prohibitions, and one end-to-end run. Eval records are kept by the maintainer outside the repo. Claude-Session: https://claude.ai/code/session_01DyaGKhTXvHNs2JgPhDktz7
2026-09-09feat(movie): simplify the Windows terminal recorder to serve/run/key/watch/closeDrew Ritter
Windows has no tmux, so the recorder had grown into a 738-line daemon with a file-based request protocol, request IDs, wait-only result retrieval, and a Win32 Job Object module. Replace it with the Unix route's shape: serve keeps ttyd and a headless browser alive and logs the terminal's output; run, key, watch, and close are one-shot CDP calls against that browser. The installed prompt reports each command's status through the window title, so run can print it without any visible marker. Process cleanup uses taskkill /T (a pgrep walk on Unix) instead of Job Objects, which also simplifies the card renderer. The session tests run on macOS too, since nothing in the script is Windows-specific. Verified: 9 session tests per shell on Windows 11 for PowerShell 5.1, PowerShell 7, and Git Bash; the browser suite with Chrome and Edge; 44 portable tests on macOS against a real ttyd session. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
2026-09-09docs(movie): trim Windows guidance to what the tools needDrew Ritter
Remove generic shell exit-status recipes and a stills wrapper that the card scene already covers. Keep the gdigrab commands and the verify-on notes short. Reduce the spec to the design: drop execution logistics, host names, and references to deleted files. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
2026-09-09chore(movie): drop the abandoned OS-rollout probe and superseded plansDrew Ritter
The first, broader OS-compatibility rollout was stopped and replaced by the narrower Windows completion. Its feasibility probe, probe cleanup test, design, review, 12-task plan, results report, and the completion plan and review record were internal execution artifacts with machine-specific paths. The one probe-derived test list is inlined into the terminal suite. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
2026-09-09docs(movie): document and verify Windows workflowsDrew Ritter
2026-09-09docs: plan three milestones to finish Windows movie supportDrew Ritter
2026-09-09docs: resolve adversarial review of Windows completion scopeDrew Ritter
2026-09-09docs: scope remaining movie work to Windows completionDrew Ritter
2026-09-09docs(movie): avoid repeating the interactive probe takeDrew Ritter
2026-09-09fix(movie): release probe resources after evidence failuresDrew Ritter
2026-09-09docs: plan proof movie OS compatibility with Windows validation hostDrew Ritter
2026-09-09docs: resolve adversarial review of movie compatibility specDrew Ritter
2026-09-09docs: specify proof movie OS compatibilityDrew Ritter
2026-08-06docs: plan Hermes version-bump wiringDrew Ritter
Record Drew's approved reduced design after the second staff review. Limit preflight to the mutating bump path, cover audit's independent read path, and require byte-for-byte proof that deterministic YAML failures cannot partially update earlier JSON manifests. Provide one TDD implementation task for the Hermes registry entry, jq/yq dispatch, focused preflight, and three behavioral checks. Explicitly defer rollback, audit-status changes, nested YAML, runtime changes, and broader release-tool refactoring.
2026-08-06docs: reduce Hermes version-bump designDrew Ritter
Incorporate the adversarial design review without turning the Hermes wiring follow-up into a general release-script refactor. Keep the existing jq path, add Mike Farah yq v4 only for .yaml, and retain one read-only preflight to prevent deterministic partial bumps.\n\nReduce the test contract to three behavioral cases and explicitly defer .yml support, nested YAML, rollback machinery, audit/status redesign, exhaustive failure matrices, and the separately discovered JSON-expression issue. This follows Drew's direction to avoid ceremony and overengineering.
2026-08-06docs: design Hermes version-bump wiringDrew Ritter
Document the agreed follow-up to PR #2025 on a branch based on its merged dev commit. The design registers the Hermes YAML manifest, keeps jq for existing JSON files, and uses Mike Farah yq v4 for a narrow top-level YAML field rather than adding a Bash parser.\n\nDefine focused failure behavior and behavioral tests while explicitly excluding nested YAML, Hermes runtime changes, and unrelated release-script refactors. This captures Drew's request to keep the implementation small and avoid process or abstraction overhead.
2026-07-31docs: codex-efficiency fix-cycle spec and plan (campaign record)fix/docs-codex-efficiency-campaignJesse Vincent
2026-07-19docs(plans): SDD fix-loop redesign implementation planJesse Vincent
Eight tasks across two repos: new re-review template, template/reference alignment, full SKILL.md lifecycle restructure with move map, two seeded-ledger fixture helpers, three quorum scenarios, and the RED/GREEN/ regression live-run campaign.
2026-07-19docs(specs): SDD fix-loop redesign design specJesse Vincent
Review-fix loop gets resume-the-implementer semantics, scoped re-reviews, a five-round circuit breaker, and controller adjudication at trip. SKILL.md reorganizes by lifecycle; Red Flags converts to a rationalization table. Brainstormed with Jesse 2026-07-15.
2026-07-19docs(windows): document shell:bash hook dispatch and the PowerShell/CMD ↵Jesse Vincent
fallback hazards
2026-07-19eval(sdd): GREEN results — plan-scoped resolution replaces cross-plan ↵Jesse Vincent
forensics
2026-07-19eval(sdd): RED baseline — 25/25 controllers refuse stale ledgers, at a ↵Jesse Vincent
forensic cost
2026-07-19docs(specs): record eval re-scope — blind adoption did not reproduce, ↵Jesse Vincent
claims narrowed 25/25 baseline reps refused the stale foreign ledger via git forensics; the spec's evaluation section now states the honest claims: structural fix + measured disambiguation-cost delta + same-plan-resume regression gate, shipping with explicit maintainer sign-off in place of a failing S1 baseline.
2026-07-19docs(plans): re-scope eval per maintainer decision — RED compiled, GREEN ↵Jesse Vincent
measures cost Three RED rounds (25 reps, three framings incl. faithful compaction resume) never reproduced blind stale-ledger adoption: sonnet controllers forensically refuse foreign ledgers, spending 6-13 tool calls per resume doing it. Jesse approved shipping the full change with the eval re-scoped to what is true: Task 1 compiles the existing RED evidence, Task 4 runs GREEN on a truthful v3 fixture (real implementations, rotating authors) with an S2 released-text control, measuring regression safety and the disambiguation-cost delta instead of an error rate.
2026-07-19docs(plans): fixture v2 — real cited commits, matched task countsJesse Vincent
Fixture v1 tripped the Task 1 STOP gate for the right reason: its ledgers cited fabricated hashes, so RED agents dismissed them via git forensics (S1 passed for the wrong mechanism, the S2 resume control failed 5/5). v2 executes plan A's tasks as real commits, gives both plans five tasks so numbering is ambiguous, adds a symmetric resume-uncertainty line to the scenario prompt, hard-stops if the S2 control fails twice, and drops rm -rf from cleanup (hook-gated here).
2026-07-19docs(plans): SDD plan-scoped workspace implementation planJesse Vincent
Five tasks: RED baseline eval (writing-skills Iron Law — before any skill edit), plan-scoped scripts via TDD, SKILL.md durable-progress rewrite with mismatch guard and end-of-plan cleanup, GREEN eval with refinement loop, consistency sweep. Eval = 5 fresh sonnet subagents per scenario per arm, hand-scored.
2026-07-19docs(specs): SDD plan-scoped workspace designJesse Vincent
The .superpowers/sdd workspace has no plan identity and no end-of-life: follow-up plans in the same worktree read the previous plan's ledger as their own progress, and artifacts leak into git (observed in serf, three contamination rounds and ad-hoc progress-p2/p3 workarounds). Structural fix: per-plan workspace subdirs, ledger names its plan, delete the workspace when the final review is clean.
2026-07-15docs: fix dead references to pruned claude-code-tools.md/copilot-tools.mdJesse Vincent
e7ddc25 deleted claude-code-tools.md and copilot-tools.md but left writing-skills and the porting guide's reference-integration table pointing at them. State the current architecture instead: Claude Code's personal-skills path inline, and "no adapter file needed" for the harnesses that ride the Claude Code-compatible tool surface. Reported by @rasibintang (#1969, with a fix proposed in #1970). Fixes #1969
2026-07-02docs: re-anchor Shape A examples away from CodexDrew Ritter
2026-07-02chore(codex): remove orphaned session-start-codex hook + refresh hook docsDrew Ritter
hooks/session-start-codex has had no caller since "Remove Codex hooks" (#1845) deleted hooks-codex.json and its manifest registration; the Codex manifest now declares an empty hooks object so Codex registers no session-start hook at all. The script is Codex-specific dead code — nothing executes it on Codex or any other harness. - Delete hooks/session-start-codex. - tests/hooks/test-session-start.sh: drop the two Codex cases that are redundant with the generic session-start tests (nested-format and the legacy-warning omission are already covered by the Claude Code cases). Re-point the "wrapper dispatches" case to the live `session-start` script so run-hook.cmd dispatch coverage — used by Claude Code and Cursor in production — is preserved rather than lost. - docs/porting-to-a-new-harness.md: Codex is no longer a Shape A (shell-hook) harness, so re-anchor that worked example to Cursor (a live shell-hook harness that demonstrates the same per-harness field, schema, and matcher variance) and mark Codex as native skill discovery with no session-start hook. Clears the references to the deleted hooks-codex.json. - docs/windows/polyglot-hooks.md: the "check hooks-codex.json" pointer referenced a file deleted in #1845; re-point to hooks-cursor.json. RELEASE-NOTES.md keeps its historical mention of hooks-codex.json (it accurately records what that release did). The tests/codex-plugin-sync fixtures build their own synthetic session-start-codex and test the sync mechanism generically, so they are intentionally left as-is. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-06-16Spec: L2b tested — opus structural win, sonnet transmission+attention gap ↵Jesse Vincent
(E35/E36); bump evals to 9919b27
2026-06-16Strict-cost spec: L2 final — died at gates; explicit escalation holds at ↵Jesse Vincent
sonnet, implicit adjudication does not
2026-06-16Strict-cost spec: L1 final — cost win re-attributed to complete-code ↵Jesse Vincent
plans; guidance owns fidelity/variance
2026-06-16Strict-cost spec: L2 recon n=2 (sonnet controller $6.68/$8.05, judgment ↵Jesse Vincent
clean, escalation points unstressed)
2026-06-16Strict-cost spec: record batch A-E rung verdicts (L1 validated, L2 recon ↵Jesse Vincent
positive, L3 dead)
2026-06-16Spec: strict-cost SDD experiment ladder — judgment as co-invariant, ↵Jesse Vincent
plan-side crispness first