Skip to main content
skill CX Codex

clarify-spec — Claude Code skill: what it does, how to install

clarify-spec resolves spec clarification markers and ambiguous requirements in Swarm projects by asking targeted questions one at a time.

MIT ★ 539 updated 2026-10-29

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add ZaxbyHub/opencode-swarm --skill clarify-spec -a claude-code
Open on GitHub

What clarify-spec does

The protocol runs inside the Swarm architect runtime whenever an effective specification contains [NEEDS CLARIFICATION] tags or the user triggers /swarm clarify. It inspects the resolved spec source, whether native .swarm/spec.md, OpenSpec, or Spec-Kit. Beyond explicit markers, it searches for untestable acceptance criteria, overlapping rules, and subjective adjectives that lack measurable targets.

Before presenting an ambiguity, the protocol consults an SME agent and runs question wording through a sounding board critic. Questions appear sequentially with up to four choices, a reasoned recommendation, and a free-form text option. Sessions halt after resolving critical ambiguities or reaching the eight-question boundary, immediately saving each accepted answer into the target spec.

Without an unambiguously resolved effective spec, the skill stops immediately and instructs you to resolve conflicting sources or generate a spec first.

What it helps with

  • resolve [NEEDS CLARIFICATION] markers in project specifications
  • detect vague adjectives and untestable acceptance criteria across requirements
  • update OpenSpec or Spec-Kit files without shadowing them with native specs
  • filter speculative self-resolutions using an automated critic sounding board

Example prompts for the agent

  • /swarm clarify
  • Review spec and resolve open clarification markers
  • Refine spec requirements and address edge cases

How to install clarify-spec

1Skills CLI (Vercel)

npx skills add ZaxbyHub/opencode-swarm --skill clarify-spec -a claude-code

2Manually: put the files in place

~/.claude/skills/clarify-spec/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/clarify-spec/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about clarify-spec

How to install clarify-spec in Claude Code?

Run npx skills add ZaxbyHub/opencode-swarm --skill clarify-spec -a claude-code. The protocol file will be placed at ~/.claude/skills/clarify-spec/SKILL.md.

What does clarify-spec do?

It guides requirement refinement through single-question prompts, checks domain implications via SME agents, and writes approved answers back into the active spec.

How does write-back work for non-native specs?

It avoids creating .swarm/spec.md to prevent file shadowing. The skill updates format artifacts in place or asks you to run /swarm sdd project before saving.

Source text

SKILL.md · MIT
---
name: clarify-spec
description: >
  Full execution protocol for MODE: CLARIFY-SPEC -- resolving spec clarification markers and maintaining spec/planning alignment.
metadata:
  audience: swarm-plugin
---

# Clarify Spec Protocol

This protocol is loaded on demand by the architect runtime. The architect prompt keeps only activation, action, and hard safety constraints; the full execution details live here.

### MODE: CLARIFY-SPEC
Activates when: `/swarm sdd status` reports a **single resolved EFFECTIVE spec** (non-null) AND it contains `[NEEDS CLARIFICATION]` markers; OR user says "clarify", "refine spec", "review spec", or "/swarm clarify" is invoked; OR architect transitions from MODE: SPECIFY or MODE: BRAINSTORM with open markers.

`/swarm sdd status` reflects `readEffectiveSpecSync`, which returns **null** (NO effective spec) for: no sources at all, multiple competing sources (e.g. `openspec/` AND `.specify/`), multi-feature Spec-Kit without a selected feature, or any other unresolvable state. CLARIFY-SPEC does NOT activate in these null cases — tell the user: "No resolved effective spec exists. Disambiguate with `/swarm sdd project --source <source>` or `--feature <feature>`, or run `/swarm specify` to generate one first." and stop.

CONSTRAINT: CLARIFY-SPEC must NEVER create a spec. Always consult `/swarm sdd status` to determine the effective spec source before proceeding.

