Epic: Codex effectiveness improvements

[rjmurillo-bot]

Epic: Codex Effectiveness Improvements

Goal

Make Codex as effective as Claude Code by enforcing session-start gates, memory-first workflows, skill-first GitHub operations, and by reducing startup context load without losing capability.

Outcomes

• Verification-based protocol enforcement (no self-reported checklists).
• Memory-first workflows with evidence (load memory-index + task memories).
• Skill-first GitHub operations; raw gh avoided when skills exist.
• 10-15% reduction in baseline context without functional regressions.

Scope

• Codex session-start gate script and integration guidance.
• Progressive disclosure for skills/docs (references/ pattern).
• Context source de-duplication and token budget tracking.
• Environment preflight checks where needed (sqlite3, pwsh, node).

Out of Scope

• Cross-repo policy changes outside ai-agents.
• Large refactors not tied to Codex workflow effectiveness.

Backlog (from .agents/planning/codex-effectiveness-backlog.md)

P0

1. Codex session-start gate (PowerShell)
2. Memory-first verification enforcement
3. Skill-first GitHub operations
4. Protocol checklist alignment for Codex

P1

5. Progressive disclosure for Codex skills and docs
6. Context de-duplication
7. Token budget policy and measurement

P2

8. Direct SQLite export parity for memory backups
9. Environment preflight checks
10. Command vs skill taxonomy enforcement

Success Metrics

• 100% session protocol compliance without manual reminders
• Startup tokens reduced by at least 10-15%
• Zero raw gh usage when skills exist
• Zero session logs missing required evidence

References

• .agents/planning/codex-effectiveness-backlog.md
• scripts/Invoke-CodexSessionStartGate.ps1
• .agents/planning/codex-context-optimization-plan.md

[traycerai]

Plan

Observations

The repository has a sophisticated agent orchestration system with Claude Code as the primary platform. It features verification-based protocol enforcement through SESSION-PROTOCOL.md, skill-based GitHub operations in .claude/skills/, memory management via Serena MCP, and validation scripts (file:scripts/Validate-SessionJson.ps1, file:scripts/Check-SkillExists.ps1, file:scripts/Detect-SkillViolation.ps1). The epic targets OpenAI Codex (GitHub Copilot Pro+ VS Code extension), which currently lacks the same enforcement mechanisms that make Claude Code effective. The infrastructure exists but needs Codex-specific adaptations. The automation focus indicates that enforcement mechanisms should be integrated into CI/CD workflows and pre-commit hooks to eliminate manual compliance steps.

Approach

The plan follows a phased approach mirroring the proven Claude Code patterns: create a PowerShell session-start gate script for Codex, establish memory-first verification enforcement, implement skill-first GitHub operation checks, and optimize context loading through progressive disclosure. This leverages existing validation infrastructure (file:scripts/Validate-SessionJson.ps1, file:scripts/Check-SkillExists.ps1) while creating Codex-specific entry points. The approach prioritizes P0 items (session gates, memory-first, skill-first) before P1 optimization work, ensuring immediate effectiveness improvements without over-engineering. Automation is embedded throughout: pre-commit hooks enforce skill-first operations, CI workflows validate protocol compliance, and session-start gates block non-compliant work before it begins. This eliminates manual checklists in favor of automated verification.

Implementation Plan

Phase 1: Foundation Documents (P0 - Priority 1)

1.1 Create Codex Effectiveness Backlog

File: file:.agents/planning/codex-effectiveness-backlog.md

Create the backlog document referenced in the epic with structured task breakdown:

• P0 Tasks: Session-start gate, memory-first verification, skill-first GitHub operations, protocol checklist alignment
• P1 Tasks: Progressive disclosure, context de-duplication, token budget policy
• P2 Tasks: SQLite export parity, environment preflight checks, command vs skill taxonomy
• Include acceptance criteria for each task
• Reference existing patterns from file:.agents/SESSION-PROTOCOL.md
• Link to related ADRs (file:.agents/architecture/ADR-033-routing-level-enforcement-gates.md)

1.2 Create Context Optimization Plan

File: file:.agents/planning/codex-context-optimization-plan.md

Document the strategy for 10-15% context reduction:

• Baseline measurement: Use file:scripts/Validate-TokenBudget.ps1 patterns to measure current Codex startup context
• Progressive disclosure strategy: Implement references/ pattern for skills and docs (load on-demand vs upfront)
• De-duplication targets: Identify redundant content between CLAUDE.md, AGENTS.md, CRITICAL-CONTEXT.md
• Token budget tracking: Extend file:scripts/Validate-TokenBudget.ps1 for Codex-specific measurements
• Success metrics: Define 10-15% reduction baseline and measurement methodology

Phase 2: Session-Start Gate Script (P0 - Priority 2)

2.1 Create Codex Session-Start Gate Script

File: file:scripts/Invoke-CodexSessionStartGate.ps1

Implement PowerShell script following ADR-005 (PowerShell-only) with these verification gates:

Gate 1: Memory-First Verification

• Check if file:.serena/memories/memory-index.md has been read
• Verify task-relevant memories loaded based on keywords
• Block execution until memory evidence exists
• Output structured JSON with pass/fail status

Gate 2: Skill Availability Check

• Reuse logic from file:scripts/Check-SkillExists.ps1
• List available GitHub skills in file:.claude/skills/github/scripts/
• Verify usage-mandatory memory loaded
• Document skill inventory for session

Gate 3: Session Log Verification

• Check for today's session log in file:.agents/sessions/
• Validate using file:scripts/Validate-SessionJson.ps1 patterns
• Block work until session log exists and validates
• Provide actionable error messages

Gate 4: Branch Verification

• Execute git branch --show-current
• Verify not on main/master
• Document branch in session context
• Block commits on wrong branch

Exit Codes (following ADR-032 patterns):

• 0: All gates passed
• 1: Logic error in gate script
• 2: Gate condition not met (blocking)
• 3: External dependency failure

Automation Integration:

• Callable from pre-commit hooks (exit code driven)
• Callable from CI workflows (JSON output for reporting)
• Callable from VS Code extension hooks (if available)
• Supports dry-run mode for validation without blocking

2.2 Create Pester Tests

File: file:scripts/tests/Invoke-CodexSessionStartGate.Tests.ps1

Test coverage for all gate scenarios:

• Memory-first gate: pass/fail conditions
• Skill availability gate: directory exists/missing
• Session log gate: valid/invalid/missing
• Branch verification gate: feature branch/main branch
• Exit code validation for each scenario
• Dry-run mode validation

Phase 3: Protocol Checklist Alignment (P0 - Priority 3)

3.1 Create Codex-Specific Protocol Document

File: file:.agents/CODEX-PROTOCOL.md

Adapt file:.agents/SESSION-PROTOCOL.md for Codex platform:

Session Start Checklist (Codex-specific):

