Intent Integrity Kit

Closing the intent-to-code chasm

An AI coding assistant toolkit that preserves your intent from idea to implementation, with cryptographic verification at each step. Compatible with Claude Code, OpenAI Codex, Google Gemini, and OpenCode.

What's New in v2.9.0

• Implementation commit strategy choice: /iikit-07-implement now asks upfront — per-task commits (clean bisectable history) or batch commits (per-phase, ~47% faster). Batch mode cuts implementation turns in half by eliminating per-task git round-trips.
• Unified post-phase.sh: Commit + dashboard refresh + next-step computation consolidated into a single script call. Reduces 3 tool call round-trips to 1 per phase, saving ~26% on implementation time.
• Dashboard deduplication: Removed redundant dashboard generation from check-prerequisites.sh — was generating the dashboard twice per phase (once in prerequisites, once after artifact creation).

v2.8

• 14 eval scenarios: 9 new cross-phase and full-pipeline evals testing intent preservation across phase boundaries, plus 3 auto-generated and 2 reworked existing evals. Baseline 48% → with context 88%.
• Skill compliance fixes: Constitution creates .specify/context.json with TDD determination in the same write step (was separate step, consistently skipped). Plan skill spec quality gate marked MANDATORY on every run including re-runs. Bugfix skill reads TDD from context.json with fallback when scripts unavailable.
• Eval anti-bleeding: All task.md files stripped of narrator coaching that telegraphed criteria to the agent. Scenarios now test genuine skill behavior, not instruction following.

v2.7

Dashboard overhaul (premise cards, architecture parser, tile review scores, bug cross-links), 27 bug fixes from E2E testing across 12 projects, externalized next-step state machine, generic clarify utility, Bash 3.2 macOS compatibility.

Full changelog →

What is Intent Integrity?

When you tell an AI what you want, there's a gap between your intent and the code it produces. Requirements get lost, assumptions slip in, tests get modified to match bugs. The Intent Integrity Chain is a methodology to close that chasm.

IIKit implements this chain:

Intent ──▶ Spec ──▶ .feature ──▶ Steps ──▶ Code
       ↑       ↑          ↑          ↑
       │       │          │          └── step quality verified (no assert True)
       │       │          └────────────── hash locked (no tampering)
       │       └───────────────────────── @FR-XXX tags traced
       └───────────────────────────────── clarified until aligned

Key principle: No part of the chain validates itself. .feature files are locked before implementation. Step definitions are verified for coverage and quality. If requirements change, you go back to the spec.

Quick Start

Installation

# Install via Tessl
tessl install tessl-labs/intent-integrity-kit

Don't have Tessl? Install it first: npm install -g @tessl/cli

Note: tessl install is the only supported installation method. During publish, shared reference and template files are copied into each skill for self-containment. Cloning the repo directly does not produce self-contained skills.

Your First Project

# 1. Launch your AI assistant
claude          # or: codex, gemini, opencode

# 2. Initialize the project
/iikit-core init

# 3. Define project governance
/iikit-00-constitution

# 4. Specify a feature
/iikit-01-specify Build a CLI task manager with add, list, complete commands

# 5. Plan the implementation
/iikit-02-plan

# 6. Generate tests from requirements
/iikit-04-testify

# 7. Break into tasks
/iikit-05-tasks

# 8. Implement (with integrity verification)
/iikit-07-implement

The Workflow

Each phase builds on the previous. Never skip phases.

┌────────────────────────────────────────────────────────────────────────────┐
│  /iikit-core               →  Initialize project, status, help             │
│  /iikit-clarify            →  Resolve ambiguities (any artifact, any time) │
│  /iikit-bugfix             →  Report and fix bugs                          │
├────────────────────────────────────────────────────────────────────────────┤
│  0. /iikit-00-constitution →  Project governance (tech-agnostic)           │
│  1. /iikit-01-specify      →  Feature specification (WHAT, not HOW)        │
│  2. /iikit-02-plan         →  Technical plan (HOW - frameworks, etc.)      │
│  3. /iikit-03-checklist    →  Quality checklists (unit tests for English)  │
│  4. /iikit-04-testify      →  Gherkin .feature files from requirements     │
│  5. /iikit-05-tasks        →  Task breakdown                               │
│  6. /iikit-06-analyze      →  Cross-artifact consistency check             │
│  7. /iikit-07-implement    →  Execute with integrity verification          │
│  8. /iikit-08-taskstoissues→  Export to GitHub Issues                      │
└────────────────────────────────────────────────────────────────────────────┘

BDD Verification Chain: How Tests Stay Locked

The core of IIKit is preventing circular verification — where AI modifies tests to match buggy code.

How It Works

1. /iikit-04-testify generates Gherkin .feature files from your spec's Given/When/Then scenarios
2. A SHA256 hash of all step lines (across all .feature files) is stored in context.json and as a git note
3. /iikit-07-implement enforces the full BDD chain before marking any task complete:
   • Hash check: .feature files not tampered since testify
   • Step coverage: verify-steps.sh — all Gherkin steps have matching step definitions (dry-run)
   • RED phase: Tests must fail before production code is written
   • GREEN phase: Tests must pass after production code is written
   • Step quality: verify-step-quality.sh — no empty bodies, no assert True, no missing assertions

