structured-dev-cycle

Structured Development Cycle

A disciplined 6-stage development cycle that enforces quality through stage-based tool restrictions. Prevents premature implementation by requiring planning and verification phases.

Background

Inspired by Pi Coding Agent Workflow Extension's structured development approach. The core insight: restricting file modification tools during planning phases forces thorough analysis before code changes.

Stages

Stage Model Recommendations

Following the reasoning-sandwich pattern:

Model selection is advisory — the orchestrator may override based on task complexity.

Stage Tracking

Stage state is tracked via a marker file for hook enforcement:

# Set stage (used by orchestrator or skill)
echo "plan" > /tmp/.codex-dev-stage-$PPID

# Valid stage values (all block Write/Edit except 'implement'):
# plan, verify-plan, implement, verify-impl, compound, done

# Clear stage (disable blocking)
rm -f /tmp/.codex-dev-stage-$PPID

A PreToolUse hook in .codex/hooks/hooks.json checks this marker and blocks Write/Edit tools during non-implementation stages.

Workflow

Stage 1: Plan

[Stage 1/6: Plan]
├── Analyze requirements and constraints
├── Read existing code for context
├── Search for related patterns
├── Define approach with rationale
└── Output: Implementation plan document

Exit criteria: Clear plan with file list, approach description, and risk assessment.

Stage 2: Verify Plan

[Stage 2/6: Verify Plan]
├── Review plan for completeness
├── Check for missing edge cases
├── Validate against existing patterns
├── Consider alternative approaches
└── Output: Plan approval or revision requests

Exit criteria: Plan verified by different perspective (ideally different model via multi-model-verification).

Stage 3: Implement

[Stage 3/6: Implement]
├── Follow verified plan
├── Create/modify files as specified
├── Write tests alongside code
├── Track deviations from plan
└── Output: Implementation complete

Optional Codex Plugin Interop: When entering Stage 3:

1. Use domain expert agents as the default implementation path.
2. If the native Claude Code plugin openai/codex-plugin-cc is explicitly installed and requested, it may provide Codex interop for new-file scaffolding before expert review.
3. Otherwise display [Codex Plugin] Not requested — proceeding with expert agents directly and proceed with standard implementation.

Suitable for optional plugin interop: new files, boilerplate, test stubs, scaffolding Not suitable: modifying existing code, architecture-dependent changes

Exit criteria: All planned files created/modified, tests written.

Stage 4: Verify Implementation

[Stage 4/6: Verify Implementation]
├── Run test suite
├── Review code quality
├── Check for plan deviations
├── Validate error handling
└── Output: Verification report

Exit criteria: All tests pass, no critical issues found. If issues found, return to Stage 3.

Stage 5: Compound

[Stage 5/6: Compound]
├── Run integration tests
├── Cross-module validation
├── Check for side effects
├── Verify documentation accuracy
└── Output: Integration report

Exit criteria: No integration issues. If issues found, return to Stage 3.

Stage 6: Done

[Stage 6/6: Done]
├── Summarize changes made
├── List files modified
├── Note any deviations from plan
├── Suggest follow-up tasks
└── Output: Completion summary

Integration

With EnterPlanMode

Stage 1 (Plan) maps to Claude Code's EnterPlanMode. When the structured cycle is active:

• EnterPlanMode triggers Stage 1
• ExitPlanMode transitions to Stage 2 (Verify Plan), not directly to implementation

With Multi-Model Verification

Stage 2 (Verify Plan) and Stage 4 (Verify Implementation) can invoke the multi-model-verification skill for comprehensive review.

With PreToolUse Hooks

The stage marker file (/tmp/.codex-dev-stage-$PPID) is read by a PreToolUse hook that enforces tool restrictions. This provides a safety net beyond instruction-based compliance.

With Agent Teams

For complex tasks, Agent Teams is preferred when available (R018):

• Plan: architect agent
• Verify: reviewer agent(s) — multi-model-verification via Agent Teams
• Implement: domain expert agent (+ optional openai/codex-plugin-cc interop only when explicitly installed/requested)
• Compound: QA agent

When Agent Teams is enabled AND task involves 3+ agents or review→fix cycles, using Agent Teams is MANDATORY per R018.

When to Use

Stage Transition Commands

# Orchestrator manages transitions:
echo "plan" > /tmp/.codex-dev-stage-$PPID           # Enter planning
echo "verify-plan" > /tmp/.codex-dev-stage-$PPID    # Enter plan verification
echo "implement" > /tmp/.codex-dev-stage-$PPID      # Enter implementation
echo "verify-impl" > /tmp/.codex-dev-stage-$PPID    # Enter impl verification
echo "compound" > /tmp/.codex-dev-stage-$PPID       # Enter compound testing
echo "done" > /tmp/.codex-dev-stage-$PPID           # Mark done
rm -f /tmp/.codex-dev-stage-$PPID                   # Clear (disable blocking)

Limitations

• Session scoping: The marker path is scoped by parent PID (/tmp/.codex-dev-stage-$PPID), so concurrent Codex sessions use distinct markers and do not conflict. The reader hooks (stage-blocker.sh, task-state-precompact.sh) and the writer commands above all resolve $PPID to the same Codex process, keeping the gate consistent.
• World-writable path: The /tmp/ directory is accessible to all users. The -$PPID suffix isolates per-session state but does not restrict filesystem permissions; avoid storing sensitive data in the marker file.

Display Format

═══ Structured Dev Cycle ═══════════════════════════
 [■■□□□□] Stage 2/6: Verify Plan
 Files planned: 5 | Risks identified: 2
═════════════════════════════════════════════════════