8c6a652d6f
- Add docs index with structured navigation and links across the new documentation set - Document onboarding and technical foundations with getting-started and architecture guides - Add detailed CLI and settings references plus feature guides for dashboard, tasks, workflow steps, missions, multi-project, and agents - Add a contributing guide and polish cross-references between docs pages for discoverability - Include dashboard screenshots for key views to provide visual context in the guides
126 lines
3.9 KiB
Markdown
126 lines
3.9 KiB
Markdown
# Architecture
|
|
|
|
[← Docs index](./README.md)
|
|
|
|
This document explains how Fusion is structured, how data is stored, and how the AI execution pipeline moves work from idea to merged code.
|
|
|
|
## End-to-End Workflow
|
|
|
|
```mermaid
|
|
graph TD
|
|
H((You)) -->|rough idea| T["Triage\n<i>auto-specification</i>"]
|
|
T --> TD["Todo\n<i>scheduled for execution</i>"]
|
|
TD --> IP["In Progress\n<i>plan, review, execute, review</i>"]
|
|
|
|
IP --> IR["In Review\n<i>ready to merge</i>"]
|
|
IR --> D["Done"]
|
|
```
|
|
|
|
At a high level:
|
|
|
|
- **Triage** writes a full `PROMPT.md` spec
|
|
- **Scheduler** selects ready tasks (respecting dependencies and limits)
|
|
- **Executor** runs agents in isolated worktrees
|
|
- **Merger** finalizes tasks to `done` (direct squash merge or PR flow)
|
|
|
|
## Workspace Packages
|
|
|
|
| Package | Responsibility |
|
|
|---|---|
|
|
| `@fusion/core` | Domain model, TaskStore/MissionStore, SQLite persistence, shared types/defaults. |
|
|
| `@fusion/dashboard` | Express API + React dashboard UI (kanban board, live updates, tooling surfaces). |
|
|
| `@fusion/engine` | Triage, scheduling, execution, workflow steps, merge orchestration, automation runtime. |
|
|
| `@fusion/tui` | Ink-based terminal UI package (lightweight terminal components). |
|
|
| `@gsxdsm/fusion` | Published CLI (`fn`) + pi extension tools. |
|
|
|
|
## Storage Architecture
|
|
|
|
Fusion uses a **hybrid model**:
|
|
|
|
- **SQLite metadata:** `.fusion/fusion.db`
|
|
- **Blob/filesystem artifacts:** `.fusion/tasks/{id}/PROMPT.md`, `agent.log`, attachments
|
|
- **Global user settings:** `~/.pi/fusion/settings.json`
|
|
|
|
### Why hybrid?
|
|
|
|
- SQLite gives transactional metadata updates and indexed queries.
|
|
- Filesystem storage keeps large task artifacts simple and portable.
|
|
|
|
### Key SQLite behavior
|
|
|
|
- WAL mode enabled for concurrent readers/writers
|
|
- Foreign keys enforced
|
|
- Monotonic metadata timestamp used for change detection
|
|
|
|
## Typical `.fusion/` Layout
|
|
|
|
```text
|
|
.fusion/
|
|
fusion.db
|
|
tasks/
|
|
FN-001/
|
|
task.json
|
|
PROMPT.md
|
|
agent.log
|
|
attachments/
|
|
backups/
|
|
```
|
|
|
|
## AI Engine Components
|
|
|
|
### 1) TriageProcessor
|
|
|
|
- Reads rough task descriptions
|
|
- Generates structured `PROMPT.md` with mission, file scope, steps, and acceptance criteria
|
|
- Can be gated by `requirePlanApproval`
|
|
|
|
### 2) Scheduler
|
|
|
|
- Moves tasks from `todo` to `in-progress`
|
|
- Enforces dependencies, concurrency limits, and overlap rules
|
|
- Coordinates mission/slice progression hooks
|
|
|
|
### 3) TaskExecutor
|
|
|
|
- Creates/attaches task worktrees (`fusion/{task-id}` branches)
|
|
- Runs agent sessions with tooling (task update/logging/review/spawn)
|
|
- Supports step session mode (`runStepsInNewSessions`) and parallel step execution (`maxParallelSteps`)
|
|
- Executes configured pre-merge workflow steps
|
|
|
|
## Error Recovery and Resilience
|
|
|
|
Fusion has multiple safety/recovery paths:
|
|
|
|
- **Transient error retry:** bounded retry flow for temporary failures
|
|
- **Stuck task detection:** inactivity timeout can terminate/requeue hung runs
|
|
- **Context-limit recovery:** compact-and-resume flow when model context overflows
|
|
- **Workflow step failure handling:** marks task failed/in-review for inspection rather than silently passing
|
|
- **Pause semantics:** global hard-stop (`globalPause`) and soft scheduler pause (`enginePaused`)
|
|
|
|
## Project Memory System
|
|
|
|
When enabled (`memoryEnabled: true`), agents can use project memory files:
|
|
|
|
- `.fusion/memory.md` — durable project learnings
|
|
- Optional derived memory insights (via scheduled extraction)
|
|
|
|
This helps agents retain patterns and pitfalls across tasks.
|
|
|
|
## Git Worktree Isolation Model
|
|
|
|
Every active task runs in its own git worktree:
|
|
|
|
- Avoids cross-task file collisions
|
|
- Makes cleanup/retry deterministic
|
|
- Enables parallel execution safely
|
|
- Supports pooled reuse when `recycleWorktrees` is enabled
|
|
|
|
Branch naming remains `fusion/{task-id}` regardless of worktree folder naming mode.
|
|
|
|
## Related Guides
|
|
|
|
- [Task Management](./task-management.md)
|
|
- [Workflow Steps](./workflow-steps.md)
|
|
- [Multi-Project](./multi-project.md)
|
|
- [Settings Reference](./settings-reference.md)
|