• Execute pwsh scripts/Invoke-CodexSessionStartGate.ps1 (BLOCKING)
• Read file:.agents/HANDOFF.md (read-only reference)
• Load memory-index and task-relevant memories (BLOCKING)
• List available skills from file:.claude/skills/github/scripts/
• Create session log using file:.claude/skills/session-init/scripts/New-SessionLog.ps1
• Verify branch with git branch --show-current

Session End Checklist (Codex-specific):

• Complete session log with outcomes
• Update Serena memory with cross-session context
• Run npx markdownlint-cli2 --fix "**/*.md"
• Execute skill violation check: pwsh scripts/Detect-SkillViolation.ps1 -StagedOnly
• Validate session: pwsh scripts/Validate-SessionJson.ps1 -SessionPath [log]
• Commit all changes including file:.agents/ and file:.serena/

Differences from Claude Code:

• No MCP hooks available (Codex limitation)
• Manual gate execution required
• Explicit skill violation checks needed
• Token budget more critical (no auto-context management)

3.2 Update Entry Point Documentation

File: file:AGENTS.md

Add Codex-specific section after Claude Code section:

• Reference file:.agents/CODEX-PROTOCOL.md
• Link to file:scripts/Invoke-CodexSessionStartGate.ps1
• Document manual gate execution workflow
• Highlight differences from Claude Code automation
• Provide quick-start commands for Codex users

Phase 4: Skill-First Enforcement (P0 - Priority 4)

4.1 Enhance Skill Violation Detection

File: file:scripts/Detect-SkillViolation.ps1 (enhance existing)

Add Codex-specific detection patterns:

• Detect raw gh commands in Codex task descriptions
• Check for inline GitHub API calls vs skill usage
• Scan for curl/wget when GitHub skills exist
• Report capability gaps with actionable remediation
• Generate skill usage report for session logs

Output Format:

• JSON structure with violations array
• File path, line number, pattern matched
• Suggested skill to use instead
• Link to skill documentation

4.2 Create Skill-First Verification Script

File: file:scripts/Validate-SkillFirst.ps1

New script for pre-commit validation:

• Parse staged files for GitHub operations
• Cross-reference with available skills in file:.claude/skills/github/scripts/
• Block commit if raw commands detected when skills exist
• Provide skill usage guidance
• Exit code 0 (pass) or 1 (violations found)

Automation Integration:

• Enforce via pre-commit hook (blocking)
• Validate in CI pipeline (report violations)
• Provide actionable feedback in PR comments
• Track violation trends in metrics dashboard

Integration:

• Add to pre-commit hook workflow
• Include in file:scripts/Invoke-CodexSessionStartGate.ps1
• Reference in file:.agents/CODEX-PROTOCOL.md

Phase 5: Progressive Disclosure (P1 - Priority 5)

5.1 Implement References Pattern for Skills

Directory Structure:

.claude/skills/github/
├── SKILL.md (overview only)
├── references/
│   ├── pr-operations.md
│   ├── issue-operations.md
│   ├── api-patterns.md
│   └── error-handling.md
└── scripts/ (existing)

Pattern:

• Main SKILL.md: 200-300 tokens (overview, triggers, quick examples)
• Detailed docs: Move to references/ subdirectory
• Load on-demand: "See references/pr-operations.md for details"
• Reduce upfront context by 40-50% per skill

5.2 Optimize Memory Index Loading

File: file:.serena/memories/memory-index.md (enhance existing)

Implement lazy loading strategy:

• Tier 1 (Always Load): session-init, protocol, project-overview
• Tier 2 (Keyword Match): Load only when task keywords match
• Tier 3 (On-Demand): Reference only, load if explicitly needed

Token Savings:

• Current: ~50 memories loaded upfront (~15K tokens)
• Target: ~10 memories loaded upfront (~3K tokens)
• Savings: ~12K tokens (80% reduction in memory context)

5.3 Create Context Budget Tracking

File: file:scripts/Measure-CodexContext.ps1

New script to measure Codex context usage:

• Parse Codex session transcripts
• Calculate token usage by category (docs, memories, skills, code)
• Compare against baseline and target budgets
• Generate optimization recommendations
• Output JSON report for tracking

Metrics:

• Startup context tokens (target: 10-15% reduction)
• Memory loading efficiency (tier 1 vs tier 2/3 ratio)
• Skill documentation tokens (before/after progressive disclosure)
• Session-to-session context growth rate

Phase 6: Context De-duplication (P1 - Priority 6)

6.1 Consolidate Entry Point Documents

Files to optimize:

• file:CLAUDE.md (currently ~80 lines)
• file:AGENTS.md (currently ~1600 lines)
• file:CRITICAL-CONTEXT.md (currently ~60 lines)

De-duplication strategy:

CRITICAL-CONTEXT.md (keep as-is):

• Auto-loaded via @import in CLAUDE.md
• Blocking gates and constraints only
• No duplication with other docs

CLAUDE.md (reduce to ~50 lines):

• Remove session protocol details (link to file:.agents/SESSION-PROTOCOL.md)
• Remove constraint details (link to file:.agents/governance/PROJECT-CONSTRAINTS.md)
• Keep only: Serena init commands, session log path, validation command
• Add Codex reference link

AGENTS.md (restructure):

• Move detailed protocol to file:.agents/SESSION-PROTOCOL.md (already done)
• Move constraints to file:.agents/governance/PROJECT-CONSTRAINTS.md (already done)
• Keep: Agent catalog, workflow patterns, memory system overview
• Add progressive disclosure: "See references/ for details"

Token Savings: ~2-3K tokens (15-20% of startup context)

6.2 Create Source-of-Truth Index

File: file:.agents/governance/DOCUMENTATION-INDEX.md

Single index mapping topics to canonical sources:

