ijfw-workflow

IJFW Workflow

Two modes, same principles, same invariants.

• Quick -- 5 moves, 3-5 minutes, locked brief. For features, fixes, ideas.
• Deep -- 6 required modules + 3 optional, 20-45 minutes. For new projects, major refactors, launches.

Donahoe Loop: BRAINSTORM -> PLAN -> EXECUTE -> VERIFY -> SHIP -> MEASURE
              |<--- memory recall at every entry --->|
              |<--- Trident cross-audit on request --->|

RUNTIME BOOTSTRAP AND FALLBACKS

Before the first workflow write or command invocation, inspect whether .ijfw/memory/ exists so the auto-picker and empty-state opener can use that signal accurately. Then ensure .ijfw/memory/ and .planning/ exist before writing artifacts. If the ijfw CLI is unavailable in this session, continue with markdown files and visible chat checklists, then state the exact CLI command the user can run later. Optional commands such as ijfw cross, ijfw design, ijfw recover, ijfw blackboard, ijfw team, and ijfw swarm must degrade to explicit written artifacts instead of blocking the workflow.

AUTO-PICKER (runs first, every time)

Deterministic signals, visible reasoning, no friction.

Protocol:

1. Read signals silently.
2. Say in one line: Reading this as <Quick|Deep> -- <reason>. Say "go deeper" / "just quick" to switch.
3. If signals tie, ask once: Quick or Deep? Accept any affirmative shortcut ("q" / "d").
4. Start immediately. The user should never wait on a modal.

Mid-flow escalation: user can say go deeper at any Quick step; skill re-enters Deep at the equivalent module. Mid-flow de-escalation: just quick collapses the remaining Deep modules into a single LOCK.

EMPTY-STATE OPENER

First session in a project (no .ijfw/memory/ or zero entries in it) is the onboarding moment. Do not stay silent. Open with one line:

Clean slate here. Want me to run a 5-minute Quick brainstorm on what we're building, or jump straight in?

User replies brainstorm / jump in / custom intent. If they jump in, still offer memory hooks for the first 3 turns so decisions get captured. If they brainstorm, route into QUICK mode FRAME. Either way, .ijfw/memory/ gets bootstrapped silently.

If memory is populated but the last handoff is >7 days old, open with a softer beat: Welcome back -- last handoff was <N> days ago. Quick recap? User says recap / new task / actual intent.

BRAINSTORM DISCIPLINE (invariants)

Hard rules. Violating any of these is a workflow failure worth auditing.

1. One question at a time. Never dump a numbered list and wait. Ask, get the answer, absorb, ask the next.
2. No offscreen research. If you dispatch an Explore / scout agent, paste a synthesis (3-5 bullets + contradictions + plan implications) in-chat BEFORE using it for anything.
3. No skipping to the plan. plan.md is written only after the user has explicitly confirmed the brief.
4. No auto-advance. Audit gates are user-facing checklists, not silent passes.
5. Visible deliverables. Every artifact (brief.md, research.md, plan.md) is summarized to the user in-chat when written.
6. Intermediate thinking is tight output, not monologue. Thirty words, then the next question.

Failure signatures to catch in yourself: about to write plan.md without user confirming brief; about to dispatch a research agent whose output will not be paraphrased back; about to say "Phase N complete, ready to build" in a turn where the user has not seen the intermediate findings.

MEMORY HOOK (every FRAME step)

At the start of every brainstorm or plan, call ijfw_memory_recall with the goal text when the memory tool is available. If it is unavailable, read the visible memory files under .ijfw/memory/ when possible; if neither is available, continue and say clean slate -- memory unavailable this turn.

I remember: decision from on -- <1-line summary>. Pull full context?

This is the single biggest superpower IJFW delivers. Never skip the attempt. If memory is empty, say so ("clean slate -- nothing recalled") so the silence is intentional, not absence of effort.

QUICK MODE -- 5 moves, 3-5 min

For focused work. Picks up from current context. Each move has ONE input slot.

Move 1 -- FRAME (45s)

