Generate SDD requirements from RFCs/specs and quantitatively verify implementation conformance. spec draft → spec align → spec verify → automated validation loop with codex/claude. Operate spec-to-impl drift gates as CI checks.

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 Verify indexion is available before proceeding. The drift gate (Step 2.5) and validation loop (Step 3) depend on it: 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: 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: Traceability chain: spec align works between documents at the same abstraction level. For full traceability, check each adjacent pair: 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: bash 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 bash 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 any Monitor impl progress: Operational notes: Always use json with file redirect + tail f . Piping through tail suppresses all output until completion. For long prompts, write to a file and use $(cat file.md) . Shell HEREDOC with $() can cause stdin blocking. Use /loop (Claude Code) to poll git log oneline 1 + ps every 60 120s during long impl runs. Step 2.5: Per Task Drift Gate (indexion) After each $kiro impl task commit, run spec alignment to verify the task closed its corresponding requirement gap. Do NOT proceed to the next task if the requirement addressed by the current task is still DRIFTED, SPEC ONLY, or SHALLOW. Phase A gate (types only — SHALLOW is expected and tolerated): Phase B gate (logic — SHALLOW must be zero): SHALLOW detection: When a requirement matches only to type/struct/enum declarations in a file that contains no non trivial function implementations ( 4 lines), spec align classifies it as SHALLOW. This catches two patterns: 1. Codex writes type definitions to satisfy vocabulary matching but omits the actual processing logic that the requirement demands. 2. Codex adds logic in a separate file from the type definition. SHALLOW checks per file, so a type in one file with methods only in another file still triggers SHALLOW on the type's file. Resolution: Add methods to the same file where the type is defined. Trivial functions (constructors, one liner accessors ≤4 lines) do not count. See Phase B prompt template for examples. When including this gate in a Codex prompt, instruct the agent to run these commands after each task commit and fix any flagged items before proceeding. Example instruction block for the prompt: Step 2.6: Phase B Iteration (SHALLOW Resolution Rounds) Phase B rarely resolves all SHALLOW items in a single Codex session. Common causes: Codex adds logic in a new file instead of the type definition file Codex adds trivial constructors/accessors (≤4 lines) that don't count New type definitions are added without corresponding logic Iteration protocol: After each Phase B session completes: 1. Run the SHALLOW audit: 2. If Shallow: 0 , proceed to E2E verification (Step 2.9). 3. If SHALLOW 0, identify the specific items: 4. Write a targeted round prompt that: Lists the remaining SHALLOW items explicitly Names the exact files that need functions added States the rule: add functions to the same file as the type Specifies what methods to add (not just "fix SHALLOW") 5. Launch the next round: Typical: 2 3 rounds. Round 1 adds core logic, Round 2 forces same file methods, Round 3 catches remaining edge cases. Step 2.7: Stall Detection and Recovery Codex processes can stall (lost API connection, blocked review loop, etc.). This is common during long Phase B sessions. Detection: Recovery — never commit manually: When a stall is confirmed: 1. Kill the process: kill $CODEX PID 2. Check what was completed: git log , git status , git diff cached 3. If uncommitted work exists and tests pass, generate indexion reports: 4. Write a resume prompt file that: States which tasks are committed and which have uncommitted work Includes the indexion reports as current state evidence Instructs Codex to verify and commit uncommitted work, then continue Requires the per task drift gate (Step 2.5) for all remaining tasks 5. Restart: codex exec full auto json C . "$(cat $REPORT DIR/resume prompt.md)" $REPORT DIR/impl resume.jsonl & Never commit implementation code manually. All commits must come from the Codex agent. If you commit manually, you bypass the SDD protocol (RED→GREEN evidence, review, verification) and invalidate the workflow. Step 2.8: Drift Gate Proxy (when Codex cannot run indexion) Codex runs indexion commands inside the impl project directory. If indexion is not installed, is too old, or lacks required KGF specs, the drift gate commands will fail or timeout inside Codex. Prevention (recommended): Verify in Step 0 that indexion works in the project directory before starting the SDD run: If indexion is not available or broken, install or update it first. Fallback — orchestrator side drift gate: If indexion cannot be fixed before the run (e.g., a required KGF spec is not yet released), the orchestrator runs the drift gate externally: 1. Tell Codex to skip drift gate commands in the impl prompt: 2. After each Codex commit, the orchestrator runs: 3. If DRIFTED/SPEC ONLY items appear, run the vocab fix step (Step 3.5) with the externally generated reports. specs dir caveat: When running the indexion binary directly (not via the project's build tool), it may not find KGF specs automatically. Pass specs dir explicitly: Without this, spec align may return "No alignment data found" because the requirement document format is unrecognized. Step 2.9: E2E Verification (post SHALLOW) After all SHALLOW items are resolved ( Shallow: 0 ), verify that the implementation actually works end to end. spec align only checks vocabulary — it cannot confirm functional correctness. Write E2E tests that exercise the full pipeline against real input data: Common E2E failure modes after SHALLOW=0: Type definitions exist and logic functions exist, but the pipeline raises errors on real input (missing encoding tables, unsupported font types, etc.) All tests pass on synthetic fixtures but fail on real files because fixtures don't exercise the full code path Functions are implemented but not wired into the top level API If E2E tests fail, write additional Codex prompts targeting the specific failure. The spec align gate ensures the vocabulary stays aligned while Codex fixes the implementation. Step 2.10: Parallel Feature Execution Multiple features can run in parallel Codex sessions: Caveats: Multiple Codex sessions may edit overlapping files (e.g., multiple features write to src/graphics/ ). Git will auto merge unless the same lines are modified. If sessions commit in different branches, merge conflicts are the orchestrator's responsibility. Monitor all sessions with /loop — check event counts, commits, and process vitals for each PID. Stalls are more common with parallel sessions (API rate limits). Use Step 2.7 detection per session. Step 3: Validation Loop (indexion + agent) This is where indexion adds value beyond pure agent review. The validation script: 1. Runs spec verify (vocabulary gap between spec and impl) 2. Runs spec align diff (requirement level drift) 3. Runs spec align trace (traceability matrix) 4. Runs spec align status (CI style pass/fail) 5. Injects all reports into the agent's validate impl prompt 6. Agent produces GO/NO GO decision with specific task numbers 7. On fix , automatically re runs spec impl for failing tasks Step 3.5: Vocabulary Alignment Fix (indexion + agent) After $kiro validate impl passes but spec align shows DRIFTED/SPEC ONLY, the implementation is functionally correct but lacks spec vocabulary in doc comments. This step closes that gap. Note: $kiro validate impl (cc sdd) does not invoke indexion's spec align internally. This step bridges the two tools. Key constraints: The prompt does NOT dictate specific vocabulary to add. It provides the alignment reports and lets the agent determine what to fix. The agent must target public declarations only — private function doc comments are invisible to spec align . Typical: 1 2 fix cycles. If SPEC ONLY persists, the agent may need guidance that the relevant public API entry point should carry the vocabulary (e.g. a top level open function documents the full flow). Known blind sp

indexion-sdd