Topic	Canonical Source	Summary Location
Session Protocol	file:.agents/SESSION-PROTOCOL.md	file:CRITICAL-CONTEXT.md
Codex Protocol	file:.agents/CODEX-PROTOCOL.md	file:AGENTS.md
Constraints	file:.agents/governance/PROJECT-CONSTRAINTS.md	file:CRITICAL-CONTEXT.md
Skills	file:.claude/skills/*/SKILL.md	file:AGENTS.md
Memory System	file:.serena/memories/memory-index.md	file:AGENTS.md
Validation	file:scripts/Validate-*.ps1	file:.agents/SESSION-PROTOCOL.md

Purpose: Prevent duplication by providing clear ownership and reference paths

Phase 7: Token Budget Policy (P1 - Priority 7)

7.1 Define Token Budget Policy

File: file:.agents/governance/TOKEN-BUDGET-POLICY.md

Establish token budget standards:

Budget Allocations:

• Startup context: 15K tokens max (target: 12-13K after optimization)
• Session logs: 2K tokens max per session
• Memory index: 1K tokens (tier 1 only)
• Skills documentation: 500 tokens per skill (main SKILL.md only)
• HANDOFF.md: 5K tokens max (existing policy from file:scripts/Validate-TokenBudget.ps1)

Enforcement:

• Pre-commit validation using file:scripts/Validate-TokenBudget.ps1 patterns
• CI checks for documentation size
• Session log validation rejects oversized logs
• Quarterly audits of token usage trends

Measurement:

• Extend file:scripts/Validate-TokenBudget.ps1 for all budget categories
• Add to file:scripts/Measure-CodexContext.ps1 output
• Track in session logs under "Context Budget" section

7.2 Create Budget Validation Script

File: file:scripts/Validate-ContextBudget.ps1

Comprehensive budget validation:

• Check all documentation files against budget limits
• Validate memory index tier 1 size
• Verify skill SKILL.md files under 500 tokens
• Report violations with remediation guidance
• Exit code 0 (pass) or 1 (over budget)

Integration:

• Add to pre-commit hooks
• Include in CI validation workflow
• Reference in file:.agents/CODEX-PROTOCOL.md

Phase 8: Environment Preflight Checks (P2 - Priority 8)

8.1 Create Environment Validation Script

File: file:scripts/Test-CodexEnvironment.ps1

Validate Codex environment prerequisites:

Checks:

• PowerShell 7.4+ installed ($PSVersionTable.PSVersion)
• Git available and configured
• GitHub CLI (gh) installed and authenticated
• Node.js available for markdownlint
• SQLite3 available (for memory backups)
• Serena MCP configured (if applicable)

Output:

• JSON report with pass/fail per check
• Actionable remediation steps for failures
• Environment summary for session logs
• Exit code 0 (all pass) or 1 (any failures)

Usage:

• Run at session start via file:scripts/Invoke-CodexSessionStartGate.ps1
• Include in file:.agents/CODEX-PROTOCOL.md checklist
• Add to troubleshooting documentation

Phase 9: Integration and Documentation (All Priorities)

9.1 Update Session-Init Skill for Codex

File: file:.claude/skills/session-init/SKILL.md (enhance existing)

Add Codex-specific guidance:

• Document manual gate execution workflow
• Add Codex platform detection logic
• Provide Codex-specific session log template
• Reference file:scripts/Invoke-CodexSessionStartGate.ps1
• Include troubleshooting for common Codex issues

9.2 Create Codex Quick Start Guide

File: file:.agents/CODEX-QUICKSTART.md

Onboarding document for Codex users:

Contents:

• Installation prerequisites (PowerShell, gh, node)
• First session workflow with gate execution
• Memory-first pattern examples
• Skill-first operation examples
• Common pitfalls and solutions
• Comparison with Claude Code workflow

Format:

• Step-by-step instructions with commands
• Screenshots/examples of expected output
• Links to detailed documentation
• Troubleshooting section

9.3 Create Pre-Commit Hook Configuration

File: file:.husky/pre-commit

Automated enforcement hook:

• Execute file:scripts/Invoke-CodexSessionStartGate.ps1 (dry-run mode)
• Run file:scripts/Validate-SkillFirst.ps1 on staged files
• Execute file:scripts/Validate-ContextBudget.ps1 on documentation changes
• Run file:scripts/Validate-SessionJson.ps1 on session log changes
• Provide clear error messages with remediation steps
• Exit with code 1 if any validation fails (blocking commit)

Configuration:

• Make hook executable: chmod +x .husky/pre-commit
• Document in file:.agents/CODEX-PROTOCOL.md
• Include bypass instructions for emergency commits (with audit trail)

9.4 Update CI Validation Workflows

File: file:.github/workflows/session-validation.yml (enhance existing)

Add Codex-specific validation:

• Run file:scripts/Invoke-CodexSessionStartGate.ps1 in dry-run mode
• Validate file:.agents/CODEX-PROTOCOL.md compliance
• Check skill-first violations with file:scripts/Detect-SkillViolation.ps1
• Measure context budget with file:scripts/Validate-ContextBudget.ps1
• Report metrics to PR comments
• Block merge if any validation fails (enforcement)

Phase 10: Success Metrics and Monitoring (Ongoing)

10.1 Define Success Metrics

Track in session logs and CI:

Protocol Compliance:

• 100% session protocol compliance (target: no manual reminders)
• 0% raw gh usage when skills exist
• 100% memory-first workflow adoption

Context Optimization:

• 10-15% reduction in startup tokens (baseline → target)
• 80% reduction in upfront memory loading (tier 1 only)
• 40-50% reduction in skill documentation tokens

Quality Metrics:

• 0% session logs missing required evidence
• 100% skill-first validation pass rate
• 0% wrong-branch commits (branch verification gate)

10.2 Create Metrics Dashboard

File: file:.agents/metrics/codex-effectiveness-dashboard.md

Living document tracking progress:

• Weekly metrics snapshots
• Trend analysis (improving/degrading)
• Violation reports with root cause analysis
• Optimization opportunities identified
• Success stories and learnings

Update Cadence: Weekly during implementation, monthly after stabilization

Workflow Diagram

sequenceDiagram
    participant User
    participant Codex
    participant Gate as Session-Start Gate
    participant Memory as Memory System
    participant Skills as Skill Registry
    participant Session as Session Log

    User->>Codex: Start new task
    Codex->>Gate: Execute Invoke-CodexSessionStartGate.ps1
    
    Gate->>Memory: Check memory-index loaded
    Memory-->>Gate: Memory evidence
    
    Gate->>Skills: List available skills
    Skills-->>Gate: Skill inventory
    
    Gate->>Session: Verify session log exists
    Session-->>Gate: Validation result
    
    Gate->>Codex: All gates passed ✓
    
    Codex->>Memory: Load task-relevant memories
    Codex->>Skills: Use skill for GitHub operation
    Codex->>Session: Document work in session log
    
    Codex->>Gate: Pre-commit validation
    Gate->>Skills: Check skill-first compliance
    Gate->>Session: Validate session log
    Gate-->>Codex: Commit approved ✓

Loading

Implementation Sequence

Phase	Priority	Estimated Effort	Dependencies
1. Foundation Documents	P0	2-3 hours	None
2. Session-Start Gate	P0	4-6 hours	Phase 1
3. Protocol Alignment	P0	3-4 hours	Phase 2
4. Skill-First Enforcement	P0	3-4 hours	Phase 2
5. Progressive Disclosure	P1	4-6 hours	Phase 1-4 complete
6. Context De-duplication	P1	3-4 hours	Phase 5
7. Token Budget Policy	P1	2-3 hours	Phase 6
8. Environment Preflight	P2	2-3 hours	Phase 2
9. Integration & Docs	All	4-6 hours	Phase 1-8
10. Metrics & Monitoring	Ongoing	1-2 hours/week	Phase 9

Total Estimated Effort: 28-41 hours for P0-P1 items, plus ongoing monitoring

Key Success Factors

1. Leverage Existing Infrastructure: Reuse file:scripts/Validate-SessionJson.ps1, file:scripts/Check-SkillExists.ps1, file:scripts/Detect-SkillViolation.ps1 patterns
2. Follow ADR-005: All scripts in PowerShell (no bash/Python)
3. Verification-Based Enforcement: Mirror Serena initialization pattern (tool output required)
4. Progressive Disclosure: Implement references/ pattern to reduce upfront context
5. Measure Everything: Token budgets, compliance rates, violation patterns
6. Codex-Specific Adaptations: Manual gate execution (no MCP hooks), explicit validation steps
7. Automation-First Design: Pre-commit hooks and CI workflows enforce compliance without manual steps
8. Exit Code Driven: All validation scripts use standard exit codes (0=pass, 1=fail) for hook/CI integration
9. Dry-Run Capability: All enforcement scripts support dry-run mode for testing and CI reporting

Import In IDE

🤖 Prompt for AI Agents

## Observations

The repository has a sophisticated agent orchestration system with Claude Code as the primary platform. It features verification-based protocol enforcement through SESSION-PROTOCOL.md, skill-based GitHub operations in `.claude/skills/`, memory management via Serena MCP, and validation scripts (file:scripts/Validate-SessionJson.ps1, file:scripts/Check-SkillExists.ps1, file:scripts/Detect-SkillViolation.ps1). The epic targets OpenAI Codex (GitHub Copilot Pro+ VS Code extension), which currently lacks the same enforcement mechanisms that make Claude Code effective. The infrastructure exists but needs Codex-specific adaptations. The automation focus indicates that enforcement mechanisms should be integrated into CI/CD workflows and pre-commit hooks to eliminate manual compliance steps.

## Approach

The plan follows a phased approach mirroring the proven Claude Code patterns: create a PowerShell session-start gate script for Codex, establish memory-first verification enforcement, implement skill-first GitHub operation checks, and optimize context loading through progressive disclosure. This leverages existing validation infrastructure (file:scripts/Validate-SessionJson.ps1, file:scripts/Check-SkillExists.ps1) while creating Codex-specific entry points. The approach prioritizes P0 items (session gates, memory-first, skill-first) before P1 optimization work, ensuring immediate effectiveness improvements without over-engineering. Automation is embedded throughout: pre-commit hooks enforce skill-first operations, CI workflows validate protocol compliance, and session-start gates block non-compliant work before it begins. This eliminates manual checklists in favor of automated verification.

## Implementation Plan

### Phase 1: Foundation Documents (P0 - Priority 1)

#### 1.1 Create Codex Effectiveness Backlog

**File**: file:.agents/planning/codex-effectiveness-backlog.md

Create the backlog document referenced in the epic with structured task breakdown:

- **P0 Tasks**: Session-start gate, memory-first verification, skill-first GitHub operations, protocol checklist alignment
- **P1 Tasks**: Progressive disclosure, context de-duplication, token budget policy
- **P2 Tasks**: SQLite export parity, environment preflight checks, command vs skill taxonomy
- Include acceptance criteria for each task
- Reference existing patterns from file:.agents/SESSION-PROTOCOL.md
- Link to related ADRs (file:.agents/architecture/ADR-033-routing-level-enforcement-gates.md)

#### 1.2 Create Context Optimization Plan

**File**: file:.agents/planning/codex-context-optimization-plan.md

Document the strategy for 10-15% context reduction:

- **Baseline measurement**: Use file:scripts/Validate-TokenBudget.ps1 patterns to measure current Codex startup context
- **Progressive disclosure strategy**: Implement references/ pattern for skills and docs (load on-demand vs upfront)
- **De-duplication targets**: Identify redundant content between CLAUDE.md, AGENTS.md, CRITICAL-CONTEXT.md
- **Token budget tracking**: Extend file:scripts/Validate-TokenBudget.ps1 for Codex-specific measurements
- **Success metrics**: Define 10-15% reduction baseline and measurement methodology

### Phase 2: Session-Start Gate Script (P0 - Priority 2)

#### 2.1 Create Codex Session-Start Gate Script

**File**: file:scripts/Invoke-CodexSessionStartGate.ps1

Implement PowerShell script following ADR-005 (PowerShell-only) with these verification gates:

**Gate 1: Memory-First Verification**
- Check if file:.serena/memories/memory-index.md has been read
- Verify task-relevant memories loaded based on keywords
- Block execution until memory evidence exists
- Output structured JSON with pass/fail status

**Gate 2: Skill Availability Check**
- Reuse logic from file:scripts/Check-SkillExists.ps1
- List available GitHub skills in file:.claude/skills/github/scripts/
- Verify usage-mandatory memory loaded
- Document skill inventory for session

**Gate 3: Session Log Verification**
- Check for today's session log in file:.agents/sessions/
- Validate using file:scripts/Validate-SessionJson.ps1 patterns
- Block work until session log exists and validates
- Provide actionable error messages

**Gate 4: Branch Verification**
- Execute `git branch --show-current`
- Verify not on main/master
- Document branch in session context
- Block commits on wrong branch

**Exit Codes** (following ADR-032 patterns):
- 0: All gates passed
- 1: Logic error in gate script
- 2: Gate condition not met (blocking)
- 3: External dependency failure

**Automation Integration**:
- Callable from pre-commit hooks (exit code driven)
- Callable from CI workflows (JSON output for reporting)
- Callable from VS Code extension hooks (if available)
- Supports dry-run mode for validation without blocking

#### 2.2 Create Pester Tests

**File**: file:scripts/tests/Invoke-CodexSessionStartGate.Tests.ps1

Test coverage for all gate scenarios:
- Memory-first gate: pass/fail conditions
- Skill availability gate: directory exists/missing
- Session log gate: valid/invalid/missing
- Branch verification gate: feature branch/main branch
- Exit code validation for each scenario
- Dry-run mode validation

### Phase 3: Protocol Checklist Alignment (P0 - Priority 3)

#### 3.1 Create Codex-Specific Protocol Document

**File**: file:.agents/CODEX-PROTOCOL.md

Adapt file:.agents/SESSION-PROTOCOL.md for Codex platform:

**Session Start Checklist** (Codex-specific):
- Execute `pwsh scripts/Invoke-CodexSessionStartGate.ps1` (BLOCKING)
- Read file:.agents/HANDOFF.md (read-only reference)
- Load memory-index and task-relevant memories (BLOCKING)
- List available skills from file:.claude/skills/github/scripts/
- Create session log using file:.claude/skills/session-init/scripts/New-SessionLog.ps1
- Verify branch with `git branch --show-current`

**Session End Checklist** (Codex-specific):
- Complete session log with outcomes
- Update Serena memory with cross-session context
- Run `npx markdownlint-cli2 --fix "**/*.md"`
- Execute skill violation check: `pwsh scripts/Detect-SkillViolation.ps1 -StagedOnly`
- Validate session: `pwsh scripts/Validate-SessionJson.ps1 -SessionPath [log]`
- Commit all changes including file:.agents/ and file:.serena/

