AI Fluency 4D Framework

Work better with AI.
Every time.

Fluently operationalizes the 4D Framework — Delegation, Description, Discernment, Diligence — so every human-AI collaboration is intentional, accountable, and reproducible. Built on community knowledge, powered by GitHub MCP.

Try it live Get started

Community cycles

Domains

Dimensions per cycle

Installs required

Claude + GitHub MCP — live knowledge

# Claude reads KNOWLEDGE.md via GitHub MCP Claude › Read KNOWLEDGE.md in Fluently-Org/fluently → 16 cycles · 7 domains · always live from main branch # Find cycles that match the task Claude › Read knowledge/index.json — which cycles fit "AI reviews PRs for style"? Best fit: Code Review Triage Delegation → augmented (human approves before merge) Discernment → compare output vs senior review standard ⚠ Antipattern: auto-merge without human sign-off # Read full YAML for detailed guidance Claude › Read knowledge/coding-code-review-triage.yaml ✓ Full 4D cycle loaded — delegation, description, discernment, diligence

The Framework

Four dimensions of great human-AI collaboration

Every Fluently cycle answers the same four questions. Together they eliminate the most common failure modes in AI-assisted work.

🎯

D1 · Delegation

Who owns the decision?

"Who should own this — human, AI, or both?"

Define the autonomy level before the task starts. Automated, augmented, or supervised. Ambiguity here creates accountability gaps.

📝

D2 · Description

Is the context complete?

"What does the AI need to understand the task fully?"

Framing determines output quality. A good description includes role, constraints, examples, and expected format — not just the ask.

🔍

D3 · Discernment

How do you evaluate trust?

"How do you know when the output is good enough?"

Define what good looks like before reviewing. Without explicit criteria, humans default to accepting fluent-sounding output regardless of accuracy.

✅

D4 · Diligence

Who stays accountable?

"What human sign-off is required after AI involvement?"

Accountability doesn't transfer to AI. Diligence names the human who owns the outcome — and the minimum verification step before shipping.

How Cycles Work

The 4Ds are conversation clusters — not tags

Every human-AI collaboration is a chain of prompts. Fluently classifies those prompt chains into four kinds of clusters — Delegation, Description, Discernment, and Diligence — and defines how they connect, loop, and restart into a repeatable cycle.

One cluster = a chain of related prompts

DEL · Delegation cluster

Human"Can you auto-approve style issues and flag logic ones?"

AI"I can flag logic issues with confidence — want me to auto-close only style nits?"

Human"Yes — auto-close style, surface everything else with a severity label."

↳ Trigger: autonomy boundaries agreed → moves to Description

DES · Description cluster

Human"Here's the PR diff, our style guide, and the three issues this PR addresses."

AI"Should I cross-reference open issues when flagging findings?"

Human"Yes — link any finding to the relevant issue if there's a match."

↳ Trigger: AI has enough context → moves to Discernment

Cycles define how the clusters connect

LINEAR email writing, lesson planning, clinical docs

Del → Des → Dis → Dil · Single pass, no loops · Safety-critical workflows

LINEAR WITH LOOPS code review, bug triage, marketing copy

Del → Des → Dis → Dil · Loop-back from Dis to Del when quality fails

ITERATIVE refactoring, literature review, content dev

Full cycle repeats multiple times · Each pass builds on the last · Scope narrows

CYCLIC creative collaboration, continuous processes

Dil loops back to Del · Continuous · Direction can reset at any Dil checkpoint

Code Review Triage — linear_with_loops · 4 D-clusters · 1 conditional loop-back

DEL

Negotiate AI scope

Human and AI agree on autonomy boundaries and severity thresholds

DES

Provide context

PR diff, style guide, and linked issues shared with AI

DIS

Evaluate findings

Human validates which AI flags are real vs false positives

↩ loop back to DEL if >30% false positives

DIL

Approve & document

Senior engineer signs off, decisions logged in PR comments

↻ restart for next PR

Community cycles by collaboration pattern

LINEAR

Email Writing · Lesson Planning
Clinical Documentation · Legal Drafting
Single pass · No loops · Strict accountability

LINEAR WITH LOOPS

Code Review · Bug Triage
Test Generation · Course Design
Data Analysis · Marketing Copy
Loop when quality fails · Scope renegotiation

ITERATIVE

Refactoring · Literature Review
Content Development · Iterative Refinement
Multiple full passes · Each builds on last

CYCLIC

Creative AI Collaboration
Continuous · Direction resets at any checkpoint

Each cycle in the knowledge base includes its full collaboration block — ordered D-clusters with example prompts, transition triggers, and loop-back conditions. Use get_collaboration_pattern via the MCP server to retrieve this for any cycle.

Architecture

Two paths to the knowledge base

Community knowledge flows through GitHub MCP — no server, always current. Private or isolated knowledge uses the custom MCP server with any connector.

Path A — Community (default)

GitHub MCP reads the knowledge base directly

The Fluently knowledge base lives in a public GitHub repo. Any AI agent with the GitHub MCP server wired can read KNOWLEDGE.md, fetch knowledge/index.json, and deep-read individual YAML cycles — no custom server, no rebuild, no auth required for reads.

Knowledge updates the moment a community cycle is merged. Contributions open a PR automatically via the same GitHub MCP.

