# agent-fde

> A methodology-driven consulting agent toolkit that accumulates experience.
> **FDE** manages the process and deliverables; the **memory system** manages experience reuse.

`agent-fde` fuses two ideas into one clean, tested, open-source Python package:

- **FDE (Frontline Deployment Engineering)** — a 5-phase pipeline that turns an
  enterprise AI/automation rollout into executable, file-based deliverables.
- **Layered memory + skill crystallization** — the agent remembers what worked
  and recalls it automatically the next time, like muscle memory.

It ships as both an **MCP server** (for host agents such as Claude) and a **CLI**.

[中文文档 →](./README.zh.md)

## Why

Most agent tooling either has a strong workflow but no memory, or accumulates
memory but has no methodology. `agent-fde` combines both: a disciplined
5-phase engagement process *and* a memory loop that crystallizes each finished
engagement into a reusable skill.

## Key design: inversion of control

The engine **never calls an LLM**. Instead:

```
old (stub):   engine → calls LLM API → generates deliverable    ❌ needs API key, vendor lock-in
new (inverted): host LLM → does its own analysis → submits structured result
                → fde_submit_analysis(...) → engine validates (pydantic) + renders  ✅
```

Result: the package has **zero LLM dependency** — no API key, no vendor lock-in.
Methodology travels with the package as `SKILL.md` prompts that guide the host
agent through each phase. Pure-CLI use falls back to heuristic templates.

## Install

```bash
pip install agent-fde              # core (MCP + FDE + memory)
pip install "agent-fde[browser]"   # + optional Playwright browser tools
pip install "agent-fde[dev]"       # + test/lint tooling
```

## Usage

### As an MCP server

```bash
agent-fde serve
```

Register it with your MCP host, e.g.:

```json
{
  "mcpServers": {
    "agent-fde": { "command": "agent-fde", "args": ["serve"] }
  }
}
```

### As a CLI

```bash
agent-fde fde new --client "Acme Clinic" --industry "Healthcare" --project "Chart AI"
agent-fde fde list
agent-fde fde run <engagement_id> --phase 1
agent-fde fde run-all <engagement_id> --input "Doctors spend 2h/day on chart entry"
agent-fde fde deliverable <engagement_id> --phase 3
```

## The 5 phases

| Phase | Name | Deliverable |
|------:|------|-------------|
| 1 | Discovery | Pain-point matrix |
| 2 | Assessment | Automation opportunity list + ROI |
| 3 | Architecture | Tech design + Mermaid diagram + milestones |
| 4 | Prototype | Prototype file skeleton + test cases + setup guide |
| 5 | Handoff | Evidence package + project index |

On Phase 5 completion the tools prompt the host agent to call
`memory_crystallize`, closing the experience loop.

## Layered memory (L0–L4)

| Layer | Role |
|------:|------|
| L0 | Meta rules (behavioural red lines) |
| L1 | Insight index (≤25 navigation pointers) |
| L2 | Global facts (user preferences, environment) |
| L3 | Skill library (crystallized reusable SOPs) |
| L4 | Session archive |

Stored under `~/.agent-fde/` (override with `AGENT_FDE_HOME`), decoupled from code.
Engagements live under `~/.agent-fde/engagements/<id>/`.

## Muscle-memory hook

`hooks/skill_reflex.py` is a zero-dependency Claude Code `UserPromptSubmit` hook.
On each prompt it fuzzy-matches your crystallized L3 skills (Chinese-friendly)
and injects the matching SOP as context — no manual retrieval. It shares the
exact matcher used by the `skill_find` MCP tool (single source of truth) and
fails safe (any error → silent `exit 0`).

## Development

```bash
pip install -e ".[dev,browser]"
pytest
ruff check .
```

## License

MIT