Spec Project: Taking a Feature From PRD to Test Evidence

A spec-driven workflow has a predictable ending. The agent works through the specification, writes the code, runs whatever checks the repository already had, and reports that the feature is complete. The specification says what the software should do. The code claims to do it. Nothing in between has been checked against a running application.

That gap is not an oversight in any particular tool. Specification frameworks are built to produce a plan an agent can execute, and they stop where execution stops. What happens after the last file is written belongs to a different job: proving the built software matches the document that described it, and keeping those two artifacts in agreement the next time the product changes.

Spec Project is an open-source agent skill that carries one feature through all three states: specification, implementation, and evidence. It runs inside a coding agent, works on its own with plain Markdown, and coordinates GitHub Spec Kit when a repository already uses it.

What the skill actually is

Spec Project is an orchestration skill, not a command-line tool. You install it into a coding agent and invoke it there, and it drives the agent through a lifecycle rather than doing the work itself. Install it with the skills CLI:

npx skills add ShiplightAI/quality/agent-skills --skill spec-project --all -y

The shape of the workflow is a single line from product intent to evidence:

product intent
    |
    v
PRD -> feature breakdown -> accepted feature spec -> plan and tasks
                                                    |
                                                    v
                                          tests and implementation
                                                    |
                                                    v
                                      verification and test report

The feature spec is the authority for product behavior. Code implements that behavior. Tests, verification, and reports provide evidence for it. When those three disagree, the skill reconciles the drift rather than assuming the newest artifact is correct, which is the failure mode of treating the codebase as documentation.

The operations

A bare invocation is a read-only status pass. It reports the detected mode, the active feature, the current phase, the artifacts it found, any drift, and the next gate. It creates no files, switches no branches, and runs no long test suites.

For a new project the first two calls establish intent, and you review what comes back before anything gets built:

/spec-project init
/spec-project lifecycle 001-user-sign-in

Acceptance of the feature spec is a gate before implementation. It is not acceptance of the implementation or of its evidence, which are separate states with separate gates.

Two modes, one lifecycle

Portable mode is the default. The agent follows whatever conventions the repository already has, or falls back to bundled Markdown templates when it has none. No specification tool is required.

Spec Kit mode activates only when the repository has a complete .specify/ setup, or when you explicitly ask for adoption. In that mode Spec Kit owns the constitution, the feature spec, the plan, the task list, and its own pointers, and the skill invokes Spec Kit workflows instead of hand-editing those files. A partial .specify/ installation is reported rather than silently repaired, and the skill will not install Spec Kit merely because it was invoked.

The mapping to the Spec Kit lifecycle is direct:

specify -> clarify -> checklist -> plan -> tasks -> analyze -> implement

Command spelling differs by agent. Codex installations tend to expose skills such as speckit-specify and speckit-plan, while other agents expose slash commands such as /speckit.specify. The skill inspects the initialized integration rather than assuming one spelling, which matters if your team runs more than one agent against the same repository.

The mode changes the mechanics. It does not change the lifecycle, and it does not change which artifact holds authority.

Who owns which artifact

The ownership map is the part worth reading closely, because it is where most spec-driven setups get vague.

Spec Project never writes the testing artifacts itself. That boundary is deliberate. If the Shiplight skill is unavailable, specification and implementation still proceed, the evidence phase stays incomplete, and the agent reports the handoff it could not make. A missing tool produces a stated gap rather than a green summary.

On the evidence side, /shiplight cover decides what kind of proof a change needs before it writes anything. Its operating principle is to choose the cheapest sufficient proof, which in practice means a deterministic YAML end-to-end test for a flow a browser can walk, and an agent verification for a journey where the state behind the UI also has to be judged. The tests it produces are readable YAML in your own repository, authored from intent rather than selectors.

Specs are snapshots, not changelogs

One design decision runs through the whole skill and is worth adopting even if you never install it: a feature spec describes the latest accepted state of the product, not a chronological log of how it got there.

When behavior changes, the skill updates the current requirements and removes superseded behavior, in both modes. Git already preserves history. Plans and release notes already carry migration detail. A spec that accumulates amendments stops being answerable, and the first person to lose is the agent reading it, which now has to infer current behavior from a sequence of changes.

The same discipline governs feature selection. Before creating a feature, the skill checks the existing roadmap and specs. A change that extends an existing capability stays with that feature even when the change is large, or when a ticket described it as new work. That is what keeps a spec directory from turning into a pile of overlapping documents six months in.

What it will not do without being asked

The safety boundaries are narrow and specific, which is what makes the skill usable on a repository with real work in progress:

• Product ambiguity stops the workflow for an owner decision instead of being resolved by the agent.
• Priorities are carried from an accepted source or recorded as UNKNOWN. The agent does not invent them.
• Branch creation, branch switching, commits, pull requests, merges, releases, and Spec Kit installation each require an explicit request.
• Existing uncommitted work and unrelated changes are preserved.

Where this is not the right fit

Honest scope, because it saves the install:

• Teams without an agent in the loop. This is a skill invoked inside a coding agent. If your team is not running one, there is nothing here that a well-kept template directory does not already give you.
• Single-feature repositories and throwaway projects. The PRD and breakdown layers pay off when features accumulate and start overlapping. On a project with one feature they are overhead.
• Teams whose specs are already disciplined and current. If your specs are genuinely maintained as snapshots and your definition of done already includes evidence, this formalizes a practice you have rather than adding one.
• The evidence phase needs a test producer. Specification and implementation work standalone. Producing test-spec.md, the tests, and test-report.md requires the Shiplight skill. Without it you get a reported handoff, not a report.

Getting the first feature through

The smallest useful sequence is three calls. Run the status pass to see what the skill detects, run init and review the PRD and breakdown it proposes, then take one feature through lifecycle and read what comes back at each gate. For a change to something that already exists, use maintenance and describe the behavior you want, and let the skill find every feature the change touches before it edits anything.

Shiplight installs into the same coding agent as a browser MCP server plus a set of skills, with a one-line install for Claude Code, Cursor, Codex, VS Code, and more. Authoring runs through the agent's own subscription over MCP and needs no Shiplight account. Running a test file with npx shiplight test needs an LLM key, either ours or your own.

Frequently Asked Questions