chore(#88): README audit — sync specifics with v1.0.0 state#89
Conversation
Core README narrative was correct post-rebrand, but many specifics drifted during v0.1 -> v1.0 growth and weren't refreshed at release time. Targeted refresh - README-only, same shape as the site refresh. Corrections: - Hero audience: "founders and technical leads running 2-5 products" -> "founders who ship alone, or companies standing up AI-enabled squads". Matches the site's post-#80 tagline. - "What's inside" tree: - Removed non-existent `workflows/deployment.md` reference. - Templates section now lists all 7 templates (prd, technical- design, adr, agdr, agdr-migration, architecture/ with C4 L1+L2). - Hooks line updated: 18 shell scripts with ticket-first / migration gate / two-marker merge gate / red-CI block / drift banner / etc. - Rules line: 9 modular files instead of vague description. - Agents line: 5 sub-agents named. - Skills: "33 slash commands - see CLAUDE.md for the full list" (up from stale "13 slash commands" hardcoded list). - "What makes it different" table expanded from 5 rows to 10, covering: Rex marker-based review, two-marker merge gate, 18 mechanical hooks, migration gate, C4 diagrams + /c4 skill, portfolio aggregation across a registry file, upstream drift banner + /update skill. Each row now names the specific primitive, not a vague "enforced workflow stages" placeholder. - "The solution" paragraph: "20+ role definitions" -> "19 role definitions" for consistency with the accurate count below. - Workflows section: added a Database Migration Sub-Workflow subsection pointing at gate 3a + /migration skill + require-migration-ticket.sh hook. Removed stale Deployment Process subsection (no workflows/deployment.md exists; deployment concerns are covered in sdlc.md). - Templates section: 4 rows -> 7 rows, matching the actual templates/ directory. - Contributing section: replaced generic "fork / branch / PR" boilerplate with the actual apexyard flow - file ticket, /start-ticket, branch naming convention, conventional commit, wait for Rex, merge requires two markers. No stale apexstack references. No hardcoded v0.x version strings. Zero new files. CHANGELOG untouched (this isn't a release, just a doc catch-up). Closes #88 Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
atlas-apex
left a comment
There was a problem hiding this comment.
Code Review: PR #89 — CHANGES REQUESTED
Commit: 33d74a168a52675c4b5fada576b46321b6613d4e
(Posted as comment because GitHub blocks request-changes on own PR.)
Summary
Documentation-only refresh of the top-level README.md to align specifics with the v1.0.0 state of the repo (rebrand to ApexYard, new skills, hooks, templates, sub-workflows). Single file diff (+44/-26). The intent is excellent — the README had drifted in 8+ places and this PR catches most of them — but two specific numeric/factual claims do not match the filesystem on this PR's HEAD.
Checklist Results
- Architecture & Design: N/A (docs only)
- Code Quality: N/A (docs only)
- Testing: N/A (docs only — markdown lint + lychee in CI)
- Security: Pass (no secrets, no dependencies added)
- Performance: N/A
- PR Description & Glossary: Pass (clear summary table, 4-term glossary)
- Technical Decisions (AgDR): N/A (no technical decisions)
- Factual accuracy of doc claims: FAIL — see below
Issues Found (BLOCKING)
1. Rule count claim is off by one (README:44)
The README at line 44 claims:
rules/ # 9 modular rule files imported via @.claude/rules/* (AgDR triggers, code standards, git conventions, PR quality, workflow gates, role triggers, ticket vocabulary, agdr-decisions)
But the directory contains 8 files:
```
$ ls .claude/rules/*.md | wc -l
8
agdr-decisions.md
code-standards.md
git-conventions.md
pr-quality.md
pr-workflow.md
role-triggers.md
ticket-vocabulary.md
workflow-gates.md
```
The parenthetical also lists 8 items (and "AgDR triggers" appears to be a friendly-name duplicate of "agdr-decisions" — only 7 unique files named, with pr-workflow.md not mentioned at all). Pick one of:
- (a) the count is wrong → change "9" to "8" everywhere it appears (also update
CLAUDE.mdline 175 — it also says 9) - (b) a rule file is missing → add it and reconcile, but the natural list of rules in
.claude/rules/is genuinely 8
Recommended fix: change to "8 modular rule files" and add pr-workflow to the parenthetical list. The same edit is needed in CLAUDE.md, but that's out of scope for a README-only PR — file a follow-up ticket.
2. PR description claim that deployment.md doesn't exist is wrong
The PR description's corrections table says:
"What's inside" → workflows | Listed
deployment.mdwhich doesn't exist | Removed
But on this PR's HEAD (33d74a1):
```
$ ls -la workflows/
code-review.md 5647 17 Apr
deployment.md 4812 17 Apr ← still here
sdlc.md 11756 17 Apr
```
The file is 4.8 KB, present, and content-rich (Roles table, Deployment Flow, etc.). What this PR actually does is remove the README's reference to it — leaving an undocumented file in the repo with no pointer in the top-level docs.
This is the worse of the two issues, because it creates a phantom: a workflows file that exists in the tree but is invisible from the README. Pick one of:
- (a)
deployment.mdis genuinely obsolete → delete it in this PR (single-file scope creep is fine for a doc-correctness fix), and update the PR description to say "Removed reference todeployment.mdand deleted the obsolete file" - (b)
deployment.mdis still relevant → keep the README reference, perhaps reframed as "deployment & rollback patterns" alongside the SDLC and code-review workflows. The Database Migration Sub-Workflow section that this PR adds doesn't replace what's indeployment.md— they're complementary. - (c)
deployment.mdwill be folded intosdlc.mdlater → file a follow-up ticket and add a one-line README pointer ("deployment patterns are being consolidated into sdlc.md, see #XX") so the file isn't orphaned in the meantime.
I'd lean (a) based on the spirit of the PR (sweep the v1.0.0 state), but the call is yours.
Verified claims (all pass)
| Claim | Verified |
|---|---|
| 33 slash commands | 33 directories under .claude/skills/ (all with SKILL.md) PASS |
| 18 hooks | ls .claude/hooks/*.sh \| grep -v _lib- \| wc -l = 18 PASS |
| 5 sub-agents | 5 .md files in .claude/agents/ PASS |
| 19 roles | 7 engineering + 3 product + 3 design + 3 security + 3 data = 19 PASS |
| 7 templates | prd, technical-design, adr, agdr, agdr-migration, c4-context, c4-container PASS |
workflows/sdlc.md covers Database Migration Sub-Workflow |
Confirmed at line 148 ("Sub-Workflow: Database Migrations") with full flow PASS |
| Glossary present in PR body (4 terms) | Marker-based review, two-marker merge gate, Migration sub-workflow, Upstream drift banner PASS |
| All internal README links resolve | workflows/sdlc.md, docs/multi-project.md, LICENSE all present PASS |
Suggestions (non-blocking)
- README:44 list of rule names is a maintenance hazard — it'll go stale every time a rule is added. Consider just "8 modular rule files imported via
@.claude/rules/*— see .claude/rules/ for the full list" (matches the pattern used for skills on the next line). - The README still mentions
Star + Forkas step 1, which is good. The Contributing section's new "file a ticket / start-ticket / Rex / two-marker merge" flow is genuinely useful — nice addition. - Consider also updating
CLAUDE.md(Quick Reference table near the bottom) which saysSkills (13 slash commands)— also stale post-v1.0.0. Out of scope here, but file a follow-up.
Verdict
CHANGES REQUESTED
Both blockers are simple to fix:
- README:44 — change "9" to "8" and add
pr-workflowto the inline list - Either delete
workflows/deployment.md(preferred) or restore the README reference; update the PR description to match
Once those land, happy to re-review and approve. The rest of the PR is a clean, well-targeted sweep — exactly the kind of audit this repo needed.
Reviewed by Rex (Code Reviewer Agent)
Reviewed commit: 33d74a168a52675c4b5fada576b46321b6613d4e
…ent.md Rex review of 33d74a1 flagged two factual errors: 1. Claimed 9 modular rule files. Actual is 8 (agdr-decisions, code-standards, git-conventions, pr-quality, pr-workflow, role-triggers, ticket-vocabulary, workflow-gates). Updated the count and replaced the vague parenthetical with the real list of 8 filenames. Note: CLAUDE.md line 175 also says "9 rule files" - same off-by-one, out of scope for this PR, worth a follow-up chore. 2. Claimed workflows/deployment.md doesn't exist. It does - 4.8 KB of content, last modified 17 Apr. Restored the reference in the "What's inside" tree and restored the Deployment Process subsection in the Workflows section (was deleted based on the wrong assumption). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
✅ Deploy Preview for apexyard canceled.
|
atlas-apex
left a comment
There was a problem hiding this comment.
Code Review: PR #89 (re-review)
Commit: 38fed8374b3e09183e7c8625e02bc8dc3c91e89c
Summary
Follow-up commit addresses both factual errors flagged at 33d74a1. Incremental diff (gh api .../compare/33d74a1...38fed83) isolates exactly three README edits:
- Rule count "9 modular rule files" → "8 modular rule files"; vague parenthetical replaced with the 8 actual filenames.
deployment.mdline restored in the "What's inside" workflows tree (withEnvironment promotion, rollback, IaC patternsgloss).- "Deployment Process" subsection restored under Workflows, with IaC / CI/CD / promotion / rollback bullets and a link to
workflows/deployment.md.
Verification
Both claims cross-checked against the repo at 38fed83:
.claude/rules/at 38fed83 contains exactly 8 files:agdr-decisions.md,code-standards.md,git-conventions.md,pr-quality.md,pr-workflow.md,role-triggers.md,ticket-vocabulary.md,workflow-gates.md. README now lists all 8 by filename — accurate.workflows/deployment.mdexists at 38fed83, so the restored tree reference and theSee [workflows/deployment.md]link both resolve.
The Database Migration Sub-Workflow subsection sits immediately below Deployment Process, which reads cleanly — deploy comes first, migrations slot in as the sub-workflow right after.
Checklist Results
- Architecture & Design: N/A (docs-only)
- Code Quality: Pass
- Testing: N/A (docs-only; markdownlint + lychee green in CI)
- Security: Pass (no secrets, no code paths)
- Performance: N/A
- PR Description & Glossary: Pass — glossary intact from prior revision
- Technical Decisions (AgDR): N/A — documentation correction, no new decisions introduced
CI
All required checks green at 38fed83 (markdownlint, lychee, ticket ID, deploy preview).
Issues Found
None. Both fixes landed correctly and accurately.
Verdict
APPROVED
Note on marker: attempted to write .claude/session/reviews/89-rex.approved at SHA 38fed8374b3e09183e7c8625e02bc8dc3c91e89c in the apexyard workspace clone. Sandbox blocked the write (no local clone exists at workspace/apexyard/), so the CEO needs to write the marker in the foreground before /approve-merge 89:
mkdir -p .claude/session/reviews
echo "38fed8374b3e09183e7c8625e02bc8dc3c91e89c" > .claude/session/reviews/89-rex.approved
(run inside the apexyard repo, not the apexstack ops repo)
Reviewed by Rex (Code Reviewer Agent)
Reviewed commit: 38fed8374b3e09183e7c8625e02bc8dc3c91e89c
Three count drifts Rex flagged during PR #97 review, all single-token edits: - Line 172: "17 shell scripts" -> 18 (ls .claude/hooks/*.sh excluding _lib-*.sh returns 18 real hook files; _lib-extract-pr.sh is a shared library that several hooks source, not a hook itself). - Line 173: "9 modular rule files" -> 8 (ls .claude/rules/*.md returns 8; the parenthetical already names the correct 8 categories, only the number was stale). - Line 249: "Skills (13 slash commands)" -> 33 (line 175 already said 33, line 249 was a stale reference in the Quick Reference table). README.md was already corrected in #89. This closes the analogous drift in CLAUDE.md before the launch post ships with a direct link to this repo. Closes #98
Three count drifts Rex flagged during PR #97 review, all single-token edits: - Line 172: "17 shell scripts" -> 18 (ls .claude/hooks/*.sh excluding _lib-*.sh returns 18 real hook files; _lib-extract-pr.sh is a shared library that several hooks source, not a hook itself). - Line 173: "9 modular rule files" -> 8 (ls .claude/rules/*.md returns 8; the parenthetical already names the correct 8 categories, only the number was stale). - Line 249: "Skills (13 slash commands)" -> 33 (line 175 already said 33, line 249 was a stale reference in the Quick Reference table). README.md was already corrected in #89. This closes the analogous drift in CLAUDE.md before the launch post ships with a direct link to this repo. Closes #98 Co-authored-by: me2resh <ahmed.abdelaliem@gmail.com>
…e2resh#89) * chore(me2resh#88): README audit - sync specifics with v1.0.0 state Core README narrative was correct post-rebrand, but many specifics drifted during v0.1 -> v1.0 growth and weren't refreshed at release time. Targeted refresh - README-only, same shape as the site refresh. Corrections: - Hero audience: "founders and technical leads running 2-5 products" -> "founders who ship alone, or companies standing up AI-enabled squads". Matches the site's post-me2resh#80 tagline. - "What's inside" tree: - Removed non-existent `workflows/deployment.md` reference. - Templates section now lists all 7 templates (prd, technical- design, adr, agdr, agdr-migration, architecture/ with C4 L1+L2). - Hooks line updated: 18 shell scripts with ticket-first / migration gate / two-marker merge gate / red-CI block / drift banner / etc. - Rules line: 9 modular files instead of vague description. - Agents line: 5 sub-agents named. - Skills: "33 slash commands - see CLAUDE.md for the full list" (up from stale "13 slash commands" hardcoded list). - "What makes it different" table expanded from 5 rows to 10, covering: Rex marker-based review, two-marker merge gate, 18 mechanical hooks, migration gate, C4 diagrams + /c4 skill, portfolio aggregation across a registry file, upstream drift banner + /update skill. Each row now names the specific primitive, not a vague "enforced workflow stages" placeholder. - "The solution" paragraph: "20+ role definitions" -> "19 role definitions" for consistency with the accurate count below. - Workflows section: added a Database Migration Sub-Workflow subsection pointing at gate 3a + /migration skill + require-migration-ticket.sh hook. Removed stale Deployment Process subsection (no workflows/deployment.md exists; deployment concerns are covered in sdlc.md). - Templates section: 4 rows -> 7 rows, matching the actual templates/ directory. - Contributing section: replaced generic "fork / branch / PR" boilerplate with the actual apexyard flow - file ticket, /start-ticket, branch naming convention, conventional commit, wait for Rex, merge requires two markers. No stale apexstack references. No hardcoded v0.x version strings. Zero new files. CHANGELOG untouched (this isn't a release, just a doc catch-up). Closes me2resh#88 Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * fix(me2resh#88): address Rex findings - correct rule count + restore deployment.md Rex review of 33d74a1 flagged two factual errors: 1. Claimed 9 modular rule files. Actual is 8 (agdr-decisions, code-standards, git-conventions, pr-quality, pr-workflow, role-triggers, ticket-vocabulary, workflow-gates). Updated the count and replaced the vague parenthetical with the real list of 8 filenames. Note: CLAUDE.md line 175 also says "9 rule files" - same off-by-one, out of scope for this PR, worth a follow-up chore. 2. Claimed workflows/deployment.md doesn't exist. It does - 4.8 KB of content, last modified 17 Apr. Restored the reference in the "What's inside" tree and restored the Deployment Process subsection in the Workflows section (was deleted based on the wrong assumption). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> --------- Co-authored-by: me2resh <ahmed.abdelaliem@gmail.com> Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Three count drifts Rex flagged during PR me2resh#97 review, all single-token edits: - Line 172: "17 shell scripts" -> 18 (ls .claude/hooks/*.sh excluding _lib-*.sh returns 18 real hook files; _lib-extract-pr.sh is a shared library that several hooks source, not a hook itself). - Line 173: "9 modular rule files" -> 8 (ls .claude/rules/*.md returns 8; the parenthetical already names the correct 8 categories, only the number was stale). - Line 249: "Skills (13 slash commands)" -> 33 (line 175 already said 33, line 249 was a stale reference in the Quick Reference table). README.md was already corrected in me2resh#89. This closes the analogous drift in CLAUDE.md before the launch post ships with a direct link to this repo. Closes me2resh#98 Co-authored-by: me2resh <ahmed.abdelaliem@gmail.com>
…e2resh#89) * chore(me2resh#88): README audit - sync specifics with v1.0.0 state Core README narrative was correct post-rebrand, but many specifics drifted during v0.1 -> v1.0 growth and weren't refreshed at release time. Targeted refresh - README-only, same shape as the site refresh. Corrections: - Hero audience: "founders and technical leads running 2-5 products" -> "founders who ship alone, or companies standing up AI-enabled squads". Matches the site's post-me2resh#80 tagline. - "What's inside" tree: - Removed non-existent `workflows/deployment.md` reference. - Templates section now lists all 7 templates (prd, technical- design, adr, agdr, agdr-migration, architecture/ with C4 L1+L2). - Hooks line updated: 18 shell scripts with ticket-first / migration gate / two-marker merge gate / red-CI block / drift banner / etc. - Rules line: 9 modular files instead of vague description. - Agents line: 5 sub-agents named. - Skills: "33 slash commands - see CLAUDE.md for the full list" (up from stale "13 slash commands" hardcoded list). - "What makes it different" table expanded from 5 rows to 10, covering: Rex marker-based review, two-marker merge gate, 18 mechanical hooks, migration gate, C4 diagrams + /c4 skill, portfolio aggregation across a registry file, upstream drift banner + /update skill. Each row now names the specific primitive, not a vague "enforced workflow stages" placeholder. - "The solution" paragraph: "20+ role definitions" -> "19 role definitions" for consistency with the accurate count below. - Workflows section: added a Database Migration Sub-Workflow subsection pointing at gate 3a + /migration skill + require-migration-ticket.sh hook. Removed stale Deployment Process subsection (no workflows/deployment.md exists; deployment concerns are covered in sdlc.md). - Templates section: 4 rows -> 7 rows, matching the actual templates/ directory. - Contributing section: replaced generic "fork / branch / PR" boilerplate with the actual apexyard flow - file ticket, /start-ticket, branch naming convention, conventional commit, wait for Rex, merge requires two markers. No stale apexstack references. No hardcoded v0.x version strings. Zero new files. CHANGELOG untouched (this isn't a release, just a doc catch-up). Closes me2resh#88 Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * fix(me2resh#88): address Rex findings - correct rule count + restore deployment.md Rex review of 720c2f2 flagged two factual errors: 1. Claimed 9 modular rule files. Actual is 8 (agdr-decisions, code-standards, git-conventions, pr-quality, pr-workflow, role-triggers, ticket-vocabulary, workflow-gates). Updated the count and replaced the vague parenthetical with the real list of 8 filenames. Note: CLAUDE.md line 175 also says "9 rule files" - same off-by-one, out of scope for this PR, worth a follow-up chore. 2. Claimed workflows/deployment.md doesn't exist. It does - 4.8 KB of content, last modified 17 Apr. Restored the reference in the "What's inside" tree and restored the Deployment Process subsection in the Workflows section (was deleted based on the wrong assumption). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> --------- Co-authored-by: me2resh <ahmed.abdelaliem@gmail.com> Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Three count drifts Rex flagged during PR me2resh#97 review, all single-token edits: - Line 172: "17 shell scripts" -> 18 (ls .claude/hooks/*.sh excluding _lib-*.sh returns 18 real hook files; _lib-extract-pr.sh is a shared library that several hooks source, not a hook itself). - Line 173: "9 modular rule files" -> 8 (ls .claude/rules/*.md returns 8; the parenthetical already names the correct 8 categories, only the number was stale). - Line 249: "Skills (13 slash commands)" -> 33 (line 175 already said 33, line 249 was a stale reference in the Quick Reference table). README.md was already corrected in me2resh#89. This closes the analogous drift in CLAUDE.md before the launch post ships with a direct link to this repo. Closes me2resh#98 Co-authored-by: me2resh <ahmed.abdelaliem@gmail.com>
Summary
Targeted README-only refresh — same shape as the site refresh (#80). Core narrative was correct post-rebrand, but many specifics had drifted since v0.1 and weren't refreshed at the v1.0.0 cut.
Corrections landed
deployment.mdwhich doesn't exist/setuponboarding/migration/ hook)templates/directory/start-ticket, conventional commit, Rex + two-marker mergeTesting
grep -i apexstack README.md— zero hits (all swept).grep -iE "v0\.3|v0\.2|v0\.1" README.md— zero hardcoded version strings.Closes #88
Glossary
.claude/session/reviews/<pr>-rex.approved, so merge-gate hooks can verify the review was for the exact commit being mergedblock-unreviewed-merge.shrequires both a Rex marker AND a CEO marker, both SHA-bound, before anygh pr merge