apstndb · Jun 19, 2025 · Jun 17, 2025 · Jun 17, 2025 · Jun 17, 2025 · Jun 17, 2025
diff --git a/.github/workflows/golangci-lint.yml b/.github/workflows/golangci-lint.yml
diff --git a/.github/workflows/run-tests.yaml b/.github/workflows/run-tests.yaml
@@ -31,6 +31,11 @@ jobs:
         with:
           go-version: '1.24'
       - run: go version
-      - name: do go test
-        run: go test ./... -coverprofile=coverage.out
+      - name: golangci-lint
+        uses: golangci/golangci-lint-action@v8
+        with:
+          version: v2.1
+          args: --timeout=5m
+      - name: run tests with coverage
+        run: make test-coverage
       - uses: k1LoW/octocov-action@v1
diff --git a/.gitignore b/.gitignore
@@ -12,13 +12,15 @@ credentials.json
 # IDE and tool directories - DO NOT delete in main workspace, safe to delete ONLY in phantom worktrees
 .idea         # JetBrains IDE settings
 .claude       # Claude Code session data
+!.claude/settings.json  # Exception: project-wide Claude Code settings (team shared)
 
 # Cache and temporary files - safe to delete anywhere
 .cache/       # Application cache directory
-tmp/          # Development temporary files
+tmp/          # Development temporary files (e.g., help output generation)
 
 # Configuration files with secrets - may contain sensitive connection info, check before deleting
 .*.cnf
 
+
 # Phantom worktree notes - temporary development notes, safe to delete anywhere
 .notes.md
diff --git a/.octocov.yml b/.octocov.yml
@@ -1,6 +1,8 @@
 # generated by octocov init
 coverage:
   if: true
+  paths:
+    - tmp/coverage.out
 codeToTestRatio:
   code:
     - '**/*.go'

diff --git a/CLAUDE.md b/CLAUDE.md
@@ -11,7 +11,7 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 **Why this rule is critical**: CLAUDE.md is read by AI assistants for every development task. Including verbose content creates cognitive overload and buries essential requirements like `make test && make lint`.
 
 ### What belongs in CLAUDE.md
-- Critical requirements (e.g., `make test && make lint` before push)
+- Critical requirements (e.g., `make check` before push)
 - Essential commands for daily development
 - Brief architecture overview with links to details
 - Documentation structure navigation
@@ -30,33 +30,37 @@ spanner-mycli is a personal fork of spanner-cli, designed as an interactive comm
 ## 🚨 CRITICAL REQUIREMENTS
 
 **Before ANY push to the repository**:
-1. **Always run `make test`** (not `make fasttest`) - all integration tests must pass
-2. **Always run `make lint`** - code quality and style compliance required
-3. **Resolve conflicts with origin/main** - ensure branch can merge cleanly to avoid integration issues
-4. **Never push directly to main branch** - always use Pull Requests
-5. **Never commit directly to main branch** - always use feature branches
+1. **Always run `make check`** - runs test && lint (required for quality assurance)
+2. **Resolve conflicts with origin/main** - ensure branch can merge cleanly to avoid integration issues
+3. **Never push directly to main branch** - always use Pull Requests
+4. **Never commit directly to main branch** - always use feature branches
 
 ## Essential Commands
 
 ```bash
-# Development cycle
+# Development cycle (CRITICAL)
+make check                    # REQUIRED before ANY push (runs test && lint)
 make build                    # Build the application
-make test && make lint        # Required before push
-make fasttest                 # Quick tests during development
-
-# Running the application
-make run PROJECT=myproject INSTANCE=myinstance DATABASE=mydatabase
-go run . -p PROJECT -i INSTANCE -d DATABASE
-
-# Documentation updates
-scripts/docs/update-help-output.sh    # Update README.md help sections
-
-# Phantom worktree management (recommended)
-scripts/dev/setup-phantom-worktree.sh issue-276-timeout-flag
-
-# GitHub review replies (automated)
-scripts/dev/list-review-threads.sh 287         # Find threads needing replies
-scripts/dev/review-reply.sh THREAD_ID "reply"  # Reply to specific thread
+make test-quick               # Quick tests during development
+
+# Development tools (Go 1.24 tool management: make build-tools)
+go tool gh-helper reviews analyze [PR]      # Comprehensive review analysis (prevents missing feedback)
+go tool gh-helper reviews wait [PR]         # Wait for reviews + checks
+go tool gh-helper reviews wait [PR] --request-review  # Request Gemini review + wait
+
+# Workflow examples  
+gh pr create                                 # Create PR (interactive for title/body)
+go tool gh-helper reviews wait              # Wait for automatic Gemini review (initial PR only)
+
+# Review response workflow (for subsequent pushes)
+go tool gh-helper reviews analyze <PR> > tmp/review-analysis.yaml  # Analyze all feedback
+# Create fix plan in tmp/fix-plan.md, make changes, commit & push
+go tool gh-helper reviews wait <PR> --request-review # Request Gemini review
+# Reply to threads with commit hash and --resolve flag
+
+# Output format examples (YAML default, JSON with --json)
+go tool gh-helper reviews analyze 306 | gojq --yaml-input '.summary.critical'
+go tool gh-helper reviews fetch 306 --json | jq '.reviewThreads.needingReply[]'
 ```
 
 ## Core Architecture Overview
