@hassangameryt/freeflow 0.5.0 → 0.7.0
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.
- package/.claude-plugin/marketplace.json +1 -1
- package/.claude-plugin/plugin.json +2 -2
- package/.codex-plugin/plugin.json +4 -5
- package/README.md +141 -163
- package/capabilities/cognitive-routing/SKILL.md +387 -0
- package/capabilities/context-virtualization/SKILL.md +103 -0
- package/capabilities/conversation-history/SKILL.md +53 -0
- package/command-surface.json +6 -37
- package/hooks/freeflow-runtime-context.mjs +50 -541
- package/hooks/hooks.json +1 -26
- package/hooks/tests/check-runtime-context-hook.sh +114 -308
- package/package.json +27 -17
- package/pi-extension/dist/cognitive-routing/commands.js +96 -0
- package/pi-extension/dist/cognitive-routing/config.js +232 -0
- package/pi-extension/dist/cognitive-routing/controller.js +1292 -0
- package/pi-extension/dist/cognitive-routing/history.js +451 -0
- package/pi-extension/dist/cognitive-routing/host.js +188 -0
- package/pi-extension/dist/cognitive-routing/pi-routing-session.js +414 -0
- package/pi-extension/dist/cognitive-routing/pi-session-control.js +320 -0
- package/pi-extension/dist/cognitive-routing/runtime.js +43 -0
- package/pi-extension/dist/cognitive-routing/tool.js +212 -0
- package/pi-extension/dist/cognitive-routing/types.js +6 -0
- package/pi-extension/dist/context-virtualization/commands.js +89 -0
- package/pi-extension/dist/context-virtualization/projector.js +42 -0
- package/pi-extension/dist/context-virtualization/runtime.js +356 -0
- package/pi-extension/dist/context-virtualization/state.js +57 -0
- package/pi-extension/dist/context-virtualization/types.js +10 -0
- package/pi-extension/dist/conversation-history/passages.js +66 -0
- package/pi-extension/dist/conversation-history/ranking.js +105 -0
- package/pi-extension/dist/conversation-history/runtime.js +226 -0
- package/pi-extension/dist/conversation-history/search.js +56 -0
- package/pi-extension/dist/conversation-history/types.js +1 -0
- package/pi-extension/dist/freeflow-context/resolver.js +120 -0
- package/pi-extension/dist/freeflow-context/runtime.js +80 -0
- package/pi-extension/dist/freeflow-context/source-projector.js +95 -0
- package/pi-extension/dist/freeflow-context/tool.js +308 -0
- package/pi-extension/dist/freeflow-context/types.js +12 -0
- package/pi-extension/dist/freeflow-context/visibility.js +28 -0
- package/pi-extension/dist/index.js +564 -129
- package/pi-extension/dist/runtime/runtime-context.js +357 -470
- package/pi-extension/dist/runtime/runtime-identity.js +5 -0
- package/pi-extension/dist/settings/settings-tui.js +78 -0
- package/pi-extension/dist/settings/settings-ui.js +572 -826
- package/pi-extension/dist/ui/text-component.js +57 -0
- package/pi-extension/src/cognitive-routing/commands.ts +129 -0
- package/pi-extension/src/cognitive-routing/config.ts +303 -0
- package/pi-extension/src/cognitive-routing/controller.ts +1628 -0
- package/pi-extension/src/cognitive-routing/history.ts +650 -0
- package/pi-extension/src/cognitive-routing/host.ts +266 -0
- package/pi-extension/src/cognitive-routing/pi-routing-session.ts +538 -0
- package/pi-extension/src/cognitive-routing/pi-session-control.ts +444 -0
- package/pi-extension/src/cognitive-routing/runtime.ts +57 -0
- package/pi-extension/src/cognitive-routing/tool.ts +273 -0
- package/pi-extension/src/cognitive-routing/types.ts +89 -0
- package/pi-extension/src/context-virtualization/commands.ts +111 -0
- package/pi-extension/src/context-virtualization/projector.ts +62 -0
- package/pi-extension/src/context-virtualization/runtime.ts +406 -0
- package/pi-extension/src/context-virtualization/state.ts +79 -0
- package/pi-extension/src/context-virtualization/types.ts +92 -0
- package/pi-extension/src/conversation-history/passages.ts +81 -0
- package/pi-extension/src/conversation-history/ranking.ts +155 -0
- package/pi-extension/src/conversation-history/runtime.ts +250 -0
- package/pi-extension/src/conversation-history/search.ts +79 -0
- package/pi-extension/src/conversation-history/types.ts +31 -0
- package/pi-extension/src/freeflow-context/resolver.ts +139 -0
- package/pi-extension/src/freeflow-context/runtime.ts +100 -0
- package/pi-extension/src/freeflow-context/source-projector.ts +106 -0
- package/pi-extension/src/freeflow-context/tool.ts +360 -0
- package/pi-extension/src/freeflow-context/types.ts +70 -0
- package/pi-extension/src/freeflow-context/visibility.ts +53 -0
- package/pi-extension/src/index.ts +597 -135
- package/pi-extension/src/runtime/runtime-context.ts +373 -491
- package/pi-extension/src/runtime/runtime-identity.ts +8 -0
- package/pi-extension/src/settings/settings-tui.ts +93 -0
- package/pi-extension/src/settings/settings-ui.ts +679 -910
- package/pi-extension/src/ui/text-component.ts +66 -0
- package/pi-extension/tests/cognitive-routing/commands.test.js +134 -0
- package/pi-extension/tests/cognitive-routing/controller.test.js +1128 -0
- package/pi-extension/tests/cognitive-routing/extension-lifecycle.test.js +1142 -0
- package/pi-extension/tests/cognitive-routing/history.test.js +274 -0
- package/pi-extension/tests/cognitive-routing/host-fixture.js +4 -0
- package/pi-extension/tests/cognitive-routing/host-identity.test.js +63 -0
- package/pi-extension/tests/cognitive-routing/pi-normal-lifecycle.test.js +434 -0
- package/pi-extension/tests/cognitive-routing/pi-session-control.test.js +174 -0
- package/pi-extension/tests/cognitive-routing/pi-session-history.test.js +91 -0
- package/pi-extension/tests/cognitive-routing/profile-resolution.test.js +279 -0
- package/pi-extension/tests/cognitive-routing/tool.test.js +230 -0
- package/pi-extension/tests/context-virtualization/extension.test.js +749 -0
- package/pi-extension/tests/context-virtualization/projector.test.js +110 -0
- package/pi-extension/tests/context-virtualization/runtime.test.js +216 -0
- package/pi-extension/tests/conversation-history/runtime.test.js +98 -0
- package/pi-extension/tests/conversation-history/search.test.js +97 -0
- package/pi-extension/tests/integration/mode-free-core.test.js +218 -0
- package/pi-extension/tests/integration/pi-extension.test.js +532 -3701
- package/pi-extension/tests/integration/prompt-architecture.test.js +350 -0
- package/pi-extension/tests/integration/unaffected-regressions.test.js +411 -0
- package/runtime/prompts/cognitive-routing.md +10 -0
- package/runtime/prompts/context-virtualization.md +3 -0
- package/runtime/prompts/conversation-history.md +3 -0
- package/runtime/prompts/core.md +84 -0
- package/runtime/prompts/interaction-contract.md +11 -0
- package/skills/action-selection/SKILL.md +140 -0
- package/skills/action-selection/references/trajectory-stalls.md +71 -0
- package/skills/bypass/SKILL.md +109 -38
- package/skills/commit-work/SKILL.md +94 -55
- package/skills/commit-work/references/git-state-edges.md +94 -0
- package/skills/commit-work/references/simple-push.md +92 -0
- package/skills/commit-work/references/staging-decisions.md +79 -46
- package/skills/decision-gate/SKILL.md +80 -22
- package/skills/design-for-depth/SKILL.md +206 -60
- package/skills/design-for-depth/references/design-pressure-signals.md +108 -240
- package/skills/design-for-depth/references/interface-design-loop.md +77 -97
- package/skills/design-for-depth/references/module-and-dependency-design.md +147 -0
- package/skills/design-for-depth/references/software-design-philosophy.md +128 -174
- package/skills/design-for-depth/references/state-and-failure-boundaries.md +136 -0
- package/skills/diagnose-failure/SKILL.md +200 -48
- package/skills/diagnose-failure/references/diagnostic-loop-catalog.md +18 -6
- package/skills/diagnose-failure/references/{flaky-and-performance.md → flaky-and-performance-diagnosis.md} +13 -5
- package/skills/discuss/SKILL.md +119 -65
- package/skills/discuss/references/discussion-continuity.md +123 -0
- package/skills/evaluate-skill/SKILL.md +166 -52
- package/skills/evaluate-skill/references/{definition-schema.md → evaluation-definition-schema.md} +43 -3
- package/skills/evaluate-skill/references/evaluation-design.md +56 -30
- package/skills/evaluate-skill/references/execution-and-evidence.md +8 -3
- package/skills/evaluate-skill/references/review-and-revision.md +62 -21
- package/skills/evaluate-skill/scripts/lib/definitions.mjs +114 -3
- package/skills/evaluate-skill/scripts/lib/grade-interaction.mjs +156 -1
- package/skills/evaluate-skill/scripts/lib/grade.mjs +9 -1
- package/skills/evaluate-skill/scripts/lib/pi.mjs +147 -32
- package/skills/evaluate-skill/scripts/lib/rpc.mjs +4 -4
- package/skills/evaluate-skill/scripts/lib/runner.mjs +36 -14
- package/skills/evaluate-skill/scripts/lib/sandbox.mjs +92 -0
- package/skills/evaluate-skill/scripts/pi-guard.mjs +1 -1
- package/skills/evaluate-skill/scripts/pi-observer.mjs +66 -0
- package/skills/evaluate-skill/scripts/skill-eval.mjs +6 -5
- package/skills/execute-work/SKILL.md +99 -57
- package/skills/execute-work/references/code-practices.md +4 -4
- package/skills/execute-work/references/execute-work-edges.md +62 -0
- package/skills/finish-branch/SKILL.md +2 -2
- package/skills/finish-branch/references/integration-options.md +1 -1
- package/skills/handoff/SKILL.md +3 -3
- package/skills/launch-work/SKILL.md +1 -1
- package/skills/launch-work/references/launch-readiness.md +2 -2
- package/skills/migration-work/SKILL.md +2 -2
- package/skills/migration-work/references/migration-lifecycle.md +1 -1
- package/skills/release-work/SKILL.md +1 -1
- package/skills/release-work/references/release-evidence.md +1 -1
- package/skills/review-artifact/SKILL.md +129 -66
- package/skills/review-artifact/references/adjudicate-artifact-review.md +101 -0
- package/skills/review-artifact/references/independent-artifact-reviewer-contract.md +159 -0
- package/skills/review-work/SKILL.md +113 -68
- package/skills/review-work/references/adjudicate-work-review.md +97 -0
- package/skills/review-work/references/independent-work-reviewer-contract.md +139 -0
- package/skills/review-work/references/security-risk-lens.md +18 -16
- package/skills/setup-freeflow/SKILL.md +16 -17
- package/skills/setup-freeflow/references/activation-contract.md +24 -30
- package/skills/setup-freeflow/references/host-setup.md +6 -7
- package/skills/simplify-code/SKILL.md +97 -39
- package/skills/simplify-code/references/simplification-patterns.md +1 -1
- package/skills/tdd/SKILL.md +100 -53
- package/skills/tdd/references/test-design.md +3 -3
- package/skills/track-work/SKILL.md +195 -58
- package/skills/track-work/references/working-record-format.md +515 -0
- package/skills/track-work/scripts/lib/document.mjs +713 -0
- package/skills/track-work/scripts/lib/format.mjs +166 -0
- package/skills/track-work/scripts/lib/store.mjs +233 -0
- package/skills/track-work/scripts/lib/transitions.mjs +790 -0
- package/skills/track-work/scripts/lib/views.mjs +40 -0
- package/skills/track-work/scripts/working-record.mjs +316 -0
- package/skills/verify-work/SKILL.md +57 -19
- package/skills/verify-work/references/browser-runtime-evidence.md +2 -2
- package/skills/verify-work/references/integration-evidence.md +1 -7
- package/skills/verify-work/references/performance-evidence.md +2 -2
- package/skills/workflow/SKILL.md +137 -55
- package/skills/workflow/references/domain-skill-composition.md +26 -40
- package/skills/write-plan/SKILL.md +1 -1
- package/skills/write-skill/SKILL.md +218 -61
- package/skills/write-skill/references/activation-boundaries.md +63 -21
- package/skills/write-skill/references/agent-first-instructions.md +61 -27
- package/skills/write-skill/references/progressive-disclosure.md +97 -33
- package/skills/write-skill/references/skill-dependency-graphs.md +190 -0
- package/capabilities/output-router/SKILL.md +0 -206
- package/capabilities/output-router/references/safety-policy.md +0 -40
- package/capabilities/output-router/references/setup.md +0 -110
- package/pi-extension/dist/output-router/host-producer-identification.js +0 -232
- package/pi-extension/dist/output-router/native-safety-net.js +0 -216
- package/pi-extension/dist/output-router/observed-tool-routing.js +0 -122
- package/pi-extension/dist/output-router/renderers.js +0 -1023
- package/pi-extension/dist/output-router/router-tools.js +0 -554
- package/pi-extension/dist/output-router/schemas.js +0 -383
- package/pi-extension/dist/output-router/status.js +0 -744
- package/pi-extension/dist/output-router/utils.js +0 -502
- package/pi-extension/src/output-router/host-producer-identification.ts +0 -256
- package/pi-extension/src/output-router/native-safety-net.ts +0 -248
- package/pi-extension/src/output-router/observed-tool-routing.ts +0 -134
- package/pi-extension/src/output-router/renderers.ts +0 -1108
- package/pi-extension/src/output-router/router-tools.ts +0 -579
- package/pi-extension/src/output-router/schemas.ts +0 -387
- package/pi-extension/src/output-router/status.ts +0 -791
- package/pi-extension/src/output-router/utils.ts +0 -554
- package/pi-extension/tests/output-router/observed-producers.test.js +0 -132
- package/pi-extension/tests/output-router/search.test.js +0 -722
- package/router/dist/benchmarks/benchmark-harness.d.ts +0 -35
- package/router/dist/benchmarks/benchmark-harness.js +0 -92
- package/router/dist/benchmarks/benchmarks.d.ts +0 -109
- package/router/dist/benchmarks/benchmarks.js +0 -979
- package/router/dist/benchmarks/codex-qa-benchmarks.d.ts +0 -95
- package/router/dist/benchmarks/codex-qa-benchmarks.js +0 -500
- package/router/dist/benchmarks/command-benchmarks.d.ts +0 -143
- package/router/dist/benchmarks/command-benchmarks.js +0 -698
- package/router/dist/benchmarks/context-mode-normalized-benchmarks.d.ts +0 -82
- package/router/dist/benchmarks/context-mode-normalized-benchmarks.js +0 -773
- package/router/dist/benchmarks/context-mode-real-deep-benchmark.d.ts +0 -132
- package/router/dist/benchmarks/context-mode-real-deep-benchmark.js +0 -1380
- package/router/dist/benchmarks/context-saving-baseline.d.ts +0 -60
- package/router/dist/benchmarks/context-saving-baseline.js +0 -470
- package/router/dist/benchmarks/index-benchmarks.d.ts +0 -103
- package/router/dist/benchmarks/index-benchmarks.js +0 -862
- package/router/dist/benchmarks/storage-policy-benchmarks.d.ts +0 -101
- package/router/dist/benchmarks/storage-policy-benchmarks.js +0 -618
- package/router/dist/benchmarks/vault-index-benchmarks.d.ts +0 -56
- package/router/dist/benchmarks/vault-index-benchmarks.js +0 -322
- package/router/dist/config/config.d.ts +0 -103
- package/router/dist/config/config.js +0 -632
- package/router/dist/config/router-contract.d.ts +0 -10
- package/router/dist/config/router-contract.js +0 -54
- package/router/dist/config/schema.d.ts +0 -27
- package/router/dist/config/schema.js +0 -648
- package/router/dist/config/types.d.ts +0 -573
- package/router/dist/config/types.js +0 -41
- package/router/dist/evidence/bounded-evidence.d.ts +0 -40
- package/router/dist/evidence/bounded-evidence.js +0 -323
- package/router/dist/evidence/evidence-range-selector.d.ts +0 -24
- package/router/dist/evidence/evidence-range-selector.js +0 -232
- package/router/dist/evidence/evidence-search.d.ts +0 -27
- package/router/dist/evidence/evidence-search.js +0 -490
- package/router/dist/evidence/evidence.d.ts +0 -38
- package/router/dist/evidence/evidence.js +0 -200
- package/router/dist/evidence/failure-contracts.d.ts +0 -37
- package/router/dist/evidence/failure-contracts.js +0 -166
- package/router/dist/evidence/line-ranges.d.ts +0 -24
- package/router/dist/evidence/line-ranges.js +0 -22
- package/router/dist/experiments/local-index.d.ts +0 -64
- package/router/dist/experiments/local-index.js +0 -581
- package/router/dist/index.d.ts +0 -30
- package/router/dist/index.js +0 -32
- package/router/dist/local/local-traversal.d.ts +0 -18
- package/router/dist/local/local-traversal.js +0 -334
- package/router/dist/processing/engine.d.ts +0 -132
- package/router/dist/processing/engine.js +0 -533
- package/router/dist/processing/reducers.d.ts +0 -280
- package/router/dist/processing/reducers.js +0 -1673
- package/router/dist/processing/renderers.d.ts +0 -31
- package/router/dist/processing/renderers.js +0 -195
- package/router/dist/processing/scripts.d.ts +0 -91
- package/router/dist/processing/scripts.js +0 -386
- package/router/dist/repo/repo-traversal.d.ts +0 -18
- package/router/dist/repo/repo-traversal.js +0 -245
- package/router/dist/routing/observed-reducers.d.ts +0 -41
- package/router/dist/routing/observed-reducers.js +0 -661
- package/router/dist/routing/observed-routing.d.ts +0 -26
- package/router/dist/routing/observed-routing.js +0 -378
- package/router/dist/routing/parsers.d.ts +0 -16
- package/router/dist/routing/parsers.js +0 -521
- package/router/dist/routing/run-filters.d.ts +0 -60
- package/router/dist/routing/run-filters.js +0 -238
- package/router/dist/routing/run-reducers.d.ts +0 -49
- package/router/dist/routing/run-reducers.js +0 -122
- package/router/dist/sandbox/adapter-roots.d.ts +0 -46
- package/router/dist/sandbox/adapter-roots.js +0 -66
- package/router/dist/sandbox/eryx-python-adapter.d.ts +0 -13
- package/router/dist/sandbox/eryx-python-adapter.js +0 -868
- package/router/dist/sandbox/jq-wasm-adapter.d.ts +0 -9
- package/router/dist/sandbox/jq-wasm-adapter.js +0 -429
- package/router/dist/sandbox/quickjs-wasi-adapter.d.ts +0 -13
- package/router/dist/sandbox/quickjs-wasi-adapter.js +0 -384
- package/router/dist/sandbox/script-sandbox.d.ts +0 -134
- package/router/dist/sandbox/script-sandbox.js +0 -337
- package/router/dist/setup/script-transform-adapters.d.ts +0 -32
- package/router/dist/setup/script-transform-adapters.js +0 -278
- package/router/dist/tools/batch.d.ts +0 -33
- package/router/dist/tools/batch.js +0 -586
- package/router/dist/tools/run.d.ts +0 -62
- package/router/dist/tools/run.js +0 -1304
- package/router/dist/tools/search.d.ts +0 -66
- package/router/dist/tools/search.js +0 -1364
- package/router/dist/transform/engine.d.ts +0 -168
- package/router/dist/transform/engine.js +0 -2072
- package/router/dist/vault/vault-index.d.ts +0 -125
- package/router/dist/vault/vault-index.js +0 -416
- package/router/dist/vault/vault.d.ts +0 -138
- package/router/dist/vault/vault.js +0 -630
- package/runtime/interaction-contract.md +0 -16
- package/skills/discuss/references/checkpoints.md +0 -66
- package/skills/execute-work/references/execution-loop.md +0 -77
- package/skills/mode-contract/SKILL.md +0 -104
- package/skills/review-artifact/references/reviewer-prompt.md +0 -148
- package/skills/review-work/references/reviewer-prompt.md +0 -134
- package/skills/track-work/references/working-record-schema.md +0 -378
- package/skills/workflow/references/workflow-loop.md +0 -92
- /package/skills/handoff/references/{templates.md → handoff-templates.md} +0 -0
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "freeflow",
|
|
3
|
-
"description": "Freeflow gives coding agents an Interaction Contract,
|
|
4
|
-
"version": "0.
|
|
3
|
+
"description": "Freeflow gives coding agents an Interaction Contract, adaptive Workflow, focused methods, and durable task memory.",
|
|
4
|
+
"version": "0.7.0",
|
|
5
5
|
"author": {
|
|
6
6
|
"name": "Hassan Mohiddin"
|
|
7
7
|
},
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "freeflow",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.7.0",
|
|
4
4
|
"description": "Feedback-based control system for coding agents.",
|
|
5
5
|
"author": {
|
|
6
6
|
"name": "Hassan Mohiddin"
|
|
@@ -25,14 +25,13 @@
|
|
|
25
25
|
"interface": {
|
|
26
26
|
"displayName": "Freeflow",
|
|
27
27
|
"shortDescription": "Feedback-based control for coding agents.",
|
|
28
|
-
"longDescription": "Freeflow gives coding agents an Interaction Contract,
|
|
28
|
+
"longDescription": "Freeflow gives coding agents an Interaction Contract, adaptive Workflow, focused methods, and durable task memory.",
|
|
29
29
|
"developerName": "Hassan Mohiddin",
|
|
30
30
|
"category": "Coding",
|
|
31
31
|
"capabilities": ["Interactive", "Read", "Write"],
|
|
32
32
|
"defaultPrompt": [
|
|
33
|
-
"Use Freeflow
|
|
34
|
-
"
|
|
35
|
-
"Use strict-workflow for this risky change."
|
|
33
|
+
"Use Freeflow's adaptive Workflow for this task.",
|
|
34
|
+
"Respect the Interaction Contract and ask before going beyond the requested scope."
|
|
36
35
|
],
|
|
37
36
|
"websiteURL": "https://github.com/hassan-mohiddin/freeflow",
|
|
38
37
|
"privacyPolicyURL": "https://github.com/hassan-mohiddin/freeflow/blob/main/README.md",
|
package/README.md
CHANGED
|
@@ -2,135 +2,91 @@
|
|
|
2
2
|
|
|
3
3
|
**A feedback-based control system for coding agents.**
|
|
4
4
|
|
|
5
|
-
Freeflow helps coding agents
|
|
5
|
+
Freeflow helps coding agents do consequential work without turning every task into a rigid ceremony. It gives the agent a clear Interaction Contract, adaptive Workflow, focused methods, durable task memory, and controlled delivery boundaries.
|
|
6
6
|
|
|
7
|
-
|
|
8
|
-
>
|
|
9
|
-
> Re-enter the narrowest owning activity when evidence changes the path.
|
|
10
|
-
>
|
|
11
|
-
> Memory preserves context. It does not create authority.
|
|
12
|
-
|
|
13
|
-
The active agent still does the work. Freeflow supplies the interaction contract, workflow routing, focused methods, task memory, and evidence discipline that help it decide what to do next—and when not to edit.
|
|
7
|
+
The host agent still owns tools, permissions, and execution. Freeflow helps it choose the right next action—and know when to stop, ask, verify, or hand work back.
|
|
14
8
|
|
|
15
9
|
## Why Freeflow
|
|
16
10
|
|
|
17
|
-
Coding agents
|
|
11
|
+
Coding agents commonly fail at control boundaries:
|
|
18
12
|
|
|
19
|
-
|
|
|
13
|
+
| Pressure | Freeflow response |
|
|
20
14
|
| --- | --- |
|
|
21
15
|
| A question or tentative idea becomes an edit. | The Interaction Contract answers first and waits for clear action authority. |
|
|
22
|
-
| A prompt conflicts with tests, policy, or accepted behavior. | Decision Gate names the conflict
|
|
23
|
-
|
|
|
24
|
-
| Every task
|
|
25
|
-
| A passing command becomes an unsupported completion claim. | Verify Work matches
|
|
26
|
-
|
|
|
27
|
-
|
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
16
|
+
| A prompt conflicts with tests, policy, or accepted behavior. | Decision Gate names the conflict before mutation. |
|
|
17
|
+
| New evidence invalidates the plan. | Workflow routes from evidence and preserves unaffected work. |
|
|
18
|
+
| Every task receives unnecessary ceremony. | Workflow enters at the narrowest useful owner and scales pressure to risk. |
|
|
19
|
+
| A passing command becomes an unsupported completion claim. | Verify Work matches evidence to the exact claim and boundary. |
|
|
20
|
+
| Compaction loses task state. | Track Work restores a Working Record and reconciles it with live state. |
|
|
21
|
+
| Tool output consumes future context. | Context Virtualization can archive consumed evidence while preserving session history. |
|
|
22
|
+
|
|
23
|
+
## Contents
|
|
24
|
+
|
|
25
|
+
- [How it works](#how-it-works)
|
|
26
|
+
- [Host support](#host-support)
|
|
27
|
+
- [Capabilities](#capabilities)
|
|
28
|
+
- [Quick start](#quick-start)
|
|
29
|
+
- [Workflow](#workflow)
|
|
30
|
+
- [System prompt architecture](#system-prompt-architecture)
|
|
31
|
+
- [Evidence and limits](#evidence-and-limits)
|
|
32
|
+
- [Commands](#commands)
|
|
33
|
+
- [Documentation and development](#documentation-and-development)
|
|
34
|
+
- [What Freeflow is not](#what-freeflow-is-not)
|
|
35
|
+
|
|
36
|
+
## How it works
|
|
37
|
+
|
|
38
|
+
Freeflow uses one active agent, one shared context, and nested feedback loops:
|
|
37
39
|
|
|
38
40
|
```text
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
41
|
+
Interaction Lifecycle
|
|
42
|
+
└─ Workflow Feedback Loop
|
|
43
|
+
├─ establishes authority, owner, and slice
|
|
44
|
+
└─ Cognitive Execution Routes — automatic control only
|
|
45
|
+
├─ Reasoning chooses one route
|
|
46
|
+
│ ├─ YIELD → Standard leads ordinary work → YIELD HANDOFF → Reasoning
|
|
47
|
+
│ ├─ DELEGATE → open model-written boundary → Standard executes
|
|
48
|
+
│ │ └─ RETURN → Reasoning assesses; boundary remains open until CLOSE
|
|
49
|
+
│ └─ TASK ACT → Reasoning performs narrow direct OBSERVE or ACT_BOUNDED
|
|
50
|
+
└─ Action Selection guides uncertain environment interactions
|
|
44
51
|
```
|
|
45
52
|
|
|
46
|
-
|
|
53
|
+
Under automatic Cognitive Routing control, each new user interaction begins in Reasoning. Under manual control, the selected compute profile runs the ordinary unsplit Workflow. Cognitive Routing changes compute placement only. It never changes authority, ownership, task scope, evidence requirements, or review independence.
|
|
47
54
|
|
|
48
|
-
|
|
55
|
+
The Workflow owner may be Discuss, Track Work, Execute Work, Verify Work, Review Work, Review Artifact, Diagnose Failure, or another focused method. These methods compose when their conditions apply; they are not a mandatory phase pipeline.
|
|
49
56
|
|
|
50
|
-
|
|
51
|
-
orient to accepted intent, task memory, and live evidence
|
|
52
|
-
-> use the narrowest owning skill
|
|
53
|
-
-> implement, discuss, test, or observe
|
|
54
|
-
-> verify what the evidence proves
|
|
55
|
-
-> when supported, self-review once
|
|
56
|
-
-> continue, correct, diagnose, revise, ask, defer, or stop
|
|
57
|
-
```
|
|
58
|
-
|
|
59
|
-
A Supported Exit may answer, wait, pause, hand off, defer, stop, preserve a controlled boundary, or complete. Freeflow does not invent another phase merely because one exists in the full skill pack.
|
|
60
|
-
|
|
61
|
-
## Core Principles
|
|
57
|
+
## Host support
|
|
62
58
|
|
|
63
|
-
|
|
64
|
-
- **Verification is factual. Review is judgment.** The active agent verifies; self-review is silent; selected independent review uses a separate context.
|
|
65
|
-
- **Pass is not the only review exit.** Pass, Non-blocking, Inconclusive, and Blocking all end review and return evidence to Workflow.
|
|
66
|
-
- **Review findings do not authorize edits.** Ask for unapproved corrections and any warranted focused follow-up together.
|
|
67
|
-
- **Specs and Plans have separate jobs and separate reviews.** Working Records carry evolving state; Plans remain stable ordered strategy.
|
|
68
|
-
- **A slice may span several feedback iterations.** Extend its boundary write-ahead only while the intended result remains coherent.
|
|
69
|
-
- **Diagnose before redesigning.** Ordinary mistakes do not prove structural failure.
|
|
70
|
-
- **Bypass skips optional pressure, not authority, safety, evidence, or selected review.**
|
|
59
|
+
Freeflow is one package with different host boundaries:
|
|
71
60
|
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
Freeflow has exactly three modes:
|
|
75
|
-
|
|
76
|
-
| Mode | Use for | Guardrail |
|
|
61
|
+
| Host | Freeflow support | Cognitive Routing |
|
|
77
62
|
| --- | --- | --- |
|
|
78
|
-
|
|
|
79
|
-
|
|
|
80
|
-
|
|
|
81
|
-
|
|
82
|
-
Task type and direct skill calls do not silently switch mode.
|
|
63
|
+
| Codex | Shared skills and lifecycle hook | Not available; Pi/PiFlow capabilities are not delivered |
|
|
64
|
+
| Claude Code | Shared skills and lifecycle hook | Not available; Pi/PiFlow capabilities are not delivered |
|
|
65
|
+
| Pi | Shared skills, Pi extension, optional context capabilities, and native host controls | Available when configured and the official model-state APIs are present |
|
|
66
|
+
| PiFlow | Freeflow package hosted by the separate PiFlow distribution | Available when configured |
|
|
83
67
|
|
|
84
|
-
|
|
68
|
+
Freeflow owns workflow policy, prompt fragments, skills, capabilities, and the Pi extension. Each host owns its launch, package installation, session state, updates, and native model-state control; PiFlow remains a supported host integration.
|
|
85
69
|
|
|
86
|
-
|
|
70
|
+
## Capabilities
|
|
87
71
|
|
|
88
|
-
|
|
72
|
+
### Workflow and task memory
|
|
89
73
|
|
|
90
|
-
|
|
74
|
+
- **Workflow** coordinates authority, owner selection, evidence-driven re-entry, and Supported Exit.
|
|
75
|
+
- **Action Selection** bounds uncertain or broad Environment Interactions while preserving the current owner.
|
|
76
|
+
- **Track Work** maintains a Working Record when decisions, evidence, blockers, or the next action must survive context loss.
|
|
77
|
+
- **Verify Work, Review Work, Review Artifact, and Diagnose Failure** separate factual support, judgment, artifact fitness, and unsupported causes.
|
|
91
78
|
|
|
92
|
-
|
|
79
|
+
### Optional host capabilities
|
|
93
80
|
|
|
94
|
-
-
|
|
95
|
-
-
|
|
96
|
-
-
|
|
97
|
-
- task-local decisions and hypotheses;
|
|
98
|
-
- evidence pointers and completed history;
|
|
99
|
-
- one next useful action;
|
|
100
|
-
- optional inert Notes.
|
|
81
|
+
- **[Cognitive Routing](https://github.com/hassan-mohiddin/freeflow/blob/main/plugin-docs/capabilities/cognitive-routing.md)** places compute between Reasoning and Standard under automatic control in Pi and PiFlow. It remains experimental.
|
|
82
|
+
- **[Context Virtualization](https://github.com/hassan-mohiddin/freeflow/blob/main/plugin-docs/capabilities/context-virtualization.md)** classifies consumed tool evidence as Full, Retained, or Reference-only for future context while leaving canonical history unchanged.
|
|
83
|
+
- **[Conversation History](https://github.com/hassan-mohiddin/freeflow/blob/main/plugin-docs/capabilities/conversation-history.md)** performs bounded retrieval of exact missing prior-conversation evidence from the current active branch.
|
|
101
84
|
|
|
102
|
-
|
|
85
|
+
The three capabilities are individually gated and default-off or unavailable unless their configuration and host conditions are effective. None grants authority or replaces Workflow.
|
|
103
86
|
|
|
104
|
-
##
|
|
87
|
+
## Quick start
|
|
105
88
|
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
| Need | Use |
|
|
109
|
-
| --- | --- |
|
|
110
|
-
| Search repo, explicit local sources, or routed evidence | `freeflow_search` |
|
|
111
|
-
| Run noisy tests, builds, typechecks, logs, or diagnostics | `freeflow_run` |
|
|
112
|
-
| Run independent searches/checks and aggregate facts | `freeflow_batch` |
|
|
113
|
-
| Compute bounded subsets or statistics | `freeflow_search action=transform` |
|
|
114
|
-
| Inspect configuration, vault, routing, or adapters | `freeflow_status` |
|
|
115
|
-
| Read a known file or run a tiny exact command | Native host tools |
|
|
116
|
-
|
|
117
|
-
Output Router is disabled by default and available only through the Pi extension. Enable it explicitly through Pi's `/output-router` surface.
|
|
118
|
-
|
|
119
|
-
## Evidence, Not Marketing Certainty
|
|
120
|
-
|
|
121
|
-
Historical v0.1 workflow fixtures and current router benchmarks remain reproducible evidence, not universal guarantees. The current adaptive skill candidate is **Unverified** pending baseline-vs-with-skill behavioral evaluation.
|
|
122
|
-
|
|
123
|
-
| Evidence | Result |
|
|
124
|
-
| --- | --- |
|
|
125
|
-
| Historical v0.1 acceptance suite | 15/15 fixtures passed after measured fixes. |
|
|
126
|
-
| Historical source-truth conflict pressure | Baseline 2/10; with-skill 10/10. |
|
|
127
|
-
| Retrieval benchmark | 7/7 gated fixtures; 98.54% weighted context reduction. |
|
|
128
|
-
| Command-output benchmark | 8/8 fixtures with exact recovery; 85.03% weighted reduction. |
|
|
129
|
-
| Pi observed-routing eval | 28/28 objective gates; 82.2% overall byte reduction. |
|
|
130
|
-
|
|
131
|
-
See [release evidence](https://github.com/hassan-mohiddin/freeflow/blob/main/plugin-docs/release-evidence.md) for boundaries, reports, and deferred checks.
|
|
132
|
-
|
|
133
|
-
## Install
|
|
89
|
+
For complete host-specific setup, see [Getting Started](https://github.com/hassan-mohiddin/freeflow/blob/main/plugin-docs/getting-started.md).
|
|
134
90
|
|
|
135
91
|
### Codex
|
|
136
92
|
|
|
@@ -138,21 +94,18 @@ See [release evidence](https://github.com/hassan-mohiddin/freeflow/blob/main/plu
|
|
|
138
94
|
codex plugin marketplace add https://github.com/hassan-mohiddin/freeflow.git
|
|
139
95
|
codex plugin marketplace upgrade freeflow
|
|
140
96
|
codex plugin add freeflow@freeflow
|
|
141
|
-
codex plugin list | rg freeflow
|
|
142
97
|
```
|
|
143
98
|
|
|
144
|
-
Trust the Freeflow
|
|
99
|
+
Trust the Freeflow hook from `/hooks`, then start a new session.
|
|
145
100
|
|
|
146
101
|
### Claude Code
|
|
147
102
|
|
|
148
|
-
```
|
|
103
|
+
```text
|
|
149
104
|
/plugin marketplace add hassan-mohiddin/freeflow
|
|
150
105
|
/plugin install freeflow
|
|
151
106
|
/reload-plugins
|
|
152
107
|
```
|
|
153
108
|
|
|
154
|
-
Start a new session after first install when the current session predates the plugin.
|
|
155
|
-
|
|
156
109
|
### Pi
|
|
157
110
|
|
|
158
111
|
```bash
|
|
@@ -165,44 +118,74 @@ Or:
|
|
|
165
118
|
pi install git:github.com/hassan-mohiddin/freeflow
|
|
166
119
|
```
|
|
167
120
|
|
|
168
|
-
|
|
121
|
+
The full normal-Pi integration targets Pi 0.84.3 or newer; Pi 0.84.4 is the current Cognitive Routing test target.
|
|
122
|
+
|
|
123
|
+
### PiFlow
|
|
169
124
|
|
|
170
|
-
|
|
125
|
+
Install PiFlow separately, then install Freeflow into it:
|
|
126
|
+
|
|
127
|
+
```bash
|
|
128
|
+
npm install -g --ignore-scripts @hassangameryt/piflow
|
|
129
|
+
piflow install npm:@hassangameryt/freeflow
|
|
130
|
+
```
|
|
131
|
+
|
|
132
|
+
For a Git source:
|
|
133
|
+
|
|
134
|
+
```bash
|
|
135
|
+
piflow install git:github.com/hassan-mohiddin/freeflow
|
|
136
|
+
```
|
|
137
|
+
|
|
138
|
+
In the target repository, run:
|
|
171
139
|
|
|
172
140
|
```text
|
|
173
141
|
/setup-freeflow
|
|
174
142
|
```
|
|
175
143
|
|
|
176
|
-
|
|
144
|
+
Setup creates `.freeflow/config.json`, the required shared activation boundary. Minimal activation is `{}`. `.freeflow/local.json` is an optional personal override and cannot activate Freeflow by itself.
|
|
177
145
|
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
|
|
181
|
-
}
|
|
182
|
-
```
|
|
146
|
+
## Workflow
|
|
147
|
+
|
|
148
|
+
Freeflow always uses one adaptive Workflow. The Interaction Contract interprets the whole user turn; Workflow then chooses the narrowest owner and scales coordination to consequence, uncertainty, interaction, and reversibility.
|
|
183
149
|
|
|
184
|
-
|
|
150
|
+
A question or tentative idea remains discussion until clear action authority exists. A direct request covers only its bounded outcome and entailed effects. Risk-sensitive work receives stronger decisions, evidence, verification, and checkpoints through the same Workflow rather than through a separate selectable process.
|
|
151
|
+
|
|
152
|
+
Every bounded activity follows the same Feedback Loop:
|
|
185
153
|
|
|
186
154
|
```text
|
|
187
|
-
|
|
188
|
-
->
|
|
189
|
-
->
|
|
190
|
-
->
|
|
155
|
+
orient to accepted intent, task memory, and live evidence
|
|
156
|
+
-> use the narrowest owner
|
|
157
|
+
-> act, discuss, test, or observe
|
|
158
|
+
-> verify what the evidence proves
|
|
159
|
+
-> self-review the supported result
|
|
160
|
+
-> continue, correct, diagnose, revise, ask, defer, or stop
|
|
191
161
|
```
|
|
192
162
|
|
|
193
|
-
|
|
163
|
+
## System prompt architecture
|
|
164
|
+
|
|
165
|
+
Freeflow’s model-facing surface has four coordinated parts:
|
|
194
166
|
|
|
195
|
-
|
|
167
|
+
1. **Core guidance** in `runtime/prompts/core.md` contains identity, shared terms, loops, Workflow, Action Selection, and Supported Exit cues.
|
|
168
|
+
2. **Interaction Contract** in `runtime/prompts/interaction-contract.md` remains a separate mandatory fragment so its behavior can be revised independently.
|
|
169
|
+
3. **Runtime State** reports current capability availability and Cognitive Routing `Control`/`Profile` at session start, after context reconstruction or loss, and when displayed state changes; unchanged state remains in the current provider context.
|
|
170
|
+
4. **Discoverable skills and tools** provide the 25 base methods and individually gated optional capability operations.
|
|
196
171
|
|
|
197
|
-
|
|
172
|
+
The core guidance and Interaction Contract are always delivered together when Freeflow is enabled. Optional capability content is omitted and reported unavailable rather than fabricated. One effective-state snapshot determines prompt assembly, discovery, tools, and projection.
|
|
198
173
|
|
|
199
|
-
|
|
200
|
-
- one `skills/workflow/SKILL.md` bootstrap per context epoch while Skills are effective;
|
|
201
|
-
- compact active or dormant mode state.
|
|
174
|
+
Read the full [System Prompt Architecture](https://github.com/hassan-mohiddin/freeflow/blob/main/plugin-docs/prompt-architecture.md) and [Workflow](https://github.com/hassan-mohiddin/freeflow/blob/main/plugin-docs/workflow.md) docs for the complete contract.
|
|
202
175
|
|
|
203
|
-
|
|
176
|
+
## Evidence and limits
|
|
204
177
|
|
|
205
|
-
|
|
178
|
+
Freeflow is explicit about what its checks prove:
|
|
179
|
+
|
|
180
|
+
- deterministic checks prove structure, assembly, package boundaries, and selected delivery behavior;
|
|
181
|
+
- release evidence is versioned and records source, checks, artifacts, deferred evidence, and limits;
|
|
182
|
+
- local installation does not prove remote host installation or registry propagation;
|
|
183
|
+
- deterministic skill/runtime checks do not prove model behavior or universal skill readiness;
|
|
184
|
+
- Cognitive Routing remains experimental pending behavioral acceptance.
|
|
185
|
+
|
|
186
|
+
The deprecated Output Router is removed and no longer available. Its implementation and evidence remain archived under `.deprecated/output-router/`.
|
|
187
|
+
|
|
188
|
+
See [Release Process](https://github.com/hassan-mohiddin/freeflow/blob/main/plugin-docs/release.md) and [Release Evidence](https://github.com/hassan-mohiddin/freeflow/blob/main/plugin-docs/release-evidence/README.md).
|
|
206
189
|
|
|
207
190
|
## Commands
|
|
208
191
|
|
|
@@ -210,6 +193,7 @@ Natural language is preferred. Pi registers these canonical direct calls:
|
|
|
210
193
|
|
|
211
194
|
```text
|
|
212
195
|
/discuss
|
|
196
|
+
/action-selection
|
|
213
197
|
/track-work
|
|
214
198
|
/write-spec
|
|
215
199
|
/review-artifact
|
|
@@ -228,13 +212,6 @@ Natural language is preferred. Pi registers these canonical direct calls:
|
|
|
228
212
|
/bypass
|
|
229
213
|
```
|
|
230
214
|
|
|
231
|
-
Pi-only compatibility aliases:
|
|
232
|
-
|
|
233
|
-
```text
|
|
234
|
-
/discover
|
|
235
|
-
/execute-plan
|
|
236
|
-
```
|
|
237
|
-
|
|
238
215
|
Contributor calls:
|
|
239
216
|
|
|
240
217
|
```text
|
|
@@ -243,45 +220,46 @@ Contributor calls:
|
|
|
243
220
|
/evaluate-skill
|
|
244
221
|
```
|
|
245
222
|
|
|
246
|
-
|
|
247
|
-
|
|
248
|
-
```text
|
|
249
|
-
/freeflow mode conversation
|
|
250
|
-
/freeflow mode workflow
|
|
251
|
-
/freeflow mode strict-workflow
|
|
252
|
-
/freeflow mode reset
|
|
253
|
-
```
|
|
254
|
-
|
|
255
|
-
Pi-native settings controls:
|
|
223
|
+
Pi and PiFlow Cognitive Routing controls:
|
|
256
224
|
|
|
257
225
|
```text
|
|
258
226
|
/freeflow
|
|
259
|
-
/
|
|
227
|
+
/freeflow settings
|
|
228
|
+
/freeflow settings session
|
|
229
|
+
/freeflow settings repo
|
|
230
|
+
/freeflow profile standard
|
|
231
|
+
/freeflow profile reasoning
|
|
232
|
+
/freeflow profile auto
|
|
260
233
|
```
|
|
261
234
|
|
|
262
|
-
|
|
235
|
+
`/freeflow settings` edits personal overrides, `/freeflow settings session` manages temporary enablement and optional-context overrides, and `/freeflow settings repo` edits shared repository settings. Profile changes require an idle host with the required model-state APIs.
|
|
263
236
|
|
|
264
|
-
|
|
237
|
+
In Pi or PiFlow, while the host is idle:
|
|
265
238
|
|
|
266
|
-
|
|
239
|
+
- `Ctrl+Shift+R` cycles the manual standard/reasoning hold.
|
|
240
|
+
- `Ctrl+Shift+A` sets automatic control; from a manual hold, it releases the hold and moves to Reasoning when necessary. Repeating it while already automatic is idempotent.
|
|
267
241
|
|
|
268
|
-
##
|
|
242
|
+
## Documentation and development
|
|
269
243
|
|
|
270
|
-
- [
|
|
271
|
-
- [
|
|
272
|
-
- [Skill routing](https://github.com/hassan-mohiddin/freeflow/blob/main/plugin-docs/skill-routing.md)
|
|
244
|
+
- [Documentation hub](https://github.com/hassan-mohiddin/freeflow/blob/main/plugin-docs/README.md)
|
|
245
|
+
- [Getting Started](https://github.com/hassan-mohiddin/freeflow/blob/main/plugin-docs/getting-started.md)
|
|
273
246
|
- [Architecture](https://github.com/hassan-mohiddin/freeflow/blob/main/plugin-docs/architecture.md)
|
|
274
|
-
- [
|
|
275
|
-
- [
|
|
276
|
-
- [
|
|
247
|
+
- [System Prompt Architecture](https://github.com/hassan-mohiddin/freeflow/blob/main/plugin-docs/prompt-architecture.md)
|
|
248
|
+
- [Capabilities](https://github.com/hassan-mohiddin/freeflow/blob/main/plugin-docs/capabilities/README.md)
|
|
249
|
+
- [PiFlow integration](https://github.com/hassan-mohiddin/freeflow/blob/main/plugin-docs/integrations/piflow.md)
|
|
250
|
+
- [Skill routing](https://github.com/hassan-mohiddin/freeflow/blob/main/plugin-docs/skill-routing.md)
|
|
251
|
+
- [Release Process](https://github.com/hassan-mohiddin/freeflow/blob/main/plugin-docs/release.md)
|
|
252
|
+
- [Changelog](CHANGELOG.md)
|
|
253
|
+
- [Contributing](CONTRIBUTING.md)
|
|
254
|
+
|
|
255
|
+
For local development, use committed Freeflow snapshots with `npm run snapshot:refresh`. Do not treat an uncommitted working tree as a production package source. PiFlow owns the host development launcher and state synchronization.
|
|
277
256
|
|
|
278
|
-
## What Freeflow
|
|
257
|
+
## What Freeflow is not
|
|
279
258
|
|
|
280
|
-
- Not a new agent.
|
|
281
|
-
- Not a
|
|
282
|
-
- Not a CLI enforcement framework.
|
|
259
|
+
- Not a new agent or workflow engine.
|
|
260
|
+
- Not a rigid phase pipeline.
|
|
261
|
+
- Not a permission or CLI enforcement framework.
|
|
283
262
|
- Not a replacement for repository instructions, tests, policies, or review culture.
|
|
284
|
-
- Not old Orchestra with a smaller README.
|
|
285
263
|
- Not proof that the current candidate is behaviorally ready.
|
|
286
264
|
|
|
287
265
|
## License
|