diff --git a/.github/ISSUE_TEMPLATE/codex_task.yml b/.github/ISSUE_TEMPLATE/codex_task.yml new file mode 100644 index 000000000..3745c47ae --- /dev/null +++ b/.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 diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index d224455e6..3cd98fd93 100644 --- a/.github/pull_request_template.md +++ b/.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. diff --git a/.github/workflows/codex-structure-check.yml b/.github/workflows/codex-structure-check.yml new file mode 100644 index 000000000..47fa727c3 --- /dev/null +++ b/.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 diff --git a/AGENTS.md b/AGENTS.md index f0570f7e0..469295a43 100644 --- a/AGENTS.md +++ b/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. diff --git a/CODEX_PASTE_PROMPT.md b/CODEX_PASTE_PROMPT.md new file mode 100644 index 000000000..8e4d41ad9 --- /dev/null +++ b/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. +``` diff --git a/agent-inbox/task-current.md b/agent-inbox/task-current.md new file mode 100644 index 000000000..cd415eec3 --- /dev/null +++ b/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. diff --git a/agent-inbox/task-queue.md b/agent-inbox/task-queue.md new file mode 100644 index 000000000..205137b88 --- /dev/null +++ b/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. diff --git a/agent-outbox/codex-report.md b/agent-outbox/codex-report.md new file mode 100644 index 000000000..af6a4e57c --- /dev/null +++ b/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. diff --git a/agent-outbox/error-report.md b/agent-outbox/error-report.md new file mode 100644 index 000000000..153e0ee61 --- /dev/null +++ b/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`. diff --git a/agent-outbox/execution-log.md b/agent-outbox/execution-log.md new file mode 100644 index 000000000..335b8286f --- /dev/null +++ b/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. diff --git a/agent-outbox/next-actions.md b/agent-outbox/next-actions.md new file mode 100644 index 000000000..ece523226 --- /dev/null +++ b/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. diff --git a/docs/chatgpt-codex-workflow.md b/docs/chatgpt-codex-workflow.md new file mode 100644 index 000000000..2e1a5ff91 --- /dev/null +++ b/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. diff --git a/docs/codex-desktop-operating-rules.md b/docs/codex-desktop-operating-rules.md new file mode 100644 index 000000000..7a7c94d5f --- /dev/null +++ b/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. diff --git a/ops/acceptance-checklist.md b/ops/acceptance-checklist.md new file mode 100644 index 000000000..76157d948 --- /dev/null +++ b/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. diff --git a/ops/rollback-plan.md b/ops/rollback-plan.md new file mode 100644 index 000000000..28d0fce61 --- /dev/null +++ b/ops/rollback-plan.md @@ -0,0 +1,26 @@ +# Rollback Plan + +## Preferred Rollback +Revert the setup commit: + +```bash +git revert +``` + +## 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. diff --git a/scripts/verify-codex-bridge.sh b/scripts/verify-codex-bridge.sh new file mode 100755 index 000000000..bf721e718 --- /dev/null +++ b/scripts/verify-codex-bridge.sh @@ -0,0 +1,46 @@ +#!/usr/bin/env bash +set -euo pipefail + +required_paths=( + ".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/acceptance-checklist.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" +) + +missing=0 +for path in "${required_paths[@]}"; do + if [[ ! -e "$path" ]]; then + echo "missing: $path" + missing=1 + fi +done + +if git diff --cached --name-only | grep -E '(^|/)\.env($|\.)|secret|credential|backup|production-data' >/dev/null; then + echo "forbidden staged file detected" + exit 1 +fi + +current_branch="$(git branch --show-current)" +if [[ "$current_branch" != "codex/stage-41a-github-bridge" ]]; then + echo "unexpected branch: $current_branch" + missing=1 +fi + +if [[ "$missing" -ne 0 ]]; then + exit 1 +fi + +echo "codex bridge structure ok"