╭─────────────────────────────────────────────────────────────────────────╮
│  BDD VERIFICATION CHAIN                                                 │
├─────────────────────────────────────────────────────────────────────────┤
│  .feature hash:    valid                                                │
│  Step coverage:    PASS (24/24 steps defined)                           │
│  Step quality:     PASS (0 empty, 0 tautological)                       │
│  TDD status:       mandatory                                            │
├─────────────────────────────────────────────────────────────────────────┤
│  Overall:          PASS                                                 │
╰─────────────────────────────────────────────────────────────────────────╯

If Requirements Change

1. Update spec.md with new requirements
2. Re-run /iikit-04-testify to regenerate .feature files
3. New hash is stored, implementation proceeds

This ensures test changes are intentional and traceable to requirement changes.

Iterating on Specs and Plans

The workflow is linear the first time through. After that, you'll often go back to refine things. Here's how.

Changing requirements (spec.md)

Option A — Re-run the skill: /iikit-01-specify with updated description. It detects the existing spec.md, shows a semantic diff (added/removed/changed requirements), warns about downstream impact, and asks before overwriting.

Option B — Edit directly: Open specs/NNN-feature/spec.md and edit the markdown. This is fine for small tweaks (rewording a requirement, adding an edge case). Then re-run downstream phases to propagate changes.

What to re-run after:

Changing the technical plan (plan.md, research.md)

Option A — Re-run: /iikit-02-plan detects the existing plan.md, shows a semantic diff of tech stack and architecture changes, and flags breaking changes with downstream impact.

Option B — Edit directly: Edit plan.md or research.md for targeted changes (swap a library, update a version, add a design decision).

What to re-run after:

Changing tasks (tasks.md)

Re-run /iikit-05-tasks. It preserves [x] completion status on existing tasks, maps old task IDs to new ones by similarity, and warns about changes to already-completed tasks.

Quick reference: "I want to change X, what do I run?"

Changed requirements?        → edit spec.md → /iikit-02-plan → /iikit-05-tasks
Changed acceptance criteria?  → edit spec.md → /iikit-04-testify
Changed tech stack?           → /iikit-02-plan (or edit plan.md) → /iikit-05-tasks
Changed a library?            → edit research.md → /iikit-05-tasks
Need more quality checks?     → /iikit-03-checklist
Everything looks wrong?       → /iikit-06-analyze (finds inconsistencies)

Rule of thumb: Edit the artifact directly for small changes. Re-run the skill for significant changes — it shows you the diff and warns about downstream impact. Then cascade forward through the phases that depend on what you changed.

Phase Separation

Understanding what belongs where is critical:

Constitution is spec-agnostic. It transcends individual features - that's why it lives at the root, not in /specs.

Powered by Tessl

IIKit is distributed as a Tessl tile - a versioned package of AI-optimized context.

What Tessl provides:

• Installation: tessl install tessl-labs/intent-integrity-kit adds IIKit to any project
• Runtime knowledge: During implementation, IIKit queries the Tessl registry for current library APIs — so the AI uses 2026 React patterns, not 2023 training data
• 2000+ tiles: Documentation, rules, and skills for major frameworks and libraries

How IIKit uses Tessl:

Project Structure

your-project/
├── CONSTITUTION.md              # Project governance (spec-agnostic)
├── AGENTS.md                    # Agent instructions
├── tessl.json                   # Installed tiles
├── .specify/                    # IIKit working directory
│   └── context.json             # Feature state
└── specs/
    └── NNN-feature-name/
        ├── spec.md              # Feature specification
        ├── plan.md              # Implementation plan
        ├── tasks.md             # Task breakdown
        ├── research.md          # Tech research + tiles
        ├── data-model.md        # Data structures
        ├── contracts/           # API contracts
        ├── checklists/          # Quality checklists
        └── tests/
            └── features/        # Locked Gherkin .feature files

Supported Agents

Acknowledgments

IIKit builds on GitHub Spec-Kit, which pioneered specification-driven development for AI coding assistants. The phased workflow, artifact structure, and checklist gating concepts originate from Spec-Kit.

IIKit extends Spec-Kit with:

• Assertion integrity - Cryptographic verification (hash-locked .feature files, pre-commit enforcement) to prevent circular validation where AI modifies tests to match buggy code
• Skills instead of scripts - Phases are Tessl skills (scoped context, prerequisite gating) rather than prompt-plus-script pairs, giving agents better adherence and context management
• Tessl integration - Distribution via tile registry plus runtime library knowledge during implementation

Learn More

• Dashboard views and features - Visual dashboard documentation
• GitHub Spec-Kit - The original specification-driven development framework
• Intent Integrity Chain explained - The methodology behind IIKit

License

MIT License - See LICENSE for details.