newaflux 1.1.0 → 1.3.0

package/README.md

@@ -1,8 +1,8 @@
-# ⚡ Newa Flux
+# Newa Flux
 
 Simplified multi-agent workflow framework for [Claude Code](https://claude.com/claude-code).
 
-**3 agents + 6 commands = 9 files.** That's it.
+**3 agents + 7 commands = 10 files.** That's it.
 
 ## Why?
 
@@ -10,11 +10,11 @@ Complex workflow frameworks turn a 1-hour bug fix into a 6-hour ordeal. Newa Flu
 
 | | Complex Frameworks | Newa Flux |
 |---|---|---|
-| Commands | 30+ | **6** |
+| Commands | 30+ | **7** |
 | Agents | 10+ | **3** |
 | Config files | Many | **0** |
 | CLI tools | Yes | **0** |
-| Total files | ~100+ | **9** |
+| Total files | ~100+ | **10** |
 
 ## Install
 
@@ -33,20 +33,21 @@ npx newaflux --uninstall  # Remove
 
 | Command | What it does |
 |---------|-------------|
-| `/fluxn:init` | Map your project with 4 parallel researchers → `PROJECT.md` |
+| `/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 |
 
 ## 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
+/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:
@@ -60,25 +61,52 @@ Or step by step:
 /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: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  |                      |
++---------------------+         +----------------------+
 ```
 
 ### 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-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.
 
 ### Project Files
 
@@ -86,13 +114,23 @@ All workflow state lives in `.fluxn/` at your project root:
 
 ```
 .fluxn/
-├── PROJECT.md          # Project map (persistent)
-├── STATE.md            # Current workflow state
-├── research/           # Research findings
-├── PLAN.md             # Execution plan with phases
-├── phases/             # Phase completion reports
-├── VERIFICATION.md     # Verification results
-└── MILESTONE.md        # Task summary for future sessions
++-- 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

package/agents/fluxn-executor.md

@@ -2,6 +2,7 @@
 name: fluxn-executor
 description: Executa fases do plano Newa Flux com commits atômicos. Spawned por /fluxn:execute.
 tools: Read, Write, Edit, Bash, Grep, Glob, WebSearch, WebFetch
+permissionMode: acceptEdits
 color: green
 ---
 
@@ -178,4 +179,6 @@ Before writing the phase report, verify:
 - **Build breaks** → Fix before proceeding. Never leave a broken build for the next phase.
 - **Unfamiliar pattern** → Read existing similar code in the project, follow the same pattern.
 
+**Language check:** Read `.fluxn/config.md` if it exists. If it contains a `**Language:**` setting, write this return summary in that language. Internal files (phase reports, code, commits) remain in English.
+
 Return a brief summary (~10 lines) to the orchestrator after writing the report.

package/agents/fluxn-researcher.md

@@ -2,6 +2,7 @@
 name: fluxn-researcher
 description: Pesquisa codebase e web para Newa Flux. Spawned por /fluxn:init e /fluxn:research.
 tools: Read, Bash, Grep, Glob, Write, WebSearch, WebFetch
+permissionMode: acceptEdits
 color: cyan
 ---
 
@@ -116,6 +117,8 @@ Before writing your output file, verify:
 
 # Return Message
 
+**Language check:** Read `.fluxn/config.md` if it exists. If it contains a `**Language:**` setting, write this return message in that language. The output file itself (research findings) remains in English.
+
 After writing the file, return ONLY a brief confirmation (~5-10 lines):
 ```
 File written: [path]

package/agents/fluxn-verifier.md

@@ -2,6 +2,7 @@
 name: fluxn-verifier
 description: Verificação READ-ONLY de implementação vs plano. Spawned por /fluxn:verify.
 tools: Read, Write, Bash, Grep, Glob
+permissionMode: acceptEdits
 color: yellow
 ---
 
@@ -168,4 +169,6 @@ Before writing reports, verify your own work:
 - **Files exist but appear empty/wrong** → Read and report actual state, compare to plan
 - **Ambiguous completion criterion** → Interpret strictly, note ambiguity
 
+**Language check:** Read `.fluxn/config.md` if it exists. If it contains a `**Language:**` setting, write this return summary in that language. Internal files (VERIFICATION.md, MILESTONE.md) remain in English.
+
 Return a brief summary (~10 lines) to the orchestrator with the overall result.

package/bin/install.js

@@ -4,8 +4,8 @@ const fs = require("fs");
 const path = require("path");
 const os = require("os");
 
-const VERSION = "1.0.0";
 const PACKAGE_DIR = path.resolve(__dirname, "..");
+const VERSION = require(path.join(PACKAGE_DIR, "package.json")).version;
 
 // --- Colors ---
 const c = {
@@ -32,6 +32,27 @@ function error(msg) {
   log(`${c.red}  ✗${c.reset} ${msg}`);
 }
 
+// --- Recommended permissions ---
+const RECOMMENDED_PERMISSIONS = [
+  "WebSearch",
+  "WebFetch",
+  "Task(fluxn-researcher)",
+  "Task(fluxn-executor)",
+  "Task(fluxn-verifier)",
+  "Bash(mkdir -p *)",
+  "Bash(rm -f .fluxn/*)",
+  "Bash(rm -rf .fluxn/init)",
+  "Bash(cp *)",
+  "Bash(ls *)",
+  "Bash(git status)",
+  "Bash(git log *)",
+  "Bash(git diff *)",
+  "Bash(git show *)",
+  "Bash(git add *)",
+  "Bash(git commit *)",
+  "Bash(npx *)",
+];
+
 // --- Args ---
 const args = process.argv.slice(2);
 const flags = new Set(args.map((a) => a.toLowerCase()));
@@ -39,6 +60,7 @@ const flags = new Set(args.map((a) => a.toLowerCase()));
 const isUninstall = flags.has("--uninstall") || flags.has("-u");
 const isLocal = flags.has("--local") || flags.has("-l");
 const isGlobal = flags.has("--global") || flags.has("-g");
+const isOptimized = flags.has("--optimized") || flags.has("-o");
 const isHelp = flags.has("--help") || flags.has("-h");
 
 if (isHelp) {
@@ -49,12 +71,14 @@ Simplified multi-agent workflow for Claude Code.
 ${c.bold}Usage:${c.reset}
   npx newaflux              Install globally (default)
   npx newaflux --local      Install in current project
+  npx newaflux --optimized  Install with optimized model profile
   npx newaflux --uninstall  Remove installation
   npx newaflux --help       Show this help
 
 ${c.bold}Options:${c.reset}
   -g, --global     Install to ~/.claude/ (all projects)
   -l, --local      Install to ./.claude/ (current project)
+  -o, --optimized  Set optimized model profile (sonnet/opus routing)
   -u, --uninstall  Remove Newa Flux files
   -h, --help       Show help
 `);
@@ -82,6 +106,8 @@ const COMMANDS = [
   "execute.md",
   "verify.md",
   "go.md",
+  "language.md",
+  "profile.md",
 ];
 
 // --- Copy helper ---
@@ -136,13 +162,70 @@ function install() {
     copied++;
   }
 
+  // Set optimized profile if requested
+  if (isOptimized) {
+    const fluxnDir = path.join(process.cwd(), ".fluxn");
+    if (!fs.existsSync(fluxnDir)) {
+      fs.mkdirSync(fluxnDir, { recursive: true });
+    }
+    const configPath = path.join(fluxnDir, "config.md");
+    let configContent = "# Newa Flux Config\n\n**Model Profile:** optimized\n";
+    if (fs.existsSync(configPath)) {
+      const existing = fs.readFileSync(configPath, "utf8");
+      const langMatch = existing.match(/^\*\*Language:\*\*.*$/m);
+      if (langMatch) {
+        configContent = "# Newa Flux Config\n\n" + langMatch[0] + "\n\n**Model Profile:** optimized\n";
+      }
+    }
+    fs.writeFileSync(configPath, configContent, "utf8");
+    success("Optimized profile set: researchers=sonnet, executor=opus, verifier=sonnet");
+  }
+
+  // Merge recommended permissions into settings.json
+  const settingsDir = isLocal
+    ? path.join(process.cwd(), ".claude")
+    : path.join(os.homedir(), ".claude");
+  const settingsPath = path.join(settingsDir, "settings.json");
+  let rulesAdded = 0;
+
+  try {
+    if (!fs.existsSync(settingsDir)) {
+      fs.mkdirSync(settingsDir, { recursive: true });
+    }
+
+    let settings = { permissions: { allow: [] } };
+    if (fs.existsSync(settingsPath)) {
+      const raw = fs.readFileSync(settingsPath, "utf8");
+      settings = JSON.parse(raw);
+      if (!settings.permissions) {
+        settings.permissions = {};
+      }
+      if (!Array.isArray(settings.permissions.allow)) {
+        settings.permissions.allow = [];
+      }
+    }
+
+    const existingRules = new Set(settings.permissions.allow);
+    for (const rule of RECOMMENDED_PERMISSIONS) {
+      if (!existingRules.has(rule)) {
+        settings.permissions.allow.push(rule);
+        rulesAdded++;
+      }
+    }
+
+    fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + "\n", "utf8");
+    success(`${rulesAdded} permission rules configured`);
+  } catch (err) {
+    warn(`Could not update settings.json: ${err.message}`);
+  }
+
   // Write version file
   const versionFile = path.join(targetDir, "newaflux-version.txt");
   fs.writeFileSync(versionFile, VERSION, "utf8");
 
   log("");
   log(
-    `  ${c.green}${c.bold}Done!${c.reset} ${copied}/9 files installed.`
+    `  ${c.green}${c.bold}Done!${c.reset} ${copied}/${AGENTS.length + COMMANDS.length} files installed.`
   );
   log("");
   log(`  ${c.bold}Commands available:${c.reset}`);
@@ -152,6 +235,8 @@ function install() {
   log(`    ${c.cyan}/fluxn:execute${c.reset}    Execute phases`);
   log(`    ${c.cyan}/fluxn:verify${c.reset}     Verify implementation`);
   log(`    ${c.cyan}/fluxn:go${c.reset}         Research + Plan in one shot`);
+  log(`    ${c.cyan}/fluxn:language${c.reset}   Set output language`);
+  log(`    ${c.cyan}/fluxn:profile${c.reset}    Switch model profile`);
   log("");
   log(
     `  ${c.dim}Start with: /fluxn:init in Claude Code${c.reset}`

package/commands/fluxn/execute.md

@@ -11,10 +11,13 @@ You are the **execution orchestrator** for Newa Flux. Your job: spawn a fresh `f
 
 ## Step 1: Load Context
 
+**Language check:** Read `.fluxn/config.md` if it exists. If it contains a `**Language:**` setting, use that language for ALL user-facing output (questions, confirmations, progress messages, routing messages). Internal files (STATE.md, phase reports) remain in English.
+
 Read these files:
-1. `.fluxn/PROJECT.md` — project map
-2. `.fluxn/STATE.md` — current state
-3. `.fluxn/PLAN.md` — the execution plan (must exist)
+1. `.fluxn/config.md` — language preference (if exists)
+2. `.fluxn/PROJECT.md` — project map
+3. `.fluxn/STATE.md` — current state
+4. `.fluxn/PLAN.md` — the execution plan (must exist)
 
 If PLAN.md doesn't exist, tell the user to run `/fluxn:plan` first.
 
@@ -40,6 +43,11 @@ mkdir -p .fluxn/phases
 
 ## Step 4: Execute Phase
 
+### Model Resolution
+Read `.fluxn/config.md`. If it contains `**Model Profile:** optimized`:
+- Add `model: "opus"` to the executor Task tool call below
+If `default` or no Model Profile line: do not pass model parameter.
+
 For the target phase, spawn ONE `fluxn-executor` agent:
 
 ```
@@ -94,10 +102,15 @@ Phases: [completed]/[total]
 
 ## Last Milestone
 [keep existing or "None"]
+
+## Milestone History
+[preserve existing Milestone History from previous STATE.md, or "None" if no history]
 ```
 
 ## Step 6: Route Next
 
+All routing messages below should be in the configured language from `.fluxn/config.md`, or English if not set.
+
 **If executing `all` and more phases remain:**
 - Read the phase-done.md just written (for context passing)
 - Go back to Step 4 for the next phase

package/commands/fluxn/go.md

@@ -19,7 +19,10 @@ If no arguments were provided, ask the user what they want to work on.
 
 ### 1.1: Load Context
 
+**Language check:** Read `.fluxn/config.md` if it exists. If it contains a `**Language:**` setting, use that language for ALL user-facing output (questions, confirmations, progress messages, the final report). Internal files (PLAN.md, STATE.md, research files) remain in English.
+
 Read these files if they exist:
+- `.fluxn/config.md` — language preference
 - `.fluxn/PROJECT.md` — project map (if missing, warn but continue)
 - `.fluxn/STATE.md` — current state
 
@@ -32,6 +35,33 @@ Classify based on the task description:
 
 Default to **feature** if ambiguous.
 
+### 1.2.5: Ask Clarifying Questions
+
+**If task type is `bug`:** skip this step entirely — proceed to 1.3.
+
+**If task type is `new-project`:** ask the user these questions (present them in the configured language):
+1. What is the scope of this project? (MVP, prototype, production-ready)
+2. Who are the target users or audience?
+3. Do you have a preferred tech stack or any technology constraints?
+4. What are the must-have features for the first version?
+5. Are there any hard constraints? (timeline, budget, platform, compliance)
+
+**If task type is `feature`:** ask the user these questions (present them in the configured language):
+1. What is the expected behavior of this feature? Describe the user flow or system behavior.
+2. Are there existing patterns or similar features in the codebase to follow?
+3. What are the acceptance criteria — how will you know this feature is done?
+4. What is the scope boundary — what should this feature explicitly NOT do?
+
+If PROJECT.md content is available, reference it to make questions more context-specific (e.g., mention existing tech stack, existing features, project conventions).
+
+After presenting the questions, tell the user: **"Type 'skip' to proceed without answering, or answer the questions above."**
+
+Wait for the user's response. Then:
+- If the user types "skip" (case-insensitive), set `userRequirements` to "User skipped clarifying questions." and proceed.
+- Otherwise, capture the user's answers as `userRequirements`.
+
+Store the answers — they will be written into STATE.md in 1.5 and passed to researcher agents in 1.4.
+
 ### 1.3: Setup
 
 ```bash
@@ -41,6 +71,11 @@ rm -f .fluxn/research/agent-*.md
 
 ### 1.4: Launch 4 Researchers in Parallel
 
+### Model Resolution
+Read `.fluxn/config.md`. If it contains `**Model Profile:** optimized`:
+- Add `model: "sonnet"` to each researcher Task tool call below
+If `default` or no Model Profile line: do not pass model parameter.
+
 Spawn 4 `fluxn-researcher` agents using the Task tool, ALL IN PARALLEL.
 
 **If new-project:**
@@ -78,15 +113,19 @@ TYPE: [codebase | web | hybrid]
 PROJECT CONTEXT:
 [PROJECT.md content or "No PROJECT.md — explore from scratch"]
 
+USER REQUIREMENTS:
+[paste userRequirements from 1.2.5, or "None — bug task, no clarifying questions asked."]
+
 SPECIFIC INSTRUCTIONS:
 [Investigation items for this focus area]
+[Incorporate any relevant user requirements into the investigation scope]
 
 Write findings to [file path]
 ```
 
 ### 1.5: Update STATE.md (after agents complete)
 
-Update `.fluxn/STATE.md` with status: researching, task info.
+Update `.fluxn/STATE.md` with status: researching, task info. Include a `## User Requirements` section with the `userRequirements` from 1.2.5 (the user's answers to clarifying questions, or "User skipped clarifying questions." if skipped, or "N/A — bug task." if task type is bug). Preserve the existing `## Milestone History` section from the previous STATE.md (or write "None" if no history exists).
 
 ---
 
@@ -98,7 +137,7 @@ Read all `.fluxn/research/agent-*.md` files that the researchers just created.
 
 ### 2.2: Synthesize and Plan
 
-From research findings, extract key decisions, approach, risks, dependencies.
+From research findings and the `## User Requirements` section in STATE.md (collected in 1.2.5), extract key decisions, approach, risks, dependencies. Use the user requirements to inform priorities, scope boundaries, and acceptance criteria in the plan.
 
 Break work into 2-6 phases following the same rules as `/fluxn:plan`:
 - Each phase completable by a fresh agent
@@ -158,13 +197,13 @@ Write `.fluxn/PLAN.md` using the standard plan template:
 
 ### 2.4: Update STATE.md
 
-Update `.fluxn/STATE.md` with status: planned, phase count.
+Update `.fluxn/STATE.md` with status: planned, phase count. Preserve the existing `## User Requirements` section and the existing `## Milestone History` section from the previous STATE.md (or write "None" if not present).
 
 ---
 
 ## PART 3: Report
 
-Tell the user:
+Tell the user (in the configured language from `.fluxn/config.md`, or English if not set):
 - Research + plan complete for: [task description]
 - Task type: [type]
 - Plan: [N] phases

package/commands/fluxn/init.md

@@ -9,6 +9,8 @@ You are the **init orchestrator** for Newa Flux. Your job: map the current proje
 
 ## Step 1: Check Existing State
 
+**Language check:** Read `.fluxn/config.md` if it exists. If it contains a `**Language:**` setting, use that language for ALL user-facing output (questions, confirmations, progress messages, the final report). Internal files (PROJECT.md, STATE.md, research files) remain in English.
+
 Check if `.fluxn/PROJECT.md` already exists.
 
 **If it exists:** Ask the user:
@@ -26,6 +28,11 @@ mkdir -p .fluxn/init
 
 ## Step 3: Launch 4 Researchers in Parallel
 
+### Model Resolution
+Read `.fluxn/config.md`. If it contains `**Model Profile:** optimized`:
+- Add `model: "sonnet"` to each researcher Task tool call below
+If `default` or no Model Profile line: do not pass model parameter.
+
 Spawn 4 `fluxn-researcher` agents using the Task tool, ALL IN PARALLEL (same message, 4 tool calls):
 
 ### Agent 1 — Tech Stack
@@ -204,6 +211,9 @@ None.
 
 ## Last Milestone
 None.
+
+## Milestone History
+None.
 ```
 
 ## Step 6: Cleanup
@@ -214,7 +224,7 @@ rm -rf .fluxn/init
 
 ## Step 7: Report
 
-Tell the user:
+Tell the user (in the configured language from `.fluxn/config.md`, or English if not set):
 - Project mapped successfully
 - Summary: [project name], [stack], [N concerns found]
 - Next step: Use `/fluxn:research <task description>` to start working on something, or `/fluxn:go <task>` for research + planning in one shot.

package/commands/fluxn/language.md

@@ -0,0 +1,52 @@
+---
+description: "Set language preference for Newa Flux output: /fluxn:language <language-code>"
+allowed-tools: Read, Write, Bash
+---
+
+# /fluxn:language — Set Language Preference
+
+$ARGUMENTS
+
+You are the **language configuration handler** for Newa Flux. Your job: set the user's preferred language for all user-facing output.
+
+## Step 1: Parse Argument
+
+The language code comes from the user's arguments: **$ARGUMENTS**
+
+If no arguments were provided, ask the user which language they want. Provide examples:
+- `en` — English
+- `pt` — Portuguese
+- `es` — Spanish
+- `fr` — French
+- `de` — German
+- `ja` — Japanese
+- `ko` — Korean
+- `zh` — Chinese
+- Or any valid language code
+
+## Step 2: Validate
+
+The argument should be a valid language code (e.g., `en`, `pt`, `es`, `fr`, `de`, `ja`, `ko`, `zh`). Accept any reasonable language code the user provides.
+
+## Step 3: Write Config
+
+```bash
+mkdir -p .fluxn
+```
+
+Write or update `.fluxn/config.md`:
+
+```markdown
+# Newa Flux Config
+**Language:** [language-code]
+```
+
+If `.fluxn/config.md` already exists, read it first and preserve any other settings. Only update the `**Language:**` line.
+
+## Step 4: Confirm
+
+Respond to the user **in the chosen language** confirming:
+- Language preference has been set to `[language-code]`
+- All future Newa Flux user-facing output will use this language
+- Internal files (research, plans, phase reports) remain in English
+- To change the language later, run `/fluxn:language <code>` again

package/commands/fluxn/plan.md

@@ -9,22 +9,29 @@ You are the **plan orchestrator** for Newa Flux. This runs INLINE (no sub-agents
 
 ## Step 1: Load All Context
 
+**Language check:** Read `.fluxn/config.md` if it exists. If it contains a `**Language:**` setting, use that language for ALL user-facing output (questions, confirmations, progress messages, the final report). Internal files (PLAN.md, STATE.md) remain in English.
+
 Read these files in order:
-1. `CLAUDE.md` — project rules (if exists)
-2. `.fluxn/PROJECT.md` — project map (if exists)
-3. `.fluxn/STATE.md` — current state (must exist, should show status: researching)
-4. ALL files matching `.fluxn/research/agent-*.md` — research findings
+1. `.fluxn/config.md` — language preference (if exists)
+2. `CLAUDE.md` — project rules (if exists)
+3. `.fluxn/PROJECT.md` — project map (if exists)
+4. `.fluxn/STATE.md` — current state (must exist, should show status: researching)
+5. ALL files matching `.fluxn/research/agent-*.md` — research findings
+
+From STATE.md, extract the `## User Requirements` section if it exists. These are the user's answers to clarifying questions asked during the research phase. They will be used as additional context during synthesis in Step 2 to inform priorities, scope, and acceptance criteria.
 
 If no research files exist, tell the user to run `/fluxn:research <task>` first.
 
 ## Step 2: Synthesize Research
 
-From all research findings, extract:
+From all research findings and the **User Requirements** (extracted from STATE.md in Step 1), extract:
 - **Key decisions** already made (e.g., "use library X", "follow pattern Y")
 - **Implementation approach** — the high-level strategy
 - **Risk areas** — what could go wrong
 - **Dependencies** — what needs to happen in order
 
+Use the User Requirements to inform priorities, scope boundaries, and acceptance criteria. If the user specified constraints (tech stack, timeline, must-have features), ensure the plan respects them.
+
 ## Step 3: Break Into Phases
 
 Divide the work into **2-6 phases**. Rules:
@@ -120,16 +127,22 @@ Update `.fluxn/STATE.md`:
 Type: [type]
 Phases: [N]
 
+## User Requirements
+[preserve existing User Requirements from previous STATE.md, or "None" if not present]
+
 ## Blockers
 None.
 
 ## Last Milestone
 [keep existing or "None"]
+
+## Milestone History
+[preserve existing Milestone History from previous STATE.md, or "None" if no history]
 ```
 
 ## Step 6: Report
 
-Present to the user:
+Present to the user (in the configured language from `.fluxn/config.md`, or English if not set):
 - Plan created with [N] phases
 - Brief summary of each phase (1 line each)
 - The checkpoint summary table

package/commands/fluxn/profile.md

@@ -0,0 +1,83 @@
+---
+description: "Switch model profile (default/optimized): /fluxn:profile [default | optimized]"
+allowed-tools: Read, Write, Edit, Bash, Grep, Glob
+---
+
+# /fluxn:profile — Model Profile Configuration
+
+$ARGUMENTS
+
+You are the **model profile handler** for Newa Flux. Your job: show or switch the active model profile that controls which AI models are assigned to each agent.
+
+## Step 1: Load Context
+
+**Language check:** Read `.fluxn/config.md` if it exists. If it contains a `**Language:**` setting, use that language for ALL user-facing output (confirmations, tables, status messages). Internal files (config.md) remain in English.
+
+Read `.fluxn/config.md` if it exists. Look for the `**Model Profile:**` line to determine the current profile.
+
+If the file does not exist or has no `**Model Profile:**` line, the current profile is `default`.
+
+## Step 2: Parse Argument
+
+The profile argument comes from the user's arguments: **$ARGUMENTS**
+
+Valid values:
+- `default` — all agents inherit the parent model (no model parameter passed)
+- `optimized` — assigns specific models per agent for cost/speed optimization
+
+If the argument is not `default` or `optimized` and is not empty, tell the user the argument is invalid and show the two valid options.
+
+## Step 3: Show or Update
+
+### If no argument was provided
+
+Show the current profile status and the model assignment table for that profile. Do not modify any files.
+
+### If an argument was provided
+
+Update `.fluxn/config.md`:
+
+```bash
+mkdir -p .fluxn
+```
+
+- If `.fluxn/config.md` does not exist, create it with the profile setting.
+- If it exists, read it first and add or replace the `**Model Profile:**` line. Preserve all other settings (e.g., `**Language:**`).
+
+The `**Model Profile:**` line format:
+```
+**Model Profile:** [default | optimized]
+```
+
+## Step 4: Display Profile Table
+
+Show the user (in the configured language) the model assignment table for the active profile:
+
+### Default Profile
+
+| Role | Agent | Model |
+|------|-------|-------|
+| Researcher | fluxn-researcher | inherit (parent model) |
+| Executor | fluxn-executor | inherit (parent model) |
+| Verifier | fluxn-verifier | inherit (parent model) |
+| Plan | inline (orchestrator) | inherit (parent model) |
+
+All agents use the same model as the parent Claude Code session. No `model` parameter is passed to Task tool calls.
+
+### Optimized Profile
+
+| Role | Agent | Model |
+|------|-------|-------|
+| Researcher | fluxn-researcher | sonnet |
+| Executor | fluxn-executor | opus |
+| Verifier | fluxn-verifier | sonnet |
+| Plan | inline (orchestrator) | inherit (parent model) |
+
+Researchers and verifier use Sonnet for speed and cost savings. Executor uses Opus for maximum code quality. Planning runs inline and inherits the parent model.
+
+## Step 5: Confirm
+
+Tell the user (in the configured language):
+- Current profile: `[profile name]`
+- If they just changed it: "Profile updated. The new model assignments will apply to all future agent spawns."
+- If they just viewed it: "To switch profiles, run `/fluxn:profile default` or `/fluxn:profile optimized`."

package/commands/fluxn/research.md

@@ -11,7 +11,10 @@ You are the **research orchestrator** for Newa Flux. Your job: classify the task
 
 ## Step 1: Load Context
 
+**Language check:** Read `.fluxn/config.md` if it exists. If it contains a `**Language:**` setting, use that language for ALL user-facing output (questions, confirmations, progress messages, the final report). Internal files (STATE.md, research files) remain in English.
+
 Read these files if they exist:
+- `.fluxn/config.md` — language preference
 - `.fluxn/PROJECT.md` — project map (if missing, suggest running `/fluxn:init` first)
 - `.fluxn/STATE.md` — current state
 
@@ -28,6 +31,33 @@ Based on the task description, classify as one of:
 
 If ambiguous, default to **feature**.
 
+## Step 2.5: Ask Clarifying Questions
+
+**If task type is `bug`:** skip this step entirely — proceed to Step 3.
+
+**If task type is `new-project`:** ask the user these questions (present them in the configured language):
+1. What is the scope of this project? (MVP, prototype, production-ready)
+2. Who are the target users or audience?
+3. Do you have a preferred tech stack or any technology constraints?
+4. What are the must-have features for the first version?
+5. Are there any hard constraints? (timeline, budget, platform, compliance)
+
+**If task type is `feature`:** ask the user these questions (present them in the configured language):
+1. What is the expected behavior of this feature? Describe the user flow or system behavior.
+2. Are there existing patterns or similar features in the codebase to follow?
+3. What are the acceptance criteria — how will you know this feature is done?
+4. What is the scope boundary — what should this feature explicitly NOT do?
+
+If PROJECT.md content is available, reference it to make questions more context-specific (e.g., mention existing tech stack, existing features, project conventions).
+
+After presenting the questions, tell the user: **"Type 'skip' to proceed without answering, or answer the questions above."**
+
+Wait for the user's response. Then:
+- If the user types "skip" (case-insensitive), set `userRequirements` to "User skipped clarifying questions." and proceed.
+- Otherwise, capture the user's answers as `userRequirements`.
+
+Store the answers — they will be written into STATE.md in Step 5 and passed to researcher agents in Step 4.
+
 ## Step 3: Setup
 
 ```bash
@@ -41,6 +71,11 @@ rm -f .fluxn/research/agent-*.md
 
 ## Step 4: Launch 4 Researchers in Parallel
 
+### Model Resolution
+Read `.fluxn/config.md`. If it contains `**Model Profile:** optimized`:
+- Add `model: "sonnet"` to each researcher Task tool call below
+If `default` or no Model Profile line: do not pass model parameter.
+
 Spawn 4 `fluxn-researcher` agents using the Task tool, ALL IN PARALLEL.
 
 Each agent receives PROJECT.md content as base context in their prompt.
@@ -88,8 +123,12 @@ TYPE: [codebase | web | hybrid]
 PROJECT CONTEXT:
 [paste PROJECT.md content here, or "No PROJECT.md yet — explore from scratch"]
 
+USER REQUIREMENTS:
+[paste userRequirements from Step 2.5, or "None — bug task, no clarifying questions asked."]
+
 SPECIFIC INSTRUCTIONS:
 [Specific investigation items for this focus area based on the task]
+[Incorporate any relevant user requirements into the investigation scope]
 
 Write your findings to [output file path]
 ```
@@ -112,16 +151,22 @@ Update `.fluxn/STATE.md`:
 Type: [new-project | bug | feature]
 Research agents: 4 (parallel)
 
+## User Requirements
+[paste userRequirements from Step 2.5 here — the user's answers to clarifying questions, or "User skipped clarifying questions." if skipped, or "N/A — bug task." if task type is bug]
+
 ## Blockers
 None.
 
 ## Last Milestone
 [keep existing or "None"]
+
+## Milestone History
+[preserve existing Milestone History from previous STATE.md, or "None" if no history]
 ```
 
 ## Step 6: Report
 
-After all 4 agents complete, tell the user:
+After all 4 agents complete, tell the user (in the configured language from `.fluxn/config.md`, or English if not set):
 - Research complete for: [task description]
 - Task type: [type]
 - 4 research documents in `.fluxn/research/`

package/commands/fluxn/verify.md

@@ -9,17 +9,25 @@ You are the **verification orchestrator** for Newa Flux. Your job: spawn a read-
 
 ## Step 1: Load Context
 
+**Language check:** Read `.fluxn/config.md` if it exists. If it contains a `**Language:**` setting, use that language for ALL user-facing output (questions, confirmations, result reports). Internal files (VERIFICATION.md, MILESTONE.md, STATE.md) remain in English.
+
 Read these files:
-1. `.fluxn/PLAN.md` — the plan (must exist)
-2. `.fluxn/PROJECT.md` — project map
-3. `.fluxn/STATE.md` — current state
-4. All `.fluxn/phases/phase-*-done.md` files — phase reports
+1. `.fluxn/config.md` — language preference (if exists)
+2. `.fluxn/PLAN.md` — the plan (must exist)
+3. `.fluxn/PROJECT.md` — project map
+4. `.fluxn/STATE.md` — current state
+5. All `.fluxn/phases/phase-*-done.md` files — phase reports
 
 If PLAN.md doesn't exist, tell the user there's nothing to verify.
 If no phase-done.md files exist, tell the user to run `/fluxn:execute` first.
 
 ## Step 2: Spawn Verifier
 
+### Model Resolution
+Read `.fluxn/config.md`. If it contains `**Model Profile:** optimized`:
+- Add `model: "sonnet"` to the verifier Task tool call below
+If `default` or no Model Profile line: do not pass model parameter.
+
 Spawn ONE `fluxn-verifier` agent:
 
 ```
@@ -47,9 +55,106 @@ prompt: |
   5. Return: overall result (PASSED/WARNINGS/FAILED) and key findings
 ```
 
-## Step 3: Update STATE.md
+## Step 3: Archive Milestone
+
+**Only run this step if verification result is PASSED or PASSED WITH WARNINGS.** Skip entirely on FAILED.
+
+### 3.1: Create Archive Folder
+
+1. Create `.fluxn/milestones/` directory if it doesn't exist
+2. Generate a timestamped archive folder name: `.fluxn/milestones/YYYY-MM-DD-<slug>/`
+   - `YYYY-MM-DD` = today's date
+   - `<slug>` = task description from STATE.md, kebab-cased (lowercase, spaces/special chars to hyphens), max 40 characters, trimmed at word boundary
+
+```bash
+mkdir -p .fluxn/milestones/YYYY-MM-DD-<slug>
+```
+
+### 3.2: Copy Artifacts to Archive
+
+Copy the following files into the archive folder:
+- `.fluxn/PLAN.md` → archive folder
+- `.fluxn/VERIFICATION.md` → archive folder
+- `.fluxn/MILESTONE.md` → archive folder
+- `.fluxn/STATE.md` → archive folder (as a snapshot of the final state)
+- All files from `.fluxn/research/` → `archive-folder/research/`
+- All files from `.fluxn/phases/` → `archive-folder/phases/`
+
+```bash
+cp .fluxn/PLAN.md .fluxn/milestones/YYYY-MM-DD-<slug>/
+cp .fluxn/VERIFICATION.md .fluxn/milestones/YYYY-MM-DD-<slug>/
+cp .fluxn/MILESTONE.md .fluxn/milestones/YYYY-MM-DD-<slug>/
+cp .fluxn/STATE.md .fluxn/milestones/YYYY-MM-DD-<slug>/
+mkdir -p .fluxn/milestones/YYYY-MM-DD-<slug>/research
+cp .fluxn/research/* .fluxn/milestones/YYYY-MM-DD-<slug>/research/ 2>/dev/null || true
+mkdir -p .fluxn/milestones/YYYY-MM-DD-<slug>/phases
+cp .fluxn/phases/* .fluxn/milestones/YYYY-MM-DD-<slug>/phases/ 2>/dev/null || true
+```
+
+### 3.3: Update INDEX.md
+
+Append an entry to `.fluxn/milestones/INDEX.md` (create the file with a header if it doesn't exist):
+
+If the file doesn't exist yet, write:
+```markdown
+# Milestone Index
+
+| Date | Task | Result | Archive Path |
+|------|------|--------|--------------|
+| YYYY-MM-DD | [task description] | [PASSED/PASSED WITH WARNINGS] | `.fluxn/milestones/YYYY-MM-DD-<slug>/` |
+```
+
+If the file already exists, append a new row to the table:
+```
+| YYYY-MM-DD | [task description] | [PASSED/PASSED WITH WARNINGS] | `.fluxn/milestones/YYYY-MM-DD-<slug>/` |
+```
+
+### 3.4: Clean Working Files
+
+Remove the working files that have been archived:
+
+```bash
+rm -f .fluxn/PLAN.md
+rm -f .fluxn/VERIFICATION.md
+rm -f .fluxn/MILESTONE.md
+rm -f .fluxn/research/*
+rm -f .fluxn/phases/*
+```
+
+Keep the empty `.fluxn/research/` and `.fluxn/phases/` directories — do NOT delete them.
+
+## Step 4: Update STATE.md
+
+After verifier completes (and after archiving if applicable), update `.fluxn/STATE.md`.
+
+Read `.fluxn/milestones/INDEX.md` if it exists to build the Milestone History section.
+
+**If verification PASSED or PASSED WITH WARNINGS** (archive was created):
+
+```markdown
+# Newa Flux State
+**Project:** [project name]
+**Task:** None
+**Status:** idle
+**Phase:** N/A
+**Last activity:** [today's date] — Verification: [PASSED|PASSED WITH WARNINGS]
+
+## Current Task
+No active task.
+
+## Blockers
+None.
 
-After verifier completes, update `.fluxn/STATE.md`:
+## Last Milestone
+[today's date] — [task description] — [result]
+Archived to `.fluxn/milestones/YYYY-MM-DD-<slug>/`
+
+## Milestone History
+[Copy ALL rows from `.fluxn/milestones/INDEX.md` table here, or list each entry as:]
+- YYYY-MM-DD — [task] — [result] — `.fluxn/milestones/YYYY-MM-DD-<slug>/`
+```
+
+**If verification FAILED** (no archive created):
 
 ```markdown
 # Newa Flux State
@@ -57,7 +162,7 @@ After verifier completes, update `.fluxn/STATE.md`:
 **Task:** [task description]
 **Status:** idle
 **Phase:** [completed]/[total]
-**Last activity:** [today's date] — Verification: [PASSED|WARNINGS|FAILED]
+**Last activity:** [today's date] — Verification: FAILED
 
 ## Current Task
 Completed: [task description]
@@ -66,15 +171,17 @@ Completed: [task description]
 None.
 
 ## Last Milestone
-[today's date] — [task description] — [result]
-See .fluxn/MILESTONE.md
+[keep existing from previous STATE.md]
+
+## Milestone History
+[preserve existing Milestone History from previous STATE.md, or "None" if empty]
 ```
 
-## Step 4: Report
+## Step 5: Report
 
-Tell the user:
+Tell the user (in the configured language from `.fluxn/config.md`, or English if not set):
 - **Result**: PASSED / PASSED WITH WARNINGS / FAILED
 - **Summary**: Key findings from the verification (read from verifier's return message)
-- **If PASSED**: "Task complete! Milestone saved to `.fluxn/MILESTONE.md`. Start a new task with `/fluxn:research <task>` or `/fluxn:go <task>`."
-- **If WARNINGS**: List warnings. "Task is mostly complete. Review warnings in `.fluxn/VERIFICATION.md`."
+- **If PASSED**: "Task complete! Milestone archived to `.fluxn/milestones/YYYY-MM-DD-<slug>/`. Start a new task with `/fluxn:research <task>` or `/fluxn:go <task>`."
+- **If WARNINGS**: List warnings. "Task archived to `.fluxn/milestones/YYYY-MM-DD-<slug>/` with warnings. Review details in the archive's VERIFICATION.md."
 - **If FAILED**: List failures. "Some criteria were not met. Review `.fluxn/VERIFICATION.md` for details. Fix issues and re-run `/fluxn:execute` for failed phases, then `/fluxn:verify` again."

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "newaflux",
-  "version": "1.1.0",
-  "description": "Simplified multi-agent workflow framework for Claude Code. 3 agents + 6 commands = 9 files.",
+  "version": "1.3.0",
+  "description": "Simplified multi-agent workflow framework for Claude Code. 3 agents + 7 commands = 10 files.",
   "bin": {
     "newaflux": "bin/install.js"
   },