From 706609fdbbd707902efe82e90f7ad0bf3f1df9a1 Mon Sep 17 00:00:00 2001 From: Max Haarhaus Date: Sat, 8 Aug 2026 01:29:07 -0400 Subject: [PATCH] chore(dx): remove memory-bank from version control --- .gitignore | 3 + AGENTS.md | 5 +- memory-bank/activeContext.md | 106 ---------------------------------- memory-bank/productContext.md | 26 --------- memory-bank/progress.md | 49 ---------------- memory-bank/projectbrief.md | 25 -------- memory-bank/systemPatterns.md | 48 --------------- memory-bank/techContext.md | 30 ---------- 8 files changed, 6 insertions(+), 286 deletions(-) delete mode 100644 memory-bank/activeContext.md delete mode 100644 memory-bank/productContext.md delete mode 100644 memory-bank/progress.md delete mode 100644 memory-bank/projectbrief.md delete mode 100644 memory-bank/systemPatterns.md delete mode 100644 memory-bank/techContext.md diff --git a/.gitignore b/.gitignore index ce255d9..a1ed549 100644 --- a/.gitignore +++ b/.gitignore @@ -4,6 +4,9 @@ !.claude/settings.json # Cline plugin install artifacts (e.g. from `cline plugin install ./ --cwd .`). .cline/plugins/ +# Cline Memory Bank contents are per-developer local state; the shared +# Memory Bank rule lives in .clinerules/ and stays tracked. +memory-bank/ .DS_Store node_modules/ .eval-magic diff --git a/AGENTS.md b/AGENTS.md index 1c83bce..eabac96 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -16,8 +16,9 @@ This repo ships Slow-powers across four harnesses: Cline-specific setup for working on this repo also lives at root: -- `.clinerules/` — Cline rules (the Memory Bank custom instructions) -- `memory-bank/` — Cline Memory Bank files recording ongoing work +- `.clinerules/` — Cline rules (the Memory Bank custom instructions), tracked +- `memory-bank/` — Cline Memory Bank contents. Gitignored: each developer + keeps their own local bank; only the rule in `.clinerules/` is shared ## Editing the right files diff --git a/memory-bank/activeContext.md b/memory-bank/activeContext.md deleted file mode 100644 index 40f0841..0000000 --- a/memory-bank/activeContext.md +++ /dev/null @@ -1,106 +0,0 @@ -# Active Context - -## Current focus - -Cline plan-gate timing fix (August 2026). The first live test of the Cline -plugin showed the gate rejecting an un-hardened plan only AFTER the plan was -presented and approved — because `switch_to_act_mode` is called post-approval -in Cline, unlike Claude's `ExitPlanMode` which carries the plan text. The gate -is now two-layer: - -1. **Cline plugin** (`cline/plugins/slow-powers.js`, declared via the `cline` - field in `package.json`): registers `bootstrap.md` AND a - `slow-powers/plan-presentation` rule (harden before presenting — the only - mechanism that reaches the agent pre-presentation), and gates - `switch_to_act_mode` as a pre-EXECUTION backstop with an - already-hardened transcript short-circuit (skip-once marker as fail-open - floor, mirroring `hooks/exit-plan-mode`). - Skills are auto-discovered from the package root — no wiring needed. -2. **Repo-local Cline setup**: `.clinerules/memory-bank.md` (canonical Memory - Bank instructions) and this `memory-bank/` directory, both committed. - -## Recent changes - -- `fix/cline-plan-gate-timing` branch: plugin header docs rewritten (real - Cline plan flow), `PLAN_PRESENTATION_RULE` added, `planAlreadyHardened()` - transcript scan added (matches the `skills` tool-input shape only, never - prose, so the hook's own skip reason can't false-positive), `SKIP_REASON` - reworded for execution-gate semantics; 5 new tests in - `tests/harness/cline-plugin.test.ts` (rule registration, short-circuit, - false-positive guards, full flow). -- Earlier (merged via PR #266/#267/#268): `cline/plugins/slow-powers.js` (new), - `package.json` `cline` field + `files`; `tests/harness/spec.ts` Cline entry; - Cline assertions in `manifests.test.ts`; README Cline install section; - AGENTS.md four-harness update; `.gitignore` covers `.cline/plugins/`. - -## Verification results - -- `bun test`: 167 pass / 0 fail; typecheck and biome clean on changed files. - (Baseline note: `bun run check` fails on three pre-existing - `.eval-magic/hardening-plans/iteration-2` eval-fixture files — unrelated.) -- Live (Cline CLI 3.0.51, headless): install, skills discovery, bootstrap rule - injection confirmed. First interactive test exposed the gate-timing issue - this branch fixes. -- Plan gate: unit-tested against the documented `AgentBeforeToolResult` - contract; runtime `skip` handling and hook context shape confirmed in the - shipped CLI source. `switch_to_act_mode` is NOT exposed in headless one-shot - sessions, so an interactive (TUI) confirmation of the new two-layer behavior - is the one remaining manual check. - -## Next steps - -- Manually confirm the new behavior in an interactive `cline -i` plan-mode - session: with the rule active the agent should harden BEFORE presenting; - if it skips hardening, the first `switch_to_act_mode` after approval is - skipped with the hardening instruction and the retry (transcript now holds - the skills call) passes. -- Then open the PR for `fix/cline-plan-gate-timing` (base `dev`). - -## Active decisions - -- Distribution reuses the root `package.json` (git install); no separate npm - package or release-workflow change. -- Pre-presentation enforcement is a RULE, not a hook: Cline has no hook moment - before a plan is shown (verified against the installed binary and - `@cline/shared` `AgentRuntimeHooks`). The hook stays as the pre-execution - backstop. Trust guarantee moves from "user only ever sees a hardened plan" - (Claude, achievable) to "an un-hardened plan is never executed, and hook - firing routes the agent to harden + re-present" (Cline). -- The already-hardened short-circuit (upstream #153 refinement) is now - implemented for Cline via the `snapshot.messages` transcript scan. -- No `.cline/skills/` dogfooding symlinks: Cline's skill registry is - last-wins with plugin dirs scanned *after* workspace dirs, so an installed - slow-powers plugin would silently shadow the repo's skills. The - installed-vs-repo precedence question is deferred to a separate - cross-harness exploration (it affects all harnesses). - -## Learnings - -- Cline plugins load only in CLI/SDK/Kanban — not VSCode/JetBrains. IDE users - get skills via manual copy into `.cline/skills/` or `~/.cline/skills/`. -- Cline reads `AGENTS.md` natively; no memory-file symlink needed for it. -- **Cline plan-mode flow (verified in CLI 3.0.51 source):** the plan is - presented as a free-form assistant message; the CLI's plan-mode system - prompt and the `switch_to_act_mode` tool description both mandate: present - plan → end turn → user approves in a follow-up message → ONLY THEN call - `switch_to_act_mode` (`lifecycle.completesRun`, then a continuation turn - with "The user approved switching to act mode..."). So - `switch_to_act_mode` is an execution boundary, never a presentation moment. -- **Complete plugin hook surface** (`AgentRuntimeHooks`, binary + SDK agree): - `beforeRun`, `afterRun` (observe), `beforeModel` (rewrite request / stop), - `afterModel` (stop only — and `stop:true` aborts the whole run), - `beforeTool` (skip/input/policy/stop), `afterTool` (result/stop), - `onEvent` (observe only). Nothing fires before streamed assistant text, - so no hook can gate plan presentation. -- Hook contexts pass the tool name on BOTH `tool.name` (first-party shape) and - `toolCall.name` (docs shape) — read `tool?.name ?? toolCall?.name`. The - `beforeTool` context also carries `snapshot.messages` — the full - conversation transcript, usable for detection logic. -- Skill invocation in Cline goes through a `skills` tool with input - `{skill, args}` — match that shape for skill-use detection. -- Headless one-shot sessions (`cline -p "..."`) don't expose - `switch_to_act_mode` and can't drive TTY-only commands (`cline config`); use - interactive sessions for plan-gate verification. -- Cline's local plugin install copies dotfile-free repo content — everything - the plugin needs (`cline/`, `skills/`, `bootstrap.md`) is a normal path, so - this is fine. diff --git a/memory-bank/productContext.md b/memory-bank/productContext.md deleted file mode 100644 index 83bfa2e..0000000 --- a/memory-bank/productContext.md +++ /dev/null @@ -1,26 +0,0 @@ -# Product Context - -## Why this exists - -Coding agents under pressure skip discipline: they present unreviewed plans, -claim success without running tests, thrash on bugs with guess-and-check, and -let new work collide with in-progress branches. Slow-powers exists to put that -discipline back — not by replacing harness features, but by hardening them -(plan-mode gates, skill-enforcement bootstrap, verification loops). - -## How it should work - -- A bootstrap block (`bootstrap.md`) is injected into every session, making - skill use non-negotiable when a skill applies. -- Skills declare prerequisite / next-step gates so the agent follows an - intended sequence (plan → harden → isolate → TDD → verify). -- Harness hooks/plugins supply the deterministic beats a skill can't enforce - on its own (e.g. gating plan presentation on hardening-plans). - -## User experience goals - -- Install once per harness, then forget it — the value shows up as plans that - don't hallucinate files, tests that exist before code, and success claims - backed by command output. -- "The plugin for people who don't install plugins": minimal surface, no - config, no lock-in; users can extend with their own evaluated skills. diff --git a/memory-bank/progress.md b/memory-bank/progress.md deleted file mode 100644 index fa3d679..0000000 --- a/memory-bank/progress.md +++ /dev/null @@ -1,49 +0,0 @@ -# Progress - -## What works - -- Eight skills with eval coverage; bootstrap injection and plan gates on - Claude Code, Codex CLI, and OpenCode. -- Full test suite green (`bun test`), typecheck and biome clean. -- **Cline support**: plugin entry, manifest field, unit + manifest tests, - README/AGENTS.md docs, memory bank initialized. Verified live on Cline CLI - 3.0.51: install, skills discovery, and bootstrap rule injection confirmed - in headless sessions. -- **Cline plan-gate timing fixed** (`fix/cline-plan-gate-timing`): first live - test showed the old skip-once hook firing after plan presentation and - approval (Cline's `switch_to_act_mode` is post-approval by design). Now - two-layer: a plan-presentation rule enforces hardening BEFORE presentation - (no Cline hook fires earlier than that), and the hook is the pre-execution - backstop with an already-hardened transcript short-circuit. - -## What's left - -- Commit/PR for `fix/cline-plan-gate-timing`; manual interactive check of the - new two-layer gate (`switch_to_act_mode` is only exposed in interactive - sessions), then release: next version bump carries the Cline plugin. - -## Known issues / deferred - -- Cline plugins don't load on VSCode/JetBrains extensions — IDE users get a - documented skills-only manual install (no bootstrap, no plan gate). -- Cline skill collisions are last-wins with plugin directories scanned after - workspace ones, so an installed slow-powers plugin shadows same-named - workspace skills (the reverse of what this repo wants for development). - Deferred: cross-harness installed-vs-repo precedence exploration. -- Cline pre-presentation enforcement is prompt-level (rule) — Cline exposes no - hook moment before streamed assistant text. The hook backstop guarantees an - un-hardened plan is never executed; if it fires, the user briefly saw an - un-hardened draft before the agent hardens and re-presents. - -## Decision log - -- 2026-08: Cline distribution via root `package.json` + git install (no new - npm package). -- 2026-08: Memory bank committed to git (`.clinerules/memory-bank.md` + - `memory-bank/`). -- 2026-08: No `.cline/skills/` symlinks (option (c)) pending the precedence - exploration. -- 2026-08: Cline plan gate re-anchored to a two-layer design (rule - pre-presentation + hook pre-execution backstop) after the first live test - showed `switch_to_act_mode` fires post-approval in Cline; the deferred - already-hardened short-circuit implemented via `snapshot.messages` scan. diff --git a/memory-bank/projectbrief.md b/memory-bank/projectbrief.md deleted file mode 100644 index a84d3e8..0000000 --- a/memory-bank/projectbrief.md +++ /dev/null @@ -1,25 +0,0 @@ -# Project Brief - -Slow-powers is an agent skill set for professional software development. It -enhances plan mode and debugging work, enforces best practices (TDD, -verification, workspace isolation), and works *with* the features of modern -agent harnesses instead of replacing them. It is a fork of -[obra/superpowers](https://github.com/obra/superpowers), with rewrites focused -on clarity, token efficiency, and a lighter touch. - -## Core goals - -- Ship discipline-enforcing skills (plan hardening, TDD, scientific debugging, - verification, isolated workspaces) that measurably improve agent behavior — - every skill ships with a documented eval or it doesn't ship. -- Support multiple agent harnesses from one repo: Claude Code, OpenAI Codex, - OpenCode, and Cline. -- Keep skill content cross-harness compatible (no harness-specific vocabulary - in skill prose). - -## Scope - -- `skills/` holds the shared skills and their evals. -- Harness-specific integration (manifests, hooks, runtime plugins) lives in - top-level directories; skill content itself stays harness-agnostic. -- This repo is the source of truth; installed plugins are downstream copies. diff --git a/memory-bank/systemPatterns.md b/memory-bank/systemPatterns.md deleted file mode 100644 index 1c645ae..0000000 --- a/memory-bank/systemPatterns.md +++ /dev/null @@ -1,48 +0,0 @@ -# System Patterns - -## Flat layout, one source of truth - -Skills and shared assets live at the repo root; each harness's integration is -a thin top-level layer that points back at them. Nothing is duplicated per -harness. - -## Per-harness delivery of the same two behaviors - -Every harness delivers (1) the `bootstrap.md` skill-enforcement block and -(2) a deterministic plan-presentation gate, using that harness's native -mechanism: - -| Harness | Bootstrap delivery | Plan gate | -| -------- | -------------------------------------- | ------------------------------------------------ | -| Claude | `hooks/session-start` (SessionStart) | `hooks/exit-plan-mode` (PreToolUse, deny-once) | -| Codex | shared `hooks/hooks.json` SessionStart | `hooks/codex-stop-plan-mode` (Stop hook) | -| OpenCode | `opencode/plugins/slow-powers.js` system-prompt transform | same plugin, `file.edited` event on plan files | -| Cline | `cline/plugins/slow-powers.js` `registerRule` (bootstrap + plan-presentation rules) | same plugin, `beforeTool` on `switch_to_act_mode` — pre-execution backstop: transcript short-circuit when hardening-plans already ran, else skip-once | - -Claude/Codex hooks are extensionless bash scripts dispatched by the -`hooks/run-hook.cmd` polyglot (Windows-safe). OpenCode/Cline integrations are -dependency-free JS runtime plugins. - -## Manifest and version lockstep - -`scripts/manifest-files.ts` lists every versioned manifest; -`scripts/bump-version.ts` rewrites them in lockstep (then biome-formats); -`tests/harness/manifests.test.ts` asserts parity. The Cline and OpenCode -integrations both declare themselves inside the root `package.json`, which is -already locked. - -## Parameterized parity tests - -`tests/harness/spec.ts` holds one `HarnessSpec` per harness; the suite in -`manifests.test.ts` applies the same contract to all of them. Adding a -harness = adding a spec entry (+ custom assertions when the manifest shape -doesn't fit the dotted-string `pathFields` machinery, as with Cline's nested -`cline.plugins[].paths[]`). - -## Skill integrity tests - -The shared-assets block in `manifests.test.ts` pins: SKILL.md frontmatter -(name + description), top-level-only skill folders, documented peer -directories (`assets`/`evals`/`references`/`scripts`), resolvable markdown -links, reachable reference files, mermaid-not-graphviz, and the bootstrap -marker. diff --git a/memory-bank/techContext.md b/memory-bank/techContext.md deleted file mode 100644 index ad3b0c4..0000000 --- a/memory-bank/techContext.md +++ /dev/null @@ -1,30 +0,0 @@ -# Tech Context - -## Stack - -- **bun** — test runner and script runtime (`bun test`, `bun scripts/*.ts`) -- **biome** — lint + format (`bun run check`, `check:ci`); JSON included -- **typescript** — `tsc --noEmit` over `scripts/**/*.ts` and `tests/**/*.ts` - only (runtime plugins and hooks are plain JS/bash, deliberately) -- **husky + lint-staged** — pre-commit typecheck/lint, pre-push test suite - (installed by `bun install` via the `prepare` script) -- **eval-magic** — skill evaluation harness (`bun run evals*` scripts); - eval fixtures live under `skills//evals/` - -## Release flow - -Releases cut from `dev`, tagged from `main`. The Release PR workflow bumps -every manifest via `scripts/bump-version.ts`; merging to `main` tags, creates -the GitHub release, and publishes `@slowdini/slow-powers-opencode` to npm. - -## Constraints - -- Hook scripts: pure bash, no jq/python/bun at hook time; printf-based JSON - (heredocs hang on bash 5.3+); extensionless filenames (Windows). -- Cline single-file plugins may import only Node builtins; `@cline/*` - packages are host-provided. -- Skill prose must use cross-harness vocabulary (see `writing-skills`). - -## Local environment - -- Cline CLI 3.0.51 (homebrew) used for live verification of the Cline plugin.