---
name: devhub-add-project
description: Register a local project directory in XA DevHub through its authenticated localhost API, including conservative project metadata discovery, duplicate prevention, complete native-editor configuration, DevHub process health recovery, dry-run/readback verification, and repository-governed rebuild or restart handling. Use when the user invokes $devhub-add-project with a directory or asks to add, include, register, or update a local project in XA DevHub.
---

# DevHub Add Project

Register one explicit local directory as an XA DevHub project. Keep the operation API-first, idempotent, and evidence-backed.

## Required input and authority

- Require one explicit project directory. Accept quoted Windows paths with spaces.
- Resolve the directory to an absolute path and fail if it does not exist or is not a directory.
- Treat a request to register the directory as authority to create the missing DevHub project. Follow the actual user's permissions and project constraints for starting or restarting DevHub; project registration alone does not establish process-control permission.
- Do not treat invocation as authority to commit, push, publish, delete records, edit databases, or force-kill a responsive process.
- Use reasonable values for optional fields. Ask only when a same-name/different-path collision or another ambiguity could overwrite the wrong project.

## Load the owning workflows

1. Read and use `$devhub-development` for intent, baseline, evidence, and closeout.
2. Read and use `$devhub-control` for every DevHub read or mutation.
3. Read the target directory's applicable domain skill and nearest `AGENTS.md` or equivalent instructions.
4. Never open or edit `devhub.db` directly, even while DevHub is closed.

## Workflow

### 1. Inspect the target

- Record the resolved path and inspect only that project plus applicable ancestor instructions.
- Read the nearest `AGENTS.md`, canonical README, build manifests, test configuration, release scripts, version authority, and project-scoped Git metadata.
- Preserve dirty files and unrelated work. Do not commit or change Git state.
- Distinguish a project-owned repository from an unrelated parent/container repository. Leave `github_url` blank unless the remote is demonstrably owned by the supplied project or the user provides it.

Derive fields conservatively:

- `name`: canonical product name from project instructions or manifest; otherwise the directory name.
- `description`: one factual sentence from current project documentation.
- `rules_path`: nearest project-owned `AGENTS.md`; otherwise its canonical README; otherwise blank.
- `codex_skills`: only installed skills that actually own this project or its test workflow. Never invent a skill name.
- `build_command`: the documented canonical build command. Saving it is metadata and does not authorize executing it.
- `prep_command`, `release_command`, and `version_command`: save only commands proven by current files or instructions.
- `build_cwd`: blank when the project root is correct; otherwise the proven working directory.
- `local_version_file`: the current manifest or source file that owns the local version.
- `remote_version_url` and `remote_version_key`: blank unless the project has a proven published-version source.
- `aliases`: a short comma-separated set of product name, folder name, and established abbreviations.
- `discord_tickets`: default `false`; enable only when the project is intended to participate in DevHub's Discord ticket menu.

For Python commands, verify that the chosen interpreter or Windows launcher is available to DevHub's process environment. A shell that finds `python` does not prove an already-running DevHub process inherited the same PATH. When correcting a saved command, preserve its script and arguments, verify the launcher separately, and avoid running a version-changing script merely to test interpreter lookup. Derive any absolute interpreter path from the user's own installation.

Distinguish a version file on public GitHub `main` from a published release or tag. Configure the comparison against the source the user actually intends, and label public source comparisons accordingly; a branch version alone does not prove that a downloadable release exists.

### 2. Establish DevHub health

Resolve the installed `devhub-control/scripts/devhub.ps1` and call `health` before any sequence.

