Try it on your idea →
⚡ Live Demo

This is what SpecForge generates

The input was one rough paragraph. This came out 28 seconds later.

Input idea (raw): "I want to build a CLI tool that takes a git diff or PR changes and auto-writes a good PR description — summary of what changed, why, what to test. Maybe integrates with GitHub API. Using TypeScript, solo project."
SpecForge processed this in 28 seconds
📋 Product Requirements
🎫 GitHub Tickets (8)
🤖 CLAUDE.md
Product Requirements Document

Project Overview

PRDraft is a CLI tool that reads a git diff or GitHub PR and generates a high-quality PR description automatically. It produces a structured description including a change summary, motivation, affected files, and testing checklist — reducing the time a developer spends on PR hygiene from 5–15 minutes to under 30 seconds.

Problem Statement

Developers write poor PR descriptions not because they don't care, but because they've already spent cognitive energy on the code. By the time a PR is ready, writing a clear description feels like overhead. The result: reviewers lack context, reviews take longer, and merge queues back up.

Existing tools require GitHub App installations, team accounts, or complex CI configuration. A solo developer with a local repo should be able to run a single command and get a draft description they're proud of.

Target User

  • Primary: Solo developers who maintain open-source projects or work in small teams
  • Secondary: Engineers who frequently submit PRs and want consistent description quality
  • Context: Working locally with git, comfortable with CLI tools, likely using Cursor or Claude Code for development

Core Features (MVP)

  • Git diff input: Accept git diff main output or read from stdin
  • GitHub PR input: Accept PR number + repo via --pr 123 --repo owner/repo
  • Structured output: Summary (2–3 sentences), What Changed (bullet list), Why (motivation), Testing Checklist
  • Copy to clipboard: Auto-copy output for immediate pasting into GitHub PR body
  • Format options: Markdown (default), plain text via --format plain

Out of Scope (MVP)

  • Automatic PR submission or editing (read-only PR generation)
  • Multi-repo batch processing
  • Slack/Jira integration
  • Team analytics or dashboards
  • Fine-tuning on org-specific PR style

Success Metrics

  • CLI runs in under 30 seconds on a 500-line diff
  • Output requires less than 1 edit before pasting (user satisfaction)
  • Zero dependencies beyond Node.js and a configured API key
  • Works fully offline from git diff (no GitHub API required for basic usage)

Tech Stack

  • Language: TypeScript (Node.js)
  • Package manager: npm
  • AI provider: Anthropic Claude API (claude-haiku for speed/cost)
  • GitHub integration: Octokit REST client
  • CLI framework: Commander.js
  • Config storage: ~/.prdraft/config.json

Architecture Notes

  • Single entry point: prdraft [options]
  • Two input modes: pipe from stdin (diff) or --pr flag (GitHub API)
  • Output is streamed to stdout, also written to temp file for clipboard
  • API key stored in config file, fallback to env var ANTHROPIC_API_KEY
  • Token limit: cap diff at 8,000 tokens before sending to API
GitHub-Ready Dev Tickets (8)
Ticket #1 · Setup
Initialize TypeScript CLI project with Commander.js
Description: Scaffold the project with tsconfig.json, package.json, Commander.js for CLI arg parsing, and a working prdraft --help command. Set up npm build script and local dev workflow with ts-node.

Acceptance criteria:
• npm run build compiles to dist/
• node dist/index.js --help shows usage
• --version flag returns version from package.json
⏱ 1h Setup P0
Ticket #2 · Core
Implement stdin pipe input — read git diff from stdin
Description: When no --pr flag is passed, read from stdin. Detect if stdin is a TTY (no pipe) and show helpful error message. Parse raw diff text and pass to prompt builder.

Acceptance criteria:
• git diff main | prdraft works end-to-end
• Running without pipe shows: "Pipe a git diff or use --pr flag"
• Diff is trimmed to 8,000 tokens if too long, with a warning
⏱ 2h Feature P0
Ticket #3 · Core
Build prompt template and Claude API integration
Description: Create a prompt that takes a git diff and outputs structured PR description: Summary (2–3 sentences), What Changed (bullets), Why (motivation inference), Testing checklist. Use claude-haiku for speed and cost. Stream output to stdout.

Acceptance criteria:
• Output has all 4 sections
• Streams to terminal as it generates
• Handles API errors with user-friendly messages
⏱ 3h Feature P0
Ticket #4 · Config
API key management — config file + env var fallback
Description: On first run with no API key, prompt user to enter their Anthropic key. Store in ~/.prdraft/config.json. Read order: config file → env var ANTHROPIC_API_KEY. Add prdraft config --set-key command to update.

Acceptance criteria:
• First run prompts for API key and stores it
• prdraft config --set-key works
• Env var overrides config file
⏱ 1.5h Feature P0
Ticket #5 · Integration
GitHub PR input mode via Octokit
Description: When --pr 123 --repo owner/repo is passed, fetch the PR diff from GitHub API using Octokit. Requires GitHub token stored in config. Combine PR title + body + diff into prompt context.

