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 <project> on <date> -- <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: <approach> -- tradeoff: <cost> B: <approach> -- tradeoff: <cost> C: <approach> -- tradeoff: <cost>

• 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.