From OctoMesh Skills
Structured workflow for committing finished work across OctoMesh repositories: scans repos for changes, resolves or creates the Azure DevOps work item, builds the AB# commit message, verifies the build/tests, and optionally opens a PR. Enforces the review checkpoint — never pushes or opens a PR without explicit user approval in the current session. Trigger on: commit, push, PR, pull request, merge, finish work, done, ship it, wrap up, AB#, work item, ready to commit, close task, create branch, feature branch, dev/, Azure DevOps.
How this skill is triggered — by the user, by Claude, or both
Slash command
/octo-claude-skills:octo-commitThis skill is limited to the following tools:
The summary Claude sees in its skill listing — used to decide when to auto-load this skill
Structured workflow for committing finished work across OctoMesh repositories with Azure DevOps work item linking, verification, and optional PR creation.
Structured workflow for committing finished work across OctoMesh repositories with Azure DevOps work item linking, verification, and optional PR creation.
Never push or create a PR without explicit user approval given in the CURRENT session. This is a firm convention from the repo owner.
git push / gh pr create / az repos pr create.AB#<WorkItemId> <New|Fix>: <Description>
| Work Item Type | Prefix | Example |
|---|---|---|
| Issue / Epic | New | AB#4521 New: Add pipeline validation endpoint |
| Task | New (default) | AB#4081 New: Add blueprint variables |
| Bug | Fix | AB#4493 Fix: Resolve null reference in CK compilation |
New and Fix cover the overwhelming majority of OctoMesh commits. Task has no distinct prefix convention in the git history — default to New and confirm the prefix with the user if the change is clearly a correction (then Fix).
Description: imperative mood, concise (e.g., "Add validation" not "Added validation").
| Workflow | Pattern | Example |
|---|---|---|
| Feature branch | dev/<username>/<feature-name> | dev/reimar/implement-skill |
| Direct to main | no branch creation | only for small, confirmed low-risk changes |
Derive <username> from git config user.name (first name, lowercase). Derive <feature-name> from the work item title or change context (kebab-case).
digraph commit_flow {
rankdir=TB;
node [shape=box];
scan [label="1. Scan repos for changes"];
context [label="2. Understand change context"];
claudemd [label="3. Read CLAUDE.md per repo"];
workitem [label="4. Find or create work item"];
strategy [label="5. Choose commit strategy"];
verify [label="6. Verify completion"];
approve [label="7. REVIEW CHECKPOINT: get explicit approval"];
execute [label="8. Commit and push"];
pr [label="9. Create PR"];
scan -> context -> claudemd -> workitem -> strategy -> verify -> approve -> execute;
execute -> pr [label="if feature branch"];
}
Find the monorepo root (directory containing octo-tools/) by walking up from the current working directory. Then scan every git repo for uncommitted changes:
# From the monorepo root
for dir in */; do
if [ -d "$dir/.git" ]; then
changes=$(git -C "$dir" status --porcelain 2>/dev/null)
if [ -n "$changes" ]; then
echo "=== $dir ==="
echo "$changes"
fi
fi
done
Report ALL repos with changes. Do not skip any. Also check for unpushed commits:
git -C "$dir" log --oneline @{upstream}..HEAD 2>/dev/null
Gather context from (priority order):
git diff and git diff --staged in each changed repoIf context is unclear, use AskUserQuestion:
"I found changes in [repos]. Can you briefly describe what you worked on?"
For every repo with pending changes:
<repo>/CLAUDE.md if it existsDebugL for OctoMesh .NET repos)IMPORTANT: Follow repo-specific conventions from CLAUDE.md. They override defaults.
Azure DevOps context: Organization meshmakers, Project OctoMesh.
Resolution order:
dev/reimar/AB1234-feature)az boards query \
--wiql "SELECT [System.Id], [System.Title], [System.WorkItemType], [System.State] \
FROM WorkItems \
WHERE [System.TeamProject] = 'OctoMesh' \
AND [System.Title] CONTAINS '<keyword>' \
AND [System.State] <> 'Closed' \
ORDER BY [System.ChangedDate] DESC" \
--org https://dev.azure.com/meshmakers
CRITICAL: The WIQL command is az boards query — there is no az boards work-item query subcommand (az boards work-item only has create/delete/show/update).
Work item types: Bug, Issue (features), Epic, Task.
Present matching work items to the user with AskUserQuestion if multiple matches found.
If no matching work item exists, ask user whether to create one. If yes, gather the following via AskUserQuestion:
OctoMesh Azure DevOps teams (use the exact names):
Solutions Team (plural), Product Team, CustomerProjects Team, Sales Team, BizOps Team, Energy Solution Team.
# List available iterations for a team
az boards iteration team list \
--team "Solutions Team" \
--org https://dev.azure.com/meshmakers \
--project OctoMesh
# List available areas for a team
az boards area team list \
--team "Solutions Team" \
--org https://dev.azure.com/meshmakers \
--project OctoMesh
Create the work item (Mutating — confirm with user first):
az boards work-item create \
--type "<Type>" \
--title "<Title>" \
--area "<AreaPath>" \
--iteration "<IterationPath>" \
--org https://dev.azure.com/meshmakers \
--project OctoMesh
Use AskUserQuestion if not already clear from context: Direct to main (small, low-risk) or Feature branch + PR (standard).
For a feature branch, create it using the Branch Naming convention above:
git -C <repo> checkout -b dev/<username>/<feature-name>
Before committing, verify the work is ready. For each changed repo, check based on its CLAUDE.md:
For .NET repos:
dotnet build <solution>.sln --configuration DebugL
dotnet test <solution>.sln --configuration DebugL
For Angular/frontend repos:
npm run lint
npm test -- --watch=false
If build or tests fail, use AskUserQuestion:
"Build/tests failed in [repo]: [error summary]. Fix first, or proceed anyway?"
For significant changes, ask about documentation:
"Does this change need documentation updates?"
Before any git push / gh pr create / az repos pr create, you must have explicit approval in the current session. Show the user what will happen via AskUserQuestion:
Ready to commit and push:
- Repo: [repo-name]
- Message:
AB#1234 New: Add pipeline validation- Files: [file list or summary]
- Branch: main / dev/reimar/feature-name
- Will push + open PR: yes/no
If the user defers ("I'll look at it later"), STOP — you may commit locally only if explicitly asked, but do not push or open a PR.
Build the commit message using the format AB#<id> <New|Fix>: <Description>.
Co-Authored-By convention: OctoMesh repos use a model-specific trailer of the form
Co-Authored-By: Claude <model name> <[email protected]> — not a bare Claude. Use the
running model's name, e.g. Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>.
For each repo with changes:
# Stage changes (prefer specific files over -A when possible)
git -C <repo> add <specific-files>
# Commit with heredoc for proper formatting
git -C <repo> commit -m "$(cat <<'EOF'
AB#<id> <New|Fix>: <Description>
Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
EOF
)"
# First push of a new branch MUST set upstream with -u
git -C <repo> push -u origin <branch>
# Subsequent pushes (upstream already set)
git -C <repo> push
CRITICAL: The initial push of a freshly created feature branch requires -u
(git push -u origin <branch>) to set the upstream tracking ref; later pushes can use a bare git push.
NEVER force-push to main. Always confirm before pushing (see Review Checkpoint).
For GitHub repos (majority of OctoMesh repos):
gh pr create \
--repo meshmakers/<repo-name> \
--title "AB#<id> <New|Fix>: <Description>" \
--body "$(cat <<'EOF'
## Summary
- <bullet points of changes>
## Azure DevOps Work Item
AB#<id>
## Test Plan
- [ ] Build passes (DebugL)
- [ ] Unit + integration tests pass
- [ ] Manual verification done
Generated with [Claude Code](https://claude.ai/code)
EOF
)"
For Azure DevOps repos (e.g., meshmakers_staging). Use --work-items to link the PR
directly to the ADO work item (space-separated IDs):
az repos pr create \
--repository <repo-name> \
--source-branch <branch> \
--target-branch main \
--title "AB#<id> <New|Fix>: <Description>" \
--work-items <id> \
--org https://dev.azure.com/meshmakers \
--project OctoMesh
Report the PR URL(s) to the user when done.
When changes span multiple repos:
Most octo-* repos live at meshmakers/<repo> on GitHub (gh pr create). meshmakers_staging
is the sole Azure DevOps-hosted repo (az repos pr create). pipeline-editor, docs,
zenon-dynprop-api, and aspire-management-prototype are under reikla/ on GitHub.
CRITICAL: The local directory docs maps to the GitHub repo reikla/ai-docs (NOT reikla/docs).
If unsure of a repo's remote, verify before pushing: git -C <repo> remote get-url origin.
See ${CLAUDE_PLUGIN_ROOT}/skills/octo-commit/references/repo-remotes.md for the full directory-to-remote table.
| Mistake | Prevention |
|---|---|
| Pushing without approval | Get explicit go-ahead this session before any push/PR |
| Committing without work item | Always resolve AB# first -- search or create |
| Wrong WIQL command | Use az boards query --wiql, NOT az boards work-item query |
| Wrong prefix (New vs Fix) | Bug -> Fix; Issue/Epic/Task -> New (confirm Task if it's a fix) |
| Wrong team name | It's Solutions Team (plural), not "Solution Team" |
| Bare Co-Authored-By | Use model-specific name: Claude <model> <[email protected]> |
| Wrong docs remote | docs dir -> reikla/ai-docs, not reikla/docs |
| Missing upstream on new branch | First push needs git push -u origin <branch> |
| Not reading CLAUDE.md | Always read before build/test/commit |
| Committing secrets | Review staged files for .env, credentials, tokens |
| Force-pushing to main | Never. Use feature branches for risky changes |
| Wrong build config | OctoMesh .NET repos require DebugL, not Debug or Release |
| Stale branch | Pull latest before branching: git pull --rebase |
-u (upstream not set)Guides creation, editing, and verification of skills for AI coding agents using test-driven development with subagent scenarios. Use when authoring or debugging skills.
npx claudepluginhub meshmakers/octo-claude-skills --plugin octo-claude-skills