Stop Looks-Right Failures with Spec-First Agent Skill

Where this fits

You ask your agent to "add team permissions to the dashboard." The agent immediately writes a few files, the app compiles, and everything looks fine—until you notice a second admin can't revoke a teammate's access. That is the "looks right" failure: the agent optimized for code completion instead of requirements verification. spec-first intercepts this by forcing a spec → plan → execute → verify loop before any code is written, turning vague build requests into explicit artifacts and checklists.

Why agents benefit

• It replaces silent pattern-matching with a visible decision process: before coding, the agent outputs three approaches and tradeoffs, so you can catch bad assumptions early.
• It creates durable artifacts—spec-[feature].md, decisions-[feature].md, and todo.md—under .agents/memory/, giving future sessions real context instead of relying on chat history.
• Each todo item includes a per-step verification command, so the agent can prove a change works, not just claim it compiles.
• It adds confirmation gates before GitHub Issue creation and before execution, keeping the agent from shipping implementation before you approve scope.
• The generated GitHub Issue checklist becomes a live tracking surface outside the chat, useful for reviews and handoff.

Practical scenarios

Building a multi-file feature with ambiguous requirements

When a user says "implement search with filters," spec-first forces a written spec with assumptions around pagination, indexing, and result ranking. The agent creates todos with checks like "run pytest for search filter tests" before touching code.

Refactoring a legacy module

A refactor request often has unclear success criteria. The skill frames alternatives—strangler pattern, full rewrite, incremental extraction—and records tradeoffs in decisions.md. That prevents a "successful" refactor that regresses an obscure behavior.

Scaffolding a new project

For "create a new service that ingests webhooks," spec-first produces a spec artifact, a todo.md checklist, and a GitHub issue with tracking. The developer can review the plan while the agent waits at the confirmation gate.

Add it to your agent workflow

Install the skill:

npx skills add shipshitdev/skills --skill spec-first

Then request something deliberately vague:

build a user settings page with avatar upload and notification preferences

The skill should create .agents/memory/spec-user-settings.md, a todo.md checklist with verification commands, and a decisions-user-settings.md log—then pause before execution for your approval.

Compare before adopting

Compare this skill across quality signals: Is the repo maintained, and are issues closed? Does the artifact structure fit how you already work? Alternatives like simple "planning" prompts may be enough for small tasks. For this skill, the concrete value is the three-stage framing plus durable memory, so check whether your agent can reliably write to .agents/memory/ and the gh CLI path for issues.

Why it is worth tracking

spec-first is a small but focused skill (35 stars) from shipshitdev, and its value is less about popularity and more about solving a specific failure mode: "looks right" code that misses hidden requirements. Watch the repo for version bumps, decision-log templates, and maintainer responses to issues; that tells you whether the skill is keeping up with agent workflows. If your agents routinely skip verification or drift on multi-file requests, this is a signal to evaluate spec-first now. For a fuller comparison of spec-first against other planning skills, visit https://www.openagentskill.com/skills/shipshitdev-spec-first.