> ## Documentation Index
> Fetch the complete documentation index at: https://panopticon-cli.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Project Registry

> Managing multiple projects with Overdeck

export const ThemedImage = ({light, dark, alt = ""}) => <>
    <img src={light} alt={alt} className="block dark:hidden" />
    <img src={dark ?? light} alt={alt} className="hidden dark:block" />
  </>;

# Project Registry

Overdeck's project registry enables multi-project management with intelligent issue routing and label-based workspace creation.

## Overview

Projects are registered in `~/.overdeck/projects.yaml`. Each project can have:

* **Issue routing rules** - Route issues to different subdirectories based on labels
* **Custom workspace commands** - For complex polyrepo setups
* **Linear team mapping** - Connect projects to Linear teams

While `projects.yaml` is the source of truth, much of this configuration is also surfaced in the dashboard's **Settings** page, alongside model routing for the agents and conversations Overdeck runs and tracker API keys.

<ThemedImage light="/images/dashboard/settings-light.png" dark="/images/dashboard/settings-dark.png" alt="Overdeck Settings page showing model routing, tracker API keys, and project configuration" />

<Note>
  Overdeck manages both the workflow pipeline and the agents and conversations
  that move issues through it. The Settings page is where model routing for those
  agents lives, while per-project routing and workspace rules below are edited in
  `~/.overdeck/projects.yaml`.
</Note>

## Registering Projects

```bash theme={null}
# Register a project
pan project add /path/to/your/project --name myproject --linear-team PRJ

# List registered projects
pan project list

# Remove a project
pan project remove myproject
```

### Rename a project

```bash theme={null}
pan project rename <key> <newName>

# Example: keep the stable `myn` key and change its display name
pan project rename myn "Mind Your Now"
```

The registration key is the stable identifier stored as the project's YAML map key. It is derived when the project is registered and cannot be renamed. The display name is the human-facing label shown throughout Overdeck; it can be renamed, but it cannot match another project's registration key or display name, ignoring letter case.

In the dashboard, use the pencil beside the name on the project page, or right-click the project tree row and choose **Rename project**. Both controls open an inline editor for the display name while preserving the registration key.

## Project Configuration

Projects are defined in `~/.overdeck/projects.yaml`:

```yaml theme={null}
projects:
  myn:
    name: "Mind Your Now"
    path: /home/user/projects/myn
    issue_prefix: MIN
    issue_routing:
      - labels: [splash, landing-pages, seo]
        path: /home/user/projects/myn/splash
      - labels: [docs, marketing]
        path: /home/user/projects/myn/docs
      - default: true
        path: /home/user/projects/myn

  overdeck:
    name: "Overdeck"
    path: /home/user/projects/overdeck
    issue_prefix: PAN
```

### Configuration Fields

| Field                      | Required | Description                                                           |
| -------------------------- | -------- | --------------------------------------------------------------------- |
| `name`                     | Yes      | Human-readable project name                                           |
| `path`                     | Yes      | Absolute path to project root                                         |
| `issue_prefix`             | Yes\*    | Issue prefix for standard format IDs (e.g., "MIN", "PAN")             |
| `tracker`                  | No       | Tracker type: `linear`, `github`, `gitlab`, `rally`                   |
| `issue_prefixes`           | No       | Array of prefixes for multi-prefix trackers (e.g., `[F, US, DE, TA]`) |
| `issue_pattern`            | No       | Custom regex for issue ID parsing: `^(PREFIX)-(\\d+)$`                |
| `issue_routing`            | No       | Label-based routing rules                                             |
| `workspace_command`        | No       | Custom workspace creation script                                      |
| `workspace_remove_command` | No       | Custom workspace cleanup script                                       |
| `workspace`                | No       | Polyrepo/progressive workspace configuration                          |
| `release`                  | No       | Coordinated post-merge release configuration                          |

\*Not required if `issue_prefixes` or `issue_pattern` is specified.

## Release Configuration

The optional `release:` section tells Overdeck how to coordinate a project's post-merge rollout across multiple components. Overdeck resolves a release plan, waits for each component to become healthy, runs verification commands, halts the plan on failure, and runs a rollback hook when one is configured.

