Initial commit

2025-11-29 18:48:15 +08:00
commit 6b8a055e98
6 changed files with 377 additions and 0 deletions
--- a/.claude-plugin/plugin.json
+++ 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"
+  ]
+}
--- a/README.md
+++ b/README.md
@@ -0,0 +1,3 @@
+# flow
+
+Namespaced Flow commands for commit authoring, push safety, and CI analysis in Claude Code.
--- a/commands/ci.md
+++ b/commands/ci.md
@@ -0,0 +1,75 @@
+---
+description: Summarize the latest GitHub Actions runs, surface results, and analyze issues.
+argument-hint: [workflow=<file|id>|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=<file|id>|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=<workflow> --limit=<count> --json databaseId,headSha,status,conclusion,event,createdAt,updatedAt,url,name` with filters:
+     - `--branch=<branch>` if provided
+     - `--limit=<count>` (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 <run-id> --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 <run-id> --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.
--- a/commands/commit.md
+++ 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 `<type>: <description>` 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.
--- a/commands/push.md
+++ 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 <branch-name>`
+- 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`
--- a/plugin.lock.json
+++ 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": []
+  }
+}