Linear Project
rdanghb/linear-project
Converte brainstorms em projetos Linear estruturados com marcos e artefatos
Ver no GitHubSkill que transforma um brainstorm de engenharia em um projeto Linear totalmente estruturado, com seis marcos (ou marcos customizados), documentação automática e rastreamento de estágios. Suporta dois modos: fluxo padrão CE (Compound Engineering) e projetos ops ad hoc com descoberta guiada.
Instalação
npx convez-ai rdanghb/linear-project1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Criar projetos de produto/feature seguindo o workflow Compound Engineering
- Organizar trabalho ops customizado com descoberta de requisitos automática
- Padronizar e acelerar setup de projetos em Linear com marcos pré-definidos
Veredito

Skill bem concebida que resolve um problema real: padronizar a criação de projetos em Linear e forçar pensamento estruturado em trabalho ops. O design em dois modos (CE vs custom) é inteligente; o escopo honesto de v1 (não completa automaticamente Work/Review) é apropriado e realista.
README
A tradução para o português deste README ainda está na fila.
/linear-project
Turn a Compound Engineering build — or an ad hoc ops project — into a fully-formed Linear project. The RevOps team's standard, repeatable way to run work in Linear.
This repo is the skill's source — not a project you run the skill against. Install it once (Setup below), then run
/linear-projectfrom your own project repos. The skill writes its per-repo state to a.linear-project.yamlin whatever directory you run it from; that file is gitignored here and is never committed to this repo, so your projects never touch this one. (If you ever do run/linear-projectfrom inside this clone, it'll just drop a local, ignored config — no harm — but that's not the intended use.)
Two modes
On a fresh project the skill asks one question first: is this a standard CE build or a custom-milestone ops project?
- CE build (
mode: ce) — a product/feature build that follows the Compound Engineering workflow. Gets the fixed six-milestone spine (Brainstorm → Plan → Work → AI Review → Human Review → CE) and pushes your Brainstorm/Plan markdown into Linear. This is the original path, unchanged. - Custom-milestone ops (
mode: custom) — ad hoc, manual ops work (list-building, vendor evals, data-matching trials) that doesn't fit the CE spine. You define your own milestones. Before the project is created, the skill runs a short discovery conversation — what you're solving, who it's for, and what's uncertain — so you think the problem through instead of jumping straight to executing. It brainstorms the open decisions with you, then pushes a plain-language Discovery doc and Plan doc into Linear.
The mode is chosen once, at create time, and is fixed for the life of the project (see mode mis-pick recovery under Troubleshooting). Everything in "The workflow" below describes CE build mode; custom mode is covered in its own section.
Why this exists
- Easy Linear Project adoption — every CE project gets the identical six-milestone spine, so status is legible at a glance across projects and to stakeholders who don't live in the terminal.
- Higher-quality builds with fewer bugs — the project structure walks you through the Compound Engineering workflow (Brainstorm → Plan → Work → AI Review → Human Review → CE) instead of improvising.
- Less manual setup — the skill auto-scaffolds the project, the six milestones (backed by tracker issues), and pushes your Brainstorm/Plan markdown into Linear. Milestone progress moves on its own as stages complete (see "A tracker issue per milestone").
- A forcing function for ops work — custom mode won't let you create a project without first answering what you're solving and what's uncertain about it. Most ad hoc ops work skips that thinking; this makes it unskippable.
What it does NOT automate (honest scope for v1): Work completeness % is owner-set by hand. AI Review captures human-run Claude + Codex reviews (the skill does not run them). Human Review is stakeholder UAT signoff. CE is fed manually post-launch. The skill does auto-complete the two stages it actually finishes — pushing the Brainstorm or Plan artifact moves that stage's tracker issue to Done, advancing the milestone — but Work / AI Review / Human Review are moved to Done by a human when their manual done-signal is met. In custom mode, the user-defined milestones are pure execution-tracking — the skill creates them but does not score their progress (no tracker issue). The skill removes the setup toil; the judgment steps stay human.
Prerequisites
- Claude Code is already installed. This README does not cover installing Claude Code itself.
- A Linear account with access to the RevOps team (or whichever team will hold your CE projects).
Setup (one-time)
What "restart Claude Code" means — read this first. Setup requires restarting Claude Code twice, and a half-restart silently fails (the new skill/MCP just never appears). "Restart" means fully quit and reopen the app — not
/clear, not a new chat, not a new terminal session. On the desktop app: quit it entirely (Cmd-Q / right-click the dock or tray icon → Quit), then reopen. In a terminal: exit theclaudeprocess completely, then start it again. If the skill still doesn't show up after a clean quit-and-reopen, reboot the machine and reopen — that's the nuclear option, rarely needed. When to restart: once after step 2 (loads thece-*skills) and once after step 3 (loads/linear-project). Don't skip either.
Let Claude set this up (semi-automated)
Setup is not fully hands-off — three steps are human-gated and Claude cannot do them for you (a browser OAuth click, two /plugin slash commands, and restarting Claude Code). But Claude can run the shell steps and walk you through the rest. Open a Claude Code session and paste:
Read the README in this repo and help me set up
/linear-project. Run the shell steps for me (theclaude mcp addcommand and thegit cloneinto my skills dir). Stop and tell me clearly each time I need to do something you can't — the Linear OAuth browser click, the/pluginslash commands, and the two Claude Code restarts (tell me exactly when each restart happens and that "restart" means fully quitting and reopening the app, not/clear). Wait for me to confirm before continuing. Setup isn't done when the install finishes — once the skill loads, walk me through running/linear-projectto create and push my first real project to Linear end-to-end, in whichever mode fits what I'm working on. Don't stop until I have a live project in Linear.
What Claude does vs. what you do:
| Step | Who | Why |
|---|---|---|
claude mcp add --scope user … linear-server … | Claude (shell) | Ordinary shell command (--scope user so the MCP works from every repo) |
| Authorize Linear in the browser | You | OAuth click — opens after first MCP connect |
/plugin marketplace add … + /plugin install … | You | Slash commands typed into the Claude Code prompt; Claude can't fire its own harness commands |
Restart #1 — quit & reopen Claude Code (loads ce-*) | You | Claude can't restart its own host process; skills only load on a fresh start |
git clone … ~/.claude/skills/linear-project | Claude (shell) | Ordinary shell command |
Restart #2 — quit & reopen Claude Code (loads /linear-project) | You | Same as above |
First /linear-project run — create + push your first project | You | The skill only exists after the clone + restart #2 |
Chicken-and-egg:
/linear-projectitself doesn't exist in the session until after the clone + restart, so the skill can't install itself — the first session just runs the shell steps and guides you; a later session has the skill loaded.
Prefer to do it by hand? The four manual steps below are the canonical reference.
1. Install the Linear MCP and complete OAuth
claude mcp add --transport http --scope user linear-server https://mcp.linear.app/mcp
--scope user is important: it registers the MCP for all your repos, not just the directory you run this command in. You'll use /linear-project from many different project repos, so the Linear MCP has to be available everywhere — without --scope user it's registered for the current directory only, and the skill fails with "Linear MCP not available" the moment you run it elsewhere.
The first time the MCP connects, a browser OAuth flow opens — authorize it. If you later see auth errors, re-run the command above and re-authenticate.
2. Install the Compound Engineering plugin
/linear-project depends on the ce-* skills (/ce-brainstorm, /ce-plan, /ce-work, /ce-code-review, /ce-compound). Install the Compound Engineering plugin from its marketplace inside Claude Code:
/plugin marketplace add EveryInc/compound-engineering-plugin
/plugin install compound-engineering
Restart #1 — now fully quit and reopen Claude Code so the ce-* skills load. (Quit the app entirely, not /clear or a new chat — see the callout at the top of Setup.) (Source: github.com/EveryInc/compound-engineering-plugin.)
3. Enable /linear-project
Clone this repo straight into your Claude Code skills directory:
git clone https://github.com/rdanghb/linear-project.git ~/.claude/skills/linear-project
Restart #2 — fully quit and reopen Claude Code so it picks up the new skill (and the MCP loads at startup). After this restart, type / and confirm /linear-project appears in the list before moving on. If it doesn't, you didn't fully quit — close the app completely and reopen (reboot the machine only as a last resort).
4. Create your first project (don't stop at install)
Installing the skill is not the finish line. You're only set up once you've pushed a real, live project into Linear. Do this now, while you're here — it proves the whole loop works end-to-end, and it's the same flow you'll use every time after. Pick whichever of the two streams matches what you're actually working on:
Stream A — CE build. From inside a repo that has a CE brainstorm (docs/brainstorms/*-requirements.md):
/linear-project
Don't have a brainstorm yet? Run /ce-brainstorm first (that's the intended on-ramp), then come back.
Stream B — custom-milestone ops project. For ad hoc ops work (a lead list, a vendor eval) with no brainstorm — run the same command from any repo:
/linear-project
On this first run the skill asks which Linear team should hold your projects (pick RevOps) and caches the choice in a repo-local .linear-project.yaml. Then it asks the project-kind question (CE build vs custom-milestone ops) — answer based on which stream you picked above. From there:
- CE build → it creates the project, scaffolds the six milestones, and pushes your brainstorm (then run it again after
/ce-planto push the plan). - Custom mode → it runs the inline discovery floor first (problem / beneficiary / uncertainty / open decisions — see "Custom-milestone projects" below), then creates the project with your milestones and pushes the Discovery + Plan docs.
You're done when you can open Linear and see your project — milestones scaffolded and at least one Document (your brainstorm summary, or your Discovery doc) attached. Open it, confirm it reads cleanly to someone who doesn't live in the terminal, and you've completed the loop. Now you're set up.
The workflow
(CE build mode. For ad hoc ops work, see "Custom-milestone projects" below.)
The Linear project mirrors the six Compound Engineering stages, in order. Each stage has a distinct "done" signal — see references/milestones.md for the canonical list.
| Stage | CE step | When you invoke /linear-project | "Done" means |
|---|---|---|---|
| Brainstorm | /ce-brainstorm | After the brainstorm — run /linear-project to create the project + push the brainstorm. | Summary + full brainstorm Documents are in the milestone; the skill moves the Brainstorm tracker issue to Done automatically. |
| Plan | /ce-plan | After planning — run /linear-project (or --push-plan) to push the plan. | Summary + full plan Documents are in the milestone; the skill moves the Plan tracker issue to Done automatically. |
| Work | /ce-work | — (set the % in Linear yourself) | Owner-set completeness hits 100%; repo linked. |
| AI Review | /ce-code-review + Codex | — (capture both reviews in the milestone) | Both the Claude slot and Codex slot are filled. |
| Human Review | stakeholders | — (record signoff in Linear) | A stakeholder records UAT acceptance. |
| CE | /ce-compound | — (links accrue over time) | Never closed — fed post-launch and per bug. |
Two Documents per stage — summary + full
Each artifact-bearing stage (Brainstorm, Plan) pushes two Linear Documents: a plain-language summary as the primary, reader-facing artifact, plus the full markdown it links to for technical depth. The milestone synopsis points at the summary. This keeps Linear legible to teammates and stakeholders who don't live in the terminal (the skill's adoption goal) without losing the full detail. The summary is generated from the full artifact and regenerated whenever the full Document changes, so it never drifts.
A tracker issue per milestone
Each progress-bearing milestone is backed by tracker issue(s) assigned to it. This is what makes a stage show a real Backlog → In Progress → Done state and what drives the milestone's progress bar — a Linear milestone has no status of its own, so a milestone with no issues sits at 0% forever even after its artifact is pushed. (That's the gap an earlier version left, where Brainstorm stayed at 0% / Backlog despite being complete.) Tracker count: one each for Brainstorm, Plan, Work, Human Review; two for AI Review (a Claude slot + a Codex slot, so it reads an honest 50% when one is in); none for CE (the ongoing milestone).
When the skill completes a stage it moves that stage's tracker to Done automatically: pushing the Brainstorm or Plan artifact flips its tracker Backlog → Done, advancing the milestone. (Upgrading a project whose artifact was already pushed before you updated the skill? The tracker is created already-Done, so the milestone isn't stranded at 0%.) The rest are completed by a human — move Work to Done at 100%, each AI Review slot when that review is captured, Human Review at UAT signoff — and CE is never closed. The "Done" state is whatever your team calls its completed status (discovered automatically, not hardcoded).
(Tracker issues are a CE-build feature. Custom-milestone ops projects don't get them — those milestones are owner-managed execution phases.)
When to invoke the skill
- After Brainstorm:
/linear-project— creates the project and pushes the brainstorm. - After Plan:
/linear-project— pushes the plan into the Plan milestone. - Fixed a typo in an artifact already pushed:
/linear-project --repush plan— re-snapshots the same-shape artifact. - Check state:
/linear-project --status— read-only stage report. - Preview without writing: add
--dry-runto any invocation.
When the work changes shape
If the work evolves after the project exists — new scope, a materially different plan, a follow-on effort — the skill does not silently re-snapshot. It asks you to classify the change:
- Post-hoc milestone — an incremental addition; a new milestone is appended after CE on the same project.
- New v2 project — a significant evolution; a fresh six-milestone project is created and linked back to the v1.
This keeps Linear honest as the source of truth instead of letting a milestone quietly drift from git. (--repush is only for unchanged-in-shape re-snapshots and never triggers this prompt.)
Custom-milestone projects (ad hoc ops work)
Pick custom-milestone ops at the project-kind question when the work is manual, ad hoc ops — building a lead list, evaluating a vendor, trialing a data-matching approach — not a product/feature build. There's no fixed spine; you define the milestones.
The forcing function. Before the project is created, the skill runs a short discovery conversation. It's deliberately lighter than a full /ce-brainstorm — a handful of questions, not a PRD:
- Problem — what are you actually solving (the underlying need, not the task list)?
- Beneficiary — who is this for / who uses the result?
- Uncertainty — what's uncertain or risky about it?
- Open decisions — what decisions are still open inside this work?
You cannot create the project without surfacing the uncertainty / open decisions (questions 3–4) — that's the non-skippable floor. Even if you arrive with your milestones already worked out, the skill holds until you've named what's uncertain. That's the whole point: ad hoc ops work tends to skip the thinking and jump straight to executing.
You bring the milestones, two ways:
- Paste your phases — e.g. "Milestone 1: Franchisor / Milestone 2: Clay". The skill structures them in your order and confirms, then still runs the discovery floor and brainstorms the open decisions embedded in them.
- Bring a fuzzy goal — the skill interviews you to draw out the phases, in order, and what each produces.
Either way the milestones are yours — no imposed CE review/CE stages, no AI Review.
For the open decisions, the skill is a thinking partner, not a transcriber. It offers concrete options rather than just filing your uncertainty. (For "match existing customers already in the DB," it proposes domain match, brand-name normalization, fuzzy match with a review queue — instead of leaving "how to match" as an open TODO.)
What you get:
- A Linear project with your user-defined milestones as pure execution-tracking phases (no artifact attached, no progress scoring).
- A plain-language Discovery Document — problem, beneficiary, uncertainties, and the open decisions with their brainstormed options.
- A plain-language Plan Document — your ordered milestones and the approach for each phase.
Both docs are written to local git markdown first (git is canonical), then pushed as single project-level Linear Documents. They live under their own filename globs (docs/brainstorms/<slug>-discovery.md, docs/plans/<slug>-ops-plan.md). The discovery glob is naturally distinct from CE's *-requirements.md; the ops-plan glob ends in -plan.md, so the CE plan locator explicitly excludes *-ops-plan.md to keep the two modes' plan artifacts from colliding in a mixed repo.
--status and --repush discovery / --repush plan work in custom mode. The CE-only flags (--push-brainstorm, --push-plan) do not.
Working across machines / teammates
.linear-project.yaml is local to your clone (gitignored — it holds your team and project ids and is never committed to the shared skill). So a teammate on a fresh clone has no project id cached. To avoid duplicate projects:
- The skill adopts, it doesn't duplicate. Before creating, it queries Linear for an existing project for this build (matched by a stable build key embedded in the project Brief, falling back to repo URL, then name). If it finds one, it shows you the project's owner/team and offers to adopt it — writing the existing ids into your local config — instead of creating a second project.
- Point a fresh clone at an existing project: just run
/linear-projectfrom the clone. When the adoption prompt appears, confirm to adopt the existing project (<your-project-name>). The skill caches its ids locally and you're synced. - Renames are safe (normal case). Renaming the project in Linear does not defeat adoption — the build key, not the name, is the primary match. The one edge: if Linear's
list_projectsever stops returning project Briefs, the skill falls back to gathering rename-vulnerable name candidates first, so a renamed project could be missed in that fallback. In normal operation (Briefs returned) renames are fully safe. - Known residual — simultaneous first runs can race. Because the check-then-create is not atomic, two teammates running the skill against the same brainstorm at the same time before either has created the project can both create one. The skill detects this right after creating (it re-queries and warns), but cannot prevent it. Recommendation: let one owner create the project first, then teammates adopt. If a duplicate slips through, archive one project in Linear and point the survivors' configs at the keeper.
(All examples here use placeholders like <your-project-name> and https://github.com/<org>/<repo> — substitute your own.)
Manual / hand-built CE projects
For a CE build too unusual for the standard scaffold, hand-build it in the Linear UI following references/native-template.md. It encodes the same six milestones and a parity checklist, and a hand-built project is still compatible with the skill afterward. (This manual path is CE-build only — custom-milestone ops projects are skill-only; there's no manual parity template for them.)
Troubleshooting
- "No brainstorm found" — run
/ce-brainstormfirst; the skill creates a CE-build project only after a brainstorm exists. (Custom-milestone projects don't need one — they run discovery inline.) - Linear auth errors — re-run the
claude mcp addcommand in step 1 and re-authenticate, then retry. - Wrong team cached — edit
team_id/team_keyin.linear-project.yaml, or delete the file to re-trigger team discovery. - Picked the wrong mode — mode is chosen once at create time and can't be flipped on an existing project (CE and custom have different milestone structures). To switch: archive the Linear project, delete (or clear the project entry from)
.linear-project.yaml, and re-run/linear-projectto pick the other mode. The skill refuses to scaffold the wrong-mode structure onto a project whose Brief marks it as the other mode.