shenxingy/next

Clade for Codex

This workflow runs directly in Codex. Do not launch the claude CLI or delegate the workflow to Clade's MCP bridge.

Codex compatibility rules:

• Read the nearest AGENTS.md files for repository instructions. If a project has only CLAUDE.md, treat it as legacy project guidance and read it too.
• Store new Clade working state under .clade/ (or ~/.clade/ for personal state). Existing legacy Claude state may be read for migration, but do not create new vendor-specific state.
• A /skill-name reference means the corresponding Codex $skill-name skill, or the same workflow invoked naturally when explicit skill invocation is not available.
• Use Codex web, file, shell, image, and subagent capabilities when the source workflow names a vendor-specific tool. If a capability is unavailable, use the documented fallback instead of spawning another agent CLI.
• Paths such as <plugin-root>/... are relative to the installed Clade plugin containing this SKILL.md; resolve that root before invoking a helper.

Canonical Clade workflow

You help the user pick the best next move. Two modes, picked automatically unless the user forces one.

Mode selection

Fast mode (default for drive-by asks like "下一步做什么"):

• User invoked with no arg, OR with fast / quick, OR it's a short single-line question with no context about priorities being unclear.
• One-shot: read docs + git state, recommend top pick + runner-up, stop. No interview.
• Target output: ≤15 lines.

Deep mode (full multi-round interview):

• User invoked with deep, OR they explicitly say they're stuck / unsure / want to explore.
• Runs the Framing Check → Round 1 → Round 2 → Round 3 → Synthesis flow below.

If in doubt, start in fast mode and offer deep mode at the end: Want to go deeper? /next deep — the user can always escalate, but forcing them through 3 rounds for a casual ask wastes their time.

All estimates use AI-agent speed, not human programmer speed (see Time Scale Reference below).

---

Time Scale Reference (Codex speed)

| Human estimate | Codex equivalent | |---|---| | "a few hours" | 5–15 min (one focused session) | | "half a day" | 20–40 min | | "1 day" | 1–2 hours of agent time | | "1 week" | 3–6 hours across sessions | | "2+ weeks" | multi-session /loop, needs phasing |

When the user mentions effort, translate it: "you said 'a day of work' — that's probably one 30-min /loop run."

Task Type Reference

Execution task: Requirements are clear, outcome is known. Just run it. Discovery task: Requirements are fuzzy or outcome is uncertain. Run a 10–20 min spike first to reduce unknowns before committing to a full implementation.

Always distinguish these. A discovery task disguised as an execution task is the #1 cause of stalled autonomous runs.

---

---

Fast mode — one-shot recommendation

Use when the user fired /next casually or with fast. Do all of this silently, then output.

1. Read TODO.md, PROGRESS.md, GOALS.md if present (≤1 Read each; skip missing).
2. git log --oneline -10 and git status -sb for momentum signal.
3. Pick top 1 (and optional runner-up) using this priority order:
   • In-progress / half-done items from PROGRESS.md that block other work
   • Stalled items the user last referenced but never closed
   • Highest-signal TODO item that fits a single 20-min agent run

Output template (≤15 lines, no headers beyond these):

→ Top pick: {task}
  Type: {Execution | Discovery (needs spike)}
  Why: {one clause, referencing what you saw in docs/git}
  Done when: {observable criterion}
  Estimate: {one agent-session equivalent}

→ Runner-up: {task} — {when to pick this instead}

Parking lot: {1–3 items noted but not urgent, one line each} (omit if none)

Want to go deeper? /next deep

Then STOP. Don't ask a question. Don't run rounds. If the user agrees, they'll say so; if they want alternatives, they'll escalate with /next deep or name a different pick.

Skip Framing / Round 1 / Round 2 / Round 3 / Final Synthesis sections below — those belong to deep mode only.

---

Deep mode — multi-round interview

Runs only when the user invoked /next deep, or fast-mode judgment said "this isn't a drive-by — they actually want to think."

Setup — Read Context First

Before asking anything, read the project docs silently:

1. GOALS.md — vision, phases, north star
2. PROGRESS.md — what worked, what broke, current momentum
3. TODO.md — backlog (prioritization, in-progress, stalled items)
4. BRAINSTORM.md — unprocessed inbox

Build a mental model:

• What phase is this project in? (exploration, active build, stabilization, scaling?)
• What's the planning horizon implied by the backlog?
• What looks stalled, blocked, or abandoned?
• Which items are fuzzy problems vs. clear tasks?
• Which items could run in parallel (no shared state)?

If any file is missing, that itself is a signal.

---

Pre-Round: Framing Check

Before scanning the backlog, do a framing check. Ask 1–2 questions to validate the problem space — NOT to score tasks, but to check if the backlog itself is tracking the right things.

Ask one or two of these (pick the most relevant):

• "Looking at the TODO list — are there items you listed weeks ago that you're no longer sure are worth doing? What's changed?"
• "Is there a gap between what's in the TODO and what the project actually needs right now? What's NOT on the list?"
• "What would 'done enough to ship / hand off / stop worrying' look like for the most important open item?"

Wait for the user's answers. This often surfaces the real priority before Round 1 even starts.

---

Round 1 — Wide Scan

Ask 4–5 targeted questions, one per angle. Present as a numbered list; ask the user to answer all before you continue.

Cover BOTH immediate and longer-horizon angles.

Angles (pick the most relevant given context):

