Custom global Codex skills for agent-first initiative work.

Use the lifecycle for initiative-sized changes. For small fixes, use only the skills proportional to risk.

Ask for the phase or outcome you want:

• "Plan an initiative for this idea."
• "Review this copy or workflow for first-time user clarity."
• "Review this initiative before activation."
• "Activate this initiative and prepare the first milestone."
• "Implement the current milestone."
• "Run conformance review."
• "Prepare the PR."
• "Handle PR feedback."
• "Finish post-merge cleanup."

Individual skills can still be named directly when you want exact control.

concept
  -> initiative-planning
  -> ux-copy-review
  -> initiative-adversary-review
  -> initiative-activation
  -> milestone-implementation
  -> milestone-conformance-review
  -> pr-readiness-gate
     (routes to ux-copy-review / pre-pr-adversary-review / release-log / pr-description as needed)
  -> copilot-feedback-gate / review-comments
  -> post-merge-cleanup
  -> initiative-completion
  -> next milestone or done

This graph shows the default initiative route. For small changes, enter at the skill that matches the current phase and let pr-readiness-gate route PR prep. Conformance and adversarial reviews produce evidence for a specific branch base/head pair; pr-readiness-gate batches the durable pre-PR lifecycle bookkeeping through initiative-lifecycle.mjs record-pr-ready.

flowchart TD
  concept["Concept or request"] --> planning["initiative-planning"]
  planning --> copyPlan{"Copy or workflow surface to review?"}
  copyPlan -->|yes| uxPlan["ux-copy-review"]
  copyPlan -->|no| planReview["initiative-adversary-review"]
  uxPlan --> planReview

  planReview -->|accepted| activation["initiative-activation"]
  planReview -->|needs revision| planning
  activation --> implementation["milestone-implementation"]

  implementation --> support{"Support work needed?"}
  support -->|tests or validation| testing["testing"]
  support -->|behavior-preserving structure| refactoring["refactoring"]
  support -->|ready to record| commit["commit"]
  testing --> commit
  refactoring --> commit
  commit --> conformance["milestone-conformance-review"]
  support -->|no extra support| conformance

  conformance -->|pass| readiness["pr-readiness-gate"]
  conformance -->|partial or fail| implementation
  conformance -->|needs decision| decision["human decision"]
  decision --> conformance

  readiness -->|copy risk| uxPR["ux-copy-review"]
  readiness -->|behavior or contract risk| adversary["pre-pr-adversary-review"]
  readiness -->|release impact| release["release-log"]
  readiness -->|missing proof| testing
  readiness -->|ready| recordReady["record-pr-ready lifecycle script"]
  recordReady --> prDescription["pr-description"]
  uxPR --> readiness
  adversary -->|changed tests or fixtures| testQuality["test-quality-review"]
  testQuality -->|weak proof| testing
  testQuality -->|proof ok| adversary
  adversary -->|fixes needed| implementation
  adversary -->|clean| readiness
  release --> readiness

  prDescription --> feedback{"Review feedback?"}
  feedback -->|functionality-heavy or systemic| feedbackGate["copilot-feedback-gate"]
  feedback -->|ordinary review threads| reviewComments["review-comments"]
  feedbackGate --> reviewComments
  feedbackGate -->|scope or risk changed| conformance
  reviewComments -->|fixes pushed| readiness
  reviewComments -->|ready for merge| merged["PR merged"]

  merged --> cleanup["post-merge-cleanup"]
  cleanup --> completion["initiative-completion"]
  completion --> next{"More milestone work?"}
  next -->|yes| activation
  next -->|no| done["done"]

Use clean spawned agents when private conversation history would bias the result.

Best clean-context candidates:

• ux-copy-review when prior implementation context may bias the review
• initiative-adversary-review
• milestone-implementation
• milestone-conformance-review
• pre-pr-adversary-review
• code-review
• copilot-feedback-gate

Usually keep stateful/action workflows in the main context:

• initiative-planning
• initiative-activation
• pr-description
• release-log
• review-comments
• post-merge-cleanup
• initiative-completion

Inherit the parent model by default. Delegate to a named custom agent when the workflow benefits from clean context or a specific model/reasoning tier.

Invoking a skill that has a Delegation Default is an explicit request to use that skill's named custom agent when a multi-agent spawn tool and the named agent are available. Do not run those workflows locally merely because the user did not separately say "use a subagent." If spawning or the named agent is not available, run the workflow in the current context and state that delegation was unavailable.

Custom agent source files live in agents/ and should be installed to ~/.codex/agents/ for Codex to load them.

Treat durable artifacts as the source of truth:

• initiative PRD, milestones, and optional architecture notes
• structured lifecycle state in initiative.json, updated through lifecycle scripts
• implementation packet and implementation report
• branch diff against main
• conformance report and adversarial review findings
• PR description, release notes, review comments, and completion report

Do not hand-edit conformance or adversarial-review gate state from conversation memory. When an initiative branch is ready for PR prep, let pr-readiness-gate record satisfied gates with:

node $SKILLS_DIR/initiative-completion/scripts/initiative-lifecycle.mjs record-pr-ready \
  --repo <repo> \
  --initiative <initiative-path> \
  --milestone <milestone-id> \
  --conformance \
  --adversarial-review \
  --base-sha <merge-base-sha> \
  --head-sha <head-sha>

If a justification matters, put it in an artifact: PRD, milestone, architecture note, code comment, test, commit message, PR description, or review reply.

Use SKILLS_DIR=/Users/hanna/.codex/skills as the base path for helper scripts and references in these docs. If a command or note uses $SKILLS_DIR, expand it to that directory before executing the command unless the shell environment already defines it.

Planning and lifecycle:

• initiative-planning
• ux-copy-review
• initiative-adversary-review
• initiative-activation
• milestone-implementation
• milestone-conformance-review
• initiative-completion

Implementation support:

• testing
• refactoring
• commit

Review and PR:

• ux-copy-review
• pre-pr-adversary-review
• code-review
• pr-description
• release-log
• copilot-feedback-gate
• review-comments

Post-merge:

• post-merge-cleanup