@dzhechkov/skills-feature-adr 1.3.24 → 1.3.28

package/README.md

@@ -106,6 +106,41 @@ ARCHITECTURE → IMPLEMENTATION →  CODE   →   QE    →  FLEET QE
 # Full protocols + 6 extra skills, up to 7 fleet QE agents
 ```
 
+### Codex model routing (optional)
+
+If [Codex](https://developers.openai.com/codex) is installed + logged in, the pipeline can route work to
+Codex — **always asking first, always with a Claude fallback** (it never blocks on Codex). Three opt-in
+knobs (via the workflow `args`, or offered interactively at the planning checkpoint):
+
+| Knob | Step | What it does |
+|---|---|---|
+| `planner: 'codex'` | 6 Plan | plan on Codex's top model (Claude fallback) |
+| `coder: 'codex-fallback'` | 7 Code | Claude first; **if the Claude Code limit is exhausted mid-run → retry on Codex** |
+| `qeReviewer: 'codex-fallback'` | 8 QE/tests | same fallback for the review/testing stage |
+| `codexModel: 'gpt-5-codex'` | — | which Codex model (`gpt-5-codex` default · `gpt-5` · `o3` · `auto`) |
+
+**Scenario — never stall on a rate limit:** a long L/XL feature hits the Claude Code session limit while
+writing code. Without this the run stalls; with `coder: 'codex-fallback'` the pipeline logs *"Claude
+unavailable (limit?) — falling back to Codex gpt-5-codex"* and finishes the code + tests on Codex, no
+restart and no lost work.
+
+```bash
+# Headless login on a VPS (no browser):
+codex login --device-auth                       # prints a code + URL you approve on another device
+# — or —
+printenv OPENAI_API_KEY | codex login --with-api-key
+```
+
+```js
+// ultracode (the deterministic workflow form): plan on Codex, code+QE fall back to Codex on Claude-limit:
+Workflow({ scriptPath: '.claude/workflows/feature-adr.js',
+  args: { slug: 'add-oauth', description: '…', tier: 'M',
+          planner: 'codex', coder: 'codex-fallback', qeReviewer: 'codex-fallback', codexModel: 'gpt-5-codex' } })
+```
+
+Omit the Codex knobs entirely for today's all-Claude behavior. The run result reports
+`plannerUsed` / `coderUsed` / `qeReviewerUsed` / `codexModel` so you can see who did what.
+
 ---
 
 ## Spec-Driven Development (SDD)

package/docs/team-onboarding.md

@@ -170,6 +170,27 @@ for load-bearing judgment). Models are **overridable defaults**.
 > steps and compare reward patterns / rework counts vs your `sonnet` baseline. This table is a
 > starting heuristic, not a benchmark — tune per project.
 
+### Codex routing (optional — cross-model + limit resilience)
+
+In the **ultracode workflow form**, feature-adr can hand steps to [Codex](https://developers.openai.com/codex)
+— opt-in, always with a Claude fallback (never blocks). Two reasons teams turn it on:
+
+1. **Cross-model planning** — plan Step 6 on Codex's top model: `planner: 'codex'`.
+2. **Never stall on a rate limit** — the killer feature: `coder: 'codex-fallback'` +
+   `qeReviewer: 'codex-fallback'`. Claude writes the code/tests as usual; but if a long L/XL run hits
+   the **Claude Code session limit mid-Step-7/8**, the pipeline auto-retries that step on Codex
+   (`gpt-5-codex` by default) instead of stalling — no restart, no lost work.
+
+```bash
+# one-time headless login (VPS, no browser):
+codex login --device-auth        # approve the printed code+URL on your phone/laptop
+
+# then, when launching a run, pass the knobs (or accept the interactive pre-flight offer):
+#   planner: 'codex' | coder: 'codex-fallback' | qeReviewer: 'codex-fallback' | codexModel: 'gpt-5-codex'
+```
+
+Omit the knobs for the all-Claude default. Full reference: `.claude/rules/feature-adr-ultracode.md`.
+
 ---
 
 ## 7. QE modes cheat-sheet

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dzhechkov/skills-feature-adr",
-  "version": "1.3.24",
+  "version": "1.3.28",
   "description": "Adaptive Feature Development skill pack for Claude Code — 11-step pipeline with Complexity Router (S/M/L/XL), ADR-driven architecture, 15 agentic-qe skills, multi-agent fleet QE. Supports --full-qe, --full-qe-extended, --with-learning, and --knowledge-extractor modes.",
   "bin": {
     "skills-feature-adr": "./bin/cli.js"

package/templates/.claude/rules/feature-adr-ultracode.md

@@ -25,6 +25,55 @@ The pipeline ALWAYS runs the feature-adr Pattern memory loop **in-process** —
 - **Step 0** recalls learned patterns (`dz recall`) → folds the top ones into requirements/ADR as `{LEARNED_PATTERNS}` + records the recalled count in the live panel (`dz statusline --fa-record`).
 - **Step 8** teaches the durable lessons back (`dz teach`) + records the stored count. The loop pays off (recall) and grows (teach) every run.
 
+## Optional Codex routing (opt-in, pre-flight ASK)
+
+feature-adr can route work to Codex's models. **All of it is opt-in and graceful** — absent / declined /
+Codex-unavailable → the default Claude agent runs; the pipeline NEVER blocks on Codex. Three knobs, all
+overridable via `args`:
+
+| Knob (`args.*`) | Step | Values | Effect |
+|---|---|---|---|
+| `planner` | 6 (Plan) | `claude` (default) · `codex` | `codex` → Step-6 plans on Codex, Claude fallback |
+| `coder` | 7 (Code) | `claude` (default) · `codex` · `codex-fallback` | `codex-fallback` → Claude first, **on limit-exhaustion (null) → Codex** |
+| `qeReviewer` | 8 (QE/tests) | `claude` (default) · `codex` · `codex-fallback` | same fallback, for the QE/testing stage |
+| `codexModel` | — | `gpt-5-codex` (default) · `gpt-5` · `o3` · `auto` | which Codex model to use |
+
+The result reports `plannerUsed` / `coderUsed` / `qeReviewerUsed` / `codexModel` so you can see who did what.
+
+**Pre-flight — detect + ASK (do this BEFORE launching a run):**
+```bash
+node "<codex-plugin>/scripts/codex-companion.mjs" setup --json   # → { "ready": true }
+```
+If `ready`, ASK the user once (skip all of this if not ready — Claude does everything):
+1. *"Plan (Step 6) on the top Codex model?"* → set `planner: 'codex'`.
+2. *"Fall back to Codex for code + tests/QE (Step 7/8) if the Claude Code limit is exhausted?"* →
+   set `coder: 'codex-fallback'`, `qeReviewer: 'codex-fallback'`.
+3. *"Which Codex model?"* (`gpt-5-codex` / `gpt-5` / `o3` / `auto`) → **write it into codex config so the
+   `codex:codex-rescue` runtime picks it up**, then pass `codexModel`:
+   ```bash
+   printf '\nmodel = "gpt-5-codex"\n' >> ~/.codex/config.toml   # or -c model=... per invocation
+   ```
+For the interactive SKILL (plain `/feature-adr`), make the same three offers at the planning checkpoint.
+
+**Scenario (the reason this exists):** a long L/XL run hits the Claude Code session limit mid-Step-7.
+Without this, the Code agent returns null and the run stalls. With `coder: 'codex-fallback'`, feature-adr
+detects the null, logs *"Claude unavailable (limit?) — falling back to Codex gpt-5-codex"*, and finishes
+the code + tests on Codex — no restart, no lost work.
+
+**Example invocations:**
+```js
+// Plan on Codex, code+QE fall back to Codex only if Claude runs out, gpt-5-codex:
+Workflow({ scriptPath: '.claude/workflows/feature-adr.js',
+  args: { slug: 'add-x', description: '…', tier: 'M',
+          planner: 'codex', coder: 'codex-fallback', qeReviewer: 'codex-fallback', codexModel: 'gpt-5-codex' } })
+
+// All-Claude (the default — omit the Codex knobs entirely):
+Workflow({ scriptPath: '.claude/workflows/feature-adr.js', args: { slug: 'add-x', description: '…', tier: 'M' } })
+```
+
+**Headless Codex login on a VPS (no browser):** `codex login --device-auth` (prints a code + URL you
+approve on another device) or `printenv OPENAI_API_KEY | codex login --with-api-key`.
+
 ## Hybrid checkpoints (router decides)
 
 - **S / M** → run autonomously to completion; present a final consolidated review (ADR + plan + QE).

package/templates/.claude/skills/feature-adr/SKILL.md

@@ -355,6 +355,26 @@ Step 0 (Complexity Router) checks:
   description, code, tier, stopAfter, repo, dzBin } })`. Hybrid checkpoints: S/M autonomous; L/XL return
   after the Plan phase for your steer. See `.claude/rules/feature-adr-ultracode.md`.
 
