Repository navigation
Adopt Spec Kit for design work, with a constitution - #178
Merged
Merged
Conversation
…ions made Adds github/spec-kit v1.0.4 (`specify init --integration claude`): `.specify/` templates, scripts and workflow, and `.claude/skills/` for the speckit commands. 380K, no Python, and the lint, type and test gates are unaffected. The reason for adopting it is that design decisions currently live scattered across commit messages, pull request bodies and issues -- the trunk choice, the LangChain ceiling, src-layout, per-collection rather than global capping, deferring the SelfQuery replacement -- and nobody joining later reconstructs that from a git log. Scope is deliberately narrow. Spec Kit is for work with real, unmade decisions: the retriever rewrite, the agent API, website integration, analysis summarisation. It is not for bug triage or dependency bumps, where five steps before code costs more than the fix. Retrofitting specifications onto existing code is archaeology and is not planned. The constitution is written from decisions and mistakes already made rather than generic principles, so it can actually be checked against a diff. Its first article is the lesson that recurred most: verify the path a user takes, not the component you changed -- retrieval was changed three times before anyone asked the pipeline a question, a README fix documented commands that each worked but failed in sequence, and the async path production uses went unexercised while the sync path was measured. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
The Dockerfile does COPY . ., so .specify/ and .claude/ would ship in the image they have no use in. Small -- 380K -- but the build context is for what runs. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Adds github/spec-kit v1.0.4 via
specify init --here --integration claude.Footprint
No Python, so nothing new for ruff or mypy to scan. Verified
lint,mypyandpytestall still pass with it in the tree, and all six bundled shell scripts parse.Scope — deliberately narrow
Spec Kit is for work with real, unmade decisions: the retriever rewrite, the headless agent API, website integration, analysis summarisation.
It is not for bug triage or dependency bumps.
/speckit.specify→/plan→/tasks→/implement→/convergeis five steps before code; on something like this week'sbge-m3default that ceremony would have cost more than the fix. Retrofitting specs onto existing code is archaeology and is not planned.That boundary is written into the constitution so it does not drift.
The constitution
Written from decisions and mistakes actually made, not generic principles, so it can be checked against a diff. Six articles:
bin/retrieval_baselineexists for this.Plus sections recording the quality gates, how contributed code is handled (GSoC applicants who will not update their PRs — harvest and close with credit), and that production and beta pin image tags rather than following
latest.Why
Design decisions currently live scattered across commit messages, PR bodies and issues. The trunk choice, the LangChain ceiling, src-layout, per-collection versus global capping, deferring the SelfQuery replacement — none of that is reconstructable from a git log by someone joining later.
🤖 Generated with Claude Code