• Assistant parses the goal from the ask or asks: Goal in one line.
• Memory hook fires. Assistant pastes up to 3 related recalls inline.
• Rewrite vague asks into verifiable goals before echoing back:
  • "Add validation" -> "Write tests for invalid inputs (empty, malformed, oversized), then make them pass."
  • "Fix the bug" -> "Write a failing test that reproduces the reported symptom, then make it pass."
  • "Refactor X" -> "Existing test suite passes before and after. No public API changes."
  • "Make it faster" -> "Benchmark the hot path, identify the bottleneck with profiling, change it, show the benchmark improved."
  • "Clean up the code" -> "Pick one specific smell. Fix only that. Diff fits in one commit message."
• If the ask cannot be reduced to a checkable outcome, surface that gap before proceeding.
• Assistant echoes: So: <concise goal>. Yes?
• User confirms or edits.

Move 2 -- WHY (30s)

• Assistant asks: Why does this matter? What's broken if we don't ship it?
• Single 5-Whys drill -- one follow-up question if the answer stays surface.
• Assistant surfaces the root motivation: Root: <X>. That means we should <design implication>.

Move 3 -- SHAPE (60s)

• Assistant proposes 3 approaches, each as 1 line + 1 tradeoff:

  A: -- tradeoff: B: -- tradeoff: C: -- tradeoff:

• User picks, hybrids, or overrides. No blank page, ever.

Move 4 -- STRESS (30s)

• Assistant runs a pre-mortem flash: Top risk: <concrete scenario>. Mitigation: <concrete fix>.
• User confirms mitigation or swaps.
• Sutherland wow: the risk the user hadn't thought of.

Move 5 -- LOCK (15s)

• Assistant pastes the brief in-chat (max 6 lines: goal / root / approach / risk / mitigation / success).
• User says one word: lock / fix <X> / go deeper.
• On lock: write .ijfw/memory/brief.md. Route straight to PLAN.

Quick-mode closer: You went from <original-ask> to locked brief with <N> risks mitigated in <M> minutes. Receipt for the work.

DEEP MODE -- 6 required modules + 3 optional

For substantial projects. Modules are a spine, not a checklist. Every module has a memory hook, a visible artifact, and a one-word commit.

Required spine

Module 1 -- FRAME (3 min)

• Memory recall on the goal keywords.
• Socratic arc: problem -> users -> constraints -> scope (in and out).
• One question per turn. Echo back every 3 turns to confirm understanding.
• Exit: Brief draft ready to review. Paste now? (y/edit)
• Artifact: .ijfw/memory/brief-draft.md (30 lines max). Promote to .ijfw/memory/brief.md only after LOCK.

Module 2 -- RECON (5-10 min)

• State the research questions in-chat first: I want to answer X, Y, Z -- okay?
• Dispatch scout / Explore agents with those questions (parallel where independent). If the current runtime has no agent-dispatch capability, do the research locally in separate labeled passes and record the limitation in .ijfw/memory/research.md.
• When agents return, paste synthesis in-chat: ask + answer + contradictions + plan implications.
• User reacts. Follow up if they push back.
• Artifact: .ijfw/memory/research.md (cleaned-up synthesis, not raw agent output).

Module 3 -- HMW (3 min)

• Assistant proposes 2-3 "How Might We" reframings based on FRAME + RECON.
• User picks one, rejects, or edits.
• The chosen HMW anchors DIVERGE.

Module 4 -- DIVERGE (8 min)

• Assistant sketches 4-5 approaches as 2-line bullets (shape + key tradeoff).
• User picks 2, rejects, or says hybrid A + C.
• No blank page. If user wants a 6th sketch, Assistant generates it on demand.

Module 5 -- CONVERGE (5 min)

• Assistant drafts success metrics / acceptance criteria from the chosen approach.
• Pre-mortem pass: Assistant generates 4-5 plausible failure scenarios.
• User picks top 2 risks. Assistant proposes mitigation for each.
• Artifact: metrics + risks + mitigations appended to brief.md.

Module 6 -- LOCK (2 min)

• Assistant pastes the full brief (goal / HMW / approach / metrics / risks / mitigations) in-chat.
• Optional Trident cross-critique fires here if ENABLED (see below).
• User says lock / fix <X> / skip Trident / route to plan.
• On lock: promote .ijfw/memory/brief-draft.md to .ijfw/memory/brief.md or write the confirmed brief there, then route to PLAN phase.

