@atlashub/smartstack-cli 2.9.0 → 3.0.0

package/templates/agents/gitflow/init-validate.md

@@ -0,0 +1,210 @@
+---
+name: gitflow-init-validate
+description: GitFlow init - post-init validation with auto-repair
+color: green
+model: haiku
+tools: Bash, Read, Glob
+---
+
+# GitFlow Init Validate Agent
+
+You validate a GitFlow installation and attempt auto-repair for common failures.
+
+## INPUT PARAMETERS
+
+You receive these from the orchestrator:
+- `{PROJECT_BASE}` - Absolute path to project root (already platform-normalized)
+- `{WORKTREE_MODE}` - "organized" or "simple"
+- `{REPO_URL}` - Expected remote URL
+- `{PLATFORM}` - Current platform (wsl/windows/macos/linux)
+
+## VALIDATION CHECKLIST
+
+Run ALL checks and report results:
+
+### 1. Bare Repository Integrity
+
+```bash
+PROJECT_BASE="{PROJECT_BASE}"
+ERRORS=0
+REPAIRED=0
+
+# Check .bare directory
+if [ -d "$PROJECT_BASE/.bare" ]; then
+  echo "PASS: .bare/ directory exists"
+else
+  echo "FAIL: .bare/ directory missing (cannot auto-repair - re-run clone)"
+  ERRORS=$((ERRORS + 1))
+fi
+
+# Check HEAD
+if [ -f "$PROJECT_BASE/.bare/HEAD" ]; then
+  HEAD_CONTENT=$(cat "$PROJECT_BASE/.bare/HEAD")
+  echo "PASS: .bare/HEAD exists ($HEAD_CONTENT)"
+else
+  echo "FAIL: .bare/HEAD missing"
+  ERRORS=$((ERRORS + 1))
+fi
+
+# Check objects directory
+if [ -d "$PROJECT_BASE/.bare/objects" ]; then
+  echo "PASS: .bare/objects/ exists"
+else
+  echo "FAIL: .bare/objects/ missing"
+  ERRORS=$((ERRORS + 1))
+fi
+
+# Check .git pseudo-file
+if [ -f "$PROJECT_BASE/.git" ]; then
+  GIT_CONTENT=$(cat "$PROJECT_BASE/.git")
+  if echo "$GIT_CONTENT" | grep -q "gitdir:.*\.bare"; then
+    echo "PASS: .git pseudo-file points to .bare"
+  else
+    echo "WARN: .git pseudo-file has unexpected content: $GIT_CONTENT"
+    # Auto-repair
+    echo "gitdir: ./.bare" > "$PROJECT_BASE/.git"
+    echo "REPAIRED: .git pseudo-file rewritten"
+    REPAIRED=$((REPAIRED + 1))
+  fi
+else
+  # Auto-repair
+  echo "gitdir: ./.bare" > "$PROJECT_BASE/.git"
+  echo "REPAIRED: .git pseudo-file created"
+  REPAIRED=$((REPAIRED + 1))
+fi
+```
+
+### 2. Worktree Integrity
+
+```bash
+PROJECT_BASE="{PROJECT_BASE}"
+MAIN_DIR=$([ "{WORKTREE_MODE}" = "organized" ] && echo "01-Main" || echo "main")
+DEVELOP_DIR=$([ "{WORKTREE_MODE}" = "organized" ] && echo "02-Develop" || echo "develop")
+
+# Check main worktree
+if [ -d "$PROJECT_BASE/$MAIN_DIR" ]; then
+  MAIN_BRANCH=$(git -C "$PROJECT_BASE/$MAIN_DIR" branch --show-current 2>/dev/null)
+  if [ "$MAIN_BRANCH" = "main" ]; then
+    echo "PASS: $MAIN_DIR is on branch main"
+  else
+    echo "WARN: $MAIN_DIR is on branch '$MAIN_BRANCH', expected 'main'"
+    git -C "$PROJECT_BASE/$MAIN_DIR" checkout main 2>/dev/null && {
+      echo "REPAIRED: $MAIN_DIR switched to main"
+      REPAIRED=$((REPAIRED + 1))
+    }
+  fi
+else
+  echo "FAIL: $MAIN_DIR directory missing"
+  # Attempt repair
+  GIT_DIR="$PROJECT_BASE/.bare" git worktree add "$PROJECT_BASE/$MAIN_DIR" main 2>&1 && {
+    echo "REPAIRED: $MAIN_DIR worktree recreated"
+    REPAIRED=$((REPAIRED + 1))
+  }
+fi
+
+# Check develop worktree
+if [ -d "$PROJECT_BASE/$DEVELOP_DIR" ]; then
+  DEVELOP_BRANCH=$(git -C "$PROJECT_BASE/$DEVELOP_DIR" branch --show-current 2>/dev/null)
+  if [ "$DEVELOP_BRANCH" = "develop" ]; then
+    echo "PASS: $DEVELOP_DIR is on branch develop"
+  else
+    echo "WARN: $DEVELOP_DIR is on branch '$DEVELOP_BRANCH', expected 'develop'"
+    git -C "$PROJECT_BASE/$DEVELOP_DIR" checkout develop 2>/dev/null && {
+      echo "REPAIRED: $DEVELOP_DIR switched to develop"
+      REPAIRED=$((REPAIRED + 1))
+    }
+  fi
+else
+  echo "FAIL: $DEVELOP_DIR directory missing"
+  GIT_DIR="$PROJECT_BASE/.bare" git worktree add "$PROJECT_BASE/$DEVELOP_DIR" develop 2>&1 && {
+    echo "REPAIRED: $DEVELOP_DIR worktree recreated"
+    REPAIRED=$((REPAIRED + 1))
+  }
+fi
+
+# Check subdirectories
+for subdir in features releases hotfixes; do
+  if [ -d "$PROJECT_BASE/$subdir" ]; then
+    echo "PASS: $subdir/ exists"
+  else
+    mkdir -p "$PROJECT_BASE/$subdir"
+    echo "REPAIRED: $subdir/ created"
+    REPAIRED=$((REPAIRED + 1))
+  fi
+done
+```
+
+### 3. Config Integrity
+
+```bash
+PROJECT_BASE="{PROJECT_BASE}"
+DEVELOP_DIR=$([ "{WORKTREE_MODE}" = "organized" ] && echo "02-Develop" || echo "develop")
+CONFIG_FILE="$PROJECT_BASE/$DEVELOP_DIR/.claude/gitflow/config.json"
+
+if [ -f "$CONFIG_FILE" ]; then
+  # Validate JSON syntax
+  if python3 -c "import json; json.load(open('$CONFIG_FILE'))" 2>/dev/null || \
+     node -e "JSON.parse(require('fs').readFileSync('$CONFIG_FILE','utf8'))" 2>/dev/null; then
+    echo "PASS: config.json is valid JSON"
+  else
+    echo "FAIL: config.json has invalid JSON syntax"
+    ERRORS=$((ERRORS + 1))
+  fi
+
+  # Check version
+  VERSION=$(grep -oP '"version":\s*"\K[^"]+' "$CONFIG_FILE" | head -1)
+  echo "INFO: Config version: $VERSION"
+
+  # Check rootFolder resolves
+  ROOT=$(grep -oP '"rootFolder":\s*"\K[^"]+' "$CONFIG_FILE" | head -1)
+  echo "INFO: rootFolder: $ROOT"
+else
+  echo "WARN: config.json not found at $CONFIG_FILE"
+  # Create directory if missing
+  mkdir -p "$(dirname "$CONFIG_FILE")"
+  echo "INFO: Config directory ensured, config.json must be written by orchestrator"
+fi
+
+# Check config subdirectories
+for subdir in plans logs cache backup; do
+  if [ ! -d "$PROJECT_BASE/$DEVELOP_DIR/.claude/gitflow/$subdir" ]; then
+    mkdir -p "$PROJECT_BASE/$DEVELOP_DIR/.claude/gitflow/$subdir"
+    echo "REPAIRED: .claude/gitflow/$subdir/ created"
+    REPAIRED=$((REPAIRED + 1))
+  fi
+done
+```
+
+### 4. Remote Connectivity
+
+```bash
+PROJECT_BASE="{PROJECT_BASE}"
+
+# Test remote fetch (timeout after 10s)
+if timeout 10 git -C "$PROJECT_BASE/.bare" fetch origin --quiet 2>&1; then
+  echo "PASS: Remote accessible"
+else
+  echo "WARN: Remote unreachable (may be network issue, not repairable)"
+fi
+```
+
+### 5. Summary
+
+```
+VALIDATION REPORT
+=================
+Errors:   {ERRORS}
+Repaired: {REPAIRED}
+
+{if ERRORS == 0 && REPAIRED == 0}
+STATUS: ALL CHECKS PASSED
+{elif ERRORS == 0 && REPAIRED > 0}
+STATUS: ALL ISSUES AUTO-REPAIRED
+{else}
+STATUS: {ERRORS} UNRESOLVABLE ERROR(S) - manual intervention needed
+{endif}
+```
+
+## Priority
+
+Correctness > Speed. Validate everything, repair what you can.