+**Optional Codex routing (opt-in).** When Codex is installed + logged in (`codex login --device-auth`
+on a headless VPS, or `printenv OPENAI_API_KEY | codex login --with-api-key`), the pipeline can route work
+to Codex — always ASKING first, always with a Claude fallback (never blocks):
+
+- **Planning (Step 6)** on Codex's top model → `args.planner: 'codex'`.
+- **Code (Step 7) + tests/QE (Step 8) FALLBACK** → `args.coder: 'codex-fallback'`, `args.qeReviewer:
+  'codex-fallback'`: Claude runs first, and only if the **Claude Code limit is exhausted mid-run** (the
+  agent returns null) does the SAME task retry on Codex — so a long build never stalls on a rate limit.
+- **Model choice** → `args.codexModel` (`gpt-5-codex` default · `gpt-5` · `o3` · `auto`).
+
+*Scenario:* an L/XL run hits the session limit during coding → with `coder: 'codex-fallback'` feature-adr
+logs *"Claude unavailable (limit?) — falling back to Codex gpt-5-codex"* and finishes on Codex, no restart.
+
+*Example:* `Workflow({ scriptPath: '.claude/workflows/feature-adr.js', args: { slug, description, tier:
+'M', planner: 'codex', coder: 'codex-fallback', qeReviewer: 'codex-fallback', codexModel: 'gpt-5-codex' } })`.
+
+Pre-flight, if Codex is `ready` (`codex-companion setup --json`), the orchestrator asks these three
+before launching; plain `/feature-adr` offers the same at the planning checkpoint. Omit the Codex knobs
+for today's all-Claude behavior. See `.claude/rules/feature-adr-ultracode.md`.
+
 ### Pattern memory loop (self-learning — runs in ALL modes)
 
 **Self-learning is MANDATORY on EVERY `/feature-adr` run — including plain `/feature-adr` without any

