Skip to content

Commit 4d01939

Browse files
faical-yannick-congoclaude
faical-yannick-congo
and
claude
committed
feat: make Fluently framework-agnostic with pluggable dimension schemas
- Add `frameworks/` directory with `4d-framework.yaml` and `index.json` - Add `framework-schema.ts` with `frameworkDefinitionSchema`, `buildKnowledgeSchemas()` factory, and `BUNDLED_4D_FRAMEWORK` constant - Knowledge entries now carry `framework_id`; all 16 existing entries updated - `buildKnowledgeSchemas()` memoises Zod schemas per framework; dimension keys are dynamic (validated against the framework's declared dimensions) - Fix TypeScript circular-type bug in schema cache by exporting `DimensionValue` type and using explicit casts in engine.ts - Add `validate-frameworks.js` and `generate-framework-index.js` scripts - Update `validate-knowledge.js` to be framework-aware - MCP server: add `list_frameworks`, `get_framework_detail`, `compare_frameworks` tools - CLI: add `--framework` filter to `list` command; framework selection in `contribute` - CI: add `frameworks/**` and `scripts/**` to trigger paths; add framework validation step - Site: new `frameworks.html` page; `knowledge.html` updated with framework filter - Docs: CONTRIBUTING.md, KNOWLEDGE.md, CLAUDE.md updated with framework guidance Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
1 parent 77e5c23 commit 4d01939

43 files changed

Lines changed: 1767 additions & 204 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.github/workflows/ci.yml‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,8 @@ on:
66
paths:
77
- 'packages/**'
88
- 'knowledge/**'
9+
- 'frameworks/**'
10+
- 'scripts/**'
911
- '.github/workflows/ci.yml'
1012
- 'package.json'
1113
- 'tsconfig.base.json'
@@ -14,6 +16,8 @@ on:
1416
paths:
1517
- 'packages/**'
1618
- 'knowledge/**'
19+
- 'frameworks/**'
20+
- 'scripts/**'
1721
- '.github/workflows/ci.yml'
1822
- 'package.json'
1923
- 'tsconfig.base.json'
@@ -48,6 +52,10 @@ jobs:
4852
- name: Build packages
4953
run: npm run build
5054

55+
- name: Validate framework definitions
56+
run: node scripts/validate-frameworks.js
57+
continue-on-error: false
58+
5159
- name: Validate knowledge schema
5260
run: node scripts/validate-knowledge.js
5361
continue-on-error: false

‎CLAUDE.md‎

Lines changed: 18 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,19 +1,29 @@
11
PROJECT: fluently
2-
PURPOSE: An open-source CLI + MCP server + knowledge base that operationalizes the AI Fluency 4D Framework (Delegation, Description, Discernment, Diligence) by Dakan & Feller. Licensed MIT. Works with any AI agent — Claude, GPT, Gemini, Mistral, Copilot, and more.
2+
PURPOSE: An open-source CLI + MCP server + knowledge base that operationalizes collaboration frameworks (starting with the AI Fluency 4D Framework by Dakan & Feller). Licensed MIT. Works with any AI agent — Claude, GPT, Gemini, Mistral, Copilot, and more. Framework-agnostic: any collaboration framework with named dimensions can be registered.
33

44
ARCHITECTURE:
5-
- /knowledge/ — YAML Fluently 4D cycles, community-contributed, organized by dimension and domain
5+
- /frameworks/ — YAML framework definitions (id, name, dimensions, canonical order); index.json auto-generated by CI
6+
- /knowledge/ — YAML knowledge cycles, community-contributed, organized by domain; each cycle carries a framework_id
67
- /packages/cli/ — Node.js CLI (`fluent` command) using commander.js; multi-provider AI support
7-
- /packages/mcp-server/ — MCP server exposing knowledge as AI-callable tools (any MCP-compatible agent)
8-
- /packages/scorer/ — Shared scoring + schema validation engine used by both CLI and MCP server
9-
- /site/ — GitHub Pages static site (plain HTML + Tailwind CDN + vanilla JS)
8+
- /packages/mcp-server/ — MCP server exposing knowledge and frameworks as AI-callable tools (any MCP-compatible agent)
9+
- /packages/scorer/ — Shared scoring + schema validation engine; builds Zod schemas per framework dynamically
10+
- /site/ — GitHub Pages static site (plain HTML + Tailwind CDN + vanilla JS); includes frameworks.html
1011

1112
RULES:
1213
- Never hardcode API keys
13-
- All knowledge entries must have all 4D fields present
14-
- Schema validation runs before any PR merges
14+
- All knowledge entries must have all dimension fields present (dimension keys defined by their framework)
15+
- framework_id is required on all new knowledge YAML files; existing 4D entries default to "4d-framework"
16+
- Schema validation runs before any PR merges — both frameworks/ and knowledge/ are validated
1517
- Test files live alongside source in __tests__ folders
16-
- Knowledge YAML must pass Zod schema before being accepted
18+
- Knowledge YAML must pass Zod schema (built dynamically per framework) before being accepted
1719
- Use ESM imports throughout (no require()); mixed require/import is a bug
20+
- All site HTML changes must be responsive (no horizontal scroll)
21+
22+
FRAMEWORK RULES:
23+
- Framework ids must be kebab-case
24+
- Dimension keys within a framework must be unique
25+
- canonical_order must be a positive integer and determines scoring and rendering order
26+
- buildKnowledgeSchemas(framework) is memoised — call it once per framework id
27+
- BUNDLED_4D_FRAMEWORK in scorer is the source of truth for the 4D schema; frameworks/4d-framework.yaml is its YAML representation
1828

1929
STACK: TypeScript, Node.js 20+, Zod, commander.js, Anthropic SDK (claude-sonnet-4-6), Vitest, GitHub Actions

‎CONTRIBUTING.md‎

Lines changed: 70 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,83 @@
11
# Contributing to Fluently
22

3-
Thank you for your interest in contributing to Fluently! This document explains how to submit new Fluently 4D cycles and contribute to the codebase.
3+
Thank you for your interest in contributing to Fluently! This document explains how to submit new Fluently 4D cycles, contribute new frameworks, and contribute to the codebase.
44

55
## Table of Contents
66

77
- [Adding a New Fluently 4D Cycle](#adding-a-new-fluently-4d-cycle)
8+
- [Contributing a New Framework](#contributing-a-new-framework)
89
- [Submitting a Pull Request](#submitting-a-pull-request)
910
- [Schema Requirements](#schema-requirements)
1011
- [Code Contributions](#code-contributions)
1112

13+
## Contributing a New Framework
14+
15+
Fluently is framework-agnostic. You can register any collaboration framework that structures human-AI tasks into named dimensions.
16+
17+
### Framework YAML schema
18+
19+
Create `frameworks/{your-framework-id}.yaml`:
20+
21+
```yaml
22+
id: my-framework # kebab-case, unique
23+
name: My Collaboration Framework
24+
version: 1.0.0
25+
contributor: Your Name
26+
description: >
27+
One-paragraph description of what the framework is and what problem it solves.
28+
dimensions:
29+
- key: plan # kebab-case dimension key
30+
label: Plan
31+
description: What planning looks like in this framework.
32+
canonical_order: 1 # determines rendering/scoring order (must be unique positive int)
33+
- key: execute
34+
label: Execute
35+
description: How execution is handled.
36+
canonical_order: 2
37+
- key: review
38+
label: Review
39+
description: How outputs are reviewed.
40+
canonical_order: 3
41+
tags:
42+
- optional-tag
43+
reference: https://your-framework-reference.example # optional
44+
```
45+
46+
### CI validation
47+
48+
Every `frameworks/*.yaml` file is validated by `scripts/validate-frameworks.js` against `frameworkDefinitionSchema`. The CI step also regenerates `frameworks/index.json`.
49+
50+
### Adding knowledge cycles for your framework
51+
52+
Once your framework YAML is merged, knowledge cycles can reference it:
53+
54+
```yaml
55+
id: my-cycle
56+
framework_id: my-framework # must match your framework's id
57+
title: My Cycle Title
58+
domain: coding
59+
dimensions:
60+
plan:
61+
description: ...
62+
example: ...
63+
antipattern: ...
64+
execute:
65+
description: ...
66+
example: ...
67+
antipattern: ...
68+
review:
69+
description: ...
70+
example: ...
71+
antipattern: ...
72+
score_hints:
73+
plan: 0.34
74+
execute: 0.33
75+
review: 0.33
76+
# ... collaboration block required
77+
```
78+
79+
Dimension keys in `dimensions` and `score_hints` must exactly match your framework's dimension keys. The Zod schema is built dynamically per framework, so a typo will fail CI validation.
80+
1281
## Adding a New Fluently 4D Cycle
1382

1483
The easiest way to contribute is by adding a new **Fluently 4D cycle** — a structured knowledge entry that teaches the AI Fluency Framework dimensions: Delegation, Description, Discernment, and Diligence.

‎KNOWLEDGE.md‎

Lines changed: 47 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -152,12 +152,57 @@ The auto-generated `index.json` contains every field needed for search and rende
152152
| Field | Type | Description |
153153
|---|---|---|
154154
| `id` | string | Kebab-case unique slug |
155+
| `framework_id` | string | Framework this entry belongs to (default: `4d-framework`) |
155156
| `title` | string | Human-readable name |
156157
| `domain` | string | One of the supported domains |
157158
| `tags` | string[] | Search/filter tags |
158159
| `contributor` | string | Author name |
159160
| `version` | string | Semver |
160161
| `summary` | string | One-sentence description |
161162
| `file` | string | Filename in knowledge/ |
162-
| `dimensions` | object | All 4 dimensions with description, example, antipattern |
163-
| `score_hints` | object | Relative weights per dimension (sum to 1.0) |
163+
| `dimensions` | object | All dimensions with description, example, antipattern — keys match the framework's dimension keys |
164+
| `score_hints` | object | Relative weights per dimension key (sum to 1.0) |
165+
166+
## Frameworks
167+
168+
Fluently is framework-agnostic. The `frameworks/` directory contains YAML definitions for each supported collaboration framework:
169+
170+
```
171+
frameworks/
172+
├── index.json ← pre-built index of all frameworks (fetch this first)
173+
└── 4d-framework.yaml ← the bundled AI Fluency 4D Framework
174+
```
175+
176+
Each framework defines:
177+
- `id` — kebab-case unique identifier (e.g. `4d-framework`)
178+
- `name` — human-readable name
179+
- `version` — semver
180+
- `contributor` — author
181+
- `dimensions` — list of dimension objects with `key`, `label`, `description`, and `canonical_order`
182+
- `tags` — optional search tags
183+
- `reference` — optional URL
184+
185+
Knowledge cycles belong to a framework via `framework_id`. Validation uses the framework's dimension keys — so a 4D entry must have `delegation`, `description`, `discernment`, and `diligence`, but a different framework's entry must match that framework's own keys.
186+
187+
### Frameworks index URL
188+
189+
```
190+
https://raw.githubusercontent.com/Fluently-Org/fluently/main/frameworks/index.json
191+
```
192+
193+
### Contributing a new framework
194+
195+
Three paths:
196+
197+
**1. Manual PR**
198+
- Create `frameworks/{id}.yaml` following the schema
199+
- CI will validate with `scripts/validate-frameworks.js` and regenerate `index.json`
200+
- Add knowledge cycles with `framework_id: your-framework-id`
201+
202+
**2. Via GitHub MCP (agents)**
203+
- Use the Fluently MCP server's `contribute_cycle` tool with `framework_id` set
204+
- Use `list_frameworks` and `get_framework_detail` to discover existing frameworks
205+
206+
**3. Private MCP**
207+
- Fork the repo and add your framework YAML privately
208+
- Configure `FLUENTLY_GITHUB_REPO` to point to your fork

‎frameworks/4d-framework.yaml‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
id: 4d-framework
2+
name: AI Fluency 4D Framework
3+
version: 1.0.0
4+
contributor: Dakan & Feller
5+
description: >
6+
Four dimensions of good human-AI collaboration. Originally described
7+
in the AI Fluency book by Dakan and Feller, this framework structures
8+
every AI-assisted task across Delegation, Description, Discernment,
9+
and Diligence.
10+
dimensions:
11+
- key: delegation
12+
label: Delegation
13+
description: Who owns the decision — human, AI, or both? What level of autonomy is appropriate?
14+
canonical_order: 1
15+
- key: description
16+
label: Description
17+
description: How should the task be framed so AI understands context fully?
18+
canonical_order: 2
19+
- key: discernment
20+
label: Discernment
21+
description: How do you evaluate whether the AI output is trustworthy? When do you push back?
22+
canonical_order: 3
23+
- key: diligence
24+
label: Diligence
25+
description: What human accountability is required after AI is involved? Who signs off?
26+
canonical_order: 4
27+
tags:
28+
- human-ai-collaboration
29+
- ai-fluency
30+
- 4d
31+
reference: https://fluently.ctrl6.com

‎frameworks/index.json‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
{
2+
"generated": "2026-03-23T00:00:00.000Z",
3+
"total": 1,
4+
"frameworks": [
5+
{
6+
"id": "4d-framework",
7+
"name": "AI Fluency 4D Framework",
8+
"version": "1.0.0",
9+
"contributor": "Dakan & Feller",
10+
"description": "Four dimensions of good human-AI collaboration. Originally described in the AI Fluency book by Dakan and Feller, this framework structures every AI-assisted task across Delegation, Description, Discernment, and Diligence.",
11+
"dimensions": [
12+
{ "key": "delegation", "label": "Delegation", "description": "Who owns the decision — human, AI, or both? What level of autonomy is appropriate?", "canonical_order": 1 },
13+
{ "key": "description", "label": "Description", "description": "How should the task be framed so AI understands context fully?", "canonical_order": 2 },
14+
{ "key": "discernment", "label": "Discernment", "description": "How do you evaluate whether the AI output is trustworthy? When do you push back?", "canonical_order": 3 },
15+
{ "key": "diligence", "label": "Diligence", "description": "What human accountability is required after AI is involved? Who signs off?", "canonical_order": 4 }
16+
],
17+
"tags": ["human-ai-collaboration", "ai-fluency", "4d"],
18+
"reference": "https://fluently.ctrl6.com"
19+
}
20+
]
21+
}

‎knowledge/coding-bug-fix-prioritization.yaml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,5 @@
11
id: bug-fix-prioritization
2+
framework_id: 4d-framework
23
version: 1.0.0
34
contributor: Dakan & Feller
45
title: Bug Fix Prioritization

‎knowledge/coding-code-review-triage.yaml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,5 @@
11
id: code-review-triage
2+
framework_id: 4d-framework
23
version: 1.0.0
34
contributor: Dakan & Feller
45
title: Code Review Triage

‎knowledge/coding-refactoring-suggestions.yaml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,5 @@
11
id: refactoring-suggestions
2+
framework_id: 4d-framework
23
version: 1.0.0
34
contributor: Dakan & Feller
45
title: Refactoring Suggestions

‎knowledge/coding-test-case-generation.yaml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,5 @@
11
id: test-case-generation
2+
framework_id: 4d-framework
23
version: 1.0.0
34
contributor: Dakan & Feller
45
title: Test Case Generation

0 commit comments

Comments
 (0)