```yaml theme={null}
projects:
  myn:
    name: "Mind Your Now"
    path: /home/user/projects/myn
    issue_prefix: MIN
    release:
      components:
        api:
          provider: kubernetes
          trigger: auto
          health_url: https://api.myn.example.com/health
          version_check: scripts/check-version.sh api
          smoke_test: scripts/smoke.sh api
          rollback: scripts/rollback.sh api
        frontend:
          provider: vercel
          trigger: auto
          depends_on: [api]
          health_url: https://myn.example.com/health
          smoke_test: scripts/smoke.sh frontend
        docs:
          provider: vercel
          trigger: skip
```

### Component fields

| Field           | Required | Description                                                                                                         |
| --------------- | -------- | ------------------------------------------------------------------------------------------------------------------- |
| `provider`      | No       | Informational label for the deployment target (e.g. `kubernetes`, `vercel`)                                         |
| `trigger`       | Yes      | `auto` — wait for external deploy and verify; `manual` — pause for operator release; `skip` — exclude from the plan |
| `depends_on`    | No       | Array of other component keys that must release before this one                                                     |
| `health_url`    | No       | URL Overdeck polls until it returns a successful response                                                           |
| `version_check` | No       | Shell command that must exit 0 after the component is healthy                                                       |
| `smoke_test`    | No       | Shell command that must exit 0 to consider the component released                                                   |
| `rollback`      | No       | Shell command to run when this component fails; success marks the issue `rolled_back`                               |

### Release semantics

* `trigger: auto` means Overdeck **waits and verifies** an external deploy; it does not invoke the provider deploy itself.
* Components are released in `depends_on` order using a topological sort. A component is only started after its dependencies pass.
* If any check fails, Overdeck stops all later components and records the final issue-level status.
* Projects without a `release:` section are **skipped cleanly** — no failure is recorded.

### Release status lifecycle

Issue-level `releaseStatus` moves through the following values:

`pending` → `releasing` → `passed`\
`pending` → `releasing` → `failed`\
`pending` → `releasing` → `partial`\
`pending` → `releasing` → `rolled_back`\
`pending` → `skipped`

The seven possible values are: `pending`, `releasing`, `passed`, `failed`, `partial`, `rolled_back`, and `skipped`.

Inspect or retry a release from the CLI with `pan rollout`:

```bash theme={null}
pan rollout status <issue-id>
pan rollout retry <issue-id>
```

`pan rollout` is distinct from `pan release`, which publishes npm stable/canary packages.

## Label-Based Routing

Issues are routed to different subdirectories based on their labels:

1. **Labeled issues** - Matched against `issue_routing` rules in order
2. **Default route** - Issues without matching labels use the `default: true` path
3. **Fallback** - If no default, uses the project root path

**Example:** An issue with label "splash" in the MIN team would create its workspace at `/home/user/projects/myn/splash/workspaces/feature-min-xxx/`.

## Linear Project Mapping

If you have multiple Linear projects, configure which local directory each maps to. Create/edit `~/.overdeck/project-mappings.json`:

```json theme={null}
[
  {
    "linearProjectId": "abc123",
    "linearProjectName": "Mind Your Now",
    "linearPrefix": "MIN",
    "localPath": "/home/user/projects/myn"
  },
  {
    "linearProjectId": "def456",
    "linearProjectName": "Househunt",
    "linearPrefix": "HH",
    "localPath": "/home/user/projects/househunt"
  }
]
```

The dashboard uses this mapping to determine where to create workspaces when you click "Create Workspace" or "Start Agent" for an issue.

## Custom Workspace Commands (Legacy)

> **Note:** For most polyrepo projects, use the built-in `workspace` configuration (see [Polyrepo Configuration](/configuration/polyrepo)) instead of custom scripts. Custom commands are only needed for highly specialized setups.

For projects that need logic beyond what the configuration supports, you can specify custom workspace scripts:

