oh-my-agent-commandcode 0.0.0-stage → 20.38.3

package/skills/oma-dev-workflow/resources/release-coordination.md

@@ -0,0 +1,240 @@
+# Release Coordination
+
+Release Please workflow for automated versioning and releases.
+
+## Overview
+
+This project uses Google's [Release Please](https://github.com/googleapis/release-please) for automated versioning and releases based on conventional commits.
+
+## How It Works
+
+1. **Release PR Creation**: When conventional commits are merged to main, Release Please creates a release PR
+2. **CHANGELOG Generation**: Automatically generates CHANGELOG.md from commits
+3. **Version Bumping**: Updates version in package.json and other files
+4. **Release on Merge**: When the release PR is merged, a GitHub release is created
+
+## GitHub Actions Workflow
+
+```yaml
+# .github/workflows/release-please.yml
+name: Release Please
+
+on:
+  push:
+    branches: [main]
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  release-please:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: googleapis/release-please-action@v4
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+          release-type: node
+```
+
+## Mise Tasks for Release Management
+
+```toml
+# Root mise.toml
+[tools]
+node = "24"
+bun = "latest"
+
+[tasks."release:check"]
+description = "Check release-please status"
+run = '''
+#!/usr/bin/env bash
+echo "Checking release status..."
+echo ""
+echo "Open release PRs:"
+gh pr list --label "autorelease: pending" --state open
+echo ""
+echo "Latest releases:"
+gh release list --limit 5
+'''
+
+[tasks."release:manifest"]
+description = "Show current release manifest"
+run = "cat .release-please-manifest.json"
+
+[tasks."release:changelog"]
+description = "Preview changelog (local dry-run)"
+run = '''
+#!/usr/bin/env bash
+echo "Recent conventional commits:"
+git log --pretty=format:"%s" $(git describe --tags --abbrev=0)..HEAD | grep -E "^(feat|fix|perf|build|revert|docs|style|refactor|test|chore|ci)(\(.+\))?:"
+'''
+```
+
+## Conventional Commit Format
+
+Release Please recognizes these commit types:
+
+| Type | Version Bump | Description |
+|------|--------------|-------------|
+| `feat:` | minor | New feature |
+| `fix:` | patch | Bug fix |
+| `docs:` | no release by default; project config may opt in | Documentation |
+| `style:` | no release by default; project config may opt in | Code style (no logic) |
+| `refactor:` | no release by default; project config may opt in | Code refactoring |
+| `test:` | no release by default; project config may opt in | Tests |
+| `chore:` | no release by default; project config may opt in | Maintenance |
+| `feat!:` | major | Breaking change |
+| `fix!:` | major | Breaking bug fix |
+
+## Release Configuration
+
+```json
+// .release-please-config.json
+{
+  "packages": {
+    ".": {
+      "release-type": "node",
+      "draft": false,
+      "prerelease": false
+    }
+  }
+}
+```
+
+```json
+// .release-please-manifest.json
+{
+  ".": "1.0.0"
+}
+```
+
+## Release Flow
+
+### 1. Develop Features
+```bash
+# Make changes with conventional commits
+git commit -m "feat(infra): add infrastructure skills category"
+git commit -m "fix(shared): correct skill installation path"
+git commit -m "docs: update installation guide"
+```
+
+### 2. Merge to Main
+```bash
+git push origin main
+```
+
+### 3. Release Please Creates PR
+Automatically creates a PR like:
+- Title: `chore(main): release 1.1.0`
+- Includes updated CHANGELOG.md
+- Includes version bump in package.json
+
+### 4. Review the release PR
+
+Review the version and changelog in the release PR before merging through the
+project's normal merge policy. This action alone does not auto-merge release PRs,
+sync OMA prompt manifests, or publish a package; those require explicit project
+automation.
+
+### 5. Verify Release
+```toml
+[tasks."release:verify"]
+description = "Verify latest release"
+run = '''
+#!/usr/bin/env bash
+echo "Latest release:"
+gh release view --json tagName,name,createdAt
+
+echo ""
+echo "Assets:"
+gh release view --json assets
+'''
+```
+
+## Release Status
+
+Inspect release status without triggering a workflow:
+
+```toml
+[tasks."release:status"]
+description = "Show release-please status"
+run = '''
+#!/usr/bin/env bash
+echo "Release-please status:"
+echo "Workflow dispatch requires a separately configured workflow_dispatch trigger."
+echo ""
+echo "Current status:"
+mise run release:check
+'''
+```
+
+## Post-Release Tasks
+
+```toml
+[tasks."release:cleanup"]
+description = "Cleanup after release"
+run = '''
+#!/usr/bin/env bash
+echo "Post-release cleanup..."
+
+# Pull latest changes with tags
+git pull origin main --tags
+
+# Verify local state
+echo ""
+echo "Local version:"
+cat package.json | grep '"version"' | cut -d'"' -f4
+
+echo ""
+echo "Latest tag:"
+git describe --tags --abbrev=0
+
+echo ""
+echo "Release cleanup complete"
+'''
+```
+
+## Troubleshooting
+
+```toml
+[tasks."release:debug"]
+description = "Debug release issues"
+run = '''
+#!/usr/bin/env bash
+echo "Release Debugging"
+echo ""
+
+echo "1. Conventional commits since last tag:"
+git log --pretty=format:"%s" $(git describe --tags --abbrev=0 2>/dev/null || echo "HEAD~10")..HEAD | grep -E "^(feat|fix|perf|build|revert|docs|style|refactor|test|chore|ci)(\(.+\))?:" || echo "  No conventional commits found"
+
+echo ""
+echo "2. Release Please config files:"
+ls -la .release-please*.json 2>/dev/null || echo "  Config files not found"
+
+echo ""
+echo "3. GitHub Actions status:"
+gh run list --workflow=release-please.yml --limit 5 2>/dev/null || echo "  No runs found"
+
+echo ""
+echo "4. Open release PRs:"
+gh pr list --label "autorelease: pending" 2>/dev/null || echo "  No release PRs"
+'''
+```
+
+## Setup Requirements
+
+1. **GitHub Actions workflow** (`.github/workflows/release-please.yml`)
+2. **Release Please config** (`.release-please-config.json`)
+3. **Release Please manifest** (`.release-please-manifest.json`)
+4. **Conventional commits** (already configured via commitlint)
+5. **GitHub CLI** (`gh`) installed for the release tasks — `brew install gh` or `mise use gh` (it is a Go binary, not an npm package; `bunx gh` resolves an unrelated deprecated package)
+6. **Publish gating** — the release workflow runs the full Test matrix against the release tag (`gate-tests` job) before publishing, and both publish jobs build from the tag rather than main HEAD
+
+## Benefits
+
+- Automated versioning based on commits
+- Auto-generated CHANGELOG.md
+- GitHub releases with notes
+- No manual version bumping
+- Integrated with GitHub PR workflow

