squadrant 0.9.0

package/plugin/skills/command-ops/SKILL.md

@@ -0,0 +1,157 @@
+---
+name: command-ops
+description: Command playbook — invoked on-demand by `squadrant command [--task ...]`. Covers daily briefing, delegation workflow, project registration, status checking, and learnings review. Command is no longer always-on.
+---
+
+# Command Operations
+
+> **On-demand only.** Command is no longer launched by `squadrant launch --all`. You were spawned by `squadrant command --task <briefing|learnings-review|wiki-aggregate>` to run a single task and exit. Do the task, then exit cleanly — no persistent loop.
+
+## Daily Briefing (Session Start)
+
+Run when session starts, or user says "morning", "catch up", "summary":
+
+1. **Check handoffs from all projects** (context from yesterday's sessions):
+```bash
+for vault in $(cat ~/.config/squadrant/config.json | python3 -c "import json,sys; [print(p['spokeVault']) for p in json.loads(sys.stdin.read())['projects'].values()]"); do
+  echo "=== $(basename $vault) ==="
+  ~/.config/squadrant/scripts/read-handoff.sh "$vault" --keep
+done
+```
+Handoffs contain: currentState, openBranches, nextSteps, blockedItems, decisions. Use these to understand where each project left off.
+
+2. Search **claude-mem** (`mem-search` skill) for recent activity across all projects.
+3. Read yesterday's logs:
+```bash
+YESTERDAY=$(date -v-1d +"%Y-%m-%d")
+for vault in $(cat ~/.config/squadrant/config.json | python3 -c "import json,sys; [print(p['spokeVault']) for p in json.loads(sys.stdin.read())['projects'].values()]"); do
+  echo "=== $vault ==="
+  cat "$vault/daily-logs/${YESTERDAY}.md" 2>/dev/null || echo "(no log)"
+done
+```
+4. Read current status: `~/.config/squadrant/scripts/read-status.sh`
+5. Run quick standup for context: `squadrant standup --yesterday --raw`
+6. Present briefing, then save to `{hubVault}/daily-logs/YYYY-MM-DD.md`
+
+## Delegation Workflow
+
+When the user gives a task for a project:
+
+### 1. Identify project
+Match to `~/.config/squadrant/config.json`.
+
+### 2. Check for captain workspace
+```bash
+/Applications/cmux.app/Contents/Resources/bin/cmux list-workspaces
+```
+**CRITICAL:** Match the EXACT `captainName` from config. `Brove` ≠ `⚓ brove-captain`.
+
+### 3. Freshness gate (run BEFORE deciding to reuse)
+A name match is **not** sufficient — the workspace may be holding a session from a previous day. Check `sessions.json` against today before reusing:
+```bash
+TODAY=$(date +%Y-%m-%d)
+LAST=$(python3 -c "import json; d=json.load(open('$HOME/.config/squadrant/sessions.json')); print(d.get('workspaces',{}).get('{captainName}',{}).get('lastLaunched',''))" 2>/dev/null)
+[ "$LAST" = "$TODAY" ] && echo "fresh" || echo "stale"
+```
+- `fresh` → reuse the existing workspace, proceed to step 5.
+- `stale` (or no entry) → close the existing workspace, then go to step 4 to respawn so `spawn-workspace.sh` runs its `↻ new day — starting fresh session` path:
+  ```bash
+  /Applications/cmux.app/Contents/Resources/bin/cmux close-workspace --workspace "workspace:N"
+  ```
+
+Never skip this gate when a workspace was found by name — that's how stale captains get reused.
+
+### 4. Spawn captain (missing or stale)
+```bash
+~/.config/squadrant/scripts/spawn-workspace.sh "{captainName}" "{projectPath}"
+```
+Wait a few seconds, then `list-workspaces` again to get its ref. Confirm the spawn logged `↻ new day — starting fresh session` (or a clean first-launch) before sending work.
+
+### 5. Send the task
+```bash
+/Applications/cmux.app/Contents/Resources/bin/cmux send --workspace "workspace:N" "Task description with all context"
+/Applications/cmux.app/Contents/Resources/bin/cmux send-key --workspace "workspace:N" Enter
+```
+
+### 6. Report back
+"Delegated to {captainName}."
+
+## Checking Status
+
+```bash
+~/.config/squadrant/scripts/read-status.sh
+```
+Or read a captain's screen:
+```bash
+/Applications/cmux.app/Contents/Resources/bin/cmux read-screen --workspace "workspace:N"
+```
+
+## Registering Projects
+
+1. Explore directory: `find {path} -maxdepth 2 -name ".git" -type d`
+2. Identify primary repo (most active, main application)
+3. Identify siblings (docs, sites, forks)
+4. Register with groups:
+```bash
+squadrant projects add {name} {path/to/repo} --group {group}
+squadrant projects add {name}-docs {path/to/docs} --group {group} --group-role "documentation site"
+```
+5. Confirm with user. Always register the `.git` directory, not the parent.
+
+## Monitoring Captains
+
+Captains will send you reports via `cmux send` when tasks complete or blockers arise. When you receive a captain report:
+
+1. Acknowledge the report
+2. Update your dashboard / briefing notes
+3. If the captain reported a blocker — escalate to the user
+4. If all tasks for a project are done — inform the user
+
+You can also **proactively check** captain progress:
+```bash
+# Read all captain statuses at once
+for vault in $(cat ~/.config/squadrant/config.json | python3 -c "import json,sys; [print(p['spokeVault']) for p in json.loads(sys.stdin.read())['projects'].values()]"); do
+  echo "=== $(basename $vault) ==="
+  head -15 "$vault/status.md" 2>/dev/null || echo "(no status)"
+done
+```
+
+Do this when:
+- The user asks for a status update
+- A captain hasn't reported back in a while
+- Before your daily briefing
+
+## Reviewing Learnings
+
+1. Scan `{spokeVault}/learnings/*.md` where `applied: false`
+2. Group by category, identify cross-project patterns
+3. If same issue in 2+ projects → propose a **captured skill**
+4. If a skill keeps failing → propose a **fix**
+5. Propose specific changes to the user
+6. After approval, apply and mark `applied: true`
+
+## Wiki Aggregation (Hub Knowledge Base)
+
+Periodically review spoke wikis across all projects to build a cross-project knowledge base.
+
+### 1. Scan spoke wiki indexes
+```bash
+for vault in $(cat ~/.config/squadrant/config.json | python3 -c "import json,sys; [print(p['spokeVault']) for p in json.loads(sys.stdin.read())['projects'].values()]"); do
+  echo "=== $(basename $vault) ==="
+  cat "$vault/wiki/index.md" 2>/dev/null || echo "(no wiki)"
+done
+```
+
+### 2. Identify cross-project knowledge
+If a pattern appears in 2+ spoke wikis, create a hub-level wiki page that synthesizes both.
+
+### 3. Create hub wiki pages
+```bash
+~/.config/squadrant/scripts/wiki-ingest.sh "{hubVaultPath}" "{slug}" "{title}" "{category}" "{body}" "{tags}" "aggregated from spoke wikis"
+```
+
+### 4. Wiki health check
+During daily briefing, check for:
+- Projects with zero wiki pages (captains not compiling knowledge)
+- Stale wiki pages (not updated in 2+ weeks)
+- Missing cross-references between related pages

package/plugin/skills/config-doctor/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: config-doctor
+description: Reconcile squadrant config drift that needs human judgment — changed defaults and invalid values surfaced by `squadrant config check`. Use when the drift banner says "items need review" or the user asks to fix config drift.
+---
+
+# Config Doctor
+
+Reconcile the config-drift items that `squadrant config check --fix` deliberately does NOT auto-apply: `changed-default` (you may have customized on purpose) and `invalid` (a value that no longer resolves). The safe tier (missing/deprecated) is already handled by `--fix`; do not duplicate it.
+
+## Steps
+
+1. **Get structured drift:**
+   ```bash
+   squadrant config check --json
+   ```
+   This prints a `DriftItem[]`. Focus only on items with `kind` of `changed-default` or `invalid`.
+
+2. **Apply the safe tier first (if any missing/deprecated remain):**
+   ```bash
+   squadrant config check --fix
+   ```
+   Re-run `--json` afterward to see what judgment items remain.
+
+3. **For each `changed-default` item:**
+   - Show the user: `path`, their `current` value, the new `suggested` default, and the `note`.
+   - Ask: *adopt the new default, or keep your value?*
+   - If keep → no edit needed (it will be dismissed in step 5 via `--accept`).
+   - If adopt → edit `~/.config/squadrant/config.json`, setting `path` to `suggested`. Edit ONLY that path.
+
+4. **For each `invalid` item:**
+   - Explain why it's invalid (the `note` says, e.g. "unknown driver 'aider'").
+   - Propose the correct value (e.g. switch driver to `claude`/`codex`/`opencode`, or remove the dead agent).
+   - On confirmation, edit `~/.config/squadrant/config.json` for that path only. Never touch `projects`, `hubVault`, `commandName`, or other user-data sections.
+
+5. **Finalize:**
+   ```bash
+   squadrant config check          # confirm zero remaining drift
+   squadrant config check --accept # stamp the version so the banner goes quiet
+   ```
+   If `check` still shows items the user intentionally kept, `--accept` is the correct way to dismiss them.
+
+## Rules
+
+- Edit only the exact dotted paths flagged. One concern per edit.
+- Never auto-decide a `changed-default` — it is the user's call.
+- After reconciling, the stamp must equal the running squadrant version or the banner returns.

package/plugin/skills/daily-log/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: daily-log
+description: Write an end-of-day log to your spoke vault. Use when session ends or user says "end of day" / "wrap up".
+---
+
+# Daily Log
+
+Write a daily log before your session ends.
+
+## Setup
+
+```bash
+DATE=$(date +"%Y-%m-%d")
+SPOKE_VAULT="{spokeVaultPath}"
+mkdir -p "$SPOKE_VAULT/daily-logs"
+```
+
+## Write to `{spokeVaultPath}/daily-logs/YYYY-MM-DD.md`
+
+```markdown
+---
+date: YYYY-MM-DD
+project: {project-name}
+---
+
+# {project-name} — Daily Log
+
+## Completed
+- [tasks completed today]
+
+## In Progress
+- [tasks still being worked on]
+
+## Blocked
+- [anything stuck]
+
+## Key Decisions
+- [important decisions made today]
+
+## Tomorrow
+- [what should be picked up next]
+```
+
+This log is read by the command session to generate the morning briefing. Keep it concise — bullet points, not paragraphs.

package/plugin/skills/karpathy-principles/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: karpathy-principles
+description: Four coding principles derived from Andrej Karpathy's observations on LLM pitfalls. Use to reduce wrong assumptions, overengineering, drive-by refactors, and vague execution. Apply to every crew coding task and every captain review.
+---
+
+# Karpathy Coding Principles
+
+Derived from [Andrej Karpathy's observations](https://x.com/karpathy/status/2015883857489522876) on how LLMs fail at coding. Ported from [forrestchang/andrej-karpathy-skills](https://github.com/forrestchang/andrej-karpathy-skills) (MIT).
+
+These four principles apply to every coding task — whether you are a captain reviewing a crew's work or a crew member writing code.
+
+## 1. Think Before Coding
+
+**Don't assume. Don't hide confusion. Surface tradeoffs.**
+
+- State assumptions explicitly — if uncertain, ask rather than guess
+- Present multiple interpretations when ambiguity exists — don't pick silently
+- Push back when warranted — if a simpler approach exists, say so
+- Stop when confused — name what's unclear and ask
+
+## 2. Simplicity First
+
+**Minimum code that solves the problem. Nothing speculative.**
+
+- No features beyond what was asked
+- No abstractions for single-use code
+- No "flexibility" or "configurability" that wasn't requested
+- No error handling for impossible scenarios
+- If 200 lines could be 50, rewrite
+
+**Test:** Would a senior engineer call this overcomplicated? If yes, simplify.
+
+## 3. Surgical Changes
+
+**Touch only what you must. Clean up only your own mess.**
+
+- Don't improve adjacent code, comments, or formatting
+- Don't refactor things that aren't broken
+- Match existing style, even if you'd do it differently
+- If you notice unrelated dead code, **mention** it — don't delete it
+
+When your changes create orphans:
+- Remove imports/variables/functions that **your changes** made unused
+- Don't remove pre-existing dead code unless asked
+
+**Test:** Every changed line should trace directly to the user's request.
+
+## 4. Goal-Driven Execution
+
+**Define success criteria. Loop until verified.**
+
+Transform imperative tasks into verifiable goals:
+
+| Instead of... | Transform to... |
+|---|---|
+| "Add validation" | "Write tests for invalid inputs, then make them pass" |
+| "Fix the bug" | "Write a test that reproduces it, then make it pass" |
+| "Refactor X" | "Ensure tests pass before and after" |
+
+For multi-step tasks, state a brief plan with per-step verification:
+
+```
+1. [Step] → verify: [check]
+2. [Step] → verify: [check]
+```
+
+Strong success criteria let the agent loop independently. Weak criteria ("make it work") force constant clarification.
+
+## Tradeoff
+
+These principles bias toward **caution over speed**. For trivial tasks (typo fixes, obvious one-liners) use judgment — not every change needs the full rigor. The goal is reducing costly mistakes on non-trivial work, not slowing down simple tasks.
+
+## Squadrant-specific notes
+
+- Squadrant already uses TDD via the `superpowers:test-driven-development` skill — principle 4 complements it, does not replace it
+- Captains applying these principles during review: if a crew member violates principle 3 (drive-by refactors), request they split the commit
+- Crew should report blockers in status.md when principle 1 triggers ("unclear" / "multiple interpretations")
+
+## Attribution
+
+- Original principles: [Andrej Karpathy on X](https://x.com/karpathy/status/2015883857489522876)
+- Packaging: [forrestchang/andrej-karpathy-skills](https://github.com/forrestchang/andrej-karpathy-skills) (MIT)

package/plugin/skills/set-effort/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: set-effort
+description: Read or set the global crew tokenomics dial (max | balance | low). Use when the user wants to change how aggressively crews consume tokens, or to check the current setting.
+---
+
+# squadrant:set-effort — Global Crew Effort Dial
+
+The effort dial is a one-field toggle in `~/.config/squadrant/config.json` that biases the captain's crew spawning decisions. It does **not** rewrite routing rules — it is a hint the captain honors when choosing agent/model for new crews.
+
+## Modes
+
+| Mode | Meaning |
+|------|---------|
+| **max** | Tokens are plentiful. Prefer claude/opus for crew spawns; don't downshift for cost. |
+| **balance** | Normal. Use default crew routing rules unchanged. (Default when field is absent.) |
+| **low** | Conserve tokens. Prefer opencode/sonnet for crews; reserve opus for work that genuinely needs it. |
+
+## Get current effort
+
+```bash
+squadrant effort
+```
+
+Prints the current mode and its one-line meaning. Does not write anything.
+
+## Set effort
+
+```bash
+squadrant effort max
+squadrant effort balance
+squadrant effort low
+```
+
+- Validates the value (errors with the 3 valid options if invalid).
+- Writes `defaults.effort` via the existing `saveConfig` atomic path.
+- Prints a confirmation line.
+- Best-effort: sends a one-line notice to any running captain workspace so a live session adjusts immediately. If no captain is running, the change applies on next launch.
+
+## Manual edit (fallback)
+
+If the CLI is unavailable, edit `~/.config/squadrant/config.json` directly:
+
+```json
+{
+  "defaults": {
+    "effort": "low"
+  }
+}
+```
+
+Valid values: `"max"` | `"balance"` | `"low"`. Absent field is equivalent to `"balance"`.
+
+## Scope
+
+Effort is **crew-only**. It does not affect captain, command, or side roles — those stay pinned to their configured model regardless of effort.
+
+## Precedence
+
+Effort is the weakest signal. Explicit `--agent` / `--model` flags on `squadrant crew spawn` always win. Effort only biases the captain's default choice when nothing more specific applies.

package/plugin/skills/side-session/SKILL.md

@@ -0,0 +1,113 @@
+---
+name: side-session
+description: Spawn and manage side-sessions (research/debug) — dedicated fresh-context tabs off the captain's daemon lifecycle. Use when you want to research a topic, discuss an idea, or debug without polluting captain context.
+---
+
+# Side-Sessions
+
+A side-session is a dedicated tab with **fresh context** running the captain model (opus), loaded with a role-specific template. It runs **outside the crew/daemon lifecycle** — no `CREW IDLE/DONE` noise back to the primary captain. Its only upward signal is an explicit, user-confirmed structured handoff.
+
+## Spawn a side-session
+
+```bash
+# Research a topic, discuss an idea, produce a spec or GH issue
+squadrant side spawn <project> "<topic>" --role research
+
+# Debug a bug in an isolated scratch worktree
+squadrant side spawn <project> "<topic>" --role debug
+```
+
+Options:
+- `--name <name>` — custom tab name (default: auto `side-N`)
+- `--direction <tab|right|down|left|up>` — placement (default: tab)
+- `--agent <claude|opencode>` — agent to use (default: claude)
+- `--topic-file <path>` — read topic from a file
+
+## Manage side-sessions
+
+```bash
+squadrant side list <project>                               # see live side tabs
+squadrant side send <project> <name> "<follow-up>"          # send a follow-up turn
+squadrant side close <project> <name>                       # close when done
+```
+
+## Role: research
+
+**Can:** Read code/docs, run read-only commands, create GH issues, write specs/plans.
+**Cannot:** Edit source code, spawn crews, merge/ship changes.
+
+The session works in fresh context and produces artifacts (specs, GH issues, analysis). When done, it asks the user to confirm before sending a structured handoff to the primary captain.
+
+## Role: debug
+
+**Can:** Read code/docs, run code and tests, edit source — but **scratch only** in its isolated worktree (instrumentation, logging, a failing test to pinpoint the root cause).
+**Cannot:** Edit source outside the scratch worktree, spawn crews, merge/ship changes.
+
+The debug role creates an isolated scratch git worktree on spawn. Edits made there are never shipped — the draft patch lives on the scratch branch and is referenced in the handoff for a crew to implement cleanly. Close prunes the scratch worktree.
+
+### Bug intake (required first step)
+
+Before instrumenting, the debug session gathers from the user:
+1. Repro steps
+2. When/where the bug appears
+3. Expected vs actual behavior
+4. Recent changes that could be related
+
+If the topic already contains all of this, it confirms and proceeds. Otherwise it asks.
+
+## Handoff workflow
+
+```
+1. Side session produces a result (root cause / artifact).
+2. Session asks: "Notify the primary captain now? (y/n)"
+3. On yes:
+   - Writes durable record: {spokeVault}/side-handoffs/<topic>.md
+   - Sends: squadrant runtime send <project> "🗒 Side handoff [<role>] — <topic> ..."
+4. Primary captain receives handoff delivered daemon-direct via cmux (#332).
+5. Captain does NOT auto-spawn a crew — waits for user's go.
+```
+
+### Structured handoff format (research)
+
+```
+🗒 Side handoff [research] — <topic>
+Summary: <one-line summary>
+Artifacts: <gh issue #NNN | spec: path/to/file.md | …>
+Next: <recommended next action>
+```
+
+### Structured handoff format (debug)
+
+```
+🗒 Side handoff [debug] — <topic>
+Root cause: <one-line root cause>
+Artifacts: <failing test path | instrumentation: <file> | draft patch: scratch branch crew/<name> | issue #NNN>
+Next: <what a crew should implement to fix this>
+```
+
+## Spawn by the primary captain
+
+When the user asks you to start a side session, spawn one:
+
+```bash
+# Research
+squadrant side spawn <project> "<the research question or topic>" --role research
+
+# Debug — creates a scratch worktree; pruned automatically on close
+squadrant side spawn <project> "<the bug description>" --role debug
+```
+
+Note the session name from the output (e.g. `side-1`) and tell the user they can steer it with:
+
+```bash
+squadrant side send <project> side-1 "<follow-up>"
+squadrant side close <project> side-1
+```
+
+When the session completes, its handoff is delivered daemon-direct via cmux (#332) with the `🗒 Side handoff` prefix.
+
+## Key invariants
+
+`squadrant side spawn` does **NOT** create a daemon task record. There is no `CREW IDLE/DONE` event for side-sessions. The only signal path is the explicit `squadrant runtime send` the side-session sends on user confirmation.
+
+`squadrant side close` on a debug session automatically prunes its scratch worktree (the branch is preserved so the draft patch survives).

package/plugin/skills/squadrant-effort/SKILL.md

@@ -0,0 +1,8 @@
+---
+name: squadrant-effort
+description: Shortcut for squadrant:set-effort — get or set the global crew tokenomics dial (max | balance | low). Use when the user types /squadrant-effort or asks about the effort setting.
+---
+
+# squadrant-effort — shortcut for squadrant:set-effort
+
+Shorthand alias. **Invoke the `set-effort` skill** (via the Skill tool) and follow it exactly. All logic lives there — this file intentionally holds none, so the two never drift.

package/plugin/skills/squadrant-new-project/SKILL.md

@@ -0,0 +1,67 @@
+---
+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
+
+```bash
+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:
+```bash
+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
+
+```bash
+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
+
+```bash
+squadrant projects list
+```
+
+Confirm the new entry appears with the correct path, group, and role.

package/plugin/skills/squadrant-register-project/SKILL.md

@@ -0,0 +1,60 @@
+---
+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:
+```bash
+gh repo clone <org>/<repo> <dest-path>
+```
+
+## Step 2 — Determine the project name
+
+Default to the directory name:
+```bash
+basename <path>
+```
+
+Override if the directory name is ambiguous (e.g. `src`, `app`).
+
+## Step 3 — Determine group placement
+
+List existing projects and their groups:
+```bash
+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
+
+```bash
+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
+
+```bash
+squadrant projects list
+```
+
+Confirm the new entry appears with the correct path, group, and role.