docs(phase-0): repository restructuring specification and preflight checklist - #1437
docs(phase-0): repository restructuring specification and preflight checklist#1437ashleyshaw wants to merge 1 commit into
Conversation
…light checklist Add two Phase 0 planning documents for the repository restructuring initiative: - SPECIFICATION.md: Comprehensive implementation plan covering folder mapping, file reference updates, implementation sequencing, dependency graph, success criteria, risk mitigation, and rollback procedures - PREFLIGHT_CHECKLIST.md: Ready-to-use checklist with 5 sections for confirming 50-question decisions, ensuring clean repository state, running tests, reviewing documentation, and final sign-off before Phase 1 begins These documents provide the detailed planning required to execute the repository restructuring safely and systematically (schema consolidation, root cleanup, scripts/website moves, agent/skill separation). Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>
|
🚫 This PR description is missing required template content. Missing required section(s): Linked issues Please update the PR body using one of the repository PR templates:
Empty placeholders, unchecked checklist boxes, and stub issue references do not count. |
github-actions
Bot
added
status:needs-review
📝 WalkthroughSummary by CodeRabbit
WalkthroughAdded a Phase 0 restructuring specification and pre-flight checklist. The documents define the target structure, migration sequence, validation steps, rollback procedures, timeline, troubleshooting commands, references, and sign-off process. ChangesRepository restructuring preparation
Estimated code review effort: 2 (Simple) | ~10 minutes Possibly related PRs
Suggested reviewers: 🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches 💡 1🛠️ Fix failing CI checks 💡
🧪 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 |
github-actions
Bot
added
priority:normal
⏱️ Aging and SLA annotation
Maintained by project-meta-sync workflow. |
github-actions
Bot
added
the
meta:needs-changelog
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 12
🤖 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 `@projects/active/repo-restructuring-2026-07-25/PREFLIGHT_CHECKLIST.md`:
- Around line 133-160: Update the “Create Backup Branch & Tag” commands to push
the branch and tag using fully qualified refs, such as refs/heads and refs/tags,
avoiding ambiguity from their shared short name. Update “Verify backup exists”
to use git ls-remote and explicitly verify both the remote branch and tag
references.
- Around line 259-280: Reset the pre-checked review and approval boxes in
PREFLIGHT_CHECKLIST.md, including the documentation review, specification
approval, and the referenced sign-off sections. Leave dependent checklist items
unchecked until the corresponding evidence, completed Parts A–E, and explicit
user approval are recorded; preserve only boxes supported by existing evidence.
- Around line 20-27: Update the referenced paths in PREFLIGHT_CHECKLIST.md to be
repository-portable: replace the workstation-specific 50-questions document path
and incorrect ../../ links with repository-relative paths to the canonical
files, including the downloads reference, or stable external URLs. Apply the
same corrections to the corresponding references in the additional section
around the later checklist items.
- Around line 122-131: Update the “Branch is up-to-date with remote” checklist
step to require a configured upstream reference and explicitly verify zero
commits ahead and behind using a numeric comparison. Replace the current git
status-only validation with commands that fail or block when no upstream exists
or either count is nonzero, while preserving the existing pull guidance for
branches that are behind.
- Around line 248-253: Update the “Overall Status” checklist command to replace
the invalid npm wildcard `npm run lint:*` with the existing `npm run lint:all`
script, while preserving the surrounding CI verification guidance.
In `@projects/active/repo-restructuring-2026-07-25/SPECIFICATION.md`:
- Around line 520-542: Update the “Rollback Plan” to use phase-specific
recovery: restore from the backup reference before commits, and revert committed
changes after the archive commit instead of relying on git reset --hard HEAD.
Replace the broad git clean -fd command with a dry-run followed by removal of
only explicitly created migration paths, preserving unrelated untracked files.
- Around line 151-196: The restructuring plan must audit every consumer of
scripts before moving the directory, not only schema-validation references.
Review package.json commands such as cleanup-branches.js, sync-version.js, and
frontmatter-metrics.js, classify each script as portable or GitHub-specific, and
update all affected npm scripts and workflow references before Phase 1 so
existing commands remain functional.
- Around line 76-85: Clarify the configuration migration rules in Section 1.2
and the related Section 1.3 content by defining the destination for every
configuration file: move only GitHub-specific files to .github/config/ and
retain portable configuration at the repository root. Ensure the guidance
resolves overlaps with the existing .github/config/ consolidation instruction.
- Around line 391-405: Update the Phase 5 documentation plan to create the
migration guide at docs/MIGRATION.md instead of .github/docs/MIGRATION.md, and
revise every related link or reference, including the CLAUDE.md update and
success criteria, to use the new location.
- Around line 14-19: Resolve the schema-location policy conflict before Phase 1:
either explicitly update the repository rule to make root schemas/
authoritative, or preserve the existing root .schemas/ policy. If preserving it,
revise the target layout, migration steps, references in PREFLIGHT_CHECKLIST.md,
documentation links, and success criteria so portable JSON schemas remain in
.schemas/.
- Around line 65-72: Update the Migration Steps in SPECIFICATION.md to require
collision-safe transfers: include dotfiles, compare source and destination files
by relative path and hash, and fail rather than overwrite when same-path
contents differ. Require verification of complete file coverage and identical
duplicate content before archiving .schemas/ and schema/; do not rely on file
counts or proceed with archival after conflicts.
- Around line 409-459: Standardize the phase numbering across SPECIFICATION.md
and PREFLIGHT_CHECKLIST.md: reconcile Section 3 with the dependency graph so
archive and cleanup use the same phase as the graph’s “Final cleanup,” while PR
creation and merge retain their corresponding phase. Update every phase
reference consistently before execution.
🪄 Autofix (Beta)
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: Repository YAML (base), Organization UI (inherited)
Review profile: CHILL
Plan: Pro Plus
Run ID: f4fdd9f8-f3a6-4b2d-9107-f9e42df3dd4c
📒 Files selected for processing (2)
projects/active/repo-restructuring-2026-07-25/PREFLIGHT_CHECKLIST.mdprojects/active/repo-restructuring-2026-07-25/SPECIFICATION.md
📜 Review details
⏰ Context from checks skipped due to timeout. (4)
- GitHub Check: coderabbit-gate
- GitHub Check: Analyze (python)
- GitHub Check: Mergify Merge Protections
- GitHub Check: Summary
⚠️ CI failures not shown inline (2)
GitHub Actions: Validate PR Template / validate-pr-template: docs(phase-0): repository restructuring specification and preflight checklist
Conclusion: failure
##[group]Run actions/github-script@v7
with:
script: const { validatePullRequestBody } = require('./scripts/validation/template-helpers.cjs');
const marker = '<!-- template-enforcement -->';
const pr = context.payload.pull_request;
const author = pr.user?.login || '';
const isDependabot = author === 'dependabot[bot]' || author === 'app/dependabot';
const isImgbot = author === 'imgbot[bot]' || author === 'app/imgbot';
if (isDependabot || isImgbot) {
core.info(`Skipping PR template validation for bot author ${author}.`);
return;
}
const validation = validatePullRequestBody(pr.body || '', pr.labels || [], pr.head?.ref || '');
const comments = await github.paginate(github.rest.issues.listComments, {
owner: context.repo.owner,
repo: context.repo.repo,
issue_number: pr.number,
per_page: 100
});
const previous = comments.find((comment) =>
comment.user?.type === 'Bot' && comment.body?.includes(marker)
);
if (validation.missing.length === 0) {
if (previous) {
await github.rest.issues.updateComment({
owner: context.repo.owner,
repo: context.repo.repo,
comment_id: previous.id,
body: `${marker}\n✅ Template check passed after update. Thanks for fixing the PR description.`
});
}
return;
}
const message = [
marker,
'🚫 This PR description is missing required template content.',
'',
`Missing required section(s): ${validation.missing.join(', ')}`,
'',
'Please update the PR body using one of the repository PR templates:',
'- https://github.com/lightspeedwp/.github/blob/develop/.github/pull_request_template.md',
'- https://github.com/lightspeedwp/.github/tree/develop/.github/PULL_REQUEST_TEMPLATE',
'',
'Empty placeholders, unchecked checklist boxes, and stub issue references do not count.'
].join('\n');
if (previous) {
await github.rest.issues.updateComment({
owner: context.repo.owner,
repo: context.repo.repo,
comment_id: previous.id,
body: message
});
} else {
await github.rest.issues....
GitHub Actions: Validate PR Template / 0_validate-pr-template.txt: docs(phase-0): repository restructuring specification and preflight checklist
Conclusion: failure
##[group]Run actions/github-script@v7
with:
script: const { validatePullRequestBody } = require('./scripts/validation/template-helpers.cjs');
const marker = '<!-- template-enforcement -->';
const pr = context.payload.pull_request;
const author = pr.user?.login || '';
const isDependabot = author === 'dependabot[bot]' || author === 'app/dependabot';
const isImgbot = author === 'imgbot[bot]' || author === 'app/imgbot';
if (isDependabot || isImgbot) {
core.info(`Skipping PR template validation for bot author ${author}.`);
return;
}
const validation = validatePullRequestBody(pr.body || '', pr.labels || [], pr.head?.ref || '');
const comments = await github.paginate(github.rest.issues.listComments, {
owner: context.repo.owner,
repo: context.repo.repo,
issue_number: pr.number,
per_page: 100
});
const previous = comments.find((comment) =>
comment.user?.type === 'Bot' && comment.body?.includes(marker)
);
if (validation.missing.length === 0) {
if (previous) {
await github.rest.issues.updateComment({
owner: context.repo.owner,
repo: context.repo.repo,
comment_id: previous.id,
body: `${marker}\n✅ Template check passed after update. Thanks for fixing the PR description.`
});
}
return;
}
const message = [
marker,
'🚫 This PR description is missing required template content.',
'',
`Missing required section(s): ${validation.missing.join(', ')}`,
'',
'Please update the PR body using one of the repository PR templates:',
'- https://github.com/lightspeedwp/.github/blob/develop/.github/pull_request_template.md',
'- https://github.com/lightspeedwp/.github/tree/develop/.github/PULL_REQUEST_TEMPLATE',
'',
'Empty placeholders, unchecked checklist boxes, and stub issue references do not count.'
].join('\n');
if (previous) {
await github.rest.issues.updateComment({
owner: context.repo.owner,
repo: context.repo.repo,
comment_id: previous.id,
body: message
});
} else {
await github.rest.issues....
🧰 Additional context used
📓 Path-based instructions (3)
**/*
📄 CodeRabbit inference engine (CLAUDE.md)
**/*: Do not place reusable AI assets under.github/; store them in the appropriate top-level portable asset folder.
Portable JSON schemas belong in the root.schemas/directory; portable agents belong inagents/; permanent human documentation belongs indocs/; temporary scratch files belong in.github/tmp/and must be cleaned up.
Do not commitnode_modules/,build/, or other generated artefacts.
**/*: Use UK English and optimise solutions for clarity, scalability, maintainability, and profitable outcomes.
Prefer minimal, modular solutions; justify heavier tools based on return on investment and maintenance cost.
Files:
projects/active/repo-restructuring-2026-07-25/SPECIFICATION.mdprojects/active/repo-restructuring-2026-07-25/PREFLIGHT_CHECKLIST.md
**/*.md
📄 CodeRabbit inference engine (CLAUDE.md)
Use UK English throughout documentation and Markdown content, including spellings such as
optimise,organisation,colour, andbehaviour.
**/*.md: Documentation and AI infrastructure files must follow their applicable documented standards, including required structure, frontmatter, quality gates, and validation.
Run Markdown linting withnpm run lint:mdand validate frontmatter withnpm run validate:frontmatterwhere applicable.
Files:
projects/active/repo-restructuring-2026-07-25/SPECIFICATION.mdprojects/active/repo-restructuring-2026-07-25/PREFLIGHT_CHECKLIST.md
**/*.{md,yml,yaml,json}
📄 CodeRabbit inference engine (CLAUDE.md)
Do not use a
referencesfrontmatter field; use inline links or footer sections instead.
Files:
projects/active/repo-restructuring-2026-07-25/SPECIFICATION.mdprojects/active/repo-restructuring-2026-07-25/PREFLIGHT_CHECKLIST.md
🪛 LanguageTool
projects/active/repo-restructuring-2026-07-25/SPECIFICATION.md
[style] ~12-~12: Would you like to use the Oxford spelling “reorganization”? The spelling ‘reorganisation’ is also correct.
Context: ... This specification defines the folder reorganisation, file migrations, and reference updates...
(OXFORD_SPELLING_Z_NOT_S)
[uncategorized] ~17-~17: The official name of this software platform is spelled with a capital “H”.
Context: ...sets (agents, skills, hooks, etc.) from .github-specific tools - Reorganise root folde...
(GITHUB)
[style] ~18-~18: Would you like to use the Oxford spelling “Reorganize”? The spelling ‘Reorganise’ is also correct.
Context: ..., etc.) from .github-specific tools - Reorganise root folder to reduce clutter and impro...
(OXFORD_SPELLING_Z_NOT_S)
[uncategorized] ~70-~70: The official name of this software platform is spelled with a capital “H”.
Context: ...4. Archive old locations: .schemas/ → .github/tmp/schema-archive/ (backup, don't del...
(GITHUB)
[uncategorized] ~71-~71: The official name of this software platform is spelled with a capital “H”.
Context: ...t) 5. Archive old location: schema/ → .github/tmp/schema-archive/ (backup, don't del...
(GITHUB)
[uncategorized] ~78-~78: The official name of this software platform is spelled with a capital “H”.
Context: ...hub/ **Move these folders from root →.github/`:** | Current Location | New Location...
(GITHUB)
[uncategorized] ~82-~82: The official name of this software platform is spelled with a capital “H”.
Context: ...on | | --- | --- | --- | | scripts/ | .github/scripts/ | .github-specific validati...
(GITHUB)
[uncategorized] ~82-~82: The official name of this software platform is spelled with a capital “H”.
Context: ...- | | scripts/ | .github/scripts/ | .github-specific validation & automation | | `...
(GITHUB)
[uncategorized] ~83-~83: The official name of this software platform is spelled with a capital “H”.
Context: ...alidation & automation | | website/ | .github/website/ | .github documentation sit...
(GITHUB)
[uncategorized] ~83-~83: The official name of this software platform is spelled with a capital “H”.
Context: ...n | | website/ | .github/website/ | .github documentation site (github.lightspeedw...
(GITHUB)
[uncategorized] ~83-~83: The official name of this software platform is spelled with a capital “H”.
Context: ...bsite/|.githubdocumentation site (github.lightspeedwp.agency) | |config/` (Git...
(GITHUB)
[uncategorized] ~84-~84: The official name of this software platform is spelled with a capital “H”.
Context: ...ency) | | config/ (GitHub-specific) | .github/config/ | GitHub labels, workflows, is...
(GITHUB)
[uncategorized] ~85-~85: The official name of this software platform is spelled with a capital “H”.
Context: ...tHub labels, workflows, issue types | | .github/config/ → consolidate | `.github/confi...
(GITHUB)
[uncategorized] ~85-~85: The official name of this software platform is spelled with a capital “H”.
Context: ...s | | .github/config/ → consolidate | .github/config/ | Already in right place; cons...
(GITHUB)
[uncategorized] ~101-~101: The official name of this software platform is spelled with a capital “H”.
Context: ...as (consolidated, visible) | Keep in .github/ (repo-specific): | Folder | Reason...
(GITHUB)
[uncategorized] ~105-~105: The official name of this software platform is spelled with a capital “H”.
Context: ...** | Folder | Reason | | --- | --- | | .github/workflows/ | GitHub Actions (.github...
(GITHUB)
[uncategorized] ~105-~105: The official name of this software platform is spelled with a capital “H”.
Context: ... .github/workflows/ | GitHub Actions (.github-only) | | .github/ISSUE_TEMPLATE/ | ...
(GITHUB)
[uncategorized] ~106-~106: The official name of this software platform is spelled with a capital “H”.
Context: ... | GitHub Actions (.github-only) | | .github/ISSUE_TEMPLATE/` | GitHub issue templat...
(GITHUB)
[uncategorized] ~107-~107: The official name of this software platform is spelled with a capital “H”.
Context: ...TEMPLATE/| GitHub issue templates | |.github/PULL_REQUEST_TEMPLATE/` | GitHub PR tem...
(GITHUB)
[uncategorized] ~108-~108: The official name of this software platform is spelled with a capital “H”.
Context: ...ST_TEMPLATE/| GitHub PR templates | |.github/agents/|.github`-specific agents (r...
(GITHUB)
[uncategorized] ~108-~108: The official name of this software platform is spelled with a capital “H”.
Context: ...ub PR templates | | .github/agents/ | .github-specific agents (repo structure linter...
(GITHUB)
[uncategorized] ~109-~109: The official name of this software platform is spelled with a capital “H”.
Context: ...e linter, changelog recovery, etc.) | | .github/skills/ | .github-specific skills (c...
(GITHUB)
[uncategorized] ~109-~109: The official name of this software platform is spelled with a capital “H”.
Context: ...recovery, etc.) | | .github/skills/ | .github-specific skills (changelog entry, PR r...
(GITHUB)
[uncategorized] ~110-~110: The official name of this software platform is spelled with a capital “H”.
Context: ...og entry, PR review, release audit) | | .github/instructions/ | .github-specific ins...
(GITHUB)
[uncategorized] ~110-~110: The official name of this software platform is spelled with a capital “H”.
Context: ...se audit) | | .github/instructions/ | .github-specific instruction files | | `.githu...
(GITHUB)
[uncategorized] ~111-~111: The official name of this software platform is spelled with a capital “H”.
Context: ....github-specific instruction files | | .github/custom-instructions.md` | Copilot confi...
(GITHUB)
[uncategorized] ~112-~112: The official name of this software platform is spelled with a capital “H”.
Context: ...Copilot configuration for this repo | | .github/scripts/ | Validation scripts tightly ...
(GITHUB)
[uncategorized] ~113-~113: The official name of this software platform is spelled with a capital “H”.
Context: ... to repo structure (move from root) | | .github/config/ | GitHub labels, labeler rules...
(GITHUB)
[uncategorized] ~114-~114: The official name of this software platform is spelled with a capital “H”.
Context: ... labels, labeler rules, issue types | | .github/website/ | github.lightspeedwp.agency ...
(GITHUB)
[uncategorized] ~114-~114: The official name of this software platform is spelled with a capital “H”.
Context: ...s, issue types | | .github/website/ | github.lightspeedwp.agency documentation site ...
(GITHUB)
[uncategorized] ~115-~115: The official name of this software platform is spelled with a capital “H”.
Context: ...documentation site (move from root) | | .github/projects/ | Active/archived project do...
(GITHUB)
[uncategorized] ~116-~116: The official name of this software platform is spelled with a capital “H”.
Context: ...tive/archived project documentation | | .github/reports/ | Reports and audit artefacts...
(GITHUB)
[uncategorized] ~117-~117: The official name of this software platform is spelled with a capital “H”.
Context: ...rts/| Reports and audit artefacts | |.github/tmp/` | Temporary scratch files (cleanu...
(GITHUB)
[uncategorized] ~138-~138: The official name of this software platform is spelled with a capital “H”.
Context: ...projects) **GitHub-Native Config → `.github/config/`:** .github/config/ ├── ...
(GITHUB)
[uncategorized] ~153-~153: The official name of this software platform is spelled with a capital “H”.
Context: ...ire Updates ### 2.1 Script Updates (in .github/scripts/validation/) **Files to audit...
(GITHUB)
[uncategorized] ~159-~159: The official name of this software platform is spelled with a capital “H”.
Context: ...hemas/frontmatter.schema.json(move to.github/scripts/validation/`) - Search & rep...
(GITHUB)
[uncategorized] ~199-~199: The official name of this software platform is spelled with a capital “H”.
Context: ...as/ --- ### 2.3 GitHub Workflows (in.github/workflows/`) Files to audit: 1. *...
(GITHUB)
[uncategorized] ~240-~240: The official name of this software platform is spelled with a capital “H”.
Context: ...struction Files (in instructions/ and .github/instructions/) **Search for schema re...
(GITHUB)
[uncategorized] ~270-~270: The official name of this software platform is spelled with a capital “H”.
Context: ... ### 2.7 Configuration Files Update .github/ relative paths: - .eslintrc.json...
(GITHUB)
[uncategorized] ~307-~307: The official name of this software platform is spelled with a capital “H”.
Context: ...mas -type f | wc -l ``` 4. Create .github/scripts/ folder (if not present) ...
(GITHUB)
[uncategorized] ~313-~313: The official name of this software platform is spelled with a capital “H”.
Context: ...`` 5. Move scripts from scripts/ → `.github/scripts/` (don't delete yet) ```b...
(GITHUB)
[uncategorized] ~332-~332: The official name of this software platform is spelled with a capital “H”.
Context: ...as/ 2. **Update validation scripts** (.github/scripts/validation/*.js`) - Update a...
(GITHUB)
[uncategorized] ~336-~336: The official name of this software platform is spelled with a capital “H”.
Context: ...dually 3. Update GitHub workflows (.github/workflows/*.yml) - Test workflows i...
(GITHUB)
[uncategorized] ~364-~364: The official name of this software platform is spelled with a capital “H”.
Context: ...contains all expected files - Verify .github/scripts/ contains all scripts - Ver...
(GITHUB)
[uncategorized] ~388-~388: The official name of this software platform is spelled with a capital “H”.
Context: ...ges and no issues reported) - Remove .github/tmp/schema-archive/ and `.github/tmp/s...
(GITHUB)
[uncategorized] ~393-~393: The official name of this software platform is spelled with a capital “H”.
Context: ...Updates 1. Create migration guide (.github/docs/MIGRATION.md) - Document schem...
(GITHUB)
[style] ~399-~399: Would you like to use the Oxford spelling “organization”? The spelling ‘organisation’ is also correct.
Context: ...EADME.md— new file documenting schema organisation -agents/README.md` — update links ...
(OXFORD_SPELLING_Z_NOT_S)
[uncategorized] ~469-~469: The official name of this software platform is spelled with a capital “H”.
Context: ...xists at root with all schema files - ✅ .github/scripts/ folder exists with all script...
(GITHUB)
[uncategorized] ~470-~470: The official name of this software platform is spelled with a capital “H”.
Context: ...o data loss (old folders still exist in .github/tmp/) - ✅ Git status shows new files (...
(GITHUB)
[typographical] ~513-~513: Do not use a colon (:) before a series that is introduced by a preposition (‘after’). Remove the colon or add a noun or a noun phrase after the preposition.
Context: ...during copy | Verify file counts before/after: find schemas -type f \| wc -l | | Wor...
(RP_COLON)
[typographical] ~573-~573: It appears that a comma is missing.
Context: ...on any questions that need clarification 2. Should we keep the archived folders (`.githu...
(COMMA_BEFORE_QUESTION_WITH_MD)
[uncategorized] ~574-~574: The official name of this software platform is spelled with a capital “H”.
Context: ...Should we keep the archived folders* (.github/tmp/schema-archive/) in Git? - ...
(GITHUB)
projects/active/repo-restructuring-2026-07-25/PREFLIGHT_CHECKLIST.md
[uncategorized] ~344-~344: The official name of this software platform is spelled with a capital “H”.
Context: ...github/scripts/ - Copywebsite/→.github/website/` (if applicable) 2. **Phase 2...
(GITHUB)
🔇 Additional comments (1)
projects/active/repo-restructuring-2026-07-25/PREFLIGHT_CHECKLIST.md (1)
205-246: 🗄️ Data Integrity & IntegrationVerify every validation command against
package.json.The supplied
package.jsoncontext at Lines 116-126 shows aggregate commands such asvalidate:all,check, andlint:all, plus specific commands such aslint:json. It does not establish that every listed command, includingvalidate:agentsandlint:js, exists. Confirm the exact script keys before treating this checklist as executable.
| - [ ] **Read the 50 questions & answers document** | ||
| - File: `/Users/ash/Downloads/50-questions-and-answers.md` (or wherever stored) | ||
| - Sections: All 50 questions reviewed | ||
|
|
||
| - [ ] **Provide feedback on ALL 50 questions** | ||
| - Use the template in `PHASE_0_TASKS.md` Task 0.1 | ||
| - Mark each question: ✅ Agree / ❌ Disagree (with reason) / ❓ Unclear | ||
| - Add critical decisions (agent location, team size, plugin adoption) |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟠 Major | ⚡ Quick win
Use repository-portable references.
/Users/ash/Downloads/50-questions-and-answers.md only works on one workstation. The links ../../CLAUDE.md and ../../docs/BRANCHING_STRATEGY.md resolve under projects/, not the repository root. The ../../downloads/... link has the same path assumption. Use repository-relative paths to canonical files, or provide stable external links.
Also applies to: 420-426
🤖 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 `@projects/active/repo-restructuring-2026-07-25/PREFLIGHT_CHECKLIST.md` around
lines 20 - 27, Update the referenced paths in PREFLIGHT_CHECKLIST.md to be
repository-portable: replace the workstation-specific 50-questions document path
and incorrect ../../ links with repository-relative paths to the canonical
files, including the downloads reference, or stable external URLs. Apply the
same corrections to the corresponding references in the additional section
around the later checklist items.
| - [ ] **Branch is up-to-date with remote** | ||
|
|
||
| ```bash | ||
| git fetch origin | ||
| git status | ||
| # Expected: "Your branch is up to date with 'origin/...'" | ||
| ``` | ||
|
|
||
| - If behind: Run `git pull` | ||
| - **Timeline:** 2 minutes |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟠 Major | ⚡ Quick win
Make branch freshness a hard gate.
git status does not fail when the current branch has no upstream. It also does not provide a numeric ahead/behind check. Require an upstream reference and verify zero ahead and behind commits before proceeding.
🤖 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 `@projects/active/repo-restructuring-2026-07-25/PREFLIGHT_CHECKLIST.md` around
lines 122 - 131, Update the “Branch is up-to-date with remote” checklist step to
require a configured upstream reference and explicitly verify zero commits ahead
and behind using a numeric comparison. Replace the current git status-only
validation with commands that fail or block when no upstream exists or either
count is nonzero, while preserving the existing pull guidance for branches that
are behind.
| ### B.2 Create Backup Branch & Tag | ||
|
|
||
| - [ ] **Create backup branch** | ||
|
|
||
| ```bash | ||
| git checkout -b backup/pre-restructure-2026-07-31 | ||
| git push -u origin backup/pre-restructure-2026-07-31 | ||
| ``` | ||
|
|
||
| - **Timeline:** 2 minutes | ||
| - **Acceptance:** Branch exists on remote | ||
|
|
||
| - [ ] **Create backup tag** | ||
|
|
||
| ```bash | ||
| git tag -a backup/pre-restructure-2026-07-31 -m "Pre-restructure backup - 2026-07-31" | ||
| git push origin backup/pre-restructure-2026-07-31 | ||
| ``` | ||
|
|
||
| - **Timeline:** 2 minutes | ||
| - **Acceptance:** Tag visible in `git tag -l` | ||
|
|
||
| - [ ] **Verify backup exists** | ||
|
|
||
| ```bash | ||
| git branch -r | grep backup/pre-restructure | ||
| git tag | grep backup/pre-restructure | ||
| ``` |
There was a problem hiding this comment.
🗄️ Data Integrity & Integration | 🟠 Major | ⚡ Quick win
Push the backup tag by its full reference.
The backup branch and tag use the same short name. git push origin backup/pre-restructure-2026-07-31 is ambiguous and can push the branch ref again instead of the tag. Use fully qualified refs for both pushes, then verify them with git ls-remote.
🤖 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 `@projects/active/repo-restructuring-2026-07-25/PREFLIGHT_CHECKLIST.md` around
lines 133 - 160, Update the “Create Backup Branch & Tag” commands to push the
branch and tag using fully qualified refs, such as refs/heads and refs/tags,
avoiding ambiguity from their shared short name. Update “Verify backup exists”
to use git ls-remote and explicitly verify both the remote branch and tag
references.
| ### C.4 Overall Status | ||
|
|
||
| - [ ] **All CI checks would pass** | ||
| - Run any local CI equivalent (GitHub Actions available in repo?) | ||
| - Or manually verify: `npm test && npm run lint:*` | ||
| - **Acceptance:** No failures |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
set -euo pipefail
echo "== package scripts =="
if [ -f package.json ]; then
python3 - <<'PY'
import json
with open('package.json', encoding='utf-8') as f:
data=json.load(f)
for k,v in data.get('scripts',{}).items():
if k.startswith('lint:'):
print(f"{k}: {v}")
PY
else
echo "no package.json at repo root"
fi
echo
echo "== checklist lines =="
sed -n '240,260p' projects/active/repo-restructuring-2026-07-25/PREFLIGHT_CHECKLIST.md 2>/dev/null || true
echo
echo "== lint:* references =="
rg -n "lint:\*|lint:all|npm run lint" projects/active/repo-restructuring-2026-07-25/PREFLIGHT_CHECKLIST.md package.json 2>/dev/null || trueRepository: lightspeedwp/.github
Length of output: 3074
Replace the invalid npm run lint:* fallback.
npm run needs a real script name; npm run lint:* is not a reliable wildcard command. Call npm run lint:all or use the exact existing lint script names.
🤖 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 `@projects/active/repo-restructuring-2026-07-25/PREFLIGHT_CHECKLIST.md` around
lines 248 - 253, Update the “Overall Status” checklist command to replace the
invalid npm wildcard `npm run lint:*` with the existing `npm run lint:all`
script, while preserving the surrounding CI verification guidance.
| ### D.1 Documentation Exists | ||
|
|
||
| - [ ] **Review phase-0 planning documents** | ||
| - [x] `PHASE_0_TASKS.md` (original task list) | ||
| - [x] `50-questions-and-answers.md` (decisions) | ||
| - [x] `SPECIFICATION.md` (THIS FILE — implementation plan) | ||
| - [x] `PREFLIGHT_CHECKLIST.md` (readiness check) | ||
|
|
||
| - [ ] **Review related repo documentation** | ||
| - [x] `CLAUDE.md` (repo instructions) | ||
| - [x] `AGENTS.md` (AI governance) | ||
| - [x] `docs/BRANCHING_STRATEGY.md` (PR process) | ||
|
|
||
| ### D.2 Specification Reviewed & Approved | ||
|
|
||
| - [ ] **Specification document approved by user** | ||
| - [x] Folder-by-folder mapping makes sense | ||
| - [x] Reference updates are comprehensive | ||
| - [x] Implementation sequencing is clear | ||
| - [x] Risk mitigation is acceptable | ||
| - [x] Rollback plan is clear | ||
|
|
There was a problem hiding this comment.
🗄️ Data Integrity & Integration | 🟠 Major | ⚡ Quick win
Do not pre-check approval and sign-off states.
SPECIFICATION.md still reports a draft awaiting user feedback. This checklist marks review criteria and sign-off templates as complete. A user can copy the template without completing Parts A-E. Keep dependent boxes unchecked until evidence and user approval exist.
Also applies to: 300-318, 430-451
🤖 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 `@projects/active/repo-restructuring-2026-07-25/PREFLIGHT_CHECKLIST.md` around
lines 259 - 280, Reset the pre-checked review and approval boxes in
PREFLIGHT_CHECKLIST.md, including the documentation review, specification
approval, and the referenced sign-off sections. Leave dependent checklist items
unchecked until the corresponding evidence, completed Parts A–E, and explicit
user approval are recorded; preserve only boxes supported by existing evidence.
| ### 1.2 Root Cleanup — Move to `.github/` | ||
|
|
||
| **Move these folders from root → `.github/`:** | ||
|
|
||
| | Current Location | New Location | Reason | | ||
| | --- | --- | --- | | ||
| | `scripts/` | `.github/scripts/` | `.github`-specific validation & automation | | ||
| | `website/` | `.github/website/` | `.github` documentation site (github.lightspeedwp.agency) | | ||
| | `config/` (GitHub-specific) | `.github/config/` | GitHub labels, workflows, issue types | | ||
| | `.github/config/` → consolidate | `.github/config/` | Already in right place; consolidate splits if any | |
There was a problem hiding this comment.
🗄️ Data Integrity & Integration | 🟠 Major | ⚡ Quick win
Resolve the config/ destination before implementation.
Section 1.2 says to move GitHub-specific config/ to .github/config/. Section 1.3 says to split config/ and keep portable files at root. A contributor can follow the earlier table and move portable configuration into .github/. Define one destination for every configuration file.
Also applies to: 121-147
🧰 Tools
🪛 LanguageTool
[uncategorized] ~78-~78: The official name of this software platform is spelled with a capital “H”.
Context: ...hub/ **Move these folders from root →.github/`:** | Current Location | New Location...
(GITHUB)
[uncategorized] ~82-~82: The official name of this software platform is spelled with a capital “H”.
Context: ...on | | --- | --- | --- | | scripts/ | .github/scripts/ | .github-specific validati...
(GITHUB)
[uncategorized] ~82-~82: The official name of this software platform is spelled with a capital “H”.
Context: ...- | | scripts/ | .github/scripts/ | .github-specific validation & automation | | `...
(GITHUB)
[uncategorized] ~83-~83: The official name of this software platform is spelled with a capital “H”.
Context: ...alidation & automation | | website/ | .github/website/ | .github documentation sit...
(GITHUB)
[uncategorized] ~83-~83: The official name of this software platform is spelled with a capital “H”.
Context: ...n | | website/ | .github/website/ | .github documentation site (github.lightspeedw...
(GITHUB)
[uncategorized] ~83-~83: The official name of this software platform is spelled with a capital “H”.
Context: ...bsite/|.githubdocumentation site (github.lightspeedwp.agency) | |config/` (Git...
(GITHUB)
[uncategorized] ~84-~84: The official name of this software platform is spelled with a capital “H”.
Context: ...ency) | | config/ (GitHub-specific) | .github/config/ | GitHub labels, workflows, is...
(GITHUB)
[uncategorized] ~85-~85: The official name of this software platform is spelled with a capital “H”.
Context: ...tHub labels, workflows, issue types | | .github/config/ → consolidate | `.github/confi...
(GITHUB)
[uncategorized] ~85-~85: The official name of this software platform is spelled with a capital “H”.
Context: ...s | | .github/config/ → consolidate | .github/config/ | Already in right place; cons...
(GITHUB)
🤖 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 `@projects/active/repo-restructuring-2026-07-25/SPECIFICATION.md` around lines
76 - 85, Clarify the configuration migration rules in Section 1.2 and the
related Section 1.3 content by defining the destination for every configuration
file: move only GitHub-specific files to .github/config/ and retain portable
configuration at the repository root. Ensure the guidance resolves overlaps with
the existing .github/config/ consolidation instruction.
| ## 2. File References That Require Updates | ||
|
|
||
| ### 2.1 Script Updates (in `.github/scripts/validation/`) | ||
|
|
||
| **Files to audit and update:** | ||
|
|
||
| 1. **`validate-frontmatter.js`** | ||
| - Current: `../../schema/frontmatter.schema.json` | ||
| - New: `../../../schemas/frontmatter.schema.json` (move to `.github/scripts/validation/`) | ||
| - Search & replace all schema path references | ||
|
|
||
| 2. **`validate-agents.js`** | ||
| - Current: references `schema` directory | ||
| - New: references `schemas` directory | ||
| - Update all glob patterns and requires | ||
|
|
||
| 3. **`validate-skills.js`** (if exists) | ||
| - Current: references `schema` directory | ||
| - New: references `schemas` directory | ||
|
|
||
| 4. **`validate-plugins.js`** (if exists) | ||
| - Current: references `schema` directory | ||
| - New: references `schemas` directory | ||
|
|
||
| 5. **`validate-json.js`** | ||
| - Current: likely references `schema/**/*.json` | ||
| - New: references `schemas/**/*.json` | ||
|
|
||
| --- | ||
|
|
||
| ### 2.2 npm Scripts (in `package.json`) | ||
|
|
||
| **Audit and update glob patterns:** | ||
|
|
||
| ```bash | ||
| # BEFORE: | ||
| npm run validate:json # May use schema/**/*.json glob | ||
| npm run validate:agents # May reference schema/ path | ||
|
|
||
| # AFTER: | ||
| npm run validate:json # Uses schemas/**/*.json glob | ||
| npm run validate:agents # References schemas/ path | ||
| ``` | ||
|
|
||
| **Action:** Search `package.json` for all `schema/` references; replace with `schemas/` | ||
|
|
There was a problem hiding this comment.
🗄️ Data Integrity & Integration | 🟠 Major | 🏗️ Heavy lift
Audit every script consumer before moving scripts/.
The supplied package.json context at Lines 116-126 invokes scripts/cleanup-branches.js, scripts/sync-version.js, and metrics/frontmatter-metrics.js. This plan only lists schema-validation references. Classify each script as portable or GitHub-specific, then update every npm script and workflow before the move. Otherwise, Phase 1 can break existing commands.
🧰 Tools
🪛 LanguageTool
[uncategorized] ~153-~153: The official name of this software platform is spelled with a capital “H”.
Context: ...ire Updates ### 2.1 Script Updates (in .github/scripts/validation/) **Files to audit...
(GITHUB)
[uncategorized] ~159-~159: The official name of this software platform is spelled with a capital “H”.
Context: ...hemas/frontmatter.schema.json(move to.github/scripts/validation/`) - Search & rep...
(GITHUB)
🤖 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 `@projects/active/repo-restructuring-2026-07-25/SPECIFICATION.md` around lines
151 - 196, The restructuring plan must audit every consumer of scripts before
moving the directory, not only schema-validation references. Review package.json
commands such as cleanup-branches.js, sync-version.js, and
frontmatter-metrics.js, classify each script as portable or GitHub-specific, and
update all affected npm scripts and workflow references before Phase 1 so
existing commands remain functional.
| ### Phase 5: Documentation Updates | ||
|
|
||
| 1. **Create migration guide** (`.github/docs/MIGRATION.md`) | ||
| - Document schema consolidation | ||
| - Document folder moves | ||
| - Provide reference update checklist | ||
|
|
||
| 2. **Update README files** | ||
| - `schemas/README.md` — new file documenting schema organisation | ||
| - `agents/README.md` — update links | ||
| - `skills/README.md` — update links | ||
|
|
||
| 3. **Update CLAUDE.md** (this file) | ||
| - Update path reference section with migration details | ||
| - Link to migration guide |
There was a problem hiding this comment.
📐 Maintainability & Code Quality | 🟠 Major | ⚡ Quick win
Place the migration guide under docs/.
Phase 5 creates .github/docs/MIGRATION.md and makes it a success criterion. That path conflicts with the repository rule for permanent human documentation. Use docs/MIGRATION.md and update all links in the same change.
As per coding guidelines, permanent human documentation belongs in docs/, not .github/.
Also applies to: 499-504
🧰 Tools
🪛 LanguageTool
[uncategorized] ~393-~393: The official name of this software platform is spelled with a capital “H”.
Context: ...Updates 1. Create migration guide (.github/docs/MIGRATION.md) - Document schem...
(GITHUB)
[style] ~399-~399: Would you like to use the Oxford spelling “organization”? The spelling ‘organisation’ is also correct.
Context: ...EADME.md— new file documenting schema organisation -agents/README.md` — update links ...
(OXFORD_SPELLING_Z_NOT_S)
🤖 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 `@projects/active/repo-restructuring-2026-07-25/SPECIFICATION.md` around lines
391 - 405, Update the Phase 5 documentation plan to create the migration guide
at docs/MIGRATION.md instead of .github/docs/MIGRATION.md, and revise every
related link or reference, including the CLAUDE.md update and success criteria,
to use the new location.
Source: Coding guidelines
| ## 4. Dependency Graph — What Must Happen First | ||
|
|
||
| ``` | ||
| ┌─────────────────────────────────────────┐ | ||
| │ 0. User confirms all 50-question │ | ||
| │ decisions (BLOCKER) │ | ||
| └────────────────┬────────────────────────┘ | ||
| │ | ||
| ▼ | ||
| ┌─────────────────────────────────────────┐ | ||
| │ 1. Folder moves (create new locations) │ | ||
| │ - Create schemas/ │ | ||
| │ - Create .github/scripts/ │ | ||
| │ - Create .github/website/ │ | ||
| │ - Copy files (don't delete yet) │ | ||
| └────────────────┬────────────────────────┘ | ||
| │ | ||
| ▼ | ||
| ┌─────────────────────────────────────────┐ | ||
| │ 2. Reference updates (by type) │ | ||
| │ - Update npm scripts │ | ||
| │ - Update validation scripts │ | ||
| │ - Update workflows │ | ||
| │ - Update docs & instructions │ | ||
| │ - Test each script │ | ||
| └────────────────┬────────────────────────┘ | ||
| │ | ||
| ▼ | ||
| ┌─────────────────────────────────────────┐ | ||
| │ 3. Validation & testing │ | ||
| │ - Run validation scripts │ | ||
| │ - Run full test suite │ | ||
| │ - Manual verification │ | ||
| │ - Fix any issues │ | ||
| └────────────────┬────────────────────────┘ | ||
| │ | ||
| ▼ | ||
| ┌─────────────────────────────────────────┐ | ||
| │ 4. Create PR & merge │ | ||
| │ - Create branch: refactor/... │ | ||
| │ - All validation passes │ | ||
| │ - Merge to develop │ | ||
| └────────────────┬────────────────────────┘ | ||
| │ | ||
| ▼ | ||
| ┌─────────────────────────────────────────┐ | ||
| │ 5. Final cleanup │ | ||
| │ - Archive old locations │ | ||
| │ - Remove archives (after PR merges) │ | ||
| │ - Update documentation │ | ||
| └─────────────────────────────────────────┘ |
There was a problem hiding this comment.
🗄️ Data Integrity & Integration | 🟠 Major | ⚡ Quick win
Use one phase order across the specification.
Section 3 labels Phase 4 as archive and cleanup, while the dependency graph labels Phase 4 as PR and merge. The graph then places final cleanup in Phase 5. PREFLIGHT_CHECKLIST.md follows the graph, not Section 3. Choose one phase numbering scheme and update all references before execution.
🤖 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 `@projects/active/repo-restructuring-2026-07-25/SPECIFICATION.md` around lines
409 - 459, Standardize the phase numbering across SPECIFICATION.md and
PREFLIGHT_CHECKLIST.md: reconcile Section 3 with the dependency graph so archive
and cleanup use the same phase as the graph’s “Final cleanup,” while PR creation
and merge retain their corresponding phase. Update every phase reference
consistently before execution.
| ## 7. Rollback Plan | ||
|
|
||
| **If validation fails at any point:** | ||
|
|
||
| 1. **Do NOT proceed** to next phase | ||
| 2. **Revert local changes** (don't commit) | ||
|
|
||
| ```bash | ||
| git reset --hard HEAD | ||
| git clean -fd | ||
| ``` | ||
|
|
||
| 3. **Or revert PR** (if already merged) | ||
|
|
||
| ```bash | ||
| git revert <merge-commit-hash> | ||
| ``` | ||
|
|
||
| 4. **Return to backup branch** | ||
|
|
||
| ```bash | ||
| git checkout backup/pre-restructure-2026-07-31 | ||
| ``` |
There was a problem hiding this comment.
🗄️ Data Integrity & Integration | 🟠 Major | ⚡ Quick win
Make rollback safe after commits and for untracked files.
git clean -fd deletes all untracked files and directories, not only migration artefacts. Also, after the archive commit at Line 384, git reset --hard HEAD cannot undo that commit. Use phase-specific rollback: restore from the backup reference before commits, revert committed changes after commits, and remove only explicitly created paths after a dry run.
🤖 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 `@projects/active/repo-restructuring-2026-07-25/SPECIFICATION.md` around lines
520 - 542, Update the “Rollback Plan” to use phase-specific recovery: restore
from the backup reference before commits, and revert committed changes after the
archive commit instead of relying on git reset --hard HEAD. Replace the broad
git clean -fd command with a dry-run followed by removal of only explicitly
created migration paths, preserving unrelated untracked files.
Pull request was closed
1 participant
Linked issues
Relates to Wave 5 documentation audit and restructuring initiative (#902–#927)
What changed
Audience & placement
.github/projects/active/repo-restructuring-2026-07-25/Preview / Screenshots
[Planning documents are text-based specifications and checklists]
Notes
Changelog
Added
Changed
Fixed
Removed
Checklist (Global DoD / PR)
🤖 Generated with Claude Code