From 75a8ded0432dd37e06de65a549bf677257a229b4 Mon Sep 17 00:00:00 2001 From: Adam Jeniski Date: Mon, 5 Jan 2026 02:23:21 -0500 Subject: [PATCH] add skills --- CLAUDE.md | 111 +++++++++++++++++++++++++++++++++++++++++++++ skills/README.md | 35 ++++++++++++++ skills/commitly.md | 68 +++++++++++++++++++++++++++ 3 files changed, 214 insertions(+) create mode 100644 CLAUDE.md create mode 100644 skills/README.md create mode 100644 skills/commitly.md diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..ce65ccb --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,111 @@ +# CLAUDE.md + +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. + +## Overview + +Commitly is a Babashka CLI tool for managing commits across multiple independent git repositories within a monorepo structure. It automates committing and pushing changes that span multiple subrepos with a single command. + +## Architecture + +### Core Concept + +The tool operates on a "monorepo of repos" pattern where: +- The parent directory contains multiple subdirectories, each with its own `.git` directory +- Each subrepo is an independent git repository (not git submodules) +- Changes often span multiple repositories and need consistent commit messages + +### Code Structure + +The entire implementation is a single Babashka script (`commitly`) with these key functions: + +- `find-subrepos` - Discovers all directories containing `.git` in the current directory +- `has-changes?` - Uses `git status --porcelain` to detect uncommitted changes +- `commit-changes` - Executes `git add -A` and `git commit -m` for a repo +- `push-changes` - Executes `git push` for a repo +- `commitly` - Main orchestration function that coordinates the workflow +- `-main` - CLI argument parsing and entry point + +### Workflow + +1. Scan current directory for subdirectories with `.git` folders +2. Filter to only repos with uncommitted changes +3. For each modified repo: stage all changes and commit with provided message +4. If `-p` flag is present, push each successfully committed repo +5. Report success/failure for each repository + +## Common Commands + +### Basic Usage + +```bash +# Commit changes across all modified subrepos +./commitly "commit message" + +# Commit and push changes +./commitly -p "commit message" + +# Push only (no commit) - useful after manual commits +./commitly -p +``` + +### Running via Babashka Tasks + +```bash +# Alternative way to run using bb.edn tasks +bb run "commit message" +``` + +### Development + +The script is self-contained with no external dependencies beyond Babashka standard library (`babashka.process`, `babashka.fs`). To modify: + +1. Edit the `commitly` script directly +2. Test changes by running `./commitly` with test arguments +3. The script is executable via shebang `#!/usr/bin/env bb` + +## Important Implementation Details + +### Error Handling + +- Each repository operation is independent - one failure doesn't stop others +- Failed commits/pushes are collected and reported at the end +- Non-zero exit code (1) if any operations fail +- Empty commit message validation prevents accidental empty commits + +### Special `-p` Flag Behavior + +The `-p` flag has dual behavior: +- With commit message: commits then pushes +- Without commit message: pushes only (skips committing) + +This allows workflows like: +```bash +# Manual commits in individual repos, then bulk push +cd service-manager && git commit -m "specific message" +cd ../www && git commit -m "different message" +cd .. +./commitly -p # Push all repos +``` + +### Process Execution + +Uses `babashka.process/shell` with: +- `:continue true` - Allows capturing errors without throwing exceptions +- `:dir` - Sets working directory for each git command +- `:out :string` and `:err :string` - Captures output for reporting + +## Context: Monorepo Usage + +This tool is designed for the ajet-industries monorepo which contains: +- `service-manager/` - Clojure orchestration service +- `www/` - Clojure dashboard website +- `gateway/` - Nginx reverse proxy configuration +- `commitly/` - This tool itself +- Other independent service repos + +Each subrepo has its own git remote and CI/CD pipeline (Gitea Actions). When a cross-cutting change is made (e.g., updating CLAUDE.md files, shared configuration), commitly ensures all affected repos get consistent commit messages. + +## Skills Integration + +The `skills/` directory contains documentation for Claude Code skills. When working on commitly functionality or explaining its usage to users, reference `skills/commitly.md` for detailed usage patterns and examples. diff --git a/skills/README.md b/skills/README.md new file mode 100644 index 0000000..c732b6b --- /dev/null +++ b/skills/README.md @@ -0,0 +1,35 @@ +# Skills + +This directory contains Claude Code skills for working with the ajet-industries monorepo. + +## Available Skills + +### commitly +Explains how to use the commitly tool for committing and pushing changes across multiple git repositories in the monorepo. + +**Invoke with:** Reference the `skills/commitly.md` file when needing to commit/push across multiple repos. + +## What are Skills? + +Skills are reusable documentation and instructions that help Claude Code understand how to work with specific tools and workflows in this repository. + +## Creating New Skills + +To create a new skill: + +1. Create a new `.md` file in this directory +2. Include clear sections: + - What the tool/workflow is + - Usage examples + - How it works + - When to use it + - Architecture context (if relevant) +3. Update this README with the new skill + +## Skill Guidelines + +- Keep skills focused on a single tool or workflow +- Include practical examples +- Explain the "why" not just the "how" +- Reference relevant architecture documentation +- Include error handling and troubleshooting info diff --git a/skills/commitly.md b/skills/commitly.md new file mode 100644 index 0000000..d106dd5 --- /dev/null +++ b/skills/commitly.md @@ -0,0 +1,68 @@ +# Commitly Skill + +Use this skill when you need to commit and/or push changes across multiple git repositories in the monorepo. + +## What is Commitly? + +Commitly is a Babashka script located at `commitly/commitly` that commits and pushes changes across all modified git subrepositories in the ajet-industries monorepo. + +## Usage + +```bash +./commitly/commitly [-p] +``` + +### Options + +- `-p` - Push changes after committing. If no commit message is provided with `-p`, it will skip committing and just push all subrepos. + +### Examples + +**Commit all modified repos with a message:** +```bash +./commitly/commitly "fix: update configuration" +``` + +**Commit and push all modified repos:** +```bash +./commitly/commitly -p "feat: add new feature" +``` + +**Just push all repos (no commit):** +```bash +./commitly/commitly -p +``` + +## How It Works + +1. **Discovery**: Scans the current directory for subdirectories containing `.git` folders +2. **Detection**: Checks each repository for uncommitted changes using `git status --porcelain` +3. **Commit**: Runs `git add -A` and `git commit -m ""` for each modified repo +4. **Push**: If `-p` flag is present, runs `git push` for each successfully committed repo (or all repos if no message provided) + +## When to Use + +Use commitly when you've made changes across multiple services (service-manager, www, gateway, etc.) and want to commit them all with the same message, rather than cd-ing into each directory individually. + +## Architecture Context + +The monorepo contains multiple independent git repositories: +- `service-manager/` - Orchestration service +- `www/` - Dashboard website +- `gateway/` - Nginx reverse proxy +- `commitly/` - This tool itself +- `just-vibes/` - Other projects + +Each has its own `.git` directory and is deployed independently via Gitea Actions when pushed to main. + +## Error Handling + +- If any repository fails to commit, commitly exits with code 1 and reports which repos failed +- If any repository fails to push (when `-p` is used), commitly exits with code 1 and reports which repos failed +- Repos are processed independently - one failure doesn't stop others from being processed + +## Requirements + +- Babashka must be installed (`bb` command available) +- The script must be executable: `chmod +x commitly/commitly` +- Each subrepo must have a git remote configured for pushing