Skip to content
v1.8.2MIT

Stack-neutral skills for a specification-first workflow with use cases: requirements, entity model, use case specifications, review, implementation, tests, change handling, coverage audit, recovery of existing systems and scaling to several teams.

up-0-navigating-spec-driven-work

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 work that is not a change: new behavior before any use case is approved, recovery of an existing system, 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, to clean the specs, or names spec-driven development without naming an artifact. For a fix, change or feature, use up-1-triaging-change-requests. Routes only; writes no artifact.

up-1-triaging-change-requests

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.

up-2-cataloging-requirements

Turns a vision, workshop transcripts, notes or an interview into a requirements catalog (docs/requirements.md) with functional requirements as role and need (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.

up-3-modeling-domain-entities

Creates or updates docs/entity_model.md: a Mermaid erDiagram of entities and relationships, attribute tables with business meanings, types and rules, lifecycle states and avoided words. Checks specification nouns and lists use cases affected by a model change. Use when the user asks for an entity, domain or data model or glossary, changes an entity or attribute, asks to resolve conflicting vocabulary, or a specification names a missing concept. Not for database migrations or ORM code.

up-4-mapping-use-cases

Finds the use cases a system needs and records them as the use case overview (docs/use_cases.md: a scope list and delivery order written by people, and an actor-goal table and Mermaid diagram generated from the use case files), creating a stub for each mapped use case. Tests user-goal level, aggregates or splits Manage-X goals, moves multi-role or waiting flows to BPMN, and checks functional requirement coverage. Use when the user asks which use cases exist or are missing, whether a goal is a use case, for a diagram or actor-goal list, to split or merge use cases, to decide scope, or to check requirement coverage. Not for writing one use case's steps, bounded contexts or draw.io.

up-5-writing-use-case-specs

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 Examples tables with boundary rows. 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.

up-6-reviewing-specifications

Reviews specification artifacts without editing them. Runs structural lint and an independent three-reader review: stakeholder clarity, engineer testability and the literal implementer's invention list. Reports severity, file, line and element, readiness for Reviewed or Approved, and a traceability matrix. Use when the user asks to review, lint, check, validate or approve specifications, find contradictions or gaps, request a traceability matrix from requirements to use cases, rules and journey tests, or create a specification quality gate. Not for code or pull request review.

up-7-implementing-use-cases

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, or for an index or partitioning that changes no behavior. Also for behavior the owner explicitly requests in the session that no use case covers; not for deciding whether a report is a bug or a change.

up-8-deriving-use-case-tests

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.

up-9-auditing-spec-coverage

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.

up-bootstrapping-spec-driven-projects

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.

up-migrating-spec-formats

Moves a specification set in upspec's earlier formats (bold Overview fields, use_cases.puml, user stories, database types in the entity model, journey tables, the long change record), or in other formats, and the project's installed checks to the current ones: a dry-run plan, a judgment pass with an invention list, the owner's yes, one or two commits, and a check that no format error is left. Use when a script reports OLD_FORMAT, the router names the migration, or the user asks to migrate specifications to the current formats.

up-recovering-specs-from-code

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, 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 it does versus what it was meant to do) and its 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, inherited or brownfield codebase into use cases, bring an existing project under spec-driven development, extract the business rules from existing code, even from a single class or service, or carry the items a baseline review left for later forward.

up-splitting-bounded-contexts

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.

up-writing-journey-test-cases

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, one gherkin block with a Scenario, literal test data and UC identifier comments, verification steps at the seams, closing Then steps 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.