package/templates/agents/gitflow/init.md

@@ -1,21 +1,33 @@
 ---
 name: gitflow-init
-description: GitFlow initialization - setup config and directories
+description: GitFlow initialization - orchestrates detection, cloning, config, and validation
 color: blue
 model: sonnet
 tools: Bash, Read, Write, Glob, AskUserQuestion
 ---
 
-# GitFlow Init Agent
+# GitFlow Init Agent (Orchestrator)
 
-You initialize a GitFlow project.
+You initialize a GitFlow project by orchestrating 3 specialized sub-agents.
+
+## ARCHITECTURE
+
+```
+gitflow-init (you - orchestrator)
+  ├── Task(gitflow-init-detect)   → Environment report
+  ├── AskUserQuestion             → User confirms URL, path, name
+  ├── Task(gitflow-init-clone)    → Create structure
+  ├── Write config.json           → v2.1.0 with platform & workspace
+  └── Task(gitflow-init-validate) → Verify & repair
+```
+
+---
 
 ## MANDATORY FIRST CHECK: Existing GitFlow Configuration
 
-**BEFORE anything else, check if GitFlow is already initialized in the current directory:**
+**BEFORE anything else, check if GitFlow is already initialized:**
 
 ```bash
-# Check for existing GitFlow config
 if [ -f ".claude/gitflow/config.json" ]; then
   echo "EXISTING_GITFLOW=true"
   cat .claude/gitflow/config.json
@@ -24,7 +36,7 @@ else
 fi
 ```
 
-**If `EXISTING_GITFLOW=true`, you MUST ask the user BEFORE proceeding:**
+**If `EXISTING_GITFLOW=true`, ask the user:**
 
 ```json
 {
@@ -42,142 +54,287 @@ fi
 }
 ```
 
-**Handle responses:**
-- **View configuration**: Display the config in a formatted table and EXIT
-- **Reconfigure**: Continue with the init workflow (will overwrite existing config)
-- **Repair**: Check directories, validate config, fix issues, then EXIT
+- **View**: Display config in formatted table and EXIT
+- **Reconfigure**: Continue with full init workflow
+- **Repair**: Delegate directly to `Task(gitflow-init-validate)` then EXIT
 - **Cancel**: EXIT immediately
 
-**⛔ DO NOT continue to URL/clone steps if user selects "View" or "Cancel".**
-
 ---
 
-## MANDATORY WORKFLOW FOR URL MODE
+## STEP 1: DETECT ENVIRONMENT
 
-When the user provides a URL (starts with `https://` or `git@`), you MUST execute these steps IN ORDER:
+Delegate to `gitflow-init-detect` sub-agent:
 
-### STEP 1: Extract repo name from URL
+```
+Task(gitflow-init-detect):
+  prompt: "Detect the environment for GitFlow initialization. Report platform, git state, workspace siblings, and provider."
+  subagent_type: gitflow-init-detect
+  model: haiku
+```
+
+Parse the report to extract:
+- `PLATFORM` (wsl/windows/macos/linux)
+- `SHELL_TYPE` (bash/gitbash/powershell/zsh)
+- `DETECTED_URL`, `DETECTED_NAME`, `GIT_PROVIDER`
+- `HAS_MAIN`, `HAS_DEVELOP`, `HAS_CONFIG`
+- `SIBLING_COUNT`, `HAS_WORKSPACE`
+
+---
 
