Skip to content

About

Intent reconciliation checkpoints for GitHub Spec Kit

Resources

Stars

3 stars

Watchers

0 watching

Forks

Latest commit

 

History

3 Commits

Folders and files

Repository files navigation

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

About

Intent reconciliation checkpoints for GitHub Spec Kit

Resources

Stars

3 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages