cospec

A small set of agent skills for building, executing, and archiving work specifications. It also includes a local web interface for reading and commenting on what the skills write. Everything the skills produce is markdown on disk: there is no state machine and no schemas.

Install

npx cospec

With no arguments, it shows a short menu based on your situation: you can install the skills, update them when the installed ones are older than the package, or start the web interface. The skills follow the open Agent Skills format, so they work with any compatible agent. Suggested targets include the cross-agent standard (./.agents/skills, ~/.agents/skills - read by Codex, Cursor, OpenCode, Warp, and more) and the per-tool directories (.claude/skills, .opencode/skills, .cursor/skills), plus any custom path. You can also skip the menu: npx cospec ./.agents/skills installs straight into that directory.

Run the same command to update: npx cospec@latest (the @latest matters, because npx may otherwise reuse an old cached version). The version of the installed skills comes from their own SKILL.md, and the menu can tell you what you have and what this package includes. When skills exist in more than one place, it asks which set to work on. If the skills already exist at the chosen location, the installer says so and asks before it replaces them. Every install and update ends with one line asking you to run /cospec-config, which checks your settings file against the one this version ships.

Publishing (maintainers)

pnpm release

The script shows the version published on npm next to the one in package.json, then suggests the next patch, minor, and major versions. Pick one, or type your own. After you confirm, it builds the engine and writes the version into package.json and into the cospec skill's frontmatter. It commits these files together with the built output in one commit ("Release x.y.z") and publishes. The built engine ships with the package, so nobody needs to install or build anything to use the web interface. If you are not logged in to npm, it starts npm login for you (browser authentication) and continues afterward. It refuses to run with uncommitted changes, and it refuses a version that is already published.

In this repo, .claude/skills/ holds symlinks into skills/, so a session here always runs the current skills, which makes it easy to test them before a release. The web interface's source lives in engine/ (Vite, React, TypeScript, Vitest). pnpm engine:serve <directory> builds it and serves that directory from a checkout. pnpm verify runs Biome, both typecheck passes, and the engine's tests.

The skills

/cospec - build or resume a spec

It starts by asking what you want to work on and lets you share everything you know. Then it works out which stages the work needs and confirms them with you in a multi-select. That confirmed set is the protocol. The stages run in the order below, and imagination mode is the one thing that changes it. The available stages are:

1. High-level exploration - think together before committing.
2. Interview - a relentless, codebase-aware search for every unresolved doubt. It checks a fixed set of ambiguity categories and adds each answer to the spec as it goes.
3. Research - outside knowledge gathered before technical decisions, sized to the work. Deciding findings are written as decision, rationale, and alternatives. A comparison is included when there is more than one viable technical choice.
4. Codebase analysis - ground the spec in the real code.
5. Technical specs - the spec itself, with testable requirements. Each requirement that a plan or a review will use gets a stable ID and an acceptance criterion. The spec includes the decisions and their rejected alternatives, and an optional non-binding solution sketch.
6. UI mocks - clickable HTML pages, one standalone file per screen, revised in place until approved.
7. Execution plan - phases sized so each fits one session. Each phase names the requirements it covers. The plan states how it honors your principles and includes a table for any justified deviation.
8. Quality review - fresh helper agents review the spec, the research, the plan, and the screens with no shared context. The clear findings are fixed, and judgment calls come to you along with the reviewer's reasoning. You confirm the review panel first: one reviewer per focus, sized to the work. You can change it or turn the review off. The report goes into the spec directory as review/REVIEW.md. You decide on each open finding at the gate.

Imagination mode. When the work starts with exploration or with screens, it offers you a wider way round. A normal run narrows from the first question. This one holds the space open on purpose and narrows late. Exploration asks what the ideal would be if everything were possible, and it keeps feasibility out of that first pass. The interview asks about the ideal experience before it asks about constraints. The screens stage opens with a fan-out: many deliberately different candidates, each on a named axis, and a gallery page where you tick the ones worth keeping. The ones you keep become the mocks and go through the normal review loop; the rest stay on disk as a creative record. With the mode on, the screens are settled before the spec is written, so the spec follows the direction you chose, and it records the ideal it reached for as a north star for whoever builds the work. You can also turn the mode on at any time by naming it, up to the moment the spec is written.

