christianorrala/upspec

Reads the state of a spec-driven repository (vision, requirements catalog, entity model, use case diagram, use case specifications with their Status, journey test cases, code and tests) and names the single next step and the skill that performs it, following the artifact chain from vision to tests. Also classifies incoming work as new behavior, change, bug, recovery of an existing system or throwaway, and picks the rigor profile (throwaway, solo, team). Use when the user asks where the project stands, what comes next, which step follows the entity model or an approved use case, whether to go ahead with a step now, whether a piece of work needs use cases or specifications at all, how to start spec-driven development or use-case-driven work on an idea or an existing codebase, or names spec-driven development without naming an artifact. Routes only; writes no artifact.

Sets a repository up for specification-first development with use cases: chooses a rigor profile (throwaway, solo, team), creates the docs tree and a vision skeleton, adds the spec-first rules to the guideline file (CLAUDE.md or AGENTS.md), for teams adds spec ownership, a pull request template with the specification-first review order, and a CI job that runs the specification lint and a spec-first guard, and offers agent hooks that run the checks in the agent's own tool. Use when the user wants to adopt, introduce or set up spec-driven development or use-case-driven work in a new or existing repository, asks which artifacts and gates a solo developer or a team needs, asks whether spec discipline is worth it for a prototype or a short-lived project, wants agent guideline rules for working from use cases, or wants hooks that make an agent run the specification checks without being asked. Not for writing a general CLAUDE.md and not for task boards.

Turns a vision, workshop transcripts, notes or an interview into a requirements catalog (docs/requirements.md) with functional requirements as user stories (FR), measurable non-functional requirements (NFR) with a verification method, and constraints (C) under stable identifiers, and returns a conflict ledger of contradictions, duplicates and open decisions for the human review gate. Runs an elicitation interview when there is no workshop material. Use when the user asks to gather, write, extract, classify or update requirements, user stories, NFRs or constraints for a spec-driven or use-case-driven project, adds, defers or drops a requirement in the catalog, or hands over meeting notes to consolidate. Not for the detailed behavior of one feature (that is a use case specification) and not for brainstorming a design.

Creates or updates the entity model (docs/entity_model.md) of a spec-driven project: a Mermaid erDiagram showing entities and relationships only, plus one attribute table per entity with business types, validation rules, lifecycle states and the words to avoid, so that it serves as the project's vocabulary. Checks that every noun used by requirements and use case specifications exists in the model and lists the use cases affected by a model change. Use when the user asks for an entity model, domain model, data model or glossary for a spec-driven or use-case-driven project, adds or changes an entity or attribute, says the specifications use two words for one thing or asks to fix the vocabulary, or when a specification uses a noun the model lacks. Not for draw.io drawings, database migrations or ORM code.

Finds the use cases a system needs and records them as the use case diagram (docs/use_cases.puml, PlantUML): builds the actor-goal list from the requirements catalog, tests every candidate for user-goal level (one actor, one sitting), aggregates and splits Manage-X use cases, moves multi-role or waiting flows to a business process, checks that every functional requirement is realized and every actor connected, and proposes the delivery order of first slices. Use when the user asks which use cases exist or are missing, whether something is a use case at all or only a step of one, wants a use case diagram or overview, an actor-goal list, to split or merge use cases, to decide scope with an in/out list, or to check requirement-to-use-case coverage. Not for writing the steps of one use case, not for sorting use cases into bounded contexts or teams, and not for draw.io diagrams.

Writes or revises one use case specification (docs/use_cases/UC-XXX-name.md) that a stakeholder can validate, an engineer can review against and an AI agent can implement without inventing behavior: goal and trigger, preconditions, a 3 to 9 step main success scenario, alternative flows found in three passes with explicit endings, success and failure postconditions, and numbered business rules with boundary examples. Asks at most five decisive questions, keeps observable behavior concrete and mechanism out, and finishes with an invention pass and a structural lint. Use when the user asks to write, draft, specify, extend or fix a use case, scenario, alternative flow, business rule or acceptance behavior, asks to specify step by step what happens when an actor does something, mentions UC-XXX with a writing request, or wants a spec an agent can implement from. Also covers use cases for APIs, scheduled jobs and events.

Reviews spec-driven artifacts without editing them and reports findings with severity, file, line and element id: a deterministic lint that may block (structure, dangling or duplicate identifiers, unrealized requirements, diagram and file mismatch, copied rules, open flows, mechanism and weak words) and an advisory three-reader review (stakeholder skim, engineer testability, literal-implementer invention list, contradictions across use cases). Ends with a verdict on readiness for Reviewed or Approved and can print the traceability matrix from requirement to use case, rule and journey test case. Use when the user asks to review, lint, check, validate or approve a use case, the requirements or the whole specification set, asks whether a spec is ready, wants contradictions or gaps found, or wants a traceability matrix or a CI quality gate for specs. Not for reviewing code or pull requests.

