# Implementation Plan - Codex Goal Mode Integration

## Revision History
| Version | Date | Description | Author |
|---|---|---|---|
| v1.0 | 2026-06-22 | Initial plan for Codex Goal Mode, skill, and workflow integration | Antigravity Orchestrator |

---

## Goal Description
Implement a **Goal Mode** (including a new **Skill** and a **Workflow**) that utilizes the Codex goal-execution capabilities for centralized task orchestration. In this mode, Codex serves as the master coordinator (Goal Conductor), partitioning a high-level user goal into subtasks, tracking progress in Symphony, and delegating specific duties back to other specialized agents (Claude, Qwen, Gemini/AGY) or its own independent sub-agents (e.g., critic, coder, tester, ios-engineer) in a collaborative loop.

---

## User Review Required

> [!IMPORTANT]
> **Orchestration Loop Protocol:** Codex Goal Mode runs as a closed-loop execution system. Checkpoints are automatically bypassed when `goal_mode = true` (using best-effort AI verification) except for safety-critical, destructive, or security tasks.

---

## Open Questions
- Do we want to support persistent background session resume for long-running goals (e.g., using `codex resume --last`)? *(Currently planned to support resume by storing execution states in `codex-reports/goals/`).*

---

## Proposed Changes

### Core Orchestration Layer

#### [NEW] [codex-goal.js](file:///Users/trungkientn/Dev/NodeJS/main-awf/scripts/codex-goal.js)
Create a new script that coordinates the Goal loop:
1. Initializes a goal workspace under `codex-reports/goals/<goal_id>/`.
2. Sets `goal_mode = true` in the process context.
3. Invokes Codex CLI to analyze the initial goal, parse it into subtasks, and map them to appropriate agents.
4. Orchestrates task execution:
   - For architecture & specs: Delegates to Claude via `scripts/claude-plan.js`.
   - For coding/refactoring: Delegates to Qwen via `scripts/qwen-exec.js`.
   - For general tasks/fallbacks: Delegates to AGY (Gemini).
   - For reviews, tests, visual QA: Delegates to Codex sub-agents (`critic`, `tester`, `ios-visual-qa-strategist`).
5. Tracks states, saves progress reports to `.md` files, and updates Symphony tickets.

---

### Workflows

#### [NEW] [goal.md](file:///Users/trungkientn/Dev/NodeJS/main-awf/workflows/lifecycle/goal.md)
Define the `/goal` workflow containing:
- Pre-requisites checks for Codex CLI.
- Workflow subcommands: `/goal "[objective]"`, `/goal:status`, `/goal:resume`, `/goal:pause`, `/goal:cancel`.
- Detailed description of the autonomous goal execution loop.
- Fallback policies and recovery steps.

---

### Skills

#### [NEW] [SKILL.md](file:///Users/trungkientn/Dev/NodeJS/main-awf/skills/codex-goal/SKILL.md)
Create a new skill for the Codex Goal Orchestrator defining:
- Developer instructions for the master Goal Conductor role.
- Task breakdown schemas and JSON mapping format.
- Sub-agent specifications (definitions, system prompts, capabilities).
- Call-back protocols for Claude, Qwen, and AGY.

---

### CLI & Code Integration

#### [MODIFY] [awk.js](file:///Users/trungkientn/Dev/NodeJS/main-awf/bin/awk.js)
1. Register `goal` in the CLI command list and register the command parser.
2. Include the new `/goal` and `/goal-mode` commands in the help usage block.
3. Add the `codex-goal` skill folder to the default runtime list, ensuring it gets synced during `awkit install`.

#### [MODIFY] [codex-generators.js](file:///Users/trungkientn/Dev/NodeJS/main-awf/bin/codex-generators.js)
Add `codex-goal` to `SPECIALIST_SKILLS` list so that a Codex-compatible `.toml` agent spec is automatically generated for it.

---

## Verification Plan

### Automated Tests
- Run `node bin/awk.js doctor` to check installation state.
- Run `awkit status` to ensure all files are synchronized.

### Manual Verification
- Execute `node bin/awk.js goal "Build a simple greeting command line tool"` and verify that the orchestration loop initializes the plan, registers tasks, calls Qwen for implementation, and reviews using the critic sub-agent.
- Verify status checks, pause, and resume capabilities.