diff --git a/docs/superpowers/plans/2026-07-27-claude-to-codex-project-context.md b/docs/superpowers/plans/2026-07-27-claude-to-codex-project-context.md new file mode 100644 index 00000000..f570a851 --- /dev/null +++ b/docs/superpowers/plans/2026-07-27-claude-to-codex-project-context.md @@ -0,0 +1,217 @@ +# Claude to Codex Project Context Implementation Plan + +> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. + +**Goal:** Add a project-level Codex entry point, release skill, and sanitized memory set while leaving `.claude` unchanged. + +**Architecture:** `AGENTS.md` contains short, always-on rules. `.agents/skills/release/SKILL.md` contains the opt-in backend release workflow. `.codex/memory/` contains detailed project knowledge linked from a single index so Codex can load it only when relevant. + +**Tech Stack:** Markdown, Codex `AGENTS.md`, Codex project skills + +--- + +### Task 1: Add the always-on Codex project instructions + +**Files:** +- Create: `AGENTS.md` + +- [x] **Step 1: Create the instruction entry point** + +Add concise sections covering: + +- Repository shape: Django backend here and Vue frontend at `../ehs_web`. +- Frontend route/menu behavior: routes are delivered by the backend; do not add new views to `src/config/route.js`. +- Python execution: use `D:\projects\factory\.venv\Scripts\python.exe`. +- Ignored scripts: never force-add `scripts/*.py` without explicit instruction. +- Release policy: never bump or release unless explicitly requested; then use `.agents/skills/release/SKILL.md`. +- Production data policy: read-only queries only when relevant, credentials from ignored local configuration, and no secrets in docs or commands. +- Pointers to `.codex/memory/MEMORY.md` for detailed context. + +- [x] **Step 2: Verify the entry point** + +Run: + +```powershell +rg -n "ehs_web|route.js|.venv|scripts/\\*\\.py|release|只读|memory" AGENTS.md +``` + +Expected: every rule category appears at least once. + +- [x] **Step 3: Commit** + +```powershell +git add -- AGENTS.md +git commit -m "docs: add Codex project instructions" +``` + +### Task 2: Add the opt-in backend release skill + +**Files:** +- Create: `.agents/skills/release/SKILL.md` + +- [x] **Step 1: Create the skill** + +Add valid skill frontmatter: + +```yaml +--- +name: factory-release +description: Use only when the user explicitly asks to release the factory backend, bump its version, or run the release workflow. +--- +``` + +The body must require this exact order: + +1. Confirm the user explicitly requested a backend release. +2. Check the working tree and prevent unrelated files from entering the release commit. +3. Run `bash update_changelog.sh` and use its emitted version. +4. Update `server/settings.py` `SYS_VERSION`. +5. Inspect the top of `changelog.md`. +6. Stage only `changelog.md` and `server/settings.py`. +7. Commit as `release: ` without Claude-specific attribution. +8. Create tag ``, push the branch, then push the tag. +9. Report version, changelog categories, commit hash, tag, and push results. + +The skill must state that frontend `ehs_web` releases use a separate workflow documented in `.codex/memory/reference_ehs_web_release.md`. + +- [x] **Step 2: Verify the skill** + +Run: + +```powershell +rg -n "explicitly|update_changelog|SYS_VERSION|changelog.md|git tag|git push|ehs_web|Co-Authored-By" .agents/skills/release/SKILL.md +``` + +Expected: all required release steps appear and `Co-Authored-By` does not appear. + +- [x] **Step 3: Commit** + +```powershell +git add -- .agents/skills/release/SKILL.md +git commit -m "docs: add factory release skill" +``` + +### Task 3: Add the sanitized Codex project memory + +**Files:** +- Create: `.codex/memory/MEMORY.md` +- Create: `.codex/memory/feedback_routing.md` +- Create: `.codex/memory/feedback_scripts_gitignore.md` +- Create: `.codex/memory/feedback_version_bump.md` +- Create: `.codex/memory/project_frontend_ehs_web.md` +- Create: `.codex/memory/project_gx_db_access.md` +- Create: `.codex/memory/project_material_ofrom_merge_bug.md` +- Create: `.codex/memory/reference_ehs_web_release.md` +- Create: `.codex/memory/reference_python_venv.md` +- Create: `.codex/memory/reference_wrapper_apps.md` + +- [x] **Step 1: Create the memory index** + +Create one relative Markdown link for each of the nine detailed memory files. Each link must summarize when the file is relevant. + +- [x] **Step 2: Migrate stable feedback and references** + +Preserve the operational meaning of: + +- Backend-delivered frontend routes. +- The intentional `scripts/*.py` ignore rule. +- Explicit-only release/version bumps. +- The project virtual environment. +- The independent frontend release workflow. +- The two wrapper applications. + +Remove Claude session IDs, Claude metadata, wiki-link syntax, and Claude-specific tool names. + +- [x] **Step 3: Migrate project background and historical diagnosis** + +Preserve: + +- Backend/frontend coupling and statistics page conventions. +- Read-only production-data verification policy. +- The `material_ofrom` historical diagnosis, affected code locations, known evidence, and next investigation point. + +Replace all database credentials with instructions to read connection parameters from ignored local configuration. Do not include usernames, passwords, `PGPASSWORD`, or ready-to-run production connection commands. + +- [x] **Step 4: Verify index targets** + +Run: + +```powershell +$missing = @() +Get-Content .codex/memory/MEMORY.md | + Select-String -AllMatches '\]\(([^)]+\.md)\)' | + ForEach-Object { $_.Matches } | + ForEach-Object { + $target = Join-Path '.codex/memory' $_.Groups[1].Value + if (-not (Test-Path -LiteralPath $target)) { $missing += $target } + } +if ($missing.Count -gt 0) { $missing; exit 1 } +"All memory links resolve" +``` + +Expected: `All memory links resolve`. + +- [x] **Step 5: Commit** + +```powershell +git add -- .codex/memory +git commit -m "docs: migrate project memory for Codex" +``` + +### Task 4: Validate migration safety and coverage + +**Files:** +- Inspect: `AGENTS.md` +- Inspect: `.agents/skills/release/SKILL.md` +- Inspect: `.codex/memory/*.md` +- Inspect unchanged: `.claude/settings.local.json` +- Inspect unchanged: `.claude/commands/release.md` + +- [x] **Step 1: Scan for prohibited Claude artifacts and secrets** + +Run: + +```powershell +rg -n -i "originSessionId|scratchpad|PGPASSWORD|Co-Authored-By: Claude|password\s*=|postgresql://" AGENTS.md .agents/skills .codex/memory +``` + +Expected: no matches. + +- [x] **Step 2: Check topic coverage** + +Run: + +```powershell +Get-ChildItem .codex/memory -File | Sort-Object Name | Select-Object -ExpandProperty Name +``` + +Expected: `MEMORY.md` plus all nine detailed memory files are listed. + +- [x] **Step 3: Confirm Claude files are untouched** + +Run: + +```powershell +git status --short -- .claude +git diff -- .claude +``` + +Expected: no output. + +- [x] **Step 4: Check formatting and scoped changes** + +Run: + +```powershell +git diff --check +git status --short +``` + +Expected: no whitespace errors; only pre-existing user files and this migration's plan file remain uncommitted. + +- [x] **Step 5: Commit the implementation plan** + +```powershell +git add -- docs/superpowers/plans/2026-07-27-claude-to-codex-project-context.md +git commit -m "docs: record Codex context migration plan" +```