Add research phase to end of current milestone in roadmap
Codex shell compatibility:
gpd on PATH.GPD_ACTIVE_RUNTIME=codex uv run gpd ....
</codex_runtime_notes>Routes to the add-phase workflow which handles:
Typical research phases include:
<execution_context> @.gpd/ROADMAP.md @.gpd/STATE.md
<required_reading> Read all files referenced by the invoking prompt's execution_context before starting. </required_reading>
If no arguments provided:
ERROR: Phase description required
Usage: $gpd-add-phase <description>
Example: $gpd-add-phase Derive renormalization group equations
Exit. </step>
INIT=$(/Users/charlie/.gpd/venv/bin/python -m gpd.runtime_cli --runtime codex --config-dir ./.codex --install-scope local init phase-op "0")
if [ $? -ne 0 ]; then
echo "ERROR: gpd initialization failed: $INIT"
# STOP — display the error to the user and do not proceed.
fi
Check roadmap_exists from init JSON. If false:
ERROR: No roadmap found (.gpd/ROADMAP.md)
Run $gpd-new-project to initialize.
Exit. </step>
RESULT=$(/Users/charlie/.gpd/venv/bin/python -m gpd.runtime_cli --runtime codex --config-dir ./.codex --install-scope local phase add "${description}")
if [ $? -ne 0 ]; then
echo "ERROR: phase add failed: $RESULT"
# STOP — do not proceed.
fi
The CLI handles:
.gpd/phases/{NN}-{slug}/)Extract from result: phase_number, padded, name, slug, directory.
</step>
/Users/charlie/.gpd/venv/bin/python -m gpd.runtime_cli --runtime codex --config-dir ./.codex --install-scope local state add-decision --phase "${N}" --summary "Added Phase ${N}: ${description}" --rationale "Extends current milestone with new research phase"
/Users/charlie/.gpd/venv/bin/python -m gpd.runtime_cli --runtime codex --config-dir ./.codex --install-scope local state update "Last Activity" "$(date +%Y-%m-%d)"
This ensures STATE.md and state.json stay in sync. Do NOT edit STATE.md directly — always use gpd state commands. </step>
Phase {N} added to current milestone:
- Description: {description}
- Directory: .gpd/phases/{phase-num}-{slug}/
- Status: Not planned yet
Roadmap updated: .gpd/ROADMAP.md
---
## Next Up
**Phase {N}: {description}**
`$gpd-plan-phase {N}`
<sub>`/clear` first -> fresh context window</sub>
---
**Also available:**
- `$gpd-add-phase <description>` -- add another phase
- Review roadmap
---
<success_criteria>
gpd phase add executed successfullygpd state add-decision (STATE.md + state.json synced)</success_criteria>
</execution_context>
The workflow handles all logic including: