newaflux 1.0.0

package/bin/install.js

@@ -0,0 +1,216 @@
+#!/usr/bin/env node
+
+const fs = require("fs");
+const path = require("path");
+const os = require("os");
+
+const VERSION = "1.0.0";
+const PACKAGE_DIR = path.resolve(__dirname, "..");
+
+// --- Colors ---
+const c = {
+  reset: "\x1b[0m",
+  bold: "\x1b[1m",
+  dim: "\x1b[2m",
+  green: "\x1b[32m",
+  cyan: "\x1b[36m",
+  yellow: "\x1b[33m",
+  red: "\x1b[31m",
+  magenta: "\x1b[35m",
+};
+
+function log(msg) {
+  console.log(msg);
+}
+function success(msg) {
+  log(`${c.green}  ✓${c.reset} ${msg}`);
+}
+function warn(msg) {
+  log(`${c.yellow}  !${c.reset} ${msg}`);
+}
+function error(msg) {
+  log(`${c.red}  ✗${c.reset} ${msg}`);
+}
+
+// --- Args ---
+const args = process.argv.slice(2);
+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 isHelp = flags.has("--help") || flags.has("-h");
+
+if (isHelp) {
+  log(`
+${c.bold}${c.cyan}Newa Flux${c.reset} v${VERSION}
+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 --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)
+  -u, --uninstall  Remove Newa Flux files
+  -h, --help       Show help
+`);
+  process.exit(0);
+}
+
+// --- Determine target ---
+function getTargetDir() {
+  if (isLocal) {
+    return path.join(process.cwd(), ".claude");
+  }
+  return path.join(os.homedir(), ".claude");
+}
+
+const targetDir = getTargetDir();
+const scope = isLocal ? "local" : "global";
+
+// --- File manifest ---
+const AGENTS = ["fluxn-researcher.md", "fluxn-executor.md", "fluxn-verifier.md"];
+
+const COMMANDS = [
+  "init.md",
+  "research.md",
+  "plan.md",
+  "execute.md",
+  "verify.md",
+  "go.md",
+];
+
+// --- Copy helper ---
+function copyFile(src, dest) {
+  const destDir = path.dirname(dest);
+  if (!fs.existsSync(destDir)) {
+    fs.mkdirSync(destDir, { recursive: true });
+  }
+  fs.copyFileSync(src, dest);
+}
+
+// --- Install ---
+function install() {
+  log("");
+  log(
+    `${c.bold}${c.cyan}  ⚡ Newa Flux${c.reset} ${c.dim}v${VERSION}${c.reset}`
+  );
+  log(
+    `${c.dim}  Simplified multi-agent workflow for Claude Code${c.reset}`
+  );
+  log("");
+  log(`  Installing ${c.bold}${scope}${c.reset} → ${c.dim}${targetDir}${c.reset}`);
+  log("");
+
+  let copied = 0;
+
+  // Copy agents
+  const agentsDir = path.join(targetDir, "agents");
+  for (const file of AGENTS) {
+    const src = path.join(PACKAGE_DIR, "agents", file);
+    const dest = path.join(agentsDir, file);
+    if (!fs.existsSync(src)) {
+      error(`Source not found: ${file}`);
+      continue;
+    }
+    copyFile(src, dest);
+    success(`agents/${file}`);
+    copied++;
+  }
+
+  // Copy commands
+  const commandsDir = path.join(targetDir, "commands", "fluxn");
+  for (const file of COMMANDS) {
+    const src = path.join(PACKAGE_DIR, "commands", "fluxn", file);
+    const dest = path.join(commandsDir, file);
+    if (!fs.existsSync(src)) {
+      error(`Source not found: ${file}`);
+      continue;
+    }
+    copyFile(src, dest);
+    success(`commands/fluxn/${file}`);
+    copied++;
+  }
+
+  // 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.`
+  );
+  log("");
+  log(`  ${c.bold}Commands available:${c.reset}`);
+  log(`    ${c.cyan}/fluxn:init${c.reset}       Map your project`);
+  log(`    ${c.cyan}/fluxn:research${c.reset}   Research a task`);
+  log(`    ${c.cyan}/fluxn:plan${c.reset}       Create execution plan`);
+  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("");
+  log(
+    `  ${c.dim}Start with: /fluxn:init in Claude Code${c.reset}`
+  );
+  log("");
+}
+
+// --- Uninstall ---
+function uninstall() {
+  log("");
+  log(`${c.bold}${c.yellow}  Uninstalling Newa Flux${c.reset} (${scope})`);
+  log("");
+
+  let removed = 0;
+
+  // Remove agents
+  for (const file of AGENTS) {
+    const fp = path.join(targetDir, "agents", file);
+    if (fs.existsSync(fp)) {
+      fs.unlinkSync(fp);
+      success(`Removed agents/${file}`);
+      removed++;
+    }
+  }
+
+  // Remove commands dir
+  const commandsDir = path.join(targetDir, "commands", "fluxn");
+  if (fs.existsSync(commandsDir)) {
+    for (const file of COMMANDS) {
+      const fp = path.join(commandsDir, file);
+      if (fs.existsSync(fp)) {
+        fs.unlinkSync(fp);
+        success(`Removed commands/fluxn/${file}`);
+        removed++;
+      }
+    }
+    // Remove fluxn dir if empty
+    try {
+      fs.rmdirSync(commandsDir);
+      success("Removed commands/fluxn/");
+    } catch {
+      // not empty, that's fine
+    }
+  }
+
+  // Remove version file
+  const versionFile = path.join(targetDir, "newaflux-version.txt");
+  if (fs.existsSync(versionFile)) {
+    fs.unlinkSync(versionFile);
+  }
+
+  log("");
+  log(`  ${c.green}${c.bold}Done!${c.reset} ${removed} files removed.`);
+  log("");
+}
+
+// --- Run ---
+if (isUninstall) {
+  uninstall();
+} else {
+  install();
+}

