# 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.

## 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:

```bash
python -m df.cli.main doctor
```

should report `MCP handshake ok` and list the available tools.

Get a workflow recommendation:

```bash
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:

```bash
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.