claude-flow-guidance-implementation 0.1.4 → 0.1.6

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +120 -77
  2. package/package.json +17 -7
package/README.md CHANGED
@@ -1,20 +1,34 @@
1
1
  # claude-flow-guidance-implementation
2
2
 
3
- NPM-first implementation kit for wiring `@claude-flow/guidance` into any repository.
3
+ Implementation kit for wiring `@claude-flow/guidance` into real repos with repeatable automation for Claude Code hooks, Codex lifecycle events, and guidance optimization workflows.
4
4
 
5
- It installs a reusable guidance control plane with:
6
- - Claude Code hook bridge
7
- - Codex lifecycle bridge
8
- - guidance runtime scripts
9
- - autopilot promotion loop (`CLAUDE.local.md` -> `CLAUDE.md`)
10
- - verification tooling
5
+ ## What This Package Is
11
6
 
12
- ## Install and run
7
+ This package is an installer and scaffold, not just an API example.
8
+ It creates a working guidance control plane in a target repo, including:
13
9
 
14
- Use directly from npm (no clone required):
10
+ - hook event wiring (`pre-*` and `post-*`)
11
+ - guidance runtime scripts (`analyze`, `optimize`, `ab-benchmark`, modules)
12
+ - Codex bridge commands (optional)
13
+ - `CLAUDE.local.md` bootstrap for local-only experiments
14
+ - verification checks so setup can be validated immediately
15
+
16
+ ## What `quickstart` is doing
17
+
18
+ The quickstart commands do two things:
19
+
20
+ - run `init` to install and wire scripts/config into your target repo
21
+ - run `verify` to confirm that required files, hooks, and syntax checks pass
22
+
23
+ It is meant to produce a runnable integration, not just generate documentation.
24
+
25
+ ## Quickstart
26
+
27
+ Use directly from npm:
15
28
 
16
29
  ```bash
17
30
  npx --yes -p claude-flow-guidance-implementation cf-guidance-impl init --target ~/source/my-project --install-deps
31
+ npx --yes -p claude-flow-guidance-implementation cf-guidance-impl verify --target ~/source/my-project
18
32
  ```
19
33
 
20
34
  Or install as a dev dependency:
@@ -22,106 +36,135 @@ Or install as a dev dependency:
22
36
  ```bash
23
37
  npm i -D claude-flow-guidance-implementation
24
38
  npx cf-guidance-impl init --target ~/source/my-project --install-deps
39
+ npx cf-guidance-impl verify --target ~/source/my-project
25
40
  ```
26
41
 
27
- Choose integration target mode explicitly when needed:
42
+ ## Integration Modes
43
+
44
+ | Mode | What gets wired |
45
+ |---|---|
46
+ | `both` (default) | Claude hooks + Codex bridge + guidance scripts |
47
+ | `claude` | Claude hooks + guidance scripts |
48
+ | `codex` | Codex bridge + guidance scripts |
49
+
50
+ Examples:
28
51
 
29
52
  ```bash
30
- # default: both Claude + Codex wiring
31
53
  npx cf-guidance-impl init --target ~/source/my-project --target-mode both
32
-
33
- # Claude-only wiring (.claude hooks + settings merge)
34
54
  npx cf-guidance-impl init --target ~/source/my-project --target-mode claude
35
-
36
- # Codex-only wiring (.agents bridge + codex scripts)
37
55
  npx cf-guidance-impl init --target ~/source/my-project --target-mode codex
38
56
  ```
39
57
 
40
- ## Quickstart
58
+ ## CLI Reference
41
59
 
