codebyplan 1.5.1 → 1.9.0

package/templates/skills/cbp-git-commit/SKILL.md

@@ -0,0 +1,278 @@
+---
+scope: org-shared
+name: cbp-git-commit
+description: Create scoped commit with conventional format
+argument-hint: "[--task|--all] [type]: [description]"
+effort: low
+---
+
+# Git Commit Command
+
+Create a commit using conventional commits format, then push to origin.
+
+## When to Use
+
+- Called by `/cbp-session-end` after files are staged
+- Direct use when user provides explicit commit message
+
+## Arguments
+
+`$ARGUMENTS`: [options] [type]: [description]
+
+**Scope Flags (one optional):**
+- `--task` - Commit all staged files (semantic: task context)
+- `--all` - Commit all staged files (explicit, same as no scope flag)
+- `--scope-task` - Commit ONLY files in the active task's `files_changed[]` (intersected with currently-staged files); leaves foreign-staged files alone
+
+**Other Options:**
+- `--files [file1] [file2] ...` - **Manual override**: commit ONLY these specific files
+- `--no-push` - Skip push to remote
+
+**Scope Flag Behavior:**
+
+| Flag | File Source | Use Case |
+|------|-------------|----------|
+| `--task` | All staged files | `/cbp-task-complete` |
+| `--all` | All staged files | Explicit full commit |
+| `--scope-task` | Intersection of `task.files_changed[].path` and `git diff --cached --name-only` | Foreign-staged files exist alongside task work; user wants to commit only the task's files in this commit |
+| (none) | All staged files | Default behavior |
+
+When a scope flag is used:
+- All staged files are committed (except `--scope-task`, which intersects with task files)
+- Semantic distinction only (for context in calling commands)
+
+**`--scope-task` Behavior:**
+
+When `--scope-task` is used:
+1. Read `task.files_changed[].path` via MCP `get_current_task`
+2. Read currently-staged files via `git diff --cached --name-only`
+3. Compute intersection — only those paths are committed
+4. Foreign-staged files (in staged set but NOT in task) remain staged after the commit; user handles them in a separate commit
+5. If intersection is empty → error "No staged files belong to TASK-N. Either use --all to commit foreign-staged files, or stage task files first."
+
+This is the right scope flag when `git status` shows foreign-staged batches alongside task work (e.g., a parallel `.claude/` sync staged simultaneously with TASK-N's work) and the commit narrative belongs to the task only.
+
+**Manual Override: --files**
+
+When `--files` is used (overrides scope flags):
+- Only the specified files are committed
+- Other staged files remain staged (not committed)
+- Specified files MUST be staged, otherwise error
+- This enables manual control when scoped flags don't fit
+
+**Message formats:**
+- `[type]: [description]`
+- `[type](scope): [description]`
+
+**Examples:**
+- `feat: add user authentication` - Commit all staged, auto-push
+- `--task feat(CHK-022): complete TASK-1` - Commit all staged in task context
+- `--all fix(api): resolve timeout` - Explicit all-staged commit
+- `--files path/to/file.md feat: add feature` - Manual specific file
+- `--no-push chore: update deps` - Commit without pushing
+
+If no message provided, analyze staged changes and generate message automatically.
+
+## Instructions
+
+### Step 1: Determine Repo Path
+
+**CRITICAL**: The shell working directory may not match the session's repo.
+
+Determine repo path from session context:
+
+The repo path is the current working directory root:
+
+```bash
+REPO_PATH="$(git rev-parse --show-toplevel)"
+```
+
+### Step 2: Parse Scope and Options
+
+**Parse `$ARGUMENTS` for flags:**
+
+1. **Check for scope flag** (mutually exclusive):
+   - `--task` -> scope = "task" (commits all staged)
+   - `--all` -> scope = "all"
+   - `--scope-task` -> scope = "scope-task" (intersection of task.files_changed[] and staged)
+   - (none) -> scope = "all" (default)
+
+2. **Check for --files** (overrides scope):
+   - If `--files` present -> use manual file list, ignore scope
+
+3. **Check for --no-push**
+
+4. **Extract commit message** (remaining arguments after flags)
+
+### Step 2a: Collect Files (if --files or --scope-task used)
+
+**If `--files` provided:** Use the manual file list.
+
+**If `--scope-task`:** Resolve via MCP + intersection.
+
+```bash
+# 1. Read task.files_changed[]
+task_paths=$(mcp get_current_task | jq -r '.files_changed[].path')
+# 2. Read staged paths
+staged_paths=$(git diff --cached --name-only)
+# 3. Compute intersection
+intersect=$(comm -12 <(echo "$task_paths" | sort) <(echo "$staged_paths" | sort))
+```
+
+If `intersect` is empty: emit error and STOP.
+
+```
+## Error: No Task Files Staged
+
+Scope: --scope-task
+TASK-N has [M] files in files_changed[]; none are currently staged.
+
+Options:
+- Stage task files: git add [path1] [path2] ...
+- Or use --all to commit the foreign-staged files instead.
+```
+
+If non-empty: use `intersect` as the file list for Step 5.
+
+**If `--task`, `--all`, or no scope:** No filtering — all staged files committed.
+
+### Step 3: Check Staged Changes
+
+```bash
+cd "$REPO_PATH" && git diff --cached --name-only
+```
+
+**If nothing staged:**
+- Show "No changes to commit."
+- Stop here.
+
+### Step 4: Analyze Changes (if no message)
+
+If no commit message provided:
+1. Read staged file diffs
+2. Determine commit type:
+   - New files with features -> `feat`
+   - Bug fixes -> `fix`
+   - Config/deps changes -> `chore`
+   - Documentation -> `docs`
+   - Refactoring -> `refactor`
+3. Generate message automatically
+
+### Step 4a: Verify Manual Files Are Staged
+
+**If `--files`:** Verify each specified file is staged.
+
+```bash
+cd "$REPO_PATH" && git diff --cached --name-only
+```
+
+**If any specified files not staged:** Show error with missing files list and STOP.
+
+**If `--task`, `--all`, or no scope:** Skip verification, use all staged.
+
+### Step 5: Create Commit
+
+**For `--scope-task`:** commit only the intersection list from Step 2a:
+
+```bash
+cd "$REPO_PATH" && git commit [intersect-file1] [intersect-file2] ... -m "$(cat <<'EOF'
+[type]: [description]
+EOF
+)"
+```
+
+Foreign-staged files remain in the index (not committed). The commit attribution covers only TASK-N's files.
+
+**Determine commit mode:**
+
+| Scope | Commit Command |
+|-------|----------------|
+| `--files [list]` | `git commit [file1] [file2] ...` |
+| `--task` | `git commit` (all staged) |
+| `--all` or (none) | `git commit` (all staged) |
+
+**If --files (manual file list):**
+
+Commit ONLY the specified files:
+
+```bash
+cd "$REPO_PATH" && git commit [file1] [file2] ... -m "$(cat <<'EOF'
+[type]: [description]
+EOF
+)"
+```
+
+**If --task, --all, or no scope (commit all staged):**
+
+```bash
+cd "$REPO_PATH" && git commit -m "$(cat <<'EOF'
+[type]: [description]
+EOF
+)"
+```
+
+### Step 6: Push to Remote
+
+**If `--no-push` option provided:**
+- Skip this step
+- Show "Push skipped (--no-push)"
+
+**Otherwise:** push the current branch to origin.
+
+```bash
+cd "$REPO_PATH" && BRANCH=$(git rev-parse --abbrev-ref HEAD) && git push origin "$BRANCH"
+```
+
+**If push fails with "no upstream":** retry with `-u`.
+
+```bash
+cd "$REPO_PATH" && git push -u origin "$BRANCH"
+```
+
+**If push fails because remote is ahead:** report to user and stop — do not auto-pull. User resolves by running `git pull --rebase origin "$BRANCH"` and retrying.
+
+### Step 7: Show Result
+
+Display output per Output Format section below.
+
+## Output Format
+
+**Standard commit (all staged):**
+```
+**Committed**: [short-hash]
+**Message**: [type]: [description]
+**Scope**: [--task / --all / --files]
+**Files**: N files changed
+**Pushed**: origin/[branch-name]
+```
+
+**If no changes to commit:**
+```
+No changes to commit.
+```
+
+**If manual files not staged:**
+```
+## Error: Files Not Staged
+
+Scope: --files
+Missing: [N] files not staged
+
+Stage the missing files or use --all.
+```
+
+## Integration
+
+- **Called by**: `/cbp-session-end`, `/cbp-task-complete`, `/cbp-checkpoint-complete`, manual
+- **Scope usage by commands**:
+  - `/cbp-task-complete` -> `--no-push` (commit all staged)
+  - `/cbp-checkpoint-complete` -> no scope needed
+  - `/cbp-session-end` -> `--all` or no scope (commit all staged)
+- **Rules**: `/.claude/rules/git-workflow.md`
+
+## Key Points
+
+1. **Simplified scopes** - `--task` and `--all` both commit all staged files
+2. **Manual override** - `--files` takes precedence over scope flags
+3. **Verification** - Only `--files` needs staged verification
+4. **Default is --all** - No scope flag = commit all staged (backward compatible)

package/templates/skills/cbp-git-worktree-create/SKILL.md

@@ -0,0 +1,226 @@
+---
+scope: org-shared
+name: cbp-git-worktree-create
+description: Create git worktree with clean command setup and register in CodeByPlan
+argument-hint: <branch-name> e.g. codebyplan-app
+effort: low
+---
+
+# Git Worktree Create
+
+Create a git worktree as a sibling folder and register it in CodeByPlan. The worktree gets its own full copy of `.claude/` files on disk (rules, skills, hooks, agents, context) — git deduplicates at the object level so there's no real cost.
+
+## Arguments
+
+`$ARGUMENTS`: branch name — becomes both the branch name and the folder name.
+
+Examples:
+- `codebyplan-app` → folder `../codebyplan-app/`, branch `codebyplan-app`
+- `codebyplan-package` → folder `../codebyplan-package/`, branch `codebyplan-package`
+
+## Prerequisites
+
+- Must run from the **main repo** (the non-worktree checkout)
+- Working tree should be clean
+- Branch should not already exist as a worktree
+
+## Instructions
+
+### Step 1: Verify Main Repo
+
+```bash
+MAIN_REPO="$(git rev-parse --show-toplevel)"
+```
+
+Verify this is the main repo (not itself a worktree):
+
+```bash
+git rev-parse --git-dir
+```
+
+If the result is a file (not `.git` directory), this is already a worktree. Stop:
+
+```
+## Error
+
+Run this command from the main repo, not from a worktree.
+Main repo: [path from git-common-dir parent]
+```
+
+### Step 2: Validate Arguments
+
+If `$ARGUMENTS` is empty, ask the user:
+
+```
+What should the worktree be called? (e.g. codebyplan-app)
+```
+
+Set:
+- `BRANCH_NAME` = `$ARGUMENTS`
+- `WORKTREE_PATH` = `$MAIN_REPO/../$BRANCH_NAME`
+
+### Step 3: Check for Conflicts
+
+Check if the worktree already exists:
+
+```bash
+git worktree list | grep "$BRANCH_NAME"
+```
+
+If it exists:
+```
+## Worktree Already Exists
+
+Branch `[name]` is already checked out at [path].
+
+Use `/cbp-git-worktree-remove [name]` to remove it first.
+```
+Stop here.
+
+Check if the folder already exists:
+
+```bash
+ls -d "$WORKTREE_PATH" 2>/dev/null
+```
+
+If it exists, stop and inform the user.
+
+### Step 4: Create Branch If Needed
+
+Check if branch exists:
+
+```bash
+git branch --list "$BRANCH_NAME"
+```
+
+If branch does NOT exist, create it from current HEAD:
+
+```bash
+git branch "$BRANCH_NAME"
+```
+
+### Step 5: Create Worktree
+
+```bash
+git worktree add "$WORKTREE_PATH" "$BRANCH_NAME"
+```
+
+### Step 6: Set Up MCP Connection
+
+Copy `.mcp.json` from the main repo to the worktree. The config points at the remote MCP endpoint (`https://codebyplan.com/mcp`) and reads the API key from the environment, so no path rewriting is needed:
+
+```bash
+cp "$MAIN_REPO/.mcp.json" "$WORKTREE_PATH/.mcp.json"
+```
+
+Expected shape (do NOT rewrite paths — this is remote HTTP):
+
+```json
+{
+  "mcpServers": {
+    "codebyplan": {
+      "url": "https://codebyplan.com/mcp",
+      "headers": {
+        "x-api-key": "${CODEBYPLAN_API_KEY}"
+      }
+    }
+  }
+}
+```
+
+### Step 7: Set Up Environment
+
+Copy `.env.local` from the main repo to the worktree (contains `CODEBYPLAN_API_KEY` and any other local env):
+
+```bash
+cp "$MAIN_REPO/.env.local" "$WORKTREE_PATH/.env.local"
+```
+
+Verify `.env.local` is already in `.gitignore` (it should be via `.env.local` pattern). If not, add it.
+
+### Step 8: Push Branch
+
+```bash
+cd "$WORKTREE_PATH" && git push -u origin "$BRANCH_NAME"
+```
+
+### Step 9: Register Worktree in CodeByPlan
+
+Get the repo ID from CLAUDE.md (`Repo ID` in Key References table).
+
+Use MCP `create_worktree` to register the worktree in the CodeByPlan database:
+
+```
+MCP create_worktree:
+  repo_id: [repo-id from CLAUDE.md]
+  name: $BRANCH_NAME
+  path: $WORKTREE_PATH
+  status: "active"
+```
+
+Save the returned `worktree_id` for reference.
+
+### Step 10: Write `.codebyplan/` directory
+
+Create the `.codebyplan/` directory in the worktree root and write per-concern config stubs:
+
+```bash
+mkdir -p "$WORKTREE_PATH/.codebyplan"
+```
+
+Write `.codebyplan/repo.json` with the correct `repo_id`:
+
+```json
+{
+  "repo_id": "[repo-id from CLAUDE.md]"
+}
+```
+
+Write stubs for the other per-concern files (populated by `npx codebyplan sync` on first run):
+
+```bash
+# .codebyplan/server.json — server port and type config
+echo '{}' > "$WORKTREE_PATH/.codebyplan/server.json"
+
+# .codebyplan/git.json — branch config
+echo '{}' > "$WORKTREE_PATH/.codebyplan/git.json"
+
+# .codebyplan/shipment.json — surface shipment config
+echo '{}' > "$WORKTREE_PATH/.codebyplan/shipment.json"
+
+# .codebyplan/vendor.json — vendor docs path
+echo '{}' > "$WORKTREE_PATH/.codebyplan/vendor.json"
+```
+
+The `.codebyplan/device.local.json` file is created by `npx codebyplan setup` on the device (gitignored). The `worktree_id` is never persisted in any of these files — it is resolved at runtime via `npx codebyplan resolve-worktree` based on the device_id, filesystem path, and current git branch.
+
+No need to mark as `skip-worktree` — the committed files are merge-safe per CHK-108 and CHK-120.
+
+### Step 11: Show Result
+
+```
+## Worktree Created
+
+**Branch**: [branch-name]
+**Path**: [worktree-path]
+**Main repo**: [main-repo-path]
+**CodeByPlan**: Registered (worktree ID: [id])
+
+### Setup
+- MCP: connected (remote endpoint)
+- API key: copied from main repo `.env.local`
+- `.claude/` files: full copy on disk (rules, skills, hooks, agents, context)
+
+### Next Steps
+- Open `[worktree-path]` in your editor
+- Run `/cbp-session-start` to begin working
+- Checkpoints can be assigned to this worktree via `worktree_id`
+
+### Existing Worktrees
+[output of git worktree list]
+```
+
+## Integration
+
+- **Related**: `/cbp-git-worktree-remove` (cleanup and deregister)
+- **MCP tools**: `create_worktree`

package/templates/skills/cbp-git-worktree-remove/SKILL.md

@@ -0,0 +1,145 @@
+---
+scope: org-shared
+name: cbp-git-worktree-remove
+description: Remove git worktree and deregister from CodeByPlan
+argument-hint: <name> e.g. codebyplan-app
+effort: low
+---
+
+# Git Worktree Remove
+
+Remove a git worktree folder, deregister it from CodeByPlan, and optionally delete its branch.
+
+## Arguments
+
+`$ARGUMENTS`: worktree name or path to remove.
+
+## Prerequisites
+
+- Must run from the **main repo** (not from the worktree being removed)
+
+## Instructions
+
+### Step 1: Verify Main Repo
+
+```bash
+MAIN_REPO="$(git rev-parse --show-toplevel)"
+```
+
+Verify not in a worktree (`.git` should be a directory, not a file).
+
+### Step 2: List Worktrees
+
+```bash
+git worktree list
+```
+
+If `$ARGUMENTS` is empty, show the list and ask which to remove.
+
+### Step 3: Resolve Worktree
+
+Find matching worktree from the list. Match by:
+1. Exact path
+2. Folder name (e.g. `codebyplan-app`)
+3. Branch name
+
+If no match found, show available worktrees and stop.
+
+Set:
+- `WORKTREE_PATH` = resolved path
+- `BRANCH_NAME` = branch checked out in that worktree
+
+### Step 4: Look Up Worktree in CodeByPlan
+
+Get the repo ID from CLAUDE.md (`Repo ID` in Key References table).
+
+Use MCP `get_worktrees` to find the worktree record:
+
+```
+MCP get_worktrees:
+  repo_id: [repo-id from CLAUDE.md]
+  status: "active"
+```
+
+Match by `name` = `$BRANCH_NAME` or `path` = `$WORKTREE_PATH`.
+
+Set `WORKTREE_ID` = matched worktree's `id`.
+
+If not found in CodeByPlan, note it and continue with local removal.
+
+### Step 5: Check for Assigned Checkpoints
+
+If `WORKTREE_ID` was found, warn if any checkpoints are assigned to this worktree:
+
+```
+⚠ This worktree has [N] checkpoint(s) assigned. They will become unassigned.
+```
+
+### Step 6: Confirm with User
+
+```
+## Remove Worktree
+
+**Path**: [worktree-path]
+**Branch**: [branch-name]
+**CodeByPlan**: [registered | not registered]
+
+Remove worktree and delete the branch? (The main repo is not affected)
+```
+
+Ask:
+1. Remove worktree only (keep branch)
+2. Remove worktree and delete branch
+3. Cancel
+
+### Step 7: Deregister from CodeByPlan
+
+If `WORKTREE_ID` was found, delete the worktree record:
+
+```
+MCP delete_worktree:
+  worktree_id: [worktree-id]
+```
+
+### Step 8: Remove Git Worktree
+
+```bash
+git worktree remove "$WORKTREE_PATH"
+```
+
+If force needed (uncommitted changes):
+```bash
+git worktree remove --force "$WORKTREE_PATH"
+```
+
+Only use `--force` if the user confirms.
+
+### Step 9: Delete Branch (if requested)
+
+**Protected branch check:** If `$BRANCH_NAME` is `main`, `development`, or `preview` — refuse deletion and stop.
+
+**Checkpoint verification:** Before deleting a feat branch, verify that the associated checkpoint has completed via `/cbp-checkpoint-end`. If the checkpoint is still active, warn the user that unshipped work may be lost.
+
+```bash
+git branch -d "$BRANCH_NAME" && git push origin --delete "$BRANCH_NAME"
+```
+
+Use `-d` (not `-D`) to prevent deleting unmerged work. If it fails because the branch is not fully merged, inform the user and ask if they want to force delete with `-D`.
+
+### Step 10: Show Result
+
+```
+## Worktree Removed
+
+**Removed**: [worktree-path]
+**Branch**: [deleted | kept]
+**CodeByPlan**: [deregistered | was not registered]
+
+### Remaining Worktrees
+[output of git worktree list]
+```
+
+## Integration
+
+- **Related**: `/cbp-git-worktree-create` (create and register)
+- **MCP tools**: `get_worktrees`, `delete_worktree`