Acceptance criteria:
• prdraft --pr 42 --repo alice/myapp fetches and generates
• Missing token shows clear setup instructions
• Rate limit errors handled gracefully
⏱ 2.5h Feature P1
Ticket #6 · UX
Copy to clipboard and format options
Description: After generation, auto-copy output to clipboard using clipboardy. Show "✓ Copied to clipboard" message. Add --format plain flag that strips markdown formatting. Add --no-copy flag to disable auto-copy.

Acceptance criteria:
• Default behavior copies to clipboard
• --format plain removes markdown symbols
• --no-copy suppresses clipboard operation
⏱ 1h Feature P1
Ticket #7 · Testing
Add unit tests for diff parsing and prompt builder
Description: Write Jest tests for: diff tokenization/truncation, prompt template output, config file read/write, and CLI arg parsing. Use fixture diff files for reproducible tests. No API calls in tests (mock the client).

Acceptance criteria:
• npm test passes with no API calls
• Truncation logic is tested at boundaries
• Config read/write tested with temp directory
⏱ 2h Testing P1
Ticket #8 · Release
Package for npm publish and write README
Description: Configure package.json for npm publish with bin pointing to CLI entry. Set up prepublish build step. Write README with installation, quickstart, all flags. Test npx prdraft flow works from scratch.

Acceptance criteria:
• npm install -g prdraft installs globally
• npx prdraft works without install
• README covers all flags with examples
⏱ 1.5h Release P2
CLAUDE.md — Paste directly into your project root
# CLAUDE.md — PRDraft

## Project Overview
PRDraft is a TypeScript CLI tool that reads a git diff or GitHub PR and generates a well-structured PR description using the Anthropic Claude API. Single developer project. Designed for simplicity and speed — zero config for basic use.

## Current Status
Early development. Building MVP toward npm publish.

## Tech Stack
- **Runtime:** Node.js (v18+)
- **Language:** TypeScript (strict mode)
- **CLI framework:** Commander.js
- **AI client:** Anthropic SDK (claude-haiku-3 for speed)
- **GitHub client:** Octokit REST
- **Clipboard:** clipboardy
- **Test runner:** Jest + ts-jest
- **Package manager:** npm

## Project Structure
```
src/
  index.ts          # CLI entry point, Commander.js setup
  input/
    stdin.ts        # Read and parse git diff from stdin
    github.ts       # Fetch PR diff via Octokit
  ai/
    prompt.ts       # Build Claude prompt from diff
    client.ts       # Anthropic API client wrapper
  config/
    store.ts        # ~/.prdraft/config.json read/write
  output/
    format.ts       # Markdown / plain text formatting
    clipboard.ts    # Copy to clipboard helper
  utils/
    tokens.ts       # Diff truncation to token limit
dist/               # Compiled output (gitignored)
tests/
  prompt.test.ts
  stdin.test.ts
  config.test.ts
```

## Key Design Decisions
- **Input priority:** stdin (git diff piped) is primary use case. GitHub API is secondary.
- **Token limit:** Hard cap at 8,000 tokens for diff input before sending to Claude. Warn user if truncated.
- **Streaming:** Stream Claude output to stdout for perceived speed. Also buffer for clipboard copy.
- **No framework bloat:** No React, no build complexity. Pure TypeScript CLI.
- **Config location:** `~/.prdraft/config.json` — follows XDG spirit, user-level config.

## Coding Guidelines
- No `any` types — TypeScript strict mode is on
- All async functions must handle errors explicitly (no unhandled rejections)
- CLI error messages should be user-readable, not stack traces
- Keep each module under 100 lines — extract helpers early
- No external state management — functions are pure where possible

## Environment Variables
- `ANTHROPIC_API_KEY` — overrides config file if set
- `GITHUB_TOKEN` — overrides config file for GitHub API calls

## What NOT to Build (MVP scope)
- Automatic PR submission or editing
- Web interface or GUI
- Team accounts or dashboards
- Webhooks or CI/CD integration
- Style fine-tuning or personalization

## Testing Approach
- Unit tests mock the Anthropic client entirely (no real API calls in tests)
- Use fixture files in `tests/fixtures/` for sample diffs
- Test truncation at the 8,000 token boundary
- Run: `npm test`

## Common Tasks
- Run locally: `ts-node src/index.ts < tests/fixtures/sample.diff`
- Build: `npm run build`
- Test: `npm test`
- Publish: `npm publish` (runs build first via prepublish)

Ready to generate your spec?

Paste your rough idea. Get a PRD, GitHub tickets, and CLAUDE.md like this — in under 30 seconds.

Generate my spec →
No account. No install. Free to try.