Indexion Sdd

indexion SDD (Spec-Driven Development)

Bridge indexion's quantitative spec alignment tools with SDD agent workflows (cc-sdd, codex, etc.).

Provides: RFC/document → SDD draft, spec↔impl drift detection, and a validation loop that feeds indexion's quantitative results into agent-driven qualitative review.

When to Use

• User wants to implement an RFC or specification as a library/package
• User asks to verify spec-to-implementation conformance
• User wants to set up a SDD project with cc-sdd + codex + indexion
• User says "run the SDD loop" or "validate against the spec"
• After codex spec-impl completes, to check for drift before merging

Important

• Set cc-sdd `--lang` to match the implementation language, not the spec language. If code is in English, use --lang en. Mismatched languages break spec align diff vocabulary matching.

Process: RFC → Implementation → Validation

Step 0: Project Setup

# Create project directory
mkdir my-rfc-impl && cd my-rfc-impl

# Install cc-sdd for your agent — set lang to match the code language
npx cc-sdd@latest --codex-skills --lang en --yes   # codex (skills mode)
npx cc-sdd@latest --claude-skills --lang en --yes   # claude (skills mode)

# Initialize project (language-specific)
# e.g., cargo init, npm init, moon new, etc.

# Initialize git
git init && git add -A && git commit -m "init"

Verify indexion is available before proceeding. The drift gate (Step 2.5) and validation loop (Step 3) depend on it:

indexion --version                       # must be installed
indexion kgf edges <any-source-file>     # must detect language and show edges

If indexion is not installed, install it first. If the KGF for your spec format is not recognized, update indexion to a version that includes it. See Step 2.7 for the fallback when this cannot be resolved.

Step 1: Specification → SDD Draft (indexion)

Fetch the specification document (RFC, ISO standard, etc.) and prepare it:

# For RFC: save as markdown or .rfc.txt
indexion spec draft --output .kiro/specs/<feature>/requirements.md rfc_document.md

# For ISO/IEC standards: extract text from PDF with cleanup, then draft
python3 scripts/extract_iso_text.py spec.pdf <start_page> <end_page> spec.spec.txt
indexion spec draft --output .kiro/specs/<feature>/requirements.md spec.spec.txt

# Create spec.json (set requirements.generated=true, approved=true)

The output uses ### Requirement N: and #### N.M: hierarchy matching cc-sdd's expected ID format. The agent's $kiro-spec-requirements phase will further refine into EARS format with acceptance criteria.

Supported specification formats: | Format | Extension | KGF spec | |--------|-----------|----------| | RFC plaintext | .rfc.txt | rfc-plaintext | | ISO/IEC technical document | .spec.txt | technical-document | | Markdown (README, etc.) | .md | markdown |

Step 1.5: Specification Fidelity Check (indexion)

After writing requirements, verify they cover the source specification:

# Check requirements ↔ original spec alignment
# (spec align now accepts document files as impl when no code files are found)
indexion spec align diff .kiro/specs/<feature>/requirements.md spec.spec.txt \
  --format markdown --threshold 0.3

# SPEC_ONLY items = requirements not covered by original spec
# DRIFTED items = requirements using different vocabulary from original spec

Traceability chain: spec align works between documents at the same abstraction level. For full traceability, check each adjacent pair:

# 1. Source spec ↔ requirements (fidelity)
indexion spec align diff requirements.md source-spec.spec.txt --threshold 0.3
# 2. Requirements ↔ design (design coverage)
indexion spec align diff requirements.md design.md --threshold 0.3
# 3. Requirements ↔ implementation (impl coverage) — after $kiro-impl
indexion spec align diff requirements.md src/ --threshold 0.3

Do NOT align source spec directly against design or code — the vocabulary spaces differ too much (normative spec language vs. software design vs. code identifiers). Each hop bridges one abstraction gap.

Semantic fidelity review (not automatable):

