Workspace vs Feature: Two Surfaces

How Fabriq separates long-lived knowledge from short-lived work — and why it matters.

Think of a physical workshop. You have two kinds of space:

The library — where schematics, reference manuals, and finished blueprints live. These are shared, long-lived, and everyone can reference them.
The workbench — where you're actively cutting material for a specific project. It's isolated from other workbenches. When you're done, the workbench gets cleared for the next job.

Fabriq works the same way.

The workspace (your library)

A workspace is the root directory Fabriq manages. It contains:

my-project/
├── .dapei/           ← Fabriq runtime data (audit logs, cognitive index)
├── docs/             ← Shared product knowledge
├── repos/            ← Registered base repositories
└── features/         ← Active feature worktrees

The docs/ and repos/ directories are the workspace dimension — long-lived, shared, version-controlled. This is where your team's specs, ADRs, and design tokens live. Everyone on the team sees the same thing.

What goes into workspace assets

Asset	Example
Product specs	`docs/03-business-design.md`
Architecture decisions	`docs/decisions/ADR-001-...`
Design tokens	`docs/tokens/`
Repository source	`repos/main-service/`

The feature (your workbench)

A feature is a unit of work for the AI agent. When you create one, Fabriq:

Creates an isolated git worktree from your base repo
Generates a feature directory with its own docs, tests, and reports
Opens the Feature Workbench — the cockpit for this work session

features/
└── add-search-filter/
    ├── feature.yaml        ← Feature metadata
    ├── docs/               ← Stage documents (01-06)
    ├── tests/              ← Testability plan + cases + runs
    ├── reports/            ← Validation report, close summary
    ├── context/            ← Runtime context for the agent
    └── repos/              ← Git worktrees (isolated!)

This is the feature dimension — short-lived, per-developer, isolated. The agent works exclusively here.

The boundary (why it matters)

The boundary between the two dimensions is enforced at every layer:

On disk: the agent's worktree is physically separate from your base repos
In the UI: the Workspace Browser shows two panels (assets vs features)
In the IPC layer: capability calls are tagged with their dimension — the engine rejects cross-dimension writes
In prompts: the Knowledge Boundary header embedded in markdown files tells the agent exactly where it can and cannot write

What this prevents:

❌ Agent overwriting your docs/architecture.md while working on a feature
❌ Agent accidentally committing half-finished work to your main branch
❌ Two features interfering with each other

What it enables:

✅ Run multiple features in parallel with full isolation
✅ Close a feature and clean up without affecting workspace assets
✅ Audit every change by dimension and feature

The UI: Workspace Browser

When you launch Fabriq, you see the Workspace Browser:

┌────────────────────────────────────────────────────────────┐
│  Workspace: my-project                                     │
│                                                            │
│  ┌─ Workspace Assets ─────────────────────────────────┐   │
│  │  📁 docs/   (shared knowledge)                    │   │
│  │  📁 repos/  (base code)                           │   │
│  │                                                    │   │
│  │  [Browse Assets]  [Add Repository]                 │   │
│  └────────────────────────────────────────────────────┘   │
│                                                            │
│  ┌─ Features ─────────────────────────────────────────┐   │
│  │  📂 add-search-filter   [Stage: Implementing]     │   │
│  │  📂 fix-login-redirect  [Stage: Review]           │   │
│  │                                                    │   │
│  │  [+ New Feature]                                   │   │
│  └────────────────────────────────────────────────────┘   │
└────────────────────────────────────────────────────────────┘

Left panel: workspace assets — read-only in feature context
Right panel: your features — click any to open its Workbench

FAQ

Q: Can I manually edit workspace assets from a feature context?
A: Not through Fabriq's IPC. The engine rejects write capabilities targeting the workspace dimension from a feature session. If you need to update a shared doc, close the feature and edit in the workspace directly (via your editor, outside Fabriq).

Q: What happens when I close a feature?
A: Selected docs are promoted back to the workspace, a feature history entry is created, and the worktree is cleaned up. Nothing is lost — it's structured knowledge return.

Q: Can two features share a worktree?
A: No. Each feature gets its own git worktree. This is the isolation guarantee — one agent's changes never contaminate another's.

Next steps

Confirmation Gates — how you review and approve agent actions
Feature Lifecycle — walk through every stage
Your First 15 Minutes — hands-on walkthrough