spec-to-pr

name

spec-to-pr

description

Execute a complete spec-to-PR pipeline from a Linear issue: auto-detect or create the Linear project for the current repo, fetch or create the spec issue inside that project, create a git branch, plan the implementation, execute tasks sequentially with TDD, commit, run a codebase readiness review, fix quality issues, commit fixes, and open a pull request with the Linear issue linked. Use this skill whenever the user says "implement this spec", "execute the Linear issue", "build this feature end-to-end", "turn this ticket into a PR", "take this issue to done", "implement and PR", "complete this Linear task", or references a Linear issue ID (e.g. "ENG-123", "PLT-42") and wants it shipped. Also trigger when asked to "implement from spec and review before PR" or "run the full pipeline on this issue." This skill chains: project detection/creation → issue resolution → branch creation → planning → TDD implementation → commit → readiness review → quality fixes → commit → PR.

Spec to PR Pipeline

A full end-to-end workflow that takes a Linear issue and produces a reviewed, committed pull request — with a quality gate baked in before the PR opens.

Why this exists

Shipping means more than writing working code. The codebase readiness review often catches issues that would otherwise create friction during code review or introduce subtle technical debt. Running it as part of the pipeline — before the PR is opened — means you fix quality issues while context is fresh, with the full implementation visible in one pass.

Keeping specs inside a Linear project (one project per repo) means there's always a single place to find what was built, why, and in what order — invaluable when onboarding or debugging months later.

The pipeline at a glance

detect/create project → resolve issue → branch → plan → TDD → commit → review → fix → commit → PR

---

Step 0: Detect or create the Linear project

Every spec must live inside a Linear project that corresponds to this repo. Do this before touching the issue.

0a. Determine the repo identity

Derive a canonical project name from the current working directory:

basename $(git rev-parse --show-toplevel 2>/dev/null || pwd)

Use this as the search key (e.g., ai-cost-visibility-dashboard).

0b. Search for an existing project

Use mcp__claude_ai_Linear__list_projects to list all projects. Look for a project whose name closely matches the repo name (case-insensitive, ignoring hyphens/underscores). Also check the project's description for the repo name or URL.

If the user is already pointing you at a specific issue ID, also call mcp__claude_ai_Linear__get_issue to read the issue's project field — if it's already in a project, use that project and skip 0c.

0c. Create the project if none exists

If no matching project is found, create one with mcp__claude_ai_Linear__save_project:

• name: repo name in Title Case (e.g., AI Cost Visibility Dashboard)
• description: Tracks all specs and implementation work for the <repo-name> repository.
• team: ask the user which team to assign it to (use mcp__claude_ai_Linear__list_teams to show options), or use the team from a provided issue ID if available

Tell the user: "No Linear project found for this repo. I've created '' — all specs for this repo will live there."

0d. Remember the project for this session

Store the project ID in memory for use in Step 1 when creating or verifying the issue.

---

Step 1: Resolve the spec issue

If the user provided an issue ID or URL: fetch it with mcp__claude_ai_Linear__get_issue. If the issue is not already linked to the project from Step 0, update it using mcp__claude_ai_Linear__save_issue to set the projectId.

If no issue was provided: ask the user to describe what to build (title + brief description). Then create the issue with mcp__claude_ai_Linear__save_issue:

• title: from the user's description
• description: expanded description with acceptance criteria (ask if unclear)
• projectId: the project from Step 0
• teamId: the team from Step 0

Either way, extract from the resolved issue:

• Title, description, acceptance criteria
• Labels and priority
• Any linked sub-issues or parent

Confirm before branching. Summarize what you understand in 3-4 bullets and ask: "Here's what I'll implement — does this look right?"

Don't proceed until the user confirms.

---

Step 2: Create a git branch

Derive a branch name from the issue:

• Format: <issue-id-lowercase>-<kebab-case-title> (e.g., eng-123-add-user-auth)
• Keep the title segment under 40 chars
• Replace spaces and special characters with hyphens, all lowercase

git checkout -b <branch-name>

If the repo has no commits yet, initialize it first:

git init && git add . && git commit -m "chore: initial commit"

---

Step 3: Write an implementation plan

Invoke superpowers:writing-plans to create a detailed, step-by-step plan.

Provide as input:

• The Linear issue title and full description
• Acceptance criteria extracted from the issue
• Any priority or label context that affects scope

The plan goes in docs/plans/YYYY-MM-DD-<feature-name>.md.

Wait for the plan to be written and reviewed before moving on.

---

Step 4: Execute the plan

Invoke superpowers:executing-plans to implement the plan task-by-task.

