| name | squadrant-register-project |
| description | Register an existing local repo (or GitHub URL) into squadrant config. Use when a project already exists and just needs to be wired into squadrant. |
Register an Existing Project
Use when the repo already exists locally or on GitHub and you just need to register it in squadrant.
Step 1 — Resolve the local path
Local path given: use it directly.
GitHub URL given: clone first, then use the destination:
gh repo clone <org>/<repo> <dest-path>
Step 2 — Determine the project name
Default to the directory name:
basename <path>
Override if the directory name is ambiguous (e.g. src, app).
Step 3 — Determine group placement
List existing projects and their groups:
squadrant projects list
Then decide:
New group — pick a group name (kebab-case). This project will be primary automatically (first in group). No --group-role needed.
Existing group — pick the group name and specify a role that describes this project's purpose (e.g. "documentation site", "agent task queue", "shared skills library"). The role must NOT be "primary" — that slot is already taken by the first project in the group.
Note: --group-role only auto-sets to "primary" when it is the first project registered in a group. All subsequent projects in the same group require an explicit --group-role.
Step 4 — Register
squadrant projects add <name> <path> \
--captain "⚓ <name>-captain" \
[--group <group-name>] \
[--group-role "<role description>"]
Omit --group and --group-role entirely if this is a standalone project with no group.
Step 5 — Verify
squadrant projects list
Confirm the new entry appears with the correct path, group, and role.
