claude-flow-guidance-implementation 0.1.0 → 0.1.1

package/README.md

@@ -1,115 +1,91 @@
 # claude-flow-guidance-implementation
 
-Reusable implementation kit for wiring `@claude-flow/guidance` into any repo with:
-- guidance runtime scripts
+NPM-first implementation kit for wiring `@claude-flow/guidance` into any repository.
+
+It installs a reusable guidance control plane with:
 - Claude Code hook bridge
+- Codex lifecycle bridge
+- guidance runtime scripts
 - 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
+- verification tooling
 
-## Quickstart
+## Install and run
+
+Use directly from npm (no clone required):
 
 ```bash
-# clone this toolkit
-cd ~/source
-git clone https://github.com/sparkling/claude-flow-guidance-implementation.git
-cd claude-flow-guidance-implementation
+npx --yes -p claude-flow-guidance-implementation cf-guidance-impl init --target ~/source/my-project --install-deps
+```
 
-# initialize + wire another repo (runs `claude-flow init --dual`, install, verify)
-node bin/cf-guidance-impl.mjs init --target ~/source/my-project --install-deps
+Or install as a dev dependency:
 
-# verify the wiring
-node bin/cf-guidance-impl.mjs verify --target ~/source/my-project
+```bash
+npm i -D claude-flow-guidance-implementation
+npx cf-guidance-impl init --target ~/source/my-project --install-deps
 ```
 
-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
+## Quickstart
 
-## Integration modes for other repos
+```bash
+# 1) initialize and wire a target repo
+npx --yes -p claude-flow-guidance-implementation cf-guidance-impl init --target ~/source/my-project --install-deps
 
-## 1) Central toolkit mode (recommended)
-Keep this repo as a shared toolkit and run installer into target repos:
+# 2) verify wiring
+npx --yes -p claude-flow-guidance-implementation cf-guidance-impl verify --target ~/source/my-project
+```
+
+## CLI commands
 
 ```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
+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>
 ```
 
-## 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 `init` does
 
-## What gets wired in the target repo
+`cf-guidance-impl init` performs:
+1. `npx @claude-flow/cli@latest init --dual` in target repo (unless `--skip-cf-init`)
+2. installs scaffold runtime files (`scripts/`, `src/guidance/`, `.claude/helpers/hook-handler.cjs`, docs)
+3. merges target `package.json` scripts + guidance deps
+4. merges `.claude/settings.json` env and hook blocks
+5. appends Codex bridge sections to `.agents/config.toml` and `AGENTS.md`
+6. creates `CLAUDE.local.md` stub and updates `.gitignore`
+7. verifies wiring (unless `--no-verify`)
 
-- 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 lifecycle integration
 
-## Codex integration runbook
+After installation, these scripts are available in the target repo:
 
 ```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:
+Validation smoke check:
+
 ```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.
+Expected JSON output:
+- `handler.ok: true` -> local bridge + hook-handler path succeeded
+- `claudeFlowHook.ok: true` -> secondary `@claude-flow/cli` hook invocation succeeded
 
-## Swarm commands
+## Notes
 
-```bash
-npm run swarm:init
-npm run swarm:route
-```
+- Target repo config is merged, not replaced.
+- Default local guidance file is `CLAUDE.local.md` (gitignored).
+- Advanced reference docs are installed into target `docs/`.
 
-## Notes
+## Links
 
-- 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.
+- GitHub: https://github.com/sparkling/claude-flow-guidance-implementation
+- Issues: https://github.com/sparkling/claude-flow-guidance-implementation/issues
+- Package: https://www.npmjs.com/package/claude-flow-guidance-implementation

package/package.json

@@ -1,9 +1,25 @@
 {
   "name": "claude-flow-guidance-implementation",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Reusable guidance control-plane implementation kit for wiring @claude-flow/guidance into any repo",
   "type": "module",
   "private": false,
+  "author": "Sparkling Ideas <henrik@sparklingideas.co.uk>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sparkling/claude-flow-guidance-implementation.git"
+  },
+  "homepage": "https://github.com/sparkling/claude-flow-guidance-implementation#readme",
+  "bugs": {
+    "url": "https://github.com/sparkling/claude-flow-guidance-implementation/issues"
+  },
+  "files": [
+    "bin",
+    "src",
+    "scaffold",
+    "README.md",
+    "LICENSE"
+  ],
   "bin": {
     "cf-guidance-impl": "bin/cf-guidance-impl.mjs"
   },
