Bootstrap spec-compliant open source repos

One command produces a complete project — LICENSE, README, AGENTS.md, CI workflows, docs, website, and more. All derived from OSS_SPEC.md. AI-optional via zag.

AI-Optional5 LanguagesSpec-DrivenAgent-FriendlySelf-Dogfooding

Get Startedcargo install oss-spec

Everything you need to bootstrap open source

From AI-powered project creation to spec conformance validation — 7 commands cover the full lifecycle.

🚀

One Command to a Real Repo

Run oss-spec init with a prompt like "create a python cli for stock analysis" and get a complete project — LICENSE, README, AGENTS.md, CI, docs, website, and more.

📜

Spec is the Source of Truth

Every file is derived from OSS_SPEC.md — a 21-section prescriptive specification. Run `oss-spec validate` to see exactly which items a repo is missing.

🧠

AI is Optional

With --no-ai you get a deterministic skeleton from flags alone. With the default flow, zag interprets a freeform prompt into a structured manifest. Same engine either way.

🌍

5 Languages

Supports rust, python, node, go, generic. Each language gets idiomatic project structure, build tooling, and CI configuration out of the box.

🤖

Agent-Friendly (§12)

Generated repos ship with the full CLI discoverability contract: --help-agent, --debug-agent, commands, docs, and man — so coding agents can self-serve.

🔧

Remote Validate & Fix

Point validate or fix at any git URL with --url. Add --create-issues to automatically file one GitHub issue per violation. Works on repos you don't own.

🐶

Self-Dogfooding

oss-spec is its own first customer — `oss-spec validate .` against the oss-spec repo passes. The tool eats its own dog food.

📖

Embedded Docs & Man Pages

Every generated project includes embedded documentation accessible via `docs` and `man` subcommands. No external dependencies needed.

📦

4 Project Kinds

Choose from lib, cli, service, webapp. Each kind gets appropriate structure — a CLI gets a manpage, a service gets health checks, a library gets API docs.

Three steps to a real repo

Describe what you want, bootstrap the project, ship it.

Describe

Tell oss-spec what to build

Use a freeform prompt or explicit flags. The AI flow interprets your intent via zag; the --no-ai path uses flags directly. Either way you get a structured manifest.

oss-spec init "create a go service for user auth"

Bootstrap

Complete repo generated

oss-spec writes every file the spec mandates: LICENSE, README, AGENTS.md (with all agent symlinks), CONTRIBUTING, SECURITY, CI workflows, docs, website skeleton, language manifest, Makefile, and more.

my-project/
  LICENSE          README.md
  AGENTS.md        CLAUDE.md -> AGENTS.md
  CONTRIBUTING.md  CODE_OF_CONDUCT.md
  SECURITY.md      CHANGELOG.md
  Makefile         .editorconfig
  src/             docs/
  .github/         website/
  prompts/         scripts/

Ship

git init, gh create, ready to go

oss-spec initializes the git repo, makes the first commit, and creates the GitHub remote. Your project is live and CI is already running.

$ cd my-project && git log --oneline
a1b2c3d Initial commit (oss-spec bootstrap)

$ gh repo view --web
Opening github.com/you/my-project...

Driven by OSS_SPEC.md

Every generated file traces back to a section of the spec. Run oss-spec validate to validate any repo against it.

my-project/

LICENSE

README.md

CONTRIBUTING.md

CODE_OF_CONDUCT.md

SECURITY.md

AGENTS.md

CLAUDE.md-> AGENTS.md

.cursorrules-> AGENTS.md

.windsurfrules-> AGENTS.md

GEMINI.md-> AGENTS.md

CHANGELOG.md

Makefile

.gitignore

.editorconfig

src/

docs/

getting-started.md

configuration.md

architecture.md

troubleshooting.md

.github/

workflows/

ci.yml

release.yml

version-bump.yml

pages.yml

ISSUE_TEMPLATE/

PULL_REQUEST_TEMPLATE.md

copilot-instructions.md-> AGENTS.md

prompts/

scripts/

website/

Conformance checks (32 items)

fileLICENSE

§2

fileREADME.md

§3

fileCONTRIBUTING.md

§4

fileCODE_OF_CONDUCT.md

§5

fileSECURITY.md

§6

fileAGENTS.md

§7

fileCHANGELOG.md

§8.4

file.gitignore

§19

file.editorconfig

§19

fileMakefile

§9

Get started in seconds

Install oss-spec and you're ready to bootstrap projects or validate existing repos.

From crates.io

Requires Rust 1.85+

cargo install oss-spec

From source

Build from latest source

git clone https://github.com/niclaslindstedt/oss-spec
cd oss-spec && cargo install --path .

GitHub Releases

Pre-built for major platforms

# Download pre-built binary from
# github.com/niclaslindstedt/oss-spec/releases

Prerequisites

Rust 1.85+(required)curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

zag CLI(optional)cargo install zag-cli

gh CLI(optional)brew install gh / apt install gh

Command reference

oss-spec initBootstrap a project. Without `--name`, fills the current directory (or `--path`); with `--name NAME`, creates `<path|cwd>/<NAME>` and bootstraps there. A freeform prompt triggers zag interpretation; without one, runs the interactive interview.

oss-spec validateValidate an existing repo against the §19 checklist. With `--url`, clones a remote repo into a temp dir first. With `--create-issues`, files one GitHub issue per violation after reporting. By default, also runs an AI quality review of file contents (skip with `--no-ai`). With `--fix`, automatically fixes all findings.

oss-spec fixBring an existing repo into OSS_SPEC.md conformance via a zag agent. Without flags: edits files in place to remove every §19 violation. With --create-issues: instead files one GitHub issue per violation cluster via `gh` (no source files are touched).

oss-spec fetchClone the public oss-spec repository into a local directory so a coding agent (or you) can browse OSS_SPEC.md, the templates, and the dogfood implementation locally as a reference.

oss-spec commandsList CLI commands in stable, machine-readable form (§12.4).

oss-spec docsPrint an embedded docs/ topic (§12.3). No arg lists topics.

oss-spec manPrint an embedded manpage (§12.3). No arg lists commands.

Try it out:

$ oss-spec init --name hello-world --lang rust --kind cli --no-ai -y