zcdsj
/
factory
5
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
factory/docs/superpowers/plans/2026-07-27-claude-to-codex-...

6.9 KiB
Raw Blame History

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

  • 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.

  • Step 2: Verify the entry point

Run:

rg -n "ehs_web|route.js|.venv|scripts/\\*\\.py|release|只读|memory" AGENTS.md

Expected: every rule category appears at least once.

  • Step 3: Commit
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

  • Step 1: Create the skill

Add valid skill frontmatter:

---
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: <VER> without Claude-specific attribution.
  8. Create tag <VER>, 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.

  • Step 2: Verify the skill

Run:

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.

  • Step 3: Commit
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

  • 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.

  • 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.

  • 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.

  • Step 4: Verify index targets

Run:

$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.

  • Step 5: Commit
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

  • Step 1: Scan for prohibited Claude artifacts and secrets

Run:

rg -n -i "originSessionId|scratchpad|PGPASSWORD|Co-Authored-By: Claude|password\s*=|postgresql://" AGENTS.md .agents/skills .codex/memory

Expected: no matches.

  • Step 2: Check topic coverage

Run:

Get-ChildItem .codex/memory -File | Sort-Object Name | Select-Object -ExpandProperty Name

Expected: MEMORY.md plus all nine detailed memory files are listed.

  • Step 3: Confirm Claude files are untouched

Run:

git status --short -- .claude
git diff -- .claude

Expected: no output.

  • Step 4: Check formatting and scoped changes

Run:

git diff --check
git status --short

Expected: no whitespace errors; only pre-existing user files and this migration's plan file remain uncommitted.

  • Step 5: Commit the implementation plan
git add -- docs/superpowers/plans/2026-07-27-claude-to-codex-project-context.md
git commit -m "docs: record Codex context migration plan"