✓ Zero install ✓ Always current ✓ Community contributions

AI Agent — settings.json

// Wire GitHub MCP — no auth needed for reads "mcpServers": { "github": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-github"], "env": { "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_xxx" } } } // Then prompt your agent: Read KNOWLEDGE.md in Fluently-Org/fluently Find cycles for "AI draft + human review" workflow

Path B — Private / Isolated

Custom MCP server with pluggable connectors

When you need private knowledge — a team's proprietary patterns, a fork with domain-specific cycles, or an air-gapped environment — the custom Fluently MCP server connects to any backend: a private GitHub repo, a local directory, SQL, or NoSQL. Five connectors, one interface.

Six tools are exposed: discover, retrieve, deep-read, inspect dimensions, force-refresh, and contribute. No numeric scores — the agent reasons over ranked candidates contextually.

✓ Private knowledge ✓ 5 connectors ✓ Offline fallback

fluently-mcp-server — connectors

# Community (default — no config) $ fluently-mcp-server # Private GitHub repo FLUENTLY_CONNECTOR=github-private FLUENTLY_GITHUB_REPO=your-org/knowledge FLUENTLY_GITHUB_TOKEN=ghp_xxx $ fluently-mcp-server # Local / offline FLUENTLY_CONNECTOR=local FLUENTLY_LOCAL_PATH=./my-knowledge $ fluently-mcp-server

Features

Everything in one knowledge base

🔄

Live Knowledge

Always current — no rebuilds

The GitHub MCP connector fetches directly from raw.githubusercontent.com on every request. The custom MCP server adds a 1-hour TTL cache with bundled offline fallback. New cycles appear the moment a PR is merged — without restarting anything.

🤖

Agent in the Loop

No biased scoring

Numeric scores encode assumptions about platform maturity and user skill. Instead, the server returns ranked keyword-similarity candidates and lets the agent reason contextually over fit — adapting to your specific context.

🏗️

Private Knowledge

Your org's own patterns

Fork the repo, add proprietary cycles, point the server at your private repo. Your team's hard-won AI collaboration patterns stay internal and compound over time.

📤

Contribute

One command to PR

Validate a new cycle via Zod schema and the contribute_cycle tool handles the rest — returns a PR URL for public knowledge, writes a file for local, or opens a branch automatically for private repos.

🛡️

Schema Validation

Zod-validated entries

Every cycle must pass the shared Zod schema before being accepted — all 4 dimensions, examples, antipatterns, score hints. CI enforces this on every PR.

📦

CLI

Terminal-first workflow

The fluent CLI scores tasks, compares cycles, lists the knowledge base, and guides you through contributing a new cycle interactively. Works offline with bundled knowledge.

Live Demo

Try it in your browser

Choose your AI provider, describe a task, and watch Fluently fetch live knowledge from GitHub and reason over cycles — exactly what the GitHub MCP path does, running right here.

AI Connection

No AI connected Connect →

Your API key is stored only in your browser's localStorage and never sent anywhere except your chosen provider's API.

Your Task

Task description

Domain (optional)

What's happening

① Fetch knowledge/index.json from GitHub (public, no auth)

② Keyword-match your task to the top 3 cycles

③ Fetch full YAML for each candidate from GitHub

④ Your AI agent reasons over the cycles and tells you which fits best — and why

Agent output

GitHub MCP AI

⚡

Connect an AI provider (GPT, Gemini, Mistral…),
describe your AI task, and click Run.

Fetches live knowledge from GitHub
and streams AI reasoning back here.

Get Started

Three ways to use Fluently

Browser, CLI, or MCP server — pick the path that fits your workflow.

🌐 Browser

Run in this page

Zero install. Connect any AI provider above, describe your task, and the demo runs the full GitHub MCP + AI reasoning flow right here.

Go to demo

⚡ npx

CLI — no global install

Run the Fluently CLI without touching your PATH. Works anywhere Node.js 20+ is available. Scores and compares cycles from the terminal.

          npx fluently-cli score "your task here"
          ⎘
        

          npx fluently-cli list coding
          ⎘
        

📦 Global install

CLI — always available

Install once to run fluent from anywhere. Includes all commands: score, compare, list, contribute, sync.

          npm install -g fluently-cli
          ⎘
        

          fluent score "AI reviews PRs for style issues"
          ⎘
        

MCP Setup

Wire it to your AI assistant

Works with any MCP-compatible client.

claude_desktop_config.json (Claude Desktop)

{ "mcpServers": { "github": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-github"], "env": { "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_xxx" } } } }

~/.claude/settings.json (Claude Code)

{ "mcpServers": { "github": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-github"], "env": { "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_xxx" } } } }

Then prompt your agent: "Read KNOWLEDGE.md in Fluently-Org/fluently and find the best cycle for my task."

Install the server

# Install globally npm install -g fluently-mcp-server # MCP agent config { "mcpServers": { "fluently": { "command": "fluently-mcp-server" } } }

Private knowledge connector

{ "mcpServers": { "fluently": { "command": "fluently-mcp-server", "env": { "FLUENTLY_CONNECTOR": "github-private", "FLUENTLY_GITHUB_REPO": "your-org/knowledge", "FLUENTLY_GITHUB_TOKEN": "ghp_xxx" } } } }

Work better with AI. Every time.