Skip to content
Back to search

Finn-loop

The Finn-loop: a 3-skill AI software factory for Claude Code — spec, build, review. Humans merge.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/finna--finn-loop/badge.svg)](/listings/finna--finn-loop)

HTML

<a href="/listings/finna--finn-loop"><img src="/api/listings/finna--finn-loop/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

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.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 346 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # Finn-loop
  2. Three Claude Code skills that turn Linear + GitHub into a small, human-gated
  3. AI software factory:
  4. **idea → `/finn-spec` interviews you and files the issue → you label it
  5. `agent-ready` → `/finn-build` claims it and opens a PR → `/finn-review` posts
  6. a verdict → you merge.**
  7. Three skills, one approval label, one rule: **humans merge**.
  8. - [`skills/finn-spec`](skills/finn-spec/SKILL.md) — researches the repo,
  9. interviews you until the behavior is unambiguous, then files a Linear issue
  10. with acceptance criteria (`AC-N`) and non-goals (`NG-N`).
  11. - [`skills/finn-build`](skills/finn-build/SKILL.md) — claims the next safe
  12. `agent-ready` issue, implements only its contract, verifies it, and opens a
  13. PR. Runs repeatedly with `/loop /finn-build`.
  14. - [`skills/finn-review`](skills/finn-review/SKILL.md) — reviews open PRs against
  15. their linked issue and required GitHub checks, then posts a three-group
  16. verdict. Runs repeatedly with `/loop /finn-review`.
  17. The `finn-` prefix avoids collisions with Claude Code's bundled commands and
  18. with generic personal skills such as `/review` or `/build`.
  19. ## Requirements
  20. - A Git repository hosted on GitHub, with a working `origin` remote
  21. - [Claude Code](https://code.claude.com/docs/en/overview) 2.1.71 or newer
  22. (`/loop` was added in that release)
  23. - A Linear workspace and team
  24. - The Linear connector enabled in Claude Code
  25. - The GitHub CLI (`gh`) authenticated with write access to the target repo
  26. - At least one required GitHub status check if you want fully automated
  27. `loop-approved` verdicts; without required CI, Finn-loop escalates the PR for
  28. human review
  29. Recommended: connect Linear's
  30. [GitHub integration](https://linear.app/docs/github-integration) so linked PRs
  31. can update issue status when they open and merge.
  32. ## Install
  33. Paste this into Claude Code inside the repo where you want the factory:
  34. ```text
  35. Set up Finn-loop from https://github.com/finna/Finn-loop.
  36. 1. Copy these files from that repo into this repo, preserving their contents:
  37. skills/finn-spec/SKILL.md → .claude/skills/finn-spec/SKILL.md
  38. skills/finn-build/SKILL.md → .claude/skills/finn-build/SKILL.md
  39. skills/finn-review/SKILL.md → .claude/skills/finn-review/SKILL.md
  40. 2. Ask for my Linear team key (for example ENG), then replace every TEAM
  41. placeholder in the copied skills with that exact key.
  42. 3. Check `claude --version` is 2.1.71 or newer. Check that the Linear
  43. connector is available and can list the chosen team's labels and workflow
  44. states. If it is unavailable, tell me to connect it and wait.
  45. 4. Check `gh auth status` and `gh repo view` both work. Detect the repository's
  46. real default branch; do not assume it is main. Confirm the authenticated
  47. account can push to this repository.
  48. 5. Create missing labels idempotently:
  49. - Linear: agent-ready, blocked
  50. - GitHub: loop-approved, loop-changes-requested, needs-human-review
  51. Do not fail if a label already exists.
  52. 6. Confirm the Linear team has a workflow state of type "started". Finn-loop
  53. will prefer a state named "In Progress" but can use any started state. A
  54. separate review state is optional.
  55. 7. Recommend enabling Linear's GitHub integration if it is not already
  56. connected. Explain that without it, Finn-loop can post the PR link but a
  57. merge may not automatically move the Linear issue to Done.
  58. 8. Validate that all three copied SKILL.md files have valid YAML frontmatter.
  59. Tell me to run `/reload-skills` (or restart Claude Code), then have me
  60. confirm `/skills` lists finn-spec, finn-build, and finn-review.
  61. 9. Smoke test by listing:
  62. - unassigned Linear issues labeled agent-ready but not blocked
  63. - the target repo's default branch and required GitHub checks
  64. - open pull requests and their Finn-loop labels
  65. All reads succeeding and all three skills appearing in `/skills` means the
  66. installation is ready. Then tell me how to run my first spec and loop.
  67. ```
  68. ## Daily rhythm (~15 minutes)
  69. 1. Run `/finn-spec` whenever an idea hits you. Read the filed issue; if you
  70. approve the exact contract, apply `agent-ready` in Linear. Only a human
  71. applies that label.
  72. 2. Start `/loop /finn-build`. If you want reviews to happen continuously, run
  73. `/loop /finn-review` in a second session.
  74. 3. Merge only PRs that are `loop-approved`, conflict-free, and green on all
  75. required checks. A `needs-human-review` PR requires you to read and resolve
  76. the reason for escalation before merging.
  77. 4. Answer concrete questions on `blocked` Linear issues, then remove the
  78. `blocked` label so a future build pass can resume them.
  79. Run only one builder loop per Linear team. The Linear assignee is a cooperative
  80. lock between people, but two simultaneous sessions authenticated as the same
  81. person cannot reliably lock each other. Use separate clean worktrees if you
  82. intentionally operate on more than one repository task at once.
  83. ## What `loop-approved` means
  84. `loop-approved` means the reviewer found no must-fix issue against the Linear
  85. contract, all required GitHub checks passed, and the PR was not conflicting at
  86. the reviewed commit. It is evidence for the human merge decision, not
  87. permission for an agent to merge.
  88. Finn-loop does not create CI for the target project. The target repository owns
  89. its build, test, security, and deployment checks.
  90. ## The rules that make it work
  91. - If it is not in the Linear issue, it does not exist. No side-channel
  92. instructions.
  93. - One issue per PR, sized to a day of agent work or less.
  94. - Acceptance criteria are observable outcomes; non-goals are binding. A PR
  95. comment or review cannot expand scope — only editing the Linear issue can.
  96. - Blocked issues and human-escalated PRs leave the automated queue until a
  97. human resolves them.
  98. - Spec quality is the bottleneck. Vague acceptance criteria produce confident
  99. wrong PRs; let `/finn-spec` ask as many questions as it needs.
  100. - Agents never merge or enable auto-merge.
  101. `/loop` runs only while its Claude Code session remains open. Watch the first
  102. few passes and your usage before leaving a new installation unattended.
  103. ## From the starter loop to a full software factory
  104. Finn-loop deliberately ships the smallest useful version: spec, build, review,
  105. and a human merge. The larger factory that inspired this repository added the
  106. layers below only after that core loop was stable.
  107. These are **architecture patterns and next steps**, not features bundled in
  108. this repository. Add them one at a time. Keep Linear and GitHub as the durable
  109. sources of truth; use Slack and other interfaces as control surfaces, never as
  110. shadow state.
  111. | Layer | What it adds | Human boundary |
  112. | --- | --- | --- |
  113. | Self-converging PRs | A fresh reviewer checks each builder PR and the builder fixes must-fix findings | Stop after a small, fixed retry budget |
  114. | Slack control plane | Blocked questions and merge-ready PRs reach founders where they already work | Slack actions are accepted only from approved users and rechecked against live state |
  115. | Risk-aware merging | Narrow safe changes can merge automatically; sensitive changes always escalate | Policy decides what is reversible and safe |
  116. | Verification gates | UI changes are tested on a real preview and behavior changes update architecture docs | Founders remain the final taste and risk check |
  117. | Direction and status | A morning planner replenishes the queue and a read-only status skill returns the exact action list | A founder approves the work packet |
  118. | Factory watchdog | Silent stalls, red CI, and unhealthy queues create actionable alerts | The watchdog alerts; it does not invent fixes |
  119. ### 1. Make build and review self-converging
  120. In the starter, `/finn-build` and `/finn-review` can run independently. The
  121. next step is to have the builder open its PR and then launch a **fresh reviewer
  122. with clean context**. Do not let the builder review its own work from the same
  123. conversation.
  124. A proven convergence policy is:
  125. 1. The builder opens one PR for one Linear issue.
  126. 2. A fresh reviewer checks the exact head commit against the issue and required
  127. CI.
  128. 3. If the verdict is `loop-changes-requested`, the builder fixes only the
  129. must-fix findings.
  130. 4. A new fresh reviewer checks the new head commit.
  131. 5. After two failed fix rounds, label the PR `loop-stuck` and stop for a human.
  132. The retry cap matters. An agent should not argue with a reviewer forever or
  133. silently broaden the Linear contract to make a test pass.
  134. ### 2. Use Slack as a human control plane
  135. Slack becomes useful when it removes trips to Linear and GitHub without
  136. replacing either one.
  137. | Channel | Event | Human action | Durable result |
  138. | --- | --- | --- | --- |
  139. | `#notifs-linear-blocked` | A builder blocks an issue with one concrete question | Reply in the message thread | Copy the answer to Linear, remove `blocked`, and return the unassigned issue to the queue |
  140. | `#notifs-merge-ready` | A PR is `loop-approved`, CI-green, conflict-free, and still at the reviewed SHA | Review the preview/test steps and react with 🚀 | Re-read the PR from GitHub, then squash-merge only if every gate is still true |
  141. | `#notifs-digest` | A scheduled daily snapshot summarizes merges, approvals, blockers, and queue depth | Use it to choose the day's founder actions | Claim one durable post per date so retries cannot create duplicate digests |
  142. | `#notifs-alerts` | The watchdog detects an unhealthy pipeline | Investigate the named condition | Post once when opened and once when resolved; stay quiet while unchanged |
  143. A safe Slack integration needs more than a webhook that calls merge:
  144. - Verify Slack and GitHub webhook signatures before processing an event.
  145. - Allow only explicitly configured founder Slack user IDs to approve an action.
  146. - Store event IDs, message timestamps, PR numbers, and reviewed head SHAs so
  147. duplicate deliveries are harmless.
  148. - Claim a post or reaction in durable storage before making an external call.
  149. - Re-read Linear or GitHub at action time. Never trust an old Slack message as
  150. proof that an issue is still blocked or a PR is still merge-ready.
  151. - Mark old merge messages as superseded when the PR head changes.
  152. - Retry transient failures, but repeat the live safety checks before every
  153. retry.
  154. - Provide environment-level kill switches for automated posting and merging.
  155. The useful division of responsibility is:
  156. - **Linear:** what should be built and whether an issue is ready or blocked.
  157. - **GitHub:** the code, review commit, CI, conflicts, and merge state.
  158. - **Slack:** human-facing questions, approvals, and alerts.
  159. - **The repository:** how the factory behaves—skills, templates, and policy.
  160. ### 3. Add risk-aware merge policy carefully
  161. The public starter's rule is intentionally simple: agents never merge. In a
  162. more mature factory, automation can execute a narrowly pre-authorized merge,
  163. but only after the team explicitly changes that governance rule.
  164. A conservative policy has three lanes:
  165. - **Human merge:** application code and anything involving schema, auth,
  166. permissions, billing, deployment, or provisioning.
  167. - **Founder-authorized merge:** a founder's 🚀 reaction authorizes one exact PR
  168. head; the system re-verifies labels, CI, conflicts, and SHA before merging.
  169. - **Safe auto-merge:** an opt-in allowlist such as docs and tests, plus an
  170. explicit override label and a global kill switch. Never infer safety merely
  171. from a small diff.
  172. Keep a `needs-human-review` label for sensitive paths and a
  173. `safe-auto-merge` label for deliberate exceptions. A PR that changes after
  174. approval must earn approval again.
  175. ### 4. Use Linear relations for multi-part features
  176. Large features should become a chain of one-day issues, connected with
  177. Linear's blocked-by relations. All parts may be approved up front, but the
  178. queue should hide a downstream issue until its blocker is Done, and the claim
  179. operation should enforce the same rule.
  180. This lets several agents work from a durable plan without allowing part three
  181. to start before part one has established the contract it depends on.
  182. ### 5. Turn previews and documentation into merge gates
  183. Unit tests are not enough for user-facing work. For a PR that changes rendered
  184. UI, require the builder to open the deployment preview, sign in with a
  185. non-production test account, run every founder-verification step from the
  186. Linear issue, and record per-step `PASS` or `FAIL` evidence with screenshots.
  187. The reviewer should treat missing or failed evidence as a must-fix finding.
  188. Behavior-changing PRs should also update the matching architecture document.
  189. A lightweight CI check can require the PR body to name the docs changed, or to
  190. state why no docs change is justified. This makes documentation part of done
  191. instead of cleanup that never happens.
  192. ### 6. Add direction and status skills
  193. Two read-mostly skills remove a surprising amount of founder overhead:
  194. - A **morning director** reads product goals plus live Linear and GitHub state,
  195. proposes a small daily packet, and files or promotes only the exact issues a
  196. founder approves in that session. It plans; it never starts builders.
  197. - A **status inspector** reads open PRs and the `agent-ready`, `spec-drafted`,
  198. `needs-spec`, and `blocked` queues, then returns an ordered list of what the
  199. founder must merge, approve, or answer. It never mutates either system.
  200. The separation is important: planning decides what enters the factory;
  201. building should remain a boring execution step.
  202. ### 7. Add a factory watchdog
  203. Event-driven notifications cover things that happen. A watchdog covers things
  204. that silently stop happening. First normalize Linear and GitHub events into one
  205. durable pipeline record per issue/PR, with derived stages such as awaiting
  206. approval, ready, building, review, merge-ready, blocked, and done. Let the
  207. status view, daily digest, and watchdog read that same model.
  208. Run the watchdog on a schedule against the pipeline model plus current
  209. default-branch CI, and alert on conditions such as:
  210. - work stuck in building or review beyond a threshold;
  211. - changes requested with no follow-up;
  212. - ready work but no recent merges;
  213. - an empty build queue or a growing spec/blocked backlog; and
  214. - red required checks on the default branch.
  215. Alert once when a condition opens, stay silent while it persists, and post a
  216. short resolved message when it clears. A watchdog that repeats the same alert
  217. every few minutes becomes noise and gets muted.
  218. ### 8. Run persistent workers with leases
  219. `/loop` is a good first scheduler, but it still depends on an open interactive
  220. session. When you move to always-on machines or a worker fleet, make jobs
  221. durable instead of treating a process named "running" as proof of life.
  222. - Give every job explicit queued, leased, running, succeeded, and failed state.
  223. - Have workers renew short leases while they work. Expire abandoned leases,
  224. requeue up to an attempt limit, then fail visibly.
  225. - Give each job a clean clone or worktree. Never let concurrent builders share
  226. a working directory.
  227. - Keep worker, dispatcher, and human-operator credentials separate and
  228. least-privileged.
  229. - Record heartbeats and terminal results so the watchdog can distinguish an
  230. empty queue from a dead scheduler.
  231. - Keep the worker boundary conservative: agents may research, draft, code,
  232. test, and propose, but publishing, spending, production mutation, and merges
  233. still require the policy gates you chose above.
  234. ### 9. Build a post-merge learning loop
  235. The highest-signal lessons often appear as reviewer must-fix findings and then
  236. disappear once the PR is corrected. A learning loop can scan recently merged
  237. PRs, read **every** earlier reviewer verdict, inspect the eventual fix, and
  238. distill one reusable rule.
  239. Store proposed rules as version-controlled files with applicability tags and
  240. source PRs. Deduplicate against active rules; reinforce an existing rule when
  241. the same failure class recurs. The agent opens a learning proposal PR, but a
  242. founder decides whether that rule becomes factory policy by merging it. Agents
  243. should never silently rewrite the instructions that govern them.
  244. ### 10. Next experiment: approve specs from Slack
  245. This is the next logical control-plane extension, but it is not part of the
  246. public starter. Treat `spec-drafted && !agent-ready` as "awaiting approval"
  247. and post a versioned spec summary to a Slack review inbox. A founder can either
  248. approve during the `/finn-spec` session or defer the decision and approve the
  249. unchanged issue later with a Slack reaction.
  250. Before applying `agent-ready`, re-read the Linear issue and confirm its version
  251. matches the Slack message. If the spec changed, supersede the old message and
  252. require a new approval. Start with approval-only reactions; a full
  253. changes-request conversation is a separate workflow.
  254. ## Suggested implementation order
  255. 1. Run the three-skill starter for several real PRs and tune spec quality.
  256. 2. Add fresh-reviewer convergence and a `loop-stuck` escape hatch.
  257. 3. Add blocked-by issue chains and a read-only status skill.
  258. 4. Connect the blocked-issue Slack lane.
  259. 5. Connect the merge-ready Slack lane with live re-verification.
  260. 6. Add preview and documentation CI gates.
  261. 7. Introduce risk-tiered merging only after the earlier evidence is reliable.
  262. 8. Add the morning director and watchdog once queue volume justifies them.
  263. 9. Add leased persistent workers when open sessions become the throughput
  264. bottleneck.
  265. 10. Add the post-merge learning loop once reviews produce recurring findings.
  266. 11. Add versioned Slack spec approval last; it changes the most important human
  267. gate in the system.
  268. The goal is not "no humans." It is for humans to handle product judgment,
  269. policy, and irreversible exceptions while agents handle repeatable execution.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.