Every user interaction goes through the question tool, and every stage is gated. A round of questions too big for that tool goes on an HTML page in the spec directory instead: you answer it in your browser and paste the result into a comment, and the page is deleted once the answers are in. As soon as the spec directory exists, it tells you the files are there and helps you get npx cospec open. If you would rather read the files yourself, it gives you file paths at every gate instead. Progress is written to disk as it happens, so you can drop a spec mid-way and resume it later, in any session, with any agent. A spec cannot be finalized while a clarification marker is still open. Any ambiguity the spec left marked is presented to you as a question first. When the review stage ran, finalizing does not read the whole spec again: it re-reads only what the reviewers never saw, the fixes the review made and the changes your decisions asked for, and then it does the marker check. Once you finalize the spec, it offers to commit the spec directory for you. Everything else in your working tree stays unchanged.

The web interface. npx cospec starts a local page over the spec directory: it reads the files from disk and renders each one, with documents split into their ## sections, mock screens shown in frames at desktop, tablet, and mobile width, and images shown inline. It gives you a comment box on every one of them, with support for pasted screenshots, attached files, and dictation. One Send writes your comments into the spec directory as .cospec/user-feedback.json, and the attachments go beside it as real files. The agent applies them and revises the work. Nothing is generated for the page, and nothing has to be kept in step with it: the page reads the files themselves and updates as they change on disk, so a tab left open all day is still current.

It renders any directory, not only a spec: you can point it at a folder of notes, drafts, or images, and it reads and takes comments on that just as well. Marking a section as read folds it away, but this is never approval: a section whose content changed since you read it comes back unfolded, and it says so. Everything the page itself writes lives in one .cospec/ directory inside the work it belongs to. Dot-prefixed entries are never rendered, and archived work is rendered read-only. The server binds to localhost, and it includes a token in the URL it prints. It never modifies the files it renders. The gates stay in chat: the page is input, and the gate is the decision.

/cospec-execute - implement the plan

Every run works the same way: one loop, one phase at a time. The agent writes the phase's detailed task list, implements it, verifies it, records it, and commits it, all by itself. The only subagents are reviewers, so that whoever judges the work did not do it. Between phases, the agent keeps everything it learned, and it settles what it can on its own: review findings, word choices, and which of two fixes reads better. It stops for you only when the work deviates significantly from the spec. It also stops when a blocker needs a decision only you can make, and when it cannot proceed for technical reasons.

Two choices made at spec time steer the run. Both are recorded in the plan and honored on every run:

• Pauses - where the run stops so you can look at the result before later phases build on it. This can be nowhere, after phases you name, or after every phase. At a pause, the run reports what the phase produced and waits for your go-ahead. Stopping there ends the run. A later run picks up at the next unfinished phase.
• Review checkpoints - where fresh reviewers judge the work: after phases you name, and at the end. Each checkpoint includes its own panel, which specifies how many reviewers there are and what each one focuses on (correctness against the spec, security, performance, or whatever the work calls for). The recommendation always includes the final whole-work panel, and it adds a mid-run checkpoint only where a phase getting it wrong would send later phases wrong. You can adjust it or decline review altogether.

Only phase boundaries, goals, and definitions of done are planned in advance. Each phase's detailed task list is written just before that phase runs, against the code as it exists by then. Each phase is verified against its own verify steps, and checkboxes are ticked as work lands. The spec is updated whenever reality ends up different from the plan.

Every phase file carries a status line (in progress, done).

Committing is chosen at spec time and recorded in the plan as Commits: none | single | per phase, alongside Branch: current | <branch name>:

• per phase - each phase is committed as soon as its verify steps pass, so after an interruption, done means committed, and uncommitted changes always point at the phase that was cut off.
• single - nothing is committed until the last phase is done, and then the whole change lands in one commit.
• none - nothing is committed at any point; everything stays in your working tree.

The commits land on your current branch, or on a branch created for the work when you asked for one at spec time. The branch is created or switched to before the first phase. Merging it back stays your call. Every commit message any skill makes follows the commit style saved in principles.md: your project's own shape, or the default style when none is set.

A review checkpoint spawns one code reviewer per planned focus, as subagents with no shared context, and they check the work so far against the spec and the plan. When commits are on, the final checkpoint never runs against an uncommitted tree. With Commits: single, the one commit lands first, and fixes that come out of a checkpoint follow as a follow-up commit. The executing agent merges the findings, then fixes and re-verifies the real ones itself, and it says in the report what was dismissed and why. The reviewers read your principles file alongside the spec and the plan.

The plan is binding on the run. This includes the commits and the branch, the pauses, the review checkpoints, the verify steps, and the principles check with any deviation it records. A deviation you approved is built that way, not quietly put back to the principle. When a run cannot do something the plan asks for, such as spawn the reviewers it names, run a verify command, or reach a tool it needs, it stops and asks you. It does not quietly do a smaller version of the task instead.

/cospec-archive - sign off

