Finn-loop: three Claude Code skills that turn Linear and GitHub into a human-gated factory

What Finn-loop is

Finn-loop is three Claude Code skills wired to Linear and GitHub. The README describes the path in one line: an idea goes into the spec skill, which interviews you and files the issue, you label it agent-ready, the build skill claims it and opens a pull request, the review skill posts a verdict, and you merge.

Each skill has a narrow job. finn-spec researches the repository, interviews you until the behaviour is unambiguous, then files a Linear issue with acceptance criteria written as AC-N and non-goals written as NG-N. finn-build claims the next safe agent-ready issue, implements only its contract, verifies it, and opens a pull request, and it is designed to run repeatedly. finn-review checks open pull requests against their linked issue and the required GitHub checks, then posts a verdict in three groups.

The naming is deliberate. The finn- prefix avoids collisions with Claude Code's bundled commands and with generic personal skills such as review or build.

What you need before installing

The requirements list is short but strict, and it is the thing most people will trip on:

- A Git repository hosted on GitHub with a working origin remote - Claude Code 2.1.71 or newer, because the loop command was added in that release - A Linear workspace and team - The Linear connector enabled in Claude Code - The GitHub CLI authenticated with write access to the target repository - At least one required GitHub status check if you want fully automated approved verdicts

That last one matters. Without required CI, Finn-loop escalates the pull request for human review instead of posting an automated verdict. Connecting Linear's GitHub integration is recommended but not required, so linked pull requests can update issue status when they open and merge.

The repository itself is small: a skills directory, a scripts directory, a licence and the README. There is no runtime to deploy.

Installing it, and what the setup actually does

Installation is a prompt you paste into Claude Code inside the repository where you want the factory to run. It is worth reading rather than pasting blindly, because it does more than copy files:

Set up Finn-loop from https://github.com/finna/Finn-loop.

1. Copy these files from that repo into this repo, preserving their contents:
   skills/finn-spec/SKILL.md   → .claude/skills/finn-spec/SKILL.md
   skills/finn-build/SKILL.md  → .claude/skills/finn-build/SKILL.md
   skills/finn-review/SKILL.md → .claude/skills/finn-review/SKILL.md

2. Ask for my Linear team key (for example ENG), then replace every TEAM
   placeholder in the copied skills with that exact key.

3. Check `claude --version` is 2.1.71 or newer. Check that the Linear
   connector is available and can list the chosen team's labels and workflow
   states. If it is unavailable, tell me to connect it and wait.

4. Check `gh auth status` and `gh repo view` both work. Detect the repository's
   real default branch; do not assume it is main. Confirm the authenticated
   account can push to this repository.

5. Create missing labels idempotently:
   - Linear: agent-ready, blocked
   - GitHub: loop-approved, loop-changes-requested, needs-human-review
   Do not fail if a label already exists.

6. Confirm the Linear team has a workflow state of type "started". Finn-loop
   will prefer a state named "In Progress" but can use any started state. A
   separate review state is optional.

7. Recommend enabling Linear's GitHub integration if it is not already
   connected. Explain that without it, Finn-loop can post the PR link but a
   merge may not automatically move the Linear issue to Done.

8. Validate that all three copied SKILL.md files have valid YAML frontmatter.
   Tell me to run `/reload-skills` (or restart Claude Code), then have me
   confirm `/skills` lists finn-spec, finn-build, and finn-review.

9. Smoke test by listing:
   - unassigned Linear issues labeled agent-ready but not blocked
   - the target repo's default branch and required GitHub checks
   - open pull requests and their Finn-loop labels
   All reads succeeding and all three skills appearing in `/skills` means the
   installation is ready. Then tell me how to run my first spec and loop.

Two details in there are easy to miss and worth keeping. The setup detects the real default branch instead of assuming main, and it finishes with a read-only smoke test rather than a first write.

The daily rhythm

The README bills the routine at roughly fifteen minutes a day. You run the spec skill whenever an idea appears, read the filed issue, and if you approve the exact contract you apply the agent-ready label in Linear, which only a human does. Then you start the build loop, and optionally the review loop in a second session. You merge only pull requests that carry the approved label, are conflict-free, and are green on every required check, and a needs-human-review pull request requires you to read and resolve the escalation reason first. Finally, you answer concrete questions on blocked issues and remove the blocked label so a later build pass can pick them up.

