Squid: An Opinionated Software Factory for Claude Code

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 <feature-spec> 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 <task> (the same SWE ↔ Tester loop, no planning or review pipeline). Starting from an empty repo? Run /squid-scaffold first — it interviews you about the stack and writes a tailored AGENTS.md plus a folder skeleton (no application source).

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 — and 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.)

Commit this into the target repo's .claude/settings.json:

{
  "extraKnownMarketplaces": {
    "iusztinpaul": {
      "source": {
        "source": "github",
        "repo": "iusztinpaul/squid"
      }
    }
  },
  "enabledPlugins": {
    "squid@iusztinpaul": true
  }
}

When a teammate (or future-you on a fresh machine) opens that repo and trusts the folder, Claude Code prompts them to add the marketplace and install in one step. enabledPlugins alone isn't enough — extraKnownMarketplaces is what tells Claude Code where squid@iusztinpaul resolves to.

claude --plugin-dir /path/to/squid

Launches Claude Code with the plugin loaded for the session. No marketplace, no install, no cache. Re-run after edits. This is the only path that exercises your local working tree directly on Claude Code v2.1+.

/plugin marketplace add /path/to/squid reads the local marketplace.json but the plugin's source points at GitHub — so the install still fetches from iusztinpaul/squid, not your working tree.

Not on Claude Code, or only want Squid's skills without the full plugin? Use the cross-agent skills CLI:

npx skills add iusztinpaul/squid

It scans the repo for SKILL.md files and installs them into whichever agents it detects (Claude Code, Cursor, Codex, and 70+ more). Add -g to install into your user directory instead of the current project, or --skill <name> to grab specific ones:

npx skills add iusztinpaul/squid --skill squid-plan --skill squid-implement-task -g

Manage them with npx skills list, npx skills update, and npx skills remove <name>.

Skills only. This installs the /squid-plan, /squid-implement-task, … skills but not Squid's five sub-agents (PA, SWE, Tester, PR-Reviewer, On-Call) or the bundled MCP plugins. The pipeline skills invoke those agents, so the full flow only works through the /plugin install path above — reach for npx skills when you want individual skills inside another agent.

/plugin uninstall squid@iusztinpaul

To also forget the marketplace (stops it checking for updates):

/plugin marketplace remove iusztinpaul

Installed via npx skills instead? Remove those with npx skills remove <name> (add --global if you used -g, or --all to clear everything).

Skills & commands

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/<component>/ 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, n