package/skills/oma-dev-workflow/resources/tooling-profiles.md

@@ -0,0 +1,217 @@
+# Tooling Profiles
+
+Use these profiles when setting up or changing development checks. For an
+execution-only request, run the project's existing commands. Inspect manifests,
+lockfiles, tool configs, task definitions, hooks, and CI before selecting a profile.
+Preserve existing choices; these defaults fill missing configuration.
+
+## Selection and task contract
+
+| Detected scope | Default for missing configuration |
+| --- | --- |
+| Python | Ruff lint/format + explicitly configured pyrefly |
+| JavaScript | Biome lint/format |
+| TypeScript | Biome + TypeScript 7 native type checking |
+| Dart / Flutter | SDK analyzer + `dart format`; Falcon is optional |
+| Dockerfile | Hadolint |
+| Commit messages | Local commitlint + `@commitlint/config-conventional` |
+
+Configure only the detected packages/files and the requested operations. Keep the
+project's package manager and runtime versions. Resolve compatible tool versions
+at setup time and record them in manifests and lockfiles; pin standalone tools in
+`mise.toml`. Provision dependencies before hooks or CI checks run. Hooks must not
+download packages or initialize configuration.
+
+Expose applicable tasks through `mise`:
+
+- `lint`: checks without fixes.
+- `format:check`: checks formatting without writes.
+- `format`: explicitly requested formatting writes.
+- `typecheck`: whole-app type analysis without compilation output.
+- `check`: aggregate the applicable non-mutating checks.
+- `git:commit-msg`, or the commit-msg hook when it already runs under `mise exec`: commitlint for the supplied message file.
+
+Each underlying checker should run once per `check`: Biome `check` already checks
+formatting, and the Dart analyzer covers both lint and types. JavaScript-only and
+Dockerfile-only scopes need no placeholder typecheck task. Keep framework-specific
+checks such as `vue-tsc` or `svelte-check` when already configured.
+
+For example, a Python app can aggregate its three independent checks:
+
+```toml
+[tasks.check]
+depends = ["lint", "format:check", "typecheck"]
+```
+
+Record the configured aggregate in an existing domain stack's supported contract:
+
+```yaml
+verify:
+  syntax:
+    cmd: "mise run check"
+```
+
+Merge this into the existing `verify` mapping; preserve `detect`, `tests`, raw-SQL
+scans, and other domain fields. Use an app-qualified task path for monorepos. Do
+not invent `verify.lint` or `verify.typecheck` fields unsupported by the schema.
+`/stack-set` records detected configuration; this skill owns tool setup. Running
+checks must not invoke `/stack-set` or install defaults implicitly.
+
+## Python: Ruff and pyrefly
+
+For an existing uv project, add both tools as development dependencies:
+
+```sh
+uv add --dev ruff pyrefly
+```
+
+For another package manager, use its development dependency/lockfile mechanism;
+do not migrate the project to uv just for these checks. Preserve existing
+`pyproject.toml`, `ruff.toml`, `.ruff.toml`, and pyrefly configuration. Derive Python
+version, source roots, and exclusions from the actual project.
+
+Configure pyrefly during setup with `uv run pyrefly init`, then inspect the
+generated changes. Alternatively, add explicit project scope to `pyproject.toml`.
+This example applies only when both `src/` and `tests/` exist:
+
+```toml
+[tool.pyrefly]
+project-includes = ["src/**/*.py", "tests/**/*.py"]
+search-path = ["src"]
+```
+
+Unconfigured pyrefly can use a basic preset or infer legacy settings. Do not claim
+full project type checking without verifying its configuration and included paths.
+Keep `init`, suppression generation, and Ruff `--fix` out of check tasks.
+
+| Task | Command for a uv project |
+| --- | --- |
+| `lint` | `uv run --no-sync --no-python-downloads ruff check .` |
+| `format:check` | `uv run --no-sync --no-python-downloads ruff format --check .` |
+| `format` | `uv run --locked ruff format .` |
+| `typecheck` | `uv run --no-sync --no-python-downloads pyrefly check` |
+
+Provision the environment with `uv sync --locked` during setup/CI dependency
+installation. `--locked` alone still permits environment synchronization;
+`--no-sync` skips it, and `--no-python-downloads` prevents interpreter downloads.
+Lockfile freshness is checked during provisioning; a missing checker must fail
+instead of downloading it in a hook.
+
+## JavaScript / TypeScript: Biome and native TypeScript
+
+Install local development dependencies with the detected package manager. This is
+an npm example for an unconfigured TypeScript project:
+
+```sh
+npm install --save-dev --save-exact @biomejs/biome typescript
+./node_modules/.bin/biome init
+```
+
+For JavaScript alone, omit TypeScript. Run `biome init` only when configuration is
+absent; use the installed version's generated schema rather than a stale JSON
+template. Preserve existing ESLint/Prettier configurations unless replacement was
+requested. Check framework, plugin, and file-type coverage before migrating tools.
+
+During Biome setup, explicitly set `linter.rules.performance.noReExportAll` to
+`"error"` in `biome.json` or `biome.jsonc`; `recommended: true` does not enable it.
+Merge this setting into the existing configuration and preserve unrelated rules
+and overrides:
+
+```json
+{
+  "linter": {
+    "rules": {
+      "performance": {
+        "noReExportAll": "error"
+      }
+    }
+  }
+}
+```
+
+This rejects value re-exports using `export * from` or `export * as ... from`.
+Named re-exports and type-only re-exports remain allowed.
+
+| Task | npm example using installed tools |
+| --- | --- |
+| `lint` | `npm exec --no -- biome check .` |
+| `format:check` | `npm exec --no -- biome format .` |
+| `format` | `npm exec --no -- biome format --write .` |
+| `typecheck` (TypeScript 7) | `npm exec --no -- tsc --noEmit` |
+
+Biome's `check` includes formatting and assists; an aggregate can depend on `lint`
+and `typecheck` without repeating `format:check`. Keep `--write` and unsafe fixes
+out of validation; `biome ci` is also a non-mutating CI entry point.
+
+TypeScript 7.0 RC and later use the executable name **`tsc`**, including the native
+compiler. Keep an existing `typescript` 7 dependency and `tsc --noEmit` task. Only
+projects explicitly using `@typescript/native-preview` should run `tsgo --noEmit`.
+Check the installed package/executable before writing tasks; do not install both
+packages or replace framework checks merely to obtain the `tsgo` name. If native
+checking is incompatible with a project's configuration, retain its working
+checker and report the limitation rather than silently skipping checks.
+
+## Dart / Flutter: SDK analyzer and formatter
+
+Read `pubspec.yaml`, `pubspec.lock`, `analysis_options.yaml`, SDK constraints, and
+the existing analyzer command. Use the project's Dart/Flutter SDK; do not install
+a second SDK or replace analyzer plugins. Preserve existing lint rules and
+analysis exclusions. Provision packages before running checks.
+
+| Task | Dart command | Flutter command |
+| --- | --- | --- |
+| Analyzer | `dart analyze --fatal-infos` | `flutter analyze --no-pub --fatal-infos` |
+| `format:check` | `dart format --output=none --set-exit-if-changed .` | Same |
+| `format` | `dart format .` | Same |
+
+The analyzer performs both lint and type checks. Use one `analyze` task and make
+`lint`/`typecheck` aliases depend on it; the aggregate `check` should depend on
+`analyze` and `format:check`. Hook/CI pipelines should call that aggregate once,
+rather than invoke both aliases sequentially. Keep an existing package-specific
+`dart analyze` command in Flutter projects that rely on analyzer plugins.
+
+[Falcon](https://github.com/viveky259259/falcon) is a Rust/tree-sitter Dart/Flutter
+linter. Offer it only as an explicitly selected additional check. Its default
+analysis is syntactic, and its semantic mode invokes the Dart analyzer; it does
+not replace SDK type checking. Verify the installed version and rule coverage
+before adding a Falcon task. Do not infer analyzer compatibility from speed
+claims or compile a tool from source without an explicit build request.
+
+## Dockerfile: Hadolint
+
+Use the installed Hadolint or provision a pinned release through mise's `hadolint`
+tool during setup. Discover the actual Dockerfiles, including files outside the
+root, and pass their paths explicitly. For a repository with a root Dockerfile:
+
+```toml
+[tasks."lint:dockerfile"]
+run = "hadolint Dockerfile"
+```
+
+Preserve `.hadolint.yaml`/`.hadolint.yml`, rule severity, ignores, and inline
+exceptions. Supply `--config` when the project uses another location. Hadolint's
+`--ignore` replaces the configured ignore list, so do not add it casually. Do not
+blanket-disable findings or append `|| true` to a failing lint command.
+
+Include `lint:dockerfile` once in root/shared checks and in the selected hook/CI
+pipeline; affected-app checks alone do not run root tasks. Hadolint performs
+static checking: no Docker image build is required. Missing tool/configuration is
+an incomplete check, not a successful skip.
+
+## Commit messages: commitlint
+
+Install both `@commitlint/cli` and `@commitlint/config-conventional` as locked local
+development dependencies using the existing JavaScript tooling area. Without one
+(for example, a Python-only repository), provision a pinned Node runtime and a
+private tooling `package.json` with a lockfile as part of requested commitlint
+setup. Keep tool dependencies separate from Python/Dart application dependencies.
+
+Preserve existing commitlint configuration and the hook manager. For new
+configuration, extend `@commitlint/config-conventional`; keep repository-specific
+types/scopes when present. Run the installed CLI from the local `commit-msg` hook
+for the quoted message-file path. Do not use transient `npx -y`, `bunx`, or
+`pnpm dlx` downloads in hooks, or assume a Python-only repository has Bun.
+
+Use [validation-pipeline.md](validation-pipeline.md) for the local dependency
+example and `commit-msg` integration.
+Initialize and install during setup; checks must only validate messages.

package/skills/oma-dev-workflow/resources/troubleshooting.md

@@ -0,0 +1,78 @@
+# Troubleshooting
+
+Common issues and solutions.
+
+## Task Not Found
+
+```bash
+# List all available tasks
+mise tasks --all
+
+# Show task details
+mise tasks <task-name>
+```
+
+## Runtime Not Found
+
+```bash
+# Install all runtimes
+mise install
+
+# Install specific runtime
+mise install node@24
+
+# List installed runtimes
+mise list
+```
+
+## Port Already in Use
+
+```bash
+# Check ports
+lsof -ti:8000  # API port
+lsof -ti:3000  # Web port
+lsof -ti:8080  # Mobile port
+
+# Inspect the owner and command before stopping a confirmed project process.
+lsof -nP -iTCP:8000 -sTCP:LISTEN
+# Set PROJECT_PID to the confirmed PID from that output.
+ps -p "$PROJECT_PID" -o pid,ppid,user,command
+kill -TERM "$PROJECT_PID" # escalate only if this same process does not stop
+```
+
+## Task Hangs
+
+```bash
+# Run with verbose output
+mise run dev --verbose
+
+# Debug mode
+MISE_DEBUG=1 mise run dev
+
+# Check for interactive prompts (use --yes if available)
+mise run install --yes
+```
+
+## Clean State
+
+```bash
+# Stop this task with Ctrl-C in its terminal, or TERM its verified project PID.
+# Inspect the versions selected by this project before changing toolchains.
+mise ls --current
+# Repair only the confirmed tool/version, if needed and authorized.
+# Example: mise install node@<project-version>
+# Do not blanket-kill other mise tasks or uninstall the user's shared runtimes.
+```
+
+## Debug Configuration
+
+```bash
+# Show mise config
+mise config
+
+# Show environment
+mise env
+
+# Doctor - check for issues
+mise doctor
+```