# 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: <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`.

- [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"
```