hm-l2-spec-driven-authoring

Files (15)

• SKILL.md
• evals.json · evals/
• .gitkeep · metrics/
• rich-eval-rubric.json · metrics/
• rich-gate-scorecard.md · metrics/
• acceptance-test-patterns.md · references/
• source-synthesis.md · references/
• spec-to-req-mapping.md · references/
• validate-rich-package.sh · scripts/
• validate-skill.sh · scripts/
• task_plan.md
• .gitkeep · templates/
• requirement-traceability-matrix.md · templates/
• .gitkeep · workflows/
• spec-lock-workflow.md · workflows/

SKILL.md (first lines)

# Spec-Driven Authoring

## Overview

Turn written intent into a falsifiable implementation contract. This skill owns spec intake, ambiguity rejection, requirement extraction, acceptance-test derivation, and handoff evidence. It does **not** execute TDD cycles; once requirements and acceptance tests are locked, hand off to `hm-test-driven-execution`.

This package synthesizes three inspected third-party patterns:

| Source pattern | Adopt / adapt decision | Local transformation |
|---|---|---|
| `addyosmani/agent-skills@spec-driven-development` | Adopt the spec-first gate sequence and assumption-surfacing discipline; adapt away from implementation ownership. | Use Source Audit → Ambiguity Gate → Requirement Table → Acceptance Matrix → Handoff Packet. |
| `proffesor-for-testing/agentic-qe@qe-requirements-validation` | Adopt SMART validation, traceability matrix, and BDD coverage framing; adapt away from AQE-specific runtime calls. | Use portable requirement-to-test matrices with project-local commands only. |
| `kw12121212/auto-spec-driven@spec-driven-sync-specs` | Adapt drift/mapping metadata; defer `.spec-driven/` layout assumptions. | Preserve optional implementation/test mapping metadata without requiring any planning framework. |

## Entry Gate

Proceed only when at least one source artifact exists: PRD, SPEC, ADR, user story, API contract, acceptance brief, regulatory requirement, or explicit user request to create falsifiable requirements.

Before authoring:

1. Identify the source artifact and intended reader.
2. Run `prompt-skim` when available to detect length, URLs, missing files, and candidate scope.
3. Run `prompt-analyze` when available to detect contradiction, vagueness, missing actors, missing success criteria, and hidden scope.
4. If either tool is unavailable, perform the same checks manually and state that the tool was unavailable.
5. Block exploratory implementation requests that do not contain a stable requirement source.

## Boundary Rules

| Nearby workflow | Boundary |
|---|---|
| `hm-test-driven-execution` | Consumes locked requirements and executes RED/GREEN/REFACTOR. This skill derives the requirements and expected tests only. |
| `hm-planning-persistence` | Persists multi-session plan/progress state in `.hivemind/state/planning/<session-id>/`. This skill may produce requirements tables for that state but does not own task scheduling. |
| Generic planning | Plans may sequence work. This skill locks what must be true and how to verify it. |
| Exploratory coding/prototyping | Not enough source truth. Return blocked or ask for a spec before deriving REQ-* items. |

## Spec-Lock Workflow

Use this default sequence. Do not skip gates because the source is short.

```text
Source Audit → Ambiguity Gate → Requirement Table → Acceptance Test Matrix → Handoff Packet
```

### 1. Source Audit

Create an audit note with:

- Source path or pasted source title.
- Date/time of review.
- Stakeholders or actors named by the source.
- Explicit MUST/SHOULD/MAY statements.
- Implicit requirements inferred from security, data integrity, accessibility, or operational correctness.
- Out-of-scope statements.

Record provenance in the format from `templates/requirement-traceability-matrix.md`. Every later REQ row must point back to a source quote, source section, or blocked missing source.

### 2. Ambiguity Gate

Reject or clarify any candidate requirement containing unbounded terms such as “fast”, “good”, “simple”, “secure”, “robust”, “intuitive”, “soon”, or “scalable” unless the source gives measurable thresholds.

If ambiguity remains after one rewrite attempt, return a blocked handoff instead of inventing precision.

Use SMART screening from the requirements-validation source pattern:

| Check | Pass condition | Block condition |
|---|---|---|
| Specific | Actor, action, object, and context are named. | Actor or object is implied but not stated. |
| Measurable | Observable output, state, event, metric, or error exists. | Outcome is subjective or unverifiable. |
| Achievable | Project constraints do not contradict it. | Source requires unsupported platform/tooling without adapter. |
| Relevant | It maps to the requested product/workflow goal. | It is implementation detail with no user/system outcome. |
| Testable | At least one verification method exists. | No automated, inspection, or manual verification can prove it. |

### 3. Requirement Extraction

For every requirement, write:

```markdown
### REQ-<domain>-<nn>: <short name>
**Source:** <quote or source section>
**Condition:** <exactly one falsifiable statement>
**Acceptance Criteria:**
- Given <state>, when <action>, then <observable result>.
**Verification Method:** <test, inspection, command, manual validation, or blocked reason>
**Integration Notes:** <agents/commands/tools/hooks/runtime-state implications>
**Status:** draft | locked | blocked
```

### 4. Acceptance-Test Derivation

For each locked requirement, derive:

- Positive case: expected success path.
- Negative case: validation, authorization, error, or invalid-input path when applicable.
- Boundary case: empty, minimum, maximum, missing dependency, timeout, or platform edge.
- Integration case: cross-component behavior when more than one runtime surface is involved.

Write the matrix before handoff:

```markdown
| REQ ID | Source quote/path | Positive | Negative | Boundary | Integration | Verification command/method | Coverage state |
|---|---|---|---|---|---|---|
```

`Coverage state` is `mapped`, `gap`, `blocked`, or `not-applicable`. A `gap` is acceptable only when it is visible in the handoff packet.

### 5. Handoff

When requirements are locked, provide a handoff packet for `hm-test-driven-execution`:

```yaml
requirements:
  - id: REQ-...
    condition: ...
    acceptance_tests: [...]
red_phase_expectation: tests fail before implementation
verification_commands: [...]
blocked_items: [...]
traceability_matrix: path-or-inline-table
source_synthesis: references/source-synthesis.md decisions applied

From shynlee04/hivemind-plugin, MIT.

More from shynlee04/hivemind-plugin