Intent Reconciliation for Spec Kit

An opt-in GitHub Spec Kit extension that keeps implementation learning from silently rewriting feature intent.

Spec Kit already checks whether implementation matches its spec, plan, and tasks. This extension adds the missing authority question:

When implementation reveals something new, should code, contract, design, or intent change?

It adds two feature artifacts:

specs/<feature>/
├── intent.md       # Compact, explicitly approved outcome and boundaries
└── decisions.md    # Append-only proposals and human resolutions

Installation

specify extension add intent \
  --from https://github.com/SuhaibAslam/spec-kit-reconcile/archive/refs/tags/v1.0.2.zip

Use the blocking entrypoint

Run the extension wrapper instead of core /speckit.implement:

/speckit.intent.implement

The exact command form depends on the active Spec Kit integration. Skills-based agents may expose a form such as $speckit-intent-implement.

The wrapper owns this sequence:

intent.confirm
       │
       ├── blocked ──> stop before implementation
       │
       └── ready
              ↓
         speckit.implement
              ↓
       intent.decisions
              │
              ├── pending ──> stop before convergence
              └── clean/reconciled

The wrapper invokes implementation only after the intent command returns the exact status RECONCILE_STATUS: READY.

Important limitation

Spec Kit extension hooks can automatically run a command, but the core implementation command does not currently interpret a hook's result as a blocking contract. This extension therefore registers no lifecycle hooks and makes no claim that it can intercept a direct call to /speckit.implement.

Calling core /speckit.implement directly bypasses reconciliation. Teams that require the checkpoint should make /speckit.intent.implement their implementation entrypoint.

Commands

Command	Purpose
speckit.intent.confirm	Establish or confirm intent.md, detect contradictions, and refuse readiness while decision proposals remain unresolved.
speckit.intent.decisions	Inspect an implementation slice, append decision proposals, require human resolution, and propagate only accepted decisions.
speckit.intent.implement	Enforce the intent → implement → decisions sequence inside one command.

Decision classifications

Every implementation discovery receives one classification:

Classification	Authority	Normal propagation
implementation-defect	Existing approved artifacts	Correct implementation; do not rewrite intent or contract to excuse the defect.
contract-discovery	Approved intent	Update the spec and tests after approval.
design-decision	Approved intent and contract	Update the plan or research rationale after approval.
intent-change	Human decision only	Update intent.md first, then align downstream artifacts.
accidental-divergence	Existing approved artifacts	Reject or reverse an unsupported implementation choice.

Implementation is evidence, not authority. Passing tests do not prove that intent should change, and code never overwrites an artifact without explicit human resolution.

Append-only history

decisions.md is an audit log. A proposal and its resolution are separate records:

## DEC-0007 — Proposal

- **Observed during**: T031
- **Classification**: design-decision
- **Observation**: The upstream API has no atomic bulk operation.
- **Proposed decision**: Use bounded batches with compensating retries.
- **Evidence**: API contract and failing integration test.
- **Affected artifacts**: plan.md, research.md
- **Status**: proposed

## DEC-0007 — Resolution

- **Decision**: accepted
- **Approved by**: human user
- **Resolved**: 2026-07-29T12:00:00Z
- **Edits authorized**: plan.md, research.md
- **Notes**: Accepted for this feature only.

Existing records are never edited, reordered, or deleted. An unattended run may append proposals but cannot infer human approval.

Reconciliation and convergence

• Reconciliation asks: What did implementation teach us, and which artifact has authority?
• Convergence asks: Does implementation satisfy the resulting spec, plan, and tasks?

Resolve every decision proposal before running /speckit.converge.

Development

python -m pip install -r requirements-dev.txt
pytest

For a local installation into a Spec Kit project:

specify extension add --dev /path/to/spec-kit-reconcile

License

MIT