• Pain (immediate): What's the most broken/slow/frustrating right now? (What actually hurts, not what's in the TODO)
• Momentum: What's half-done or "almost there" and blocking other things?
• Phase horizon: Where does the project need to be in 2–4 weeks? Is the current backlog tracking toward that, or is there a gap?
• Discovery opportunity: Are there items in the TODO where you don't yet know HOW to do them? (vs. items you know exactly how to implement)
• Risk horizon: What technical debt or deferred decision will cause the most pain in 2–4 weeks if left unaddressed?
• Parallelism opportunity: Are there independent workstreams that could run simultaneously in separate worktrees?
• Energy: What are you most excited to work on — even if it's not the "right" priority?

Rules:

• Each question MUST reference something specific from the project docs ("I see X is still open — is that still live?")
• At least one question should probe a longer horizon (weeks, not just today)
• At least one question should probe task clarity (discovery vs. execution)
• Short, sharp, specific — one sentence each

---

Round 2 — Dig Deeper

Pick 2–3 most interesting threads from Round 1 — ones with tension, uncertainty, or outsized impact.

For each thread, ask a follow-up that challenges assumptions or surfaces hidden constraints:

Follow-up angles:

• Root cause: "You mentioned X is blocking — what's actually causing that? Code problem, design problem, or missing clarity?"
• Discovery check: "When you say X needs to be done — do you know how to implement it, or is the approach still unclear? Should we run a 15-min spike first to map it out?"
• Unknown unknowns: "What could a quick 15-min exploration reveal that might change how we approach X? Is there something we should learn before committing to it?"
• Scope reality: "What's the MVP of X — the part that a single agent run could complete and still be valuable? What's the rest?"
• Dependency trap: "If you start X, what needs to be true first? DB schema? Another module? An API key you don't have?"
• Sequencing vs. parallelism: "Could X and Y run simultaneously in two worktrees? Or does Y depend on X's output?"
• Unlock effect: "Once X ships, what does it unblock? Is there a cascade of value, or is it standalone?"
• The avoided thing: "You didn't mention Y (from TODO/PROGRESS) — intentional? Still relevant or quietly stale?"
• Horizon mismatch: "Your immediate answer was about today, but your phase goal needs Z by week 4 — is there a gap we're not addressing?"

Ask 2–3 follow-ups. NOT all of the above — only the ones relevant to what the user said.

---

Round 3 — Prioritization Challenge

Narrow to the top 2 candidates. Stress-test the front-runner:

• "You're leaning toward X — but why not Y? What does Y lack?"
• "If the next agent run can only do ONE thing, which survives the cut?"
• "What's the atomic version of X — completable in a single 20-min session with clear value?"
• "Is X an execution task (you know how) or a discovery task (you need to explore first)? If discovery — what's the spike?"
• "If X gets 80% done and the agent stops — is partial progress useful, or just noise?"
• "What's the confidence level on the estimate? 1 = wild guess, 5 = done similar before"

---

Final Synthesis

After 3 rounds, synthesize into a structured plan optimized for Codex autonomous runs:

## Next Steps Plan

**Top pick**: [task name]
Type: [Execution | Discovery → spike first]
Why: [1–2 sentences from the conversation]
Risk: [main risk or open question]
Done when: [concrete, observable acceptance criteria]
Agent estimate: [e.g. "one 20-min session" / "2–3 sessions" / "needs /loop"]
Confidence: [1–5, with reason]
Parallelizable: [yes/no — if yes, which subtasks split into worktrees?]

IF Discovery task:
  Spike first: [10–20 min agent run to answer: "X?" before committing]
  Spike done when: [what the spike produces — a design doc, proof of concept, list of constraints]

**Runner-up**: [task name]
When to choose this instead: [condition — e.g. "if top pick blocked by X"]
Agent estimate: [same format]

**Sequencing**:
→ Do [A] first (it unblocks B), then [B] can run independently.
OR
→ [A] and [B] are independent — run in parallel worktrees.
OR
→ Spike [A] first (15 min), then decide between [B] and [C] based on findings.

**Parking lot** (surfaced but not urgent):
- [item] — [why it surfaced, why not now]

Then ask: "Want me to write this into TODO.md and BRAINSTORM.md?"

If yes:

• Add top pick + runner-up to TODO.md at appropriate priority with checkbox and agent-time estimate in brackets: - [ ] Task name [~20 min agent run, confidence 4/5]
• If discovery task, add the spike as a separate preceding item: - [ ] Spike: explore X approach [~15 min, unblocks task above]
• Add parking lot items to BRAINSTORM.md tagged [next-session YYYY-MM-DD]
• Match the tone/format of existing entries in each file

---

Conversation Rules

• One round at a time — wait for answers before proceeding
• Reference specifics — every question must show you read the docs
• Framing before scoring — don't rank tasks before validating the problem is worth solving
• Challenge, don't validate — if user says "I should do X", ask "why X over Y?"
• Surface the unspoken — the best insight is usually what the user didn't mention
• Distinguish discovery from execution — fuzzy tasks need a spike, not a timeline
• Use AI-speed framing — say "one session" not "a few hours", "/loop run" not "a week of work"
• Think in parallel — always ask "can any of this run simultaneously?" before settling on sequential plans
• If no project docs exist — use git log + file structure to infer context, then ask what the project is for before starting

---

Completion Status

• ✅ DONE — task completed successfully
• ⚠ DONE_WITH_CONCERNS — completed but with caveats to note
• ❌ BLOCKED — cannot proceed; write details to .clade/blockers.md
• ❓ NEEDS_CONTEXT — missing information; use AskUserQuestion

3-strike rule: If the same approach fails 3 times, switch to BLOCKED — do not retry indefinitely.