spec align checks vocabulary overlap, but cannot detect requirements that invert the source spec's intent while using the same vocabulary. A common failure mode:

• Source spec: "The DCTDecode filter shall decode JPEG data into samples"
• Requirements draft: "For DCTDecode, the decoder shall return an error indicating the filter is not yet supported"

Both mention "DCTDecode", "filter", "shall" — vocabulary matches, so spec align reports MATCHED. But the requirement says the opposite of what the spec demands. This creates a hidden gap that only surfaces when E2E tests fail (Step 2.9).

After `spec draft` generates requirements, review for these patterns:

• "not yet supported", "not implemented", "placeholder", "stub" — these indicate the draft punted on a spec requirement
• "shall return an error" for something the source spec says "shall decode/process/convert" — intent inversion
• Requirements that group multiple spec features into a single "unsupported" bucket — each spec feature deserves its own requirement

Fix these before proceeding to Step 2. Leaving them creates a false sense of spec conformance that only E2E testing can expose.

Step 2: Agent SDD Phases (codex / claude)

cc-sdd v3+ uses skills mode ($kiro-spec-* commands).

Non-interactive execution with indexion gates between phases:

FEATURE=<feature>
SPEC_DIR=.kiro/specs/$FEATURE
REPORT_DIR=.indexion/sdd-reports/$FEATURE
mkdir -p $REPORT_DIR

# Helper: approve a phase in spec.json
approve() { jq --arg p "$1" '.approvals[$p].approved = true' $SPEC_DIR/spec.json > /tmp/spec.json && mv /tmp/spec.json $SPEC_DIR/spec.json; }

# --- Design ---
codex exec --full-auto --json -C . "\$kiro-spec-design $FEATURE -y" > $REPORT_DIR/design.jsonl
approve design
# Verify requirements ↔ design
indexion spec align diff $SPEC_DIR/requirements.md $SPEC_DIR/design.md \
  --format markdown --threshold 0.3 | tee $REPORT_DIR/req-design-align.md
git add $SPEC_DIR && git commit -m "spec: design for $FEATURE"

# --- Tasks ---
codex exec --full-auto --json -C . "\$kiro-spec-tasks $FEATURE -y" > $REPORT_DIR/tasks.jsonl
git add $SPEC_DIR && git commit -m "spec: tasks for $FEATURE"

# --- Impl Phase A: Types & Structures ---
# Phase A implements type definitions, error types, data structures,
# and public API surface. No logic implementations yet.
cat > $REPORT_DIR/impl-phase-a.md << 'PHASE_A_EOF'
## Context

You are implementing Phase A (Types & Structures) of the <FEATURE> feature.
Read `.kiro/specs/<FEATURE>/tasks.md` for task details and
`.kiro/specs/<FEATURE>/design.md` for the design.

## Phase A Scope

In this phase, implement ONLY:
- Public type definitions (structs, enums, type aliases)
- Error types
- Constants and configuration structures
- Public API function signatures with placeholder bodies
- Test scaffolding (test files with placeholder tests)

Do NOT implement:
- Parsing, conversion, or transformation logic
- Algorithm implementations
- Complex function bodies beyond trivial constructors/accessors

## Per-Task Drift Gate

After completing each task and committing, run:

indexion spec align diff .kiro/specs/<FEATURE>/requirements.md src/<pkg>/ --format markdown --threshold 0.3 indexion spec align status .kiro/specs/<FEATURE>/requirements.md src/<pkg>/ --threshold 0.3 --fail-on drifted

If DRIFTED items remain for the requirement your task addresses, fix them
(add spec vocabulary to public declaration doc comments) and re-commit.

When all tasks are done, `spec align status --fail-on drifted` must exit 0.

## Important

Commit your work after completing tasks. Do not leave changes uncommitted.
PHASE_A_EOF

sed -i '' "s/<FEATURE>/$FEATURE/g; s/<pkg>/$PKG/g" $REPORT_DIR/impl-phase-a.md