42
60
  ```bash
43
- # 1) initialize and wire a target repo
44
- npx --yes -p claude-flow-guidance-implementation cf-guidance-impl init --target ~/source/my-project --install-deps
45
-
46
- # 2) verify wiring
47
- npx --yes -p claude-flow-guidance-implementation cf-guidance-impl verify --target ~/source/my-project
61
+ cf-guidance-impl init --target <repoPath> [--target-mode both|claude|codex] [--force] [--install-deps] [--no-dual] [--skip-cf-init] [--no-verify]
62
+ cf-guidance-impl install --target <repoPath> [--target-mode both|claude|codex] [--force] [--install-deps]
63
+ cf-guidance-impl verify --target <repoPath> [--target-mode both|claude|codex]
48
64
  ```
49
65
 
50
- ## Package Runtime Mode (No Local Guidance Code)
51
-
52
- You can run guidance directly from `node_modules` and avoid committing copied guidance runtime files.
66
+ ## What `init` Changes In Your Target Repo
53
67
 
54
- Example `package.json` scripts in a target repo:
68
+ `cf-guidance-impl init` performs:
55
69
 
56
- ```bash
57
- "guidance:analyze": "node ./node_modules/claude-flow-guidance-implementation/scaffold/scripts/analyze-guidance.js",
58
- "guidance:optimize": "node ./node_modules/claude-flow-guidance-implementation/scaffold/scripts/guidance-autopilot.js --once --apply --source manual",
59
- "guidance:ab-benchmark": "node ./node_modules/claude-flow-guidance-implementation/scaffold/scripts/guidance-ab-benchmark.js",
60
- "guidance:codex:status": "node ./node_modules/claude-flow-guidance-implementation/scaffold/scripts/guidance-codex-bridge.js status"
70
+ 1. Runs `npx @claude-flow/cli@latest init` unless `--skip-cf-init`.
71
+ 2. Adds CLI mode flags automatically:
72
+ - `both` uses `--dual` unless `--no-dual`
73
+ - `codex` uses `--codex`
74
+ - `claude` uses standard init
75
+ 3. Copies scaffold runtime files (`scripts/`, `src/guidance/`, docs, hook handler).
76
+ 4. Merges guidance scripts and dependencies into `package.json`.
77
+ 5. Merges `.claude/settings.json` env and hooks in Claude-enabled modes.
78
+ 6. Appends Codex bridge sections to `.agents/config.toml` and `AGENTS.md` in Codex-enabled modes.
79
+ 7. Creates `CLAUDE.local.md` (if missing) and appends `CLAUDE.local.md` to `.gitignore`.
80
+ 8. Runs verification unless `--no-verify`.
81
+
82
+ ## Installed Scripts (Target Repo)
83
+
84
+ Core:
85
+
86
+ - `guidance:analyze`
87
+ - `guidance:optimize`
88
+ - `guidance:autopilot:once`
89
+ - `guidance:autopilot:daemon`
90
+ - `guidance:ab-benchmark`
91
+ - `guidance:status`
92
+ - `guidance:all`
93
+ - `guidance:trust`
94
+ - `guidance:adversarial`
95
+ - `guidance:proof`
96
+ - `guidance:conformance`
97
+ - `guidance:evolution`
98
+
99
+ Codex lifecycle bridge:
100
+
101
+ - `guidance:codex:status`
102
+ - `guidance:codex:session-start`
103
+ - `guidance:codex:pre-command`
104
+ - `guidance:codex:pre-edit`
105
+ - `guidance:codex:pre-task`
106
+ - `guidance:codex:post-edit`
107
+ - `guidance:codex:post-task`
108
+ - `guidance:codex:session-end`
109
+
110
+ ## Manual Runtime Mode (No Copied Runtime Files)
111
+
112
+ You can also execute scripts directly from `node_modules`:
113
+
114
+ ```json
115
+ {
116
+ "scripts": {
117
+ "guidance:analyze": "node ./node_modules/claude-flow-guidance-implementation/scaffold/scripts/analyze-guidance.js",
118
+ "guidance:optimize": "node ./node_modules/claude-flow-guidance-implementation/scaffold/scripts/guidance-autopilot.js --once --apply --source manual",
119
+ "guidance:ab-benchmark": "node ./node_modules/claude-flow-guidance-implementation/scaffold/scripts/guidance-ab-benchmark.js",
120
+ "guidance:codex:status": "node ./node_modules/claude-flow-guidance-implementation/scaffold/scripts/guidance-codex-bridge.js status"
121
+ }
122
+ }
61
123
  ```
62
124
 
63
125
  Project root resolution for scaffold scripts:
64
- - `GUIDANCE_PROJECT_DIR` (if set)
65
- - else `CLAUDE_PROJECT_DIR` (if set)
66
- - else current working directory (`process.cwd()`)
67
126
 
68
- ## CLI commands
127
+ - `GUIDANCE_PROJECT_DIR` if set
128
+ - else `CLAUDE_PROJECT_DIR` if set
129
+ - else `process.cwd()`
69
130
 
70
- ```bash
71
- cf-guidance-impl init --target <repoPath> [--target-mode both|claude|codex] [--force] [--install-deps] [--no-dual] [--skip-cf-init] [--no-verify]
72
- cf-guidance-impl install --target <repoPath> [--target-mode both|claude|codex] [--force] [--install-deps]
73
- cf-guidance-impl verify --target <repoPath> [--target-mode both|claude|codex]
74
- ```
75
-
76
- ## What `init` does
77
-
78
- `cf-guidance-impl init` performs:
79
- 1. runs `npx @claude-flow/cli@latest init` in target repo (unless `--skip-cf-init`)
80
- 2. adds init flags by mode:
81
- - `--target-mode both` + default dual -> `--dual`
82
- - `--target-mode codex` -> `--codex`
83
- - `--target-mode claude` -> no codex flag
84
- - `--no-dual` only affects `both` mode (skips `--dual`)
85
- 3. installs scaffold runtime files (`scripts/`, `src/guidance/`, `.claude/helpers/hook-handler.cjs`, docs)
86
- 4. merges target `package.json` scripts + guidance deps (Codex scripts only for `both|codex`)
87
- 5. merges `.claude/settings.json` env and hook blocks (only for `both|claude`)
88
- 6. appends Codex bridge sections to `.agents/config.toml` and `AGENTS.md` (only for `both|codex`)
89
- 7. creates `CLAUDE.local.md` stub and updates `.gitignore`
90
- 8. verifies wiring for selected mode (unless `--no-verify`)
91
-
92
- ## Codex lifecycle integration
93
-
94
- After installation, these scripts are available in the target repo:
131
+ ## Verify + Smoke Test
95
132
 
96
133
  ```bash
