Newa Flux

Simplified multi-agent workflow framework for Claude Code.

4 agents + 9 commands = 13 files. That's it.

Why?

Complex workflow frameworks turn a 1-hour bug fix into a 6-hour ordeal. Newa Flux keeps the benefits of multi-agent workflows (parallel research, clean context, handoffs) with minimal complexity.

| | Complex Frameworks | Newa Flux | |---|---|---| | Commands | 30+ | 9 | | Agents | 10+ | 4 | | Config files | Many | 0 | | CLI tools | Yes | 0 | | Total files | ~100+ | 13 |

Install

npx newaflux

Options:

npx newaflux --global     # All projects (default)
npx newaflux --local      # Current project only
npx newaflux --uninstall  # Remove

Commands

| Command | What it does | |---------|-------------| | /fluxn:init | Map your project with 4 parallel researchers -> PROJECT.md | | /fluxn:research <task> | Research a task with 4 focused agents | | /fluxn:plan | Synthesize research into phased execution plan | | /fluxn:execute [phase] | Execute phases with atomic commits | | /fluxn:verify | Read-only verification of implementation vs plan | | /fluxn:go <task> | Research + Plan in one shot | | /fluxn:language <code> | Set output language for all user-facing messages | | /fluxn:profile | Switch model profile (default/optimized) | | /fluxn:debug <bug> | Investigate and fix bugs with scientific debugging |

Workflow

/fluxn:init          -> Maps your project (run once)
/fluxn:go <task>     -> Research + Plan (or run separately)
/fluxn:execute all   -> Execute all phases
/fluxn:verify        -> Verify everything works

Or step by step:

/fluxn:init
/fluxn:research fix the auth bug
/fluxn:plan
/fluxn:execute 1
/fluxn:execute 2
/fluxn:verify

Features

Language Support

Set a preferred language for all user-facing output (progress messages, confirmations, reports):

/fluxn:language pt

Supports any valid language code (en, pt, es, fr, de, ja, ko, zh, etc.). Internal workflow files (research, plans, phase reports) remain in English for consistency. The preference is stored in .fluxn/config.md and respected by all commands and agents.

Clarifying Questions

During the research phase (/fluxn:research or /fluxn:go), the framework asks clarifying questions based on the task type:

• New project: 5 questions about scope, audience, tech stack, must-have features, and constraints
• Feature: 4 questions about expected behavior, existing patterns, acceptance criteria, and scope boundaries
• Bug fix: Skips questions entirely to get to the fix faster

You can type skip to bypass questions and proceed directly. Answers are stored in STATE.md and used to inform the execution plan.

Milestone Archiving

When /fluxn:verify passes, the entire workflow (plan, research, phases, verification) is automatically archived to .fluxn/milestones/YYYY-MM-DD-<slug>/. This keeps a full history of completed tasks without cluttering the working directory. An append-only INDEX.md in the milestones folder tracks all archived milestones.

Architecture

Commands (orchestrators)         Agents (specialized workers)
+---------------------+         +----------------------+
| /fluxn:init         |-------->| fluxn-researcher (x4)|
| /fluxn:research     |-------->| fluxn-researcher (x4)|
| /fluxn:plan         | inline  |                      |
| /fluxn:execute      |-------->| fluxn-executor   (x1)|
| /fluxn:verify       |-------->| fluxn-verifier   (x1)|
| /fluxn:go           |-------->| researcher + inline  |
| /fluxn:language     | inline  |                      |
| /fluxn:profile      | inline  |                      |
| /fluxn:debug        |-------->| fluxn-debugger   (x1)|
+---------------------+         +----------------------+

Agents

• fluxn-researcher -- Explores codebase and web. Used by init, research, and go. Has WebSearch/WebFetch.
• fluxn-executor -- Implements one phase with atomic commits. Has all editing tools. Follows commit protocol.
• fluxn-verifier -- Read-only verification. No Edit tool. Cannot modify code to "pass" checks.
• fluxn-debugger -- Scientific bug investigator. Forms hypotheses, gathers evidence, eliminates possibilities. Supports browser automation via Playwright MCP.

Project Files

All workflow state lives in .fluxn/ at your project root:

.fluxn/
+-- PROJECT.md          # Project map (persistent)
+-- STATE.md            # Current workflow state
+-- config.md           # User preferences (language, etc.)
+-- research/           # Research findings
+-- PLAN.md             # Execution plan with phases
+-- phases/             # Phase completion reports
+-- VERIFICATION.md     # Verification results
+-- MILESTONE.md        # Task summary for future sessions
+-- milestones/         # Archived milestones
    +-- INDEX.md        # Append-only milestone index
    +-- YYYY-MM-DD-slug/  # One folder per completed task
        +-- PLAN.md
        +-- VERIFICATION.md
        +-- MILESTONE.md
        +-- STATE.md
        +-- research/
        +-- phases/

Requirements

• Claude Code CLI
• Node.js >= 16

License

MIT