FrameworkIA — AI Framework for Programmers

A framework for working with AI coding assistants (Claude Code, OpenCode, Codex, Cursor, etc.) that combines a Spec-Driven Development methodology, persistent memory, reusable skills, a CLI, and an MCP server. The Python package is definitive-ai-framework, installed as the df command. The goal is for the AI to produce not just working code, but code shaped by context-aware reasoning rather than mechanical checklists.

Philosophy

Most "AI configs" for coding are prescriptive: universal checklists the AI applies mechanically, which tends to produce generic feedback and solutions that don't fit the actual project. This framework is contextual instead: its rules are written as reasoning guides that teach the AI to analyze the project before applying them — reflections on how to think about quality, efficiency, security, testing, and documentation, rather than "always do X" lists.

The AI is expected to: read the project's real context, work out which parts of each rule actually apply, reason about trade-offs before recommending anything, explain the why, keep the project's memory file up to date, and evaluate new AI-coding techniques with evidence before adopting them.

Related MCP server: CodeGraph

What's implemented

The df package is a working Python CLI + MCP server, not just documentation:

• MCP server (df/mcp/server.py) — a hand-rolled JSON-RPC 2.0/stdio server exposing 15 tools to any MCP-compatible client: memory_search, memory_store, memory_recent, memory_reindex, memory_consolidate, project_profile, context_build, pattern_lookup, test_generator, arch_review, self_improve, research_radar, workflow_recommend, plan_decompose, clear_memory.

• Persistent memory (df/memory/) — SQLite with FTS5 full-text search, optionally augmented with vector embeddings (sentence-transformers/all-MiniLM-L6-v2) for hybrid search, plus a consolidation step that decays stale entries and merges duplicates.

• Project detection (df/project/) — infers language, linter, and test framework from pyproject.toml/package.json/Cargo.toml/etc., and generates a project-specific AGENTS.md.

• Research radar — a curated table rating AI-coding techniques (verifier loops, explore-plan-build, repo maps, model routing, tree search, etc.) as adopt / experiment / watch / reject, used to push back on hype.

• Workflow recommender (df/evaluation/workflow.py) — rule-based guidance on direct-build vs. plan-then-build vs. orchestrator strategies and reasoning-effort level, plus a local JSONL benchmark log to check those heuristics against real outcomes.

• Plan decomposer (df/orchestrator/decomposer.py) — validates a task DAG and computes parallel execution groups.

• Skills (df/skills/) — pluggable code-generation, architecture review, doc-generation, and test-generation skills.

An earlier, more ambitious design ("Vision B": a fully autonomous Planner→Writer→Tester→Reviewer→Security→Optimizer pipeline calling LLM APIs directly) is documented in definitive-ai-framework-plan.md but not implemented — only the current, human-in-the-loop MCP-tool design ("Vision A") is built.

Structure

FrameworkIA/
├── AI.md                              # Entry point for the AI assistant
├── definitive-ai-framework-plan.md    # Longer-term technical plan (Vision A/B)
├── opencode.jsonc                     # MCP config for OpenCode
├── pyproject.toml                     # Python package + `df` CLI entry point
├── df/                                # Framework implementation
│   ├── cli/                           # `df` CLI commands
│   ├── mcp/                           # MCP server
│   ├── memory/                        # Persistent memory (SQLite + FTS5 + embeddings)
│   ├── project/                       # Stack/project detection
│   ├── quality/                       # Quality pattern catalog
│   └── skills/                        # Reusable skills
├── .framework/
│   ├── shared/                        # AGENTS.md and shared context
│   ├── skills/                        # Generated, project-specific skills
│   └── local/                         # Local memory DB (gitignored)
└── .sdd/
    ├── context/                       # Project context and living memory
    ├── rules/                         # Philosophical, universal rules
    ├── specs/                         # Per-feature specs
    └── docs/                          # Living documentation

Setup

1. Open FrameworkIA as the assistant's root folder.

2. Edit .sdd/context/context_of_project.txt with a description of your project.

3. Install the package if you want the CLI: pip install -e . (optionally pip install -e ".[embeddings]" for semantic memory search).

4. Open OpenCode from this root so it picks up opencode.jsonc and the df.mcp.server MCP server. opencode.jsonc currently hardcodes a local Python interpreter path — edit it to match your machine before using it.

5. Read AI.md at the start of a session — it points the agent to context, rules, memory, and workflow.

Diagnose the MCP integration:

python -m df.cli.main doctor

should report MCP handshake ok and list the available tools.

Get a workflow recommendation:

python -m df.cli.main workflow recommend --task-type feature --files 3 --risk medium --uncertainty high --verifier tests

Log a local result and see the report:

python -m df.cli.main workflow record --case-id task-001 --variant explore_plan_build --success --quality 4 --verifier-passed
python -m df.cli.main workflow report

Other commands: df init [path] (bootstrap .framework/ for a target project), df mcp (start the MCP server directly), df status, df improve --level 1|2|3|4 [--apply], df session --task "..." (currently a stub).

Session flow

1. You start a conversation.

2. The AI reads context_of_project.txt and memories.md.

3. Before significant changes, it consults the relevant rules.

4. It proposes a plan with reasoning; you approve, adjust, or reject.

5. It implements.

6. At the end of a module: a quality gate re-checks the change against the rules and reports what's solid, what's debt, and what's a problem.

7. memories.md is updated with what was learned.

The rules

Each .sdd/rules/*.md file follows the same structure: philosophy, when to apply it, how to analyze the project against it, universal red flags, common trade-offs, how to give useful (non-generic) feedback, and what to record in memories.md.

• stack.md — choosing technology that fits the project, not what's trendy, with explicit trade-offs.

• diagram.md — when a diagram is worth it and which kind (Mermaid by default, simple over exhaustive).

• quality_code.md — structural quality as contextual judgment, not magic numbers.

• efficiency.md — algorithmic complexity as a trade-off system; when to optimize and when not to.

• security.md — security proportional to the project's real attack surface, with a few universal red flags (hardcoded secrets, SQL injection) regardless of context.

• testing.md — tests for confidence when changing code, not for chasing coverage numbers.

• documentation.md — documentation that answers real questions, kept close to the code and living, not a one-off dump.

Anti-patterns it avoids

Blanket rules applied without checking if they're relevant (e.g. "always add rate limiting" without knowing if there's an exposed API, "max 25 lines per function" as a mechanical rule, chasing an 80% coverage number), generic feedback ("this follows best practices"), documenting every function mechanically, and recommending the most popular stack without analysis.

Customization

The framework is modular: add your own rules under .sdd/rules/, edit the existing ones for your team/domain, add context files under .sdd/context/, or rename .sdd/ (update the references in AI.md and the rules if you do).

Status

The MCP server, CLI, memory store, and rules are functional and used day-to-day. There is currently no automated test suite for the df package itself (df/tests/ is empty) and no license file yet.