From 6b8a055e982f1c7cab6b4c935d9b4b0dd9a65606 Mon Sep 17 00:00:00 2001 From: Zhongwei Li Date: Sat, 29 Nov 2025 18:48:15 +0800 Subject: [PATCH] Initial commit --- .claude-plugin/plugin.json | 11 +++ README.md | 3 + commands/ci.md | 75 +++++++++++++++ commands/commit.md | 183 +++++++++++++++++++++++++++++++++++++ commands/push.md | 52 +++++++++++ plugin.lock.json | 53 +++++++++++ 6 files changed, 377 insertions(+) create mode 100644 .claude-plugin/plugin.json create mode 100644 README.md create mode 100644 commands/ci.md create mode 100644 commands/commit.md create mode 100644 commands/push.md create mode 100644 plugin.lock.json diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json new file mode 100644 index 0000000..22ad966 --- /dev/null +++ b/.claude-plugin/plugin.json @@ -0,0 +1,11 @@ +{ + "name": "flow", + "description": "Namespaced Flow commands for commit authoring, push safety, and CI analysis in Claude Code.", + "version": "1.0.1", + "author": { + "name": "Ilya Nikokoshev" + }, + "commands": [ + "./commands" + ] +} \ No newline at end of file diff --git a/README.md b/README.md new file mode 100644 index 0000000..5f1f730 --- /dev/null +++ b/README.md @@ -0,0 +1,3 @@ +# flow + +Namespaced Flow commands for commit authoring, push safety, and CI analysis in Claude Code. diff --git a/commands/ci.md b/commands/ci.md new file mode 100644 index 0000000..c580dca --- /dev/null +++ b/commands/ci.md @@ -0,0 +1,75 @@ +--- +description: Summarize the latest GitHub Actions runs, surface results, and analyze issues. +argument-hint: [workflow=|all] +allowed-tools: Edit, Bash, Grep, Read +--- + +# Goal + +Pull the most recent GitHub Actions workflow runs for a repo, summarize their status, and analyze failures with actionable diagnostics and next steps. + +# Inputs + +- `$ARGUMENTS` can be: + - Optional flags: + - `workflow=|all` (e.g., `workflow=ci.yml` or `workflow=all`; default: all workflows) + +# Plan + +1. **Resolve repository coordinates** + - You usually know what the current owner/repo are (often repo is the folder name). + - If `owner/repo` is unclear, infer from local git: + - Verify repo: !`git rev-parse --is-inside-work-tree` + - Remote URL: !`git remote get-url origin || git config --get remote.origin.url` + - Parse `owner` and `repo` from `https://github.com/owner/repo(.git)?` or `git@github.com:owner/repo(.git)?`. + - Find out and remember the current commit SHA using `git rev-parse HEAD`. + +2. **Select workflows** + - If `workflow` not provided or set to `all`, use `gh workflow list` to enumerate available workflows. + - When calling `/flow:ci` next time, remember what those workflows are; no need to repeat unless explicitly prompted. + - Otherwise, constrain to the specified workflow file name or numeric ID. + +3. **Fetch latest runs** + - For each selected workflow, use `gh run list --workflow= --limit= --json databaseId,headSha,status,conclusion,event,createdAt,updatedAt,url,name` with filters: + - `--branch=` if provided + - `--limit=` (default 3, max 20) + - For each run returned, check if it refers to the current commit SHA. + - For each that does and that is completed, use `gh run view --json status,conclusion,createdAt,updatedAt,url,event,jobs` to get more info: + - Capture status, conclusion, timings, HTML URL, job details + - If for a given workflow the run for the current commit has not yet completed, remember that but also examine the most recent completed run. + +4. **Deep-dive on failures** + - For any run that has completed but with `conclusion` not `success`: + - Use `gh run view --log-failed` to get logs for failed jobs. + - Extract dominant error patterns (stack traces, test failures, exit codes, missing secrets, flaky steps, infra timeouts). + - Map failing jobs to workflow graph where possible; note common failing steps across runs. + +5. **Produce report** + - Show commit SHA prominently in the header as well as whether all runs for this commit succeeded, some failed or are still ongoing. + - **Overview table** (per workflow): run ID โ†’ commit SHA, status, conclusion, event, duration, started, link. + - Again, show the runs for the current commit, except if they are not complete, in which case also show the most revent completed run. + - **Failure summary**: frequency by job/step, top error signatures, first-seen vs. most-recent. + - **Root-cause hypotheses** per failure cluster, with **concrete next actions**: + - config fixes (matrix keys, permissions, cache keys) + - environment/toolchain diffs (runner image, Node/Java versions) + - flaky tests (test names, suggested quarantine patterns) + - secret/permission issues (missing `GITHUB_TOKEN` scopes, OIDC, org secret visibility) + - **Appendix**: tailed logs for failed jobs + +6. **Output** + - Show this to the user + +# Execution details + +- Prefer _read-only_ operations; do **not** cancel or rerun jobs in this command. +- Be resilient to: + - Missing workflows (empty list) + - Private repos or insufficient PAT scopes (report and stop gracefully) + - Very large logs (use appropriate filtering) +- If `gh` CLI is not authenticated or configured, inform the user to run `gh auth login` first. + +# Now do it + +1. Gather data using the `gh` CLI commands listed above. +2. Analyze failures and suggest possible steps to mitigate. +3. Present the report to the user in the nice visual format. diff --git a/commands/commit.md b/commands/commit.md new file mode 100644 index 0000000..40373d2 --- /dev/null +++ b/commands/commit.md @@ -0,0 +1,183 @@ +--- +description: Create commits with intelligent splitting and pre-commit fixes +argument-hint: [topic] +allowed-tools: Bash(git:*) +--- + +# Claude Command: Flow Commit + +This command helps you create well-formatted commits with conventional commit messages and emoji. + +## Usage + +To review the pre-commit issues and create a commit, just type: + +```text +/flow:commit +``` + +Or with hinting about a specific topic: + +```text +/flow:commit VoiceSelector refactor +``` + +## Context + +- Current git status: !`git status --short || true` +- Current git diff (staged and unstaged changes): !`git diff HEAD || true` +- Current branch: !`git branch --show-current || true` +- Latest commits: !`git log --oneline -20 || true` +- Pre-commit hook results from git: !`git hook run pre-commit || true` +- User-provided topic (can be empty): $ARGUMENTS + +## What This Command Does + +**Note:** This is a custom command. When being executed, Claude will see a "/flow:commit is running" message indicating the command is being processed and your thinking should proceed as below. + +0. If this is not a git repository, initiate one with `git init` and use `main` branch as default. +1. Check which files are staged from `git status` output; if none are staged, automatically add all modified and new files with `git add`. +2. Performs a `git diff` to understand what changes are being committed +3. Analyzes the diff to determine if multiple distinct logical changes are present +4. If multiple distinct changes are detected, break the commit into multiple smaller commits +5. For each commit (or the single commit if not split), create a commit message using emoji conventional commit format +6. Analyze the pre-commit hook output; if there are formatting issues, try to fix them with project-standard formatting tools, often `just format`. +7. For other issues, like linting or test failures, try to fix them yourself. +8. Run the git hook again after any changes. +9. If there are complex issues that are hard to fix then ask the user how to proceed: fix the issues, commit with `--no-verify` or continue other work. + +## Best Practices for Commits + +- **Verify before committing**: Ensure code is linted, builds correctly, and documentation is updated +- **Atomic commits**: Each commit should contain related changes that serve a single purpose +- **Split large changes**: If changes touch multiple concerns, split them into separate commits +- **Conventional commit format**: Use the format `: ` where type is one of: + - `feat`: A new feature + - `fix`: A bug fix + - `docs`: Documentation changes + - `style`: Code style changes (formatting, etc) + - `refactor`: Code changes that neither fix bugs nor add features + - `perf`: Performance improvements + - `test`: Adding or fixing tests + - `chore`: Changes to the build process, tools, etc. +- **Present tense, imperative mood**: Write commit messages as commands (e.g., "add feature" not "added feature") +- **Concise first line**: Keep the first line under 72 characters +- **Only most important details**: make it clear what the commit touches (e.g. auth flow or /payments endpoint) but clarify the specifics only on a very high level, use brackets if helpful +- **Emoji**: Each commit type is paired with an appropriate emoji: + - โœจ `feat`: New feature + - ๐Ÿ› `fix`: Bug fix + - ๐Ÿ“ `docs`: Documentation + - ๐Ÿ’„ `style`: Formatting/style + - โ™ป๏ธ `refactor`: Code refactoring + - โšก๏ธ `perf`: Performance improvements + - โœ… `test`: Tests + - ๐Ÿ”ง `chore`: Tooling, configuration + - ๐Ÿš€ `ci`: CI/CD improvements + - ๐Ÿ—‘๏ธ `revert`: Reverting changes + - ๐Ÿšจ `fix`: Fix compiler/linter warnings + - ๐Ÿ”’๏ธ `fix`: Fix security issues + - ๐Ÿ‘ฅ `chore`: Add or update contributors + - ๐Ÿšš `refactor`: Move or rename resources + - ๐Ÿ—๏ธ `refactor`: Make architectural changes + - ๐Ÿ”€ `chore`: Merge branches + - ๐Ÿ“ฆ๏ธ `chore`: Add or update compiled files or packages + - โž• `chore`: Add a dependency + - โž– `chore`: Remove a dependency + - ๐ŸŒฑ `chore`: Add or update seed files + - ๐Ÿง‘โ€๐Ÿ’ป `chore`: Improve developer experience + - ๐Ÿงต `feat`: Add or update code related to multithreading or concurrency + - ๐Ÿ”๏ธ `feat`: Improve SEO + - ๐Ÿท๏ธ `feat`: Add or update types + - ๐Ÿ’ฌ `feat`: Add or update text and literals + - ๐ŸŒ `feat`: Internationalization and localization + - ๐Ÿ‘” `feat`: Add or update business logic + - ๐Ÿ“ฑ `feat`: Work on responsive design + - ๐Ÿšธ `feat`: Improve user experience / usability + - ๐Ÿฉน `fix`: Simple fix for a non-critical issue + - ๐Ÿฅ… `fix`: Catch errors + - ๐Ÿ‘ฝ๏ธ `fix`: Update code due to external API changes + - ๐Ÿ”ฅ `fix`: Remove code or files + - ๐ŸŽจ `style`: Improve structure/format of the code + - ๐Ÿš‘๏ธ `fix`: Critical hotfix + - ๐ŸŽ‰ `chore`: Begin a project + - ๐Ÿ”– `chore`: Release/Version tags + - ๐Ÿšง `wip`: Work in progress + - ๐Ÿ’š `fix`: Fix CI build + - ๐Ÿ“Œ `chore`: Pin dependencies to specific versions + - ๐Ÿ‘ท `ci`: Add or update CI build system + - ๐Ÿ“ˆ `feat`: Add or update analytics or tracking code + - โœ๏ธ `fix`: Fix typos + - โช๏ธ `revert`: Revert changes + - ๐Ÿ“„ `chore`: Add or update license + - ๐Ÿ’ฅ `feat`: Introduce breaking changes + - ๐Ÿฑ `assets`: Add or update assets + - โ™ฟ๏ธ `feat`: Improve accessibility + - ๐Ÿ’ก `docs`: Add or update comments in source code + - ๐Ÿ—ƒ๏ธ `db`: Perform database related changes + - ๐Ÿ”Š `feat`: Add or update logs + - ๐Ÿ”‡ `fix`: Remove logs + - ๐Ÿคก `test`: Mock things + - ๐Ÿฅš `feat`: Add or update an easter egg + - ๐Ÿ™ˆ `chore`: Add or update .gitignore file + - ๐Ÿ“ธ `test`: Add or update snapshots + - โš—๏ธ `experiment`: Perform experiments + - ๐Ÿšฉ `feat`: Add, update, or remove feature flags + - ๐Ÿ’ซ `ui`: Add or update animations and transitions + - โšฐ๏ธ `refactor`: Remove dead code + - ๐Ÿฆบ `feat`: Add or update code related to validation + - โœˆ๏ธ `feat`: Improve offline support + +## Guidelines for Splitting Commits + +When analyzing the diff, consider splitting commits based on these criteria: + +1. **Different concerns**: Changes to unrelated parts of the codebase +2. **Different types of changes**: Mixing features, fixes, refactoring, etc. +3. **File patterns**: Changes to different types of files (e.g., source code vs documentation) +4. **Logical grouping**: Changes that would be easier to understand or review separately +5. **Size**: Very large changes that would be clearer if broken down + +If unclear, ask the user how to proceed. + +## Examples + +Good commit messages: + +- โœจ feat: add user authentication system +- ๐Ÿ› fix: resolve memory leak in rendering process +- ๐Ÿ“ docs: update API documentation with /user/... endpoints +- โ™ป๏ธ refactor: simplify error handling logic in VoiceSelector +- ๐Ÿšจ fix: resolve linter warnings in component files +- ๐Ÿง‘โ€๐Ÿ’ป chore: use just for developer tooling +- ๐Ÿ‘” feat: implement business logic for transaction validation +- ๐Ÿฉน fix: address minor styling inconsistency in header +- ๐Ÿš‘๏ธ fix: patch critical security vulnerability in auth flow +- ๐ŸŽจ style: reorganize VoiceSelector component for better readability +- ๐Ÿ”ฅ fix: remove deprecated legacy code in /v1/payment +- ๐Ÿฆบ feat: add input validation for user registration form +- ๐Ÿ’š fix: failing CI pipeline tests (CSS linting settings mismatch) +- ๐Ÿ“ˆ feat: implement analytics tracking for user engagement +- ๐Ÿ”’๏ธ fix: strengthen authentication password requirements (16 chars) +- โ™ฟ๏ธ feat: improve login form accessibility for screen readers + +Example of splitting commits: + +- First commit: โœจ feat: add new solc version type definitions +- Second commit: ๐Ÿ“ docs: update documentation for new solc versions +- Third commit: ๐Ÿ”ง chore: update package.json dependencies +- Fourth commit: ๐Ÿท๏ธ feat: add type definitions for /user endpoints +- Fifth commit: ๐Ÿงต feat: improve concurrency handling in worker threads +- Sixth commit: ๐Ÿšจ fix: resolve linting issues in new solc code +- Seventh commit: โœ… test: add unit tests for new solc version features +- Eighth commit: ๐Ÿ”’๏ธ fix: update dependencies with security vulnerabilities + +## Important Notes + +โ€ผ๏ธ If no git repository exists, the command will initialize one with `main` as the default branch. +โ€ผ๏ธ If specific files are already staged, the command will only commit those files. +โ€ผ๏ธ If no files are staged, it will automatically stage all modified and new files. +โ€ผ๏ธ The commit message will be constructed based on the changes detected, but using user-provided hints +โ€ผ๏ธ Before committing, the command will review the diff to identify if multiple commits would be more appropriate. +โ€ผ๏ธ If suggesting multiple commits, it will help you stage and commit the changes separately. +โ€ผ๏ธ Always reviews the commit diff to ensure the message matches the changes. +โ€ผ๏ธ This command can commit with --no-verify but ONLY if the user explicitly agreed to it when asked. diff --git a/commands/push.md b/commands/push.md new file mode 100644 index 0000000..bc47ae4 --- /dev/null +++ b/commands/push.md @@ -0,0 +1,52 @@ +--- +description: Guard pushes by reviewing commits for risky or sensitive changes +argument-hint: +allowed-tools: Bash, Read, Grep +--- + +# Goal + +Review the commits that are not published to the remote. Check for any information that might leak when pushing. + +# Context + +- !`git log @{upstream}..HEAD || true` +- !`git hook run pre-push || true` + +# Plan + +1. **Get changes in the commits** + +- If there are no unpushed commits, inform the user showing the current branch and remote branch that was compared, then STOP here +- Examine the commits provided as part of the context. +- Try to get the full diff with `git diff @{upstream}..HEAD` to review all changes, unless you expect it to be too large. + +2. **Review the changes** + +- Check the output of the pre-commit hook, if any. +- Look for any things that provide information about my system, e.g. the string `/Users/` referencing the home folder. +- Check that no passwords, secret strings or similar are included in the code, except if clearly intended to be public. +- Check the text files for any descriptions that should not be public, e.g. implementation plans for other repos. + +3. **Present your review** + +- If something that should not be published is found, display the information to the user and STOP here. +- If any pre-push hook issues that would prevent a push are found STOP and ask the user whether they should be fixed. + +4. **Do the push** + +- If you have found no issues in 2) and 4) then run `git push` +- If the push requires setting upstream, use `git push -u origin ` +- if there is not a remote configured, ask the user if they want to create a new private GitHub repo with `gh` and then push to it. Only create it as public if the user explicitly requests it. +- If the issues that prohibit push exist but the user directs you to push without fixing them, push with `--no-verify` + +# Execution details + +- If there is a long list of issues, present the concise summary. + +# Now do it + +1. Gather data about the unpushed commits using `git log @{upstream}..HEAD` +2. Analyze the changes with `git diff @{upstream}..HEAD` and run `just pre-commit` +3. If no issues found, execute `git push` +4. If issues found then ONLY if the user explicitly agrees execute `git push --no-verify` diff --git a/plugin.lock.json b/plugin.lock.json new file mode 100644 index 0000000..253fb1a --- /dev/null +++ b/plugin.lock.json @@ -0,0 +1,53 @@ +{ + "$schema": "internal://schemas/plugin.lock.v1.json", + "pluginId": "gh:ilyannn/claude-commands:", + "normalized": { + "repo": null, + "ref": "refs/tags/v20251128.0", + "commit": "daa7142666b915bddad2bed55746d36f1fd90883", + "treeHash": "8ce89ced8088ecceefc6b368dc42fac4607bee283dedae15921ee7252498b974", + "generatedAt": "2025-11-28T10:17:39.854004Z", + "toolVersion": "publish_plugins.py@0.2.0" + }, + "origin": { + "remote": "git@github.com:zhongweili/42plugin-data.git", + "branch": "master", + "commit": "aa1497ed0949fd50e99e70d6324a29c5b34f9390", + "repoRoot": "/Users/zhongweili/projects/openmind/42plugin-data" + }, + "manifest": { + "name": "flow", + "description": "Namespaced Flow commands for commit authoring, push safety, and CI analysis in Claude Code.", + "version": "1.0.1" + }, + "content": { + "files": [ + { + "path": "README.md", + "sha256": "a95707d48453bb338d32169e734d619bf81159ef8076c246b2748f537d87a3b4" + }, + { + "path": ".claude-plugin/plugin.json", + "sha256": "02dd7899feece0662725cdbbcb09d2116ac46d5e363d917f156a627284a85ea7" + }, + { + "path": "commands/push.md", + "sha256": "8fb6d53f21c5cdc7a93e5f688fc23ac2934c78fe685c40a373624aa04a9a82c1" + }, + { + "path": "commands/commit.md", + "sha256": "6122883cdeb42b33d4638c172c6d986837034c6288fbc4235b1f305fb97a3757" + }, + { + "path": "commands/ci.md", + "sha256": "3cde68b7638b4fe3fd72cf15cbe586984959d560df18d042f7f92a5d7d8d1499" + } + ], + "dirSha256": "8ce89ced8088ecceefc6b368dc42fac4607bee283dedae15921ee7252498b974" + }, + "security": { + "scannedAt": null, + "scannerVersion": null, + "flags": [] + } +} \ No newline at end of file