From fa8dcb89dd1107d7e839c629177dd5f9974cec2d Mon Sep 17 00:00:00 2001 From: database-tycoon Date: Tue, 23 Dec 2025 08:36:31 -0500 Subject: [PATCH] feat: Add snowtower-maintainer Claude Code skill MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Creates a specialized skill for maintaining SnowTower project: - README maintenance and statistics updates - .claude folder organization and agent auditing - Documentation sync procedures - Self-maintenance capabilities Includes PROJECT_STRUCTURE.md reference document. Closes #12 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude --- .../snowtower-maintainer/PROJECT_STRUCTURE.md | 71 ++++++ .claude/skills/snowtower-maintainer/SKILL.md | 205 ++++++++++++++++++ 2 files changed, 276 insertions(+) create mode 100644 .claude/skills/snowtower-maintainer/PROJECT_STRUCTURE.md create mode 100644 .claude/skills/snowtower-maintainer/SKILL.md diff --git a/.claude/skills/snowtower-maintainer/PROJECT_STRUCTURE.md b/.claude/skills/snowtower-maintainer/PROJECT_STRUCTURE.md new file mode 100644 index 0000000..48fd208 --- /dev/null +++ b/.claude/skills/snowtower-maintainer/PROJECT_STRUCTURE.md @@ -0,0 +1,71 @@ +# SnowTower Project Structure Reference + +Quick reference for the maintainer skill. + +## Directory Layout + +``` +snowtower/ +├── .claude/ # Claude Code configuration +│ ├── skills/ # Skills (model-invoked capabilities) +│ │ └── snowtower-maintainer/ +│ ├── agents/ # Agent definitions +│ └── patterns/ # Reusable patterns +├── .github/ # GitHub configuration +│ ├── workflows/ # CI/CD workflows +│ │ ├── ci.yml # PR validation +│ │ ├── labeler.yml # Auto-labeling +│ │ ├── changelog.yml # Changelog generation +│ │ └── release.yml # Release automation +│ ├── ISSUE_TEMPLATE/ # Issue templates +│ └── PULL_REQUEST_TEMPLATE.md +├── snowddl/ # SnowDDL YAML configurations +│ ├── user.yaml # User accounts +│ ├── business_role.yaml # Business roles +│ ├── tech_role.yaml # Technical roles +│ ├── warehouse.yaml # Warehouses +│ ├── *_policy.yaml # Security policies +│ └── {DATABASE}/ # Database-specific configs +├── src/ # Python source code +│ ├── snowddl_core/ # OOP framework +│ ├── user_management/ # User lifecycle +│ ├── web/ # Streamlit apps +│ └── management_cli.py # CLI entry points +├── scripts/ # Standalone scripts +├── tests/ # Test suite +├── docs/ # Documentation +│ ├── guide/ # User guides +│ ├── agents/ # Agent documentation +│ └── releases/ # Release documentation +├── pyproject.toml # Project configuration +├── README.md # Main documentation +└── CLAUDE.md # Claude Code instructions +``` + +## Key Files to Monitor + +| File | Purpose | Update Frequency | +|------|---------|------------------| +| `README.md` | Main project documentation | After features/releases | +| `CLAUDE.md` | Claude Code instructions | When patterns change | +| `pyproject.toml` | Commands and dependencies | When adding commands | +| `.claude/agents/*.md` | Agent definitions | When capabilities change | +| `docs/guide/*.md` | User guides | When workflows change | + +## Current Statistics (Update These) + +```yaml +# Last updated: 2024-XX-XX +users: ~13 +databases: ~6 +warehouses: ~8 +agents: ~20+ +workflows: 4 +``` + +## Maintenance Schedule + +- **Weekly**: Check for broken links, outdated statistics +- **Per Release**: Full documentation audit +- **Per Feature**: Update relevant docs and README +- **Quarterly**: Agent consolidation review diff --git a/.claude/skills/snowtower-maintainer/SKILL.md b/.claude/skills/snowtower-maintainer/SKILL.md new file mode 100644 index 0000000..79a2a5d --- /dev/null +++ b/.claude/skills/snowtower-maintainer/SKILL.md @@ -0,0 +1,205 @@ +--- +name: snowtower-maintainer +description: Maintains SnowTower project documentation, README, and Claude configuration. Use when updating documentation, auditing .claude folder contents, syncing README with actual project state, or reviewing agent/pattern definitions. Triggers on mentions of documentation, README, maintenance, or .claude folder updates. +--- + +# SnowTower Project Maintainer + +A specialized skill for maintaining the SnowTower project's documentation, README, and Claude Code configuration. + +## Core Responsibilities + +### 1. README Maintenance + +Keep `README.md` accurate and current: + +- **Version badges**: Ensure CI/CD badges point to correct workflows +- **Command references**: Verify all `uv run` commands are valid +- **Architecture diagrams**: Keep mermaid diagrams in sync with actual structure +- **Statistics**: Update user counts, database counts, warehouse counts +- **Links**: Verify all internal links resolve correctly + +**Audit checklist:** +```bash +# Verify commands mentioned in README actually exist +uv run --help | grep -E "snowddl-plan|deploy-safe|manage-users" + +# Check workflow badge URLs match actual workflow files +ls .github/workflows/ + +# Verify documentation links +find docs/ -name "*.md" | head -20 +``` + +### 2. Claude Folder Maintenance + +Maintain `.claude/` organization: + +``` +.claude/ +├── skills/ # Claude Code skills (like this one) +├── agents/ # Agent definitions for task delegation +├── patterns/ # Reusable patterns and templates +└── settings.local.json +``` + +**Agent audit tasks:** +- Remove duplicate or redundant agents +- Consolidate agents with overlapping purposes +- Update agent descriptions to match current capabilities +- Ensure agents reference correct file paths + +**Pattern audit tasks:** +- Verify patterns match current project conventions +- Update code examples in patterns +- Remove outdated patterns + +### 3. Documentation Sync + +Ensure docs reflect actual project state: + +| Doc File | Should Match | +|----------|--------------| +| `docs/guide/MANAGEMENT_COMMANDS.md` | `pyproject.toml` scripts | +| `docs/guide/QUICKSTART.md` | Current setup process | +| `docs/guide/SCHEMA_GRANTS.md` | Current grant handling | +| Agent files in `.claude/agents/` | Available functionality | + +## Maintenance Procedures + +### Quick Health Check + +```bash +# 1. Verify project structure +ls -la snowddl/ src/ scripts/ docs/ + +# 2. Check available commands +uv run --help + +# 3. Verify tests pass +uv run pytest --co -q | tail -5 + +# 4. Check pre-commit status +uv run pre-commit run --all-files +``` + +### README Update Workflow + +1. **Gather current state:** + ```bash + # Count configured users + grep -c "^ [A-Z]" snowddl/user.yaml + + # Count databases + ls -d snowddl/*/ | grep -v __pycache__ | wc -l + + # List warehouses + grep "^ [A-Z]" snowddl/warehouse.yaml + ``` + +2. **Verify commands:** + ```bash + # Extract commands from pyproject.toml + grep -A1 "\[project.scripts\]" pyproject.toml + ``` + +3. **Update statistics section** in README with current counts + +4. **Verify all links** resolve to existing files + +### Agent Consolidation + +When auditing `.claude/agents/`: + +1. **List all agents:** + ```bash + ls .claude/agents/*.md + ``` + +2. **Identify overlaps:** Look for agents with similar purposes + +3. **Consolidation criteria:** + - Merge agents that serve the same domain + - Keep agents with distinct, valuable roles + - Remove agents that duplicate built-in capabilities + +4. **Update references:** After consolidation, update any docs referencing removed agents + +### Self-Maintenance + +This skill should maintain itself by: + +1. Keeping this SKILL.md up to date with project changes +2. Adding new maintenance procedures as project evolves +3. Updating file paths when project structure changes +4. Documenting new patterns discovered during maintenance + +## Common Maintenance Tasks + +### Task: Update README Statistics + +```markdown +### Status & Metrics + +- **Active Users**: [COUNT] configured users with MFA +- **Databases**: [COUNT] production databases managed +- **Warehouses**: [COUNT] warehouses with auto-suspend +``` + +Update these by running: +```bash +echo "Users: $(grep -c '^ [A-Z]' snowddl/user.yaml)" +echo "Databases: $(ls -d snowddl/*/ 2>/dev/null | grep -v __pycache__ | wc -l)" +echo "Warehouses: $(grep -c '^ [A-Z]' snowddl/warehouse.yaml)" +``` + +### Task: Verify Workflow Badges + +Check that README badges match actual workflows: +```bash +# List workflows +ls .github/workflows/ + +# Verify badge URLs in README reference these files +grep "actions/workflows" README.md +``` + +### Task: Audit Agent Definitions + +```bash +# List agents and their purposes +for f in .claude/agents/*.md; do + echo "=== $f ===" + head -5 "$f" + echo +done +``` + +### Task: Clean Up Obsolete Content + +Remove references to: +- Deleted files or directories +- Deprecated commands +- Old workflow names +- Removed features + +## Integration with Project + +This skill works with: + +- **CI/CD workflows**: `.github/workflows/` +- **SnowDDL configs**: `snowddl/*.yaml` +- **Python tooling**: `src/`, `scripts/` +- **Documentation**: `docs/` +- **Claude config**: `.claude/` + +## When to Trigger + +Invoke this skill when: +- User asks to "update the README" +- User mentions "documentation maintenance" +- User wants to "audit the .claude folder" +- User asks about "project documentation" +- After significant feature additions +- Before releases to ensure docs are current +- When onboarding new contributors