claude-flow-guidance-implementation 0.1.0

package/CLAUDE.md

@@ -0,0 +1,188 @@
+# Claude Code Configuration - Claude Flow V3
+
+## Behavioral Rules (Always Enforced)
+
+- Do what has been asked; nothing more, nothing less
+- NEVER create files unless they're absolutely necessary for achieving your goal
+- ALWAYS prefer editing an existing file to creating a new one
+- NEVER proactively create documentation files (*.md) or README files unless explicitly requested
+- NEVER save working files, text/mds, or tests to the root folder
+- Never continuously check status after spawning a swarm — wait for results
+- ALWAYS read a file before editing it
+- NEVER commit secrets, credentials, or .env files
+
+## File Organization
+
+- NEVER save to root folder — use the directories below
+- Use `/src` for source code files
+- Use `/tests` for test files
+- Use `/docs` for documentation and markdown files
+- Use `/config` for configuration files
+- Use `/scripts` for utility scripts
+- Use `/examples` for example code
+
+## Project Architecture
+
+- Follow Domain-Driven Design with bounded contexts
+- Keep files under 500 lines
+- Use typed interfaces for all public APIs
+- Prefer TDD London School (mock-first) for new code
+- Use event sourcing for state changes
+- Ensure input validation at system boundaries
+
+### Project Config
+
+- **Topology**: hierarchical-mesh
+- **Max Agents**: 15
+- **Memory**: hybrid
+- **HNSW**: Enabled
+- **Neural**: Enabled
+
+## Build & Test
+
+```bash
+# Build
+npm run build
+
+# Test
+npm test
+
+# Lint
+npm run lint
+```
+
+- ALWAYS run tests after making code changes
+- ALWAYS verify build succeeds before committing
+
+## Security Rules
+
+- NEVER hardcode API keys, secrets, or credentials in source files
+- NEVER commit .env files or any file containing secrets
+- Always validate user input at system boundaries
+- Always sanitize file paths to prevent directory traversal
+- Run `npx @claude-flow/cli@latest security scan` after security-related changes
+
+## Concurrency: 1 MESSAGE = ALL RELATED OPERATIONS
+
+- All operations MUST be concurrent/parallel in a single message
+- Use Claude Code's Task tool for spawning agents, not just MCP
+- ALWAYS batch ALL todos in ONE TodoWrite call (5-10+ minimum)
+- ALWAYS spawn ALL agents in ONE message with full instructions via Task tool
+- ALWAYS batch ALL file reads/writes/edits in ONE message
+- ALWAYS batch ALL Bash commands in ONE message
+
+## Swarm Orchestration
+
+- MUST initialize the swarm using CLI tools when starting complex tasks
+- MUST spawn concurrent agents using Claude Code's Task tool
+- Never use CLI tools alone for execution — Task tool agents do the actual work
+- MUST call CLI tools AND Task tool in ONE message for complex work
+
+### 3-Tier Model Routing (ADR-026)
+
+| Tier | Handler | Latency | Cost | Use Cases |
+|------|---------|---------|------|-----------|
+| **1** | Agent Booster (WASM) | <1ms | $0 | Simple transforms (var→const, add types) — Skip LLM |
+| **2** | Haiku | ~500ms | $0.0002 | Simple tasks, low complexity (<30%) |
+| **3** | Sonnet/Opus | 2-5s | $0.003-0.015 | Complex reasoning, architecture, security (>30%) |
+
+- Always check for `[AGENT_BOOSTER_AVAILABLE]` or `[TASK_MODEL_RECOMMENDATION]` before spawning agents
+- Use Edit tool directly when `[AGENT_BOOSTER_AVAILABLE]`
+
+## Swarm Configuration & Anti-Drift
+
+- ALWAYS use hierarchical topology for coding swarms
+- Keep maxAgents at 6-8 for tight coordination
+- Use specialized strategy for clear role boundaries
+- Use `raft` consensus for hive-mind (leader maintains authoritative state)
+- Run frequent checkpoints via `post-task` hooks
+- Keep shared memory namespace for all agents
+
+```bash
+npx @claude-flow/cli@latest swarm init --topology hierarchical --max-agents 8 --strategy specialized
+```
+
+## Swarm Execution Rules
+
+- ALWAYS use `run_in_background: true` for all agent Task calls
+- ALWAYS put ALL agent Task calls in ONE message for parallel execution
+- After spawning, STOP — do NOT add more tool calls or check status
+- Never poll TaskOutput or check swarm status — trust agents to return
+- When agent results arrive, review ALL results before proceeding
+
+## V3 CLI Commands
+
+### Core Commands
+
+| Command | Subcommands | Description |
+|---------|-------------|-------------|
+| `init` | 4 | Project initialization |
+| `agent` | 8 | Agent lifecycle management |
+| `swarm` | 6 | Multi-agent swarm coordination |
+| `memory` | 11 | AgentDB memory with HNSW search |
+| `task` | 6 | Task creation and lifecycle |
+| `session` | 7 | Session state management |
+| `hooks` | 17 | Self-learning hooks + 12 workers |
+| `hive-mind` | 6 | Byzantine fault-tolerant consensus |
+
+### Quick CLI Examples
+
+```bash
+npx @claude-flow/cli@latest init --wizard
+npx @claude-flow/cli@latest agent spawn -t coder --name my-coder
+npx @claude-flow/cli@latest swarm init --v3-mode
+npx @claude-flow/cli@latest memory search --query "authentication patterns"
+npx @claude-flow/cli@latest doctor --fix
+```
+
+## Available Agents (60+ Types)
+
+### Core Development
+`coder`, `reviewer`, `tester`, `planner`, `researcher`
+
+### Specialized
+`security-architect`, `security-auditor`, `memory-specialist`, `performance-engineer`
+
+### Swarm Coordination
+`hierarchical-coordinator`, `mesh-coordinator`, `adaptive-coordinator`
+
+### GitHub & Repository
+`pr-manager`, `code-review-swarm`, `issue-tracker`, `release-manager`
+
+### SPARC Methodology
+`sparc-coord`, `sparc-coder`, `specification`, `pseudocode`, `architecture`
+
+## Memory Commands Reference
+
+```bash
+# Store (REQUIRED: --key, --value; OPTIONAL: --namespace, --ttl, --tags)
+npx @claude-flow/cli@latest memory store --key "pattern-auth" --value "JWT with refresh" --namespace patterns
+
+# Search (REQUIRED: --query; OPTIONAL: --namespace, --limit, --threshold)
+npx @claude-flow/cli@latest memory search --query "authentication patterns"
+
+# List (OPTIONAL: --namespace, --limit)
+npx @claude-flow/cli@latest memory list --namespace patterns --limit 10
+
+# Retrieve (REQUIRED: --key; OPTIONAL: --namespace)
+npx @claude-flow/cli@latest memory retrieve --key "pattern-auth" --namespace patterns
+```
+
+## Quick Setup
+
+```bash
+claude mcp add claude-flow -- npx -y @claude-flow/cli@latest
+npx @claude-flow/cli@latest daemon start
+npx @claude-flow/cli@latest doctor --fix
+```
+
+## Claude Code vs CLI Tools
+
+- Claude Code's Task tool handles ALL execution: agents, file ops, code generation, git
+- CLI tools handle coordination via Bash: swarm init, memory, hooks, routing
+- NEVER use CLI tools as a substitute for Task tool agents
+
+## Support
+
+- Documentation: https://github.com/ruvnet/claude-flow
+- Issues: https://github.com/ruvnet/claude-flow/issues

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,115 @@
+# claude-flow-guidance-implementation
+
+Reusable implementation kit for wiring `@claude-flow/guidance` into any repo with:
+- guidance runtime scripts
+- Claude Code hook bridge
+- autopilot promotion loop (`CLAUDE.local.md` -> `CLAUDE.md`)
+- verification runbook and docs
+
+## What this repo provides
+
+- A reusable scaffold under `scaffold/`:
+  - `.claude/helpers/hook-handler.cjs`
+  - `scripts/guidance-*.js`
+  - `src/guidance/*.js`
+  - docs
+- An installer CLI:
+  - `cf-guidance-impl install --target <repo>`
+  - `cf-guidance-impl verify --target <repo>`
+- JSON merge logic for:
+  - `package.json` scripts + dependencies
+  - `.claude/settings.json` env + hooks
+  - `.agents/config.toml` Codex bridge section
+  - `AGENTS.md` Codex lifecycle usage section
+
+## Quickstart
+
+```bash
+# clone this toolkit
+cd ~/source
+git clone https://github.com/sparkling/claude-flow-guidance-implementation.git
+cd claude-flow-guidance-implementation
+
+# initialize + wire another repo (runs `claude-flow init --dual`, install, verify)
+node bin/cf-guidance-impl.mjs init --target ~/source/my-project --install-deps
+
+# verify the wiring
+node bin/cf-guidance-impl.mjs verify --target ~/source/my-project
+```
+
+Init command options:
+- `--no-dual`: run `claude-flow init` without `--dual`
+- `--skip-cf-init`: skip `claude-flow init` and only apply toolkit wiring
+- `--no-verify`: skip post-install verification
+
+## Integration modes for other repos
+
+## 1) Central toolkit mode (recommended)
+Keep this repo as a shared toolkit and run installer into target repos:
+
+```bash
+node ~/source/claude-flow-guidance-implementation/bin/cf-guidance-impl.mjs init --target ~/source/repo-a --install-deps
+node ~/source/claude-flow-guidance-implementation/bin/cf-guidance-impl.mjs init --target ~/source/repo-b --install-deps
+```
+
+## 2) Submodule mode
+Add this repo as a submodule in each project and invoke the installer from there.
+
+## 3) Copy mode
+Copy `scaffold/` manually and merge settings/scripts manually.
+
+## What gets wired in the target repo
+
+- Hook flow: `PreToolUse`/`PostToolUse`/`SessionStart`/`SessionEnd`
+- Guidance events: `pre-command`, `pre-edit`, `pre-task`, `post-edit`, `post-task`, `session-end`
+- Codex lifecycle bridge: `scripts/guidance-codex-bridge.js`
+- Background session-end autopilot launch
+- NPM wrappers:
+  - `guidance:analyze`, `guidance:status`, `guidance:all`
+  - `guidance:optimize`, `guidance:ab-benchmark`
+  - `guidance:scaffold`
+  - `guidance:autopilot:once`, `guidance:autopilot:daemon`
+  - `guidance:codex:status`
+  - `guidance:codex:pre-command`, `guidance:codex:pre-edit`, `guidance:codex:pre-task`
+  - `guidance:codex:post-edit`, `guidance:codex:post-task`
+  - `guidance:codex:session-start`, `guidance:codex:session-end`
+
+## Codex integration runbook
+
+```bash
+# initialize lifecycle context
+npm run guidance:codex:session-start
+
+# gate the task and operations
+npm run guidance:codex:pre-task -- --task-id task-123 --description "Implement feature X"
+npm run guidance:codex:pre-command -- --task-id task-123 --command "git status"
+npm run guidance:codex:pre-edit -- --task-id task-123 --file src/example.ts --operation modify
+
+# record completion
+npm run guidance:codex:post-edit -- --task-id task-123 --file src/example.ts
+npm run guidance:codex:post-task -- --task-id task-123 --status completed --description "Implement feature X"
+npm run guidance:codex:session-end -- --task-id task-123
+```
+
+Validation:
+```bash
+npm run guidance:codex:status
+npm run guidance:codex:pre-task -- --task-id smoke-1 --description "smoke" --skip-cf-hooks
+```
+
+Expected output is JSON:
+- `handler.ok: true` means local bridge + hook-handler path passed.
+- `claudeFlowHook.ok: true` means secondary `@claude-flow/cli` hook invocation passed.
+
+## Swarm commands
+
+```bash
+npm run swarm:init
+npm run swarm:route
+```
+
+## Notes
+
+- Existing target repo config is merged, not replaced.
+- `CLAUDE.local.md` is created if missing and added to `.gitignore`.
+- The scaffold includes docs that explain operational details.