**Differences from Claude Code**:
- No MCP hooks available (Codex limitation)
- Manual gate execution required
- Explicit skill violation checks needed
- Token budget more critical (no auto-context management)

#### 3.2 Update Entry Point Documentation

**File**: file:AGENTS.md

Add Codex-specific section after Claude Code section:

- Reference file:.agents/CODEX-PROTOCOL.md
- Link to file:scripts/Invoke-CodexSessionStartGate.ps1
- Document manual gate execution workflow
- Highlight differences from Claude Code automation
- Provide quick-start commands for Codex users

### Phase 4: Skill-First Enforcement (P0 - Priority 4)

#### 4.1 Enhance Skill Violation Detection

**File**: file:scripts/Detect-SkillViolation.ps1 (enhance existing)

Add Codex-specific detection patterns:

- Detect raw `gh` commands in Codex task descriptions
- Check for inline GitHub API calls vs skill usage
- Scan for curl/wget when GitHub skills exist
- Report capability gaps with actionable remediation
- Generate skill usage report for session logs

**Output Format**:
- JSON structure with violations array
- File path, line number, pattern matched
- Suggested skill to use instead
- Link to skill documentation

#### 4.2 Create Skill-First Verification Script

**File**: file:scripts/Validate-SkillFirst.ps1

