skills.rest
kpiteira
kpiteiraCOMMUNITY
Explore all skills by this author →
GitHub

kspec

Turn feature ideas into signed intent specs with work briefs and planner-authored acceptance tests.

2|1|Updated Feb 5, 2026
Search Tags:#specification#feature planning#ai workflow#sign-off#triage#acceptance tests#milestone briefs
One-click install
npx skills add https://github.com/kpiteira/devops-ai --skill kspec-kpiteira
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: kspec
Source: https://github.com/kpiteira/devops-ai/tree/main/skills/kspec
Command: npx skills add https://github.com/kpiteira/devops-ai --skill kspec-kpiteira

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Feature planning often produces vague specs that executors cannot act on without the original conversation, and acceptance criteria get written after implementation instead of before. This Skill runs planner sessions that translate a human's raw intent into a signed intent spec, one work brief per milestone, and runnable acceptance tests authored before any code exists. ## Core Features & Use Cases - Plan mode: Interview the human, investigate the codebase, decompose the feature into vertical-slice milestones, pin each brief's Surface, and author acceptance tests measured against the real runtime before sign-off. - Triage and replan modes: Verify executor divergence reports against the code, classify them as false facts, untenable decisions, or wrong outcomes, and re-draft affected briefs and tests with an amendment log. - Close mode: Run a fresh-session intent-conformance review over the whole feature diff, produce a close report, and archive the spec with acceptance tests promoted by kind. - Use Case: A developer types an intent dump for a new reminders feature; the planner walks them through the relevant code, asks the unresolved questions, writes SPEC.md plus per-milestone briefs and failing acceptance tests, gets per-item sign-off, and hands off to the executor workflow. ## Quick Start Ask the AI to plan a new feature by describing your idea, for example: run kspec to plan adding wellness reminders to the app and walk me through the decisions.

Frequently Asked Questions about kspec

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I turn a feature idea into an executable spec?▼

Run the plan mode with your intent dump. The planner interviews you to remove ambiguity, investigates the code, decomposes the feature into vertical-slice milestones, and authors acceptance tests before sign-off, producing a SPEC.md plus one work brief per milestone.

How do I write acceptance tests before implementation exists?▼

Author tests against the brief's pinned Surface, then run them in the executor's runtime to confirm they fail because the surface does not exist yet, not because the test is broken. Every job needs at least one blocking test, and every blocking test must map to a job.

What happens when an executor finds a spec contradiction?▼

The executor stops and files a divergence report instead of classifying it. The triage mode verifies the report against the code, then classifies it as a false fact, an untenable decision, or a wrong outcome, recording the resolution in the spec's amendment log.

Can acceptance tests change after the spec is signed?▼

Only in the replan mode, which is the sole context besides initial planning where acceptance tests may change. Replanning re-drafts the affected milestones' briefs and tests, appends an amendment entry with the rejected alternative, and requires fresh per-item human sign-off.

Why must the feature close review run in a fresh session?▼

Drift is invisible to the session that planned or built the feature. A fresh close session reviews the whole diff against the spec's Intent paragraph from an adversarial angle the blocking tests did not take, then archives the spec and promotes acceptance tests by kind.

Related Skills

Explore More Software Engineering Skills→
lyingparachutelyingparachute

to-spec

Convert conversation context into a project specification and publish it to the issue tracker.

Community
Intermediate
SAZO-KRSAZO-KR

review

Launch five parallel fresh-context code review agents until all pass.

Official
Advanced
dbc-oduffydbc-oduffy
5

merging-to-main

Merge a feature branch into main with acceptance-oracle and CI-gated checks.

Community
Advanced
TMI-appsTMI-apps
2

quick-piv

Automate a three-phase plan, implement, and validate workflow for small tasks.

Official
Intermediate