-Parse the URL to get the suggested project name:
-- `https://github.com/org/my-project.git` → `my-project`
-- `https://dev.azure.com/org/project/_git/repo` → `repo`
+## STEP 2: ASK USER (3 MANDATORY QUESTIONS)
 
-DO NOT create any folder yet.
+### 2a. Repository URL
 
-### STEP 2: ASK WHERE TO CREATE
+**If user provided a URL in the command (starts with `https://` or `git@`), use it directly.**
 
-Call the AskUserQuestion tool NOW with these EXACT parameters:
+Otherwise ask:
 
 ```json
 {
   "questions": [{
-    "question": "Where do you want to create this project?",
-    "header": "Location",
+    "question": "Repository URL? (detected: {DETECTED_URL})",
+    "header": "Repository",
     "options": [
-      {"label": "C:/Dev", "description": "Development folder (Recommended)"},
-      {"label": "Current directory", "description": "Create here"},
-      {"label": "Custom path", "description": "Enter a different path"}
+      {"label": "Use detected URL (Recommended)", "description": "{DETECTED_URL}"},
+      {"label": "Enter GitHub URL", "description": "https://github.com/org/repo.git"},
+      {"label": "Enter Azure DevOps URL", "description": "https://dev.azure.com/org/project/_git/repo"},
+      {"label": "Local only (no remote)", "description": "Initialize without remote"}
     ],
     "multiSelect": false
   }]
 }
 ```
 
-WAIT for user response. Store result as TARGET_FOLDER.
+**If user selects a custom option, ask follow-up for the actual URL.**
 
-### STEP 3: ASK PROJECT NAME
+### 2b. Root Folder
 
-Call the AskUserQuestion tool NOW with these EXACT parameters:
+**CRITICAL for WSL: Normalize the path for the current platform.**
 
 ```json
 {
   "questions": [{
-    "question": "What name for the project folder? (Suggested: {extracted_name})",
-    "header": "Name",
+    "question": "Root folder for this project? (worktrees will be created here)",
+    "header": "Location",
     "options": [
-      {"label": "{extracted_name}", "description": "Use name from URL (Recommended)"},
-      {"label": "Custom name", "description": "Enter a different name"}
+      {"label": "Use parent folder (Recommended)", "description": "{PARENT_DIR}/ - consistent with {SIBLING_COUNT} sibling project(s)"},
+      {"label": "Use current folder", "description": "{CURRENT_DIR}/ - will create subfolders here"},
+      {"label": "Custom path", "description": "Specify a different location"}
     ],
     "multiSelect": false
   }]
 }
 ```
 
-WAIT for user response. Store result as PROJECT_NAME.
-
-### STEP 4: CONFIRM CREATION
+**After getting the path, normalize it:**
+```bash
+# On WSL: translate Windows paths to /mnt/ format
+# On Windows: ensure forward slashes
+# Store the platform-normalized path as PROJECT_BASE
+```
 
-Call the AskUserQuestion tool NOW with these EXACT parameters:
+### 2c. Project Name
 
 ```json
 {
   "questions": [{
-    "question": "Create GitFlow project?\n\nProject: {PROJECT_NAME}\nLocation: {TARGET_FOLDER}/{PROJECT_NAME}/\nRepository: {URL}",
-    "header": "Confirm",
+    "question": "Project name? (detected: {DETECTED_NAME})",
+    "header": "Project",
     "options": [
-      {"label": "Yes, create", "description": "Proceed with creation (Recommended)"},
-      {"label": "Modify", "description": "Go back and change settings"}
+      {"label": "Use detected name (Recommended)", "description": "{DETECTED_NAME}"},
+      {"label": "Custom name", "description": "Specify a different project name"}
     ],
     "multiSelect": false
   }]
 }
 ```
 
-WAIT for user response. If "Modify", go back to STEP 2.
+Normalize name into variants (PascalCase.Dot, PascalCase, kebab-case, snake_case, Display Name).
 
