iusztinpaul/squid

Claude Code writes code fast. It’s worse at writing the code your team would actually ship — code that follows your conventions, has tests you trust, and survives review.

Squid is a Claude Code plugin that turns a feature spec into a reviewed PR through a 5-agent pipeline — PA → SWE → Tester → PR Reviewer → On-Call — with exactly two human gates: plan approval and final merge. No file templates, no render step: just markdown specs and agent contracts, and every file in your project gets written by an agent that reads them.

How it works

Run /squid-plan then /squid-implement-night, and Squid drives this end-to-end:

  feature spec
       │
       ▼   /squid-plan
  ┌──────────────────────────────────────────────────────────────┐
  │ grill → PA grooms Tasks Plan (+ADR) → HUMAN approves (1/2)     │
  │ → branch + worktree                                            │
  └──────────────────────────────────────────────────────────────┘
       │   /squid-implement-night  (runs end-to-end in the worktree)
       ▼
  ┌──────────────────────┐    ┌───────────────────┐    ┌─────────────────┐
  │ /squid-implement-task│──▶ │ /squid-review     │──▶ │ /squid-review-ci│
  │ SWE ↔ Tester         │    │ push → PA accept →│    │ On-Call drives  │
  │ commit each task     │    │ PR-Reviewer       │    │ CI to green     │
  └──────────────────────┘    └───────────────────┘    └─────────────────┘
                                                                │
                                                                ▼
                                                    HUMAN squash-merges (2/2)

Branch + worktree, grooming, the per-task implement/verify loop, push, diff review, and CI are all automated — you only show up for the two gates. For a quick single change, run /squid-implement-task (the same SWE ↔ Tester loop, no planning or review pipeline). Starting from an empty repo? Run /squid-scaffold first (see Quick start).

Who this is for

• Yes: solo devs and small teams shipping Python backends, TypeScript frontends, or Go TUIs who want Claude Code to consistently hit your team’s bar without re-explaining conventions every session.
• Maybe not: teams with an established in-house agent pipeline they don’t want to displace, or stacks Squid doesn’t cover yet (Rust, Java, mobile — PRs welcome).

Learn How to Build Agentic Coding Frameworks From Scratch

Join 40k+ engineers subscribed to the Decoding AI Magazine to learn to build agentic coding frameworks like Squid from scratch.

Install

/plugin marketplace add iusztinpaul/squid
/plugin install squid@iusztinpaul

That’s it. Open any repo in Claude Code; the agents and skills appear in /agents and /help. Run /plugin marketplace update iusztinpaul later to pull fresh changes.

Installing Squid also pulls in three plugins the agent team relies on, all from Anthropic’s official claude-plugins-official marketplace — context7 (live library docs via MCP), code-review, and commit-commands. That marketplace ships with Claude Code, so these resolve and enable on their own. (Requires Claude Code v2.1.143+ for auto-enable; v2.1.110+ for the dependency mechanism. If a dependency fails to resolve, run /plugin marketplace update claude-plugins-official.)

Optional companion: caveman

Squid integrates with caveman — an optional plugin that compresses agent output ~75%. It isn’t pulled in automatically (it lives in a different marketplace); install it alongside Squid and the pipeline picks it up:

/plugin marketplace add JuliusBrussee/caveman
/plugin install caveman@caveman

With caveman installed, Squid uses it for:

• Commits — the SWE writes each commit via /caveman-commit (Conventional Commits, ≤50-char subject, why-over-what).
• Reviews — the PR-Reviewer posts one-line findings on the PR in /caveman-review style (L42: bug: user null. add guard.), on top of its usual rollup task.
• Memory compression — /squid-scaffold offers to run /caveman-compress AGENTS.md, so the memory file every session loads is ~46% leaner; /squid-clean-memory chains the same pass with a de-duplication cut.
• Shorter replies — caveman’s SessionStart hook auto-compresses every reply; tune the level with /caveman [lite|full|ultra].

Squid runs fine without it — each integration falls back to its native behavior.

Skills & commands

Which model runs which agent

Squid pins a model per agent, following Anthropic’s advisor pattern — reasoning-heavy roles get the strongest model, and the token-hungry executor roles run one tier down, where most of the spend lands.

Two things worth knowing:

• Fable is for planning, not for coding. It costs $10/$50 per MTok against Opus’s $5/$25 — benchmarks suggest that coding with Fable at high effort buys you roughly what Opus already gives you, for more money. Squid deliberately keeps it off the code-writing path.
• effort: high is a downshift. Claude Code defaults subagents to xhigh. Anthropic’s own guidance is to start Opus 4.8 at high and only raise it, and Sonnet 5 already defaults to high. Drop software-engineer to effort: medium if you want to trade a little headroom for cost.

Overriding. Each value lives in the agent’s frontmatter (agents/*.md), so a fork can just edit it. Note that a CLAUDE_CODE_SUBAGENT_MODEL environment variable silently overrides every agent’s model: — if all five agents seem to be running on one model, that’s why.

The /squid-scaffold spec library (under skills/squid-scaffold/specs/) covers:

• Python: backend layout, uv, pyproject, ruff, FastAPI, FastMCP, CLI tools
• TypeScript frontend: package/tsconfig/vite conventions, React, Vue, Svelte, vanilla
• Go TUI: layout + Bubbletea / tview patterns
• Infra: Docker, docker-compose, GitHub Actions monorepo CI, OpenAPI contracts
• Process: monorepo layout, Makefile delegator, tracker workflow

Several specs are still stubs — the foundations are filled in (python-backend, typescript-frontend, go-tui, uv-python, pyproject, makefile-delegator, monorepo-layout); the rest are good first contributions.

Contributing

Issues and PRs welcome — especially new specs (Rust, Java, mobile, additional Python/TS frameworks) and stub fill-ins. See CONTRIBUTING.md to get started, and CLAUDE.md for the underlying plugin-dev conventions.

Quick start

In an empty directory:

/squid-scaffold

The skill asks what you want to build (components, frameworks, infra, license) and writes:

• AGENTS.md — project brief distilled from the relevant specs; the single source of truth, with CLAUDE.md symlinked to it for Claude Code
• .agents/skills/ — canonical home for project-local skills, with .claude/skills symlinked to it
• Skeleton packages// directories with placeholder Makefiles and component-level AGENTS.mds (each with its own CLAUDE.md symlink)
• Root Makefile, .env.example, .gitignore
• Optional: docker-compose.yml, .github/workflows/, tasks/

It does not write application source. That’s the next step:

/squid-implement-task "Bootstrap packages/backend with a FastAPI /health endpoint and one unit test."

The SWE agent reads AGENTS.md, picks up the specs it references, writes real code + tests, hands off to the Tester, and commits the task once it passes.

Philosophy

• Specs over templates. Opinions live as markdown the agent reads — no Jinja, no render step, no drift between a template and what the agent produces.
• Progressive disclosure. A session loads only the skills whose descriptions match the task; the spec library is gated behind /squid-scaffold so it doesn’t pollute every session’s index.
• One skill per concern. Adding a new stack is one markdown file, not a new scaffolding engine.
• AGENTS.md is the brief. After /squid-scaffold, the generated AGENTS.md is the single source of truth for how that project builds. Specs are referenced, not transcluded.
• Agents are gates. The PA catches scope drift and signs off from the user’s perspective; the Tester catches false-confidence “tests pass” claims and runs an e2e adversarial pass; the PR Reviewer catches dead/duplicate/untested code, over-engineering, and hot-path regressions; On-Call catches CI breakage. No agent both writes code and decides whether it’s correct.

License

See LICENSE.