218 lines
6.9 KiB
Markdown
218 lines
6.9 KiB
Markdown
# 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"
|
|
```
|