Initial commit

commands/adopt.md

@@ -0,0 +1,758 @@
+---
+description: Add .ai-context.json metadata to an existing worktree
+argument-hint: [--mode <mode>] [--description "<text>"]
+allowed-tools: Bash, Write, Read
+model: sonnet
+---
+
+# /adopt:working-tree
+
+Generate `.ai-context.json` and `README.working-tree.md` for existing worktree lacking metadata.
+
+## ARGUMENT SPECIFICATION
+
+```
+SYNTAX: /adopt:working-tree [--mode <mode>] [--description "<text>"]
+
+OPTIONAL:
+  --mode <mode>
+    Type: enum[main, feature, bugfix, experiment, review]
+    Default: inferred from branch-name (see MODE_INFERENCE_ALGORITHM)
+    Validation: must match exactly one of the enum values
+
+  --description "<text>"
+    Type: string (quoted if contains spaces)
+    Default: "" (empty string)
+    Validation: any string, no restrictions
+```
+
+## MODE_INFERENCE_ALGORITHM
+
+APPLY rules sequentially, first match wins:
+
+```python
+def infer_mode(branch_name: str) -> str:
+    if branch_name.startswith("feature/"):
+        return "feature"
+    elif branch_name.startswith(("bugfix/", "fix/")):
+        return "bugfix"
+    elif branch_name.startswith(("exp/", "experiment/")):
+        return "experiment"
+    elif branch_name.startswith("review/"):
+        return "review"
+    elif branch_name in ("main", "master"):
+        return "main"
+    else:
+        return "feature"  # DEFAULT
+```
+
+DETERMINISTIC: Given same branch_name, always produces same mode.
+
+## EXECUTION PROTOCOL
+
+Execute steps sequentially. Each step must complete successfully before proceeding.
+
+### STEP 1: DETECT REPOSITORY INFO
+
+EXECUTE:
+```bash
+REPO_ROOT=$(git rev-parse --show-toplevel 2>&1)
+EXIT_CODE_ROOT=$?
+CURRENT_BRANCH=$(git rev-parse --abbrev-ref HEAD 2>&1)
+EXIT_CODE_BRANCH=$?
+```
+
+VALIDATION:
+- IF EXIT_CODE_ROOT != 0 → ERROR PATTERN "not-in-git-repo"
+- IF EXIT_CODE_BRANCH != 0 → ERROR PATTERN "git-command-failed"
+- REPO_ROOT must be absolute path starting with /
+
+DATA EXTRACTION:
+```bash
+WORKTREE_NAME=$(basename "$REPO_ROOT")
+```
+
+NEXT:
+- On success → STEP 2
+- On failure → ABORT
+
+### STEP 2: CHECK EXISTING METADATA
+
+EXECUTE:
+```bash
+METADATA_PATH="$REPO_ROOT/.ai-context.json"
+test -f "$METADATA_PATH"
+EXISTS=$?
+```
+
+VALIDATION:
+- EXISTS is 0 (exists) or 1 (does not exist)
+
+ACTION:
+- IF EXISTS == 0 → STEP 3 (check for overwrite)
+- IF EXISTS == 1 → STEP 4 (proceed with creation)
+
+NEXT:
+- Conditional based on EXISTS value
+
+### STEP 3: HANDLE EXISTING METADATA
+
+EXECUTE:
+```bash
+EXISTING_JSON=$(cat "$METADATA_PATH" 2>&1)
+EXISTING_MODE=$(echo "$EXISTING_JSON" | jq -r '.mode // "unknown"' 2>&1)
+EXISTING_DESC=$(echo "$EXISTING_JSON" | jq -r '.description // ""' 2>&1)
+EXISTING_CREATED=$(echo "$EXISTING_JSON" | jq -r '.created // ""' 2>&1)
+```
+
+DISPLAY TO USER:
+```
+Current worktree already has metadata:
+
+  Directory:    {WORKTREE_NAME}
+  Branch:       {CURRENT_BRANCH}
+  Mode:         {EXISTING_MODE}
+  Created:      {EXISTING_CREATED}
+  Description:  {EXISTING_DESC or "None"}
+
+Do you want to overwrite this metadata?
+```
+
+USER DECISION (use AskUserQuestion):
+- Option 1: "Keep existing metadata" → TERMINATE (no changes)
+- Option 2: "Overwrite with new metadata" → STEP 4 (proceed)
+- Option 3: "Cancel" → TERMINATE (no changes)
+
+NEXT:
+- IF user selects overwrite → STEP 4
+- IF user selects keep/cancel → TERMINATE
+
+### STEP 4: PARSE AND VALIDATE ARGUMENTS
+
+PARSE:
+```bash
+# Parse --mode flag (if present)
+if [[ "$@" =~ --mode[[:space:]]+([a-z]+) ]]; then
+    MODE_ARG="${BASH_REMATCH[1]}"
+else
+    MODE_ARG=""
+fi
+
+# Parse --description flag (if present)
+if [[ "$@" =~ --description[[:space:]]+\"([^\"]+)\" ]]; then
+    DESCRIPTION="${BASH_REMATCH[1]}"
+elif [[ "$@" =~ --description[[:space:]]+([^[:space:]]+) ]]; then
+    DESCRIPTION="${BASH_REMATCH[1]}"
+else
+    DESCRIPTION=""
+fi
+```
+
+VALIDATION:
+- IF MODE_ARG not empty AND MODE_ARG not in [main, feature, bugfix, experiment, review] → ERROR PATTERN "invalid-mode"
+
+NEXT:
+- On success → STEP 5
+- On failure → ABORT
+
+### STEP 5: DETERMINE MODE
+
+EXECUTE:
+```bash
+if [ -n "$MODE_ARG" ]; then
+    # Explicit mode provided
+    MODE="$MODE_ARG"
+else
+    # Infer from branch name using MODE_INFERENCE_ALGORITHM
+    case "$CURRENT_BRANCH" in
+        feature/*)
+            MODE="feature"
+            ;;
+        bugfix/*|fix/*)
+            MODE="bugfix"
+            ;;
+        exp/*|experiment/*)
+            MODE="experiment"
+            ;;
+        review/*)
+            MODE="review"
+            ;;
+        main|master)
+            MODE="main"
+            ;;
+        *)
+            MODE="feature"
+            ;;
+    esac
+fi
+```
+
+VALIDATION:
+- MODE must be exactly one of: main, feature, bugfix, experiment, review
+- MODE must not be empty
+
+DATA:
+- MODE = final determined mode (explicit or inferred)
+
+NEXT:
+- On success → STEP 6
+- On failure → ABORT (should not occur if STEP 4 validation passed)
+
+### STEP 6: GENERATE TIMESTAMP
+
+EXECUTE:
+```bash
+CREATED_TIMESTAMP=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+```
+
+FORMAT: ISO 8601 UTC (example: 2025-11-23T12:34:56Z)
+
+VALIDATION:
+- CREATED_TIMESTAMP must match pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}Z$
+
+NEXT:
+- On success → STEP 7
+- No failure case
+
+### STEP 7: GENERATE .ai-context.json
+
+CONTENT TEMPLATE:
+```json
+{
+  "worktree": "{WORKTREE_NAME}",
+  "branch": "{CURRENT_BRANCH}",
+  "mode": "{MODE}",
+  "created": "{CREATED_TIMESTAMP}",
+  "description": "{DESCRIPTION}"
+}
+```
+
+SUBSTITUTIONS:
+- {WORKTREE_NAME} = from STEP 1
+- {CURRENT_BRANCH} = from STEP 1
+- {MODE} = from STEP 5
+- {CREATED_TIMESTAMP} = from STEP 6
+- {DESCRIPTION} = from STEP 4 (empty string if not provided)
+
+EXECUTE:
+```bash
+cat > "$REPO_ROOT/.ai-context.json" <<EOF
+{
+  "worktree": "$WORKTREE_NAME",
+  "branch": "$CURRENT_BRANCH",
+  "mode": "$MODE",
+  "created": "$CREATED_TIMESTAMP",
+  "description": "$DESCRIPTION"
+}
+EOF
+```
+
+VALIDATION:
+- File must be created at exact path: $REPO_ROOT/.ai-context.json
+- File must contain valid JSON
+- Verify with: `jq empty "$REPO_ROOT/.ai-context.json"`
+- IF jq fails → ERROR PATTERN "metadata-write-failed"
+
+NEXT:
+- On success → STEP 8
+- On failure → ABORT
+
+### STEP 8: GENERATE README.working-tree.md (IF MISSING)
+
+CHECK:
+```bash
+README_PATH="$REPO_ROOT/README.working-tree.md"
+test -f "$README_PATH"
+README_EXISTS=$?
+```
+
+ACTION:
+- IF README_EXISTS == 0 (exists) → SKIP to STEP 9 (don't overwrite)
+- IF README_EXISTS == 1 (missing) → Create README
+
+CONTENT TEMPLATE:
+```markdown
+# Worktree: {WORKTREE_NAME}
+
+**Branch:** `{CURRENT_BRANCH}`
+**Mode:** `{MODE}`
+**Created:** {CREATED_TIMESTAMP}
+
+## Purpose
+
+{DESCRIPTION_OR_DEFAULT}
+
+## Mode Semantics
+
+- **main**: Minimal changes, stable work only
+- **feature**: Active development, larger changes allowed
+- **bugfix**: Isolated, surgical fixes only
+- **experiment**: Prototypes, large swings, unsafe changes allowed
+- **review**: Documentation, analysis, audits
+
+## About This Worktree
+
+This directory is an independent Git worktree attached to the main repository.
+
+- Main repo: {REPO_ROOT}
+- Worktree path: {REPO_ROOT}
+- Branch: {CURRENT_BRANCH}
+
+See `.ai-context.json` for machine-readable metadata.
+```
+
+SUBSTITUTIONS:
+- {WORKTREE_NAME} = from STEP 1
+- {CURRENT_BRANCH} = from STEP 1
+- {MODE} = from STEP 5
+- {CREATED_TIMESTAMP} = from STEP 6
+- {DESCRIPTION_OR_DEFAULT} = DESCRIPTION if not empty, else "No description provided"
+- {REPO_ROOT} = from STEP 1
+
+EXECUTE (only if README_EXISTS == 1):
+```bash
+DESCRIPTION_TEXT="${DESCRIPTION:-No description provided}"
+cat > "$REPO_ROOT/README.working-tree.md" <<EOF
+# Worktree: $WORKTREE_NAME
+
+**Branch:** \`$CURRENT_BRANCH\`
+**Mode:** \`$MODE\`
+**Created:** $CREATED_TIMESTAMP
+
+## Purpose
+
+$DESCRIPTION_TEXT
+
+## Mode Semantics
+
+- **main**: Minimal changes, stable work only
+- **feature**: Active development, larger changes allowed
+- **bugfix**: Isolated, surgical fixes only
+- **experiment**: Prototypes, large swings, unsafe changes allowed
+- **review**: Documentation, analysis, audits
+
+## About This Worktree
+
+This directory is an independent Git worktree attached to the main repository.
+
+- Main repo: $REPO_ROOT
+- Worktree path: $REPO_ROOT
+- Branch: $CURRENT_BRANCH
+
+See \`.ai-context.json\` for machine-readable metadata.
+EOF
+```
+
+VALIDATION:
+- IF created, file must exist at: $REPO_ROOT/README.working-tree.md
+- IF file creation failed → Warning (not fatal)
+
+NEXT:
+- On success or skip → STEP 9
+- On failure → Warning (continue)
+
+### STEP 9: OUTPUT SUCCESS SUMMARY
+
+OUTPUT FORMAT (exact):
+```
+Adopted worktree successfully!
+
+  Directory: {WORKTREE_NAME}
+  Branch: {CURRENT_BRANCH}
+  Mode: {MODE}
+  Description: {DESCRIPTION_OR_NONE}
+
+Metadata files created:
+  ✓ .ai-context.json
+  {README_STATUS}
+
+Use /status:working-tree to view metadata anytime.
+```
+
+SUBSTITUTIONS:
+- {WORKTREE_NAME} = from STEP 1
+- {CURRENT_BRANCH} = from STEP 1
+- {MODE} = from STEP 5
+- {DESCRIPTION_OR_NONE} = DESCRIPTION if not empty, else "None"
+- {README_STATUS} = "✓ README.working-tree.md (created)" if created, "- README.working-tree.md (already exists)" if skipped
+
+NEXT:
+- TERMINATE (success)
+
+## ERROR PATTERNS
+
+### PATTERN: not-in-git-repo
+
+DETECTION:
+- TRIGGER: git rev-parse --show-toplevel exit code != 0
+- INDICATORS: stderr contains "not a git repository"
+
+RESPONSE (exact):
+```
+Error: Not in a git repository
+
+Run this command from within a git repository.
+
+To create a new worktree with metadata:
+  /create:working-tree <branch-name>
+```
+
+CONTROL FLOW:
+- ABORT: true
+- CLEANUP: none
+- RETRY: false
+
+### PATTERN: git-command-failed
+
+DETECTION:
+- TRIGGER: Any git command (except rev-parse --show-toplevel) returns non-zero exit code
+- CAPTURE: stderr from git command
+
+RESPONSE (exact):
+```
+Error: Failed to read git information
+
+Git error: {GIT_STDERR}
+
+Check that:
+  - You're in a git repository
+  - Git is installed and working
+```
+
+TEMPLATE SUBSTITUTIONS:
+- {GIT_STDERR} = captured stderr
+
+CONTROL FLOW:
+- ABORT: true
+- CLEANUP: none
+- RETRY: false
+
+### PATTERN: invalid-mode
+
+DETECTION:
+- TRIGGER: MODE_ARG provided but not in [main, feature, bugfix, experiment, review]
+
+RESPONSE (exact):
+```
+Error: Invalid mode '{MODE_ARG}'
+
+Valid modes: main, feature, bugfix, experiment, review
+
+Example:
+  /adopt:working-tree --mode feature --description "new feature work"
+```
+
+TEMPLATE SUBSTITUTIONS:
+- {MODE_ARG} = the invalid mode provided
+
+CONTROL FLOW:
+- ABORT: true
+- CLEANUP: none
+- RETRY: false
+
+### PATTERN: metadata-write-failed
+
+DETECTION:
+- TRIGGER: .ai-context.json write fails or invalid JSON (STEP 7)
+- CHECK: jq validation fails
+
+RESPONSE (exact):
+```
+Error: Failed to write .ai-context.json
+
+Write error: {ERROR_MESSAGE}
+
+Check that:
+  - You have write permission in this directory
+  - Disk space is available
+  - No file conflicts exist
+```
+
+TEMPLATE SUBSTITUTIONS:
+- {ERROR_MESSAGE} = error message from write operation
+
+CONTROL FLOW:
+- ABORT: true
+- CLEANUP: none
+- RETRY: false
+
+### PATTERN: readme-write-failed
+
+DETECTION:
+- TRIGGER: README.working-tree.md write fails (STEP 8)
+
+RESPONSE (exact):
+```
+Warning: Failed to write README.working-tree.md
+
+The .ai-context.json was created successfully.
+
+You can manually create the README if needed.
+```
+
+CONTROL FLOW:
+- ABORT: false (warning, not critical)
+- CLEANUP: none
+- FALLBACK: Continue without README
+
+## TOOL PERMISSION MATRIX
+
+| Tool | Pattern | Permission | Pre-Check | Post-Check | On-Deny-Action |
+|------|---------|------------|-----------|------------|----------------|
+| Bash | git:* | ALLOW | command_safe | validate_output | N/A |
+| Bash | date:* | ALLOW | N/A | N/A | N/A |
+| Bash | test:* | ALLOW | N/A | N/A | N/A |
+| Bash | basename:* | ALLOW | N/A | N/A | N/A |
+| Bash | cat > *.json | ALLOW | dir_writable | valid_json | N/A |
+| Bash | cat > *.md | ALLOW | dir_writable | N/A | N/A |
+| Bash | jq:* | ALLOW | N/A | N/A | N/A |
+| Bash | rm:* | DENY | N/A | N/A | ABORT "Destructive operation" |
+| Bash | sudo:* | DENY | N/A | N/A | ABORT "Elevated privileges" |
+| Write | $REPO_ROOT/.ai-context.json | ALLOW | dir_exists | valid_json | N/A |
+| Write | $REPO_ROOT/README.working-tree.md | ALLOW | dir_exists | N/A | N/A |
+| Write | **/.env* | DENY | N/A | N/A | ABORT "Secrets file" |
+| Read | $REPO_ROOT/.ai-context.json | ALLOW | file_exists | N/A | N/A |
+
+SECURITY CONSTRAINTS:
+- Can only write to current worktree directory (REPO_ROOT)
+- Cannot modify files outside current worktree
+- Cannot execute destructive operations
+- All file writes must be to metadata files only
+
+## TEST CASES
+
+### TC001: Adopt worktree without metadata
+
+PRECONDITIONS:
+- In git repository at /Users/dev/myapp
+- Current branch: feature/login
+- File does NOT exist: /Users/dev/myapp/.ai-context.json
+
+INPUT:
+```
+/adopt:working-tree
+```
+
+EXPECTED EXECUTION FLOW:
+1. STEP 1 → REPO_ROOT="/Users/dev/myapp", WORKTREE_NAME="myapp", CURRENT_BRANCH="feature/login"
+2. STEP 2 → EXISTS=1 (no metadata)
+3. STEP 4 → MODE_ARG="", DESCRIPTION=""
+4. STEP 5 → MODE="feature" (inferred from "feature/" prefix)
+5. STEP 6 → Generate timestamp
+6. STEP 7 → Write .ai-context.json
+7. STEP 8 → README_EXISTS=1, create README
+8. STEP 9 → Output summary
+
+EXPECTED OUTPUT:
+```
+Adopted worktree successfully!
+
+  Directory: myapp
+  Branch: feature/login
+  Mode: feature
+  Description: None
+
+Metadata files created:
+  ✓ .ai-context.json
+  ✓ README.working-tree.md (created)
+
+Use /status:working-tree to view metadata anytime.
+```
+
+VALIDATION COMMANDS:
+```bash
+# Verify .ai-context.json created
+test -f /Users/dev/myapp/.ai-context.json && echo "PASS" || echo "FAIL"
+jq -r '.mode' /Users/dev/myapp/.ai-context.json | grep "feature" && echo "PASS" || echo "FAIL"
+
+# Verify README created
+test -f /Users/dev/myapp/README.working-tree.md && echo "PASS" || echo "FAIL"
+```
+
+### TC002: Adopt with explicit mode and description
+
+PRECONDITIONS:
+- In git repository at /Users/dev/myapp
+- Current branch: main
+- No existing metadata
+
+INPUT:
+```
+/adopt:working-tree --mode main --description "Primary development branch"
+```
+
+EXPECTED EXECUTION FLOW:
+1-2. Standard detection
+3. STEP 4 → MODE_ARG="main", DESCRIPTION="Primary development branch"
+4. STEP 5 → MODE="main" (explicit, not inferred)
+5-8. Standard flow
+
+EXPECTED .ai-context.json:
+```json
+{
+  "worktree": "myapp",
+  "branch": "main",
+  "mode": "main",
+  "created": "2025-11-23T12:34:56Z",
+  "description": "Primary development branch"
+}
+```
+
+VALIDATION:
+```bash
+jq -r '.mode' .ai-context.json | grep "main" && echo "PASS" || echo "FAIL"
+jq -r '.description' .ai-context.json | grep "Primary development branch" && echo "PASS" || echo "FAIL"
+```
+
+### TC003: Metadata already exists - user keeps existing
+
+PRECONDITIONS:
+- In git repository at /Users/dev/myapp
+- File exists: /Users/dev/myapp/.ai-context.json with valid data
+
+INPUT:
+```
+/adopt:working-tree --mode experiment
+```
+
+EXPECTED EXECUTION FLOW:
+1. STEP 1 → Detect repo
+2. STEP 2 → EXISTS=0 (metadata exists)
+3. STEP 3 → Display existing metadata, ask user
+4. USER SELECTS "Keep existing metadata"
+5. TERMINATE (no changes)
+
+EXPECTED OUTPUT:
+```
+Current worktree already has metadata:
+
+  Directory:    myapp
+  Branch:       feature/login
+  Mode:         feature
+  Created:      2025-11-20T10:00:00Z
+  Description:  Original description
+
+Do you want to overwrite this metadata?
+```
+
+POSTCONDITIONS:
+- .ai-context.json unchanged
+- No files modified
+
+### TC004: Metadata already exists - user overwrites
+
+PRECONDITIONS:
+- In git repository with existing .ai-context.json
+
+INPUT:
+```
+/adopt:working-tree --mode experiment --description "New description"
+```
+
+EXPECTED EXECUTION FLOW:
+1-2. Detect repo, metadata exists
+3. STEP 3 → Display existing, ask user
+4. USER SELECTS "Overwrite with new metadata"
+5-9. Continue with creation (new timestamp, new mode, new description)
+
+EXPECTED OUTPUT:
+```
+Current worktree already has metadata:
+  [existing data shown]
+
+Do you want to overwrite this metadata?
+
+[User confirms overwrite]
+
+Adopted worktree successfully!
+
+  Directory: myapp
+  Branch: feature/login
+  Mode: experiment
+  Description: New description
+
+Metadata files created:
+  ✓ .ai-context.json
+  - README.working-tree.md (already exists)
+
+Use /status:working-tree to view metadata anytime.
+```
+
+### TC005: README already exists
+
+PRECONDITIONS:
+- No .ai-context.json
+- README.working-tree.md already exists
+
+INPUT:
+```
+/adopt:working-tree
+```
+
+EXPECTED EXECUTION FLOW:
+1-7. Standard flow, create .ai-context.json
+8. STEP 8 → README_EXISTS=0 (exists), skip creation
+9. STEP 9 → Output shows README skipped
+
+EXPECTED OUTPUT:
+```
+Adopted worktree successfully!
+
+  Directory: myapp
+  Branch: feature/login
+  Mode: feature
+  Description: None
+
+Metadata files created:
+  ✓ .ai-context.json
+  - README.working-tree.md (already exists)
+
+Use /status:working-tree to view metadata anytime.
+```
+
+## USE CASES
+
+### UC001: Adopting main repository
+When working in main repo without worktrees:
+```bash
+cd ~/myapp
+/adopt:working-tree --mode main --description "Primary development branch"
+```
+
+### UC002: Adopting manually created worktree
+If worktree created without /create:working-tree:
+```bash
+cd ../myapp-feature-something
+/adopt:working-tree
+```
+
+### UC003: Adding description later
+If worktree created without description:
+```bash
+/adopt:working-tree --description "Working on user authentication refactor"
+```
+(Will prompt to overwrite existing metadata)
+
+### UC004: Correcting mode
+If mode was inferred incorrectly:
+```bash
+/adopt:working-tree --mode experiment
+```
+(Will prompt to overwrite existing metadata)
+
+## RELATED COMMANDS
+
+- /status:working-tree - View current metadata after adoption
+- /create:working-tree - Create new worktree with metadata from start
+- /list:working-tree - See all worktrees and their metadata status
+
+## DELEGATION
+
+For organizing worktree adoption strategy:
+```
+Task(
+  subagent_type='working-tree-consultant',
+  description='Worktree adoption strategy',
+  prompt='[question about when/how to adopt worktrees]'
+)
+```