This skill handles:

• TDD: write tests first, then minimal implementation
• Batch execution with human checkpoints (default: 3 tasks per batch)
• Running verifications after each task

Don't skip the checkpoints. Let the user confirm each batch.

---

Step 5: Commit the implementation

Once all tasks are complete and verifications pass, stage and commit:

git add -p   # review each hunk — don't blindly stage everything
git commit -m "$(cat <<'EOF'
feat(<scope>): <description matching Linear issue title>

Implements <LINEAR-ISSUE-ID>: <one-line summary of what was built>

Co-Authored-By: Claude Sonnet 4.6 <[e-mail]>
EOF
)"

Derive <scope> from labels or the primary area touched (e.g., auth, api, ui, db).

---

Step 6: Run the codebase readiness review

Invoke codebase-readiness-review to score the codebase across 8 pillars and the OpenSSF supply-chain checks.

The review runs real commands (lint, typecheck, tests, audit) — not just config reads. Read the output carefully: you need the ranked fix list for the next step.

---

Step 7: Fix quality issues

Work through the ranked fix list from the review. Prioritize in this order:

1. False-confidence gaps — config that declares a standard but CI never enforces it
2. Broken quality gates — lint/typecheck/test failures introduced by this implementation
3. Security findings — anything flagged in the OpenSSF checks
4. High-ROI housekeeping — things the review ranked as high-value that are quick to fix

For each fix:

• Read the exact finding before touching code — don't guess at what it's asking for
• Make the minimal change that closes the gap
• Verify the gate passes by rerunning the same command the review ran

Skip out-of-scope fixes. If a finding is unrelated to this spec and would require significant refactoring, note it as a follow-up Linear issue instead of blocking this PR.

When to stop: Stop when all findings from the implementation itself are resolved and the most critical pre-existing issues are addressed. Aim for "shippable with confidence," not "perfect."

---

Step 8: Commit the quality fixes

git add -p
git commit -m "$(cat <<'EOF'
chore: fix quality issues from readiness review

- <bullet: specific thing fixed>
- <bullet: specific thing fixed>

Co-Authored-By: Claude Sonnet 4.6 <[e-mail]>
EOF
)"

If the review found no issues, skip this step and note "no quality issues found" in the PR body.

---

Step 9: Create the pull request

gh pr create \
  --title "<LINEAR-ISSUE-ID>: <issue title>" \
  --body "$(cat <<'EOF'
## Summary

- <what was built>
- <key design decisions>
- <any scope tradeoffs made>

## Linear issue

Closes <Linear issue URL>

## Readiness review

- Overall maturity: Level N/5 (score: XX)
- Quality fixes applied: <brief list or "none required">
- Deferred findings: <brief list or "none">

## Test plan

- [ ] <step to verify the feature works>
- [ ] <edge case to verify>
- [ ] Tests pass: `<test command>`

🤖 Generated with [Claude Code](https://claude.com/claude-code)
EOF
)"

After the PR is created, post the PR URL as a comment on the Linear issue using mcp__claude_ai_Linear__save_comment.

---

Edge cases

No git history in the repo: Initialize with git init && git add . && git commit -m "chore: initial commit" before creating the branch.

Multiple projects with similar names: List them to the user and ask which one to use. Don't guess — the wrong project means specs end up in the wrong place.

Issue already exists but is in the wrong project: Update the issue's projectId silently using mcp__claude_ai_Linear__save_issue before proceeding. Tell the user you've moved it.

Issue has sub-tasks in Linear: Fetch each sub-task and treat them as task groups in the plan. Ensure all sub-tasks are linked to the same project. Mention in Step 1 confirmation that you'll implement all sub-tasks.

User provides a description instead of an issue ID: Create the issue in Linear first (Step 1, "no issue provided" path), then proceed. Don't skip the issue creation — a spec without a Linear issue has no paper trail.

Tests fail during the readiness review: These must be fixed before the PR opens — broken tests block the pipeline and shouldn't land on reviewers. Treat test failures as P0 fixes in Step 7.

User wants to skip the review: Respect it. Skip Steps 6–8 and note in the PR body that the readiness review was skipped. But mention what it would have checked.

Plan reveals the spec is ambiguous: Raise the ambiguity in Step 3 before writing any code. Better to clarify with the user now than to build the wrong thing and discover it in review.

No Linear access / MCP unavailable: Tell the user and ask if they want to proceed without the Linear integration (skipping Steps 0–1 project/issue management and the final comment). The rest of the pipeline (branch, plan, implement, review, PR) still works.