agentic-flow 3.0.0 → 3.1.0

package/.claude/skills/agentic-flow-quickstart/skill.md

@@ -18,16 +18,16 @@ Initialize and configure agentic-flow for optimal Claude Code integration.
 
 ```bash
 # Initialize new project with agentic-flow
-npx agentic-flow@alpha init
+npx agentic-flow@3.1.0 init
 
 # Start MCP server for Claude Code
-npx agentic-flow@alpha mcp start
+npx agentic-flow@3.1.0 mcp start
 
 # List available agents
-npx agentic-flow@alpha --list
+npx agentic-flow@3.1.0 --list
 
 # Run a specific agent
-npx agentic-flow@alpha --agent coder --task "implement feature X"
+npx agentic-flow@3.1.0 --agent coder --task "implement feature X"
 ```
 
 ## Features
@@ -63,7 +63,7 @@ Settings are stored in `.claude/settings.json`:
 
 ## Next Steps
 
-1. Run `npx agentic-flow@alpha init` to set up project
-2. Start MCP server with `npx agentic-flow@alpha mcp start`
+1. Run `npx agentic-flow@3.1.0 init` to set up project
+2. Start MCP server with `npx agentic-flow@3.1.0 mcp start`
 3. Use Claude Code's Task tool to spawn agents
 4. Monitor via statusline and metrics

package/.claude/skills/hooks-automation/skill.md

@@ -27,14 +27,14 @@ Triggered before Claude Code tools execute.
       "matcher": "Edit|Write|MultiEdit",
       "hooks": [{
         "type": "command",
-        "command": "npx agentic-flow@alpha hooks pre-edit \"$TOOL_INPUT_file_path\""
+        "command": "npx agentic-flow@3.1.0 hooks pre-edit \"$TOOL_INPUT_file_path\""
       }]
     },
     {
       "matcher": "Bash",
       "hooks": [{
         "type": "command",
-        "command": "npx agentic-flow@alpha hooks pre-command \"$TOOL_INPUT_command\""
+        "command": "npx agentic-flow@3.1.0 hooks pre-command \"$TOOL_INPUT_command\""
       }]
     }
   ]
@@ -51,7 +51,7 @@ Triggered after successful tool execution.
       "matcher": "Edit|Write|MultiEdit",
       "hooks": [{
         "type": "command",
-        "command": "npx agentic-flow@alpha hooks post-edit \"$TOOL_INPUT_file_path\" --success"
+        "command": "npx agentic-flow@3.1.0 hooks post-edit \"$TOOL_INPUT_file_path\" --success"
       }]
     }
   ]
@@ -66,13 +66,13 @@ Triggered at session start/end.
   "SessionStart": [{
     "hooks": [{
       "type": "command",
-      "command": "npx agentic-flow@alpha hooks intelligence stats --json"
+      "command": "npx agentic-flow@3.1.0 hooks intelligence stats --json"
     }]
   }],
   "SessionEnd": [{
     "hooks": [{
       "type": "command",
-      "command": "npx agentic-flow@alpha hooks metrics --session --json"
+      "command": "npx agentic-flow@3.1.0 hooks metrics --session --json"
     }]
   }]
 }
@@ -82,22 +82,22 @@ Triggered at session start/end.
 
 ```bash
 # Pre-edit: Check for patterns, validate
-npx agentic-flow@alpha hooks pre-edit "src/api.ts"
+npx agentic-flow@3.1.0 hooks pre-edit "src/api.ts"
 
 # Post-edit: Format, learn pattern
-npx agentic-flow@alpha hooks post-edit "src/api.ts" --success
+npx agentic-flow@3.1.0 hooks post-edit "src/api.ts" --success
 
 # Pre-command: Validate safety
-npx agentic-flow@alpha hooks pre-command "npm install"
+npx agentic-flow@3.1.0 hooks pre-command "npm install"
 
 # Post-command: Track result
-npx agentic-flow@alpha hooks post-command "npm install"
+npx agentic-flow@3.1.0 hooks post-command "npm install"
 
 # Intelligence routing
-npx agentic-flow@alpha hooks route "implement OAuth"
+npx agentic-flow@3.1.0 hooks route "implement OAuth"
 
 # Session metrics
-npx agentic-flow@alpha hooks metrics --session
+npx agentic-flow@3.1.0 hooks metrics --session
 ```
 
 ## Automation Features

package/.claude/skills/memory-patterns/skill.md