This is your confirmation that a spec is implemented. It warns about anything unchecked, but never blocks on it. When the work ran on a dedicated branch and commits landed there after execution finished, it reads what those commits changed, and it offers to bring the spec in line when they left it out of date. On a dedicated branch, archiving belongs before you merge, which is why the /cospec-execute report tells you so when a run finishes the last phase there. That check only works while the work is still on its own branch. Archiving first means the merge includes the archived spec with it. It stamps the completion date and moves the directory to cospec/archive/YYYY-MM-DD-<slug>/. Once the move is done, it offers to commit that move, scoped to the archive change alone. The archive is the documentation trail of what was built and when.

/cospec-config - your preferences

One markdown file, principles.md, sits at the cospec root and is read by every skill before it starts. It holds a settings section and a principles section, and nothing else is generated or managed in it. It carries only the values and the principles, with no explanation of either, because every skill reads it on every run, so it holds only what an agent must honor. What each setting means is documented here and inside /cospec-config.

The settings, one - key: value bullet each:

• commit_style - how every commit message the skills make is written: your project's own shape, described in plain words with an example, or the default style.
• commit_mode, commit_grouping, branch_naming - saved answers for the planning questions about commits and branching. A saved answer skips its question at spec time, while the plan still records the outcome.

The principles section holds plain-English engineering principles and rules that every skill reads at the start of a run and honors on a best-effort basis. They steer the agents, and they are not enforced checks. Each principle states its reason when the reason is not obvious. A principle scopes itself in its own sentence when it should not apply everywhere. Rules already written in your own documents (CLAUDE.md, AGENTS.md, and similar files) are pointed at and declared binding, but never copied in.

Run /cospec-config to view and change any of it through questions, or edit the file by hand. It also checks your file: it compares your file with the one this version of cospec ships, and walks you through what is missing, what holds a value it does not know, and what you deliberately removed. Your settings and your principles are never overwritten, and anything you took out stays out unless you ask for it back. A skill that finds no file at all offers the one-time setup on the spot. It proposes a commit style derived from your project's own commits. It offers to draft the principles from your project: your rule documents, the README, the lint and CI setup, and recent commits. Or it can start with none and add them later. Nothing else about the file is ever repaired mid-run: a run you are waiting on reads what parses, falls back to the defaults for the rest, and says so in a line.

On-disk layout

All state lives under the cospec root: a cospec/ directory next to the project the skills are installed for. Skills installed under a project's agent directory (<project>/.claude/skills/, <project>/.agents/skills/, or similar) put the root at <project>/cospec/. In a monorepo with the skills at apps/shop/.claude/skills/, specs live under apps/shop/cospec/. Skills installed under your home directory put the root at cospec/ in the workspace root.

There is one directory per stage that produces a document, each holding that document in uppercase with any supporting artifacts beside it:

cospec/
  principles.md          your settings and principles, owned by /cospec-config
  <slug>/
    README.md            confirmed stages and status - the resume point
    spec/
      SPEC.md            the specification
      *.md, *.svg, ...   what you shared while collecting, and visuals written beside the spec
    research/
      RESEARCH.md        research findings (if selected)
    mocks/               UI mocks (if selected)
      <mock-id>.html     one standalone page per mock screen, revised in place
      candidates/        imagination mode's candidate screens; those you do not choose stay here as a record
    plan/
      PLAN.md            overview: Commits:, Branch:, Pauses:, Review checkpoints:, the principles check, and the phases with definitions of done and the requirement IDs they cover
      phase-NN-<slug>.md one per phase: status, tasks, verify steps (written during execution, just before its phase)
    review/
      REVIEW.md          the quality review report (if selected)
    .cospec/             what the web interface writes: your feedback, its attachments, and the page's own state
  archive/
    YYYY-MM-DD-<slug>/   signed-off specs, rendered read-only

A stage directory appears when its stage produces its document. The web interface renders whatever it finds. The layout is a convention of the skills, not something the code depends on. An executing agent loads PLAN.md plus the one phase file it is working on, never the whole plan.

Design principles

• The protocol is decided per piece of work and confirmed by the user, not fixed by the tool.
• Markdown for agents is the same markdown rendered for humans: one source of truth, read two ways.
• The web interface understands no cospec format. It renders a directory.
• Nothing it shows can go stale, and nothing it reads needs a version.
• State is markdown with checkboxes; any agent can read it, any session can resume it.
• Questions with fixed answers are written into the skills word for word, so you are asked the same way every time.
• Specs are written for a fresh agent who never saw the conversation.
• The plan is the user's instruction and is binding on the run.
• An executor that cannot carry out a part of the plan, or that finds a part wrong against the real code, stops and raises it. It does not quietly build something smaller.
• There are four skills, and nothing else.