finn-loop

Finn-loop

Three Claude Code skills that turn Linear + GitHub into a small, human-gated AI software factory:

idea → /finn-spec interviews you and files the issue → you label it agent-ready → /finn-build claims it and opens a PR → /finn-review posts a verdict → you merge.

Three skills, one approval label, one rule: humans merge.

• skills/finn-spec — researches the repo, interviews you until the behavior is unambiguous, then files a Linear issue with acceptance criteria (AC-N) and non-goals (NG-N).
• skills/finn-build — claims the next safe agent-ready issue, implements only its contract, verifies it, and opens a PR. Runs repeatedly with /loop /finn-build.
• skills/finn-review — reviews open PRs against their linked issue and required GitHub checks, then posts a three-group verdict. Runs repeatedly with /loop /finn-review.

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

Requirements

• A Git repository hosted on GitHub, with a working origin remote
• Claude Code 2.1.71 or newer (/loop was added in that release)
• A Linear workspace and team
• The Linear connector enabled in Claude Code
• The GitHub CLI (gh) authenticated with write access to the target repo
• At least one required GitHub status check if you want fully automated loop-approved verdicts; without required CI, Finn-loop escalates the PR for human review

Recommended: connect Linear's GitHub integration so linked PRs can update issue status when they open and merge.

Install

Paste this into Claude Code inside the repo where you want the factory:

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.

Daily rhythm (~15 minutes)

1. Run /finn-spec whenever an idea hits you. Read the filed issue; if you approve the exact contract, apply agent-ready in Linear. Only a human applies that label.
2. Start /loop /finn-build. If you want reviews to happen continuously, run /loop /finn-review in a second session.
3. Merge only PRs that are loop-approved, conflict-free, and green on all required checks. A needs-human-review PR requires you to read and resolve the reason for escalation before merging.
4. Answer concrete questions on blocked Linear issues, then remove the blocked label so a future build pass can resume them.

Run only one builder loop per Linear team. The Linear assignee is a cooperative lock between people, but two simultaneous sessions authenticated as the same person cannot reliably lock each other. Use separate clean worktrees if you intentionally operate on more than one repository task at once.

What loop-approved means

loop-approved means the reviewer found no must-fix issue against the Linear contract, all required GitHub checks passed, and the PR was not conflicting at the reviewed commit. 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.

The rules that make it work

• If it is not in the Linear issue, it does not exist. No side-channel instructions.
• One issue per PR, sized to a day of agent work or less.
• Acceptance criteria are observable outcomes; non-goals are binding. A PR comment or review cannot expand scope — only editing the Linear issue can.
• Blocked issues and human-escalated PRs leave the automated queue until a human resolves them.
• Spec quality is the bottleneck. Vague acceptance criteria produce confident wrong PRs; let /finn-spec ask as many questions as it needs.
• Agents never merge or enable auto-merge.

/loop runs only while its Claude Code session remains open. Watch the first few passes and your usage before leaving a new installation unattended.

From the starter loop to a full software factory

Finn-loop deliberately ships the smallest useful version: spec, build, review, and a human merge. The larger factory that inspired this repository added the layers below only after that core loop was stable.

These are architecture patterns and next steps, not features bundled in this repository. Add them one at a time. Keep Linear and GitHub as the durable sources of truth; use Slack and other interfaces as control surfaces, never as shadow state.

1. Make build and review self-converging

In the starter, /finn-build and /finn-review can run independently. The next step is to have the builder open its PR and then launch a fresh reviewer with clean context. Do not let the builder review its own work from the same conversation.

A proven convergence policy is:

1. The builder opens one PR for one Linear issue.
2. A fresh reviewer checks the exact head commit against the issue and required CI.
3. If the verdict is loop-changes-requested, the builder fixes only the must-fix findings.
4. A new fresh reviewer checks the new head commit.
5. After two failed fix rounds, label the PR loop-stuck and stop for a human.

The retry cap matters. An agent should not argue with a reviewer forever or silently broaden the Linear contract to make a test pass.

2. Use Slack as a human control plane

Slack becomes useful when it removes trips to Linear and GitHub without replacing either one.

A safe Slack integration needs more than a webhook that calls merge:

• Verify Slack and GitHub webhook signatures before processing an event.
• Allow only explicitly configured founder Slack user IDs to approve an action.
• Store event IDs, message timestamps, PR numbers, and reviewed head SHAs so duplicate deliveries are harmless.
• Claim a post or reaction in durable storage before making an external call.
• Re-read Linear or GitHub at action time. Never trust an old Slack message as proof that an issue is still blocked or a PR is still merge-ready.
• Mark old merge messages as superseded when the PR head changes.
• Retry transient failures, but repeat the live safety checks before every retry.
• Provide environment-level kill switches for automated posting and merging.

The useful division of responsibility is:

• Linear: what should be built and whether an issue is ready or blocked.
• GitHub: the code, review commit, CI, conflicts, and merge state.
• Slack: human-facing questions, approvals, and alerts.
• The repository: how the factory behaves—skills, templates, and policy.

3. Add risk-aware merge policy carefully

The public starter's rule is intentionally simple: agents never merge. In a more mature factory, automation can execute a narrowly pre-authorized merge, but only after the team explicitly changes that governance rule.

A conservative policy has three lanes:

• Human merge: application code and anything involving schema, auth, permissions, billing, deployment, or provisioning.
• Founder-authorized merge: a founder's 🚀 reaction authorizes one exact PR head; the system re-verifies labels, CI, conflicts, and SHA before merging.
• Safe auto-merge: an opt-in allowlist such as docs and tests, plus an explicit override label and a global kill switch. Never infer safety merely from a small diff.

Keep a needs-human-review label for sensitive paths and a safe-auto-merge label for deliberate exceptions. A PR that changes after approval must earn approval again.

4. Use Linear relations for multi-part features

Large features should become a chain of one-day issues, connected with Linear's blocked-by relations. All parts may be approved up front, but the queue should hide a downstream issue until its blocker is Done, and the claim operation should enforce the same rule.

This lets several agents work from a durable plan without allowing part three