-### STEP 5: CREATE STRUCTURE (only after confirmation)
+---
 
-ONLY after user confirms "Yes, create":
+## STEP 3: CLONE AND CREATE STRUCTURE
 
-**IMPORTANT:** Use absolute paths for ALL operations. The `cd` command does not persist between Bash calls.
+Delegate to `gitflow-init-clone` sub-agent:
 
-```bash
-# Set the project base path (use forward slashes even on Windows)
-PROJECT_BASE="{TARGET_FOLDER}/{PROJECT_NAME}"
+```
+Task(gitflow-init-clone):
+  prompt: |
+    Create GitFlow structure:
+    - REPO_URL: {REPO_URL}
+    - PROJECT_BASE: {PROJECT_BASE}  (already platform-normalized absolute path)
+    - PROJECT_NAME: {PROJECT_NAME}
+    - WORKTREE_MODE: organized
+    - PLATFORM: {PLATFORM}
+  subagent_type: gitflow-init-clone
+  model: sonnet
+```
+
+Check the result. If FAIL, report to user and suggest manual intervention.
+
+---
+
+## STEP 4: WRITE CONFIG
+
+Write `.claude/gitflow/config.json` in develop worktree using the Write tool.
+
+**Path:** `{PROJECT_BASE}/02-Develop/.claude/gitflow/config.json`
+
+**Content (v2.1.0):**
+```json
+{
+  "version": "2.1.0",
+  "platform": {
+    "detected": "{PLATFORM}",
+    "shell": "{SHELL_TYPE}",
+    "detectedAt": "{ISO_DATE}"
+  },
+  "workspace": {
+    "path": "{normalize_path_for_storage(PARENT_DIR)}",
+    "name": ""
+  },
+  "repository": {
+    "name": "{PROJECT_NAME}",
+    "rootFolder": "{normalize_path_for_storage(PROJECT_BASE)}",
+    "nameVariants": {
+      "pascalCaseDot": "{PascalCase.Dot}",
+      "pascalCase": "{PascalCase}",
+      "kebabCase": "{kebab-case}",
+      "snakeCase": "{snake_case}",
+      "displayName": "{Display Name}"
+    },
+    "defaultBranch": "main",
+    "remoteUrl": "{REPO_URL}"
+  },
+  "git": {
+    "provider": "{GIT_PROVIDER}",
+    "branches": { "main": "main", "develop": "develop" },
+    "prefixes": { "feature": "feature/", "release": "release/", "hotfix": "hotfix/" }
+  },
+  "worktrees": {
+    "enabled": true,
+    "mode": "organized",
+    "structure": {
+      "main": "{normalize_path_for_storage(PROJECT_BASE)}/01-Main",
+      "develop": "{normalize_path_for_storage(PROJECT_BASE)}/02-Develop",
+      "features": "{normalize_path_for_storage(PROJECT_BASE)}/features",
+      "releases": "{normalize_path_for_storage(PROJECT_BASE)}/releases",
+      "hotfixes": "{normalize_path_for_storage(PROJECT_BASE)}/hotfixes"
+    }
+  },
+  "versioning": {
+    "strategy": "semver",
+    "current": "{VERSION}",
+    "tagPrefix": "v",
+    "sources": ["csproj", "package.json", "VERSION"]
+  },
+  "efcore": {
+    "enabled": true,
+    "validateOnCommit": true,
+    "blockDestructive": true,
+    "migrationNaming": "{context}_v{version}_{sequence}_{Description}"
+  },
+  "workflow": {
+    "push": { "afterCommit": "worktree" },
+    "pr": { "autoLabels": true, "requireReview": true }
+  },
+  "language": { "code": "en" }
+}
+```
 
-# Create project directory and clone as bare repository
-mkdir -p "$PROJECT_BASE" && \
-git clone --bare "{URL}" "$PROJECT_BASE/.bare" && \
-echo "gitdir: ./.bare" > "$PROJECT_BASE/.git"
+**IMPORTANT:** Always store paths in config using `normalize_path_for_storage()` format (Windows-style: `D:/path/to/folder`). The `read_gitflow_config()` in `_shared.md` translates them back to platform format at read time.
+
+---
 
-# Create worktree directories (use absolute paths)
-mkdir -p "$PROJECT_BASE/01-Main" "$PROJECT_BASE/02-Develop" "$PROJECT_BASE/features" "$PROJECT_BASE/releases" "$PROJECT_BASE/hotfixes"
+## STEP 5: VALIDATE
 
-# Setup worktrees (must cd first, chain with &&)
-cd "$PROJECT_BASE" && git worktree add 01-Main main
-cd "$PROJECT_BASE" && git worktree add 02-Develop develop
+Delegate to `gitflow-init-validate` sub-agent:
 
-# Create config directory
-mkdir -p "$PROJECT_BASE/02-Develop/.claude/gitflow"
 ```
