tiny-spec 0.1.0__tar.gz

tiny_spec-0.1.0/.gitignore

@@ -0,0 +1,25 @@
+### macOS
+# Finder metadata
+.DS_Store
+
+# Thumbnails
+._*
+
+# Custom folder icons
+Icon
+
+# Volume root files
+.DocumentRevisions-V100
+.fseventsd
+.Spotlight-V100
+.TemporaryItems
+.Trashes
+.VolumeIcon.icns
+.com.apple.timemachine.donotpresent
+### Python
+__pycache__/
+*.py[cod]
+build/
+dist/
+*.egg-info/
+.venv/

tiny_spec-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Snir Orlanczyk
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

tiny_spec-0.1.0/PKG-INFO

@@ -0,0 +1,236 @@
+Metadata-Version: 2.4
+Name: tiny-spec
+Version: 0.1.0
+Summary: A tiny, opinionated take on spec-driven development.
+Project-URL: Homepage, https://github.com/GrayMa77er/tiny-spec
+Project-URL: Source, https://github.com/GrayMa77er/tiny-spec
+Project-URL: Issues, https://github.com/GrayMa77er/tiny-spec/issues
+Author: Snir Orlanczyk
+License: MIT License
+        
+        Copyright (c) 2026 Snir Orlanczyk
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Keywords: ai-agents,claude,claude-code,skills,spec-driven-development
+Classifier: Environment :: Console
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <img src="images/logo.png" alt="tiny-spec" width="200">
+</p>
+
+<h1 align="center">tiny-spec</h1>
+
+<p align="center">A tiny, opinionated take on spec-driven development.</p>
+
+<p align="center">
+  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="License: MIT"></a>
+  <a href="https://docs.claude.com/en/docs/claude-code/overview"><img src="https://img.shields.io/badge/Claude%20Code-skills-d97757.svg" alt="Claude Code"></a>
+</p>
+
+tiny-spec is a four-step workflow for Claude Code that turns a ticket into shipped,
+reviewed code. You write the intent, it produces a design, a task list, and then
+builds the work one task at a time. Every task is implemented by one agent and
+graded by an independent reviewer that runs the real tests before anything is
+committed.
+
+It is four skills and two agents. No orchestrator, no config file, no build step.
+
+```
+tiny-spec-create  →  tiny-spec-plan  →  tiny-spec-tasks  →  tiny-spec-build
+   intent               design             tasks            per-task loop
+   SPEC.md              PLAN.md +          tasks.md         plan → implement → review → commit
+                        constitution
+```
+
+## New to spec-driven development?
+
+Spec-driven development (SDD) means writing down *what* you want and *why* before
+any code exists, then letting that spec drive the build. Instead of prompting an
+agent and hoping, you hand it a small, explicit contract — the intent, a design,
+and an ordered list of tasks — and it implements against that. The payoff: the
+agent stops guessing. It knows what "done" looks like, you can review the plan
+before a single line is written, and the result is checked against the spec
+rather than vibes. tiny-spec is one small take on that idea.
+
+## Quickstart
+
+Install the skills and agents into your Claude Code config with
+[uv](https://docs.astral.sh/uv/):
+
+```sh
+uvx tiny-spec install
+```
+
+Restart Claude Code so it picks up the new skills, then run the flow in your project:
+
+```
+/tiny-spec-create   # capture intent and requirements (binds a ticket, optional)
+/tiny-spec-plan     # turn the spec into a design and harden the constitution
+/tiny-spec-tasks    # slice the plan into an ordered checklist
+/tiny-spec-build    # build each task: implement, review, commit
+```
+
+Re-run `install` any time to update; `tiny-spec uninstall` removes only what it
+installed. Each skill is copied (not symlinked) so every install is
+self-contained.
+
+<details>
+<summary>Manual install (no uv)</summary>
+
+The skills and agents are plain markdown — copy them in by hand. Claude Code
+loads skills from `~/.claude/skills/` and agents from `~/.claude/agents/`:
+
+```sh
+git clone https://github.com/GrayMa77er/tiny-spec.git
+cd tiny-spec
+
+mkdir -p "$HOME/.claude/skills" "$HOME/.claude/agents"
+for s in tiny-spec-create tiny-spec-plan tiny-spec-tasks tiny-spec-build; do
+  cp -R "$s" "$HOME/.claude/skills/$s"
+done
+cp agents/*.md "$HOME/.claude/agents/"
+```
+
+If a skill name collides with one you already have, rename these before copying,
+or install one set at a time.
+
+</details>
+
+## How it works
+
+The constitution (`constitution.md`) is the spine. `tiny-spec-create` seeds it from a
+short interview, `tiny-spec-plan` hardens it with concrete engineering rules, and
+`tiny-spec-build` injects it whole into every task. It holds your style, standards,
+invariants, definition of done, and verification commands.
+
+`tiny-spec-build` walks the task list top to bottom. Each task runs through one loop:
+
+1. Plan the task against the constitution (inline, brief).
+2. Implement it with a fresh `tiny-spec-build-executor` agent.
+3. Review it with an independent `tiny-spec-build-reviewer` agent that runs the gate
+   end to end and grades against the constitution and the task's acceptance.
+4. On pass, commit the code plus a checklist tick. On fail, loop back to the
+   executor with the findings. After two failed attempts it becomes a blocker.
+
+```mermaid
+flowchart TB
+    SPEC[SPEC.md<br/>intent] --> PLAN[PLAN.md<br/>design] --> TASKS[tasks.md<br/>checklist]
+
+    TASKS --> P[Plan task]
+    P --> I[Implement<br/>executor]
+    I --> R[Review + run gate<br/>reviewer]
+    R -->|pass| C[Commit + tick]
+    C --> TASKS
+    R -->|fail| I
+    R -->|fail twice| B[Blocker logged to decisions.md]
+
+    CON([constitution.md]) -.-> P & I & R
+    MEM([memory.md]) -.-> I & R
+```
+
+Solid arrows are the flow. Dotted arrows show the persistent context injected into
+a step: the `constitution.md` goes into planning, implementation, and review, while
+`memory.md` is handed to the executor and reviewer.
+
+A small `memory.md` carries operational lessons between runs, so the executor and
+reviewer (which start fresh each time) don't relearn the same pitfalls.
+
+When a task can't pass because of a gap in the design or spec, the executor stops
+and logs a blocker instead of hacking around it. You fix the gap upstream in
+`tiny-spec-plan` or `tiny-spec-create`, then resume. Work runs one ticket at a time and
+resumes from the checklist state.
+
+## Why it's small
+
+Most spec frameworks are generous by default:
+many phases, many agents, many generated documents. tiny-spec makes the opposite
+bet. Keep one safeguard, drop the rest.
+
+A green unit test suite is not the same as working software, so the reviewer
+exercises acceptance criteria end to end and a final smoke test confirms the whole
+spec. That independent review is the safeguard — not the volume of planning
+artifacts. One task, one commit, an external reviewer. Nothing gets added unless
+it earns its place.
+
+The case for staying small:
+
+- **Documents are context, and context isn't free.** Generating large `spec.md`,
+  `plan.md`, `research.md`, and `data-model.md` files costs tokens to write, then
+  costs context to carry. Every paragraph the agent has to hold is room it no
+  longer has for your actual code. tiny-spec keeps the spine small — a
+  constitution and a short memory — and injects only what each task needs.
+- **Real work is a ticket inside a system, not a greenfield repo.** Bigger kits
+  assume you're bootstrapping a project from a blank page. Day to day, you pick up
+  a ticket and change part of a system that already exists. tiny-spec binds to a
+  ticket, works one at a time, and references your task platform instead of
+  re-describing the world.
+- **Rigid pipelines fight the user.** Mandatory phases and required sections
+  impose ceremony on work that doesn't need it. tiny-spec's extra structure is
+  optional by design — add shape where it pays, skip it where it doesn't.
+- **More moving parts is more to maintain.** Orchestrators, ownership contracts,
+  checkpoint matrices, and config files are themselves a system you have to learn
+  and keep in sync. Four skills and two agents are not.
+- **Generated docs can fake rigor.** A folder of polished planning artifacts looks
+  like progress, but it isn't proof. The proof is the reviewer running your real
+  tests before each commit.
+
+That's the whole trade: where larger kits add machinery, tiny-spec adds one
+independent reviewer and stops.
+
+## Project layout
+
+Each skill is self-contained. It carries its own templates and refers to them by
+relative path, with no absolute paths and no shared parent required at runtime, so
+a skill folder works wherever you drop it.
+
+tiny-spec creates a `.spec/` directory in your project root, never inside a skill.
+It is namespaced per ticket, with a shared spine at the root:
+
+```
+.spec/
+  ACTIVE                    the active ticket directory name (resolution pointer)
+  constitution.md           project-wide, shared across tickets
+  memory.md                 operational lessons, shared across tickets
+  <ticket-id>/              one directory per ticket (PROJ-123/, gh-42/, …)
+    SPEC.md  PLAN.md  tasks.md  decisions.md
+```
+
+`CONTRACTS.md` documents the formats for maintainers. The skills do not read it at
+runtime; each is self-sufficient.
+
+## Integrations
+
+tiny-spec binds to a task platform (Jira, GitHub Issues, Azure DevOps, Monday) by
+reference only: a `ticket` block in the spec and a `Refs:` footer on each
+[Conventional Commit](https://www.conventionalcommits.org/en/v1.0.0/), so the
+platform auto-links the work. No API calls or credentials are required.
+
+## Contributing
+
+Issues and pull requests are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md), and
+read [AGENTS.md](AGENTS.md) before changing any skill or agent.
+
+## License
+
+[MIT](LICENSE)

tiny_spec-0.1.0/README.md

@@ -0,0 +1,199 @@
+<p align="center">
+  <img src="images/logo.png" alt="tiny-spec" width="200">
+</p>
+
+<h1 align="center">tiny-spec</h1>
+
+<p align="center">A tiny, opinionated take on spec-driven development.</p>
+
+<p align="center">
+  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="License: MIT"></a>
+  <a href="https://docs.claude.com/en/docs/claude-code/overview"><img src="https://img.shields.io/badge/Claude%20Code-skills-d97757.svg" alt="Claude Code"></a>
+</p>
+
+tiny-spec is a four-step workflow for Claude Code that turns a ticket into shipped,
+reviewed code. You write the intent, it produces a design, a task list, and then
+builds the work one task at a time. Every task is implemented by one agent and
+graded by an independent reviewer that runs the real tests before anything is
+committed.
+
+It is four skills and two agents. No orchestrator, no config file, no build step.
+
+```
+tiny-spec-create  →  tiny-spec-plan  →  tiny-spec-tasks  →  tiny-spec-build
+   intent               design             tasks            per-task loop
+   SPEC.md              PLAN.md +          tasks.md         plan → implement → review → commit
+                        constitution
+```
+
+## New to spec-driven development?
+
+Spec-driven development (SDD) means writing down *what* you want and *why* before
+any code exists, then letting that spec drive the build. Instead of prompting an
+agent and hoping, you hand it a small, explicit contract — the intent, a design,
+and an ordered list of tasks — and it implements against that. The payoff: the
+agent stops guessing. It knows what "done" looks like, you can review the plan
+before a single line is written, and the result is checked against the spec
+rather than vibes. tiny-spec is one small take on that idea.
+
+## Quickstart
+
+Install the skills and agents into your Claude Code config with
+[uv](https://docs.astral.sh/uv/):
+
+```sh
+uvx tiny-spec install
+```
+
+Restart Claude Code so it picks up the new skills, then run the flow in your project:
+
+```
+/tiny-spec-create   # capture intent and requirements (binds a ticket, optional)
+/tiny-spec-plan     # turn the spec into a design and harden the constitution
+/tiny-spec-tasks    # slice the plan into an ordered checklist
+/tiny-spec-build    # build each task: implement, review, commit
+```
+
+Re-run `install` any time to update; `tiny-spec uninstall` removes only what it
+installed. Each skill is copied (not symlinked) so every install is
+self-contained.
+
+<details>
+<summary>Manual install (no uv)</summary>
+
+The skills and agents are plain markdown — copy them in by hand. Claude Code
+loads skills from `~/.claude/skills/` and agents from `~/.claude/agents/`:
+
+```sh
+git clone https://github.com/GrayMa77er/tiny-spec.git
+cd tiny-spec
+
+mkdir -p "$HOME/.claude/skills" "$HOME/.claude/agents"
+for s in tiny-spec-create tiny-spec-plan tiny-spec-tasks tiny-spec-build; do
+  cp -R "$s" "$HOME/.claude/skills/$s"
+done
+cp agents/*.md "$HOME/.claude/agents/"
+```
+
+If a skill name collides with one you already have, rename these before copying,
+or install one set at a time.
+
+</details>
+
+## How it works
+
+The constitution (`constitution.md`) is the spine. `tiny-spec-create` seeds it from a
+short interview, `tiny-spec-plan` hardens it with concrete engineering rules, and
+`tiny-spec-build` injects it whole into every task. It holds your style, standards,
+invariants, definition of done, and verification commands.
+
+`tiny-spec-build` walks the task list top to bottom. Each task runs through one loop:
+
+1. Plan the task against the constitution (inline, brief).
+2. Implement it with a fresh `tiny-spec-build-executor` agent.
+3. Review it with an independent `tiny-spec-build-reviewer` agent that runs the gate
+   end to end and grades against the constitution and the task's acceptance.
+4. On pass, commit the code plus a checklist tick. On fail, loop back to the
+   executor with the findings. After two failed attempts it becomes a blocker.
+
+```mermaid
+flowchart TB
+    SPEC[SPEC.md<br/>intent] --> PLAN[PLAN.md<br/>design] --> TASKS[tasks.md<br/>checklist]
+
+    TASKS --> P[Plan task]
+    P --> I[Implement<br/>executor]
+    I --> R[Review + run gate<br/>reviewer]
+    R -->|pass| C[Commit + tick]
+    C --> TASKS
+    R -->|fail| I
+    R -->|fail twice| B[Blocker logged to decisions.md]
+
+    CON([constitution.md]) -.-> P & I & R
+    MEM([memory.md]) -.-> I & R
+```
+
+Solid arrows are the flow. Dotted arrows show the persistent context injected into
+a step: the `constitution.md` goes into planning, implementation, and review, while
+`memory.md` is handed to the executor and reviewer.
+
+A small `memory.md` carries operational lessons between runs, so the executor and
+reviewer (which start fresh each time) don't relearn the same pitfalls.
+
+When a task can't pass because of a gap in the design or spec, the executor stops
+and logs a blocker instead of hacking around it. You fix the gap upstream in
+`tiny-spec-plan` or `tiny-spec-create`, then resume. Work runs one ticket at a time and
+resumes from the checklist state.
+
+## Why it's small
+
+Most spec frameworks are generous by default:
+many phases, many agents, many generated documents. tiny-spec makes the opposite
+bet. Keep one safeguard, drop the rest.
+
+A green unit test suite is not the same as working software, so the reviewer
+exercises acceptance criteria end to end and a final smoke test confirms the whole
+spec. That independent review is the safeguard — not the volume of planning
+artifacts. One task, one commit, an external reviewer. Nothing gets added unless
+it earns its place.
+
+The case for staying small:
+
+- **Documents are context, and context isn't free.** Generating large `spec.md`,
+  `plan.md`, `research.md`, and `data-model.md` files costs tokens to write, then
+  costs context to carry. Every paragraph the agent has to hold is room it no
+  longer has for your actual code. tiny-spec keeps the spine small — a
+  constitution and a short memory — and injects only what each task needs.
+- **Real work is a ticket inside a system, not a greenfield repo.** Bigger kits
+  assume you're bootstrapping a project from a blank page. Day to day, you pick up
+  a ticket and change part of a system that already exists. tiny-spec binds to a
+  ticket, works one at a time, and references your task platform instead of
+  re-describing the world.
+- **Rigid pipelines fight the user.** Mandatory phases and required sections
+  impose ceremony on work that doesn't need it. tiny-spec's extra structure is
+  optional by design — add shape where it pays, skip it where it doesn't.
+- **More moving parts is more to maintain.** Orchestrators, ownership contracts,
+  checkpoint matrices, and config files are themselves a system you have to learn
+  and keep in sync. Four skills and two agents are not.
+- **Generated docs can fake rigor.** A folder of polished planning artifacts looks
+  like progress, but it isn't proof. The proof is the reviewer running your real
+  tests before each commit.
+
+That's the whole trade: where larger kits add machinery, tiny-spec adds one
+independent reviewer and stops.
+
+## Project layout
+
+Each skill is self-contained. It carries its own templates and refers to them by
+relative path, with no absolute paths and no shared parent required at runtime, so
+a skill folder works wherever you drop it.
+
+tiny-spec creates a `.spec/` directory in your project root, never inside a skill.
+It is namespaced per ticket, with a shared spine at the root:
+
+```
+.spec/
+  ACTIVE                    the active ticket directory name (resolution pointer)
+  constitution.md           project-wide, shared across tickets
+  memory.md                 operational lessons, shared across tickets
+  <ticket-id>/              one directory per ticket (PROJ-123/, gh-42/, …)
+    SPEC.md  PLAN.md  tasks.md  decisions.md
+```
+
+`CONTRACTS.md` documents the formats for maintainers. The skills do not read it at
+runtime; each is self-sufficient.
+
+## Integrations
+
+tiny-spec binds to a task platform (Jira, GitHub Issues, Azure DevOps, Monday) by
+reference only: a `ticket` block in the spec and a `Refs:` footer on each
+[Conventional Commit](https://www.conventionalcommits.org/en/v1.0.0/), so the
+platform auto-links the work. No API calls or credentials are required.
+
+## Contributing
+
+Issues and pull requests are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md), and
+read [AGENTS.md](AGENTS.md) before changing any skill or agent.
+
+## License
+
+[MIT](LICENSE)

tiny_spec-0.1.0/agents/tiny-spec-build-executor.md

@@ -0,0 +1,78 @@
+---
+name: tiny-spec-build-executor
+description: Implements a single task — writes/modifies code to satisfy one task, adhering to the project's constitution, and reports what changed plus any decisions or blockers. Spawned (one per task) by tiny-spec-build. Does not plan, spawn other agents, or invoke skills.
+tools: Read, Write, Edit, Bash, Grep, Glob
+---
+
+# tiny-spec-build-executor
+
+You implement **one task** from a build. You are spawned by `tiny-spec-build`,
+one instance per task, running on its own. Your final message **is** the
+structured report back — it is not shown to a human, so return data, not prose
+pleasantries.
+
+## What you receive (the context contract)
+
+Everything you need and nothing you don't:
+
+- the **task id**, **description**, and **acceptance** (the outcome that proves it done);
+- a **`files:` hint** — likely paths to touch (guidance, not a hard boundary);
+- the full **constitution** (`constitution.md`): Style, Engineering standards,
+  Guiding invariants, Glossary, Layout, Definition of Done, Verification commands;
+- the project's **memory** if any (`memory.md`) — operational lessons; honor them
+  so you don't re-learn a pitfall a past run already paid for;
+- the specific existing files that are your starting point, named explicitly.
+
+You are **blind to the workflow, not to the codebase.** You don't get the plan,
+other tasks, or shared state. But the named files are a launch point, not the whole
+picture: **explore the codebase read-only** as far as you need — grep for callers
+and usages, read the types you touch, find the existing helper or pattern to reuse
+instead of reinventing. Editing existing code blind is how the constitution gets
+violated.
+
+## How to work
+
+1. Read your launch-point files, then explore outward (read-only) until you
+   understand the code you're changing and the patterns to match.
+2. Write or modify code to satisfy the task, **adhering strictly to the
+   constitution** — style, invariants, error handling, testing approach, layout.
+3. If the task implies tests and the constitution calls for them, write them.
+4. Keep your changes focused on this task. The `files:` hint is guidance — if the
+   task genuinely needs a nearby file the hint missed, that's fine (you're
+   sequential, no one else is writing). But do **not** refactor unrelated code or
+   implement adjacent tasks — that's scope creep, not thoroughness.
+5. You MAY run a **narrow self-check** of your own work (the one test file you
+   wrote, a syntax/import check). You do **not** need to run the full gate — the
+   independent **reviewer** runs the authoritative Verification commands next.
+   Leave the tree in a clean, buildable state for it.
+
+## Hard constraints
+
+- **Never spawn subagents or invoke skills.** You have no Agent tool by design.
+  One task, one executor.
+- **Never hack around a blocker.** If you cannot proceed correctly — a design gap,
+  an impossible requirement, a missing dependency, a contradiction with the
+  constitution — **stop and report a blocker.** Do not invent a workaround, stub
+  silently, or guess intent. Bubbling up is the correct outcome, not a failure.
+- **Surface, don't bury, decisions.** Record any non-obvious choice in your report.
+
+## Report back (your final message)
+
+Return exactly this structure so `tiny-spec-build` can act:
+
+```
+TASK: <task id>
+STATUS: done | blocked
+CHANGES:
+- <file>: <one-line summary of what changed>
+DECISIONS:
+- <any non-obvious choice you made, and why> (omit section if none)
+BLOCKER:
+- <if blocked: what stopped you, and which upstream doc (SPEC or PLAN) must change
+  to unblock> (omit section if not blocked)
+SELF-CHECK:
+- <the narrow check you ran and its result, or "none — left the gate to the reviewer">
+```
+
+If `STATUS` is `blocked`, leave the work in a clean state (no half-applied hacks) —
+`tiny-spec-build` will leave the task unchecked and route the blocker upstream.

tiny_spec-0.1.0/agents/tiny-spec-build-reviewer.md

@@ -0,0 +1,69 @@
+---
+name: tiny-spec-build-reviewer
+description: Independently reviews a single finished task — runs the project's real gate end-to-end and checks the code against the constitution and the task's acceptance. Blind to how the code was written. Returns PASS/FAIL plus findings. Spawned (one per task) by tiny-spec-build. Does not fix code, plan, spawn agents, or invoke skills.
+tools: Read, Write, Edit, Bash, Grep, Glob
+---
+
+# tiny-spec-build-reviewer
+
+You independently review **one finished task** from a build. You did
+**not** write this code and you have no memory of how it was written — that
+independence is the whole point. Your final message **is** the structured verdict
+back to `tiny-spec-build`; return data, not pleasantries.
+
+## What you receive (the context contract)
+
+- the **task id**, **description**, and **acceptance** (the outcome that must hold);
+- the full **constitution** (`constitution.md`) — especially **Guiding invariants**,
+  **Definition of Done**, and **Verification commands**;
+- the project's **memory** if any (`memory.md`) — operational lessons (e.g. the
+  gate needs the package installed first); honor them so you don't false-fail on a
+  known precondition;
+- the list of **changed files** to review.
+
+## How to review
+
+Your job is to answer one question honestly: **does this task actually satisfy its
+acceptance and the constitution — verified, not inferred?**
+
+1. **Read the changed code.** Check it against the constitution: does it honor the
+   **Guiding invariants**, match the **Style** and **Layout**, meet the
+   **Definition of Done**? Note any violation as a finding.
+2. **Run the real gate.** Execute the constitution's **Verification commands**
+   end-to-end (install → lint → test → build → run, as applicable) from a clean
+   state, after the documented setup — not a test-runner shortcut. Capture the
+   real output.
+3. **Exercise the acceptance.** Trigger the task's stated outcome the most
+   black-box way available (CLI > HTTP > public API) with realistic input,
+   including a negative case if the acceptance implies a boundary or rejection.
+   The acceptance is met only if the **observed** effect is the one it names — not
+   an adjacent or merely-plausible behavior. "A unit test exists" or "the code
+   looks right" is **not** evidence.
+
+## Verdict rules
+
+- **`PASS`** — the gate is green AND you exercised the acceptance end-to-end with
+  real input AND the observed effect matches AND no invariant/DoD violation. Only
+  this is a pass.
+- **`FAIL`** — anything short of the above: a red gate, an invariant violated, the
+  acceptance not observably met, or you couldn't exercise it end-to-end. When torn,
+  **fail** — never round up. List concrete, actionable findings so the executor
+  can fix them.
+
+You are **read-only on the source** — you run commands and read files, but you do
+**not** edit code, fix the task, or rewrite docs. If it's wrong, you report it; the
+executor fixes it on the next attempt. (You have edit tools only so you can run
+gates that scratch-write build output — never use them on source.)
+
+Never spawn subagents or invoke skills.
+
+## Report back (your final message)
+
+```
+TASK: <task id>
+VERDICT: PASS | FAIL
+GATE: <the Verification commands you ran + the real result (pass/fail + key output)>
+ACCEPTANCE: <how you exercised it + the observed effect, or why you couldn't>
+FINDINGS:
+- <each invariant/DoD/acceptance problem, concrete and actionable> (omit if PASS)
+```