Menu
Delta-merge procedure — DELTA marker semantics, library-organization thresholds, and ADR-promotion field mapping. Triggered by recorder-agent.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
Audit a speq project's health — spec-library structure, feature/decision-log/plan validation, mission-to-spec sync, unrecorded plans, and gitignore hygiene — then guide fixes. Use when the user asks to audit, health-check, doctor, lint, or sanity-check the specs or repo, or after cloning or inheriting a speq project.
Code review tag taxonomy and findings output format — guardrail violations, dead code, obsolete tests, bad comments, optimizations, YAGNI/over-engineering. Triggered by code-reviewer.
Headless follow-up to speq-plan-pr. Continues on a plan's feat/plan-name branch, runs speq-implement, bumps the version, runs the real test suites, records only if green, then pushes and opens/updates a PR. Arg: plan name, PR number, or branch name.
Orchestrate implementation of reviewed plans according to the spec deltas. Arg: <plan-name>.
Create specs/mission.md via interactive interview. Detects brownfield vs greenfield.
Headless, non-interactive version of speq-plan. Plans a feature without a live interview, commits the result to a feat/plan-name branch, and opens a PR. If a decision genuinely needs a human, it persists the partial plan and open questions and asks in a PR comment instead of blocking. Arg — plan name, feature intent text, PR number, or branch name.
| name | speq-spec-merge |
| description | Delta-merge procedure — DELTA marker semantics, library-organization thresholds, and ADR-promotion field mapping. Triggered by recorder-agent. |
Read: specs/_plans/<plan-name>/plan.md
List: specs/_plans/<plan-name>/**/spec.md
Run speq feature list to see the current permanent spec library.
For each delta spec at specs/_plans/<plan-name>/<domain>/<feature>/spec.md:
specs/<domain>/<feature>/spec.md exists?
├─ No → Copy delta (strip markers)
└─ Yes → Merge using markers below
| Marker | Action |
|---|---|
DELTA:NEW | Append scenario |
DELTA:CHANGED | Replace scenario with same name |
DELTA:REMOVED | Delete scenario with same name |
After each merge:
<!-- DELTA:* --> markersspeq feature validate <domain>/<feature>After merges, check for organization signals:
| Metric | Threshold | Action |
|---|---|---|
| Scenarios per spec | >10 | Return to orchestrator for user decision |
| Domain features | >8 | Return to orchestrator for user decision |
Never assume — library reorganization is a user decision. Signal back to the orchestrator with a concrete question.
Read specs/_plans/<plan-name>/decision-log.md (if it exists).
For each entry where Promotes to ADR: yes:
Convert to ADR format using .claude/skills/speq-plan/references/decision-log-permanent-template.md:
specs/_decision/<plan-name>AcceptedWrite ONE new fragment file specs/_decision/NNN-<plan-name>.md:
specs/_decision/) + 1, zero-padded to 3 digits# Decisions: <plan-name>## ADR: <Title> block per promoted entry, in decision-log orderspecs/_decision/ — a supersede reference is a one-way pointer from the new ADR's **Supersedes:** field to the target slugValidate: speq decision-log validate
If decision-log.md is absent or has no "Promotes to ADR: yes" entries, skip silently.
speq feature validatemv specs/_plans/<plan-name> specs/_recorded/NNN-<plan-name>, where NNN = (count of existing entries in specs/_recorded/) + 1, zero-padded to 3 digitsIf a threshold is exceeded, return BEFORE archiving and ask the orchestrator to clarify with the user.
| Pattern | Why Wrong |
|---|---|
| Merging without running validator | Broken specs may land |
| Assuming split/domain reorganization | User must decide |
| Rewriting scenario wording during merge | Recording is a mechanical operation |
| Leaving DELTA markers | Pollutes permanent specs |