Skip to content

CLAUDE.md

Latest commit

 

History

History
29 lines (25 loc) · 2.15 KB

CLAUDE.md

File metadata and controls

29 lines (25 loc) · 2.15 KB
Raw

PROJECT: fluently 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.

ARCHITECTURE:

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

RULES:

  • Never hardcode API keys
  • All knowledge entries must have all dimension fields present (dimension keys defined by their framework)
  • framework_id is required on all new knowledge YAML files; existing 4D entries default to "4d-framework"
  • Schema validation runs before any PR merges — both frameworks/ and knowledge/ are validated
  • Test files live alongside source in tests folders
  • Knowledge YAML must pass Zod schema (built dynamically per framework) before being accepted
  • Use ESM imports throughout (no require()); mixed require/import is a bug
  • All site HTML changes must be responsive (no horizontal scroll)

FRAMEWORK RULES:

  • Framework ids must be kebab-case
  • Dimension keys within a framework must be unique
  • canonical_order must be a positive integer and determines scoring and rendering order
  • buildKnowledgeSchemas(framework) is memoised — call it once per framework id
  • BUNDLED_4D_FRAMEWORK in scorer is the source of truth for the 4D schema; frameworks/4d-framework.yaml is its YAML representation

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