atelier-fashion/adlc-toolkit/spec

/spec — Requirement Specification

You are writing a requirement spec following the spec-driven ADLC process.

Ethos

!test -s .adlc/ETHOS.md && cat .adlc/ETHOS.md || echo No ethos found — run /init, or /adlc:init on the plugin install, to vendor .adlc/ETHOS.md

Context

Run this block first, with your shell tool, and read its output before you continue. Each read prints a notice instead of failing when its file is absent.

# adlc-context
echo '--- ADLC context'
cat .adlc/context/project-overview.md 2>/dev/null || echo 'No project overview found'
echo '--- Requirement template'
cat .adlc/templates/requirement-template.md 2>/dev/null || echo 'No requirement template found — run /init (/adlc:init on the plugin install) to vendor .adlc/templates'
echo '--- Taxonomy'
cat .adlc/context/taxonomy.md 2>/dev/null || echo 'No taxonomy found — consider running /init (/adlc:init on the plugin install) to scaffold one'

Input

The feature request is the argument: whatever follows /spec in the invocation (on Claude Code it can also arrive as an ARGUMENTS: line appended to this text). With none, ask the user what to build.

Lane flags — read and strip these before anything else (REQ-652 BR-4). The argument may carry --lite or --full, each a standalone token, to force the REQ's lane instead of letting Step 1.7 triage it. Read them from the argument above and remove every occurrence of both tokens, before the Prerequisites check and before Step 1.4's intake gate:

• Both present — stop with /spec: --lite and --full are mutually exclusive — pass at most one and do nothing else: no intake, no retrieval, and no Step 2. An id allocated for a request that then errors is burned, because adlc_alloc_id advances a machine-global counter and pushes a remote reservation ref.
• One present — remember which. Step 1.7 records it instead of triaging.
• Neither — Step 1.7 triages.

From here on, "the feature request" means the argument with those tokens removed, and every fence below that passes the argument receives the stripped text: where the argument appears inline in a fence, delete the flag tokens from it before running the fence. adlc_intake_detect reads its argument raw, so a leftover flag would count as request text, and --lite notes.txt would no longer resolve as a readable file path. --intake is not a lane flag; it stays. This is the model reading the argument, as with /sprint --workflow and /wrapup --close-out — no shell parses the lane flags, and partials/intake.sh knows nothing about them.

Prerequisites

Before proceeding, verify that .adlc/context/project-overview.md exists. If it doesn't, stop and tell the user: "The .adlc/ structure hasn't been initialized. Run /init (/adlc:init on the plugin install) first to set up the project context."

Instructions

Step 1: Understand the Request

1. Read .adlc/context/project-overview.md for grounding context (skip if already in conversation)
2. Read .adlc/context/architecture.md for existing patterns (skip if already in conversation)
3. If the feature request is vague or ambiguous, ask clarifying questions before proceeding. Wait for answers. When Step 1.4's intake gate activates, that step supersedes this item — ambiguity is then handled by the structured gap list rather than by ad-hoc questions here. This item stays in force for the ordinary short-request path, where there is not enough source material to check against the template.

Step 1.4: Unstructured-Source Intake

Requirements do not always arrive as a coherent feature request. They arrive as meeting notes, a chat transcript, a ticket dump, a voice-note transcription, or three paragraphs of stakeholder prose. This step accepts that input and produces two things: the distilled feature request Step 1.5 will tag, and an explicit, classified gap list naming what the source does not answer.

The gap list is the point. A spec written from a transcript will always contain assumptions; the failure mode is not making them, it is making them invisibly.

This step runs before Step 1.5 because Step 1.5 derives the retrieval query from the request, and a distilled statement is better tag input than a raw transcript. It runs before Step 2 because an interactive blocking-gap halt must not burn a REQ id — adlc_alloc_id mutates a shared machine-global counter and pushes a remote reservation ref.

1. Activation gate (BR-1). Intake activates only when the input is unstructured. Source the partial and call the detector in the same fenced block (BR-10 — the cross-fence-fn rule). The detector gets the feature request with --lite and --full already stripped (Input), here and in step 2's fence: substitute it for <request>, quotes included, as one single-quoted literal with every ' in it written '\'' (conventions.md "Bash in skills", "Substituting a value into a fence"). Never double-quote it: a backtick or $ in the request would run.

``sh ADLC_TOOLKIT_ROOT="${CLAUDE_PLUGIN_ROOT}"; [ -n "$ADLC_TOOLKIT_ROOT" ] || [ ! -d "$HOME/.claude/skills/partials" ] || ADLC_TOOLKIT_ROOT="$HOME/.claude/skills"; [ -n "$ADLC_TOOLKIT_ROOT" ] || ADLC_TOOLKIT_ROOT=$(cat "$HOME/.claude/adlc/plugin-root" 2>/dev/null); export ADLC_TOOLKIT_ROOT="${ADLC_TOOLKIT_ROOT:-$HOME/.claude/skills}" if [ -f .adlc/partials/intake.sh ]; then . .adlc/partials/intake.sh; else . "$ADLC_TOOLKIT_ROOT/partials/intake.sh"; fi adlc_intake_detect '<request>'; gate=$? echo "intake_gate=$gate reason=${ADLC_INTAKE_REASON:-none} kind=${ADLC_INTAKE_KIND:-none} inline=${ADLC_INTAKE_INLINE:-0}" # This fence is a GATE PROBE only — step 2 re-derives everything in its own shell. # For an inline source, detect materializes a temp dir; discard this probe's copy # here or every intake run leaks one. Deletion guards live in the partial, never # at the call site. adlc_intake_cleanup "" "$ADLC_INTAKE_PATH" exit 0 ``

