Documentation Menu

Contributing to SpecMarket

SpecMarket is built with specs. The entire platform — CLI, backend, web frontend — was generated by Ralph Loops running against structured specifications. Contributing follows the same pattern: define what you want to build, validate it, and ship it.

There are four ways to contribute, ordered by impact.

1. Publish Specs

The highest-impact contribution is publishing specs that replace SaaS tools. Every published spec with a solid success rate directly reduces someone’s monthly software bill.

What makes a good spec:

  • Replaces a real SaaS product people are paying for
  • Has clear, testable success criteria (not vague goals)
  • Includes infrastructure requirements so the output runs in production
  • Targets an 80%+ success rate across multiple runs
  • Honestly describes what percentage of the SaaS it replaces

Quick start:

specmarket init --name my-spec
# Edit the generated files
specmarket validate ./my-spec
specmarket run ./my-spec    # Test it locally
specmarket publish ./my-spec

See the Publishing Guide for the full 9-step workflow with code examples for every file.

Earning from specs: When users run your spec through managed cloud runs, you earn 30% of the margin. Specs with high success rates and many runs generate ongoing income. The platform tracks creator reputation based on cumulative run quality.

2. Fund and Claim Bounties

Bounties connect demand with supply. If you need a SaaS replacement that doesn’t exist as a spec yet, fund a bounty. If you’re a spec creator looking for high-value targets, claim one.

Funding a bounty:

Browse open bounties at specmarket.dev/bounties or create a new one. Contributions go through Stripe checkout. Multiple people can fund the same bounty — the total grows as more people want the same replacement.

Claiming a bounty:

  1. Find an open bounty that matches your skills
  2. Submit a spec that meets the bounty’s requirements
  3. The community evaluates submissions based on success rate and completeness
  4. The bounty creator approves a winner
  5. Funds are distributed to the winning spec creator

Current top bounties are listed on the bounties page. The most requested categories: project management tools, design-to-code workflows, and billing systems.

3. Report Issues and Improve Docs

Reporting bugs:

  • For CLI issues: include the command you ran, the error output, and your Node.js version
  • For spec issues: include the spec ID, run ID, and which success criteria failed
  • For platform issues: include browser, OS, and steps to reproduce

File issues on GitHub. Include the specmarket report <run-id> output when relevant.

Improving documentation:

Documentation lives in apps/web/src/content/docs/ as Markdown files. Every doc page has a lastVerified field — if you find something outdated, update it.

To contribute a doc fix:

git checkout -b docs/fix-description
# Edit the relevant file in apps/web/src/content/docs/
git add apps/web/src/content/docs/your-file.md
git commit -m "docs: fix description of the change"
git push -u origin docs/fix-description
gh pr create --title "docs: fix description" --body "What was wrong and what this fixes"

4. Run Specs and Submit Telemetry

Every run with telemetry enabled helps the community. Run reports contribute to:

  • Success rate tracking — Helps other users know which specs work
  • Cost benchmarking — Real cost data across models and specs
  • Stall detection — Identifies specs that need improvement
  • Model comparison — Which models work best for which spec types

Enable telemetry:

specmarket config set telemetry true

No source code is ever transmitted. Only metadata: spec ID, model, tokens, cost, time, status, and success criteria pass/fail. You can delete all your data at any time with specmarket config delete-telemetry.

Development Setup

If you’re contributing to the platform itself (CLI, backend, or web frontend):

Prerequisites:

  • Node.js 20+
  • pnpm 8+

Clone and install:

git clone https://github.com/specmarket/specmarket.git
cd specmarket
pnpm install

Project structure:

specmarket/
├── packages/cli/          # CLI tool (@specmarket/cli)
├── packages/convex/       # Convex backend (@specmarket/convex)
├── packages/shared/       # Shared validators and types (@specmarket/shared)
└── apps/web/              # Astro + React web frontend

Build and test:

# Shared library (build first — CLI and Convex depend on it)
pnpm --filter @specmarket/shared build
pnpm --filter @specmarket/shared test    # 17 tests
 
# CLI
pnpm --filter @specmarket/cli build
pnpm --filter @specmarket/cli test       # 20 tests
 
# Convex backend
pnpm --filter @specmarket/convex typecheck
pnpm --filter @specmarket/convex test    # 292 tests
 
# Web frontend
pnpm --filter @specmarket/web dev        # Local dev server
pnpm --filter @specmarket/web build      # Production build

Total: 329 tests across 14 test files. All tests must pass before submitting a PR.

Convex testing notes:

Tests use convex-test with the anyApi proxy for function references. If your mutation schedules follow-up functions, use vi.useFakeTimers() in beforeEach and drain with t.finishAllScheduledFunctions(vi.runAllTimers).

Code of Conduct

  • Be helpful. Answer questions. Share what you know.
  • Be honest. Don’t fabricate metrics or claim specs replace SaaS features they don’t cover.
  • Be respectful. Critique code and specs, not people.
  • Don’t spam. If your contribution is primarily self-promotion, it will be removed.