- Healthy API: keep DevHub running and continue.
- DevHub stopped: when starting it is authorized, resolve the existing executable from `DEVHUB_EXE`, `executable_path` in `devhub-control/scripts/devhub.config.json`, or a previously verified installation path. Start only that exact executable with its directory as the working directory, wait up to 30 seconds, then call `health` again. If no executable is safely resolvable, stop and request the installation path instead of searching unrelated workspaces broadly.
- Process running but API temporarily unavailable: retry bounded health checks. If recovery is needed and process control is authorized, verify that no build, import, migration, or maintenance operation is active; request a graceful close with `CloseMainWindow()`, wait for exit, restart the existing binary, and recheck health. Otherwise report the health failure and leave process recovery to the user.
- Do not force-terminate a responsive DevHub process or risk unsaved operator input. Ask before forced termination if graceful recovery fails.
- If the server remains unavailable, stop. Do not fall back to SQLite or fabricate a successful add.

### 3. Prevent duplicates

1. Call `project-list`.
2. Read each plausible match with `project-get`; the list route intentionally omits paths and commands.
3. Compare normalized absolute paths case-insensitively.
4. If the exact path already exists, report the existing ID and treat the request as an idempotent no-op. Update it only when the user requested an update or current fields are provably stale and the update is within scope.
5. If the proposed name belongs to another path, stop and request direction.

### 4. Record intent and baseline

For a non-trivial add or any lifecycle recovery, create a lightweight `$devhub-development` workflow under the registered DevHub application project until the new project has an ID. If that project is not registered, use a cross-project workflow rather than inventing an ID. Record:

- objective and minimum success;
- explicit project directory and scope boundaries;
- live health/version and existing project count;
- derived complete payload;
- process/build constraints;
- validation criteria and next action.

Use workflow artifacts for the baseline and checkpoints. Do not make project creation depend on filling unnecessary template fields.

### 5. Save through the API

Create a temporary JSON payload with exactly this complete field set and correct JSON types:

```json
{
  "name": "",
  "description": "",
  "path": "",
  "rules_path": "",
  "codex_skills": "",
  "build_command": "",
  "prep_command": "",
  "release_command": "",
  "version_command": "",
  "build_cwd": "",
  "local_version_file": "",
  "remote_version_url": "",
  "remote_version_key": "",
  "github_url": "",
  "aliases": "",
  "discord_tickets": false
}
```

- Keep the payload free of credentials and runtime data.
- Use a JSON file for `-InputJson` when paths or commands contain quotes; nested inline PowerShell quoting is unreliable.
- Run `project-save -WhatIf` first.
- If preview succeeds, run `project-save` without `-WhatIf`.
- Preserve the returned project ID. The transport performs exact `project-get` readback; call `project-get` again when collecting final evidence.

### 6. Rebuild or restart only when required

- Ordinary project creation does not require a target-project build, DevHub source edit, DevHub restart, or DevHub rebuild.
- The GUI reloads projects periodically; allow at least one refresh interval before assuming a restart is needed.
- If the live server lacks the required route or has a confirmed source/runtime mismatch, inspect the current DevHub source root and its nearest `AGENTS.md` or equivalent repository instructions before editing or building.
- Follow the current repository build-owner boundary exactly. When repository instructions reserve native builds for the operator, stop at that gate, provide the exact command, and wait for the supplied output.
- Never claim a rebuild because source was edited or a command was proposed.

### 7. Verify and close out

Require current-run evidence for:

1. exact `project-get` values and returned ID;
2. one case-insensitive path match in the live project set;
3. post-mutation `health` with `ok: true`;
4. DevHub process responsiveness when lifecycle work occurred;
5. any separately authorized source, build, test, or runtime gate.

Record checkpoints and typed workflow evidence with exact commands, ordered timestamps, integer exit code, and failure count. Complete the workflow only when every minimum-success criterion has fresh passing evidence.

Delete only the exact temporary payload files created for this run. Leave DevHub open unless the user asks otherwise or the prior state was closed.

## Report

Lead with the project name, DevHub ID/slug, and whether DevHub was restarted or rebuilt. List the saved path, build command, rules path, skills, version authority, Discord-ticket setting, and verification results. State any blank optional fields and why they were left blank.