From speky
Guidelines for working with Speky requirements and tests via the speky MCP server tools
How this skill is triggered — by the user, by Claude, or both
Slash command
/speky:speky-workflowWhen to use
When working with requirements, tests, specifications, or using any speky MCP tools (get_requirement, get_test, search_requirements, search_tests, list_all_ids, list_all_tags, list_references_to, test_plan_coverage, least_tested_requirements)
The summary Claude sees in its skill listing — used to decide when to auto-load this skill
Speky organizes a project's detailed specification into **requirements** (what the system must do) and **tests** (how to verify it). Items are identified by short IDs like `RF001`, `RN02`, `T003`.
Speky organizes a project's detailed specification into requirements (what the system must do) and tests (how to verify it). Items are identified by short IDs like RF001, RN02, T003.
list_all_ids to get a full overview of available IDs before searching or fetching.get_requirement / get_test when you already know the ID — it's faster and returns full detail including cross-references.search_requirements only when filtering by tag or category. Use search_tests only when filtering by category or by requirement (tester_of). Do not call either with no filters as a substitute for list_all_ids.list_all_tags to discover available tags before filtering by one.list_references_to to find what depends on a given item (e.g., before modifying or deleting it).test_plan_coverage to find coverage gaps — it gives a project-wide summary without requiring manual inspection.least_tested_requirements to find where to write new tests — it ranks requirements by ascending test count and accepts tag, category, and count filters.get_requirement returns tested_by (tests covering it) and referenced_by (requirements that depend on it). Read these before assessing coverage or impact.get_test returns ref (requirements it validates) and prereq (tests that must run first). Read these to understand test scope and ordering.namespace:value (e.g., output:pdf, mcp:tools). When filtering by tag, use the exact full string.ref list (visible as tested_by on the requirement).test_plan_coverage for a project-wide summary before concluding anything about overall coverage.least_tested_requirements (with optional tag or category filter) to pinpoint the requirements most in need of new tests.tested_by.prereq field rather than repeating setup steps.Each test step has one required field and several optional ones:
action (required): describes what the tester does in this step. Always present, even when other fields are set — it gives context to the reader.run: a shell command to execute. When present, the step is automatable. Prefer long-form flags (e.g. --output over -o) for readability.expected: an excerpt of the expected stdout from the run command. Use [...] for elided parts. Only valid when run is set — do not use it for steps without a command.sample + sample_lang: a code/data snippet illustrating the step (e.g. the content of a file being created, a JSON payload, a config fragment). Use sample_lang for syntax highlighting (e.g. yaml, json, python, toml). Unlike expected, a sample can appear on any step — it shows what something looks like, not what a command outputs.Follow this order strictly:
Category is a free-form field, but four values cover most cases:
| Category | Intent | Test plan |
|---|---|---|
functional | User-facing behavior: "The user shall be able to …" | Primary focus of test plans |
non-functional | System-level constraint: "The system shall … (e.g. handle 100k tps, respond in < 1ms)" | Test if measurable, otherwise document |
architecture | Represents an architectural decision | Not tested |
definition | Defines a project-specific term, referenced from other requirements to avoid duplication | Not tested |
When writing requirements, pick the category that reflects the intent, not just the wording.
Two MCP servers are available:
speky — the current project's specification. Use this for all requirement and test lookups in the project you are working on.speky-selfspec — Speky's own specification. Use this as a reference when you need examples of well-formed requirements or tests, or to understand how Speky itself works.Always qualify tool calls with the correct server when both are connected.
specs/.specs/spec.yaml) lists which files to load — new files must be referenced there.speky MCP server to pick up changes (it loads specs at startup).npx claudepluginhub agagniere/speky --plugin spekyProvides UI/UX resources: 50+ styles, color palettes, font pairings, guidelines, charts for web/mobile across React, Next.js, Vue, Svelte, Tailwind, React Native, Flutter. Aids planning, building, reviewing interfaces.
Fetches up-to-date documentation from Context7 for libraries and frameworks like React, Next.js, Prisma. Use for setup questions, API references, and code examples.