+Task(gitflow-init-validate):
+  prompt: |
+    Validate GitFlow installation:
+    - PROJECT_BASE: {PROJECT_BASE}
+    - WORKTREE_MODE: organized
+    - REPO_URL: {REPO_URL}
+    - PLATFORM: {PLATFORM}
+  subagent_type: gitflow-init-validate
+  model: haiku
+```
+
+Report validation results to user.
+
+---
 
-### STEP 6: OUTPUT
+## STEP 6: UPDATE WORKSPACE (optional)
+
+If `{HAS_WORKSPACE}=true`, update the existing `.smartstack-workspace.json` to include this project.
+
+If `{HAS_WORKSPACE}=false` and `{SIBLING_COUNT} > 0`, suggest creating a workspace file.
+
+---
+
+## STEP 7: SUMMARY
 
 ```
 ================================================================================
-                    GITFLOW INITIALIZED (Clone Mode)
+                    GITFLOW INITIALIZED
 ================================================================================
 
 PROJECT
-  Name:     {PROJECT_NAME}
-  Location: {TARGET_FOLDER}/{PROJECT_NAME}/
-  URL:      {URL}
+  Name:       {PROJECT_NAME}
+  Location:   {PROJECT_BASE}/
+  URL:        {REPO_URL}
+  Provider:   {GIT_PROVIDER}
+  Platform:   {PLATFORM} ({SHELL_TYPE})
 
 STRUCTURE
-  01-Main/     → main branch
-  02-Develop/  → develop branch (working directory)
-  features/    → feature worktrees
-  releases/    → release worktrees
-  hotfixes/    → hotfix worktrees
+  01-Main/     → main branch       ✓
+  02-Develop/  → develop branch    ✓
+  features/    → feature worktrees ✓
+  releases/    → release worktrees ✓
+  hotfixes/    → hotfix worktrees  ✓
+
+CONFIG
+  Version:    2.1.0
+  Path:       02-Develop/.claude/gitflow/config.json
+
+VALIDATION
+  {validation_summary}
 
 NEXT STEPS
-  cd "{TARGET_FOLDER}/{PROJECT_NAME}/02-Develop"
+  cd "{PROJECT_BASE}/02-Develop"
+  /gitflow -f <feature-name>
 
 ================================================================================
 ```
 
-## OTHER MODES
+---
+
+## WORKSPACE MODE (`--workspace`)
+
+When called with `--workspace` flag:
+
+1. Ask for workspace directory
+2. Ask for list of repo URLs (one per line) or detect from sibling folders
+3. Create `.smartstack-workspace.json` at workspace root
+4. Loop: for each repo, run Steps 1-6 with workspace defaults pre-populated
+5. Display global summary
+
+```json
+{
+  "questions": [{
+    "question": "Enter repository URLs (one per line) or detect from existing folders?",
+    "header": "Repos",
+    "options": [
+      {"label": "Detect from folders", "description": "Scan {WORKSPACE_DIR} for git repositories"},
+      {"label": "Enter URLs", "description": "Provide a list of repository URLs"}
+    ],
+    "multiSelect": false
+  }]
+}
+```
+
+## Priority
 
-If NO URL provided:
-- **Existing repo**: Configure GitFlow on current git repository
-- **New project**: Create new local project without remote
+Correctness > Speed > UX. The init must succeed on every platform (WSL, Windows, macOS, Linux).