@@ -80,7 +84,7 @@ For detailed implementation patterns, see [dev-docs/patterns/system-variables.md
 ### Phantom Worktree Usage
 ```bash
 # Automated setup (recommended)
-scripts/dev/setup-phantom-worktree.sh issue-123-feature  # Auto-fetches and bases on origin/main
+make worktree-setup WORKTREE_NAME=issue-123-feature  # Auto-fetches and bases on origin/main
 
 # Work in isolated environment
 phantom shell issue-123-feature --tmux-horizontal
@@ -112,9 +116,8 @@ This is a simplified guide. For detailed information, refer to:
 - **[query_plan.md](docs/query_plan.md)** - Query plan analysis features
 - **[system_variables.md](docs/system_variables.md)** - System variables reference
 
-### Automation Scripts (`scripts/`)
-- **[docs/update-help-output.sh](scripts/docs/update-help-output.sh)** - Update README help sections
-- **[dev/setup-phantom-worktree.sh](scripts/dev/setup-phantom-worktree.sh)** - Automated worktree setup
+### Development Tools **Go 1.24 Tool Management: `make build-tools`**
+- **gh-helper** - Generic GitHub operations (managed via go.mod tool directive)
 
 ## 🎯 Task-Specific Documentation Guide
 
@@ -127,20 +130,24 @@ This is a simplified guide. For detailed information, refer to:
 1. **ALWAYS check**: [dev-docs/issue-management.md](dev-docs/issue-management.md) - Complete GitHub workflow
 2. **For PR labels**: [dev-docs/issue-management.md#pull-request-labels](dev-docs/issue-management.md#pull-request-labels) - Release notes categorization
 3. **For insights capture**: [dev-docs/issue-management.md#knowledge-management](dev-docs/issue-management.md#knowledge-management) - PR comment best practices
-4. **For review replies**: Use `scripts/dev/list-review-threads.sh` and `scripts/dev/review-reply.sh` - Automated thread replies
-5. **GitHub GraphQL API**: [docs.github.com/en/graphql](https://docs.github.com/en/graphql) - Official API documentation
+4. **For review analysis**: Use `go tool gh-helper reviews analyze` for comprehensive feedback analysis (prevents missing critical issues)
+5. **For thread replies**: Use `go tool gh-helper threads reply` - Automated thread replies
+6. **GitHub GraphQL API**: [docs.github.com/en/graphql](https://docs.github.com/en/graphql) - Official API documentation
+
+**⚠️ CRITICAL: Use `go tool gh-helper reviews analyze` for comprehensive feedback analysis (review bodies + threads)**
+**⚠️ WORKFLOW: Plan fixes → commit & push → reply with commit hash and resolve threads immediately**
 
 ### When encountering development problems:
 1. **ALWAYS check**: [dev-docs/development-insights.md](dev-docs/development-insights.md) - Known patterns and solutions
 2. **For error handling**: [dev-docs/development-insights.md#error-handling-architecture-evolution](dev-docs/development-insights.md#error-handling-architecture-evolution)
 3. **For resource management**: [dev-docs/development-insights.md#resource-management-in-batch-processing](dev-docs/development-insights.md#resource-management-in-batch-processing)
 
 ### When setting up development environment:
-1. **Start here**: Use `scripts/dev/setup-phantom-worktree.sh` for worktree setup
+1. **Start here**: Use `make worktree-setup WORKTREE_NAME=issue-123-feature` for worktree setup
 2. **For workflow details**: [dev-docs/development-insights.md#parallel-issue-development-with-phantom](dev-docs/development-insights.md#parallel-issue-development-with-phantom)
 
 ### When updating documentation:
-1. **README.md help updates**: Use `scripts/docs/update-help-output.sh`
+1. **README.md help updates**: Use `make docs-update`
 2. **CLAUDE.md updates**: Follow the rules in this file (self-contained)
 3. **Other docs**: See [dev-docs/README.md](dev-docs/README.md) for structure guidance
 
@@ -158,9 +165,11 @@ make lint              # Code quality checks (required before push)
 ```
 
 ### Git Practices
-- Always use `git add <specific-files>` (never `git add .`)
+- **CRITICAL**: Always use `git add <specific-files>` (never `git add .` or `git add -A`)
+- **Reason**: Prevents accidental commits of untracked files (.claude, .idea/, tmp/, etc.)
- **CRITICAL**: Always use `git add <specific-files>` (never `git add .` or `git add -A`)
- **Reason**: Prevents accidental commits of untracked files (.claude, .idea/, tmp/, etc.)
+git add <specific-files>
- **CRITICAL**: Always use `git add <specific-files>` (never `git add .` or `git add -A`)
- **Reason**: Prevents accidental commits of untracked files (.claude, .idea/, tmp/, etc.)
+- **CRITICAL**: Always use `git add <specific-files>` (never `git add .` or `git add -A`)
+- **Reason**: Prevents accidental commits of untracked files (.claude, .idea/, tmp/, etc.). Always check `git status` before committing to verify only intended files are staged.
- **CRITICAL**: Always use `git add <specific-files>` (never `git add .` or `git add -A`)
- **Reason**: Prevents accidental commits of untracked files (.claude, .idea/, tmp/, etc.)
+git add <specific-files>
- **CRITICAL**: Always use `git add <specific-files>` (never `git add .` or `git add -A`)
- **Reason**: Prevents accidental commits of untracked files (.claude, .idea/, tmp/, etc.)
+- **CRITICAL**: Always use `git add <specific-files>` (never `git add .` or `git add -A`)
+- **Reason**: Prevents accidental commits of untracked files (.claude, .idea/, tmp/, etc.). Always check `git status` before committing to verify only intended files are staged.
 - Link PRs to issues: "Fixes #issue-number"
-- Check `git status` before committing
+- Check `git status` before committing to verify only intended files are staged
+
 
 ## Important Notes
 

diff --git a/Makefile b/Makefile
@@ -1,6 +1,14 @@
 build:
 	go build
 
+build-tools:
+	# Install development tools using Go 1.24 tool management
+	# gh-helper: Generic GitHub operations (reviews, threads) - managed via go.mod tool directive
+	@echo "📦 Installing tools from go.mod tool directive..."
+	go install tool
+	@echo "✅ Tools installed successfully"
+	@echo "💡 Use: go tool gh-helper --help"
+
 clean:
 	rm -f spanner-mycli
 	rm -rf dist/
@@ -15,11 +23,94 @@ test:
 test-verbose:
 	go test -v ./...
 
-fasttest:
-	go test -short ./...
+# Test with coverage profile (for CI)
+test-coverage:
+	@mkdir -p tmp
+	go test ./... -coverprofile=tmp/coverage.out
 
-fasttest-verbose:
-	go test -short -v ./...
 
 lint:
 	golangci-lint run
+
+
+# Enhanced development targets (issue #301 - script reorganization)
+# Development targets using Go 1.24 tool management and simple Makefile workflows
+.PHONY: test-quick check docs-update help-dev worktree-setup worktree-list worktree-delete gh-review build-tools
+
+# Quick tests for development cycle
+test-quick:
+	go test -short ./...
+
+# Combined test and lint check (required before push)
+check: test lint
+
+
+# Update README.md help sections (replacing spanner-mycli-dev)
+docs-update:
+	@echo "📝 Updating help output for README.md..."
+	@mkdir -p tmp
+	@script -q tmp/help_output.txt sh -c "stty cols 200; go run . --help"
+	@go run . --statement-help > tmp/statement_help.txt
+	@sed '1s/^...//' tmp/help_output.txt > tmp/help_clean.txt
+	@echo "✅ Help output files generated successfully in ./tmp/"
+	@echo "📋 Generated files:"
+	@echo "   - help_clean.txt: --help output for README.md"
+	@echo "   - statement_help.txt: --statement-help output for README.md"
+
+# Show development help
+help-dev:
+	@echo "🛠️  Development Commands:"
+	@echo "  make build            - Build the application"
+	@echo "  make build-tools      - Install gh-helper using Go 1.24 tool management"
+	@echo "  make test             - Run full test suite (required before push)"
+	@echo "  make test-coverage    - Run tests with coverage profile (for CI)"
+	@echo "  make test-quick       - Run quick tests (go test -short)"
+	@echo "  make lint             - Run linter (required before push)"
+	@echo "  make check            - Run test && lint (required before push)"
+	@echo "  make clean            - Clean build artifacts and test cache"
+	@echo "  make run              - Run with PROJECT/INSTANCE/DATABASE env vars"
+	@echo "  make docs-update      - Generate help output for README.md"
+	@echo "  make worktree-setup   - Setup phantom worktree (requires WORKTREE_NAME)"
+	@echo "  make worktree-list    - List existing phantom worktrees"
+	@echo "  make worktree-delete  - Delete phantom worktree (requires WORKTREE_NAME)"
+	@echo ""
+	@echo "🔧 Development Tools:"
+	@echo "  go tool gh-helper     - GitHub operations (managed via go.mod tool directive)"
+	@echo ""
+	@echo "🚀 Quick Start for AI Assistants:"
+	@echo "  gh pr create && go tool gh-helper reviews wait  # Create PR + wait for review"
+	@echo "  go tool gh-helper reviews wait <PR> --request-review  # Request Gemini review + wait"
+
+# Phantom worktree management (replacing spanner-mycli-dev)
+worktree-setup:
+	@if [ -z "$(WORKTREE_NAME)" ]; then \
+		echo "❌ WORKTREE_NAME required. Usage: make worktree-setup WORKTREE_NAME=issue-123-feature"; \
+		exit 1; \
+	fi
+	@echo "🔧 Creating phantom worktree: $(WORKTREE_NAME)"
+	@git fetch origin
+	@phantom create $(WORKTREE_NAME) --base origin/main --exec "ln -sf ../../../../.claude .claude"
+	@echo "✅ Worktree created successfully!"
+	@echo "📋 Next: phantom shell $(WORKTREE_NAME) --tmux-horizontal"
+
+worktree-list:
+	@phantom list
+
+worktree-delete:
+	@if [ -z "$(WORKTREE_NAME)" ]; then \
+		echo "❌ WORKTREE_NAME required. Usage: make worktree-delete WORKTREE_NAME=issue-123-feature"; \
+		exit 1; \
+	fi
+	@echo "🔍 Checking status of worktree: $(WORKTREE_NAME)"
+	@phantom exec $(WORKTREE_NAME) git status --porcelain
+	@echo "🗑️  Deleting worktree: $(WORKTREE_NAME)"
+	@phantom delete $(WORKTREE_NAME)
+	@echo "✅ Worktree deleted successfully"
+
+# GitHub review monitoring (requires PR_NUMBER)
+gh-review:
+	@if [ -z "$(PR_NUMBER)" ]; then \
+		echo "❌ PR_NUMBER required. Usage: make gh-review PR_NUMBER=123"; \
+		exit 1; \
+	fi
+	@go tool gh-helper reviews analyze $(PR_NUMBER) --timeout 15m
diff --git a/README.md b/README.md
@@ -92,7 +92,7 @@ https://github.com/apstndb/spanner-mycli/pkgs/container/spanner-mycli
 
 ## Usage
 
-<!-- Content from ./tmp/help_clean.txt. Generated by: scripts/docs/update-help-output.sh -->
+<!-- Content from ./tmp/help_clean.txt. Generated by: make docs-update -->
 ```
 Usage:
   spanner-mycli [OPTIONS]
@@ -382,7 +382,7 @@ and `{A|B|...}` for a mutually exclusive keyword.
 
 * The syntax is case-insensitive.
 
-<!-- Generated with: scripts/docs/update-help-output.sh -->
+<!-- Generated with: make docs-update -->
 | Usage                                                           | Syntax                                                                                                     | Note                                                                                                                                                                       |
 |:----------------------------------------------------------------|:-----------------------------------------------------------------------------------------------------------|:---------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
 | Switch database                                                 | `USE <database> [ROLE <role>];`                                                                            | The role you set is used for accessing with [fine-grained access control](https://cloud.google.com/spanner/docs/fgac-about).                                               |

diff --git a/dev-docs/README.md b/dev-docs/README.md
@@ -32,20 +32,17 @@ dev-docs/
 - Context and session management
 
 ### [Issue Management](issue-management.md)
-- GitHub issue workflow
-- Pull request process
-- Code review strategies
-- Git best practices
+- Development tools usage (Go 1.24 tool management)
+- GitHub issue workflow and labeling
+- Pull request process and code review
+- Gemini AI review integration
+- Git best practices and phantom worktree management
 - Knowledge management through PR comments
 
-<<<<<<< HEAD
-=======
 ### [Coding Guidelines](coding-guidelines.md)
 - Go language standards and conventions
 - Project-specific coding rules
 - Current deviations and future improvements
-
->>>>>>> origin/main
 ### [Patterns](patterns/)
 - [System Variables](patterns/system-variables.md) - Implementation patterns for system variables, timeout management, and testing strategies
 
@@ -71,7 +68,7 @@ dev-docs/
 
 ```bash
 # Generate help output files
-scripts/docs/update-help-output.sh
+make docs-update
 
 # Files are generated in ./tmp/
 # - help_clean.txt: Content for README.md --help section (lines 97-135)

diff --git a/dev-docs/architecture-guide.md b/dev-docs/architecture-guide.md
@@ -261,7 +261,7 @@ spanner-mycli/
 ├── testdata/                        # Test fixtures
 ├── docs/                            # User documentation
 ├── dev-docs/                        # Developer documentation
-├── scripts/                         # Automation scripts
+├── bin/                             # Development tool symlinks (created by make build-tools)
 └── official_docs/                   # Upstream documentation
 ```