Optional modules (auto-triggered)

EXTERNAL BRIEF (5 min) -- mini PR/FAQ

Auto-triggers when: project has end-users, public launch, marketing surface, or user says "product". Writes a 2-paragraph press-release + 5-question FAQ. Forces customer-POV thinking.

ANTI-SCOPE (2 min) -- "what we won't do"

Auto-triggers when: 5+ candidate features surfaced in DIVERGE, or domain is feature-heavy (CRM, dashboards, admin panels). Assistant lists 5 things we could build but won't. User confirms or pulls one back in.

TRIDENT CROSS-CRITIQUE (~2 min) -- external model challenge

Auto-triggers when: new project, major refactor, public launch, or LOCK on brief > 20 lines. Fires ijfw cross critique <brief> in background. Surfaces consensus + contested findings. User decides. User override: skip Trident or force Trident at any LOCK.

POST-BRAINSTORM WORKFLOW

After LOCK, the brief drives every downstream phase. Same discipline, same memory hooks, same positive framing.

PLAN (after LOCK)

• Memory hook: recall past similar plans.
• Assistant drafts .ijfw/memory/plan.md (max 15 tasks for Quick, 30 for Deep).
• Each task: what / how-to-verify / file paths.
• User reviews. One-word commit: approve / trim / expand.

Design auto-fire -- if plan mentions UI, dashboard, component, page, layout, CSS, styles, content layout, brand system, document design, diagram, presentation, marketing surface, or another visual artifact:

• Deep mode: dispatch ijfw-design automatically before writing tasks. Log observation via bash scripts/design-pass.sh.
• Quick mode: offer I'll run a design pass first. Say "show me" to open it, or "skip" to continue. Wait for the user's next turn before starting visual companion work.
• Use ijfw design init when no DESIGN.md exists or the existing contract is stale.
• Use ijfw design plan before implementation tasks so the plan has durable visual scope, constraints, and success criteria.
• Use ijfw design audit or ijfw design critique at LOCK or before EXECUTE when visual quality, accessibility, brand fit, hierarchy, or audience fit carries risk.
• Use ijfw design polish, ijfw design normalize, ijfw design bolder, or ijfw design quieter during refinement, depending on whether the artifact needs quality pass, drift correction, stronger expression, or restraint.
• Use ijfw design handoff before VERIFY/SHIP when visual decisions need to survive context loss or platform handoff.
• Live companion commands (ijfw design start/open/status/stop/push/clear) are transient preview. DESIGN.md plus the durable design commands are the design memory.
• On completion: write .ijfw/design-pass.json sentinel for preflight gate.

Plan audit -- run ijfw plan-check or follow inline checklist, not silent:

• Every task has a verify step.
• No unstated assumptions.
• Scope matches brief (nothing new).
• Destructive ops flagged.
• User confirms before EXECUTE.

EXECUTE

Phase banner -- emit at every phase transition (Brainstorm, Plan, Execute, Verify, Ship):

IJFW > BRAINSTORM (Quick mode, step 2 of 5)
IJFW > PLAN (Deep mode, module 3 of 6)
IJFW > EXECUTE (Wave 2 of 4)

Team announcement -- at plan→execute transition, emit before dispatching agents:

Assembling team: [Opus] Architect, 2x [Sonnet] Builders, [Haiku] Scout
Dispatching Wave 1...

Swarm preparation (Deep mode or 2+ parallel agents):

• Before using swarm commands, run ijfw recover status to surface any existing checkpoint and ijfw blackboard init when the project has no blackboard yet.

• If no team exists, run ijfw team init first. Use --archetype <type> when the project type is known.

• In Codex-heavy projects, run ijfw codex doctor after team setup to confirm plugin metadata, hooks, MCP config, skills, AGENTS.md memory, and custom-agent surfaces are ready.

