Specs your agent can actually follow.

A minimal spec-driven development framework for AI coding agents. Write a short spec, plan the tasks, and let the agent implement them.

Install BareSpec How it works

Plugin for VS Code, Copilot CLI and Claude Code. Compliant with Agent Plugins 1.0.0. MIT licence.

quick start

/init-context           # 1. Project context
/spec-create <feature>  # 2. Feature spec
/spec-plan <spec>       # 3. Task plan
/spec-implement <spec>  # 4. Build it

files it writes

barespec/
├─ context.md
└─ specs/user-auth/
   ├─ spec.yaml
   └─ plan.md

Install

BareSpec is published as a plugin through the alessioscarfone marketplace, which is this repository. Pick the tool you use.

VS Code (GitHub Copilot)

1. Add the marketplace to your user settings:

settings.json

"chat.plugins.marketplaces": ["AlessioScarfone/barespec"]

2. Open the Extensions view, search @agentPlugins, and install barespec.

Or run Chat: Install Plugin From Source from the Command Palette and enter:

repository URL

https://github.com/AlessioScarfone/barespec

GitHub Copilot CLI

terminal

copilot plugin marketplace add AlessioScarfone/barespec
copilot plugin install barespec@alessioscarfone

Claude Code

claude code

/plugin marketplace add AlessioScarfone/barespec
/plugin install barespec@alessioscarfone

In Claude Code, plugin skills are namespaced: use /barespec:spec-create instead of /spec-create.

Skills only (any agent)

terminal

npx skills add AlessioScarfone/barespec

Installs the skills without the plugin, for any agent that supports them.

Installed? Open your agent’s chat in a project and run /init-context. What happens next

Usage: four steps, one loop.

BareSpec splits a feature into a contract and a checklist. A feature moves through four slash commands, and each one writes a file the next one reads.

context.md holds the project background every skill reads. spec.yaml is the requirement contract for one feature, and plan.md is its ordered task checklist. The agent implements the plan task by task and records what changed.

Every step reads and writes plain files in your repo, so you can stop after any command and pick up later.

Pre and post hooks can run around every step. Set them up with /init-config.

01 /init-context context.md
02 /spec-create spec.yaml · draft
03 /spec-plan plan.md · ready
04 /spec-implement in-progress → done

FeedbackWhen a spec is done, /spec-implement updates context.md (back to 01).
Optional/spec-visualize after 02 or 03 renders the spec and plan as visual.html. Read-only.
Optional/spec-code-review after 04 reports on the diff. Read-only.

Every command is described in the command reference.

Status follows the work.

The status field in spec.yaml tells you, and the next skill, where a feature stands.

draft
set by /spec-create

Spec contract written, no plan yet.
ready
set by /spec-plan

Plan generated, ready to implement.
in-progress
set by /spec-implement

Implementation started.
done
set by /spec-implement

Implementation completed.

A spec whose requires list names specs that are not done cannot be implemented yet. When a spec finishes, BareSpec reports which dependent specs are now unblocked.

Add your own steps.

Hooks are plain-text instructions the agent follows before or after a skill. There are no scripts to maintain.

Hooks live in barespec/barespec.config.yml, which /init-config creates. Each of the six steps takes a pre and a post list: context, spec, plan, implement, review and visualize.

pre hookse.g. check git status
the skillany BareSpec step
post hookse.g. run lint and tests

The config file is optional. Without it, every skill runs without hooks.

barespec/barespec.config.yml

hooks:
  spec:
    pre:
      - "Check that the git working directory
         is clean before creating the spec."
  implement:
    pre:
      - "Run the existing test suite and confirm
         it is green before starting."
    post:
      - "Run 'npm run lint && npm test' and fix
         any failures before closing the spec."

What lands in your repo.

Everything lives in one barespec/ folder, so it is easy to review, commit or ignore.

context.md is shared by every skill.
spec.yaml holds the requirements for one feature, plan.md its tasks.
visual.html exists only if you ran /spec-visualize. Committing it is up to you.

your-project/

your-project/
└── barespec/
    ├── context.md
    ├── barespec.config.yml   # optional
    └── specs/
        ├── user-authentication/
        │   ├── spec.yaml
        │   ├── plan.md
        │   └── visual.html   # optional
        └── csv-export/
            ├── spec.yaml
            └── plan.md

Command reference

Run the skills as slash commands in any compatible AI coding agent. Each step builds on the file the previous one wrote. The examples below are illustrative.