package/bin/cf-guidance-impl.mjs

@@ -0,0 +1,74 @@
+#!/usr/bin/env node
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { initRepo, installIntoRepo, verifyRepo } from '../src/installer.mjs';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const toolkitRoot = resolve(__dirname, '..');
+
+function usage() {
+  console.log(`Usage:
+  cf-guidance-impl init --target <repoPath> [--force] [--install-deps] [--no-dual] [--skip-cf-init] [--no-verify]
+  cf-guidance-impl install --target <repoPath> [--force] [--install-deps]
+  cf-guidance-impl verify --target <repoPath>
+`);
+}
+
+function getFlagValue(args, flag, fallback = null) {
+  const index = args.indexOf(flag);
+  if (index < 0 || index + 1 >= args.length) return fallback;
+  return args[index + 1];
+}
+
+function hasFlag(args, flag) {
+  return args.includes(flag);
+}
+
+async function main() {
+  const [, , command, ...args] = process.argv;
+
+  if (!command || command === '--help' || command === '-h') {
+    usage();
+    process.exit(command ? 0 : 1);
+  }
+
+  const target = getFlagValue(args, '--target', process.cwd());
+  const force = hasFlag(args, '--force');
+  const installDeps = hasFlag(args, '--install-deps');
+
+  if (command === 'init') {
+    const result = initRepo({
+      toolkitRoot,
+      targetRepo: target,
+      force,
+      installDeps,
+      dual: !hasFlag(args, '--no-dual'),
+      skipCfInit: hasFlag(args, '--skip-cf-init'),
+      verify: !hasFlag(args, '--no-verify'),
+    });
+    console.log(JSON.stringify(result, null, 2));
+    return;
+  }
+
+  if (command === 'install') {
+    const result = installIntoRepo({ toolkitRoot, targetRepo: target, force, installDeps });
+    console.log(JSON.stringify(result, null, 2));
+    return;
+  }
+
+  if (command === 'verify') {
+    const report = verifyRepo({ targetRepo: target });
+    console.log(JSON.stringify(report, null, 2));
+    process.exit(report.passed ? 0 : 2);
+  }
+
+  usage();
+  process.exit(1);
+}
+
+main().catch((error) => {
+  const message = error instanceof Error ? error.message : String(error);
+  console.error(message);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "claude-flow-guidance-implementation",
+  "version": "0.1.0",
+  "description": "Reusable guidance control-plane implementation kit for wiring @claude-flow/guidance into any repo",
+  "type": "module",
+  "private": false,
+  "bin": {
+    "cf-guidance-impl": "bin/cf-guidance-impl.mjs"
+  },
+  "scripts": {
+    "lint": "node ./bin/cf-guidance-impl.mjs verify --target .",
+    "swarm:init": "npx @claude-flow/cli@latest swarm init --topology hierarchical --max-agents 8 --strategy specialized",
+    "swarm:route": "npx @claude-flow/cli@latest hooks route --task \"implement reusable guidance integration kit\""
+  },
+  "keywords": [
+    "claude-flow",
+    "guidance",
+    "hooks",
+    "claude-code",
+    "automation"
+  ],
+  "license": "MIT"
+}