Why SimpleSpec?

Most AI coding workflows break down in the same place: unclear intent.

SimpleSpec gives you a lightweight, repeatable structure for defining what to build before generation starts. It helps your agent ship work that is:

• ✅ Aligned with your actual requirements
• ✅ Consistent across features and contributors
• ✅ Easier to review, test, and iterate

What it does

SimpleSpec helps you:

• Create structured feature specifications
• Apply specs in a consistent implementation workflow
• Reduce ambiguity between product ideas and generated code
• Improve output quality from your AI runtime of choice

Quick start

npx simplespec@latest

That’s it. Follow the guided flow and start building with clearer direction.

Test the packaged dist artifact locally

Use this before publishing to ensure the same tarball users get from npm works end-to-end.

npm run dist:test

This will:

• run npm run prepack
• create a temporary sandbox outside the repository
• build and pack the artifact in the sandbox
• install that tarball in a dedicated smoke project
• run npx simplespec --help as a smoke test

How to use

Create a spec

Use this command as your core workflow. This will generate a structured feature specification based on your input. The agent will ask you for additional details when needed.

Create a new spec from an idea

/spec-new Build a task dashboard with filters, sorting, and bulk actions

This generates a structured spec under .simplespec/specs/ with clear requirements, acceptance criteria, and implementation tasks.

/spec-new will ask if you want to continue directly into implementation.

Implement a spec

Use this command to implement a spec. If the command is sent in the same context as the spec creation, you do not need to specify the spec ID. Otherwise, provide the ID of the spec you want to implement.

/spec-apply spec:<id>

Telemetry optout

Pass --no-telemetry to disable telemetry for a run.

Verbose installer logs

Pass --verbose (or -v) to print detailed installer progress, including directory mappings and file-level copy/symlink operations.

Built for the AI era

SimpleSpec is designed for modern, agent-assisted development:

• Human-readable specs
• Repeatable execution patterns
• Better prompts through better structure

When your specs are clear, your code gets better.

License

MIT — see LICENSE.