adlc_intake_detect returns 1 for an ordinary feature request — none of BR-1's three triggers (an explicit --intake flag, an argument resolving to a readable file path, or an argument exceeding 25 lines) fired. When it returns 1, skip the entire rest of Step 1.4 and go straight to Step 1.5. No intake runs, no gap list is produced, no ## Provenance section is written, and no stderr line is emitted (AC-1). This is the common path and it must stay exactly as fast and as quiet as it is today.

It returns 0 when intake should run, having exported ADLC_INTAKE_REASON (which trigger fired), ADLC_INTAKE_KIND (transcript | notes | ticket | prose), ADLC_INTAKE_PATH, and ADLC_INTAKE_INLINE.

1. Segment the source before delegating (BR-12). Segmentation is what makes a partial delegate summary detectable. Without it a truncated read yields zero gaps precisely because the unread remainder is invisible, and BR-11's benign path would certify the result as complete.

Segmentation and credential redaction happen in one fenced block, and that block re-runs the detector rather than relying on step 1's exports. This is not redundancy: each fenced block is a separate shell invocation, so nothing — not even an exported variable — survives from step 1's block. Re-deriving is the only correct option, which is why the detector is cheap and idempotent.

``sh ADLC_TOOLKIT_ROOT="${CLAUDE_PLUGIN_ROOT}"; [ -n "$ADLC_TOOLKIT_ROOT" ] || [ ! -d "$HOME/.claude/skills/partials" ] || ADLC_TOOLKIT_ROOT="$HOME/.claude/skills"; [ -n "$ADLC_TOOLKIT_ROOT" ] || ADLC_TOOLKIT_ROOT=$(cat "$HOME/.claude/adlc/plugin-root" 2>/dev/null); export ADLC_TOOLKIT_ROOT="${ADLC_TOOLKIT_ROOT:-$HOME/.claude/skills}" if [ -f .adlc/partials/intake.sh ]; then . .adlc/partials/intake.sh; else . "$ADLC_TOOLKIT_ROOT/partials/intake.sh"; fi adlc_intake_detect '<request>' || exit 0 adlc_intake_segment "$ADLC_INTAKE_PATH" || exit $? adlc_intake_redact "$ADLC_INTAKE_CORPUS" || exit $? echo "INTAKE_CORPUS=$ADLC_INTAKE_CORPUS" echo "INTAKE_SOURCE=$ADLC_INTAKE_SOURCE" echo "INTAKE_SEGMENTS=$ADLC_INTAKE_SEGMENTS" echo "INTAKE_LINES=$ADLC_INTAKE_LINES" echo "INTAKE_INLINE=$ADLC_INTAKE_INLINE" ``

INTAKE_INLINE=1 means the source was pasted rather than a file on disk, and adlc_intake_detect materialized it into a private temp dir so the file-based steps below work uniformly. It matters at cleanup (step 7): a materialized temp dir is ours to delete, a user's source file never is.

Return codes from adlc_intake_segment: 0 = segmented; 2 = source unreadable; 3 = over budget. On rc=3 the partial has already printed a refusal naming the actual line count and the 8000-line / 40-segment budget. Halt. Do not write a spec (AC-10). Tell the operator to split the source and run intake on each part. Never truncate: reading the first 8000 lines silently would recreate the exact invisible-compression failure this step exists to eliminate.

The corpus embeds only the source's basename (BR-7); full local paths stay on the machine. Redaction runs before anything leaves the machine, applying the same 5-pattern chain /proceed Phase 5 uses on its verify diff.

Thread the echoed values forward as literals. Later fenced blocks cannot read them as variables — substitute the actual printed values into the commands below, the same way the telemetry flag path is threaded through Step 1.6. Writing "$ADLC_INTAKE_CORPUS" in a later block would silently expand to an empty string.

1. Read the source body — gated delegation, hard fallback (BR-5). Read spec/references/intake-source-read.md and follow it before you continue. It holds this step in full: the telemetry flag, the delegate gate, the delegated read with its coverage reconciliation and citation checks, the fallback read, and the telemetry emit, all working from the literals step 2 echoed. Nothing in this file replaces it.

1. Identify gaps against the template's sections. Get the checklist — derived from the requirement template, never hardcoded, so a future template section is gap-checked automatically:

``sh ADLC_TOOLKIT_ROOT="${CLAUDE_PLUGIN_ROOT}"; [ -n "$ADLC_TOOLKIT_ROOT" ] || [ ! -d "$HOME/.claude/skills/partials" ] || ADLC_TOOLKIT_ROOT="$HOME/.claude/skills"; [ -n "$ADLC_TOOLKIT_ROOT" ] || ADLC_TOOLKIT_ROOT=$(cat "$HOME/.claude/adlc/plugin-root" 2>/dev/null); export ADLC_TOOLKIT_ROOT="${ADLC_TOOLKIT_ROOT:-$HOME/.claude/skills}" if [ -f .adlc/partials/intake.sh ]; then . .adlc/partials/intake.sh; else . "$ADLC_TOOLKIT_ROOT/partials/intake.sh"; fi adlc_intake_sections ``

<!-- intake-gap-rules: read verbatim by space/build.mjs (REQ-670); keep the markers -->

For each section returned, ask what the source material does not answer, and write the gap as a specific unanswered question, never a category label. "Who is allowed to archive a project — any member, or only the owner?" is a gap. "Permissions unclear" is not; it names a topic instead of a question, and nobody can answer it.

A section with everything it needs produces no gap. A complete, unambiguous source produces zero gaps, no halt, and no Open Questions (BR-11).

1. Classify every gap (BR-2). Each gap is exactly one of:

Classification is per-gap and must be justified in one sentence. The justification is what stops blocking from becoming a reflex and assumption from becoming a dumping ground.

<!-- /intake-gap-rules -->