[Codex] Stage 41A - Add GitHub handoff bridge

.github/ISSUE_TEMPLATE/codex_task.yml

@@ -0,0 +1,74 @@
+name: Codex Task
+description: Hand off a scoped implementation task to Codex Desktop.
+title: "[Codex] "
+labels:
+  - codex
+  - agent-task
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Use this template to hand off a bounded task from ChatGPT Web to Codex Desktop.
+  - type: input
+    id: task_id
+    attributes:
+      label: Task ID
+      description: Stable identifier for this handoff.
+      placeholder: Stage-41B-SMOKE-TEST
+    validations:
+      required: true
+  - type: textarea
+    id: objective
+    attributes:
+      label: Objective
+      description: What should Codex accomplish?
+    validations:
+      required: true
+  - type: textarea
+    id: allowed_scope
+    attributes:
+      label: Allowed Scope
+      description: Files, directories, and behaviors Codex may change.
+      placeholder: |
+        - README.md
+        - docs/
+    validations:
+      required: true
+  - type: textarea
+    id: forbidden_scope
+    attributes:
+      label: Forbidden Scope
+      description: Files, directories, or data Codex must not touch.
+      value: |
+        - .env
+        - .env.*
+        - secret files
+        - credential files
+        - database backups
+        - production data
+    validations:
+      required: true
+  - type: textarea
+    id: acceptance_criteria
+    attributes:
+      label: Acceptance Criteria
+      description: Concrete checks that must pass before the task is complete.
+    validations:
+      required: true
+  - type: textarea
+    id: verification
+    attributes:
+      label: Verification
+      description: Commands or manual checks Codex should run.
+      placeholder: |
+        npm test
+        git status --short
+    validations:
+      required: true
+  - type: textarea
+    id: rollback_plan
+    attributes:
+      label: Rollback Plan
+      description: How to undo the change if needed.
+    validations:
+      required: true

.github/pull_request_template.md

@@ -6,3 +6,10 @@
 
 - [ ] Tested locally
 - [ ] No unrelated changes included
+
+## Codex Handoff
+
+- [ ] `agent-outbox/codex-report.md` is updated when this PR was produced by Codex.
+- [ ] Verification commands and results are summarized in the PR or outbox report.
+- [ ] No secrets, credentials, backups, production data, or environment files are included.
+- [ ] Rollback plan is documented for Codex handoff changes.

.github/workflows/codex-structure-check.yml

@@ -0,0 +1,27 @@
+name: Codex Structure Check
+
+on:
+  pull_request:
+    paths:
+      - ".github/ISSUE_TEMPLATE/codex_task.yml"
+      - ".github/pull_request_template.md"
+      - ".github/workflows/codex-structure-check.yml"
+      - "agent-inbox/**"
+      - "agent-outbox/**"
+      - "ops/**"
+      - "scripts/verify-codex-bridge.sh"
+      - "docs/chatgpt-codex-workflow.md"
+      - "docs/codex-desktop-operating-rules.md"
+      - "CODEX_PASTE_PROMPT.md"
+      - "AGENTS.md"
+  workflow_dispatch:
+
+jobs:
+  structure:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Verify Codex bridge files
+        run: bash scripts/verify-codex-bridge.sh

AGENTS.md

@@ -34,3 +34,15 @@ In practice:
 
 - At the end of each completed task, play a short local completion sound on the user's machine (for example with `afplay` on macOS) so the user notices work has finished even when reading or working in another window.
 - This reminder should be treated as a default behavior for this repository across sessions unless the user explicitly asks to skip it for a specific task.
+
+## GitHub Handoff Workflow
+
+For ChatGPT Web <-> Codex Desktop handoff tasks:
+
+1. Read `agent-inbox/task-current.md` before making changes.
+2. Stay within the task's allowed scope.
+3. Do not modify `.env`, `.env.*`, secrets, credentials, database backups, production data, or deployment credentials.
+4. Write execution results to `agent-outbox/`.
+5. Run `scripts/verify-codex-bridge.sh` when the handoff structure is relevant.
+6. Commit task-related changes on the current task branch when requested.
+7. Do not push unless explicitly instructed.

CODEX_PASTE_PROMPT.md

@@ -0,0 +1,21 @@
+# Codex Paste Prompt
+
+Use this prompt when handing a GitHub task from ChatGPT Web to Codex Desktop.
+
+```text
+You are working in the Clawith repository.
+
+Read AGENTS.md first, then read agent-inbox/task-current.md.
+
+Implement only the allowed scope listed in the current task. Do not modify forbidden files, secrets, production data, deployment credentials, database backups, or unrelated business source code.
+
+After implementation:
+1. Update agent-outbox/codex-report.md with the summary and verification.
+2. Update agent-outbox/execution-log.md with important actions.
+3. Update agent-outbox/error-report.md if anything failed.
+4. Update agent-outbox/next-actions.md with remaining work.
+5. Run the requested verification commands.
+6. Show git status.
+7. Commit only the task-related changes if the task requires a commit.
+8. Do not push unless explicitly instructed.
+```

