docs: init CLAUDE.md runtime prompt, correct README to match reality - #4
Merged
Conversation
Re-initializes CLAUDE.md from the bootstrap seed into a full runtime prompt and brings README.md in line with what the repo actually is. CLAUDE.md: repo status (the analyse-propose-apply lane is scaffold-only today), build/lint/test commands as CI runs them, the three-layer CLI architecture and the contracts the teken rubric gate enforces, an 8-step checklist for adding a noun/verb, and the working conventions (version-bump-every-PR, the cicd lane, cite-don't-import skills, worktree layout, memory discipline). README.md: adds a Status section stating the refactoring lane is not implemented yet, corrects the vendored skill count (11 -> 18), and replaces the clone-a-template "Make it your own" checklist with a Contributing section. Fixes a broken Quickstart: README instructed `uv run refactoring-cli`, which is the distribution name rather than the console script, so every documented command failed with `Failed to spawn: refactoring-cli`. The scaffold rename is incomplete (package dir and script are `refactor`; dist name, argparse prog, help text, explain catalog and tests all say `refactoring-cli`) — corrected to `refactor` and the divergence is now documented in both files with a discovery command and target list. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01PoE5ij1LNYZYi52xaogwRJ
Contributor
Author
|
/agentic_review |
|
PR Summary by QodoDocs: initialize runtime CLAUDE.md and align README with actual CLI/script name
AI Description
Diagram
High-Level Assessment
Files changed (5)
|
Code Review by Qodo
1. ~/.eidetic/memory referenced in docs
|
![qodo-code-review[bot]](https://avatars.githubusercontent.com/in/484649?s=60&v=4){kind=small}
Comment on lines
+223
to
+224
| vendored wrappers default to this agent's personal private scope (`--scope | ||
| refactoring-cli --visibility private`, store `~/.eidetic/memory`); pass |
There was a problem hiding this comment.
1. ~/.eidetic/memory referenced in docs 📜 Skill insight ≡ Correctness
CLAUDE.md newly documents storing data at ~/.eidetic/memory, which is a per-user dotfile path disallowed in committed docs/configs. This can break portability and violates the repo policy requiring repo-local or portable lookup documentation instead.
Agent Prompt
## Issue description
`CLAUDE.md` references the per-user dotfile path `~/.eidetic/memory`, which is disallowed in committed documentation.
## Issue Context
The compliance rule forbids `~/.<dotfile>` references in committed docs/configs unless they are under `~/.claude/skills/<x>/scripts/` or `~/.culture/`.
## Fix Focus Areas
- CLAUDE.md[223-224]
ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools
| uv run pytest tests/test_cli.py::test_whoami_json -v # a single test | ||
| uv run pytest -k "doctor" -v # by name | ||
| uv run pytest -n auto --cov=refactor --cov-report=term # with coverage | ||
| bash .claude/skills/run-tests/scripts/test.sh --ci # exact CI invocation |
There was a problem hiding this comment.
2. Ci command docs drift 🐞 Bug ⚙ Maintainability
CLAUDE.md claims bash .claude/skills/run-tests/scripts/test.sh --ci is the “exact CI invocation”, but CI runs pytest with a slightly different command and the script itself says it only “mimic[s]” CI. This can mislead contributors when reproducing CI failures and investigating coverage differences.
Agent Prompt
## Issue description
`CLAUDE.md` states that the run-tests skill invocation is the **exact** CI command, but CI uses a different pytest invocation and the script itself documents that it only *mimics* CI. This is a documentation correctness/operability issue: people will copy/paste the documented command expecting to exactly reproduce CI.
## Issue Context
- CI runs `uv run pytest -n auto --cov=refactor --cov-report=xml:coverage.xml --cov-report=term -v`.
- The run-tests skill uses `uv run pytest -n auto --cov --cov-report=xml:coverage.xml --cov-report=term -v` (relies on `[tool.coverage.run] source`), and its header calls this “Mimic full CI invocation”.
## Fix Focus Areas
- CLAUDE.md[31-45]
- .github/workflows/tests.yml[28-33]
- .claude/skills/run-tests/scripts/test.sh[8-14]
ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools
OriNachum
added a commit
that referenced
this pull request
Aug 24, 2026
Resolves the version-bump collision between this branch (0.6.1 -> 0.7.0, ask-colleague 1.63.0 re-vendor) and main's PR #4 (0.6.1 -> 0.6.2, CLAUDE.md runtime prompt + README correction). No substantive overlap: the branch only touches .claude/skills/ask-colleague/** and docs/skill-sources.md, neither of which main modified. - pyproject.toml: keep 0.7.0 (minor supersedes main's patch) - CHANGELOG.md: keep both entries, 0.7.0 above 0.6.2 - uv.lock: take main's alphabetically re-sorted lock, re-run `uv lock` for 0.7.0 — the apparent conflict was uv moving the workspace-member block, not a dependency change Co-Authored-By: Claude Opus 5 (1M context) <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.
Summary
Runs
/initon this repo for the first time and bringsREADME.mdin line withwhat the code actually does.
CLAUDE.mdwas still the bootstrap seed left byscaffold refactoring-cli from culture-agent-template— it described how tore-initialize itself, not how to work here. It's now a full runtime prompt.
What changed
CLAUDE.md— re-initialized from the seed:project description does not exist yet; the tree is still the scaffold, and
several docstrings/catalog entries still call this "a clonable template for
AgentCulture mesh agents." A future instance reading the description would
otherwise hunt for code that isn't there.
and the two non-obvious
pyproject.tomlsettings (fail_under = 60;relative_files = true, load-bearing for Sonar coverage mapping).tekenrubric gateenforces —
_CliArgumentParserrouting parse-time errors through theerror:/hint:contract, the_json_hintargv pre-scan, whyread_agent_fields()hand-parses YAML (runtimedependencies = []), and whyfind_culture_yaml()walks up from__file__rather than cwd._build_parser,the explain catalog, both payloads in
learn.py,_VERBSinoverview.py,and tests — miss one and the rubric gate fails.
cicdlane, thecite-don't-import rule for
.claude/skills/, worktree layout, memorydiscipline, and the
ask-colleaguereflex.README.md— corrected to describe this agent rather than the template itwas scaffolded from:
section.
Bug fixed
The README Quickstart instructed
uv run refactoring-cli whoami. That is thedistribution name, not the console script, so every documented command failed:
The scaffold rename is incomplete — package directory and console script are
refactor, while the distribution name, argparseprog, help text,explaincatalog and tests all say
refactoring-cli. The rubric gate never caught thisbecause
tekendiscovers the script name frompyproject.toml.Commands are corrected to
refactor, and the divergence is now documented inboth files with a
git grepdiscovery command and the full rename target list(including
sonar.projectKey, which must keep matching the registeredSonarCloud project).
Deliberately not in this PR
The inherited "clonable template" prose inside
learn.py,overview.py, andexplain/catalog.pyis code, and rewriting it belongs with the rename decisionrather than a docs pass. It's flagged in
CLAUDE.mdinstead.Verification
All CI checks run locally and pass:
pytest -n auto(22 passed),black --check,isort --check-only,flake8,bandit,markdownlint-cli2(8files, 0 errors),
teken cli doctor . --strict, anddevex pr lint(noviolations). The corrected Quickstart commands were run and produce output.
Version bumped
0.6.1→0.6.2with a CHANGELOG entry.