Ensures spec-driven behavior during all workflows. Use when loading context, discussing project structure, starting features, or when "spec", "specification", "acceptance criteria", or "bootstrap" are mentioned. Activates during /context:load, /context:refresh, /spec:init, /define, /design, /deliver, /discern, /handoff, /done, and /discover.
From genienpx claudepluginhub elmmly/genie-team --plugin genieThis skill is limited to using the following tools:
Designs and optimizes AI agent action spaces, tool definitions, observation formats, error recovery, and context for higher task completion rates.
Guides using Bun as runtime, package manager, bundler, and test runner for JS/TS projects with Node comparisons, migration steps, and Vercel deployment.
Compares coding agents like Claude Code and Aider on custom YAML-defined codebase tasks using git worktrees, measuring pass rate, cost, time, and consistency.
Spec-driven development is the standard. Every capability should have a persistent
specification in docs/specs/ (with type: spec YAML frontmatter) before implementation begins.
Specs are the persistent source of truth for what the system does. Backlog items in
docs/backlog/ describe changes to make — they are transient and get archived when done.
Specs model the product architecture, not the code structure. They are organized by domain (a product-level bounded context) and capability (a specific behavior within that domain).
docs/specs/
{domain}/
{capability}.md # active or deprecated spec
| Term | Definition | Stability | Example |
|---|---|---|---|
| Domain | A product-level bounded context — a coherent area of functionality. Domains change on a product-strategy timescale (years). | Very stable | identity, workflow, execution |
| Capability | A specific behavior the system provides within a domain. The unit of specification. | Stable | authentication, headless-mode, tdd-discipline |
| Spec | A file describing one capability: docs/specs/{domain}/{capability}.md | Persistent | docs/specs/execution/headless-mode.md |
identity, workflow, data-pipeline — NOT src-services, api, frontendauthentication, headless-mode, spec-bootstrappingdocs/specs/{domain}/{capability}.md/spec:init → docs/specs/{domain}/{capability}.md (status: active) [bulk — existing project]
/define → docs/specs/{domain}/{capability}.md (status: active) [incremental — new capability]
↓
deprecation → status: deprecated (stays in place, never deleted)
/spec:init (bulk from existing project) or /define (incremental for new capability). The source of truth.Domains are rooted in product architecture, NOT code architecture. Code modules get refactored; domains persist. Specs organized by domain survive code reorganizations without needing to be moved.
This skill activates during:
/context:load — Report spec coverage/context:refresh — Detect drift (does NOT create specs)/spec:init — Bootstrap rich specs from existing project source code, tests, and docs/define — Link to existing spec with behavioral delta, or create new spec for new capability/design — Load spec for context, write back design constraints/deliver — Load spec ACs for TDD, write back implementation evidence/discern — Verify implementation against spec ACs, update AC statuses/handoff — Inject spec-specific transition guidance into handoff output/done — Preserve spec on archiveAll commands that read specs follow this pattern:
spec_ref from backlog item frontmatterspec_ref is present: Read the referenced spec filespec_ref is missing: Warn and continue without spec context:
This backlog item has no spec_ref. Consider linking it to a persistent spec in docs/specs/{domain}/.
spec_ref points to a nonexistent file: Warn and continue:
spec_ref points to {path} but file not found. Proceeding without spec context.
Bootstraps rich specs from an existing project:
docs/specs/**/*.md — skip capabilities that already have specsdocs/specs/{domain}/{capability}.md with status: activeReads: Source code, test files, project docs, config files, docs/specs/**/*.md
Writes: docs/specs/{domain}/{capability}.md, docs/specs/{domain}/README.md (per Domain README Format)
Links to existing specs with behavioral delta, or creates new specs:
When changing an existing capability:
spec_ref or by searching docs/specs/ with user confirmationspec_ref on the backlog itemWhen creating a new capability:
docs/specs/{domain}/{capability}.md with status: activespec_ref: docs/specs/{domain}/{capability}.md in the backlog item frontmatterReads: docs/specs/ domain directories, existing spec ACs
Writes: docs/specs/{domain}/{capability}.md (new capability only), docs/specs/{domain}/README.md (per Domain README Format, new capability only), backlog frontmatter spec_ref
Loads spec for design context and writes back constraints:
spec_ref (using common pattern above)Reads: Spec ACs, existing evidence sections
Writes: Spec body "## Design Constraints" section, spec frontmatter acceptance_criteria (append only), docs/specs/{domain}/README.md (per Domain README Format)
Loads spec ACs for TDD and writes back implementation evidence:
spec_ref (using common pattern above)Spec delta active: This work modifies existing spec behavior. Verify that the implementation matches the proposed changes in the Behavioral Delta section, not just the original spec ACs. b. If spec has ACs with
status: met: Regression watch: Some spec ACs are already met. Verify the implementation doesn't regress previously passing criteria.
Reads: Spec acceptance_criteria
Writes: Spec body "## Implementation Evidence" section, docs/specs/{domain}/README.md (per Domain README Format)
Verifies implementation against spec ACs and updates statuses:
spec_ref (using common pattern above)status: pending → met or unmet for each ACReads: Spec acceptance_criteria, implementation evidence
Writes: Spec frontmatter AC statuses, spec body "## Review Verdict" section, docs/specs/{domain}/README.md (per Domain README Format)
Preserves spec when archiving backlog:
docs/archive/)Reads: Spec status Writes: Nothing (spec preservation is passive — just don't archive it)
Injects spec-specific transition guidance into handoff output:
spec_ref (using common pattern)design → deliver handoff:
Spec context for Crafter: Spec at {spec_ref} has {N} acceptance criteria ({M} pending). {If backlog has Behavioral Delta: "Behavioral delta exists — implementation must match proposed changes, not just original ACs."} b. For
deliver → discernhandoff: Spec context for Critic: {If spec has ACs with status: met: "Some ACs were previously met — check for regressions."} {If backlog has Behavioral Delta: "Spec delta — verify both old and new behavior."}
Reads: Spec acceptance_criteria, backlog item body Writes: Nothing (read-only — guidance injection only)
Surface test-based insights about the project:
Reads: Test files, docs/specs/ Writes: Nothing (read-only)
Include spec coverage in the context summary:
docs/specs/**/*.md recursively for type: spec in frontmatteractive, deprecateddocs/specs/)docs/backlog/*.md for active work items (separately)Reads: docs/specs/**/*.md, docs/backlog/*.md
Writes: Nothing (read-only)
When discussing any feature or component:
docs/specs/{domain}/These rules apply to ALL commands that write to specs:
docs/specs/. Only backlog items are transient.docs/specs/{domain}/README.md for the affected domain(s). The README is fully generated (not hand-edited). See Domain README Format below.When regenerating docs/specs/{domain}/README.md, produce the following format. The README is fully machine-generated — never hand-edit it.
docs/specs/{domain}/*.md (files with type: spec frontmatter)title, status, acceptance_criteria (count by status), and the first paragraph of the body (or the ## Overview section if present) as a one-line summarydocs/specs/{domain}/README.md in this format:<!-- Auto-generated by spec-awareness. Do not edit manually. -->
# {Domain Name}
{N} capabilities | {M met} / {T total} acceptance criteria
## Capabilities
### [{Capability Title}](./{capability}.md)
**Status:** {active|deprecated} | **ACs:** {met}/{total} ({pending} pending, {unmet} unmet)
{One-line summary from spec body}
### [{Another Capability}](./{another}.md)
...
Rules:
{Domain Name} is the domain directory name, title-cased (e.g., workflow → Workflow, data-pipeline → Data Pipeline)acceptance_criteria frontmatter: count entries by status field (met, pending, unmet)## Overview section content if present), truncated to one line