package/templates/.claude/workflows/feature-adr.js

@@ -1,7 +1,7 @@
 export const meta = {
   name: 'feature-adr',
-  description: 'Canonical /feature-adr --full-qe-extended pipeline as a reusable workflow: router+RECALL then design(ADR, applies learned patterns) then plan then code then agentic-qe QE+TEACH, producing features/<slug>/00-09 artifacts. MANDATORY in-process self-learning loop (Step-0 recall, apply, Step-8 teach). Hybrid checkpoints (S/M autonomous; L/XL stop-after-plan).',
-  whenToUse: 'ultracode + a feature implementation. Invoke via Workflow({scriptPath:".claude/workflows/feature-adr.js", args:{slug, description, code, tier, stopAfter}}) instead of an ad-hoc orchestration, so every feature ships with an ADR + inline agentic-qe QE + self-learning.',
+  description: 'Canonical /feature-adr --full-qe-extended pipeline as a reusable workflow: router+RECALL then design(ADR, applies learned patterns) then plan then code then agentic-qe QE+TEACH, producing features/<slug>/00-09 artifacts. MANDATORY in-process self-learning loop (Step-0 recall, apply, Step-8 teach). OPTIONAL Codex routing: args.planner=codex (Step-6), args.coder/qeReviewer='codex-fallback' (Step-7/8 fall back to Codex gpt-5-codex when Claude limits exhaust; args.codexModel picks the model). Hybrid checkpoints (S/M autonomous; L/XL stop-after-plan).',
+  whenToUse: 'ultracode + a feature implementation. Invoke via Workflow({scriptPath:".claude/workflows/feature-adr.js", args:{slug, description, code, tier, stopAfter, planner, coder, qeReviewer, codexModel}}) instead of an ad-hoc orchestration, so every feature ships with an ADR + inline agentic-qe QE + self-learning.',
   phases: [
     { title: 'Router', detail: 'Step 0 - classify + self-learning recall' },
     { title: 'Design', detail: 'Steps 1-5 - requirements, ADR, QCSD, architecture (tier-gated)' },
@@ -58,24 +58,73 @@ if (isMplus) {
 }
 const design = await parallel(designThunks)
 
-// Step 6: Plan
+// Step 6: Plan — optionally routed to Codex's top model (opt-in via args.planner='codex').
+// The user opts in at pre-flight ('use the top Codex model for planning?'); we route the Plan step to
+// the codex:codex-rescue runtime and GRACEFULLY FALL BACK to the default (Claude) planner if Codex is
+// unavailable/errors — the pipeline never blocks on Codex.
 phase('Plan')
-const plan = await agent('Step 6 (SPARC-GOAP implementation plan) of /feature-adr for "' + DESC + '" (' + SLUG + ', tier ' + tier + '). Given the requirements + ADR + architecture in ' + FDIR + ', decompose into milestones + concrete tasks with success metrics. Write ' + FDIR + '/06_implementation_plan.md. Return wrote[] + summary.', { label: 'plan', phase: 'Plan', schema: ARTIFACT })
+const PLANNER = (A.planner === 'codex') ? 'codex' : 'claude'
+const planPrompt = 'Step 6 (SPARC-GOAP implementation plan) of /feature-adr for "' + DESC + '" (' + SLUG + ', tier ' + tier + '). Given the requirements + ADR + architecture in ' + FDIR + ', decompose into milestones + concrete tasks with success metrics. Write ' + FDIR + '/06_implementation_plan.md. Return wrote[] + summary.'
+let plan = null
+if (PLANNER === 'codex') {
+  const codexPlan = await agent(planPrompt, { label: 'plan:codex', phase: 'Plan', agentType: 'codex:codex-rescue' })
+  if (codexPlan) {
+    plan = { wrote: [FDIR + '/06_implementation_plan.md'], summary: String(codexPlan).slice(0, 500), planner: 'codex' }
+    log('Plan: Codex (top model)')
+  } else {
+    log('Plan: Codex unavailable — falling back to the default planner')
+  }
+}
+if (plan === null) {
+  const claudePlan = await agent(planPrompt, { label: 'plan', phase: 'Plan', schema: ARTIFACT })
+  plan = claudePlan ? { wrote: claudePlan.wrote, summary: claudePlan.summary, planner: PLANNER === 'codex' ? 'claude-fallback' : 'claude' } : null
+}
 
 // Hybrid checkpoint for L/XL
 const stopHere = STOP_AFTER === 'plan' || (isLplus && STOP_AFTER !== 'none')
 if (stopHere) {
-  return { tier: tier, phase: 'checkpoint-after-plan', artifactsDir: FDIR, plan: (plan ? plan.summary : null), note: 'L/XL checkpoint - review the ADR + plan, then re-invoke with args.stopAfter="none" to implement + QE.' }
+  return { tier: tier, phase: 'checkpoint-after-plan', artifactsDir: FDIR, planner: (plan ? plan.planner : null), plan: (plan ? plan.summary : null), note: 'L/XL checkpoint - review the ADR + plan, then re-invoke with args.stopAfter="none" to implement + QE.' }
 }
 
-// Step 7: Code
+// Codex fallback config (opt-in). CODER/QE_REVIEWER ∈ 'claude'|'codex'|'codex-fallback'. On
+// 'codex-fallback' the Claude agent runs FIRST; if it returns null (e.g. the Claude Code session limit
+// is exhausted mid-code/mid-QE — exactly the failure we hit before), the SAME task is retried on the
+// codex:codex-rescue runtime (model = args.codexModel, default gpt-5-codex). The model is set into
+// ~/.codex/config.toml by the orchestrator at pre-flight; the hint below reinforces it.
+const CODEX_MODEL = A.codexModel || 'gpt-5-codex'
+const CODEX_HINT = ' (If you are the Codex runtime, prefer the ' + CODEX_MODEL + ' model.)'
+const CODER = (A.coder === 'codex' || A.coder === 'codex-fallback') ? A.coder : 'claude'
+const QE_REVIEWER = (A.qeReviewer === 'codex' || A.qeReviewer === 'codex-fallback') ? A.qeReviewer : 'claude'
+
+// Step 7: Code (optional Codex fallback on Claude-limit exhaustion)
 phase('Code')
-const code = await agent('Step 7 (Code) of /feature-adr for "' + DESC + '" (' + SLUG + '). Implement the feature per the plan + ADR + architecture in ' + FDIR + '. Write the ACTUAL production code + its tests (mirror the closest existing implementation named in research/architecture). Follow repo conventions; build must pass. Write a change manifest ' + FDIR + '/07_code_changes/change_manifest.md listing every file touched. Return wrote[] (incl. real source files) + summary.', { label: 'code', phase: 'Code', schema: ARTIFACT, effort: 'high' })
+const codePrompt = 'Step 7 (Code) of /feature-adr for "' + DESC + '" (' + SLUG + '). Implement the feature per the plan + ADR + architecture in ' + FDIR + '. Write the ACTUAL production code + its tests (mirror the closest existing implementation named in research/architecture). Follow repo conventions; build must pass. Write a change manifest ' + FDIR + '/07_code_changes/change_manifest.md listing every file touched. Return wrote[] (incl. real source files) + summary.'
+let code = null
+let coderUsed = 'claude'
+if (CODER !== 'codex') {
+  code = await agent(codePrompt, { label: 'code', phase: 'Code', schema: ARTIFACT, effort: 'high' })
+  if (code) coderUsed = 'claude'
+}
+if (code === null && (CODER === 'codex' || CODER === 'codex-fallback')) {
+  if (CODER === 'codex-fallback') log('Code: Claude unavailable (limit?) — falling back to Codex ' + CODEX_MODEL)
+  const codexCode = await agent(codePrompt + CODEX_HINT, { label: 'code:codex', phase: 'Code', agentType: 'codex:codex-rescue' })
+  if (codexCode) { code = { wrote: [FDIR + '/07_code_changes/change_manifest.md'], summary: String(codexCode).slice(0, 500) }; coderUsed = CODER === 'codex' ? 'codex' : 'codex-fallback' }
+}
 
 // Step 8: QE (brutal-honesty, agentic-qe) + MANDATORY teach
 phase('QE')
 const qePrompt = 'Step 8 (QE - brutal-honesty review, agentic-qe) of /feature-adr for "' + DESC + '" (' + SLUG + '). Adversarially review the SHIPPED code (read it): correctness, edge cases, error handling, and the LOAD-BEARING property the ADR named (ASSERT it has a test - the recurring lesson). Grade A/B/C/D honestly. Assess code-test adequacy + doc-test presence. List CONFIRMED gaps with severity. Write ' + FDIR + '/08_qe_report.md. MANDATORY SELF-LEARNING STORE (close the loop, never skip): via Bash run `dz teach "<a durable reusable lesson from this feature - a rule/pattern/pitfall, NOT a checkpoint echo>" --reward <0.7-0.95> --domain <area>` for each genuine lesson (1-3 max, high-signal), then run `' + DZ + ' statusline --fa-record --slug ' + SLUG + ' --step "Step 8 QE" --recalled 3 --stored <count taught> --mode ' + MODE + ' --project ' + REPO + '` (run it verbatim via Bash, do not skip). Do NOT teach trivia or invent gaps. Return {grade, gaps, codeTestsAdequate, docTestsPresent}.'
-const qe = await agent(qePrompt, { label: 'qe:brutal', phase: 'QE', agentType: 'qe-code-reviewer', schema: QE })
+let qe = null
+let qeReviewerUsed = 'claude'
+if (QE_REVIEWER !== 'codex') {
+  qe = await agent(qePrompt, { label: 'qe:brutal', phase: 'QE', agentType: 'qe-code-reviewer', schema: QE })
+  if (qe) qeReviewerUsed = 'claude'
+}
+if (qe === null && (QE_REVIEWER === 'codex' || QE_REVIEWER === 'codex-fallback')) {
+  if (QE_REVIEWER === 'codex-fallback') log('QE: Claude unavailable (limit?) — falling back to Codex ' + CODEX_MODEL)
+  const codexQe = await agent(qePrompt + CODEX_HINT, { label: 'qe:codex', phase: 'QE', agentType: 'codex:codex-rescue' })
+  if (codexQe) { qe = { grade: 'codex-review', gaps: [], codeTestsAdequate: null, docTestsPresent: null, summary: String(codexQe).slice(0, 500) }; qeReviewerUsed = QE_REVIEWER === 'codex' ? 'codex' : 'codex-fallback' }
+}
 
 // Step 9: Fleet QE (L/XL)
 let fleet = 'skipped (S/M)'
@@ -100,6 +149,10 @@ return {
   codeTestsAdequate: qe ? qe.codeTestsAdequate : null,
   docTestsPresent: qe ? qe.docTestsPresent : null,
   fleetQE: fleet,
+  plannerUsed: plan ? plan.planner : null,
+  coderUsed: coderUsed,
+  qeReviewerUsed: qeReviewerUsed,
+  codexModel: CODEX_MODEL,
   selfLearning: 'recall@Step0 + teach@Step8 (mandatory)',
   promiseTags: tags,
 }