Dogfood the ADR toolkit, write README/examples, clean up gitignore - #1
Merged
Merged
Conversation
Initialize docs/decisions/ via the toolkit's own INIT command, then record the four most significant architectural decisions made while building it, via RECORD (evidence gathering, significance scoring, and human approval before writing): - ADR-0002: CHECK's conflict detection stays structural-evidence-only, never semantic/AST-based. - ADR-0003: i18n covers only index.py's generated strings; agent- composed text stays untranslated, governed by a SKILL.md instruction instead of a lookup table. - ADR-0004: harness adapters ship manifest-only with install-time symlinks (never committed to git), and manifest formats are verified against real documentation, never guessed. - ADR-0005: Git Flow branch policy with direct-tag release automation, adopted today alongside the branch/release work itself. All four scored "recommended" (7-12 of 14) on the toolkit's own significance rubric. Full suite: 212/212 passing, unaffected. Co-Authored-By: Claude Sonnet 5 <[email protected]> Claude-Session: https://claude.ai/code/session_01LZwXoWN1hSTy9dmgXi1gf8
README.md was a one-line stub since the initial commit. Replace it with the pitch, the four operations, a per-harness install table linking each adapter's README, the no-agent create --interactive path, MVP scope (linking the two ADRs that define it), and a pointer to AGENTS.md. Add examples/quickstart.md: a full INIT -> RECORD -> CHECK walkthrough against a small example service, including a real constraints: rule that CHECK catches a violation of and then confirms clears after a fix. Every command and JSON block in it is real output from actually running the commands in a scratch repo, not written from memory. Co-Authored-By: Claude Sonnet 5 <[email protected]> Claude-Session: https://claude.ai/code/session_01LZwXoWN1hSTy9dmgXi1gf8
Mark the README-stub item done in improvements.md's Open list, and add a changelog entry for the v0.1.0 release, Git Flow adoption, the dogfooded ADRs, and the new README/quickstart example. Co-Authored-By: Claude Sonnet 5 <[email protected]> Claude-Session: https://claude.ai/code/session_01LZwXoWN1hSTy9dmgXi1gf8
Task-by-task implementation plans (subagent-driven-development artifacts: exact code snippets, TDD steps, agent review process) add little ongoing reference value now that the code itself is the source of truth, and their volume (6700+ lines across 4 files) would clutter a first-time visitor's browse of the repo once it goes public. Kept: docs/superpowers/specs/ — the design spec, which explains product decisions the way docs/decisions/'s ADRs do, and is genuinely useful to a reader. Untracked, not deleted: the plan files stay on disk locally and are still recoverable from git history before this commit; only future changes stop being tracked. Co-Authored-By: Claude Sonnet 5 <[email protected]> Claude-Session: https://claude.ai/code/session_01LZwXoWN1hSTy9dmgXi1gf8
Missed staging this alongside the untrack commit (57d0481) — without it, the plan files would just get re-added on the next git add -A. Co-Authored-By: Claude Sonnet 5 <[email protected]> Claude-Session: https://claude.ai/code/session_01LZwXoWN1hSTy9dmgXi1gf8
Add .DS_Store (found one already loose on disk, uncommitted — this would have been swept up by the next git add -A), Python virtualenv directories, editor/IDE folders, .env/.env.*.local (never commit real credentials), and coverage/build artifacts. None of these are present in the tracked tree today; this is preventive. Co-Authored-By: Claude Sonnet 5 <[email protected]> Claude-Session: https://claude.ai/code/session_01LZwXoWN1hSTy9dmgXi1gf8
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.
Summary
docs/decisions/and records the 4 most significant architectural decisions made while building it (CHECK's structural-only scope, i18n's index-only scope, adapter packaging policy, the Git Flow adoption itself), all via the toolkit's own RECORD workflow (evidence gathering, significance scoring, human approval before writing).README.md(previously a one-line stub) andexamples/quickstart.md— a full INIT → RECORD → CHECK walkthrough with real command output.docs/superpowers/plans/(kept locally/in Notion, not part of the public tree going forward) while keepingdocs/superpowers/specs/tracked..gitignorefor common local artifacts (.DS_Store, venvs, editor configs,.env*, coverage/build output).Test plan
python -m pytest tests/unit tests/integration -v— 212/212 passing after every commit in this branchdocs/decisions/validated via the toolkit's ownvalidate/indexcommands