New script for pre-commit validation:

- Parse staged files for GitHub operations
- Cross-reference with available skills in file:.claude/skills/github/scripts/
- Block commit if raw commands detected when skills exist
- Provide skill usage guidance
- Exit code 0 (pass) or 1 (violations found)

**Automation Integration**:
- Enforce via pre-commit hook (blocking)
- Validate in CI pipeline (report violations)
- Provide actionable feedback in PR comments
- Track violation trends in metrics dashboard

**Integration**:
- Add to pre-commit hook workflow
- Include in file:scripts/Invoke-CodexSessionStartGate.ps1
- Reference in file:.agents/CODEX-PROTOCOL.md

### Phase 5: Progressive Disclosure (P1 - Priority 5)

#### 5.1 Implement References Pattern for Skills

**Directory Structure**:
```
.claude/skills/github/
├── SKILL.md (overview only)
├── references/
│   ├── pr-operations.md
│   ├── issue-operations.md
│   ├── api-patterns.md
│   └── error-handling.md
└── scripts/ (existing)
```

**Pattern**:
- Main SKILL.md: 200-300 tokens (overview, triggers, quick examples)
- Detailed docs: Move to references/ subdirectory
- Load on-demand: "See references/pr-operations.md for details"
- Reduce upfront context by 40-50% per skill

#### 5.2 Optimize Memory Index Loading

**File**: file:.serena/memories/memory-index.md (enhance existing)

Implement lazy loading strategy:

- **Tier 1 (Always Load)**: session-init, protocol, project-overview
- **Tier 2 (Keyword Match)**: Load only when task keywords match
- **Tier 3 (On-Demand)**: Reference only, load if explicitly needed

**Token Savings**:
- Current: ~50 memories loaded upfront (~15K tokens)
- Target: ~10 memories loaded upfront (~3K tokens)
- Savings: ~12K tokens (80% reduction in memory context)

#### 5.3 Create Context Budget Tracking

**File**: file:scripts/Measure-CodexContext.ps1

New script to measure Codex context usage:

- Parse Codex session transcripts
- Calculate token usage by category (docs, memories, skills, code)
- Compare against baseline and target budgets
- Generate optimization recommendations
- Output JSON report for tracking

**Metrics**:
- Startup context tokens (target: 10-15% reduction)
- Memory loading efficiency (tier 1 vs tier 2/3 ratio)
- Skill documentation tokens (before/after progressive disclosure)
- Session-to-session context growth rate

### Phase 6: Context De-duplication (P1 - Priority 6)

#### 6.1 Consolidate Entry Point Documents

**Files to optimize**:
- file:CLAUDE.md (currently ~80 lines)
- file:AGENTS.md (currently ~1600 lines)
- file:CRITICAL-CONTEXT.md (currently ~60 lines)

**De-duplication strategy**:

**CRITICAL-CONTEXT.md** (keep as-is):
- Auto-loaded via @import in CLAUDE.md
- Blocking gates and constraints only
- No duplication with other docs

**CLAUDE.md** (reduce to ~50 lines):
- Remove session protocol details (link to file:.agents/SESSION-PROTOCOL.md)
- Remove constraint details (link to file:.agents/governance/PROJECT-CONSTRAINTS.md)
- Keep only: Serena init commands, session log path, validation command
- Add Codex reference link

**AGENTS.md** (restructure):
- Move detailed protocol to file:.agents/SESSION-PROTOCOL.md (already done)
- Move constraints to file:.agents/governance/PROJECT-CONSTRAINTS.md (already done)
- Keep: Agent catalog, workflow patterns, memory system overview
- Add progressive disclosure: "See references/ for details"

**Token Savings**: ~2-3K tokens (15-20% of startup context)

#### 6.2 Create Source-of-Truth Index

**File**: file:.agents/governance/DOCUMENTATION-INDEX.md

Single index mapping topics to canonical sources:

