Adding and Managing Repositories

Before Fabriq can create features, it needs to know which repositories to use. The repo pool is the collection of base repositories registered in your workspace — the read-only source of truth that features branch from.

Workspace
├── repos/
│   ├── my-app/         ← Base repo (read-only in feature context)
│   ├── my-api/         ← Multiple repos supported
│   └── shared-lib/     ← All registered here
├── features/
│   └── add-dark-mode-toggle/
│       └── repos/
│           └── my-app/ ← Worktree (agent writes here)

Adding a repository

1. Open the Workspace Browser
2. Click the Repos tab
3. Click Add Repository

You'll see a dialog asking for the path to the repository on your machine. Point it at the git repo directory.

What happens when you add a repo:

1. Fabriq scans the directory and validates it's a git repo
2. It registers the repository path in the workspace config
3. If it's not already in repos/<name>/, Fabriq may create a local reference

After adding, the repo appears in the Repos tab:

┌─ Repositories ──────────────────────────────────────┐
│  │  my-app    │  main  │  git@github.com/... │  ✓   │
│  │  my-api    │  main  │  git@github.com/... │  ✓   │
│                                                     │
│  [+ Add Repository]                                  │
└─────────────────────────────────────────────────────┘

Multiple repositories

If your project spans multiple repos, register them all:

Workspace/repos/
├── frontend-app/       ← React frontend
├── backend-api/        ← Node.js API
└── shared-types/       ← Shared TypeScript types

When you create a feature, Fabriq creates worktrees for all relevant repos. The feature's repos/ directory mirrors the workspace's repos/ structure:

features/delete-user-flow/
└── repos/
    ├── frontend-app/    ← Worktree of frontend-app
    └── backend-api/     ← Worktree of backend-api

Removing a repository

1. Open the Repos tab
2. Find the repo you want to remove
3. Click the ⋮ menu next to it → Remove Repository

Fabriq checks that no active features depend on this repo before removing. If features are using it, you'll be prompted to close them first.

Troubleshooting

Problem	Likely cause	Solution
"Not a git repository"	The directory isn't a git repo, or the .git folder is missing	Run git init or clone the repo first
"Repository not found"	The path doesn't exist or was moved	Check the path and update it
"Authentication failed"	Private repo without credentials	Set up SSH key or use HTTPS with credentials
"Clone too large"	Repository has extensive history or large binary files	Try a shallow clone, or add specific paths to sparse checkout
"Repository already registered"	Duplicate entry	Remove the existing entry first, or update its path

Next steps

• Concepts: Workspace vs Feature — understanding the two surfaces
• Creating a Feature — create your first feature with an isolated worktree
• Workspaces Overview — more about workspace structure