```yaml theme={null}
projects:
  myn:
    name: "Mind Your Now"
    path: /home/user/projects/myn
    issue_prefix: MIN
    # Custom scripts handle complex workspace setup
    workspace_command: /home/user/projects/myn/infra/new-feature
    workspace_remove_command: /home/user/projects/myn/infra/remove-feature
```

When `workspace_command` is specified, Overdeck calls your script instead of creating a standard git worktree. The script receives the normalized issue ID (e.g., `min-123`) as an argument.

When `workspace_remove_command` is specified, Overdeck calls your script when deleting workspaces (e.g., aborting planning with "delete workspace" enabled). This is important for complex setups that need to:

* Stop Docker containers and remove volumes
* Clean up root-owned files created by containers
* Remove git worktrees from multiple repositories
* Release port assignments
* Remove DNS entries

**What your custom script should handle:**

* Creating git worktrees for multiple repositories (polyrepo structure)
* Setting up Docker Compose files and dev containers
* Configuring environment variables and `.env` files
* Setting up DNS entries for workspace-specific URLs (e.g., Traefik routing)
* Creating a `./dev` script for container management
* Copying agent configuration templates (CLAUDE.md, .mcp.json, etc.)

**Example script flow:**

```bash theme={null}
#!/bin/bash
# new-feature script for a polyrepo project
ISSUE_ID=$1  # e.g., "min-123"

# Create worktrees for frontend and api repos
git -C /path/to/frontend worktree add ../workspaces/feature-$ISSUE_ID/fe feature/$ISSUE_ID
git -C /path/to/api worktree add ../workspaces/feature-$ISSUE_ID/api feature/$ISSUE_ID

# Generate docker-compose from templates
sed "s/{{FEATURE_FOLDER}}/feature-$ISSUE_ID/g" template.yml > workspace/docker-compose.yml

# Set up DNS and Traefik routing
# ... additional setup
```

The standard `pan workspace create` command will automatically detect and use your custom script.

## Project Initialization

When registering a new project with Overdeck (`pan project add`), the system will:

1. **Check for existing PRD** - Look for `docs/PRD.md`, `PRD.md`, `README.md`, or similar
2. **If found**: Use it to create/update the canonical PRD format, prompting for any missing crucial information
3. **If not found**: Generate one by:
   * Analyzing the codebase structure
   * Identifying key technologies and patterns
   * Asking discovery questions about the product

This ensures every Overdeck-managed project has a well-defined canonical PRD that agents can reference.

## Progressive Workspaces

For large projects with 10+ repositories, progressive workspaces provide on-demand repo checkout. Enable in `workspace` config:

```yaml theme={null}
projects:
  enterprise:
    name: "Enterprise Integration"
    path: /home/user/projects/enterprise
    tracker: rally
    issue_prefixes: [F, US, DE, TA]
    workspace:
      type: polyrepo
      progressive: true
      always_include: [meta]
      groups_file: team-meta/overdeck/repo-groups.yaml
      pr_target: qa
      repos:
        - name: meta
          path: team-meta
          link_type: symlink
          readonly: true
```

Key progressive fields:

| Field            | Description                                                        |
| ---------------- | ------------------------------------------------------------------ |
| `progressive`    | When `true`, only `always_include` repos created on workspace init |
| `always_include` | Repo names to always include (typically meta/docs repos)           |
| `groups_file`    | Path to `repo-groups.yaml` for named repo groups                   |
| `pr_target`      | Default PR target branch (e.g., `'qa'`)                            |

See [Progressive Polyrepo](/configuration/progressive-polyrepo) for full documentation.

## Related Guides

* [Polyrepo Configuration](/configuration/polyrepo) - Multi-repository workspace setup
* [Progressive Polyrepo](/configuration/progressive-polyrepo) - Large-scale polyrepo with on-demand checkout
* [Setup Wizard](/configuration/setup-wizard) - Interactive project configuration
* [Meta Repos](/configuration/meta-repos) - Team conventions and onboarding kits
* [Issue Tracker Integration](/configuration/issue-trackers) - Connecting to Linear, GitHub, Rally, etc.
* [Workspaces](/features/workspaces) - Workspace management