@@ -19,16 +19,16 @@ Implement persistent memory patterns for AI agents using ReasoningBank.
 
 ```bash
 # Store a pattern
-npx agentic-flow@alpha memory store "api:auth" "OAuth2 with JWT"
+npx agentic-flow@3.1.0 memory store "api:auth" "OAuth2 with JWT"
 
 # Retrieve a pattern
-npx agentic-flow@alpha memory get "api:auth"
+npx agentic-flow@3.1.0 memory get "api:auth"
 
 # Search patterns
-npx agentic-flow@alpha memory search "authentication"
+npx agentic-flow@3.1.0 memory search "authentication"
 
 # List all patterns
-npx agentic-flow@alpha memory list --namespace project
+npx agentic-flow@3.1.0 memory list --namespace project
 ```
 
 ## Memory Namespaces
@@ -46,7 +46,7 @@ npx agentic-flow@alpha memory list --namespace project
 ### Decision Patterns
 ```bash
 # Store decision with context
-npx agentic-flow@alpha memory store \
+npx agentic-flow@3.1.0 memory store \
   "decisions:auth-method" \
   '{"choice": "JWT", "reason": "stateless, scalable", "date": "2024-01-01"}'
 ```
@@ -54,7 +54,7 @@ npx agentic-flow@alpha memory store \
 ### Code Patterns
 ```bash
 # Store reusable code pattern
-npx agentic-flow@alpha memory store \
+npx agentic-flow@3.1.0 memory store \
   "patterns:error-handling" \
   "try-catch with custom error classes and logging"
 ```
@@ -62,7 +62,7 @@ npx agentic-flow@alpha memory store \
 ### Learning Patterns
 ```bash
 # Store learning from successful task
-npx agentic-flow@alpha memory store \
+npx agentic-flow@3.1.0 memory store \
   "learnings:react-hooks" \
   "useCallback for event handlers, useMemo for expensive computations"
 ```

package/.claude/skills/sparc-methodology/skill.md