@@ -15,6 +31,9 @@
   "keywords": [
     "claude-flow",
     "guidance",
+    "codex",
+    "claude-md",
+    "agentic",
     "hooks",
     "claude-code",
     "automation"

package/.agents/README.md

@@ -1,38 +0,0 @@
-# .agents Directory
-
-This directory contains agent configuration and skills for OpenAI Codex CLI.
-
-## Structure
-
-```
-.agents/
-  config.toml     # Main configuration file
-  skills/         # Skill definitions
-    skill-name/
-      SKILL.md    # Skill instructions
-      scripts/    # Optional scripts
-      docs/       # Optional documentation
-  README.md       # This file
-```
-
-## Configuration
-
-The `config.toml` file controls:
-- Model selection
-- Approval policies
-- Sandbox modes
-- MCP server connections
-- Skills configuration
-
-## Skills
-
-Skills are invoked using `$skill-name` syntax. Each skill has:
-- YAML frontmatter with metadata
-- Trigger and skip conditions
-- Commands and examples
-
-## Documentation
-
-- Main instructions: `AGENTS.md` (project root)
-- Local overrides: `.codex/AGENTS.override.md` (gitignored)
-- Claude Flow: https://github.com/ruvnet/claude-flow

package/.agents/config.toml

@@ -1,298 +0,0 @@
-# =============================================================================
-# Claude Flow V3 - Codex Configuration
-# =============================================================================
-# Generated by: @claude-flow/codex
-# Documentation: https://github.com/ruvnet/claude-flow
-# 
-# This file configures the Codex CLI for Claude Flow integration.
-# Place in .agents/config.toml (project) or .codex/config.toml (user).
-# =============================================================================
-
-# =============================================================================
-# Core Settings
-# =============================================================================
-
-# Model selection - the AI model to use for code generation
-# Options: gpt-5.3-codex, gpt-4o, claude-sonnet, claude-opus
-model = "gpt-5.3-codex"
-
-# Approval policy determines when human approval is required
-# - untrusted: Always require approval
-# - on-failure: Require approval only after failures
-# - on-request: Require approval for significant changes
-# - never: Auto-approve all actions (use with caution)
-approval_policy = "on-request"
-
-# Sandbox mode controls file system access
-# - read-only: Can only read files, no modifications
-# - workspace-write: Can write within workspace directory
-# - danger-full-access: Full file system access (dangerous)
-sandbox_mode = "workspace-write"
-
-# Web search enables internet access for research
-# - disabled: No web access
-# - cached: Use cached results when available
-# - live: Always fetch fresh results
-web_search = "cached"
-
-# =============================================================================
-# Project Documentation
-# =============================================================================
-
-# Maximum bytes to read from AGENTS.md files
-project_doc_max_bytes = 65536
-
-# Fallback filenames if AGENTS.md not found
-project_doc_fallback_filenames = [
-  "AGENTS.md",
-  "TEAM_GUIDE.md",
-  ".agents.md"
-]
-
-# =============================================================================
-# Features
-# =============================================================================
-
-[features]
-# Enable child AGENTS.md guidance
-child_agents_md = true
-
-# Cache shell environment for faster repeated commands
-shell_snapshot = true
-
-# Smart approvals based on request context
-request_rule = true
-
-# Enable remote compaction for large histories
-remote_compaction = true
-
-# =============================================================================
-# MCP Servers
-# =============================================================================
-
-[mcp_servers.claude-flow]
-command = "npx"
-args = ["-y", "@claude-flow/cli@latest"]
-enabled = true
-tool_timeout_sec = 120
-
-# =============================================================================
-# Skills Configuration
-# =============================================================================
-
-[[skills.config]]
-path = ".agents/skills/swarm-orchestration"
-enabled = true
-
-[[skills.config]]
-path = ".agents/skills/memory-management"
-enabled = true
-
-[[skills.config]]
-path = ".agents/skills/sparc-methodology"
-enabled = true
-
-[[skills.config]]
-path = ".agents/skills/security-audit"
-enabled = true
-
-# =============================================================================
-# Profiles
-# =============================================================================
-
-# Development profile - more permissive for local work
-[profiles.dev]
-approval_policy = "never"
-sandbox_mode = "danger-full-access"
-web_search = "live"
-
-# Safe profile - maximum restrictions
-[profiles.safe]
-approval_policy = "untrusted"
-sandbox_mode = "read-only"
-web_search = "disabled"
-
-# CI profile - for automated pipelines
-[profiles.ci]
-approval_policy = "never"
-sandbox_mode = "workspace-write"
-web_search = "cached"
-
-# =============================================================================
-# History
-# =============================================================================
-
-[history]
-# Save all session transcripts
-persistence = "save-all"
-
-# =============================================================================
-# Shell Environment
-# =============================================================================
-
-[shell_environment_policy]
-# Inherit environment variables
-inherit = "core"
-
-# Exclude sensitive variables
-exclude = ["*_KEY", "*_SECRET", "*_TOKEN", "*_PASSWORD"]
-
-# =============================================================================
-# Sandbox Workspace Write Settings
-# =============================================================================
-
-[sandbox_workspace_write]
-# Additional writable paths beyond workspace
-writable_roots = []
-
-# Allow network access
-network_access = true
-
-# Exclude temp directories
-exclude_slash_tmp = false
-
-# =============================================================================
-# Security Settings
-# =============================================================================
-
-[security]
-# Enable input validation for all user inputs
-input_validation = true
-
-# Prevent directory traversal attacks
-path_traversal_prevention = true
-
-# Scan for hardcoded secrets
-secret_scanning = true
-
-# Scan dependencies for known CVEs
-cve_scanning = true
-
-# Maximum file size for operations (bytes)
-max_file_size = 10485760
-
-# Allowed file extensions (empty = allow all)
-allowed_extensions = []
-
-# Blocked file patterns (regex)
-blocked_patterns = ["\\.env$", "credentials\\.json$", "\\.pem$", "\\.key$"]
-
-# =============================================================================
-# Performance Settings
-# =============================================================================
-
-[performance]
-# Maximum concurrent agents
-max_agents = 8
-
-# Task timeout in seconds
-task_timeout = 300
-
-# Memory limit per agent
-memory_limit = "512MB"
-
-# Enable response caching
-cache_enabled = true
-
-# Cache TTL in seconds
-cache_ttl = 3600
-
-# Enable parallel task execution
-parallel_execution = true
-
-# =============================================================================
-# Logging Settings
-# =============================================================================
-
-[logging]
-# Log level: debug, info, warn, error
-level = "info"
-
-# Log format: json, text, pretty
-format = "pretty"
-
-# Log destination: stdout, file, both
-destination = "stdout"
-
-# =============================================================================
-# Neural Intelligence Settings
-# =============================================================================
-
-[neural]
-# Enable SONA (Self-Optimizing Neural Architecture)
-sona_enabled = true
-
-# Enable HNSW vector search
-hnsw_enabled = true
-
-# HNSW index parameters
-hnsw_m = 16
-hnsw_ef_construction = 200
-hnsw_ef_search = 100
-
-# Enable pattern learning
-pattern_learning = true
-
-# Learning rate for neural adaptation
-learning_rate = 0.01
-
-# =============================================================================
-# Swarm Orchestration Settings
-# =============================================================================
-
-[swarm]
-# Default topology: hierarchical, mesh, ring, star
-default_topology = "hierarchical"
-
-# Default strategy: balanced, specialized, adaptive
-default_strategy = "specialized"
-
-# Consensus algorithm: raft, byzantine, gossip
-consensus = "raft"
-
-# Enable anti-drift measures
-anti_drift = true
-
-# Checkpoint interval (tasks)
-checkpoint_interval = 10
-
-# =============================================================================
-# Hooks Configuration
-# =============================================================================
-
-[hooks]
-# Enable lifecycle hooks
-enabled = true
-
-# Pre-task hook
-pre_task = true
-
-# Post-task hook (for learning)
-post_task = true
-
-# Enable neural training on post-edit
-train_on_edit = true
-
-# =============================================================================
-# Background Workers
-# =============================================================================
-
-[workers]
-# Enable background workers
-enabled = true
-
-# Worker configuration
-[workers.audit]
-enabled = true
-priority = "critical"
-interval = 300
-
-[workers.optimize]
-enabled = true
-priority = "high"
-interval = 600
-
-[workers.consolidate]
-enabled = true
-priority = "low"
-interval = 1800

package/.agents/skills/memory-management/SKILL.md

@@ -1,126 +0,0 @@
----
-name: memory-management
-description: >
-  AgentDB memory system with HNSW vector search. Provides 150x-12,500x faster pattern retrieval, persistent storage, and semantic search capabilities for learning and knowledge management.
-  Use when: need to store successful patterns, searching for similar solutions, semantic lookup of past work, learning from previous tasks, sharing knowledge between agents, building knowledge base.
-  Skip when: no learning needed, ephemeral one-off tasks, external data sources available, read-only exploration.
----
-
-# Memory Management Skill
-
-## Purpose
-AgentDB memory system with HNSW vector search. Provides 150x-12,500x faster pattern retrieval, persistent storage, and semantic search capabilities for learning and knowledge management.
-
-## When to Trigger
-- need to store successful patterns
-- searching for similar solutions
-- semantic lookup of past work
-- learning from previous tasks
-- sharing knowledge between agents
-- building knowledge base
-
-## When to Skip
-- no learning needed
-- ephemeral one-off tasks
-- external data sources available
-- read-only exploration
-
-## Commands
-
-### Store Pattern
-Store a pattern or knowledge item in memory
-
-```bash
-npx @claude-flow/cli memory store --key "[key]" --value "[value]" --namespace patterns
-```
-
-**Example:**
-```bash
-npx @claude-flow/cli memory store --key "auth-jwt-pattern" --value "JWT validation with refresh tokens" --namespace patterns
-```
-
-### Semantic Search
-Search memory using semantic similarity
-
-```bash
-npx @claude-flow/cli memory search --query "[search terms]" --limit 10
-```
-
-**Example:**
-```bash
-npx @claude-flow/cli memory search --query "authentication best practices" --limit 5
-```
-
-### Retrieve Entry
-Retrieve a specific memory entry by key
-
-```bash
-npx @claude-flow/cli memory get --key "[key]" --namespace [namespace]
-```
-
-**Example:**
-```bash
-npx @claude-flow/cli memory get --key "auth-jwt-pattern" --namespace patterns
-```
-
-### List Entries
-List all entries in a namespace
-
-```bash
-npx @claude-flow/cli memory list --namespace [namespace]
-```
-
-**Example:**
-```bash
-npx @claude-flow/cli memory list --namespace patterns --limit 20
-```
-
-### Delete Entry
-Delete a memory entry
-
-```bash
-npx @claude-flow/cli memory delete --key "[key]" --namespace [namespace]
-```
-
-### Initialize HNSW Index
-Initialize HNSW vector search index
-
-```bash
-npx @claude-flow/cli memory init --enable-hnsw
-```
-
-### Memory Stats
-Show memory usage statistics
-
-```bash
-npx @claude-flow/cli memory stats
-```
-
-### Export Memory
-Export memory to JSON
-
-```bash
-npx @claude-flow/cli memory export --output memory-backup.json
-```
-
-
-## Scripts
-
-| Script | Path | Description |
-|--------|------|-------------|
-| `memory-backup` | `.agents/scripts/memory-backup.sh` | Backup memory to external storage |
-| `memory-consolidate` | `.agents/scripts/memory-consolidate.sh` | Consolidate and optimize memory |
-
-
-## References
-
-| Document | Path | Description |
-|----------|------|-------------|
-| `HNSW Guide` | `docs/hnsw.md` | HNSW vector search configuration |
-| `Memory Schema` | `docs/memory-schema.md` | Memory namespace and schema reference |
-
-## Best Practices
-1. Check memory for existing patterns before starting
-2. Use hierarchical topology for coordination
-3. Store successful patterns after completion
-4. Document any new learnings

package/.agents/skills/memory-management/scripts/memory-backup.sh

@@ -1,16 +0,0 @@
-#!/bin/bash
-# Memory Management - Backup Script
-# Export memory to backup file
-
-set -e
-
-BACKUP_DIR="${BACKUP_DIR:-./.backups}"
-TIMESTAMP=$(date +%Y%m%d_%H%M%S)
-BACKUP_FILE="${BACKUP_DIR}/memory_${TIMESTAMP}.json"
-
-mkdir -p "$BACKUP_DIR"
-
-echo "Backing up memory to $BACKUP_FILE..."
-npx @claude-flow/cli memory export --output "$BACKUP_FILE"
-
-echo "Backup complete: $BACKUP_FILE"

package/.agents/skills/memory-management/scripts/memory-consolidate.sh

@@ -1,11 +0,0 @@
-#!/bin/bash
-# Memory Management - Consolidate Script
-# Optimize and consolidate memory
-
-set -e
-
-echo "Running memory consolidation..."
-npx @claude-flow/cli hooks worker dispatch --trigger consolidate
-
-echo "Memory consolidation complete"
-npx @claude-flow/cli memory stats