squadrant-new-project

name	squadrant-new-project
description	Create a brand-new GitHub repo, clone it, and register it in squadrant. Handles both new workspace (new group) and existing workspace (join existing group).

Create and Register a New Project

Use when the project does not exist yet — you need to create the GitHub repo, clone it locally, and wire it into squadrant.

Step 1 — Collect inputs

You need:

• Repo name (kebab-case, e.g. my-project)
• GitHub org or user (e.g. Quantum3-Labs or your GitHub username)
• Visibility — public or private
• Local parent directory — where to clone into (e.g. /Users/you/Q3/MyGroup/)

Step 2 — Determine workspace placement

New workspace (no existing group):

• Pick a group name (kebab-case). This project will be primary automatically.
• No --group-role needed.

Existing workspace (joining an existing group):

• Run squadrant projects list to see current groups.
• Pick the group to join and specify a role for this project (e.g. "landing page", "mobile client", "CLI tool").
• The role must NOT be "primary" — that slot is already taken.

Step 3 — Create the GitHub repo and clone

gh repo create <org>/<repo-name> --[public|private] --clone --clone-dir <parent-dir>

This creates the repo on GitHub and clones it into <parent-dir>/<repo-name>.

Step 4 — Optional: initial scaffold

If the repo should start with a README and first commit:

cd <parent-dir>/<repo-name>
echo "# <repo-name>" > README.md
git add README.md
git commit -m "chore: initial commit"
git push

Skip if the repo already has content or the user wants to scaffold separately.

Step 5 — Register in squadrant

squadrant projects add <repo-name> <parent-dir>/<repo-name> \
  --captain "⚓ <repo-name>-captain" \
  [--group <group-name>] \
  [--group-role "<role description>"]

Omit --group and --group-role for a standalone project with no group.

Step 6 — Verify

squadrant projects list

Confirm the new entry appears with the correct path, group, and role.