agent-inbox/task-current.md

@@ -0,0 +1,55 @@
+# Current Codex Task
+
+## Task ID
+Stage-41A-GITHUB-BRIDGE
+
+## Title
+Deploy ChatGPT Web <-> Codex Desktop GitHub handoff workflow
+
+## Objective
+Create a lightweight GitHub-based handoff system so ChatGPT Web can generate tasks and review results, while Codex Desktop reads tasks, modifies code, writes reports, and creates PRs.
+
+## Allowed Scope
+Codex may create or update only:
+
+- `.github/ISSUE_TEMPLATE/codex_task.yml`
+- `.github/pull_request_template.md`
+- `.github/workflows/codex-structure-check.yml`
+- `agent-inbox/`
+- `agent-outbox/`
+- `ops/`
+- `scripts/`
+- `docs/`
+- `CODEX_PASTE_PROMPT.md`
+- `AGENTS.md`
+
+## Forbidden Scope
+Codex must not modify:
+
+- `.env`
+- `.env.*`
+- secret files
+- credential files
+- database backups
+- production data
+- deployment credentials
+- existing business source code
+
+## Required Actions
+1. Create the GitHub handoff structure.
+2. Create inbox, outbox, ops, docs, and script files.
+3. Add Codex operating rules to `AGENTS.md`.
+4. Verify all required files exist.
+5. Commit changes on the current branch.
+6. Do not push unless explicitly instructed.
+
+## Acceptance Criteria
+- Required directories exist.
+- Required files exist.
+- No secret or production file is staged.
+- Branch is `codex/stage-41a-github-bridge`.
+- Commit is created successfully.
+- Rollback plan exists.
+
+## Rollback Plan
+Revert the generated commit or delete the generated handoff files.

agent-inbox/task-queue.md

@@ -0,0 +1,7 @@
+# Codex Task Queue
+
+## Pending
+- Stage-41B-SMOKE-TEST: Run a harmless README edit and complete the full task -> report -> PR -> ChatGPT review loop.
+
+## Completed
+- Stage-41A-GITHUB-BRIDGE: Initialize GitHub handoff workflow.

agent-outbox/codex-report.md

@@ -0,0 +1,40 @@
+# Codex Execution Report
+
+## Task ID
+Stage-41A-GITHUB-BRIDGE
+
+## Status
+COMPLETED
+
+## Summary
+Created a lightweight GitHub handoff workflow for ChatGPT Web and Codex Desktop.
+
+## Files Created Or Updated
+- `agent-inbox/task-current.md`
+- `agent-inbox/task-queue.md`
+- `agent-outbox/codex-report.md`
+- `agent-outbox/execution-log.md`
+- `agent-outbox/error-report.md`
+- `agent-outbox/next-actions.md`
+- `ops/acceptance-checklist.md`
+- `ops/rollback-plan.md`
+- `scripts/verify-codex-bridge.sh`
+- `.github/ISSUE_TEMPLATE/codex_task.yml`
+- `.github/pull_request_template.md`
+- `.github/workflows/codex-structure-check.yml`
+- `docs/chatgpt-codex-workflow.md`
+- `docs/codex-desktop-operating-rules.md`
+- `CODEX_PASTE_PROMPT.md`
+- `AGENTS.md`
+
+## Verification
+Run:
+
+```bash
+scripts/verify-codex-bridge.sh
+git status --short
+```
+
+## Notes
+- No push was performed.
+- Existing business source code was not modified.

agent-outbox/error-report.md

@@ -0,0 +1,11 @@
+# Error Report
+
+## Task ID
+Stage-41A-GITHUB-BRIDGE
+
+## Status
+No known errors.
+
+## Notes
+- The previously provided one-key shell script was incomplete and contained a placeholder repository path.
+- This repository setup was completed directly in `/Users/meitetools/Clawith`.

agent-outbox/execution-log.md

@@ -0,0 +1,9 @@
+# Execution Log
+
+## Stage-41A-GITHUB-BRIDGE
+- Verified target repository path: `/Users/meitetools/Clawith`.
+- Created branch: `codex/stage-41a-github-bridge`.
+- Created handoff directories and files.
+- Added Codex operating rules to `AGENTS.md`.
+- Added PR checklist items for Codex handoff reports.
+- Added local and CI structure checks.

agent-outbox/next-actions.md

@@ -0,0 +1,12 @@
+# Next Actions
+
+## Recommended
+1. Review the generated handoff files.
+2. Push branch `codex/stage-41a-github-bridge` when ready.
+3. Open a pull request using the generated PR template.
+4. Run Stage-41B-SMOKE-TEST after the PR workflow is confirmed.
+
+## Do Not Do Automatically
+- Do not push without explicit instruction.
+- Do not modify secrets or production data.
+- Do not change business source code as part of handoff plumbing.

