feat: implement SDD adoption - #230
Conversation
Implements ADR: docs/adr/spec-driven-development.md Changes: - AGENTS.md: rewrite as navigation guide with topic index (FullSend pattern — lean entry point for all AI tools) - .specify/memory/constitution.md: bump to v2.0.0, add SDD principle, Go code style, commit message standards, updated file organization and quality gates - openspec/config.yaml: fill in LoLa project context and conventions for AI-generated change proposals - .gitignore: add .opencode/ (uf optional, contributor-local), track .specify/memory/ (constitution must be committed) - CONTRIBUTING.md: add SDD section (when to write ADR/spec) - .github/PULL_REQUEST_TEMPLATE.md: add Spec/ADR Reference field, update checklist for Go + commit standards
📝 WalkthroughWalkthroughThis PR adds a project constitution, spec-driven development guidance, OpenSpec configuration, updated agent instructions, pull request checklist changes, and ignore rules for contributor tooling. ChangesSpec-driven development governance
Estimated code review effort: 1 (Trivial) | ~5 minutes Possibly related PRs
Suggested labels: 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 |
![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: 1208c1a836
ℹ️ 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".
| - [ ] Tests pass (`pytest` / `go test -race ./...`) | ||
| - [ ] Linting passes (`ruff check src tests` / `golangci-lint`) |
There was a problem hiding this comment.
For Go PRs, this checklist lets authors tick the lint gate with bare golangci-lint; I checked golangci-lint --help, and only the run subcommand is described as running the linters, while the bare command just prints help and exits 0. It also omits the required go vet ./..., so Go changes can satisfy the template without running two required checks; please mirror golangci-lint run and go vet ./....
AGENTS.md reference: AGENTS.md:L15-L15
Useful? React with 👍 / 👎.
| - [ ] Type checking passes (`ty check`) | ||
| - [ ] Tests pass (`pytest` / `go test -race ./...`) | ||
| - [ ] Linting passes (`ruff check src tests` / `golangci-lint`) | ||
| - [ ] Type checking passes (`basedpyright src`) |
There was a problem hiding this comment.
For Python PRs, this switches the checklist to basedpyright src, but the committed dev dependencies still include ty/mypy and not basedpyright, and CI still runs uv run ty check plus uv run mypy src. Contributors following the template after uv sync --group dev either hit a missing command or skip the checks CI actually enforces; add basedpyright to the toolchain/CI or keep the checklist on the existing checks.
Useful? React with 👍 / 👎.
| once, install them to Claude Code, Cursor, Gemini CLI, OpenCode, | ||
| and more. | ||
|
|
||
| Tech stack: Python 3.13+ (src/lola/) and Go 1.24+ (cmd/, internal/) |
There was a problem hiding this comment.
The OpenSpec context says Go 1.24+, but go.mod declares go 1.26.3. Any AI/tooling or contributor using this SDD context to select a 1.24/1.25 toolchain will fail before building or testing, so update this line to the module's actual minimum Go version.
Useful? React with 👍 / 👎.
| | cursor | `.cursor/skills/` | `.cursor/commands/` | `.cursor/agents/` | | ||
| | gemini-cli | `GEMINI.md` | `.gemini/commands/` | N/A | | ||
| | opencode | `AGENTS.md` | `.opencode/commands/` | `.opencode/agents/` | | ||
| | copilot | `.github/skills/` | `.github/prompts/` | `.github/agents/` | |
There was a problem hiding this comment.
This row now documents a copilot assistant, but the CLI's -a/--assistant choices come from TARGETS, which contains copilot-cli and copilot-vscode but no copilot. Anyone following AGENTS.md and running lola install ... -a copilot gets rejected, so list the actual assistant keys rather than the collapsed label.
Useful? React with 👍 / 👎.
SecKatie
left a comment
SecKatie
left a comment
There was a problem hiding this comment.
Just a few nitpicks. You can take them or leave them.
| - Always include a "Non-goals" section | ||
| - Reference the relevant ADR if one exists | ||
| tasks: | ||
| - Break tasks into chunks of max 2 hours |
There was a problem hiding this comment.
Models are very bad at estimating time to completion. Should we have another metric?
| 3. **Updates**: `lola update` regenerates assistant files from source modules | ||
| 4. **Marketplace Registration**: `lola market add <name> <url>` fetches marketplace catalogs to `~/.lola/market/` (reference) and `~/.lola/market/cache/` (full catalog) | ||
| 5. **Module Discovery**: `lola search <query>` searches both the local module registry and enabled marketplace caches (use `--mod` or `--market` to scope); `lola mod search <query>` is a deprecated alias for `lola search <query> --mod`; `lola install <module>` auto-adds from marketplace if not in registry | ||
| | Task | Read this | |
There was a problem hiding this comment.
Let's include the PR template in here.
| @@ -141,6 +141,30 @@ PR updates automatically! | |||
| **Note**: For large changes, open an issue first to discuss your | |||
| approach. | |||
|
|
|||
There was a problem hiding this comment.
Can we also say something about the PR template?
![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
🧹 Nitpick comments (3)
.specify/memory/constitution.md (3)
166-167: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick winAdd the blank line required before the Markdown table.
The static analysis report flags MD058 at Line 167. Add a blank line
between### Violations Requiring Justificationand the table.[details]
[summary]Proposed Markdown fix[/summary]### Violations Requiring Justification + | Pattern | When Allowed | Justification Required |[/details]
🤖 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 @.specify/memory/constitution.md around lines 166 - 167, Insert a blank line between the “Violations Requiring Justification” heading and the following Markdown table.Source: Linters/SAST tools
110-110: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick winAdd language identifiers to both fenced code blocks.
The static analysis report flags MD040 for the file-tree fences. Use a
textlanguage identifier on each opening fence.
.specify/memory/constitution.md#L110-L110: add thetextlanguage identifier.AGENTS.md#L101-L101: add thetextlanguage identifier.🤖 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 @.specify/memory/constitution.md at line 110, Add the text language identifier to the opening file-tree fenced code block in .specify/memory/constitution.md at lines 110-110 and to the corresponding opening fence in AGENTS.md at lines 101-101; leave the contents of both blocks unchanged.Source: Linters/SAST tools
150-153: 🗄️ Data Integrity & Integration | 🔵 Trivial | ⚡ Quick winDefine one coverage scope across the governance documents.
As per coding guidelines, keep coverage above 80 percent. The supplied
coverage configuration measuressrc/lola, but the policy text says
“changed files”. This PR changes only documentation and configuration
files. Define a docs/config-only exception or use “changed source files”
in all three locations.
.specify/memory/constitution.md#L150-L153: define the source-file scope or docs/config-only exception.openspec/config.yaml#L18-L18: mirror the agreed coverage wording.AGENTS.md#L17-L17: mirror the agreed coverage wording.🤖 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 @.specify/memory/constitution.md around lines 150 - 153, Define a single coverage scope using “changed source files” or an explicit docs/config-only exception in the Pre-Merge requirement of .specify/memory/constitution.md (lines 150-153), then mirror the same wording in openspec/config.yaml (line 18) and AGENTS.md (line 17).Source: Coding guidelines
🤖 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 @.github/PULL_REQUEST_TEMPLATE.md:
- Around line 29-32: Update the pull request checklist by adding conditional
entries for go vet ./..., coverage above 80%, and e2e BDD tests when introducing
new CLI commands; also provide an explicit N/A option for docs-only or
configuration-only changes, including the existing test, lint, type-check, and
commit checks.
In @.specify/memory/constitution.md:
- Around line 177-188: Use consistent approval wording in the “Constitution
Authority” and “Amendment Process” sections: replace the differing “both
maintainers” and “unanimous maintainer approval” phrases with one shared rule,
such as approval from all current maintainers.
- Around line 24-31: Update the “Type Safety & Modern Python” requirements in
the constitution and the pre-commit gate documentation to match the checks
actually enforced by .pre-commit-config.yaml: either add a basedpyright hook and
hooks for every listed gate, or remove unsupported gate claims and document the
existing ty check and mypy checks instead.
In `@AGENTS.md`:
- Line 86: Update the target-definition reference on line 86 of AGENTS.md from
the nonexistent src/lola/targets.py file to the existing src/lola/targets/
directory, preserving the surrounding description.
---
Nitpick comments:
In @.specify/memory/constitution.md:
- Around line 166-167: Insert a blank line between the “Violations Requiring
Justification” heading and the following Markdown table.
- Line 110: Add the text language identifier to the opening file-tree fenced
code block in .specify/memory/constitution.md at lines 110-110 and to the
corresponding opening fence in AGENTS.md at lines 101-101; leave the contents of
both blocks unchanged.
- Around line 150-153: Define a single coverage scope using “changed source
files” or an explicit docs/config-only exception in the Pre-Merge requirement of
.specify/memory/constitution.md (lines 150-153), then mirror the same wording in
openspec/config.yaml (line 18) and AGENTS.md (line 17).
🪄 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: 50ae5cd0-2a34-4a90-9750-0f1ff78c389d
📒 Files selected for processing (6)
.github/PULL_REQUEST_TEMPLATE.md.gitignore.specify/memory/constitution.mdAGENTS.mdCONTRIBUTING.mdopenspec/config.yaml
| - [ ] Tests pass (`pytest` / `go test -race ./...`) | ||
| - [ ] Linting passes (`ruff check src tests` / `golangci-lint`) | ||
| - [ ] Type checking passes (`basedpyright src`) | ||
| - [ ] Commit subjects ≤ 50 chars, body wrapped at 72 |
There was a problem hiding this comment.
🗄️ Data Integrity & Integration | 🟠 Major | ⚡ Quick win
Complete and condition the required checklist.
The constitution requires go vet ./..., coverage above 80 percent, and
e2e BDD tests for new CLI commands on Lines 145, 152, and 154. The changed
checklist omits these checks. It also has no N/A path for docs-only or
configuration-only changes, although this PR is documentation-only. Add
the missing conditional checks or state when each item is not applicable.
[details]
[summary]Checklist additions[/summary]
+- [ ] `go vet ./...` passes for Go changes
+- [ ] Coverage above 80% for changed source files
+- [ ] New CLI commands have e2e BDD tests
+- [ ] Mark checks N/A for docs/config-only changes[/details]
📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| - [ ] Tests pass (`pytest` / `go test -race ./...`) | |
| - [ ] Linting passes (`ruff check src tests` / `golangci-lint`) | |
| - [ ] Type checking passes (`basedpyright src`) | |
| - [ ] Commit subjects ≤ 50 chars, body wrapped at 72 | |
| - [ ] Tests pass (`pytest` / `go test -race ./...`) | |
| - [ ] Linting passes (`ruff check src tests` / `golangci-lint`) | |
| - [ ] Type checking passes (`basedpyright src`) | |
| - [ ] Commit subjects ≤ 50 chars, body wrapped at 72 | |
| - [ ] `go vet ./...` passes for Go changes | |
| - [ ] Coverage above 80% for changed source files | |
| - [ ] New CLI commands have e2e BDD tests | |
| - [ ] Mark checks N/A for docs/config-only changes |
🤖 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 @.github/PULL_REQUEST_TEMPLATE.md around lines 29 - 32, Update the pull
request checklist by adding conditional entries for go vet ./..., coverage above
80%, and e2e BDD tests when introducing new CLI commands; also provide an
explicit N/A option for docs-only or configuration-only changes, including the
existing test, lint, type-check, and commit checks.
| ### III. Type Safety & Modern Python (NON-NEGOTIABLE) | ||
| Leverage Python 3.13+ features for code quality: | ||
| - Type hints required on all functions (params + returns) | ||
| - Use modern syntax: `list[str]` not `List[str]` | ||
| - Dataclasses for data models | ||
| - Immutable data structures preferred | ||
| - Pass basedpyright type checker in standard mode | ||
| - No `typing.Any` without justification |
There was a problem hiding this comment.
🗄️ Data Integrity & Integration | 🟡 Minor | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
set -euo pipefail
rg -n -C3 \
'basedpyright|ty check|mypy|ruff|golangci|go vet|gofmt|80|markdown|yaml' \
.pre-commit-config.yaml pyproject.tomlRepository: LobsterTrap/lola
Length of output: 2887
🏁 Script executed:
#!/bin/bash
set -euo pipefail
printf '%s\n' '--- .pre-commit-config.yaml ---'
cat -n .pre-commit-config.yaml
printf '%s\n' '--- constitution.md lines 20-35 and 135-155 ---'
sed -n '20,35p;135,155p' .specify/memory/constitution.md
printf '%s\n' '--- related configuration and references ---'
rg -n -C3 'basedpyright|typeCheckingMode|ty check|mypy|automated|gate|coverage|pre-commit' \
.specify/memory/constitution.md .pre-commit-config.yaml pyproject.toml README.md \
2>/dev/null || trueRepository: LobsterTrap/lola
Length of output: 9024
Align the documented pre-commit gates with the hooks.
.pre-commit-config.yaml does not run basedpyright; it runs ty check and mypy. Add a basedpyright hook or document an enforced checker. Lines 143-148 also list gates without corresponding hooks. Remove those claims or add the required hooks.
🤖 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 @.specify/memory/constitution.md around lines 24 - 31, Update the “Type
Safety & Modern Python” requirements in the constitution and the pre-commit gate
documentation to match the checks actually enforced by .pre-commit-config.yaml:
either add a basedpyright hook and hooks for every listed gate, or remove
unsupported gate claims and document the existing ty check and mypy checks
instead.
| ### Constitution Authority | ||
| - This constitution supersedes code review preferences | ||
| - All PRs must verify compliance via checklist | ||
| - Violations require justification in PR description | ||
| - Amendments require approval from both maintainers | ||
|
|
||
| ### Amendment Process | ||
| 1. Propose change with rationale | ||
| 2. Discuss impact on existing code | ||
| 3. Document migration plan if breaking | ||
| 4. Require unanimous maintainer approval | ||
| 5. Update constitution and announce |
There was a problem hiding this comment.
📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win
Use one amendment approval rule.
Line 181 requires approval from “both maintainers”. Line 187 requires
“unanimous maintainer approval”. These rules differ when the maintainer
count is not exactly two. Use one term, such as “all current maintainers”,
in both sections.
[details]
[summary]Proposed wording[/summary]
- Amendments require approval from both maintainers
+ Amendments require approval from all current maintainers
...
-4. Require unanimous maintainer approval
+4. Require approval from all current maintainers[/details]
📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| ### Constitution Authority | |
| - This constitution supersedes code review preferences | |
| - All PRs must verify compliance via checklist | |
| - Violations require justification in PR description | |
| - Amendments require approval from both maintainers | |
| ### Amendment Process | |
| 1. Propose change with rationale | |
| 2. Discuss impact on existing code | |
| 3. Document migration plan if breaking | |
| 4. Require unanimous maintainer approval | |
| 5. Update constitution and announce | |
| ### Constitution Authority | |
| - This constitution supersedes code review preferences | |
| - All PRs must verify compliance via checklist | |
| - Violations require justification in PR description | |
| - Amendments require approval from all current maintainers | |
| ### Amendment Process | |
| 1. Propose change with rationale | |
| 2. Discuss impact on existing code | |
| 3. Document migration plan if breaking | |
| 4. Require approval from all current maintainers | |
| 5. Update constitution and announce |
🤖 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 @.specify/memory/constitution.md around lines 177 - 188, Use consistent
approval wording in the “Constitution Authority” and “Amendment Process”
sections: replace the differing “both maintainers” and “unanimous maintainer
approval” phrases with one shared rule, such as approval from all current
maintainers.
| - `src/lola/cli/market.py` — Marketplace management | ||
| - `src/lola/models.py` — Data models | ||
| - `src/lola/config.py` — Global paths | ||
| - `src/lola/targets.py` — Assistant definitions |
There was a problem hiding this comment.
🗄️ Data Integrity & Integration | 🟡 Minor | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
set -euo pipefail
fd -t f -t d 'targets(\.py)?$' src/lola || true
rg -n 'src/lola/targets(\.py|/)' \
AGENTS.md .specify/memory/constitution.md docs/dev-guideRepository: LobsterTrap/lola
Length of output: 398
🏁 Script executed:
#!/bin/bash
set -euo pipefail
python3 - <<'PY'
from pathlib import Path
root = Path(".")
checks = {
"AGENTS.md": ["src/lola/targets.py"],
".specify/memory/constitution.md": [
"src/lola/targets/",
],
}
for name, needles in checks.items():
path = root / name
text = path.read_text()
print(f"{name}: exists={path.exists()}")
for needle in needles:
lines = [
i for i, line in enumerate(text.splitlines(), 1)
if needle in line
]
print(f" {needle}: lines={lines}")
for rel in ("src/lola/targets.py", "src/lola/targets"):
path = root / rel
print(f"{rel}: exists={path.exists()} type="
f"{'dir' if path.is_dir() else 'file' if path.is_file() else 'missing'}")
print("tracked target paths:")
for path in __import__("subprocess").check_output(
["git", "ls-files", "src/lola/targets.py", "src/lola/targets"],
text=True,
).splitlines():
print(f" {path}")
PYRepository: LobsterTrap/lola
Length of output: 672
Fix the targets path in AGENTS.md.
src/lola/targets.py does not exist. The target definitions are in src/lola/targets/. Update Line 86.
🤖 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 `@AGENTS.md` at line 86, Update the target-definition reference on line 86 of
AGENTS.md from the nonexistent src/lola/targets.py file to the existing
src/lola/targets/ directory, preserving the surrounding description.
2 participants
Summary
Spec / ADR Reference
ADR: docs/adr/spec-driven-development.md (merged in PR #229)
Related Issues
Follow-on to #229
Test Plan
Checklist
pytest/go test -race ./...) — N/A: docs onlyruff check src tests/golangci-lint) — N/A: docs onlybasedpyright src) — N/A: docs onlyAI Disclosure
AI-assisted with Claude via OpenCode. All file content reviewed
and approved by maintainer before commit.
Summary by CodeRabbit
Documentation
Chores