clarify

A pre-planning interview command that resolves unclear requirements and records architectural decisions before implementation begins.

In plain words
What is it for?
Use it to clarify a specification, examine hidden architecture choices, review compliance scope, and save decisions in the project's defaults registry.
Why use it?
It reduces the chance that the coding agent silently guesses about missing product or system details.

Command

Install

Getting it into your agent

One page per mod, every tool's command on it. A separate URL per tool would split the same page into five that compete with each other.

agentmods
npx agentmods add commands/chappygo-os/atomic-spec/clarify
Clone the repo
git clone --depth 1 https://github.com/Chappygo-OS/Atomic-Spec
Per session 65 Only the description is in the session, so the agent can decide to use it. The body loads when it is invoked.
When invoked 5,988 The whole file, excluding the scripts and references it only reads on demand.
Security scan A 0 findings. Scan, not verified.
Origin original No closer match found in the catalogue.
Token cost

What it costs to keep this loaded

Counted locally with the o200k_base tokenizer, which is exact for GPT models; Claude uses its own tokenizer and its counts differ. Treat this as one consistent yardstick across the catalogue rather than a bill. Prices are per million input tokens.

ModelPer sessionOnce invoked
Fable 5 $0.00065 $0.05988
Opus 5 $0.00032 $0.02994
Sonnet 5 $0.00013 $0.01198
Haiku 4.5 $0.00006 $0.00599

Measured 2d ago against content hash e60894980588, method: parsed. Prices are Anthropic first-party input rates as of 2026-08-30, from the pricing page.

Security

Grade A, and why

clarify scanned grade A with 0 findings against 26 rules in 11 categories — prompt injection, anti-refusal, data exfiltration, privilege escalation, supply chain, agent snooping, system-prompt leakage, SSRF and excessive agency — measured 2d ago.

A static scan of the body, not an audit. Every finding is printed with the line that produced it so you can judge whether it matters here. A mod is markdown that instructs an agent; that is exactly why what it instructs is worth reading.

Nothing flagged

None of the 26 patterns this scan looks for appear in this file: no shell pipes, no recursive deletes, no credential paths, no hidden text, no instruction-override or anti-refusal phrasing, no agent-config snooping. That is not a guarantee, it is the absence of the things that are checkable.

templates/commands/clarify.md · 408 lines

How it starts

The opening of the file, as written. The whole thing — 408 lines — stays where its author put it; the contents beside it link to each section on GitHub.

User Input

$ARGUMENTS

You MUST consider the user input before proceeding (if not empty).

Goal

Identify and resolve gaps that would cause the AI to make silent decisions during /atomicspec.plan or /atomicspec.implement. Two kinds of gaps:

  1. Spec ambiguity — things the user wrote but unclearly (v0.1 contract).
  2. Architectural lurkers + structural decisions — things the user didn't write but that the project needs answered before any code is generated. This is the v0.2 hardening (per Article IX Directive 7 scope).

Output: an updated spec.md (Clarifications section) AND new entries in specs/_defaults/registry.yaml with _provenance tags AND interview_completed: <today> set if the session completes normally.

This workflow runs BEFORE /atomicspec.plan. /atomicspec.plan Phase 0 will redirect users here when interview_completed: null (genesis behaviour). After it's set, /atomicspec.specify still advertises clarify (soft nudge) but does not block.

Six-phase flow

Phase 1: Mode question         (Lite vs Detailed, sets cap)
Phase 2: Spec ambiguity scan   (v0.1 contract — 11-category taxonomy)
Phase 3: Architectural lurkers (from .specify/knowledge/architectural-lurkers.yaml)
Phase 4: Trigger-driven probes (from .specify/knowledge/triggers.yaml)
Phase 5: Compliance probes     (compliance:true triggers, two-step gate)
Phase 6: Write + provenance    (batched registry write, accept-rate audit)

Registry Protocol (Constitution Directive 7)

Follow _registry-protocol.md:

  • On entry: Read specs/_defaults/registry.yaml. Load existing values so we don't re-ask fields that are already non-null.
  • During: Track every accepted answer in working memory. Mark each as human (active choice) or accepted_recommendation (default taken) for provenance tagging.
  • On exit: Batch-write to registry.yaml. Set interview_completed if the session completed normally. Update _provenance block with one entry per write.

Read the full file on GitHub · 408 lines

Changes

What this file has done since we first saw it

Hashed on every crawl. A supply-chain change to an agent config is a question of when, not whether, so the history is kept rather than the latest state alone.

  1. 2d ago First seen · 408 lines · 65 tokens per session scan A e60894980588

Subscribe to this mod's changes

clarify is a command published in the GitHub repository Chappygo-OS/Atomic-Spec (10 stars, last pushed 9d ago), licensed MIT. It adds 65 tokens to every session and 5,988 once invoked, about $0.0003 per session on Opus 5. A static security scan graded it A with 0 findings. No closer match exists in the catalogue, so it is treated as the original; first seen 2026-08-31.