| Topic | Canonical Source | Summary Location |
|-------|------------------|------------------|
| Session Protocol | file:.agents/SESSION-PROTOCOL.md | file:CRITICAL-CONTEXT.md |
| Codex Protocol | file:.agents/CODEX-PROTOCOL.md | file:AGENTS.md |
| Constraints | file:.agents/governance/PROJECT-CONSTRAINTS.md | file:CRITICAL-CONTEXT.md |
| Skills | file:.claude/skills/*/SKILL.md | file:AGENTS.md |
| Memory System | file:.serena/memories/memory-index.md | file:AGENTS.md |
| Validation | file:scripts/Validate-*.ps1 | file:.agents/SESSION-PROTOCOL.md |

**Purpose**: Prevent duplication by providing clear ownership and reference paths

### Phase 7: Token Budget Policy (P1 - Priority 7)

#### 7.1 Define Token Budget Policy

**File**: file:.agents/governance/TOKEN-BUDGET-POLICY.md

Establish token budget standards:

**Budget Allocations**:
- Startup context: 15K tokens max (target: 12-13K after optimization)
- Session logs: 2K tokens max per session
- Memory index: 1K tokens (tier 1 only)
- Skills documentation: 500 tokens per skill (main SKILL.md only)
- HANDOFF.md: 5K tokens max (existing policy from file:scripts/Validate-TokenBudget.ps1)

**Enforcement**:
- Pre-commit validation using file:scripts/Validate-TokenBudget.ps1 patterns
- CI checks for documentation size
- Session log validation rejects oversized logs
- Quarterly audits of token usage trends

**Measurement**:
- Extend file:scripts/Validate-TokenBudget.ps1 for all budget categories
- Add to file:scripts/Measure-CodexContext.ps1 output
- Track in session logs under "Context Budget" section

#### 7.2 Create Budget Validation Script

**File**: file:scripts/Validate-ContextBudget.ps1

Comprehensive budget validation:

- Check all documentation files against budget limits
- Validate memory index tier 1 size
- Verify skill SKILL.md files under 500 tokens
- Report violations with remediation guidance
- Exit code 0 (pass) or 1 (over budget)

**Integration**:
- Add to pre-commit hooks
- Include in CI validation workflow
- Reference in file:.agents/CODEX-PROTOCOL.md

### Phase 8: Environment Preflight Checks (P2 - Priority 8)

#### 8.1 Create Environment Validation Script

**File**: file:scripts/Test-CodexEnvironment.ps1

Validate Codex environment prerequisites:

**Checks**:
- PowerShell 7.4+ installed (`$PSVersionTable.PSVersion`)
- Git available and configured
- GitHub CLI (`gh`) installed and authenticated
- Node.js available for markdownlint
- SQLite3 available (for memory backups)
- Serena MCP configured (if applicable)

**Output**:
- JSON report with pass/fail per check
- Actionable remediation steps for failures
- Environment summary for session logs
- Exit code 0 (all pass) or 1 (any failures)

**Usage**:
- Run at session start via file:scripts/Invoke-CodexSessionStartGate.ps1
- Include in file:.agents/CODEX-PROTOCOL.md checklist
- Add to troubleshooting documentation

### Phase 9: Integration and Documentation (All Priorities)

#### 9.1 Update Session-Init Skill for Codex

**File**: file:.claude/skills/session-init/SKILL.md (enhance existing)

Add Codex-specific guidance:

- Document manual gate execution workflow
- Add Codex platform detection logic
- Provide Codex-specific session log template
- Reference file:scripts/Invoke-CodexSessionStartGate.ps1
- Include troubleshooting for common Codex issues

#### 9.2 Create Codex Quick Start Guide

**File**: file:.agents/CODEX-QUICKSTART.md

Onboarding document for Codex users:

**Contents**:
- Installation prerequisites (PowerShell, gh, node)
- First session workflow with gate execution
- Memory-first pattern examples
- Skill-first operation examples
- Common pitfalls and solutions
- Comparison with Claude Code workflow

**Format**:
- Step-by-step instructions with commands
- Screenshots/examples of expected output
- Links to detailed documentation
- Troubleshooting section

#### 9.3 Create Pre-Commit Hook Configuration

**File**: file:.husky/pre-commit

Automated enforcement hook:

- Execute file:scripts/Invoke-CodexSessionStartGate.ps1 (dry-run mode)
- Run file:scripts/Validate-SkillFirst.ps1 on staged files
- Execute file:scripts/Validate-ContextBudget.ps1 on documentation changes
- Run file:scripts/Validate-SessionJson.ps1 on session log changes
- Provide clear error messages with remediation steps
- Exit with code 1 if any validation fails (blocking commit)

**Configuration**:
- Make hook executable: `chmod +x .husky/pre-commit`
- Document in file:.agents/CODEX-PROTOCOL.md
- Include bypass instructions for emergency commits (with audit trail)

#### 9.4 Update CI Validation Workflows

**File**: file:.github/workflows/session-validation.yml (enhance existing)

Add Codex-specific validation:

- Run file:scripts/Invoke-CodexSessionStartGate.ps1 in dry-run mode
- Validate file:.agents/CODEX-PROTOCOL.md compliance
- Check skill-first violations with file:scripts/Detect-SkillViolation.ps1
- Measure context budget with file:scripts/Validate-ContextBudget.ps1
- Report metrics to PR comments
- Block merge if any validation fails (enforcement)

### Phase 10: Success Metrics and Monitoring (Ongoing)

#### 10.1 Define Success Metrics

Track in session logs and CI:

**Protocol Compliance**:
- 100% session protocol compliance (target: no manual reminders)
- 0% raw `gh` usage when skills exist
- 100% memory-first workflow adoption

**Context Optimization**:
- 10-15% reduction in startup tokens (baseline → target)
- 80% reduction in upfront memory loading (tier 1 only)
- 40-50% reduction in skill documentation tokens

**Quality Metrics**:
- 0% session logs missing required evidence
- 100% skill-first validation pass rate
- 0% wrong-branch commits (branch verification gate)

#### 10.2 Create Metrics Dashboard

**File**: file:.agents/metrics/codex-effectiveness-dashboard.md

Living document tracking progress:

- Weekly metrics snapshots
- Trend analysis (improving/degrading)
- Violation reports with root cause analysis
- Optimization opportunities identified
- Success stories and learnings

**Update Cadence**: Weekly during implementation, monthly after stabilization

## Workflow Diagram

```mermaid
sequenceDiagram
    participant User
    participant Codex
    participant Gate as Session-Start Gate
    participant Memory as Memory System
    participant Skills as Skill Registry
    participant Session as Session Log

    User->>Codex: Start new task
    Codex->>Gate: Execute Invoke-CodexSessionStartGate.ps1
    
    Gate->>Memory: Check memory-index loaded
    Memory-->>Gate: Memory evidence
    
    Gate->>Skills: List available skills
    Skills-->>Gate: Skill inventory
    
    Gate->>Session: Verify session log exists
    Session-->>Gate: Validation result
    
    Gate->>Codex: All gates passed ✓
    
    Codex->>Memory: Load task-relevant memories
    Codex->>Skills: Use skill for GitHub operation
    Codex->>Session: Document work in session log
    
    Codex->>Gate: Pre-commit validation
    Gate->>Skills: Check skill-first compliance
    Gate->>Session: Validate session log
    Gate-->>Codex: Commit approved ✓
```

## Implementation Sequence

| Phase | Priority | Estimated Effort | Dependencies |
|-------|----------|------------------|--------------|
| 1. Foundation Documents | P0 | 2-3 hours | None |
| 2. Session-Start Gate | P0 | 4-6 hours | Phase 1 |
| 3. Protocol Alignment | P0 | 3-4 hours | Phase 2 |
| 4. Skill-First Enforcement | P0 | 3-4 hours | Phase 2 |
| 5. Progressive Disclosure | P1 | 4-6 hours | Phase 1-4 complete |
| 6. Context De-duplication | P1 | 3-4 hours | Phase 5 |
| 7. Token Budget Policy | P1 | 2-3 hours | Phase 6 |
| 8. Environment Preflight | P2 | 2-3 hours | Phase 2 |
| 9. Integration & Docs | All | 4-6 hours | Phase 1-8 |
| 10. Metrics & Monitoring | Ongoing | 1-2 hours/week | Phase 9 |

**Total Estimated Effort**: 28-41 hours for P0-P1 items, plus ongoing monitoring

## Key Success Factors

1. **Leverage Existing Infrastructure**: Reuse file:scripts/Validate-SessionJson.ps1, file:scripts/Check-SkillExists.ps1, file:scripts/Detect-SkillViolation.ps1 patterns
2. **Follow ADR-005**: All scripts in PowerShell (no bash/Python)
3. **Verification-Based Enforcement**: Mirror Serena initialization pattern (tool output required)
4. **Progressive Disclosure**: Implement references/ pattern to reduce upfront context
5. **Measure Everything**: Token budgets, compliance rates, violation patterns
6. **Codex-Specific Adaptations**: Manual gate execution (no MCP hooks), explicit validation steps
7. **Automation-First Design**: Pre-commit hooks and CI workflows enforce compliance without manual steps
8. **Exit Code Driven**: All validation scripts use standard exit codes (0=pass, 1=fail) for hook/CI integration
9. **Dry-Run Capability**: All enforcement scripts support dry-run mode for testing and CI reporting

---

Execution Information

Branch: main
Commit: e0318e3

---

💡 Tips

Supported Commands (Inside Comments)

• Use @traycerai generate to iterate on the previous version of the implementation plan.

Supported Commands (Inside Description)

• Add @traycerai ignore anywhere in the ticket description to prevent this ticket from being processed.
• Add @traycerai branch:<branch-name> anywhere in the ticket description to specify the target branch for the implementation plan.

Community

• Join our Discord Community to get help, request features, and share feedback.
• Follow us on X/Twitter for updates and announcements.

[coderabbitai]

📝 CodeRabbit Plan Mode

Generate an implementation plan and prompts that you can use with your favorite coding agent.

• Create Plan

Examples

• Example 1
• Example 2

---

⚠️ Possible Duplicate Issue

• ADR-007 Bulletproof Enforcement: Claude Code Hooks + Validation Enhancement #729

🔗 Related PRs

#255 - feat(github-skill): enhance skill for Claude effectiveness [merged]
#301 - docs: autonomous PR monitoring prompt and retrospective [merged]
#752 - feat(memory): memory system foundation (Session 230) [merged]
#775 - docs: implement CLAUDE.md @imports pattern [merged]
#830 - feat(session-init): session protocol validation improvements and module refactoring [merged]

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!

[github-actions]

Product Requirements Document

Important

This PRD was automatically generated based on issue triage escalation.
Complexity Score: 9/12 (Detailed)
Escalation Criteria: feature_request,multi_phase_work,research_required

About this PRD

This PRD was generated by the Explainer Agent after the issue was flagged
for detailed analysis. The document is designed to be self-contained - it can
be passed to a separate AI agent instance for implementation without additional
context.

PRD Depth Levels:

• Standard (4-6): Brief analysis, clear requirements
• Detailed (7-9): Research section, blocking questions
• Comprehensive (10-12): Phased implementation, risk analysis

---

Now I have sufficient context to write a comprehensive PRD. Let me create it:

The file system write was denied. I will output the PRD directly for the user to use:

---

PRD: Codex Effectiveness Improvements

Executive Summary

The Codex AI coding agent operates in the ai-agents repository but lacks the enforcement mechanisms that make Claude Code sessions successful. Claude Code achieves near-100% protocol compliance through verification-based enforcement gates. Codex sessions show recurring compliance gaps: skipped memory loading, raw gh command usage, and incomplete session initialization.

This PRD defines implementation requirements to achieve Codex parity with Claude Code through verification-based gates, memory-first workflows, skill-first GitHub operations, and context optimization.

Scope	Status	Blocker
Codex session-start gate script	🟢 READY	None
Memory-first verification enforcement	🟢 READY	None
Skill-first GitHub operations	🟢 READY	None
Protocol checklist alignment	🟢 READY	None
Progressive disclosure for skills/docs	🟢 READY	None
Context de-duplication	🟡 PARTIAL	Requires token measurement baseline
Token budget policy	🟡 PARTIAL	Requires baseline measurement
Environment preflight checks	🟢 READY	None

Verdict: READY for P0 items. P1 items require discovery phase for token measurement.

---

Problem Statement

Current State

Component	Claude Code	Codex	Gap
Session-start gate	Serena init via MCP tools	None	No blocking enforcement
Memory loading	memory-index read required	Ad-hoc	Inconsistent retrieval
Skill usage	SKILL.md + pre-commit detection	None	Raw gh commands used
Session log creation	session-init skill	Manual	Template variations
Context loading	Progressive via skill triggers	Full upfront	Context bloat

Gap Analysis

Why this matters: Codex sessions operating without enforcement mechanisms produce:

1. Repeated discoveries: Patterns already documented in memory are rediscovered (30% efficiency loss per session-init-003-memory-first-monitoring-gate)
2. Skill violations: Raw gh commands bypass tested, validated skill scripts
3. Protocol drift: Session logs fail CI validation due to template variations
4. Context exhaustion: Full context loading consumes tokens needed for task execution

User Impact

User	Impact
Codex sessions	Lower task completion rate, repeated mistakes
Human reviewers	Must catch violations CI should block
Repository maintainers	Manual remediation of failed sessions

---

Research Findings

Primary Sources

SESSION-PROTOCOL.md (Canonical):

"This protocol uses verification-based enforcement. Protocol compliance is verified through:

1. Technical controls that block work until requirements are met
2. Observable checkpoints that produce verifiable evidence
3. Validation tooling that detects violations automatically"

Confidence: CONFIRMED

ADR-007-memory-first-architecture.md:

"Memory retrieval MUST precede reasoning in all agent workflows... Evidence: 30% session efficiency loss observed when memories not loaded first"

Confidence: CONFIRMED

usage-mandatory.md (Serena memory):

"NEVER use raw commands when a Claude skill exists for that functionality... Skills are tested, handle errors, have proper parameter validation, and are maintained centrally."

Confidence: CONFIRMED

Existing Enforcement Scripts

Script	Purpose	Status
Check-SkillExists.ps1	Verify skill availability	ACTIVE
Detect-SkillViolation.ps1	Detect raw gh usage	ACTIVE (non-blocking)
Validate-TokenBudget.ps1	HANDOFF.md token limit	ACTIVE
Validate-SessionJson.ps1	Session log validation	ACTIVE

Confidence: CONFIRMED (verified in codebase)

---

Proposed Solution

Phase 1: Codex Session-Start Gate (P0)

Status: READY | Effort: M | Blockers: None

Task	Description
1.1	Create Invoke-CodexSessionStartGate.ps1 in scripts/
1.2	Implement verification-based checks (not self-reported)
1.3	Add exit codes: 0=pass, 1=memory-missing, 2=skill-missing, 3=branch-invalid
1.4	Create Codex-specific AGENTS.md section with gate invocation
1.5	Add Pester tests for all gate conditions

Implementation Pattern:

# Invoke-CodexSessionStartGate.ps1
[CmdletBinding()]
param(
    [Parameter(Mandatory = $false)]
    [string]$SessionObjective
)

# Phase 0: Git state verification
$branch = git branch --show-current
if ($branch -in @('main', 'master')) {
    Write-Error "BLOCKED: Cannot work on protected branch. Create feature branch first."
    exit 3
}

# Phase 1: Memory availability check
$memoryIndex = Join-Path $PSScriptRoot ".." ".serena" "memories" "memory-index.md"
if (-not (Test-Path $memoryIndex)) {
    Write-Error "BLOCKED: memory-index.md not found. Initialize Serena memories."
    exit 1
}

# Phase 2: Skill directory verification
$skillsDir = Join-Path $PSScriptRoot ".." ".claude" "skills" "github" "scripts"
if (-not (Test-Path $skillsDir)) {
    Write-Error "BLOCKED: GitHub skills directory not found."
    exit 2
}

# Phase 3: List available skills for session context
$skills = Get-ChildItem -Path $skillsDir -Recurse -Filter "*.ps1" | 
    Select-Object -ExpandProperty Name
Write-Output "Available GitHub skills: $($skills -join ', ')"

# Phase 4: Output session context
Write-Output "Branch: $branch"
Write-Output "Memory index: AVAILABLE"
Write-Output "GitHub skills: $($skills.Count) scripts"

exit 0

Phase 2: Memory-First Verification Enforcement (P0)

Status: READY | Effort: S | Blockers: None

Task	Description
2.1	Add memory loading check to session-start gate
2.2	Require evidence of memory-index content in session log
2.3	Update Validate-SessionJson.ps1 to verify memory evidence
2.4	Document memory loading in Codex-specific instructions

Phase 3: Skill-First GitHub Operations (P0)

Status: READY | Effort: S | Blockers: None

Task	Description
3.1	Upgrade Detect-SkillViolation.ps1 to blocking mode for Codex
3.2	Add skill inventory output to session-start gate
3.3	Create Codex-specific skill usage instructions
3.4	Add skill violation detection to pre-commit hook

Phase 4: Protocol Checklist Alignment (P0)

Status: READY | Effort: S | Blockers: None

Task	Description
4.1	Create Codex-specific session protocol section
4.2	Align checklist with Codex capabilities (no MCP tools)
4.3	Define fallback behavior for missing Serena MCP
4.4	Update session validation to accept Codex-style evidence

Codex Protocol Differences:

Requirement	Claude Code	Codex Equivalent
Serena activation	mcp__serena__activate_project	Read .serena/memories/ directly
Memory search	mcp__serena__search_memories	Grep memory-index.md for keywords
Session log creation	/session-init slash command	pwsh scripts/New-SessionLog.ps1
Memory write	mcp__serena__write_memory	Create markdown file in .serena/memories/

Phase 5: Progressive Disclosure (P1)

Status: READY | Effort: M | Blockers: None

Task	Description
5.1	Create references/ pattern for skill directories
5.2	Move detailed documentation to reference files
5.3	Keep SKILL.md files under 200 lines
5.4	Add "For details, see references/..." pointers

Phase 6: Context De-duplication (P1)

Status: PARTIAL | Effort: M | Blockers: Requires token measurement baseline

Task	Description
6.1	Audit context sources for duplication
6.2	Identify redundant content across AGENTS.md, CLAUDE.md, skill files
6.3	Consolidate to single-source patterns
6.4	Measure token reduction (target: 10-15%)

Phase 7: Token Budget Policy (P1)

Status: PARTIAL | Effort: S | Blockers: Requires baseline from Phase 6

Phase 8: Environment Preflight Checks (P2)

Status: READY | Effort: S | Blockers: None

Task	Description
8.1	Add tool availability checks to session-start gate
8.2	Check for: pwsh, node, git, gh
8.3	Optional: Check for sqlite3 (memory export)
8.4	Report missing tools with install instructions

---

Functional Requirements

FR-1: Session-Start Gate (P0)

ID	Requirement	Acceptance Criteria
FR-1.1	Gate script MUST verify git branch is not main/master	Exit code 3 when on protected branch
FR-1.2	Gate script MUST verify memory-index.md exists	Exit code 1 when missing
FR-1.3	Gate script MUST verify skill directory exists	Exit code 2 when missing
FR-1.4	Gate script MUST output available skill inventory	Skill names printed to stdout
FR-1.5	Gate script MUST be idempotent	Multiple invocations produce same result

FR-2: Memory-First Enforcement (P0)

ID	Requirement	Acceptance Criteria
FR-2.1	Session validation MUST verify memory evidence	Validation fails if Evidence column empty
FR-2.2	Memory evidence MUST include memory names loaded	At least memory-index documented

FR-3: Skill-First Operations (P0)

ID	Requirement	Acceptance Criteria
FR-3.1	Skill violation detection MUST run on staged files	Detect-SkillViolation.ps1 with -StagedOnly
FR-3.2	Violations MUST be reported with suggested skill alternative	Script name in output

---

Success Metrics

Metric	Target
Session protocol compliance	100% without manual reminders
Startup tokens reduced	10-15% reduction
Raw gh usage	Zero when skills exist
Session logs missing evidence	Zero
Gate script test coverage	80%+

---

Risks and Mitigations

Risk	Likelihood	Impact	Mitigation
Codex ignores gate script	Medium	High	Add gate check to session validation
Memory files not committed	Low	Medium	Pre-commit hook verifies .serena/ changes
Token measurement inaccurate	Medium	Medium	Use heuristic with safety margin

---

Appendix A: Research Sources

Source	Location
SESSION-PROTOCOL.md	.agents/SESSION-PROTOCOL.md
ADR-007	.agents/architecture/ADR-007-memory-first-architecture.md
usage-mandatory	.serena/memories/usage-mandatory.md
memory-index	.serena/memories/memory-index.md
PROJECT-CONSTRAINTS	.agents/governance/PROJECT-CONSTRAINTS.md

---

PRD Version: 1.0 | Complexity Score: 9 (Detailed PRD)

_{Generated by AI PRD Generation | View Workflow}

[github-actions]

AI Triage Summary

Note

This issue has been automatically triaged by AI agents

What is AI Triage?

This issue was analyzed by AI agents:

• Analyst Agent: Categorizes the issue and suggests appropriate labels
• Roadmap Agent: Aligns the issue with project milestones and priorities
• Explainer Agent (if escalated): Generates comprehensive PRD

Triage Results

Property	Value
Category	enhancement
Labels	["enhancement","agent-orchestrator","agent-memory","area-workflows"]
Priority	P1
Milestone	v1.1
PRD Escalation	Generated (see below)

Categorization Analysis

```json
{
  "labels": ["enhancement", "agent-orchestrator", "agent-memory", "area-workflows"],
  "category": "enhancement",
  "confidence": 0.92,
  "reasoning": "Epic describes new workflow improvements for Codex including session gates, memory-first workflows, and skill enforcement - clearly an enhancement spanning orchestration, memory, and workflow areas"
}

</details>

<details>
<summary>Roadmap Alignment</summary>

```json
```json
{
  "milestone": "v1.1",
  "priority": "P1",
  "epic_alignment": "",
  "confidence": 0.85,
  "reasoning": "New epic for Codex effectiveness with clear outcomes, 10 backlog items, and measurable success metrics; aligns with v1.1 maintainability theme",
  "escalate_to_prd": true,
  "escalation_criteria": ["feature_request", "multi_phase_work", "research_required"],
  "complexity_score": 9
}

</details>

---

<sub>Powered by [AI Issue Triage](https://github.com/rjmurillo/ai-agents) workflow</sub>