package/commands/fluxn/execute.md

@@ -0,0 +1,114 @@
+---
+description: "Execute plan phases: /fluxn:execute [phase-number | all]"
+allowed-tools: Read, Write, Edit, Bash, Grep, Glob, Task
+---
+
+# /fluxn:execute — Phase Execution
+
+$ARGUMENTS
+
+You are the **execution orchestrator** for Newa Flux. Your job: spawn a fresh `fluxn-executor` agent for each phase, providing it with full context to work independently.
+
+## Step 1: Load Context
+
+Read these files:
+1. `.fluxn/PROJECT.md` — project map
+2. `.fluxn/STATE.md` — current state
+3. `.fluxn/PLAN.md` — the execution plan (must exist)
+
+If PLAN.md doesn't exist, tell the user to run `/fluxn:plan` first.
+
+## Step 2: Determine Target Phase
+
+Parse the argument from **$ARGUMENTS**:
+- **A number** (e.g., `1`, `3`): execute that specific phase
+- **`all`**: execute all pending phases sequentially
+- **Empty/no argument**: find the next pending phase from the Checkpoint Summary table in PLAN.md
+
+If all phases are already done, tell the user and suggest `/fluxn:verify`.
+
+## Step 3: Load Previous Phase Context
+
+Read all existing `.fluxn/phases/phase-*-done.md` files. These contain:
+- What was built in previous phases
+- Handoff context for the current phase
+- Any deviations or issues from previous phases
+
+```bash
+mkdir -p .fluxn/phases
+```
+
+## Step 4: Execute Phase
+
+For the target phase, spawn ONE `fluxn-executor` agent:
+
+```
+subagent_type: "fluxn-executor"
+prompt: |
+  # Execute Phase [N]: [Phase Name]
+
+  ## Project Rules (CLAUDE.md)
+  [paste CLAUDE.md content, or "No CLAUDE.md found"]
+
+  ## Project Context (PROJECT.md)
+  [paste PROJECT.md content]
+
+  ## Previous Phases
+  [paste all phase-done.md summaries, or "This is the first phase"]
+
+  ## Your Phase
+  [paste the EXACT phase content from PLAN.md — Goal, Tasks, Files, Verification, Context]
+
+  ## Instructions
+  1. Execute all tasks in this phase
+  2. Commit after each logical unit (follow commit protocol)
+  3. Run all verification checks
+  4. Write your report to: .fluxn/phases/phase-[N]-done.md
+  5. Return a brief summary
+```
+
+## Step 5: Update State After Phase Completes
+
+After the executor finishes:
+
+### Update PLAN.md Checkpoint Summary
+Change the phase's status from `pending` to `done` in the Checkpoint Summary table.
+Use Edit tool to update just that line.
+
+### Update STATE.md
+```markdown
+# Newa Flux State
+**Project:** [project name]
+**Task:** [task description]
+**Status:** executing
+**Phase:** [completed]/[total]
+**Last activity:** [today's date] — Phase [N] completed: [phase name]
+
+## Current Task
+[task description]
+Type: [type]
+Phases: [completed]/[total]
+
+## Blockers
+[any issues from phase-done.md, or "None"]
+
+## Last Milestone
+[keep existing or "None"]
+```
+
+## Step 6: Route Next
+
+**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
+
+**If the current phase was `partial`:**
+- Tell the user what failed
+- Suggest: fix the issue manually, then re-run `/fluxn:execute [N]` to retry
+
+**If all phases are complete:**
+- Tell the user: "All [N] phases complete. Run `/fluxn:verify` to verify the implementation."
+
+**If only the requested phase is done (not `all`):**
+- Report phase results
+- Tell the user: "Phase [N] complete. Next: `/fluxn:execute` for the next phase, or `/fluxn:execute all` for remaining phases."

package/commands/fluxn/go.md

