---
description: 🎯 Codex Goal Conductor — Pursue high-level goals autonomously using Codex coordination
---

# /goal — Codex Goal Mode Workflow

> Launch Codex in Goal Mode to orchestrate multi-agent task execution and pursue complex goals.

---

## 🛠️ Step-by-Step Execution

### 1. Prerequisites Check
Ensure Codex CLI is installed on the system:
```bash
which codex || echo "NOT_INSTALLED"
```
If missing, suggest the user install it:
```bash
npm i -g @openai/codex
```

### 2. Launching the Goal
Initiate the goal execution loop:
```bash
awkit goal "Build a simple greeting command line tool"
```
Or execute through a specific pipeline command:
```bash
awkit pipeline goal "FeatureName"
```

### 3. Loop Execution Flow
1. **Initialize State:** Create directory `codex-reports/goals/<goal_id>/` and output the planned task list.
2. **Set Goal Mode:** Set `goal_mode = true` globally so that checkpoints automatically verify and bypass user blocks.
3. **Task Orchestration:** The loop script (`scripts/codex-goal.js`) executes tasks sequentially:
   - Partition goal → Delegate plan/design to Claude.
   - Implement code → Delegate implementation to Qwen.
   - Verification → Run Codex sub-agents (`critic` or `tester`).
4. **State Persistence:** Save logs and state changes at the end of each step.

---

## 🔔 Sub-commands

### `/goal:status`
Check the status of the currently active goal and print active task reports:
```bash
node scripts/codex-goal.js --status
```

### `/goal:pause`
Pause the active goal execution loop and save the current state:
```bash
node scripts/codex-goal.js --pause
```

### `/goal:resume`
Resume the most recently paused or saved goal session:
```bash
node scripts/codex-goal.js --resume
```

### `/goal:cancel`
Cancel the active goal session, clean up temporary resources, and reset `goal_mode = false`:
```bash
node scripts/codex-goal.js --cancel
```

---

## 🔔 Sound Notifications

Upon task completion or session completion, trigger sound alerts:
- Success: `afplay /System/Library/Sounds/Glass.aiff && say "Goal phase completed successfully"`
- Paused/Blocker: `afplay /System/Library/Sounds/Basso.aiff && say "Goal execution paused. User attention required."`

---

## 🚫 Fallback Policy

- If Codex CLI fails to launch or encounters critical issues:
  - Fall back to standard **Gemini Conductor** or **Claude Planner** workflows (`scripts/claude-plan.js` or `agy`).
- If Qwen CLI is not available during execution:
  - Fall back to `agy --model gemini-3.5-flash` for code generation.
- Ensure the orchestration script does not crash and logs error outputs gracefully to `codex-reports/goals/error.log`.

---

## 🤖 Autopilot Loop (Fully Automated Mode)

> Fully automated end-to-end goal execution: decompose → seed Symphony DB → launch background worker → self-supervise via re-armed checkpoints until done.

### 1. Decomposition Format Rules

When breaking a goal into `task.md`, every task line MUST follow this parseable format:

```
- [ ] (runner) [Title]: Description | Files: file1,file2 | After: index1,index2
```

- `(runner)`: target executor for the task — e.g. `(qwen)`, `(codex)`, `(claude)`, `(agy)`.
- `[Title]`: short imperative task title.
- `Description`: what needs to be done, self-contained enough for the runner to act without extra context.
- `Files:`: comma-separated list of files the task touches (no spaces required, but keep consistent).
- `After:`: comma-separated list of **preceding** task indices this task depends on. **Backward-only** — a task may only reference indices of tasks that appear before it in the list. Forward references (a task depending on a later task) are invalid and must be rejected/rewritten during decomposition.

Example:
```
- [ ] (qwen) [1] Setup DB schema: Create migrations for users table | Files: migrations/001_users.sql | After:
- [ ] (qwen) [2] Add User model: Implement User model bound to schema | Files: src/models/user.js | After: 1
- [ ] (codex) [3] Build signup UI: Create signup form component | Files: src/ui/Signup.jsx | After: 1
- [ ] (claude) [4] Wire signup flow: Connect UI to User model and validate | Files: src/ui/Signup.jsx,src/models/user.js | After: 2,3
```

### 2. Pushing Tasks to Symphony DB

Once `task.md` is finalized and validated (format + backward-only `After` references), seed it into the Symphony task database:

```bash
awkit symphony-push
```

This parses `task.md` and creates corresponding tasks/dependencies in the Symphony DB, ready for worker pickup.

### 3. Launching the Worker

Start the autonomous background worker daemon that pulls and executes ready tasks:

```bash
awkit symphony-worker --background --project <project_id>
```

Omit `--project <project_id>` to run against the global cross-project queue instead of a single project's task set.

### 4. Checkpoint Supervision Prompt Template

Use this self-contained template to re-awaken the checkpoint agent on each scheduled wake-up (it must carry enough context to act without relying on prior conversation memory):

```
You are the Autopilot Checkpoint Supervisor for goal <goal_id> (project: <project_id>).

Context:
- Goal: <goal description>
- task.md location: <path>
- Symphony DB project scope: <project_id>

Steps:
1. Query Symphony worker + task status (`symphony status`, `symphony next`, or equivalent DB query).
2. Classify current state using the Checkpoint Decision Tree below.
3. Execute the matching action.
4. If re-arming, schedule the next checkpoint wake-up in 300s.
5. Log the decision and any action taken to the goal's walkthrough/log file.
```

### 5. Checkpoint Decision Tree

On each checkpoint wake-up, evaluate in order:

1. **All tasks finished (done or abandoned)** → Verify the build passes, write `walkthrough.md` summarizing the run, and finish. Do **NOT** re-arm the timer.
2. **Worker dead but tasks still ready/pending** → Restart the worker (`awkit symphony-worker --background --project <project_id>`). Allowed up to **3 restarts per goal** — if the 3rd restart also dies, treat as an unrecoverable error (escalate per case 3).
3. **Worker state is `halted` or `stalled`** → Report the error to the user and escalate immediately. Do **NOT** re-arm the timer.
4. **Else (worker alive, tasks still in progress)** → Re-arm the checkpoint timer using the IDE's schedule mechanism, duration **300s**, for up to **24 checkpoints** total (~2 hours). If the 24-checkpoint budget is exhausted without completion, escalate to the user instead of silently re-arming further.

### 6. Safety Guardrails

- Autopilot runs under **Goal Mode Override** (`goal_mode = true`): no interactive confirmations are requested mid-loop for checkpoints, gate approvals, or routine decisions.
- Goal Mode Override does **NOT** bypass the global Safety Guardrails — the loop must never autonomously perform: force-push, `git reset --hard`, recursive delete (`rm -rf`), unscoped `DROP`/`DELETE`, `docker prune`, publish, or production deploy.
- Any destructive or ambiguous-safety action encountered mid-loop halts the loop and escalates to the user instead of proceeding.