@@ -20,17 +20,17 @@ Systematic Test-Driven Development using SPARC (Specification, Pseudocode, Archi
 
 ```bash
 # Run complete TDD workflow
-npx agentic-flow@alpha sparc tdd "implement user authentication"
+npx agentic-flow@3.1.0 sparc tdd "implement user authentication"
 
 # Run specific phase
-npx agentic-flow@alpha sparc run specification "auth system"
-npx agentic-flow@alpha sparc run pseudocode "auth system"
-npx agentic-flow@alpha sparc run architect "auth system"
-npx agentic-flow@alpha sparc run refinement "auth system"
-npx agentic-flow@alpha sparc run completion "auth system"
+npx agentic-flow@3.1.0 sparc run specification "auth system"
+npx agentic-flow@3.1.0 sparc run pseudocode "auth system"
+npx agentic-flow@3.1.0 sparc run architect "auth system"
+npx agentic-flow@3.1.0 sparc run refinement "auth system"
+npx agentic-flow@3.1.0 sparc run completion "auth system"
 
 # Batch execution
-npx agentic-flow@alpha sparc batch "spec-pseudocode,architect" "feature X"
+npx agentic-flow@3.1.0 sparc batch "spec-pseudocode,architect" "feature X"
 ```
 
 ## SPARC Phases
@@ -42,7 +42,7 @@ Define requirements and acceptance criteria.
 **Output**: Requirements doc, test cases
 **Command**:
 ```bash
-npx agentic-flow@alpha sparc run spec "user login feature"
+npx agentic-flow@3.1.0 sparc run spec "user login feature"
 ```
 
 ### 2. Pseudocode (pseudo)
@@ -52,7 +52,7 @@ Design algorithms and logic flow.
 **Output**: Algorithm design, flow diagrams
 **Command**:
 ```bash
-npx agentic-flow@alpha sparc run pseudo "auth flow"
+npx agentic-flow@3.1.0 sparc run pseudo "auth flow"
 ```
 
 ### 3. Architecture (arch)
@@ -62,7 +62,7 @@ System design and component structure.
 **Output**: Component diagram, API design
 **Command**:
 ```bash
-npx agentic-flow@alpha sparc run arch "microservices layout"
+npx agentic-flow@3.1.0 sparc run arch "microservices layout"
 ```
 
 ### 4. Refinement (refine)
@@ -72,7 +72,7 @@ Iterative TDD implementation.
 **Output**: Tests + Implementation
 **Command**:
 ```bash
-npx agentic-flow@alpha sparc run refine "auth module"
+npx agentic-flow@3.1.0 sparc run refine "auth module"
 ```
 
 ### 5. Completion (complete)
@@ -82,7 +82,7 @@ Integration and deployment.
 **Output**: Integrated system, docs
 **Command**:
 ```bash
-npx agentic-flow@alpha sparc run complete "auth system"
+npx agentic-flow@3.1.0 sparc run complete "auth system"
 ```
 
 ## SPARC Modes
@@ -104,7 +104,7 @@ Additional specialized modes:
 
 ```bash
 # Full TDD cycle
-npx agentic-flow@alpha sparc tdd "implement OAuth2"
+npx agentic-flow@3.1.0 sparc tdd "implement OAuth2"
 
 # This runs:
 # 1. Specification: Define requirements

package/.claude/skills/swarm-coordination/skill.md

@@ -19,17 +19,17 @@ Coordinate multi-agent swarms for parallel task execution with intelligent topol
 
 ```bash
 # Initialize a mesh swarm with 5 agents
-npx agentic-flow@alpha swarm init --topology mesh --agents 5
+npx agentic-flow@3.1.0 swarm init --topology mesh --agents 5
 
 # Spawn specialized agents
-npx agentic-flow@alpha swarm spawn --type researcher --name "Research Agent"
-npx agentic-flow@alpha swarm spawn --type coder --name "Code Agent"
+npx agentic-flow@3.1.0 swarm spawn --type researcher --name "Research Agent"
+npx agentic-flow@3.1.0 swarm spawn --type coder --name "Code Agent"
 
 # Orchestrate a task
-npx agentic-flow@alpha swarm orchestrate "Implement feature X with tests"
+npx agentic-flow@3.1.0 swarm orchestrate "Implement feature X with tests"
 
 # Check swarm status
-npx agentic-flow@alpha swarm status
+npx agentic-flow@3.1.0 swarm status
 ```
 
 ## Topologies

package/.claude/skills/worker-benchmarks/skill.md

@@ -18,13 +18,13 @@ Run comprehensive performance benchmarks for the agentic-flow worker system.
 
 ```bash
 # Run full benchmark suite
-npx agentic-flow workers benchmark
+npx agentic-flow@3.1.0 workers benchmark
 
 # Run specific benchmark
-npx agentic-flow workers benchmark --type trigger-detection
-npx agentic-flow workers benchmark --type registry
-npx agentic-flow workers benchmark --type agent-selection
-npx agentic-flow workers benchmark --type concurrent
+npx agentic-flow@3.1.0 workers benchmark --type trigger-detection
+npx agentic-flow@3.1.0 workers benchmark --type registry
+npx agentic-flow@3.1.0 workers benchmark --type agent-selection
+npx agentic-flow@3.1.0 workers benchmark --type concurrent
 ```
 
 ## Benchmark Types

package/.claude/skills/worker-integration/skill.md

@@ -19,14 +19,14 @@ Intelligent coordination between background workers and specialized agents.
 
 ```bash
 # View agent recommendations for a trigger
-npx agentic-flow workers agents ultralearn
-npx agentic-flow workers agents optimize
+npx agentic-flow@3.1.0 workers agents ultralearn
+npx agentic-flow@3.1.0 workers agents optimize
 
 # View performance metrics
-npx agentic-flow workers metrics
+npx agentic-flow@3.1.0 workers metrics
 
 # View integration stats
-npx agentic-flow workers stats --integration
+npx agentic-flow@3.1.0 workers stats --integration
 ```
 
 ## Agent Mappings
@@ -119,7 +119,7 @@ const { compliant, violations } = workerAgentIntegration.checkBenchmarkComplianc
 ## Integration Statistics
 
 ```bash
-$ npx agentic-flow workers stats --integration
+$ npx agentic-flow@3.1.0 workers stats --integration
 
 Worker-Agent Integration Stats
 ══════════════════════════════

package/.claude/statusline.mjs

@@ -3,7 +3,9 @@
  * Shows model, tokens, cost, swarm status, and memory usage
  */
 
-import { execSync } from 'child_process';
+import { execFileSync } from 'child_process';
+import { existsSync } from 'fs';
+import { join } from 'path';
 
 // Cache for expensive operations
 let lastSwarmCheck = 0;
@@ -19,10 +21,21 @@ function getSwarmStatus() {
     return cachedSwarmStatus;
   }
 
+  // Ask the project's own install only. `npx agentic-flow@<tag>` here ran
+  // whatever the tag pointed at (the deprecated alpha) on every refresh.
+  const bin = join(process.cwd(), 'node_modules', '.bin',
+    process.platform === 'win32' ? 'agentic-flow.cmd' : 'agentic-flow');
+  if (!existsSync(bin)) {
+    cachedSwarmStatus = '⚡';
+    lastSwarmCheck = now;
+    return cachedSwarmStatus;
+  }
+
   try {
-    const result = execSync('npx agentic-flow@alpha mcp status 2>/dev/null || echo "idle"', {
+    const result = execFileSync(bin, ['mcp', 'status'], {
       encoding: 'utf-8',
-      timeout: 2000
+      timeout: 2000,
+      stdio: ['ignore', 'pipe', 'ignore']
     }).trim();
 
     cachedSwarmStatus = result.includes('running') ? '🐝' : '⚡';
@@ -68,8 +81,12 @@ export default function statusline(context) {
   parts.push('🤖');
 
   // Model name (shortened)
-  if (context.model) {
-    const model = context.model
+  // Claude Code passes `model` as { id, display_name }; older callers pass a string.
+  const modelName = typeof context.model === 'string'
+    ? context.model
+    : context.model?.display_name ?? context.model?.id;
+  if (typeof modelName === 'string' && modelName) {
+    const model = modelName
       .replace('claude-', '')
       .replace('-20250514', '')
       .replace('sonnet-4', 'S4')

package/CHANGELOG.md

@@ -2,6 +2,29 @@
 
 All notable changes to this project will be documented in this file.
 
+## [3.1.0] - 2026-10-31
+
+Fixes two correctness bugs left after 3.0.0 and brings the docs in line with its proxy auth. See ADR-080.
+
+### Changed
+- **One embedding space per process (#246).** A failed model load used to be retried on the next call, so one process could hold hash-fallback vectors and model vectors side by side and compare them (cosine of the same text across the two was ~0.03). The first embedding now fixes the space:
+  - a failed load is **not retried automatically**; the process stays on hash vectors and `isSemanticEmbedding()` stays false;
+  - if the model fails on a text **after model vectors were produced**, `computeEmbedding`/`computeEmbeddingBatch` **throw** instead of returning a hash vector. `retrieveMemories` and `distillMemories` propagate that error;
+  - new `resetEmbeddingBackend()` clears the choice and the cache so the model is tried again (re-embed anything you kept); new `getEmbeddingKind()` returns `'local'`, `'hash'` or `null`.
+
+### Security
+- **`.claude/statusline.mjs` ran `npx agentic-flow@alpha mcp status` on every refresh**, which executes the deprecated March 3.0.0-alpha line (and its critical `protobufjs` advisory). It now asks only the project's own `node_modules/.bin/agentic-flow`, without a shell, and shows the idle marker when there is none.
+- **`hooks init` pre-approved `Bash(npx:*)`, `Bash(npm run:*)` and the whole `agentic-flow`, `claude-flow` and `ruv-swarm` MCP servers**, so any package or tool ran without a prompt. It now allows only `Bash(agentic-flow:*)`, as `init` has since 3.0.0. Re-run `hooks init --force` in existing projects.
+- **`hooks init` wrote unversioned `npx agentic-flow …` hooks**, which resolve to whatever `@latest` is that day. They now pin the installed version, as `init` has since 3.0.0. The `swarm` commands print a pinned `swarm connect` line instead of `@alpha`, and `scripts/validate-providers.sh`, the versioned `docs/docker-tests` Dockerfiles and the worker skills pin too. The version comes from a shared `src/utils/package-version.ts`, which throws instead of falling back to a tag.
+
+### Fixed
+- `.claude/statusline.mjs` no longer crashes when Claude Code passes `model` as `{ id, display_name }`; it shows `display_name ?? id` and still accepts a string.
+- The Gemini and Requesty proxies' streams no longer drop an SSE line split across reads or corrupt a multibyte character split across chunks (3.0.0 fixed only OpenRouter). All three now share `src/proxy/sse-lines.ts`; the Gemini proxy also strips CR from its CRLF lines.
+
+### Docs
+- The proxy guides (`STANDALONE_PROXY_GUIDE`, `CLAUDE-CODE-INTEGRATION`, `PROXY-ARCHITECTURE-AND-EXTENSION`, both copies) and the shipped Requesty plans sent a dummy key that the 3.0.0 proxies reject. They now use the token the proxy prints and document `AGENTIC_FLOW_PROXY_TOKEN` and `AGENTIC_FLOW_PROXY_HOST`; the extension guide's template uses the `proxy-auth` helpers.
+- The READMEs and the skills in `.claude/skills` ran `npx agentic-flow@alpha`, which resolves to the March 3.0.0-alpha line. They pin `agentic-flow@3.1.0`, and a test keeps that pin equal to the package version.
+
 ## [3.0.0] - 2026-10-31
 
 First stable 3.x. It is the main line (2.1.5) plus a security and correctness review; it supersedes 3.0.0-alpha.1/.2, which were built from a different tree. Published without an alpha dist-tag (ruflo ADR-513/515).