Concurrency is where people get hurt, and the README is blunt about it. Run only one builder loop per Linear team. The Linear assignee acts as a cooperative lock between people, but two simultaneous sessions authenticated as the same person cannot reliably lock each other, so if you intentionally work more than one repository task at a time, use separate clean worktrees.

What the approved label actually means

This is the section to read before trusting the output. The approved label means the reviewer found no must-fix issue against the Linear contract, all required GitHub checks passed, and the pull request was not conflicting at the reviewed commit. The README then draws the line that makes the whole design make sense: it is evidence for the human merge decision, not permission for an agent to merge.

Finn-loop does not create CI for the target project. The target repository owns its build, test, security and deployment checks, so the quality of the verdict is bounded by the quality of whatever checks already exist there.

The loop command also has a lifetime. It runs only while its Claude Code session remains open, and the README advises watching the first few passes and your usage before leaving a new installation unattended.

The rules that make it work

Six rules carry the design, and they read like things someone learned the hard way:

- If it is not in the Linear issue, it does not exist, with no side-channel instructions - One issue per pull request, sized to a day of agent work or less - Acceptance criteria are observable outcomes, non-goals are binding, and a pull request comment or review cannot expand scope, only editing the Linear issue can - Blocked issues and human-escalated pull requests leave the automated queue until a human resolves them - Spec quality is the bottleneck, because vague acceptance criteria produce confident wrong pull requests, so let the spec skill ask as many questions as it needs - Agents never merge or enable auto-merge

That last rule is the one the repository will not bend on, and it is why the project is described as human-gated rather than autonomous.

What is deliberately not included

The README has a long section on the larger factory that inspired this repository, and it is explicit that these are architecture patterns and next steps rather than bundled features. A table lists six layers: self-converging pull requests where a fresh reviewer checks each builder output and the builder fixes must-fix findings under a fixed retry budget; a Slack control plane for blocked questions and merge-ready notices; risk-aware merging with narrow automatic lanes and sensitive paths always escalating; verification gates that require preview evidence and documentation updates; direction and status skills for planning and reporting; and a factory watchdog that alerts on silent stalls, red CI and unhealthy queues.

Ten numbered sections follow with the operational detail, including a convergence policy that stops after two failed fix rounds and labels the pull request as stuck, and a set of rules for a safe Slack integration: verify webhook signatures, allow only configured founder user IDs, store event identifiers and reviewed head SHAs so duplicate deliveries are harmless, re-read Linear or GitHub at action time rather than trusting an old message, and keep environment-level kill switches for automated posting and merging.

There is also a suggested implementation order of eleven steps, starting with running the three-skill starter for several real pull requests and ending with Slack spec approval, which it calls the most important human gate in the system.

Licence, maturity and how it compares

Finn-loop is MIT licensed. The version in the repository is early and quiet: no published releases, and the last push in view is 2026-07-23. The tree is a README, a skills directory, a scripts directory and a licence, so what you are adopting is a set of instructions for an agent rather than a service.

Compared with a hosted agent coding product, the difference is where state lives. Here Linear holds what should be built and GitHub holds the code, the CI and the merge, and the agent reads and writes both through their own interfaces. There is no separate database to fall out of sync, and no vendor dashboard to learn.

Compared with wiring up generic agent loops yourself, the difference is the gates. The approval label, the blocked label, the escalation path and the refusal to auto-merge are the parts you would otherwise have to invent. The trade is that you inherit Linear and GitHub as hard dependencies, and you accept that a vague issue will produce a confident wrong pull request.

Editorial conclusion

Finn-loop is worth trying if you already run Linear and GitHub and want to see what agent execution looks like without giving an agent the merge button. The value is in the discipline rather than the code: one issue per pull request, observable acceptance criteria, binding non-goals, and a verdict label that is explicitly evidence for a human decision rather than permission to act. It is also honest about its limits, since it ships no CI, needs a required status check to reach automated verdicts, and tells you to watch the first passes before leaving it alone. The prerequisites are the real filter. You need Claude Code 2.1.71 or newer, the Linear connector, an authenticated gh with write access, and a team willing to keep specifications tight, because the README says plainly that spec quality is the bottleneck and vague criteria produce confident wrong pull requests.

Frequently asked questions

Official sources

1. finna/Finn-loop on GitHub
2. Issues
3. License: MIT
4. README