1. Read the **effective spec** resolved by `/swarm sdd status` (native `.swarm/spec.md` OR OpenSpec `openspec/` OR Spec-Kit `.specify/` — read the resolved spec FIRST before making any changes).
2. Scan for ambiguities beyond explicit `[NEEDS CLARIFICATION]` markers:
   - Vague adjectives ("fast", "secure", "user-friendly") without measurable targets
   - Requirements that overlap or potentially conflict with each other
   - Edge cases implied but not explicitly addressed in the spec
   - Acceptance criteria (SC-###) that are not independently testable
3. Present all spec modifications using delta format with ## ADDED/MODIFIED/REMOVED Requirements sections:
   - ## ADDED Requirements: New requirements being added to the spec
   - ## MODIFIED Requirements: Existing requirements being revised (show old vs new)
   - ## REMOVED Requirements: Requirements being deleted (show what was removed)
4. Delegate to `the active swarm's sme agent` for domain research on ambiguous areas before presenting questions.
5. Present questions to the user ONE AT A TIME (max 8 per session):
   - Offer 2–4 multiple-choice options for each question
   - Mark the recommended option with reasoning (e.g., "Recommended: Option 2 because…")
   - Allow free-form input as an alternative to the options
6. After each accepted answer, write the resolution to the **resolved effective source** (source-aware write-back):
    - **NATIVE effective spec** (`.swarm/spec.md` exists): update `.swarm/spec.md` with the resolution directly.
    - **NON-NATIVE effective spec** (openspec/specify-only, NO native `.swarm/spec.md`): do NOT write `.swarm/spec.md` — this would silently shadow the non-native source. Instead:
      - (a) If the resolved source supports in-place edits (e.g., OpenSpec sections), update the source artifacts directly.
      - (b) If no in-place edit path exists, ask the user: "The effective spec lives in `<source>`. To persist this resolution as a native spec, run `/swarm sdd project` first to materialize one, or I can stop here. Proceed?" — if the user consents to project, materialize via `/swarm sdd project` then write `.swarm/spec.md`; otherwise stop.
      - (c) If neither (a) nor (b) applies, stop and tell the user the clarification cannot be auto-written to a non-native source without a projection step.
    - Replace the relevant `[NEEDS CLARIFICATION]` marker or vague language with the accepted answer.
    - If the answer invalidates an earlier requirement, update it to remove the contradiction.
7. Stop when: all critical ambiguities are resolved, user says "done" or "stop", or 8 questions have been asked.
8. Report a ## Clarification Summary: total questions asked, requirements added/modified/removed, remaining open ambiguities (if any), and suggest next step (`PLAN` if spec is clear, or continue clarifying).

CLARIFY-SPEC RULES:
- FR-ID increment rule: When adding new requirements, find the highest existing FR-ID and increment from there (FR-001 → FR-002). Never reuse or skip FR-IDs.
- One question at a time — never ask multiple questions in the same message.
- Do not modify any part of the spec that was not affected by the accepted answer.
- Always write the accepted answer back to the resolved effective source before presenting the next question. Never write `.swarm/spec.md` in a non-native (openspec/specify-only) repo — see step 5 source-aware write-back rule.
- Max 8 questions per session — if limit reached, report remaining ambiguities and stop.
- Do not create, overwrite, or shadow the spec file — only refine what exists. In non-native (openspec/specify-only) repos, never silently materialize a `.swarm/spec.md` that would shadow the effective source.

### Scoped Funnel Protocol (CLARIFY-SPEC only)

CLARIFY-SPEC handles **already-surfaced** `[NEEDS CLARIFICATION]` markers and spec ambiguities — it does not perform open-ended discovery of new uncertainties. The full four-stage clarification funnel (inventory, classify, consult critic, surface) described in the clarify skill applies to MODE: CLARIFY and MODE: PLAN, not here.

However, before surfacing each marker question to the user, CLARIFY-SPEC MUST:

1. **Consult `critic_sounding_board`** with the candidate marker question and surrounding spec context to check whether the question wording can be improved or the item can be resolved from existing context.
2. **Apply the Overconfidence guard:** If the critic supplies a `RESOLVE` verdict with a default answer, but that default is not directly supported by user request, spec, or recorded context, classify the item as `user_decision` rather than `self_resolved`.
3. **Apply always-surface protection:** If the marker belongs to an always-surface category (scope boundaries, destructive behavior, security/privacy, backward compatibility, breaking API changes, new dependencies, deprecations, cross-platform impact, cost/performance tradeoffs, user-visible UX, rollout strategy, QA gates), the item MUST NOT receive `UNNECESSARY`/`DROP` from the critic — override to `APPROVED`/`ASK_USER`.

Critic verdict mapping (`SoundingBoardVerdict`): `UNNECESSARY`→DROP, `RESOLVE`→RESOLVE, `REPHRASE`→REPHRASE, `APPROVED`→ASK_USER.

This scoped protocol is lighter than the full funnel because CLARIFY-SPEC starts from known markers rather than open uncertainty inventory, but it still protects against overconfident self-resolution and premature dropping of important questions.

© ZaxbyHub · MIT · ZaxbyHub/opencode-swarm

Similar skills

All skills for Agent setup: memory, context, orchestration →

From the same set121

The whole set →
design-docs Writes and syncs a project's design docs: domain, technical spec, behavior spec, plus a traceability registry and changelog. CX Codex +1 ★ 539repo stars orchestrating-subagents orchestrating-subagents is a Claude Code skill for dividing project tasks among subagents, with parallel explorers and independent code review in isolated contexts. CX Codex +1 ★ 539repo stars commit-pr The commit-pr skill guides commits, pull request updates, and CI checks in opencode-swarm. Use it when publishing issue-related code changes or closing out a PR. CX Codex +1 ★ 539repo stars contributing contributing walks an agent through the full pull-request cycle in the opencode-swarm repo: branch naming, commit format, a release-notes fragment, local checks and the PR template. CX Codex +1 ★ 539repo stars pre-phase-briefing pre-phase-briefing builds phase-start context, reviews prior retrospectives, and checks whether the referenced codebase matches the planned work. CX Codex +1 ★ 539repo stars rust-crate-ci rust-crate-ci — a skill for editing the runners/swarm-sandbox-runner crate: it fixes the order of local checks and flags Windows breakage that only CI would catch. CX Codex +1 ★ 539repo stars clarify clarify filters requirements through a four-stage funnel with critic evaluation to build decision packets without noisy questions. CX Codex +1 ★ 539repo stars editing-skills Use this skill before editing SKILL.md files in opencode-swarm. It explains the repository’s mirror, adapter, and package-shipping rules. CX Codex +1 ★ 539repo stars

Project sponsors

Companies that keep this analytics open