docs/chatgpt-codex-workflow.md

@@ -0,0 +1,24 @@
+# ChatGPT Web <-> Codex Desktop Workflow
+
+## Purpose
+This repository uses GitHub as a lightweight handoff layer between ChatGPT Web and Codex Desktop.
+
+## Flow
+1. ChatGPT Web drafts a scoped task using `.github/ISSUE_TEMPLATE/codex_task.yml`.
+2. The task is copied into `agent-inbox/task-current.md` or tracked in `agent-inbox/task-queue.md`.
+3. Codex Desktop reads the inbox, implements only the allowed scope, and avoids forbidden files.
+4. Codex Desktop writes results to `agent-outbox/`.
+5. Codex Desktop commits on a task branch and opens a pull request when explicitly instructed.
+6. ChatGPT Web reviews the PR, the outbox report, and verification evidence.
+
+## Required Outbox Files
+- `agent-outbox/codex-report.md`
+- `agent-outbox/execution-log.md`
+- `agent-outbox/error-report.md`
+- `agent-outbox/next-actions.md`
+
+## Guardrails
+- Keep each handoff small and reviewable.
+- Include acceptance criteria before implementation starts.
+- Never include secrets in inbox, outbox, issues, commits, or PRs.
+- Do not push branches unless explicitly instructed.

docs/codex-desktop-operating-rules.md

@@ -0,0 +1,22 @@
+# Codex Desktop Operating Rules
+
+## Before Work
+1. Read `AGENTS.md`.
+2. Read `agent-inbox/task-current.md`.
+3. Confirm the current branch and repository status.
+4. Confirm the task's allowed and forbidden scope.
+
+## During Work
+- Stay inside the allowed scope.
+- Do not modify `.env`, credentials, backups, production data, or deployment secrets.
+- Keep changes small and easy to review.
+- Record important actions in `agent-outbox/execution-log.md`.
+- Record blockers or failures in `agent-outbox/error-report.md`.
+
+## After Work
+1. Run task-specific verification.
+2. Run `scripts/verify-codex-bridge.sh` when the handoff structure is relevant.
+3. Update `agent-outbox/codex-report.md`.
+4. Check `git status --short` for unexpected files.
+5. Commit changes when requested by the task.
+6. Do not push unless explicitly instructed.

ops/acceptance-checklist.md

@@ -0,0 +1,32 @@
+# Acceptance Checklist
+
+## Stage-41A-GITHUB-BRIDGE
+- [ ] Branch is `codex/stage-41a-github-bridge`.
+- [ ] Required directories exist:
+  - [ ] `.github/ISSUE_TEMPLATE`
+  - [ ] `.github/workflows`
+  - [ ] `agent-inbox`
+  - [ ] `agent-outbox`
+  - [ ] `ops`
+  - [ ] `scripts`
+  - [ ] `docs`
+- [ ] Required files exist:
+  - [ ] `.github/ISSUE_TEMPLATE/codex_task.yml`
+  - [ ] `.github/pull_request_template.md`
+  - [ ] `.github/workflows/codex-structure-check.yml`
+  - [ ] `agent-inbox/task-current.md`
+  - [ ] `agent-inbox/task-queue.md`
+  - [ ] `agent-outbox/codex-report.md`
+  - [ ] `agent-outbox/execution-log.md`
+  - [ ] `agent-outbox/error-report.md`
+  - [ ] `agent-outbox/next-actions.md`
+  - [ ] `ops/rollback-plan.md`
+  - [ ] `scripts/verify-codex-bridge.sh`
+  - [ ] `docs/chatgpt-codex-workflow.md`
+  - [ ] `docs/codex-desktop-operating-rules.md`
+  - [ ] `CODEX_PASTE_PROMPT.md`
+  - [ ] `AGENTS.md`
+- [ ] No secret, credential, backup, production data, or environment file is staged.
+- [ ] Verification script passes locally.
+- [ ] Commit is created successfully.
+- [ ] No push is performed unless explicitly instructed.

ops/rollback-plan.md

@@ -0,0 +1,26 @@
+# Rollback Plan
+
+## Preferred Rollback
+Revert the setup commit:
+
+```bash
+git revert <commit_sha>
+```
+
+## Manual Rollback
+Delete the generated handoff files and restore the two updated files:
+
+```bash
+rm -rf agent-inbox agent-outbox ops
+rm -f scripts/verify-codex-bridge.sh
+rm -f docs/chatgpt-codex-workflow.md docs/codex-desktop-operating-rules.md
+rm -f CODEX_PASTE_PROMPT.md
+rm -f .github/ISSUE_TEMPLATE/codex_task.yml
+rm -f .github/workflows/codex-structure-check.yml
+git checkout -- AGENTS.md .github/pull_request_template.md
+```
+
+## Safety Notes
+- Do not delete existing project source code.
+- Do not delete existing issue templates unrelated to Codex.
+- Do not modify `.env` or credential files during rollback.