# Functional Description: FPF Agent Stack
FunctionGemma (Ollama) + AgentFS (Turso) + Agent Skills tools.
## 1. Objective
Build a local-first agent runtime that uses only the FunctionGemma model for reasoning and tool selection, while executing all file/state operations inside an auditable, copy-on-write sandbox (AgentFS). Tools are packaged as Agent Skills folders.
## 2. Scope
### 2.1 In scope
- Inference via Ollama running functiongemma:* (no other LLMs).
- Skills as the only tool interface: each tool lives in a skills/ folder with SKILL.md + optional scripts/resources.
- AgentFS sandbox sessions for: workspace overlay, state persistence, audit trail.
- BDD acceptance tests in Cucumber/Gherkin.
- Training loop for FunctionGemma based on audited tool-call traces (optional, after baseline works).
### 2.2 Out of scope (initially)
- Network tool access (keep offline-first until policy is explicit).
- Autonomous long-running background jobs.
- General chat assistant features not tied to skills.
## 3. Definitions (FPF-aligned)
These definitions keep planning vs execution explicit and keep ‘documents’ separate from the things they describe.
| Term | Working definition |
| :--- | :--- |
| **Skill (tool)** | A packaged capability: instructions + schemas + scripts/resources, loadable on demand. |
| **Tool call** | A structured invocation of a Skill-defined interface with validated arguments. |
| **Description** | A human-readable statement of what the system/tool is and what it is supposed to do. |
| **Spec** | A Description that is falsifiable by an executable harness (e.g., Cucumber tests). |
| **Work** | A dated execution instance (what actually happened) and its recorded outcomes. |
| **WorkPlan** | A schedule/calendar for intended work (not proof that work happened). |
| **GuardDecision** | Tri-state: `pass` \| `degrade` \| `abstain`. Unknown never coerces to pass. |
| **Evidence carrier** | Logs, traces, test reports, etc. used to adjudicate guard predicates. |
## 4. User-facing behaviors
### 4.1 Skill discovery and loading
- Given a task, the agent selects a minimal set of relevant skills by searching SKILL.md metadata and instructions.
- The agent loads only those skills into the prompt context (token-budget control).
- If no skills match, the agent responds with abstain + explanation + suggested next steps.
### 4.2 Tool execution in AgentFS
- All filesystem writes happen inside an AgentFS copy-on-write overlay session.
- Every file operation is auditable and queryable in AgentFS (session DB).
- The agent can export a change summary (diff) and an audit report per run.
### 4.3 Reliability constraints
- Arguments to tools must validate against the skill’s JSON schema before execution.
- On schema failure: abstain (no execution), with a minimal repair hint.
- On execution failure: degrade, attach error + evidence pointer (audit log query).
## 5. Non-functional requirements
| NFR | Target / rule |
| :--- | :--- |
| **Reproducibility** | Same inputs + same skills version + same AgentFS snapshot => same outputs, within known nondeterminism bounds. |
| **Auditability** | Every tool call and file op recorded, with stable IDs and timestamps. |
| **Isolation** | No writes to the host workspace; only overlay writes inside AgentFS. |
| **Observability** | Structured logs; per-run artifact bundle includes: tool calls, diffs, test report, audit summary. |
| **Safety** | Allowlist skills; deny unknown tools; tri-state guards; minimal permissions per skill. |
## Appendix A. Minimal repo layout (suggested)
```text
repo/
skills/
<skill-name>/
SKILL.md
schemas/
scripts/
examples/
agent/
src/
test/
bdd/
features/
step_definitions/
agentfs/
sessions/ # produced artifacts (sqlite dbs)
```
## Appendix B. References
- Agent Skills overview (agentskills.io).
- AgentFS introduction (docs.turso.tech).
- FunctionGemma on Ollama library (ollama.com).
