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