{ "markdown": "

\n \"Claude\n \"Apache\n \"v2.3\n

\n\n

Just Keep Swimming

\n\n

\n A scrum master for Claude Code. It runs your multi-phase plan with parallel dev agents, reviews every phase before merging, ships as it goes, and keeps one live board so any session can pick the work back up from two file reads.\n
\n Landing Page · Thinking Protocol · Why JKS?\n

\n\n---\n\n## The problem\n\nBig plans go badly for AI agents in a predictable way. The agent executes phases one at a time even when they're independent. It spends its own context reading source files until the important early decisions get compressed into mush. When the session dies, the next one starts by re-reading a pile of handoff notes that grows every day. You come back in the morning to find it stalled on phase 2 of 9, asking a question it already answered.\n\nVersion 1 of this plugin treated the symptom: write everything down before you forget. Version 2 treats the cause. The orchestrator stops doing the work that burns its context in the first place.\n\n## Quick start\n\n```bash\n# Plugin install (recommended)\n/plugin marketplace add cyber-qais/justkeepswimming\n/plugin install justkeepswimming\n\n# Or manual install\nmkdir -p ~/.claude/commands/justkeepswimming\ncp commands/justkeepswimming/*.md ~/.claude/commands/justkeepswimming/\n```\n\nThen:\n```\n/justkeepswimming:go my-feature\n```\n\nComing back later? Run it with no arguments. It prints a status line for every plan and resumes the most recent active one.\n\n---\n\n## How v2 works: the scrum master model\n\n```\nPLAN.md -> sprint plan -> dispatch devs (parallel) -> review gate -> merge window -> ship\n ^ | (dispatch NEXT sprint\n +-------------- BOARD.md update <------------+ BEFORE integrating.\n The door stays open.)\n```\n\nThe orchestrator never reads implementation files. Parallel dev agents own disjoint sets of files and report back in 25 lines or less. One session can supervise ten phases this way instead of executing two.\n\nState lives on a single live BOARD.md, updated at every sync point. Resume means two file reads: the plan and the board. It doesn't matter how many sessions came before.\n\nThe door stays open. Each plan gets one worktree or branch, kept alive across sprints and across sessions. Merge windows integrate and deploy finished phases while later phases are still being built. There's no per-phase workspace churn and no big-bang merge at the end.\n\nEvery phase passes an adversarial review gate before it merges. When a reviewer finds real bugs, the findings go back to the same dev agent that wrote the code, because its context is warm and cached. A fresh agent would start by re-reading the world.\n\nAnd the board is audited, not trusted. A zero-dependency script checks its claims against git itself.\n\n## Two commands\n\n### `/justkeepswimming:go`\n\n| What it does | How |\n|---|---|\n| Picks up where you left off | Bare invocation: status table of every plan, then auto-resume the most recent active one |\n| Creates plans | From scratch, from the current conversation (`--from-context`), or imported. Every phase carries acceptance criteria and dependencies |\n| Executes in lanes | Lite lane for half-day jobs, solo lane for small serial plans, scrum lane with parallel agents for everything bigger |\n| Reviews before merging | An adversarial review gate per phase. Two failed rounds and the phase is parked on the board instead of looped forever |\n| Ships continuously | Merge windows integrate and deploy green phases while agents keep working |\n| Survives any session end | The board is always current; a crash loses one sprint at most |\n| Maintains delivered work | Structured post-delivery debugging with maintenance logs |\n\n### `/justkeepswimming:night-build`\n\nAn unattended end-of-day sweep. It reads your CLAUDE.md, baselines against the last night build, fans out parallel reviewers (correctness, conventions, security, wiring gaps) over the day's commits, applies the fixes it's confident about, defers the rest with file and line references, runs your tests, deploys through your project's own release path, and leaves a summary you can read over coffee. A day with no commits produces a one-line report and exits. That counts as success.\n\n---\n\n## Flags\n\n```\n/justkeepswimming:go [plan-name|status] [flags]\n```\n\n| Argument | Effect |\n|:-----|:-------|\n| *(nothing)* | Status table of every plan, then auto-resume the most recent active one |\n| `status` | Status table only. No resume, no dispatch |\n| `` | Autonomous mode on that plan: execute continuously, board stays current |\n| `--lite` | Half-day lane: one LITE.md, inline execution, one review gate at the end |\n| `--solo` | Force inline execution, no agent orchestration |\n| `--interactive` | Pause at sprint boundaries for review |\n| `--from-context` | Build the plan from the current conversation |\n| `--now` | `--from-context` plus skip every confirmation |\n\n---\n\n## The board\n\n```markdown\n# Board — API Migration\n\n**Updated**: 2026-03-13 22:41 · **Door**: wt-api-migration (open)\n**Progress**: 4/6 phases merged · **Shipped**: abc1234\n\n## Status\n| Phase | State | Agent | Files | Commit |\n|---|---|---|---|---|\n| 3. Auth middleware | merged | Dev-3 | middleware/auth.js | e19af02 |\n| 5. Rate limiting | review | Dev-5 | services/rateLimiter.js | — |\n\n## Decisions (settled)\n- 2026-03-12: merge convention: FF to main; deploy: npm run deploy; checks: npm test\n\n## Learnings (cumulative)\n- Redis cache uses `user:{id}:session` key scheme (TTL 30min)\n- Rate limiter must exempt /health — `services/rateLimiter.js:88`\n```\n\nEvery learning, decision, and file reference lives in one document that is always current.\n\nSelf-reported state drifts, so the board gets audited. `scripts/board-check.js` ships with the plugin and verifies every claim against git: merged phases must point at commits that exist and are actually on the integration branch, the progress count must match the table, the ship SHA must be on origin, and an \"open\" door must appear in `git worktree list`. It runs at resume, after every merge window, and before completion.\n\n```\n$ node scripts/board-check.js api-migration\n ❌ FAIL: \"Phase 3\": commit 9f3ab12 is NOT on main — state says merged\n ✖ 1 failure(s) — the board does not match git truth.\n```\n\nWhen that happens, the agent fixes the board from git evidence before it dispatches anything else.\n\n## The tier doctrine\n\nEvery model goes where it earns its cost. The strongest available model orchestrates and is never downgraded and never allowed to keep judging after compaction. Dev agents run one tier down; their depth comes from focus (one phase, owned files), not from raw model size. Rote lanes like renames and boilerplate go two tiers down at low effort. Review gates run at high effort, and the riskiest surfaces (security, data loss, auth) get reviewed by the orchestrator's own model.\n\nAs of the Claude 5 family that maps to: Fable orchestrates, Opus develops, Sonnet and Haiku take the rote lanes.\n\n## Fresh sessions beat compaction\n\nHarness compaction keeps a session alive, but it silently blurs the things a scrum master exists to hold: decisions, ownership boundaries, verdicts. So v2 works in shifts. A session runs sprints until it reaches a clean boundary (batch integrated, board current) while it's still sharp, then ends on purpose. The next session resumes from two reads with full acuity. Waiting for a compression signal is already too late, and the skill says so explicitly.\n\n## The token economy\n\n| Rule | Practice |\n|:---|:---|\n| Delegate the noise | The orchestrator never reads implementation files; agents return short structured reports |\n| One-read resume | BOARD.md is the only state file. The handoff pile is gone |\n| Cache alignment | Front-load reads, batch tool calls, keep orchestrator turns short and stable |\n| Reuse warm agents | Fixes go to the agent that wrote the code, not a fresh spawn |\n| Tier doctrine | Strongest model orchestrates, one tier down develops, rote lanes go two tiers down |\n| Kill rework | Acceptance criteria travel in every dispatch; review gates run before every merge |\n| Fresh sessions | Shifts end at board boundaries; resume costs two reads |\n\n---\n\n## Post-delivery maintenance\n\nPlan complete? The skill stays useful. When bugs surface later:\n\n```\n/justkeepswimming:go my-feature\n> \"That plan is complete. Maintenance mode?\"\n```\n\nIt restores context from SUMMARY.md, applies the Thinking Protocol to the investigation, fixes the root cause only, and writes a maintenance log with the steps, changes, and verification. If the request turns out to be bigger than a targeted fix, it says so and offers a follow-up plan instead of forcing a refactor through a bug-fix workflow.\n\n## The Thinking Protocol\n\nMost agents pattern-match to common fixes and try them one at a time until something sticks. The Thinking Protocol replaces guessing with verification:\n\n| # | Principle |\n|:-:|:----------|\n| 1 | Diagnose before you prescribe |\n| 2 | Trace the full chain |\n| 3 | Check what's actually there, not what you expect |\n| 4 | Know the silent failures |\n| 5 | Minimum effective intervention |\n| 6 | Resist \"the usual fix\" |\n\nThe meta-rule: every condition required for success must be verified, and the one you skip is the one that's broken. v2 adds the Orchestrator's Corollary for scrum-lane work: delegate the noise, keep the signal. Details in [`THINKING.md`](THINKING.md), which you can extend with your own team's debugging lessons.\n\n---\n\n## Directory structure\n\n```\nyour-project/\n└── docs/justkeepswimming/\n ├── api-migration/\n │ ├── PLAN.md # Phases + acceptance criteria + dependencies\n │ ├── BOARD.md # Live state, always current, git-audited\n │ ├── SUMMARY.md # Architecture overview + next steps\n │ ├── 2026-03-15-maintenance-001.md # Post-delivery fix log\n │ └── archive/ # Legacy handoffs, review scratch\n ├── fix-invoice-rounding/\n │ └── LITE.md # Half-day job: goal, checklist, outcome\n └── night-build/\n └── 2026-03-14-night-build.md # Build report\n```\n\nPlain markdown plus one small script. Commit them, branch them, `git blame` them.\n\n## Comparison\n\n| | Just Keep Swimming | Heavy workflow systems |\n|:---|:---|:---|\n| Files | 2 commands, 1 methodology doc, 1 audit script | 30+ files with state tracking |\n| State | One live board per plan, verified against git | STATE.md, ROADMAP.md, CONTEXT.md, ... |\n| Concepts | Plan, Board, Sprint, Merge window | Projects, Milestones, Phases, Waves, Audits |\n| Parallelism | File-ownership lanes, review gates, one git owner | Usually none, or unmanaged |\n| Setup | Install the plugin or copy two files | Plugin plus configuration plus a learning curve |\n\n## Dependencies\n\nClaude Code, any recent version. Subagent support (the Agent tool) unlocks the scrum lane; without it the solo and lite lanes still work everywhere. The optional superpowers plugin adds auto-generated plans via `superpowers:writing-plans`, but you can bring your own plan or use `--from-context`.\n\n---\n\n## FAQ\n\n
\nWhat happened to handoff documents?\nThe live board replaced them. v1 plans with handoff piles migrate automatically: the first v2 session synthesizes BOARD.md from them once, archives the pile, and never reads it again. Resume is two file reads from then on.\n
\n\n
\nDo parallel agents conflict with each other?\nNo. Each phase owns a disjoint set of files, shared registries are edited only by the orchestrator at merge windows, and only the orchestrator runs git. Conflicts are prevented structurally rather than resolved after the fact.\n
\n\n
\nWhat stops the board from lying?\nscripts/board-check.js. It verifies commit existence and branch ancestry for every merged phase, the progress count, the ship SHA, and the door state against git worktree list. A failing check blocks dispatch until the board matches git.\n
\n\n
\nCan I use this without subagent support?\nYes. The solo lane executes inline with the same board, review discipline, and completion flow. --solo forces it, and --lite covers half-day jobs with even less ceremony.\n
\n\n
\nWhat happens when the plan is complete?\nA completeness critic hunts for gaps first: unmet acceptance criteria, unwired registrations, missing tests or docs. Then SUMMARY.md, a cleaned folder, the worktree closed out, and an offer to turn the recommendations into a follow-up plan.\n
\n\n
\nCan I have multiple active plans?\nYes. Each plan has its own directory, board, and open door. Bare go shows all of them and resumes the most recently active; name a plan to switch.\n
\n\n---\n\n

\n Apache 2.0 · Made by Qais Alkurdi\n

\n", "bytes": 14076, "sha": "e76ed77dbd5002d61c026e8600abd295dfe911b62b23bbe59bb9a1b11511af91", "repo_slug": "cyber-qais/justkeepswimming", "fonte": "repo", "truncated": false, "api": "https://agentalog.com/api/listings/plg_cyber_qais_justkeepswimming_just_keep_sw_c63073f8/readme" }