• Run ijfw codex sync-agents when .codex/agents/*.toml needs to be regenerated from the current Team Assembly charter.

• Run ijfw swarm plan to explain artifact owners, parallel/review/blocked waves, and verification.

• Run ijfw swarm prepare before dispatch, or ijfw swarm prepare --reviews when review tasks should be queued immediately. This writes .ijfw/blackboard/tasks.json.

• Run ijfw swarm tasks to list prepared task IDs. Tasks may represent code, design, research, writing, business artifacts, or other project work.

• Run ijfw swarm status and surface ready/blocked counts before assigning agents.

• Dispatch only tasks marked ready. For each dispatched task, run ijfw swarm start <task-id> before work begins.

• Generate a scoped dispatch brief before spawning a worker: ijfw swarm prompt <task-id>, or ijfw swarm prompt <task-id> --codex when the worker is a Codex subagent. Paste the generated prompt into the worker so artifact scope, allowed paths, dependencies, blackboard commands, verification, and non-revert rules travel with the task.

• Codex runtime caveat: some tool-backed Codex sessions expose only a generic spawn_agent interface, without direct named custom-agent invocation. IJFW still generates .codex/agents/*.toml; when named agents are not callable, paste the ijfw swarm prompt <task-id> --codex output into the built-in worker or explorer agent.

• On completion, run ijfw swarm complete <task-id>. If a task is blocked, run ijfw swarm block <task-id> --message <why> and escalate the blocker through claims, scope adjustment, or user decision.

• At each transition, create a durable safety point with ijfw memory checkpoint <label>. Use labels like after-team-init, after-swarm-prepare, after-wave-1, before-worktree-integrate, and before-ship.

• If context is lost, run ijfw recover status first, then ijfw recover latest for the last checkpoint body.

• Conservative worktree support (code-heavy tasks only by default):

  • Worktrees are optional execution isolation, not the coordination model. Use blackboard claims for writing, design, research, business, strategy, and other non-code artifacts.
  • Create a task worktree only after ijfw swarm start <task-id> has succeeded: ijfw swarm worktree create <task-id>.
  • Inspect active task worktrees with ijfw swarm worktree list before assigning or integrating parallel code work.
  • Before integration, run task verification in the worktree and create ijfw memory checkpoint before-worktree-integrate.
  • Integrate one completed task at a time with ijfw swarm worktree integrate <task-id>, then run wave-level verification in the main worktree.
  • Clean up only successful, verified integrations with ijfw swarm worktree cleanup <task-id>.
  • Preserve failed or blocked worktrees for inspection. Do not clean them up automatically.
  • Never auto-resolve merge conflicts. On any conflict, stop, record ijfw swarm block <task-id> --message <why>, and escalate to the user or lead agent.

• Dispatch per workflow manifest and blackboard task records.

• Use blackboard claims before parallel artifact edits: ijfw blackboard claim --artifact <id> --owner <agent> --paths <globs>.

• When the platform has a native task tracker, create one visible task per prepared blackboard task and keep it synchronized with start / complete / block.

• Mid-step pings for operations > 30s: <agent> in progress (~<estimate>).

• After each task: task micro-audit (6 points).

• Post-wave: update blackboard tasks/findings/blockers. Integrate worktrees only when worktrees were used. Conflicts halt + escalate without auto-resolution.

• No auto-advance to VERIFY. User confirms all tasks done.

Task micro-audit -- one line per task:

• Criteria met, scope clean, tests pass, no new assumptions.

Phase audit -- at wave/milestone boundaries:

• Brief still accurate? Speed respectful? Security invisible? Memory updated?

LIVE VISUAL COMPANION (UI/design projects, opt-in)

For visual software work -- HTML, app UI, dashboards, interfaces, landing pages, components, design systems -- offer a live preview before SHAPE: This is visual. Want me to open a live preview while we brainstorm?

yes runs ijfw design start, writes/pushes real HTML mockups with ijfw design push <file.html> [more.html ...], and keeps http://localhost:<port>/design open while options evolve. Use this for brainstorm variants, design choices, and implementation review. Durable visual identity still belongs in DESIGN.md; the live companion is the fast feedback loop.

For architecture-only visuals, use Mermaid in .ijfw/visual/<phase>.md. Skip visual companion for non-visual work where the brief and plan carry enough structure.

VERIFY

• Audit the result against the brief, not the plan. (Tasks can pass while brief goals miss.)
• Functional + UX + Security + Quality checklists.
• Optional Trident cross-audit on the diff: ijfw cross audit <diff>.
• User confirms: verified / gap: <X> / ship it.

SHIP

• Atomic commit with the brief's one-liner as the title, only after explicit user approval to commit.
• Optional Trident final critique: ijfw cross critique HEAD~1..HEAD (background).
• Before any tag, release, deploy, or publish action, read AGENTS.md/CLAUDE.md memory for release cautions and require explicit user approval.
• Tag / release notes / CHANGELOG entry only when this is a public ship and the release gate is clear.
• Memory write: decision + pattern + learning.
• Announcement copy -- user owns the channels, IJFW provides talking points.

Ship gate -- single pass:

• Diff matches brief. Tests green. Changelog updated. Memory stored. Trident receipt logged.

NARRATION (every transition)

One sentence at every phase entry and mid-step ping. Format:

Phase <name> -- Move <n> -- <what's happening>.

Examples:

• Brainstorm Quick -- Move 3 SHAPE -- proposing three approaches.
• Brainstorm Deep -- RECON -- dispatching two research agents.
• Plan -- drafting 12 tasks from brief.
• Execute -- wave 1/3 in progress (~4 min).
• Ship -- Trident critique running in background.

Model routing (mandatory): Before every agent dispatch, name the actual platform/model or role tier available in the current runtime, for example Routing to builder for implementation or Routing to Sonnet for this build when Claude tiers are available. Never dispatch silently.

No hardcoded phase numbers. Narration tracks the current workflow step, not historical plan-doc coordinates.

POSITIVE FRAMING (enforced everywhere)

Replace negatives with reframes for brainstorming, planning, and ordinary user-facing progress. Do not rewrite exact failure terminology in audit, CI, preflight, security, exception, test, or log contexts where precise status words are required.

End-of-phase closer is a receipt, not a report:

You went from <input> to <outcome> in <time>.

USER OVERRIDES (one-word commits)

The skill accepts these at any prompt:

• lock -- commit current artifact, advance.
• go deeper -- escalate Quick to Deep at the equivalent module.
• just quick -- collapse remaining Deep modules into one LOCK.
• skip <module> -- drop an optional module (Trident / External Brief / Anti-scope).
• force Trident -- run Trident cross-critique even on low-stakes LOCK.
• rollback -- revert to the prior module's artifact.
• help -- where am I + what's next.

TASK TRACKING USAGE (mandatory)

When the platform exposes native task tracking, create one task per specialist or prepared swarm task before dispatch. Mark in_progress when work starts, then completed or blocked as soon as each worker reports back. If no native tracker exists, use .ijfw/blackboard/tasks.json plus concise progress updates.

[Model] prefix required -- every task title includes the model tier:

[Haiku] Scout: explore auth module
[Sonnet] Build: implement login flow
[Opus] Audit: cross-audit Wave 1

The user must see real-time progress in the platform's native form. Use strikethrough task lists where supported; otherwise use concise status updates plus .ijfw/blackboard/tasks.json. Silent dispatch is a workflow violation.

Quick-mode minimum: 5 tasks (one per move). Deep-mode minimum: one per module + one per specialist + one per audit gate + ship gate. ~12-18 tasks per full run.

NAMING-GAP AUDIT (every turn)

Before emitting any "next step" text, scan for foreign plugin prefixes -- any <plugin>: pattern where <plugin> is not ijfw. If found as an action verb, rewrite to the IJFW-native equivalent or halt with: Rewrite needed -- foreign plugin verb detected.

Specialist swarm members (code-reviewer, silent-failure-hunter, pr-test-analyzer, type-design-analyzer) are allowed. Foreign plugin commands are not.

STATE FILE (Deep Mode)

Write .ijfw/state/workflow.json at every transition:

{
  "mode": "deep",
  "module": "HMW",
  "last_commit": "lock",
  "artifacts": ["brief.md", "research.md"],
  "next": "DIVERGE"
}

On session resume: read this file, echo the current state, offer continue / restart. Memory recall also fires on resume so context is live.

Invariant: every move the user experiences should make them feel smarter and more in control -- memory recall surfaces forgotten context, Assistant proposes before the user has to, Trident challenges before they commit, one word advances. Anything that makes them feel stupid or stuck is a workflow bug.