97
- npm run guidance:codex:session-start
98
- npm run guidance:codex:pre-task -- --task-id task-123 --description "Implement feature X"
99
- npm run guidance:codex:pre-command -- --task-id task-123 --command "git status"
100
- npm run guidance:codex:pre-edit -- --task-id task-123 --file src/example.ts --operation modify
101
- npm run guidance:codex:post-edit -- --task-id task-123 --file src/example.ts
102
- npm run guidance:codex:post-task -- --task-id task-123 --status completed --description "Implement feature X"
103
- npm run guidance:codex:session-end -- --task-id task-123
134
+ npx cf-guidance-impl verify --target ~/source/my-project
135
+ cd ~/source/my-project
136
+ npm run guidance:status
137
+ npm run guidance:analyze
138
+ npm run guidance:codex:status
104
139
  ```
105
140
 
106
- Validation smoke check:
141
+ For Codex bridge smoke checks:
107
142
 
108
143
  ```bash
109
- npm run guidance:codex:status
110
- npm run guidance:codex:pre-task -- --task-id smoke-1 --description "smoke" --skip-cf-hooks
144
+ npm run guidance:codex:pre-task -- --task-id smoke-1 --description "smoke"
111
145
  ```
112
146
 
113
- Expected JSON output:
114
- - `handler.ok: true` -> local bridge + hook-handler path succeeded
115
- - `claudeFlowHook.ok: true` -> secondary `@claude-flow/cli` hook invocation succeeded
147
+ Expected success signals:
148
+
149
+ - `handler.ok: true` means local bridge path succeeded
150
+ - `claudeFlowHook.ok: true` means optional `@claude-flow/cli` hook call succeeded
116
151
 
117
- ## Notes
152
+ ## Installed Files (High-Level)
118
153
 
119
- - Target repo config is merged, not replaced.
120
- - Default local guidance file is `CLAUDE.local.md` (gitignored).
121
- - Advanced reference docs are installed into target `docs/`.
154
+ | Path | Purpose |
155
+ |---|---|
156
+ | `.claude/helpers/hook-handler.cjs` | Event entrypoint for hook dispatch |
157
+ | `scripts/guidance-integrations.js` | Unified guidance module runner |
158
+ | `scripts/guidance-codex-bridge.js` | Codex lifecycle adapter |
159
+ | `scripts/guidance-autopilot.js` | Local-rule optimization/promotion loop |
160
+ | `src/guidance/phase1-runtime.js` | Compile/retrieve/gates/ledger integration |
161
+ | `src/guidance/advanced-runtime.js` | Trust/adversarial/proof/conformance/evolution modules |
162
+ | `docs/guidance-control-plane.md` | Operational overview |
163
+ | `docs/guidance-implementation-guide.md` | Authoritative implementation guide |
122
164
 
123
165
  ## Links
124
166
 
167
+ - Homepage: https://sparkling.github.io/claude-flow/guidance
168
+ - Package: https://www.npmjs.com/package/claude-flow-guidance-implementation
125
169
  - GitHub: https://github.com/sparkling/claude-flow-guidance-implementation
126
170
  - Issues: https://github.com/sparkling/claude-flow-guidance-implementation/issues
127
- - Package: https://www.npmjs.com/package/claude-flow-guidance-implementation
package/package.json CHANGED
@@ -1,18 +1,25 @@
1
1
  {
2
2
  "name": "claude-flow-guidance-implementation",
3
- "version": "0.1.4",
4
- "description": "Reusable guidance control-plane implementation kit for wiring @claude-flow/guidance into any repo",
3
+ "version": "0.1.6",
4
+ "description": "Implementation kit for wiring @claude-flow/guidance into Claude Code and Codex repos with hook automation",
5
5
  "type": "module",
6
6
  "private": false,
7
+ "license": "MIT",
7
8
  "author": "Sparkling Ideas <henrik@sparklingideas.co.uk>",
8
9
  "repository": {
9
10
  "type": "git",
10
11
  "url": "git+https://github.com/sparkling/claude-flow-guidance-implementation.git"
11
12
  },
12
- "homepage": "https://github.com/sparkling/claude-flow-guidance-implementation#readme",
13
+ "homepage": "https://sparkling.github.io/claude-flow/guidance",
13
14
  "bugs": {
14
15
  "url": "https://github.com/sparkling/claude-flow-guidance-implementation/issues"
15
16
  },
17
+ "engines": {
18
+ "node": ">=20"
19
+ },
20
+ "publishConfig": {
21
+ "access": "public"
22
+ },
16
23
  "files": [
17
24
  "bin",
18
25
  "src",
@@ -31,12 +38,15 @@
31
38
  "keywords": [
32
39
  "claude-flow",
33
40
  "guidance",
34
- "codex",
35
- "claude-md",
36
41
  "agentic",
42
+ "claude-md",
43
+ "codex",
44
+ "control-plane",
45
+ "hook-handler",
37
46
  "hooks",
38
47
  "claude-code",
39
- "automation"
48
+ "automation",
49
+ "autopilot"
40
50
  ],
41
- "license": "MIT"
51
+ "packageManager": "npm@10"
42
52
  }