Skip to content

Commit 35438f3

Browse files
atxtechbroatxtechbro
authored
feat: implement sync and cleanup for Claude commands (#1291)
* feat: implement sync and cleanup for Claude commands Closes #1285 - Add sync-claude-commands.sh tool to detect and clean orphaned commands - Integrate auto-cleanup into generate-commands.sh - Add CI/CD validation for command synchronization - Create pre-commit hook for command validation - Configure git hooks in setup.sh - Add comprehensive documentation for command lifecycle management This prevents orphaned commands when renaming/iterating and maintains a clean command infrastructure following systems-stewardship and subtraction-creates-value principles. * docs: make command lifecycle doc more succinct for context window
1 parent 9882a7c commit 35438f3

7 files changed

Lines changed: 477 additions & 0 deletions

File tree

‎.githooks/pre-commit‎

Lines changed: 62 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,62 @@
1+
#!/bin/bash
2+
# Pre-commit hook to validate Claude command synchronization
3+
# Principles: systems-stewardship, defensive-programming
4+
5+
set -euo pipefail
6+
7+
# Colors for output
8+
RED='\033[0;31m'
9+
GREEN='\033[0;32m'
10+
YELLOW='\033[1;33m'
11+
NC='\033[0m' # No Color
12+
13+
# Get the repository root
14+
REPO_ROOT="$(git rev-parse --show-toplevel)"
15+
SYNC_SCRIPT="$REPO_ROOT/utils/sync-claude-commands.sh"
16+
17+
# Check if any command template files are being committed
18+
if git diff --cached --name-only | grep -q ".claude/command-templates/.*\.md$"; then
19+
echo -e "${YELLOW}⚠${NC} Command templates modified, checking synchronization..."
20+
21+
# Check if sync script exists
22+
if [[ ! -x "$SYNC_SCRIPT" ]]; then
23+
echo -e "${YELLOW}⚠${NC} Warning: sync-claude-commands.sh not found or not executable"
24+
echo "Skipping command sync validation"
25+
exit 0
26+
fi
27+
28+
# Run sync check
29+
if ! "$SYNC_SCRIPT" --check > /dev/null 2>&1; then
30+
echo -e "${RED}✗${NC} Claude commands are out of sync!"
31+
echo
32+
"$SYNC_SCRIPT" --check
33+
echo
34+
echo "To fix this issue, run:"
35+
echo " ./utils/generate-commands.sh"
36+
echo
37+
echo "Or to just clean orphaned commands:"
38+
echo " ./utils/sync-claude-commands.sh --clean"
39+
echo
40+
echo "Then stage the changes and commit again."
41+
exit 1
42+
fi
43+
44+
echo -e "${GREEN}✓${NC} Claude commands are synchronized"
45+
fi
46+
47+
# Check if generate-commands.sh was modified
48+
if git diff --cached --name-only | grep -q "utils/generate-commands.sh"; then
49+
echo -e "${YELLOW}⚠${NC} Command generator modified, regenerating commands..."
50+
51+
# Run the generator to ensure consistency
52+
if [[ -x "$REPO_ROOT/utils/generate-commands.sh" ]]; then
53+
"$REPO_ROOT/utils/generate-commands.sh"
54+
echo -e "${GREEN}✓${NC} Commands regenerated successfully"
55+
echo
56+
echo "Note: If new command files were generated, you may need to:"
57+
echo " git add ~/.claude/commands/*.md"
58+
echo " git commit --amend"
59+
fi
60+
fi
61+
62+
exit 0

‎.github/workflows/validate-dotfiles.yml‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -83,3 +83,21 @@ jobs:
8383
git config --list || exit 1
8484
8585
echo "All configurations validated successfully"
86+
87+
- name: Validate Claude commands sync
88+
run: |
89+
export HOME=/tmp/test-home
90+
91+
echo "Checking Claude command synchronization..."
92+
cd $HOME/ppv/pillars/dotfiles
93+
94+
# Run the sync check
95+
if [[ -x utils/sync-claude-commands.sh ]]; then
96+
utils/sync-claude-commands.sh --check || {
97+
echo "Error: Claude commands are out of sync!"
98+
echo "Run 'utils/sync-claude-commands.sh --clean' locally to fix"
99+
exit 1
100+
}
101+
else
102+
echo "Warning: sync-claude-commands.sh not found, skipping check"
103+
fi

‎README.md‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -286,6 +286,24 @@ To modify a slash command:
286286
2. Run `utils/generate-commands.sh` (automatically run by `source setup.sh`)
287287
3. The updated command is available in all configured AI providers
288288

289+
**Command Lifecycle Management**:
290+
- **Sync Tool**: `utils/sync-claude-commands.sh` detects and cleans orphaned commands
291+
- **Auto-Cleanup**: `generate-commands.sh` automatically removes orphaned commands before generation
292+
- **CI Validation**: GitHub Actions verify command synchronization on every push
293+
- **Pre-commit Hook**: Ensures commands stay synchronized (enable with `git config core.hooksPath .githooks`)
294+
295+
To check command synchronization:
296+
```bash
297+
# Check for orphaned or missing commands
298+
utils/sync-claude-commands.sh --check
299+
300+
# Clean orphaned commands
301+
utils/sync-claude-commands.sh --clean
302+
303+
# Regenerate all commands (includes auto-cleanup)
304+
utils/generate-commands.sh
305+
```
306+
289307
**Principle**: This vendor-agnostic approach follows `systems-stewardship` - building reusable patterns across tools.
290308

291309
### Claude Code Settings

‎knowledge/procedures/command-lifecycle-management.md‎

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
# Command Lifecycle Management
2+
3+
Prevents orphaned Claude commands when renaming/iterating. Principles: systems-stewardship, subtraction-creates-value.
4+
5+
## Tools
6+
7+
```bash
8+
utils/sync-claude-commands.sh --check # Detect orphaned/missing
9+
utils/sync-claude-commands.sh --clean # Remove orphaned
10+
utils/generate-commands.sh # Auto-cleans + generates
11+
```
12+
13+
## Lifecycle
14+
15+
1. **Create**: Add template to `.claude/command-templates/*.md`
16+
2. **Generate**: Run `utils/generate-commands.sh` → outputs to `~/.claude/commands/`
17+
3. **Rename**: Rename template file + regenerate (auto-removes old)
18+
4. **Delete**: Remove template + regenerate (auto-cleans orphaned)
19+
20+
## Validation Layers
21+
22+
- **Pre-commit hook**: `.githooks/pre-commit` (auto-configured by setup.sh)
23+
- **CI/CD**: `validate-dotfiles.yml` runs sync check
24+
- **Manual**: `utils/sync-claude-commands.sh --check`
25+
26+
## Quick Fixes
27+
28+
```bash
29+
# CI failing on sync?
30+
utils/generate-commands.sh
31+
git add -A && git commit --amend
32+
33+
# Orphaned commands persist?
34+
utils/sync-claude-commands.sh --clean
35+
```
36+
37+
## Architecture
38+
39+
```
40+
.claude/command-templates/*.md → generate-commands.sh → ~/.claude/commands/*.md
41+
↓
42+
sync-claude-commands.sh (cleanup)

‎setup.sh‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -623,6 +623,16 @@ fi
623623
# echo -e "${YELLOW}start-mcp-dashboard script not found. Skipping dashboard setup.${NC}"
624624
# fi
625625

626+
# Configure git hooks
627+
if [[ -d "$DOT_DEN/.githooks" ]]; then
628+
echo "Configuring git hooks..."
629+
# Set the git hooks path for the dotfiles repository
630+
(cd "$DOT_DEN" && git config core.hooksPath .githooks)
631+
echo -e "${GREEN}Git hooks configured for command synchronization validation${NC}"
632+
else
633+
echo -e "${YELLOW}Git hooks directory not found. Skipping hooks configuration.${NC}"
634+
fi
635+
626636
echo -e "${DIVIDER}"
627637
echo -e "${GREEN}✅ Dotfiles setup complete!${NC}"
628638
echo "Your development environment is now configured and ready to use."

‎utils/generate-commands.sh‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -62,6 +62,15 @@ fi
6262
# Track if any templates were processed
6363
TEMPLATES_PROCESSED=0
6464

65+
# Run cleanup before generating new commands
66+
echo "Running cleanup to remove orphaned commands..."
67+
if [[ -x "$SCRIPT_DIR/sync-claude-commands.sh" ]]; then
68+
"$SCRIPT_DIR/sync-claude-commands.sh" --clean
69+
else
70+
echo "Warning: sync-claude-commands.sh not found or not executable"
71+
fi
72+
echo
73+
6574
# Process templates for each provider
6675
for config in "${PROVIDER_CONFIGS[@]}"; do
6776
provider="${config%%:*}"

0 commit comments

Comments
 (0)