SpecPunk is a repository-first runtime for AI-driven engineering work across codebases. It is built around bounded execution, deterministic gate semantics, proof-bearing decisions, and a small operator-facing surface.

​
At a glance

SpecPunk is designed for engineering work that needs to be:
  • bounded
  • inspectable
  • contract-first
  • proof-bearing
  • local-first
The public surface is intentionally small:
  • one CLI: punk
  • one vocabulary: plot / cut / gate
  • one final decision writer: gate

​
Why it exists

SpecPunk is not trying to be a provider-zoo shell, a broad hosted control plane, or an always-on swarm interface. It exists to make AI-assisted engineering work more legible, safer to operate, and easier to verify at the repository level.

​
Current status

SpecPunk is in an active rebuild phase. These docs describe the current operator path and keep it separate from inactive or future surfaces. Today:
  • punk is the public CLI
  • the active v0 path is init -> start/go -> plot -> cut -> gate -> proof
  • punk-council is in-tree but inactive
  • punk-shell, punk-skills, punk-eval, and punk-research are planned only

​
Start here

If you are new to the project, use this order:
  1. Install
  2. Quickstart
  3. CLI reference
  4. Roadmap
  5. Repo status

​
Scope of this site

This site is a public, curated layer over the repository. It focuses on:
  • what SpecPunk is
  • how to run the current CLI
  • how the current operator path works
  • what is current today
  • what is on the roadmap
Internal research notes are intentionally not part of the public docs.