docs: propose spec-driven development ADR - #229
Conversation
📝 WalkthroughWalkthroughChangesSpec-Driven Development
Estimated code review effort: 1 (Trivial) | ~5 minutes Suggested reviewers: 🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
mrbrandao
added
documentation
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: b0c33450d7
ℹ️ About Codex in GitHub
Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".
|
|
||
| 1. **AGENTS.md** — navigation guide and entry point for all AI | ||
| tools and contributors | ||
| 2. **.specify/memory/constitution.md** — project standards and |
There was a problem hiding this comment.
This ADR marks SDD as accepted and immediately makes .specify/memory/constitution.md one of the two co-authoritative process documents, but that path is not present in this commit or elsewhere in the repo, and the implementation notes say it will only be updated by a later PR. In the interim, any contributor or agent following the accepted process hits a missing standards document for the required source of truth; either add the constitution with this ADR or keep the status/wording proposed until the implementation PR lands.
Useful? React with 👍 / 👎.
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 4
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/adr/spec-driven-development.md`:
- Around line 28-31: Update the ADR statement about AGENTS.md and topic-guide
artifact discovery to use normative wording: require the guide to provide these
pointers, or explicitly mark the behavior as pending until
feat/sdd-implementation merges. Align the wording with the deferred updates
referenced near the implementation section.
- Around line 20-26: Clarify the relationship between AGENTS.md and
.specify/memory/constitution.md in the ADR: AGENTS.md governs navigation and
entry-point guidance, while the constitution governs project standards and
principles; explicitly state how to resolve any overlap or conflict.
- Around line 36-38: Update the e2e BDD coverage statement in the spec-driven
development ADR to include a stable issue, PR, or owner reference for the
follow-on task; if no such task exists, replace “tracked” with “identified”
rather than implying active tracking.
- Around line 74-75: Update the tool-name description in the spec-driven
development ADR to use “Spec Kit” for GitHub’s project, and define uf with its
intended project name or replace it with the correct tool name. Preserve the
requirement that contributors use one of the listed spec-driven development
tools.
🪄 Autofix
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro Plus
Run ID: 8ac141bb-25c5-43eb-9a3c-482c2f507def
📒 Files selected for processing (1)
docs/adr/spec-driven-development.md
| LoLa adopts Spec-Driven Development (SDD) governed by two | ||
| co-authoritative documents: | ||
|
|
||
| 1. **AGENTS.md** — navigation guide and entry point for all AI | ||
| tools and contributors | ||
| 2. **.specify/memory/constitution.md** — project standards and | ||
| principles |
There was a problem hiding this comment.
🗄️ Data Integrity & Integration | 🟠 Major | ⚡ Quick win
Define scope and precedence for the two governing documents.
AGENTS.md and .specify/memory/constitution.md are both called co-authoritative. The ADR does not define what happens if they conflict. State that AGENTS.md controls navigation and the constitution controls standards, or add an explicit precedence rule. This prevents contributors and AI tools from applying different requirements.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/adr/spec-driven-development.md` around lines 20 - 26, Clarify the
relationship between AGENTS.md and .specify/memory/constitution.md in the ADR:
AGENTS.md governs navigation and entry-point guidance, while the constitution
governs project standards and principles; explicitly state how to resolve any
overlap or conflict.
| AGENTS.md points AI agents to the right artifacts for any task. | ||
| Where specs exist, AI agents find them by following the topic | ||
| guide in AGENTS.md. No specific spec format or tooling is | ||
| mandated. |
There was a problem hiding this comment.
🗄️ Data Integrity & Integration | 🟡 Minor | ⚡ Quick win
Use normative wording until the implementation PR lands.
This text states that AGENTS.md already points agents to the required artifacts. Lines 96-97 defer those updates to feat/sdd-implementation. State that the guide must provide these pointers, or mark the behavior as pending until that PR merges. Otherwise, the accepted ADR can describe a process that is not available in the current repository.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/adr/spec-driven-development.md` around lines 28 - 31, Update the ADR
statement about AGENTS.md and topic-guide artifact discovery to use normative
wording: require the guide to provide these pointers, or explicitly mark the
behavior as pending until feat/sdd-implementation merges. Align the wording with
the deferred updates referenced near the implementation section.
| New CLI commands and features require e2e BDD tests (Gherkin, | ||
| in `e2e/features/`). Existing coverage gap is acknowledged and | ||
| tracked as a follow-on task. |
There was a problem hiding this comment.
📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win
Link the follow-on coverage task.
The ADR says the existing e2e coverage gap is tracked, but it provides no issue, PR, or owner. Add a stable reference. If no task exists, change “tracked” to “identified” until one exists.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/adr/spec-driven-development.md` around lines 36 - 38, Update the e2e BDD
coverage statement in the spec-driven development ADR to include a stable issue,
PR, or owner reference for the follow-on task; if no such task exists, replace
“tracked” with “identified” rather than implying active tracking.
| - Description: Require all contributors to use Speckit, OpenSpec, | ||
| or uf for spec-driven development |
There was a problem hiding this comment.
📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
set -euo pipefail
# Expect: every named alternative has a definition or reference.
rg -n --hidden -g '!.git' -g '*.md' -i '\b(uf|spec[ -]?kit|openspec)\b' .Repository: LobsterTrap/lola
Length of output: 2276
🏁 Script executed:
#!/bin/bash
set -euo pipefail
printf '%s\n' '--- ADR context ---'
cat -n docs/adr/spec-driven-development.md | sed -n '60,82p'
printf '%s\n' '--- Local tool-name and directory evidence ---'
rg -n --hidden -g '!.git' -i \
'(^|[^[:alnum:]_])(uf|spec[ -]?kit|openspec)([^[:alnum:]_]|$)|(^|[^[:alnum:]_])speckit[. /_-]' .
printf '%s\n' '--- Candidate definitions and references ---'
git ls-files | rg -i '(^|/)(readme|index|spec.?kit|open.?spec|uf)([^/]*)(/|\.|$)|(^|/)openspec/|(^|/)specs/'Repository: LobsterTrap/lola
Length of output: 4496
🌐 Web query:
GitHub github/spec-kit official project name documentation "Spec Kit"
💡 Result:
The official project name is Spec Kit [1][2]. It is an open-source toolkit maintained by GitHub, designed to facilitate Spec-Driven Development (SDD) when working with AI coding agents [1][3]. The project documentation is available at https://github.github.io/spec-kit/ [1][2]. The toolkit is distributed as the specify-cli package on PyPI [4][5]. The command-line interface associated with the toolkit is referred to as the Specify CLI, which is invoked using the specify command [4][6][7]. Core processes within the toolkit are triggered by your AI coding agent using /speckit.* slash commands [6][7].
Citations:
- 1: https://github.com/github/spec-kit
- 2: https://github.github.com/spec-kit/
- 3: https://github.blog/ai-and-ml/generative-ai/spec-driven-development-with-ai-get-started-with-a-new-open-source-toolkit/
- 4: https://github.github.com/spec-kit/installation.html
- 5: https://github.github.io/spec-kit/installation.html
- 6: https://github.github.io/spec-kit/reference/overview.html
- 7: https://github.github.io/spec-kit/quickstart.html
Define the tool names.
Use Spec Kit for GitHub’s project. Define uf or replace it with the intended project name; no repository reference defines uf.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/adr/spec-driven-development.md` around lines 74 - 75, Update the
tool-name description in the spec-driven development ADR to use “Spec Kit” for
GitHub’s project, and define uf with its intended project name or replace it
with the correct tool name. Preserve the requirement that contributors use one
of the listed spec-driven development tools.
SecKatie
left a comment
SecKatie
left a comment
There was a problem hiding this comment.
Great direction! I am in agreement.
## Summary - Implements the SDD adoption ADR (PR #229) - Rewrites AGENTS.md as a lean navigation guide with topic index - Updates constitution to v2.0.0 with SDD, Go standards, and commit conventions - Fills openspec/config.yaml with LoLa project context - Adds SDD section to CONTRIBUTING.md - Adds Spec/ADR Reference field to PR template - Gitignores .opencode/ (optional contributor tooling) ## Spec / ADR Reference ADR: docs/adr/spec-driven-development.md (merged in PR #229) ## Related Issues Follow-on to #229 ## Test Plan - [x] Read AGENTS.md and confirm topic guide points to correct files - [x] Read .specify/memory/constitution.md and confirm v2.0.0 changes - [x] Read openspec/config.yaml and confirm LoLa context is accurate - [x] Confirm .gitignore tracks .specify/memory/ and ignores .opencode/ - [x] Confirm CONTRIBUTING.md SDD section is clear - [x] Confirm PR template has Spec/ADR Reference field ## Checklist - [x] Tests pass (`pytest` / `go test -race ./...`) — N/A: docs only - [x] Linting passes (`ruff check src tests` / `golangci-lint`) — N/A: docs only - [x] Type checking passes (`basedpyright src`) — N/A: docs only - [x] Commit subjects ≤ 50 chars, body wrapped at 72 ## AI Disclosure AI-assisted with Claude via OpenCode. All file content reviewed and approved by maintainer before commit. <!-- This is an auto-generated comment: release notes by coderabbit.ai --> ## Summary by CodeRabbit * **Documentation** * Added project-wide constitution and governance standards. * Documented spec-driven development, ADRs, coding practices, testing, and contribution workflows. * Updated repository guidance with architecture, commands, modules, and review expectations. * Added configuration for specifications, proposals, tasks, and project conventions. * **Chores** * Refined pull request checklist guidance, including testing, linting, typing, and commit-message requirements. * Updated ignored files for specification and contributor tooling directories. <!-- end of auto-generated comment: release notes by coderabbit.ai -->
2 participants
Summary
formalizing the informal practice already present in LoLa
all AI tools, with .specify/memory/constitution.md as the
standards document
fits; AI agents follow topic pointers in AGENTS.md
Related Issues
Opens discussion on SDD adoption. Implementation PR
(
feat/sdd-implementation) follows once this ADR is accepted.Test Plan
docs/adr/spec-driven-development.mdand confirmthe decision accurately describes the intended SDD approach
follow-on PR
Checklist
pytest) — N/A: documentation onlyruff check src tests) — N/A: documentation onlyty check) — N/A: documentation onlyAI Disclosure
Drafted with AI assistance (Claude via OpenCode). The ADR
reflects decisions made through collaborative exploration of SDD
tooling options and LoLa's existing informal practices.
Summary by CodeRabbit