@@ -0,0 +1,173 @@
+---
+description: "Quick start: research + plan in one shot: /fluxn:go <task description>"
+allowed-tools: Read, Write, Edit, Bash, Grep, Glob, Task
+---
+
+# /fluxn:go — Research + Plan (Quick Start)
+
+$ARGUMENTS
+
+You are the **go orchestrator** for Newa Flux. This is a shortcut that combines `/fluxn:research` and `/fluxn:plan` into one flow without pausing between them.
+
+The task description comes from the user's arguments: **$ARGUMENTS**
+
+If no arguments were provided, ask the user what they want to work on.
+
+---
+
+## PART 1: Research (same as /fluxn:research)
+
+### 1.1: Load Context
+
+Read these files if they exist:
+- `.fluxn/PROJECT.md` — project map (if missing, warn but continue)
+- `.fluxn/STATE.md` — current state
+
+### 1.2: Classify Task Type
+
+Classify based on the task description:
+- **new-project**: Building something from scratch ("create", "build", "new", "scaffold", "start")
+- **bug**: Fixing something broken ("fix", "bug", "error", "broken", "crash", "not working")
+- **feature**: Adding to or modifying existing code ("add", "implement", "update", "change", "improve", "refactor")
+
+Default to **feature** if ambiguous.
+
+### 1.3: Setup
+
+```bash
+mkdir -p .fluxn/research
+rm -f .fluxn/research/agent-*.md
+```
+
+### 1.4: Launch 4 Researchers in Parallel
+
+Spawn 4 `fluxn-researcher` agents using the Task tool, ALL IN PARALLEL.
+
+**If new-project:**
+| Agent | Focus | Output File |
+|-------|-------|-------------|
+| 1 | Stack & tools research (web) | `.fluxn/research/agent-1-stack.md` |
+| 2 | Architecture patterns (web) | `.fluxn/research/agent-2-architecture.md` |
+| 3 | Feature implementation (web) | `.fluxn/research/agent-3-features.md` |
+| 4 | Common pitfalls & best practices (web) | `.fluxn/research/agent-4-pitfalls.md` |
+
+**If bug:**
+| Agent | Focus | Output File |
+|-------|-------|-------------|
+| 1 | Symptom analysis & reproduction | `.fluxn/research/agent-1-symptoms.md` |
+| 2 | Codebase investigation | `.fluxn/research/agent-2-codebase.md` |
+| 3 | Git history & recent changes | `.fluxn/research/agent-3-history.md` |
+| 4 | Known solutions & patterns (web) | `.fluxn/research/agent-4-solutions.md` |
+
+**If feature:**
+| Agent | Focus | Output File |
+|-------|-------|-------------|
+| 1 | Existing codebase analysis | `.fluxn/research/agent-1-codebase.md` |
+| 2 | Existing patterns to follow | `.fluxn/research/agent-2-patterns.md` |
+| 3 | Dependencies & impact analysis | `.fluxn/research/agent-3-impact.md` |
+| 4 | Best practices & references (web) | `.fluxn/research/agent-4-practices.md` |
+
+Each agent receives PROJECT.md content as base context in their prompt:
+```
+FOCUS: [focus area]
+AGENT: [N] of 4
+OUTPUT FILE: [file path]
+TASK: [full task description]
+TYPE: [codebase | web | hybrid]
+
+PROJECT CONTEXT:
+[PROJECT.md content or "No PROJECT.md — explore from scratch"]
+
+SPECIFIC INSTRUCTIONS:
+[Investigation items for this focus area]
+
+Write findings to [file path]
+```
+
+### 1.5: Update STATE.md (after agents complete)
+
+Update `.fluxn/STATE.md` with status: researching, task info.
+
+---
+
+## PART 2: Plan (same as /fluxn:plan, runs inline)
+
+### 2.1: Read All Research
+
+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.
+
+Break work into 2-6 phases following the same rules as `/fluxn:plan`:
+- Each phase completable by a fresh agent
+- Clear, verifiable goals
+- Explicit file paths in tasks
+- Executable verification commands
+- Complete handoff between phases
+
+### 2.3: Write PLAN.md
+
+Write `.fluxn/PLAN.md` using the standard plan template:
+
+```markdown
+# Newa Flux Plan
+**Task:** [task description]
+**Type:** [type]
+**Phases:** [N]
+**Created:** [today's date]
+
+## Research Summary
+[3-5 sentences]
+
+**Key decisions:**
+- [Decision: what and why]
+
+---
+
+## Phase 1: [Name]
+**Goal:** [one sentence]
+
+### Tasks
+1. [specific task with file paths]
+
+### Files to Create/Modify
+- `path` — [purpose]
+
+### Verification
+- [ ] `[command]`
+
+### Context for Next Phase
+[handoff]
+
+---
+
+[... more phases]
+
+---
+
+## Checkpoint Summary
+| Phase | Goal | Verification | Status |
+|-------|------|-------------|--------|
+| 1 | ... | ... | pending |
+
+## Completion Criteria
+- [ ] [criterion]
+```
+
+### 2.4: Update STATE.md
+
+Update `.fluxn/STATE.md` with status: planned, phase count.
+
+---
+
+## PART 3: Report
+
+Tell the user:
+- Research + plan complete for: [task description]
+- Task type: [type]
+- Plan: [N] phases
+- Brief summary of each phase (1 line each)
+- Checkpoint summary table
+- Next step: Run `/fluxn:execute` to start phase 1, or `/fluxn:execute all` for all phases.