{"slug": "show-hn-specification-first-agentic-development-plugin-and-prove", "title": "Show HN: Specification First Agentic Development Plugin and Prove", "summary": "A developer released a Show HN plugin called Spec-First for agentic development, built around 9 skills and a single commit gate that runs four commands — create-spec, review-spec, apply-spec and deliver-spec — to write a spec, check it against the code, build it in its own worktree and open a verified pull request. The plugin, which works with Claude Code, Codex, Cursor and Copilot, assigns one branch and worktree per spec with offline-minted ids so parallel agents never collide, and stores state in context.yaml so work resumes after a restart. The author says the workflow is how the Agent Smith project is built daily across more than a thousand specs, with each non-obvious choice logged in decisions/ alongside the code.", "body_md": "We'd like to use Google Analytics to see how many people visit and which pages they read. It sets cookies and sends data to Google. Nothing loads unless you say yes, and you can change your mind under Privacy settings at the bottom of every page.\n\nVibe coding is dead. Talk it through, the rest is guided.\n\nDescribe the feature in your own words. Four commands write the spec, check it against your code, build it in its own worktree and deliver it through your checks. Run several side by side and get back verified pull requests.\n\nYou talk, it listensYou describe the app in your own words. Before asking anything, the agent reads your memory and the repository, so it only asks what neither can answer.\n\nThe spec comes firstcreate-spec writes goal, facts with file and line, steps and done criteria, on a fresh branch in its own worktree. No code yet.\n\nA second pair of eyesA script checks that every cited file and line exists. Then a new agent with no chat history attacks the spec against the code, and its cuts are applied before anything is built.\n\nBuilt by the specapply-spec works through the steps, writes the tests the spec names, and logs every choice that wasn't obvious in decisions/.\n\nOnly green landsThe commit goes through the gate: build and tests have to pass. Then the branch is pushed and the pull request opens with the spec inside.\n\nThe rows with a dot are what the skills do on their own: reading, writing, checking, building. You type the lines in boxes.\n\n9 skills1 commit gatea worktree per specids minted offline, safe in parallelClaude Code · Codex · Cursor · Copilot\n\n§1\n\nWhat changes when agents work from specs\n\nThis is how Agent Smith is built every day, across more than a thousand specs.\n\nVerified\n\nA fresh reviewer checks the spec against the code before the build. A gate runs your checks before the commit.\n\nParallel\n\nOne branch and worktree per spec. Ids come from the clock, so two agents never take the same one.\n\nUninterrupted\n\nA reviewed spec has already answered the open questions, so the agent builds to its done criteria instead of coming back to ask.\n\nStructured\n\nOne spec, one branch, one commit. A pull request carries one spec or a whole series, and every change has the same shape.\n\nResumable\n\nState lives in context.yaml. Restart the machine or the agent and the work picks up where it stopped.\n\nExplained, as a side effect\n\nEach choice is logged with what it beat and why, so the reasoning stays next to the code.\n\n§2\n\nA whole series, side by side\n\nCut a bigger change into a series of specs. /spec-first:deliver-series reviews all of them, builds the groups that share no file at the same time, verifies the merged tree and opens one pull request.\n\n3 worktrees building in parallel · every spec commit through the gate\n\nPR #42\n\nAn example run of /spec-first:deliver-series. Specs that share no file are built at the same time; specs that depend on each other share a group.\n\n§3\n\nOne spec, from idea to pull request\n\nFour skills take a piece of work through its own branch and worktree. Each one leaves a file behind for the next step and for whoever reads the history later.\n\ncreate-spec\n\nGoal, steps, facts with file and line, what done means. No code yet.\n\nspecs/planned/{id}.yaml\n\nreview-spec\n\nEvery citation resolved, then a reviewer who never saw the chat attacks it.\n\nBUILD · CUTS · REFUSE\n\napply-spec\n\nContracts, code, wiring, tests, following the project's own rules.\n\ndecisions/{id}.yaml\n\ndeliver-spec\n\nOne commit through the gate, pushed, pull request opened.\n\nfeat: … ({id})\n\nThe recordgrows with every spec, read before every step\n\nspecs/\n\nEvery spec, from planned to done, with its facts and done criteria.\n\ndecisions/\n\nWhat each spec chose, what it chose over, and why.\n\nmemory/\n\nWhat you told the agent once, so you don't say it twice.\n\n/spec-first:bootstrap-project writes the contexts once from your code: stack, rules and the checks a commit must pass. After that, each spec adds one line of state.\n\n§4\n\nA spec is reviewed before anyone builds it\n\nA REFUSE costs you one spec. Without the review, the same mistake would have cost you the branch.\n\nSpec2026-10-27-8a3f\n\nApplies toserver\n\nBranchspec/8a3f\n\nGoal\n\nTicket providers so pipelines can pull work from GitHub and Jira.\n\nFacts, read in the code\n\nPipelines take work only from the CLI todayProgram.cs:40-58\n\nConfig already carries a tracker sectionAppConfig.cs:12-19\n\nDecision\n\nAdapter over repository: read-mostly data, no unit of work needed.\n\nDone when\n\nGitHub provider returns tickets end to end\n\nJira provider behind the same interface\n\nverify: stages green\n\nREVIEWED · BUILDfresh reviewer · 27 OCT\n\nreview-spec · 2026-10-27-8a3f2 cuts\n\n✓ src/Host/Program.cs:40-58 resolves\n\n✓ src/Config/AppConfig.cs:12-19 resolves\n\nevidence resolves: 1 spec\n\nBUILD WITH CUTSthe spec holds once two steps change\n\nCUT 1\n\nStep jira needs a second auth mode the config can't hold yet. AppConfig.cs:15 Move it to its own spec.\n\nCUT 2\n\nPaging is missing: GitHub returns 30 issues per page. GitHubClient.cs:88 Add a done criterion.\n\nEvery citation is checked\n\nA script opens each file and line the spec cites. A claim nobody checked in the code has to be listed as an assumption.\n\nThe reviewer starts fresh\n\nA new agent with no conversation history reads the code as it is, not as the spec says it is.\n\nOne verdict, with cuts named\n\nBUILD, BUILD WITH CUTS or REFUSE, and every finding names a file and a line.\n\n§5\n\nThe reasoning comes along for free\n\nNobody has to write documentation afterwards. While it builds, the agent logs each choice that wasn't obvious: what it chose, what it chose over, and why. One file per spec, next to the code.\n\ndecisions/2026-10-27-8a3f.yaml\n\n```\nspec: 2026-10-27-8a3f\ndecisions:\n  - category: TradeOff\n    chose: \"Raw HttpClient for the GitHub API\"\n    over: \"Octokit\"\n    reason: \"Three megabytes of dependencies\n      for four calls.\"\n  - category: Architecture\n    chose: \"One ITicketProvider per tracker\"\n    over: \"A generic REST mapper\"\n    reason: \"Each tracker pages and authenticates\n      differently; the mapper would leak it.\"\n```\n\nNo wiki to keep alive\n\ncat decisions/*.yaml is the project's reasoning, spec by spec, in the same history as the code it explains.\n\nMemory for what git can't tell\n\nHow the operator wants things done, a constraint outside the repo, a pointer elsewhere. One fact per file, one line in an index.\n\nBack in thirty seconds\n\nRestart the machine, restart the agent, open context.yaml. It knows what is done, what is active and what comes next.\n\n§6\n\nNothing lands past a red stage\n\nThe plugin's commit gate runs every verify stage your contexts declare when a commit names its spec. All green, it commits. The first red stage blocks it, and its output goes back to the agent.\n\nthe commit\n\n```\ngit commit -m \"feat: ticket\n  providers (2026-10-27-8a3f)\"\n```\n\nThe id in parentheses triggers it. -F <file>, -C and --amend --no-edit are gated too.\n\nverify: stages\n\n✓builddotnet build\n\n✓testsdotnet test\n\n✕webcd web && npm test\n\nPASSED\n\nCommitted\n\nevery stage green\n\nBLOCKED\n\nNot committed\n\nthe first red stage stops it, and its output goes back to the agent\n\n# spec-first-gate.log · one line per spec commit\n\n2026-10-27T09:14:02Z blocked 2026-10-27-8a3f /work/repo a1b2c3d web\n\nA spec commit with no line in the ledger never met the gate. A project with its own gate says gate: project, and the plugin steps aside.\n\nBuilt this way\n\nAgent Smith\n\nThe open source agentic software factory: a ticket goes in, a verified pull request comes out. Agent Smith is entirely built with this method, and the method grew out of building it. Everything in the plugin ran there first.\n\nCounted in the Agent Smith repository, October 2026.\n\n§7\n\nInstall\n\nIn Claude Code the plugin does the bookkeeping and runs the gate. Other agents follow the same files through AGENTS.md, and a git hook runs the same gate.\n\nThen run /spec-first:bootstrap-project. It reads your code and writes the contexts and rules from what it finds.\n\ncreate-spec\n\nWrites the spec on its own branch and worktree\n\nreview-spec\n\nEvidence check, then a fresh reviewer's verdict\n\napply-spec\n\nBuilds the spec up to its done criteria\n\ndeliver-spec\n\nCommits through the gate and opens the pull request\n\ndeliver-series\n\nTakes a whole series of specs to one pull request\n\nlog-decision · update-project · bootstrap-project\n\nDecisions, upgrades, setup\n\nLet your agent set it up\n\nPaste this into Codex, Cursor, Copilot or any agent that can read and write your repository.\n\n```\nSet up specification-first agentic development in this repository,\nfollowing the templates at\nhttps://github.com/holgerleichsenring/specification-first-agentic-development/tree/main/templates\n\n1. Create .{project}/contexts/default/context.yaml and coding-principles.md.\n   Fill them from the code as it is: stack, architecture, limits, conventions,\n   and the commands that build and test it as verify: stages. Invent nothing.\n2. Create .{project}/specs/planned, active and done, .{project}/decisions/\n   and .{project}/memory/MEMORY.md.\n3. Write AGENTS.md from templates/prompt.md, with .{project}/ filled in.\n4. Add \"gate: git\" at the top level of that context.yaml.\n```\n\nCopy prompt\n\nAGENTS.md carries the method\n\nCodex, Cursor and Copilot read AGENTS.md when a session starts. It holds the read order and the workflow, and every step says how to do it by hand, the review brief for a fresh session included.\n\nThe gate as a git hook\n\nClone the spec-first repository once, then run python3 <clone>/hooks/install-git-hook.py in each clone of your project. The commit-msg hook runs your verify: stages on every commit that names a spec, from any agent or the terminal. git commit --no-verify skips it. The evidence check is skills/review-spec/scripts/check-evidence.py in the same clone and needs PyYAML.\n\n§8\n\nQuestions about spec-first agentic development\n\nSpecification-driven agentic development, in short answers.\n\nWhat is spec-first agentic development?\n\nA way of working with AI coding agents in which every change starts as a written spec in your repository. A fresh reviewer checks the spec against your code before anything is built, the agent builds it on its own branch and worktree, and the commit lands only when your checks pass.\n\nWhat does specification-driven agentic development mean here?\n\nThe spec drives the work from start to finish. It names the goal, the facts it rests on with file and line, the steps and the done criteria, and the agent builds to exactly that. Spec-first agentic development is specification-driven agentic development in which the spec is reviewed against the code before the first line is written.\n\nDo I need Claude Code?\n\nNo. The Claude Code plugin runs the steps as commands. Codex, Cursor, Copilot or a terminal follow the same files through AGENTS.md, and a git commit-msg hook runs the same commit gate in every clone where it is installed.\n\nHow does it differ from vibe coding?\n\nYou still describe the feature in your own words and talk it through. After that, the agent works from a reviewed spec instead of from the last prompt, logs each decision with its reason, and a commit lands only when your build and tests pass.\n\nWhat does a spec contain?\n\nA one-sentence goal, the facts it rests on with file and line, the steps, what an upgrade costs an operator, and the done criteria. The decisions made while building go into a separate YAML file next to it.\n\nWhat does it cost?\n\nNothing. The method, the templates and the Claude Code plugin are MIT licensed.", "url": "https://wpnews.pro/news/show-hn-specification-first-agentic-development-plugin-and-prove", "canonical_source": "https://spec-first.dev/", "published_at": "2026-10-27 15:12:20+00:00", "updated_at": "2026-10-27 16:14:05.356098+00:00", "lang": "en", "topics": ["ai-agents", "ai-tools", "developer-tools", "ai-products"], "entities": ["Spec-First", "Agent Smith", "Claude Code", "Codex", "Cursor", "Copilot", "Google Analytics"], "also_reported_by": [], "alternates": {"html": "https://wpnews.pro/news/show-hn-specification-first-agentic-development-plugin-and-prove", "markdown": "https://wpnews.pro/news/show-hn-specification-first-agentic-development-plugin-and-prove.md", "text": "https://wpnews.pro/news/show-hn-specification-first-agentic-development-plugin-and-prove.txt", "jsonld": "https://wpnews.pro/news/show-hn-specification-first-agentic-development-plugin-and-prove.jsonld"}}