Implements or synchronizes exactly one approved use case in code, in any stack: checks the Status gate, reads only the use case, its linked requirement rows, the entity model and the guideline file, shows an element-to-code plan with the list of decisions the specification leaves open, then generates a new slice or applies only the behavioral difference between the previous and the current specification, marks rule-enforcing code with the rule identifier, audits the diff for out-of-scope changes and handles schema changes as a guarded sub-procedure. Use when the user says implement, build, generate, sync or synchronize UC-XXX, asks to bring code in line with a changed use case, or asks for a database migration or schema change after the entity model changed. Not for work that names no use case and not for deciding whether a report is a bug or a change.

Derives and maintains the tests of one use case from its specification, in any stack: lists the coverage units (main success scenario, each alternative flow, each business rule with its boundaries, success postconditions, failure guarantees, guarded preconditions, linked testable NFRs), picks the test layer from the use case's interface, writes one traceable test per unit asserting postconditions rather than internals, proves each rule test fails against a deliberately broken rule, and on a specification change updates, deletes or keeps tests according to the difference. Use when the user asks to write, generate, update or review tests for UC-XXX, asks which tests a use case needs, wants spec-based acceptance tests, asks whether the tests really guard a business rule, or suspects generated tests assert the wrong thing. Not for end-to-end journeys across several use cases and not for test-first design of code that has no use case.

Audits whether code and tests realize the specifications and reports without fixing: for one use case, a matrix of every step, alternative flow, business rule, postcondition and linked NFR against code evidence and test evidence, with gaps, drift and the Status the evidence justifies; for the project, the spec dashboard in Markdown (requirements and use cases complete, in progress, not started; per use case code, unit, end-to-end, regression, integrity) generated from Status fields, identifiers in code and tests, and the test report. Use when the user asks whether UC-XXX is fully implemented or tested, which rules lack tests, whether a Status may move to Tested or Done, for specification coverage, progress, a spec dashboard, or drift between code and specs. Not for line coverage, charts, or reviewing the specs themselves.

Recovers the specifications of an existing system from its code and running behavior: actors from authorization, a use case map from server, front-end and hosted-service entry points grouped by user goal, an entity model from the schema in the project's own words, and use case specifications at the depth the owner chooses (a short baseline for every use case, or full ones where change is coming), written at business level with implementation detail kept out by check. Keeps an evidence ledger and a list of suspect behavior instead of correcting anything, prepares the two-role baseline review (what the system does versus what it was meant to do) and the first change log, and pins current behavior with tests before the first change. Use when the user wants to reverse-engineer, document, baseline or onboard a legacy or brownfield codebase into use cases, bring an existing project under spec-driven development, or extract the business rules from existing code, even from a single class or service.

Splits a specification set that has outgrown review into bounded contexts, each owning its own requirements catalog, entity model, use cases, guideline file and pipeline: measures the specification core, clusters use cases by shared entities and actors, proposes contexts named after business capabilities, assigns every requirement, entity and use case to exactly one context, turns shared data into explicit contracts, moves the files keeping identifiers and history, and sets ownership and the cross-context rule review. Use when the user says the specs are too big to review, several teams or agents collide in docs, asks how to scale spec-driven development to multiple teams, wants to split a monolith's specifications, or asks which use cases, entities or requirements belong to which context, such as Billing or Order Management. Not for splitting code into services without specifications.

Turns an incoming bug report, feature or change request, or production hotfix into a specification-first change: classifies it with the sign-off test (code wrong, specification wrong, test wrong, ambiguous specification, enhancement, new use case, or no behavior change), lists the affected requirements, use cases, rules, entities, journey test cases and tests, prepares the specification change first, resets the use case Status, and hands over to implementation and tests. Use when the user reports a bug or relays that users report something fails and asks to fix it, in a project that has use case specifications; forwards a stakeholder change such as a new limit, period or policy, asks whether something is a bug or a feature, wants an urgent fix or a production hotfix, says to patch the code now and fix the specification later, or asks what a change affects; it comes first, before any code is read. Not for diagnosing the technical root cause of a failure, not for projects without use case specifications.

Writes a journey test case document (docs/test_cases/TC-XXX-name.md) that chains several use cases into one end-to-end story a stakeholder recognizes: roles, preconditions with their data source, a flow table with literal test data and a link to the use case each step exercises, verification rows at the seams, end-state validations and a cleanup inventory. Selects journeys by risk or derives one per path of a BPMN business process, and keeps per-use-case detail out. Use when the user asks for an end-to-end scenario, a user journey, a test case across use cases, TC-XXX, asks which journeys or paths to test end to end, or wants test cases derived from a business process or .bpmn file. Not for the tests of a single use case and not for writing browser automation code.