1.0 Capture the project

/init-context

Creates or updates barespec/context.md, the file every other skill reads for background: product, architecture, tech stack and non-functional requirements.

The skill inspects your codebase first, then interviews you in rounds to close the remaining gaps. Run it again after a feature changes the architecture or stack.

barespec/context.md

# Project Context

> Last updated: 2026-10-15

## Product

**Name**: inventory-api
**Description**: REST service that tracks stock levels
for the warehouse team.

## Tech Stack

- **Language(s)**: TypeScript
- **Framework(s)**: Fastify
- **Testing**: Vitest

2.0 Write the feature spec

/spec-create <feature>

Defines the requirement contract in barespec/specs/<name>/spec.yaml, with status draft. Requirements are grouped into components, and each one gets an ID such as user-auth.LOGIN.1-1 that the plan refers to later.

If the spec already exists you can update it or start a new one. Updating resets it to draft so the plan can be regenerated.

barespec/specs/user-auth/spec.yaml

feature:
  name: user-auth
  status: draft
  requires: []

components:
  LOGIN:
    name: Email login
    requirements:
      1: A registered user can sign in with
         email and password.
      1-1: A wrong password returns an error
         without revealing if the email exists.

3.0 Plan the work

/spec-plan <spec-name>

Breaks the spec into ordered, testable tasks in plan.md. Every task carries the requirement IDs it satisfies and a check for when it is done.

You confirm the breakdown before it is written, and the spec moves to ready. If a plan already exists you choose between regenerating it and appending tasks.

barespec/specs/user-auth/plan.md

### 1. Login endpoint
- [ ] 1.1 Add POST /login handler. _(LOGIN.1)_
- [ ] 1.2 Return a generic error on a wrong
      password. _(LOGIN.1-1)_
- [ ] 1.3 Checkpoint: run unit tests

4.0 Build it

/spec-implement <spec-name>

Works through plan.md task by task, checking each one off, and moves the spec from in-progress to done. Run it again to resume from the first unchecked task.

It stops if the spec is still draft or if a spec listed in requires is not done. On completion it updates context.md and records development notes.

barespec/specs/user-auth/plan.md

### 1. Login endpoint
- [x] 1.1 Add POST /login handler. _(LOGIN.1)_
- [x] 1.2 Return a generic error on a wrong
      password. _(LOGIN.1-1)_
- [ ] 1.3 Checkpoint: run unit tests

5.0 Review the diff

/spec-code-review [fixed-point] [spec-name]

Optional and read-only. Reviews the diff between HEAD and a fixed point (a commit, branch or tag) along two independent axes, coding standards and spec, each run by its own sub-agent. With no fixed point it reviews your uncommitted changes.

It reports findings and never edits code, checks off tasks or changes a spec’s status. The spec comes from the argument, the branch name or a recently updated spec; with none, give a one-line description of the intent instead.

examples

/spec-code-review                   # uncommitted
/spec-code-review main user-auth   # since main
/spec-code-review v1.2.0           # since a tag

6.0 See the spec

/spec-visualize [spec-name]

Optional and read-only. Renders a spec and its plan as visual.html: status, version and dates, a requirement tree with a coverage badge on every ID, a traceability matrix, task states, and warnings for inconsistencies.

The page is self-contained, works offline and follows your system theme. Click an ID to highlight it in every view. A spec without a plan still renders, with a “No plan yet” banner, and each run overwrites the file.

Open the example page

Generated from an invented user-auth spec: spec.yaml and plan.md.

example

/spec-visualize user-auth

barespec/specs/user-auth/visual.html

7.0 Customize the workflow

/init-config

Optional. Creates or updates barespec/barespec.config.yml, the file where you write custom instructions to run before or after each BareSpec step. If the file exists it shows your current hooks and asks whether to update them or reset to the default template.

It then asks about every hook slot in one go and writes only the events that have an instruction. What hooks are and which steps accept them is covered in Hooks.

barespec/barespec.config.yml

hooks:
  context:
    pre:
      - "Check whether a context.md already exists
         in a non-standard location and warn me."
  plan:
    post:
      - "Summarize the task count and estimated
         scope back to me."
  review:
    post:
      - "Write the findings and action items to
         review-summary.md in the spec folder."
  visualize:
    post:
      - "Open the generated visual.html in the
         default browser."

barespec-guide is a background skill, not a command. Agents load it automatically when a conversation mentions BareSpec.