pjandro/OmniRoute
1
0
Fork 0
mirror of https://github.com/diegosouzapw/OmniRoute.git synced 2026-07-26 09:52:11 +03:00
Code Issues Packages Projects Releases Wiki Activity

docs(agents): atualiza fluxos de release e triagem

Browse Source 
Expande os workflows de release para incluir auditoria de segurança,
CHANGELOG completo por commits, quality gate obrigatório, homologação em
VPS local, publicação oficial, deploy em Akamai e validação de artefatos.

Reorganiza a triagem de features com arquivos permanentes por bucket,
suporte a itens em andamento, regra de reclaim após 15 dias e novo
tratamento para ideias viáveis catalogadas.

Corrige a orientação de revisão de discussões para usar a ordem
cronológica real dos comentários e respostas ao identificar a última
atividade.
This commit is contained in:
diegosouzapw
2026-05-27 22:52:23 -03:00
parent 722e9f41cd
commit 9343451ca8
9 changed files with 1202 additions and 588 deletions
Download Patch File Download Diff File Expand all files Collapse all files

433
.agents/skills/generate-release/SKILL.md
View File

@@ -1,11 +1,11 @@
---
name: generate-release-cx
description: Create a new release, bump version up to the .999 patch threshold, update changelog, and manage Pull Requests
description: Create a new release, bump version up to the .999 patch threshold, generate a complete CHANGELOG (with PR co-authors + every commit since the last tag), and manage Pull Requests
---
# Generate Release Workflow
Bump version, finalize CHANGELOG, commit, open a **PR to main** and wait for user confirmation before tagging, publishing, and deploying.
Bump version, build a **complete CHANGELOG** from every commit since the last tag (with PR back-reference and contributor attribution), commit, open a **PR to main** and wait for user confirmation before tagging, publishing, and deploying.
## Codex Execution Notes
@@ -21,12 +21,16 @@ Bump version, finalize CHANGELOG, commit, open a **PR to main** and wait for use
---
## ⚠️ Two-Phase Flow
## ⚠️ Four-Phase Flow
```
Phase 1 (automated): bump → docs → i18n → commit → push → open PR
↕ 🛑 STOP: Notify user, wait for PR confirmation
Phase 2 (post-merge): tag → publish → GitHub release → Docker → deploy
Phase 0 → security audit (npm + CodeQL + Dependabot)
Phase 1 → bump → full quality gate → changelog from commits → commit → push → open PR
↕ 🛑 STOP (BlockedOnUser: true): notify user, wait for PR merge
Phase 2 → deploy main to Local VPS for homologation
↕ 🛑 STOP (BlockedOnUser: true): notify user, wait for OK
Phase 3 → tag → GitHub release → Docker → npm → Akamai
Phase 4 → monitor CI pipelines and validate artifacts
```
**NEVER push directly to main or create tags before the user confirms the PR.**
@@ -35,107 +39,203 @@ Phase 2 (post-merge): tag → publish → GitHub release → Docker → deploy
## Phase 0: Security Verification (MANDATORY)
Before creating the release, you must ensure the codebase and supply chain are secure and free of known vulnerabilities.
// turbo
1. **Run Local Dependencies Audit:**
```bash
# 1. Local dependency audit
npm audit --production --audit-level=high
```bash
npm audit
```
# 2. GitHub CodeQL alerts (open + high severity)
gh api '/repos/diegosouzapw/OmniRoute/code-scanning/alerts?state=open&severity=high' \
--jq '.[] | {rule: .rule.id, path: .most_recent_instance.location.path, msg: .most_recent_instance.message.text}' \
2>/dev/null || echo "(no CodeQL access or no alerts)"
_Fix any `high` or `critical` vulnerabilities identified._
# 3. Dependabot alerts (open + high/critical)
gh api '/repos/diegosouzapw/OmniRoute/dependabot/alerts?state=open' \
--jq '.[] | select(.security_advisory.severity == "high" or .security_advisory.severity == "critical") | {pkg: .dependency.package.name, sev: .security_advisory.severity, summary: .security_advisory.summary}' \
2>/dev/null || echo "(no Dependabot access or no alerts)"
```
2. **Check GitHub CodeQL & Dependabot Alerts:**
Navigate to the repository's **Security** tab on GitHub, or use the project's `vulnerability-scanner` skill to analyze active alerts. Ensure all static analysis findings (e.g., prototype pollution, insecure randomness, ReDoS, shell injections) are addressed and logically committed on a target branch.
Fix or justify (with `vulnerability-scanner` skill, or dismissal comment per Hard Rule #14) any `high`/`critical` findings before proceeding.
---
## Phase 1: Pre-Merge
### 1. Create release branch
### 1. Create or confirm release branch
```bash
git checkout -b release/v3.x.y
# First release on a new minor (e.g. starting 3.9.0):
git checkout -b release/v3.9.0
# Continuing current cycle:
git branch --show-current
```
### 2. Determine and sync version
Check current version in `package.json`:
```bash
grep '"version"' package.json
```
> **🔴 BRANCH-VERSION PARITY RULE**: The logical version in `package.json` MUST exactly match the release branch name. For example, if you are on `release/v3.7.0`, the version in `package.json` MUST be `3.7.0`.
>
> - If this is the FIRST time generating a release for a new minor/major branch (e.g., bumping from 3.6.9 to 3.7.0), you MUST ensure the version is bumped to match the new branch logic.
> - If you are just bumping a patch on the current branch (e.g., 3.6.9 to 3.6.10), use:
> `npm version patch --no-git-tag-version`
> **🔴 BRANCH-VERSION PARITY GATE** — auto-checked before any work:
> **⚠️ ATOMIC COMMIT RULE — Version bump MUST happen before committing feature files.**
>
> **CORRECT order:**
>
> 1. `npm version patch --no-git-tag-version` ← bump first
> 2. implement features / fix bugs
> 3. `git add -A && git commit -m "chore(release): v3.x.y — all changes in ONE commit"`
>
> **OR if features are already staged:**
>
> 1. implement features (do NOT commit yet)
> 2. `npm version patch --no-git-tag-version` ← bump before committing
> 3. `git add -A && git commit -m "chore(release): v3.x.y — all changes in ONE commit"`
>
> **NEVER do this (creates version mismatch in git history):**
>
> - ~~commit features → then bump version → commit package.json separately~~
>
> This ensures that `git show v3.x.y` always contains both code changes and the version bump together.
> The GitHub release tag will point to a commit that includes ALL changes for that version.
// turbo
```bash
BRANCH=$(git branch --show-current)
BRANCH_VER=${BRANCH#release/v}
PKG_VER=$(node -p "require('./package.json').version")
if [[ "$BRANCH" != release/v* ]]; then
echo "❌ Not on a release/v* branch (current: $BRANCH). Aborting."; exit 1
fi
echo "Branch target: $BRANCH_VER"
echo "package.json: $PKG_VER"
```
> **⚠️ ATOMIC COMMIT RULE** — bump and feature/fix code MUST land in the same commit so that `git show vX.Y.Z` always contains both. NEVER commit features first and bump in a separate commit.
```bash
npm version patch --no-git-tag-version
```
### 3. Regenerate lock file (REQUIRED after version bump)
**Mandatory** — skipping causes `@swc/helpers` lock mismatch and CI failures:
```bash
npm install
```
### 4. Finalize CHANGELOG.md
Skipping causes `@swc/helpers` lock mismatch and CI failures.
> **🔴 NO MIXUPS RULE**: Ensure you do NOT mix the backlog of the previous version with the new one. The new version section must ONLY contain the features and fixes for the current release.
### 4. Build CHANGELOG from EVERY commit since the last tag
Replace the `[Unreleased]` header with the new version and date.
Keep an empty `## [Unreleased]` section above it, separated by a horizontal rule (`---`).
> **🎯 Goal**: produce a complete CHANGELOG section following the format of PR #2617 — emoji-grouped sections, PR back-reference, and `— thanks @user` attribution. Nothing must slip through.
> **🔴 NO MIXUPS RULE**: do not mix backlog of the previous version. The new section must contain ONLY commits whose merge/landing happened after the previous tag.
#### 4a. Collect raw commit log since last tag
// turbo
```bash
LAST_TAG=$(git describe --tags --abbrev=0)
NEW_VERSION=$(node -p "require('./package.json').version")
TODAY=$(date -u +%F)
echo "Range: $LAST_TAG..HEAD → v$NEW_VERSION ($TODAY)"
# Full commit list (oneline)
git log --no-merges "$LAST_TAG..HEAD" --pretty=format:'%h %s' > /tmp/release_commits.txt
wc -l /tmp/release_commits.txt
# Merge commits (preserve PR numbers + authors)
git log --merges "$LAST_TAG..HEAD" --pretty=format:'%h %s%n author=%an <%ae>' > /tmp/release_merges.txt
# Per-commit detailed list (PR refs, co-authors, body)
git log "$LAST_TAG..HEAD" --pretty=format:'---%n%h | %s%n author=%an <%ae>%n body=%b' > /tmp/release_detailed.txt
```
#### 4b. Enrich with PR metadata + co-authors
For each commit referencing a PR (e.g. `(#2617)` or merge commit `Merge pull request #N`), fetch the PR author and any additional contributors. Use `multi_tool_use.parallel` to fan out the `gh pr view` calls.
// turbo
```bash
# Extract all PR numbers referenced in the range
grep -oE '#[0-9]+' /tmp/release_commits.txt | sort -u > /tmp/release_prs.txt
echo "PRs in range:"; cat /tmp/release_prs.txt
# Fetch author + co-author info for every PR
> /tmp/release_pr_meta.json
while read -r PR; do
N=${PR#\#}
gh pr view "$N" --repo diegosouzapw/OmniRoute \
--json number,title,author,mergeCommit,body \
>> /tmp/release_pr_meta.json 2>/dev/null || echo "(skip $PR — not found)"
echo "" >> /tmp/release_pr_meta.json
done < /tmp/release_prs.txt
```
#### 4c. Assemble the new CHANGELOG section
Using `/tmp/release_commits.txt` + `/tmp/release_pr_meta.json` + `/tmp/release_detailed.txt`, build a new entry that:
1. **Covers every commit** — read the full list and group by Conventional Commit type. A commit is "covered" iff it appears (or is intentionally rolled-up) in the new section.
2. **Groups using these section headers (model from PR #2617)**:
- `### ✨ New Features` — `feat(*)`
- `### 🔧 Bug Fixes` — `fix(*)`
- `### 📝 Maintenance` — `chore(*)`, `refactor(*)`, `docs(*)`, `test(*)`, `ci(*)`, `build(*)`
- `### 🔒 Security` — security-flagged commits (only if any)
3. **Entry format**:
```
- **type(scope):** human-friendly description — extra context if useful. ([#PR](https://github.com/diegosouzapw/OmniRoute/pull/PR) — thanks @author / @coauthor1 / @coauthor2)
```
- When **no PR** is referenced (direct commit on release branch): `(thanks @author)`.
- When the PR closed an external contributor's PR via cherry-pick or re-implementation, attribute BOTH the original author AND the implementer: `thanks @originalAuthor / @diegosouzapw`.
- **Co-authors** must be extracted from the merge commit body (`Co-Authored-By:` lines that pre-date Hard Rule #16) and from PR participants who supplied commits.
4. **Coverage check** — after drafting, diff the section against `/tmp/release_commits.txt`. Any unlisted commit must either be explicitly added or consolidated under a roll-up bullet (e.g. "various lint and test alignments"). Do NOT silently drop commits.
Place the new section in `CHANGELOG.md` right below `## [Unreleased]`, separated by `---`:
```markdown
## [Unreleased]
---
## [3.7.0] — 2026-04-19
## [3.9.0] — 2026-05-27
### ✨ New Features
- **feat(scope):** description ([#1234](https://github.com/diegosouzapw/OmniRoute/pull/1234) — thanks @author)
- ...
### 🐛 Bug Fixes
### 🔧 Bug Fixes
- **fix(scope):** description ([#1235](https://github.com/diegosouzapw/OmniRoute/pull/1235) — thanks @author / @diegosouzapw)
- ...
### 📝 Maintenance
- **chore(scope):** description (thanks @diegosouzapw)
- ...
### 🏆 Hall of Contributors
A special thanks to everyone who contributed code, reviews, and tests for this release:
@user1, @user2
@user1, @user2, @user3
---
## [3.6.9] — 2026-04-19
## [3.8.999] — 2026-05-20
```
> **🔴 HALL OF CONTRIBUTORS RULE**: You MUST parse all the PR author mentions (e.g., `(thanks @username)`) from the new version's changelog items, deduplicate them, and append them as a "Hall of Contributors" section at the end of the new release block, exactly as shown above.
> **🔴 HALL OF CONTRIBUTORS RULE**: After drafting all section bullets, parse every `@username` mention from the bullets (PR authors AND co-authors), deduplicate, sort, and append them as a `### 🏆 Hall of Contributors` block at the end of the new release section (before the trailing `---`).
### 5. Update openapi.yaml version ⚠️ MANDATORY
#### 4d. Coverage assertion
// turbo
```bash
NEW_VERSION=$(node -p "require('./package.json').version")
# Count commits in range
COMMITS=$(wc -l < /tmp/release_commits.txt)
# Count bullets under the new section
BULLETS=$(awk "/^## \\[$NEW_VERSION\\]/{flag=1;next} /^## \\[/{flag=0} flag" CHANGELOG.md | grep -c '^- ')
echo "Commits in range: $COMMITS"
echo "Changelog bullets: $BULLETS"
if [ "$BULLETS" -lt $(( COMMITS / 3 )) ]; then
echo "⚠️ Bullet count looks low (< commits/3). Re-review /tmp/release_commits.txt for missed entries."
fi
```
> If a commit cannot be matched to a bullet, EITHER add it or explicitly justify the omission in this session before continuing.
### 5. Sync versioned files ⚠️ MANDATORY
> **CI will fail** if `docs/reference/openapi.yaml` version ≠ `package.json` version (`check:docs-sync` enforces this).
@@ -152,40 +252,52 @@ for dir in electron open-sse; do
echo "✓ $dir/package.json → $VERSION"
fi
done
# Re-run install to assert the workspace lockfile is updated
# Re-run install so workspace lockfile picks up the bumps
npm install
```
### 6. Update README.md and i18n docs
### 6. Sync README.md and i18n docs
Manually perform these documentation updates (there is no `/update-docs` workflow — it was deprecated in v3.8):
There is **no `/update-docs` workflow** (deprecated in v3.8). Updates must happen manually OR via parallel agents.
- Update feature table rows and "What's new in vX.Y.Z" section in `README.md`
- Sync feature changes to all 40 language `docs/i18n/*/README.md` files (use the same row edits across each translated README)
- Update the relevant `docs/<AREA>.md` if architecture or counts changed
- Re-run `npm run check:docs-sync` and `npm run check:docs-all` to catch drift
**Recommended automation** — fan out via `multi_tool_use.parallel`:
### 7. Run tests
1. Apply the substantive change to `README.md` first (feature table row + "What's new in vX.Y.Z" section).
2. Capture the diff: `git diff README.md > /tmp/readme.patch`.
3. Dispatch 5-10 parallel sub-tasks, each handling a slice of the 40 `docs/i18n/*/README.md`, translating the diff into the target language.
4. Update `docs/<AREA>.md` if architecture/counts changed (e.g. `docs/frameworks/MCP-SERVER.md` when MCP tools change).
5. Validate: `npm run check:docs-sync && npm run check:docs-all`.
### 7. Full quality gate (MANDATORY — replaces the old `npm test`)
> **Precedent**: the v3.8.2 cycle landed with 49 broken tests because only `npm test` was running. Lint + typecheck + cycles caught zero of those regressions.
// turbo
```bash
set -e
npm run lint
npm run typecheck:core
npm run check:cycles
npm run check:docs-all
npm test
```
All tests must pass before creating the PR.
All five must pass before opening the PR. If any fail, fix and re-run.
### 8. Stage, commit, and push
### 8. Stage, commit, and push (atomic — bump + features + changelog + i18n in ONE commit)
// turbo-all
```bash
VERSION=$(node -p "require('./package.json').version")
git add -A
git commit -m "chore(release): v3.x.y — summary of changes"
git push origin release/v3.x.y
git commit -m "chore(release): v$VERSION — $(date -u +%F)"
git push origin "release/v$VERSION"
```
### 9. Open PR to main
> **NEVER** include `Co-Authored-By:` trailers in the release commit (Hard Rule #16). Co-author attribution lives inside the CHANGELOG entries and the Hall of Contributors block.
### 9. Open PR to main
@@ -194,34 +306,49 @@ git push origin release/v3.x.y
```bash
VERSION=$(node -p "require('./package.json').version")
# Extract the exact changelog entry for this version from the root CHANGELOG.md
# Extract the exact changelog entry for this version
awk "/^## \\[$VERSION\\]/{flag=1; print; next} /^---/{if(flag) {flag=0; exit}} flag" CHANGELOG.md > /tmp/changelog_body.txt
# Append test status and next steps
echo "" >> /tmp/changelog_body.txt
echo "### Tests" >> /tmp/changelog_body.txt
echo "- All tests pass" >> /tmp/changelog_body.txt
echo "" >> /tmp/changelog_body.txt
echo "### ⚠️ After merging: run Phase 2 steps to tag, publish, and deploy." >> /tmp/changelog_body.txt
# Append PR-only metadata (test status + reviewer instructions)
{
echo ""
echo "---"
echo ""
echo "### Quality Gate"
echo "- lint: pass"
echo "- typecheck:core: pass"
echo "- check:cycles: pass"
echo "- check:docs-all: pass"
echo "- tests: pass"
echo ""
echo "### Coverage of commits since previous tag"
LAST_TAG=$(git describe --tags --abbrev=0 HEAD~1 2>/dev/null || echo "(no previous tag)")
COMMITS=$(git rev-list --no-merges "$LAST_TAG..HEAD" | wc -l)
echo "- Range: \`$LAST_TAG..HEAD\`"
echo "- Commits inspected: $COMMITS"
echo ""
echo "### ⚠️ After merging: run Phase 2 (Local VPS homologation) before tagging."
} >> /tmp/changelog_body.txt
gh pr create \
--repo diegosouzapw/OmniRoute \
--base main \
--head release/v$VERSION \
--head "release/v$VERSION" \
--title "Release v$VERSION" \
--body-file /tmp/changelog_body.txt
```
### 10. 🛑 STOP — Notify User & Await PR Confirmation
### 10. 🛑 STOP — Notify user & await PR confirmation (`BlockedOnUser: true`)
**This is a mandatory stop point.** Present the report in the final response and stop. Do not continue to the next phase until the user explicitly approves.
Present in the final response and stop. Do not continue to Phase 2 until the user explicitly approves.
Inform the user:
Provide:
- PR URL
- Summary of changes
- Test results
- List of files changed
- Summary of changes (top 5 from CHANGELOG)
- Quality gate results
- List of files changed (`git diff --stat $LAST_TAG..HEAD`)
- Coverage count vs commits-in-range
**DO NOT proceed to Phase 2 until the user confirms the PR looks good and merges it.**
@@ -229,41 +356,37 @@ Inform the user:
## Phase 2: Post-Merge Validation (Local VPS)
> Run these steps only AFTER the user has merged the PR into `main` and all CI jobs have passed.
> Run only AFTER the user has merged the PR into `main` and all CI jobs pass.
### 11. Deploy to Local VPS for Final Validation (MANDATORY)
### 11. Deploy `main` to the Local VPS
Before cutting the official git tag and publishing to the world, deploy the `main` branch to the Local VPS for a final homologation test.
Delegate to the `deploy-vps-local-cx` skill (single source of truth for the deploy procedure — do NOT duplicate SCP/SSH commands here):
```bash
git checkout main
git pull origin main
# Build and pack locally
cd /home/diegosouzapw/dev/proxys/OmniRoute && rm -f omniroute-*.tgz && rm -rf .next/cache app/.next/cache && npm run build:cli && rm -rf app/logs app/coverage app/.git app/.app-build-backup* && npm pack --ignore-scripts
# Deploy to LOCAL VPS (192.168.0.15)
scp omniroute-*.tgz root@192.168.0.15:/tmp/
ssh root@192.168.0.15 "npm install -g /tmp/omniroute-*.tgz --ignore-scripts && cd /usr/lib/node_modules/omniroute/app && npm rebuild better-sqlite3 && pm2 delete omniroute 2>/dev/null; pm2 start /root/.omniroute/ecosystem.config.cjs --update-env && pm2 save && echo '✅ Local done'"
# Verify
curl -s -o /dev/null -w "LOCAL: HTTP %{http_code}\n" http://192.168.0.15:20128/
```
/deploy-vps-local-cx
```
### 12. 🛑 STOP — Notify User & Await Final OK
The skill handles: checkout `main`, `npm pack`, scp to `192.168.0.15`, install, pm2 restart, and HTTP probe.
**This is a mandatory stop point.**
Inform the user that the `main` branch is now running on the Local VPS.
Wait for the user to manually test and give the **OK**.
**DO NOT proceed to Phase 3 until the user confirms the local deploy is stable.**
### 12. 🛑 STOP — Notify user & await final OK (`BlockedOnUser: true`)
Inform the user that `main` is running on `192.168.0.15:20128`. Provide a smoke-test checklist:
- [ ] `GET /` returns 200
- [ ] Dashboard login works (`/dashboard`)
- [ ] `/v1/chat/completions` with default provider returns a stream
- [ ] No critical errors in `pm2 logs omniroute --lines 100`
- [ ] Any release-specific UI features are reachable
Wait for user **OK** before Phase 3.
---
## Phase 3: Official Launch
> Run these steps only AFTER the user gives the final OK from the Phase 2 local validation.
> Run only AFTER the user gives the final OK from Phase 2.
### 13. Create Git Tag and GitHub Release (MANDATORY)
### 13. Create git tag and GitHub Release
// turbo
@@ -272,85 +395,112 @@ git checkout main
git pull origin main
VERSION=$(node -p "require('./package.json').version")
# Extracts the changelog section for this version
# Extract release notes section from CHANGELOG
NOTES=$(awk "/^## \\[$VERSION\\]/{flag=1; next} /^---/{if(flag) {flag=0; exit}} flag" CHANGELOG.md | sed -e 's/^[[:space:]]*//' -e 's/[[:space:]]*$//')
if [ -z "$NOTES" ]; then NOTES="OmniRoute v$VERSION Release"; fi
[ -z "$NOTES" ] && NOTES="OmniRoute v$VERSION Release"
git tag -a "v$VERSION" -m "Release v$VERSION"
git push origin "v$VERSION"
gh release create "v$VERSION" --repo diegosouzapw/OmniRoute --title "v$VERSION" --notes "$NOTES" --target main || gh release edit "v$VERSION" --repo diegosouzapw/OmniRoute --title "v$VERSION" --notes "$NOTES"
gh release create "v$VERSION" \
--repo diegosouzapw/OmniRoute \
--title "v$VERSION" \
--notes "$NOTES" \
--target main \
|| gh release edit "v$VERSION" \
--repo diegosouzapw/OmniRoute \
--title "v$VERSION" \
--notes "$NOTES"
```
### 14. 🐳 Trigger Docker Hub build (MANDATORY — keep npm and Docker in sync)
### 14. 🐳 Trigger / verify Docker Hub build
> **CRITICAL**: Docker Hub and npm MUST always publish the same version.
> The Docker image is built automatically via GitHub Actions when a new tag is pushed.
> After pushing the tag in step 13, **verify the workflow runs**:
> **CRITICAL**: Docker Hub and npm MUST publish the same version.
```bash
# Verify the Docker workflow triggered
VERSION=$(node -p "require('./package.json').version")
gh run list --repo diegosouzapw/OmniRoute --workflow docker-publish.yml --limit 3
# Wait for the Docker build to complete (usually 5–10 min)
gh run watch --repo diegosouzapw/OmniRoute
```
### 15. Publish to NPM (Optional/Automated)
### 15. Publish to npm (usually CI)
Normally handled by CI, but if manual publish is required:
`prepublishOnly` runs `npm run build:cli`. Manual fallback:
```bash
npm publish
npm info omniroute version # verify
```
### 16. Deploy to Akamai VPS (Production)
Delegate to the `deploy-vps-akamai-cx` skill if present, or run the inline equivalent of `deploy-vps-local-cx` against `69.164.221.35`. Do NOT duplicate the procedure here.
### 17. Rollback playbook (use only if Phase 3 fails after tag push)
If a fatal regression surfaces after the tag is pushed:
```bash
VERSION=$(node -p "require('./package.json').version")
PREV=$(git describe --tags --abbrev=0 "v$VERSION^")
# 1. Mark GitHub release as pre-release (do not delete history)
gh release edit "v$VERSION" --repo diegosouzapw/OmniRoute --prerelease
# 2. Re-deploy previous version to Akamai
git checkout "$PREV" && /deploy-vps-akamai-cx
# 3. Deprecate the broken npm version
npm deprecate "omniroute@$VERSION" "broken release — use $PREV"
# 4. Open follow-up issue and start a new patch cycle from main
```
---
## Phase 4: Release Monitoring & Artifact Validation
> After triggering the official release, actively monitor the CI pipelines until all artifacts are successfully generated. If any pipeline fails, stop and apply the necessary corrections before continuing.
> Actively monitor the CI pipelines until all artifacts succeed. If any fail, stop and fix before continuing.
### 16. Monitor CI Pipelines
### 18. Monitor CI pipelines
Wait for and verify the successful completion of the following automated jobs:
Verify successful completion of:
1. **Docker Hub Publish**
2. **Electron Build**
3. **NPM Registry Publish** (Check with `npm info omniroute version`)
3. **npm Registry Publish**
```bash
# Monitor Docker Hub workflow
gh run list --repo diegosouzapw/OmniRoute --workflow docker-publish.yml --limit 1
gh run watch <RUN_ID>
# Monitor Electron build
gh run list --repo diegosouzapw/OmniRoute --workflow electron-release.yml --limit 1
gh run watch <RUN_ID>
# Verify NPM version
npm info omniroute version
```
### 17. Handle Failures (If Any)
If a workflow fails:
- Use `gh run view <RUN_ID> --log-failed` to identify the error.
- Apply the fix on the `main` branch.
- If necessary, re-trigger the workflow using `gh workflow run <workflow_name.yml> --repo diegosouzapw/OmniRoute --ref v3.x.y`
### 18. Preserve release branch
### 19. Handle failures
```bash
# Branch is kept for historical purposes. Do not delete.
gh run view <RUN_ID> --log-failed
# Fix on main, then re-trigger:
VERSION=$(node -p "require('./package.json').version")
gh workflow run <workflow.yml> --repo diegosouzapw/OmniRoute --ref "v$VERSION"
```
### 20. Preserve release branch
Branch is kept for historical purposes. Do not delete.
---
## Notes
- Ensure CHANGELOG, README and `docs/*` are current BEFORE this workflow — run `npm run check:docs-all` and `/version-bump` first (there is no `/update-docs` workflow anymore)
- The `prepublishOnly` script runs `npm run build:cli` automatically during `npm publish`
- After npm publish, verify with `npm info omniroute version`
- Lock file sync errors are caused by skipping `npm install` after version bump
- Use `gh auth switch -u diegosouzapw` if git push fails with wrong account
- Ensure CHANGELOG, README and `docs/*` are current BEFORE this workflow — run `npm run check:docs-all` first.
- The `prepublishOnly` script runs `npm run build:cli` automatically during `npm publish`.
- After npm publish, verify with `npm info omniroute version`.
- Lock file sync errors are caused by skipping `npm install` after version bump.
- Use `gh auth switch -u diegosouzapw` if `git push` fails with the wrong account.
- Deploy procedures live in dedicated skills (`deploy-vps-local-cx`, `deploy-vps-akamai-cx` if present) — never inline the SCP/SSH commands here, to avoid drift.
## Known CI Pitfalls
@@ -360,3 +510,4 @@ If a workflow fails:
| `[docs-sync] FAIL - CHANGELOG.md first section must be "## [Unreleased]"` | `## [Unreleased]` missing or not at top of CHANGELOG | Add `## [Unreleased]\n\n---\n` before the first versioned `## [x.y.z]` |
| Electron Linux `.deb` build fails (`FpmTarget` error) | `fpm` Ruby gem not installed on `ubuntu-latest` runner | Already fixed in `electron-release.yml` (`gem install fpm` step) |
| Docker Hub `502 error writing layer blob` | Transient Docker Hub network error during ARM64 push | Re-run the Docker publish workflow; no code change needed |
| Coverage gate fails (statements/lines < 75% or branches < 70%) | Production code changed without tests | Add tests, re-run `npm run test:coverage` (see CLAUDE.md hard rule #9) |

155
.agents/skills/implement-features/SKILL.md
View File

@@ -15,22 +15,27 @@ A **5-phase** workflow that systematically harvests feature requests from GitHub
- Approval gates (Phase 3 and Phase 4 → 5) are hard stops. Present the report/plan in the final response and do not move to implementation phases until the user explicitly approves.
- Keep harvest/research bounded enough to produce the approval report quickly; do not start implementation while still in report phases.
- The trust-but-verify audit in Phase 5.2 is mandatory before any commit — full lint + typecheck + cycles + build + coverage, plus a real `git diff` review for out-of-scope changes.
- Phase 1.7 stale-reclaim (15-day rule) is opt-in per run: only execute when the user asks for a "reclaim pass" or when the harvest report explicitly flags eligible IN FLIGHT / NEEDS DETAIL items.
**Output directory structure:**
```
_ideia/
├── viable/ # Features approved for implementation
│ ├── need_details/ # ❓ Good idea but waiting for author clarification (issues stay OPEN)
│ │ └── 1015-warp-terminal-mitm.md
│ ├── 1046-native-playground.md # ✅ Ready — researched and planned
├── viable/ # ✅ Approved, awaiting implementation
│ ├── 1046-native-playground.md
│ └── 1046-native-playground.requirements.md
├── implemented/ # 🚧 Implemented but PR not yet merged to main (transient)
├── implemented/ # ✅ Implemented but release PR not yet merged to main (transient)
│ └── 1046-native-playground.md
├── defer/ # ⏭️ Good ideas deferred for future cycles (issues CLOSED after Phase 3 approval)
├── need_details/ # ❓ Issue OPEN — awaiting author clarification (permanent archive)
│ └── 1015-warp-terminal-mitm.md
├── defer/ # ⏭️ Issue CLOSED — good idea, deferred for future cycles (permanent)
│ └── 1041-smart-auto-combos.md
└── notfit/ # ❌ Out of scope / already exists (issues CLOSED after Phase 3 approval)
└── 945-telegram-integration.md
├── notfit/ # ❌ Issue CLOSED — out of scope (permanent)
│ └── 945-telegram-integration.md
├── exists/ # 🔁 Issue CLOSED — feature already shipped (permanent, kept separate from notfit)
│ └── 812-rate-limit-dashboard.md
└── in_flight/ # 🚧 Issue OPEN — third-party PR already addresses it (permanent until reclaim or merge)
└── 988-batch-export.md
_tasks/features-vX.Y.Z/ # Implementation plans (per-release)
└── 1046-native-playground.plan.md
@@ -39,8 +44,8 @@ _tasks/features-vX.Y.Z/ # Implementation plans (per-release)
> **LIFECYCLE RULE:**
> - `viable/` files are **MOVED** to `implemented/` once code lands on the release branch.
> - `implemented/` files are **DELETED** only after the release PR is merged to `main`.
> - This preserves recovery context if implementation fails partially (build green but i18n missing, etc).
> - Files in `defer/` and `notfit/` remain as permanent reference.
> - All other buckets — `need_details/`, `defer/`, `notfit/`, `exists/`, `in_flight/` — are **permanent archives**. Even when the upstream issue is CLOSED, the local file stays. Future cycles can revisit any of them (Phase 1.7 stale-reclaim turns `in_flight/` and `need_details/` back into VIABLE after 15 days of upstream inactivity).
> - This preserves recovery context if implementation fails partially AND lets us re-evaluate old decisions when the project matures.
> **BRANCH RULE**: All implementation work MUST happen on the current `release/vX.Y.Z` branch. Never create separate `feat/` branches. If no release branch exists yet, delegate creation to `/generate-release` (see Phase 1.2) — do NOT reimplement bump logic here.
@@ -196,7 +201,7 @@ For each issue number, check whether an open PR or branch already targets it:
```bash
# Open PRs that link the issue
gh pr list --repo <owner>/<repo> --state open --search "linked:#<NUMBER>" --json number,title,headRefName
gh pr list --repo <owner>/<repo> --state open --search "linked:#<NUMBER>" --json number,title,headRefName,updatedAt,author
# Local branches that mention the issue number
git branch -a | grep -E "(^|/)(feat|fix|refactor)/.*-?<NUMBER>(-|$)" || true
@@ -204,9 +209,73 @@ git branch -a | grep -E "(^|/)(feat|fix|refactor)/.*-?<NUMBER>(-|$)" || true
If a PR or branch already exists:
- Mark the idea file with `> ⚠️ In-flight: PR #<PR_NUMBER> / branch <name>` near the top.
- Mark the idea file with `> ⚠️ In-flight: PR #<PR_NUMBER> by @<author> / branch <name> (last activity <date>)` near the top.
- **Skip Phase 2 research and Phase 4 planning** for this feature — the implementation is already in motion.
- In the Phase 3 report, list it under a separate "🚧 Already in progress" bucket; do NOT count it as VIABLE for implementation.
- The idea file will be moved to `_ideia/in_flight/` in Phase 2.5.2 (it stays there permanently, but Phase 1.7 may reclaim it later).
### 1.7 Stale Reclaim (15-day rule)
Some issues sit in `in_flight/` or `need_details/` forever — third-party PRs go cold, authors disappear, the world moves on. This phase reclaims them when they go quiet.
**Trigger conditions** (run for each issue currently in `_ideia/in_flight/` or `_ideia/need_details/`):
```bash
# For IN FLIGHT — last activity on the linked PR (commit OR comment)
gh pr view <PR_NUMBER> --repo <owner>/<repo> --json updatedAt,commits,comments \
--jq '[.updatedAt, (.commits[-1].committedDate // ""), (.comments[-1].createdAt // "")] | max'
# For NEEDS DETAIL — last activity from the issue author (any comment by them)
gh issue view <NUMBER> --repo <owner>/<repo> --json comments,author \
--jq '.author.login as $a | [.comments[] | select(.author.login == $a) | .createdAt] | max // (.createdAt)'
```
Compute the gap in days between the timestamp above and today.
**Reclaim rule:**
| Bucket | Trigger | Action |
| --------------- | ------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------- |
| 🚧 IN FLIGHT | ≥15 days since last PR activity (commit OR comment by PR author) | Post **intent-to-take-over comment** (template below), wait **48h**, then reclaim if no response |
| ❓ NEEDS DETAIL | ≥15 days since last comment by the issue author | Post **gentle nudge** (template below), wait **48h**, then reclaim as VIABLE if no response |
**Intent-to-take-over comment (🚧 IN FLIGHT path)** — translate to `reply_lang`:
```markdown
Hi @<pr_author> and @<issue_author>! 👋
This PR (#<PR>) addressing issue #<NUMBER> hasn't had updates in <N> days. We'd love to ship this feature in our next release.
**Plan:** if there are no updates in the next **48 hours**, our team will take over the work and merge it as part of `release/vX.Y.Z`. The original PR will be referenced and authorship preserved in the commit trailer.
If you're still working on it, just drop a comment here and we'll hold off. Thanks for the contribution either way! 🙏
```
**Gentle nudge (❓ NEEDS DETAIL path)** — translate to `reply_lang`:
```markdown
Hi @<author>! 👋
It's been <N> days since we asked for more details on this feature request. We'd still love to move forward.
**Plan:** if we don't hear back in the next **48 hours**, we'll proceed with our best interpretation of the original request and add it to our backlog for implementation. We'll tag you on the implementation PR so you can review before it ships.
If you still want to provide the details, just reply here — we'll wait. 🙏
```
**Reclaim execution** (only after the 48h grace period, with no new author/PR-author activity):
1. Move the idea file to `_ideia/viable/` (preserve any prior content + add a `> ♻️ Reclaimed on <date> after 15-day inactivity` banner near the top).
2. If it was IN FLIGHT and a research file does not yet exist, run Phase 2 (Research) for it now.
3. Otherwise create the requirements file based on the existing content + a quick research pass.
4. Add a `viable_origin: stale_reclaim` line to the front-matter so the Phase 3 report can flag it.
5. In Phase 5 (commit / PR), include a commit trailer crediting the original PR author if applicable:
```
Originally-proposed-by: @<pr_author> in #<original_pr_number>
```
(This is NOT `Co-Authored-By` — hard rule #16 still applies. It is a free-form trailer that preserves credit without GitHub re-attributing the commit.)
> **Why 15 days + 48h grace?** Long enough that the original contributor has truly moved on; short enough that the feature still ships in the same release cycle. Grace period is documented in `feedback_issue_triage_independence` so we don't default to "trust prior triage" — we verify the silence is real.
---
@@ -364,12 +433,16 @@ For each researched feature, create a requirements file alongside its idea file:
```bash
mkdir -p <project_root>/_ideia/viable
mkdir -p <project_root>/_ideia/viable/need_details
mkdir -p <project_root>/_ideia/implemented
mkdir -p <project_root>/_ideia/need_details
mkdir -p <project_root>/_ideia/defer
mkdir -p <project_root>/_ideia/notfit
mkdir -p <project_root>/_ideia/exists
mkdir -p <project_root>/_ideia/in_flight
```
> **Permanent archives**: `need_details/`, `defer/`, `notfit/`, `exists/`, `in_flight/`. Even after the upstream issue is closed, the local file stays — future cycles may revisit.
### 2.5.2 Move Idea Files to Category Subdirectories
After classification, move EVERY idea file to its correct subdirectory (still local-only — no GitHub side-effects):
@@ -379,19 +452,23 @@ After classification, move EVERY idea file to its correct subdirectory (still lo
mv _ideia/<NUMBER>-*.md _ideia/viable/
mv _ideia/<NUMBER>-*.requirements.md _ideia/viable/
# ❓ NEEDS DETAIL — viable but waiting for author response
mv _ideia/<NUMBER>-*.md _ideia/viable/need_details/
# ❓ NEEDS DETAIL — viable but waiting for author response (issue stays OPEN)
mv _ideia/<NUMBER>-*.md _ideia/need_details/
# ⏭️ DEFER — move idea files only
# ⏭️ DEFER — issue will be CLOSED but file is kept permanently for future re-evaluation
mv _ideia/<NUMBER>-*.md _ideia/defer/
# ❌ NOT FIT & 🔁 ALREADY EXISTS — move idea files only
# ❌ NOT FIT — issue will be CLOSED but file is kept permanently
mv _ideia/<NUMBER>-*.md _ideia/notfit/
# 🚧 IN FLIGHT — leave in _ideia/ root with a top-of-file banner; do NOT touch the PR/branch
# 🔁 ALREADY EXISTS — issue will be CLOSED but file is kept permanently (separate bucket from NOT FIT)
mv _ideia/<NUMBER>-*.md _ideia/exists/
# 🚧 IN FLIGHT — issue stays OPEN, third-party PR is handling it; file kept permanently for Phase 1.7 stale-reclaim
mv _ideia/<NUMBER>-*.md _ideia/in_flight/
```
No idea files should remain in `_ideia/` root after this step except `🚧 IN FLIGHT` entries.
No idea files should remain in `_ideia/` root after this step.
---
@@ -405,14 +482,15 @@ Present a structured report containing:
#### 3.1a — Feature Summary Table
| # | Issue | Title | Verdict | Local Location | Planned GitHub Action |
| --- | ----- | ----- | --------------- | ----------------------------- | -------------------------------- |
| 1 | #N | Title | ✅ VIABLE | `_ideia/viable/` | Comment + keep OPEN |
| 2 | #N | Title | ⏭️ DEFER | `_ideia/defer/` | Comment + CLOSE |
| 3 | #N | Title | ❌ NOT FIT | `_ideia/notfit/` | Comment + CLOSE |
| 4 | #N | Title | 🔁 EXISTS | `_ideia/notfit/` | Comment with location + CLOSE |
| 5 | #N | Title | ❓ NEEDS DETAIL | `_ideia/viable/need_details/` | Comment with questions + OPEN |
| 6 | #N | Title | 🚧 IN FLIGHT | `_ideia/` (banner) | None — PR #M already handles it |
| # | Issue | Title | Verdict | Local Location | Planned GitHub Action |
| --- | ----- | ----- | ----------------- | ----------------------- | -------------------------------------- |
| 1 | #N | Title | ✅ VIABLE | `_ideia/viable/` | Comment + keep OPEN |
| 2 | #N | Title | ⏭️ DEFER | `_ideia/defer/` | Comment + CLOSE |
| 3 | #N | Title | ❌ NOT FIT | `_ideia/notfit/` | Comment + CLOSE |
| 4 | #N | Title | 🔁 EXISTS | `_ideia/exists/` | Comment with location + CLOSE |
| 5 | #N | Title | ❓ NEEDS DETAIL | `_ideia/need_details/` | Comment with questions + keep OPEN |
| 6 | #N | Title | 🚧 IN FLIGHT | `_ideia/in_flight/` | None — PR #M handles it |
| 7 | #N | Title | ♻️ RECLAIMED | `_ideia/viable/` | Intent comment posted in Phase 1.7 |
#### 3.1b — Viable Features Detail
@@ -799,22 +877,23 @@ rm _ideia/implemented/<NUMBER>-*.md
Present a final summary report to the user:
| Issue | Title | Verdict | Action | Commit |
| ----- | ----- | --------------- | -------------------------------------------------- | --------- |
| #N | Title | ✅ Implemented | Issue closed, idea file in `_ideia/implemented/` | `abc1234` |
| #N | Title | ⏭️ Deferred | Issue closed + saved in `_ideia/defer/` | — |
| #N | Title | ❌ Not Fit | Issue closed + saved in `_ideia/notfit/` | — |
| #N | Title | 🔁 Exists | Issue closed + saved in `_ideia/notfit/` | — |
| #N | Title | ❓ Needs Detail | Issue OPEN, moved to `_ideia/viable/need_details/` | — |
| #N | Title | 🚧 In Flight | Untouched — tracked by PR #M | — |
| Issue | Title | Verdict | Action | Commit |
| ----- | ----- | ---------------- | --------------------------------------------------------------- | --------- |
| #N | Title | ✅ Implemented | Issue closed, idea file in `_ideia/implemented/` (until merge) | `abc1234` |
| #N | Title | ♻️ Reclaimed | Was IN FLIGHT / NEEDS DETAIL, reclaimed after 15d → implemented | `abc1234` |
| #N | Title | ⏭️ Deferred | Issue closed + permanent archive in `_ideia/defer/` | — |
| #N | Title | ❌ Not Fit | Issue closed + permanent archive in `_ideia/notfit/` | — |
| #N | Title | 🔁 Exists | Issue closed + permanent archive in `_ideia/exists/` | — |
| #N | Title | ❓ Needs Detail | Issue OPEN, archive in `_ideia/need_details/` | — |
| #N | Title | 🚧 In Flight | Issue OPEN, archive in `_ideia/in_flight/`, tracked by PR #M | — |
Include:
- Total features harvested
- Total ideas cataloged (`viable/need_details/` + `defer/` + `notfit/`)
- Total ideas archived per bucket (`need_details/` / `defer/` / `notfit/` / `exists/` / `in_flight/`)
- Total features implemented (idea files in `_ideia/implemented/`, awaiting post-merge cleanup)
- Total features deferred
- Total reclaimed via Phase 1.7 (stale 15-day rule)
- Total issues closed
- Total issues left open (NEEDS DETAIL + VIABLE-pending-implementation + IN FLIGHT)
- Total issues left open (NEEDS DETAIL + VIABLE-pending + IN FLIGHT)
- Audit results: lint / typecheck / cycles / build / coverage (pass-count per phase)
- Languages used in posted comments (e.g. "3× pt-BR, 5× en, 1× es")

2
.agents/skills/review-discussions/SKILL.md
View File

@@ -49,7 +49,7 @@ For each discussion, extract:
- **Category** (Announcements, General, Ideas, Q&A, Show and tell)
- **Created** + **Last updated** (ISO date)
- **Summary** of original post (1-2 sentences)
- **Comment count** + **last commenter** + **last comment date**
- **Comment count** + **last commenter** + **last comment date** — determine these by **chronological `createdAt`**, not iteration order. Comments and their nested replies must be merged into a single sorted timeline before picking the latest event (otherwise a recent top-level reply gets shadowed by an older nested reply of an earlier comment, and the discussion is misclassified).
- **Maintainer involvement**: whether the repo owner already replied, and how many times
- **Pending action** — derived state, see categories below
- **Attachments**: count of screenshots / videos / pastebin links

414
.agents/workflows/generate-release-ag.md
View File

@@ -1,10 +1,10 @@
---
description: Create a new release, bump version up to the .999 patch threshold, update changelog, and manage Pull Requests
description: Create a new release, bump version up to the .999 patch threshold, generate a complete CHANGELOG (with PR co-authors + every commit since the last tag), and manage Pull Requests
---
# Generate Release Workflow
Bump version, finalize CHANGELOG, commit, open a **PR to main** and wait for user confirmation before tagging, publishing, and deploying.
Bump version, build a **complete CHANGELOG** from every commit since the last tag (with PR back-reference and contributor attribution), commit, open a **PR to main** and wait for user confirmation before tagging, publishing, and deploying.
> **VERSION RULE: Always use PATCH bumps (3.x.y → 3.x.y+1)**
> NEVER use `npm version minor` or `npm version major`.
@@ -15,12 +15,16 @@ Bump version, finalize CHANGELOG, commit, open a **PR to main** and wait for use
---
## ⚠️ Two-Phase Flow
## ⚠️ Four-Phase Flow
```
Phase 1 (automated): bump → docs → i18n → commit → push → open PR
↕ 🛑 STOP: Notify user, wait for PR confirmation
Phase 2 (post-merge): tag → publish → GitHub release → Docker → deploy
Phase 0 → security audit (npm + CodeQL + Dependabot)
Phase 1 → bump → full quality gate → changelog from commits → commit → push → open PR
↕ 🛑 STOP: notify user, wait for PR merge
Phase 2 → deploy main to Local VPS for homologation
↕ 🛑 STOP: notify user, wait for OK
Phase 3 → tag → GitHub release → Docker → npm → Akamai
Phase 4 → monitor CI pipelines and validate artifacts
```
**NEVER push directly to main or create tags before the user confirms the PR.**
@@ -29,111 +33,167 @@ Phase 2 (post-merge): tag → publish → GitHub release → Docker → deploy
## Phase 0: Security Verification (MANDATORY)
Before creating the release, you must ensure the codebase and supply chain are secure and free of known vulnerabilities.
```bash
# 1. Local dependency audit
npm audit --production --audit-level=high
1. **Run Local Dependencies Audit:**
# 2. GitHub CodeQL alerts (open + high severity)
gh api '/repos/diegosouzapw/OmniRoute/code-scanning/alerts?state=open&severity=high' \
--jq '.[] | {rule: .rule.id, path: .most_recent_instance.location.path, msg: .most_recent_instance.message.text}' \
2>/dev/null || echo "(no CodeQL access or no alerts)"
```bash
npm audit
```
# 3. Dependabot alerts (open + high/critical)
gh api '/repos/diegosouzapw/OmniRoute/dependabot/alerts?state=open' \
--jq '.[] | select(.security_advisory.severity == "high" or .security_advisory.severity == "critical") | {pkg: .dependency.package.name, sev: .security_advisory.severity, summary: .security_advisory.summary}' \
2>/dev/null || echo "(no Dependabot access or no alerts)"
```
_Fix any `high` or `critical` vulnerabilities identified._
2. **Check GitHub CodeQL & Dependabot Alerts:**
Navigate to the repository's **Security** tab on GitHub, or use the project's `vulnerability-scanner` skill to analyze active alerts. Ensure all static analysis findings (e.g., prototype pollution, insecure randomness, ReDoS, shell injections) are addressed and logically committed on a target branch.
Fix or justify (per Hard Rule #14) any `high`/`critical` findings before proceeding.
---
## Phase 1: Pre-Merge
### 1. Create release branch
### 1. Create or confirm release branch
```bash
git checkout -b release/v3.x.y
# First release on a new minor (e.g. starting 3.9.0):
git checkout -b release/v3.9.0
# Continuing current cycle:
git branch --show-current
```
### 2. Determine and sync version
Check current version in `package.json`:
```bash
grep '"version"' package.json
```
> **🔴 BRANCH-VERSION PARITY RULE**: The logical version in `package.json` MUST exactly match the release branch name. For example, if you are on `release/v3.7.0`, the version in `package.json` MUST be `3.7.0`.
>
> - If this is the FIRST time generating a release for a new minor/major branch (e.g., bumping from 3.6.9 to 3.7.0), you MUST ensure the version is bumped to match the new branch logic.
> - If you are just bumping a patch on the current branch (e.g., 3.6.9 to 3.6.10), use:
> `npm version patch --no-git-tag-version`
> **🔴 BRANCH-VERSION PARITY GATE**:
> **⚠️ ATOMIC COMMIT RULE — Version bump MUST happen before committing feature files.**
>
> **CORRECT order:**
>
> 1. `npm version patch --no-git-tag-version` ← bump first
> 2. implement features / fix bugs
> 3. `git add -A && git commit -m "chore(release): v3.x.y — all changes in ONE commit"`
>
> **OR if features are already staged:**
>
> 1. implement features (do NOT commit yet)
> 2. `npm version patch --no-git-tag-version` ← bump before committing
> 3. `git add -A && git commit -m "chore(release): v3.x.y — all changes in ONE commit"`
>
> **NEVER do this (creates version mismatch in git history):**
>
> - ~~commit features → then bump version → commit package.json separately~~
>
> This ensures that `git show v3.x.y` always contains both code changes and the version bump together.
> The GitHub release tag will point to a commit that includes ALL changes for that version.
```bash
BRANCH=$(git branch --show-current)
BRANCH_VER=${BRANCH#release/v}
PKG_VER=$(node -p "require('./package.json').version")
if [[ "$BRANCH" != release/v* ]]; then
echo "❌ Not on a release/v* branch (current: $BRANCH). Aborting."; exit 1
fi
echo "Branch target: $BRANCH_VER"
echo "package.json: $PKG_VER"
```
> **⚠️ ATOMIC COMMIT RULE** — bump and feature/fix code MUST land in the same commit so that `git show vX.Y.Z` always contains both. NEVER commit features first and bump in a separate commit.
```bash
npm version patch --no-git-tag-version
```
### 3. Regenerate lock file (REQUIRED after version bump)
**Mandatory** — skipping causes `@swc/helpers` lock mismatch and CI failures:
```bash
npm install
```
### 4. Finalize CHANGELOG.md
### 4. Build CHANGELOG from EVERY commit since the last tag
> **🔴 NO MIXUPS RULE**: Ensure you do NOT mix the backlog of the previous version with the new one. The new version section must ONLY contain the features and fixes for the current release.
> **🎯 Goal**: produce a complete CHANGELOG section — emoji-grouped sections, PR back-reference, and `— thanks @user` attribution. Nothing must slip through.
Replace the `[Unreleased]` header with the new version and date.
Keep an empty `## [Unreleased]` section above it, separated by a horizontal rule (`---`).
> **🔴 NO MIXUPS RULE**: do not mix backlog of the previous version. The new section must contain ONLY commits whose merge/landing happened after the previous tag.
#### 4a. Collect raw commit log since last tag
```bash
LAST_TAG=$(git describe --tags --abbrev=0)
NEW_VERSION=$(node -p "require('./package.json').version")
TODAY=$(date -u +%F)
echo "Range: $LAST_TAG..HEAD → v$NEW_VERSION ($TODAY)"
git log --no-merges "$LAST_TAG..HEAD" --pretty=format:'%h %s' > /tmp/release_commits.txt
wc -l /tmp/release_commits.txt
git log --merges "$LAST_TAG..HEAD" --pretty=format:'%h %s%n author=%an <%ae>' > /tmp/release_merges.txt
git log "$LAST_TAG..HEAD" --pretty=format:'---%n%h | %s%n author=%an <%ae>%n body=%b' > /tmp/release_detailed.txt
```
#### 4b. Enrich with PR metadata + co-authors
```bash
grep -oE '#[0-9]+' /tmp/release_commits.txt | sort -u > /tmp/release_prs.txt
> /tmp/release_pr_meta.json
while read -r PR; do
N=${PR#\#}
gh pr view "$N" --repo diegosouzapw/OmniRoute \
--json number,title,author,mergeCommit,body \
>> /tmp/release_pr_meta.json 2>/dev/null || echo "(skip $PR — not found)"
echo "" >> /tmp/release_pr_meta.json
done < /tmp/release_prs.txt
```
#### 4c. Assemble the new CHANGELOG section
Using `/tmp/release_commits.txt` + `/tmp/release_pr_meta.json` + `/tmp/release_detailed.txt`, build a new entry that:
1. **Covers every commit** — read the full list and group by Conventional Commit type. A commit is "covered" iff it appears (or is intentionally rolled-up) in the new section.
2. **Groups using these section headers**:
- `### ✨ New Features` — `feat(*)`
- `### 🔧 Bug Fixes` — `fix(*)`
- `### 📝 Maintenance` — `chore(*)`, `refactor(*)`, `docs(*)`, `test(*)`, `ci(*)`, `build(*)`
- `### 🔒 Security` — security-flagged commits (only if any)
3. **Entry format**:
```
- **type(scope):** human-friendly description — extra context if useful. ([#PR](https://github.com/diegosouzapw/OmniRoute/pull/PR) — thanks @author / @coauthor1 / @coauthor2)
```
- No PR referenced (direct commit on release branch): `(thanks @author)`.
- PR closed an external contributor's PR via cherry-pick or re-implementation: attribute BOTH (`thanks @originalAuthor / @diegosouzapw`).
- **Co-authors** extracted from merge commit body and from PR participants who supplied commits.
4. **Coverage check** — diff the section against `/tmp/release_commits.txt`. Any unlisted commit must either be explicitly added or consolidated under a roll-up bullet. Do NOT silently drop commits.
Layout in `CHANGELOG.md` (right below `## [Unreleased]`):
```markdown
## [Unreleased]
---
## [3.7.0] — 2026-04-19
## [3.9.0] — 2026-05-27
### ✨ New Features
- ...
- **feat(scope):** description ([#1234](https://github.com/diegosouzapw/OmniRoute/pull/1234) — thanks @author)
### 🐛 Bug Fixes
### 🔧 Bug Fixes
- ...
- **fix(scope):** description ([#1235](https://github.com/diegosouzapw/OmniRoute/pull/1235) — thanks @author / @diegosouzapw)
### 🏆 Hall of Contributors
### 📝 Maintenance
A special thanks to everyone who contributed code, reviews, and tests for this release:
@user1, @user2
- **chore(scope):** description (thanks @diegosouzapw)
---
## [3.6.9] — 2026-04-19
## [3.8.999] — 2026-05-20
```
> **🔴 HALL OF CONTRIBUTORS RULE**: You MUST parse all the PR author mentions (e.g., `(thanks @username)`) from the new version's changelog items, deduplicate them, and append them as a "Hall of Contributors" section at the end of the new release block, exactly as shown above.
#### 4d. Coverage assertion
### 5. Update openapi.yaml version ⚠️ MANDATORY
```bash
NEW_VERSION=$(node -p "require('./package.json').version")
COMMITS=$(wc -l < /tmp/release_commits.txt)
BULLETS=$(awk "/^## \\[$NEW_VERSION\\]/{flag=1;next} /^## \\[/{flag=0} flag" CHANGELOG.md | grep -c '^- ')
> **CI will fail** if `docs/reference/openapi.yaml` version ≠ `package.json` version (`check:docs-sync` enforces this).
echo "Commits in range: $COMMITS"
echo "Changelog bullets: $BULLETS"
if [ "$BULLETS" -lt $(( COMMITS / 3 )) ]; then
echo "⚠️ Bullet count looks low (< commits/3). Re-review /tmp/release_commits.txt for missed entries."
fi
```
// turbo
### 5. Sync versioned files ⚠️ MANDATORY
```bash
VERSION=$(node -p "require('./package.json').version")
@@ -146,205 +206,212 @@ for dir in electron open-sse; do
echo "✓ $dir/package.json → $VERSION"
fi
done
# Re-run install to assert the workspace lockfile is updated
npm install
```
### 6. Update README.md and i18n docs
### 6. Sync README.md and i18n docs
Manually perform these documentation updates (there is no `/update-docs` workflow — it was deprecated in v3.8):
No `/update-docs` workflow exists (deprecated in v3.8). Apply manually OR via parallel agents:
- Update feature table rows and "What's new in vX.Y.Z" section in `README.md`
- Sync feature changes to all 40 language `docs/i18n/*/README.md` files (use the same row edits across each translated README)
- Update the relevant `docs/<AREA>.md` if architecture or counts changed
- Re-run `npm run check:docs-sync` and `npm run check:docs-all` to catch drift
1. Apply the substantive change to `README.md` first (feature table row + "What's new in vX.Y.Z" section).
2. Capture the diff: `git diff README.md > /tmp/readme.patch`.
3. Dispatch 5-10 parallel agents, each handling a slice of the 40 `docs/i18n/*/README.md`, translating the diff into the target language.
4. Update `docs/<AREA>.md` if architecture/counts changed.
5. Validate: `npm run check:docs-sync && npm run check:docs-all`.
### 7. Run tests
### 7. Full quality gate (MANDATORY — replaces the old `npm test`)
// turbo
> **Precedent**: v3.8.2 landed with 49 broken tests because only `npm test` was running. Lint + typecheck + cycles caught zero of those regressions.
```bash
set -e
npm run lint
npm run typecheck:core
npm run check:cycles
npm run check:docs-all
npm test
```
All tests must pass before creating the PR.
All five must pass before opening the PR.
### 8. Stage, commit, and push
// turbo-all
### 8. Stage, commit, and push (atomic — bump + features + changelog + i18n in ONE commit)
```bash
VERSION=$(node -p "require('./package.json').version")
git add -A
git commit -m "chore(release): v3.x.y — summary of changes"
git push origin release/v3.x.y
git commit -m "chore(release): v$VERSION — $(date -u +%F)"
git push origin "release/v$VERSION"
```
### 9. Open PR to main
> **NEVER** include `Co-Authored-By:` trailers in the release commit (Hard Rule #16). Attribution lives inside the CHANGELOG entries.
### 9. Open PR to main
// turbo
```bash
VERSION=$(node -p "require('./package.json').version")
# Extract the exact changelog entry for this version from the root CHANGELOG.md
awk "/^## \\[$VERSION\\]/{flag=1; print; next} /^---/{if(flag) {flag=0; exit}} flag" CHANGELOG.md > /tmp/changelog_body.txt
# Append test status and next steps
echo "" >> /tmp/changelog_body.txt
echo "### Tests" >> /tmp/changelog_body.txt
echo "- All tests pass" >> /tmp/changelog_body.txt
echo "" >> /tmp/changelog_body.txt
echo "### ⚠️ After merging: run Phase 2 steps to tag, publish, and deploy." >> /tmp/changelog_body.txt
{
echo ""
echo "---"
echo ""
echo "### Quality Gate"
echo "- lint: pass"
echo "- typecheck:core: pass"
echo "- check:cycles: pass"
echo "- check:docs-all: pass"
echo "- tests: pass"
echo ""
echo "### Coverage of commits since previous tag"
LAST_TAG=$(git describe --tags --abbrev=0 HEAD~1 2>/dev/null || echo "(no previous tag)")
COMMITS=$(git rev-list --no-merges "$LAST_TAG..HEAD" | wc -l)
echo "- Range: \`$LAST_TAG..HEAD\`"
echo "- Commits inspected: $COMMITS"
echo ""
echo "### ⚠️ After merging: run Phase 2 (Local VPS homologation) before tagging."
} >> /tmp/changelog_body.txt
gh pr create \
--repo diegosouzapw/OmniRoute \
--base main \
--head release/v$VERSION \
--head "release/v$VERSION" \
--title "Release v$VERSION" \
--body-file /tmp/changelog_body.txt
```
### 10. 🛑 STOP — Notify User & Await PR Confirmation
### 10. 🛑 STOP — Notify user & await PR confirmation
**This is a mandatory stop point.** Present the report in the final response and stop. Do not continue to the next phase until the user explicitly approves.
Inform the user:
Present the report and stop. Provide:
- PR URL
- Summary of changes
- Test results
- List of files changed
- Summary of changes (top 5 from CHANGELOG)
- Quality gate results
- `git diff --stat $LAST_TAG..HEAD`
- Coverage count vs commits-in-range
**DO NOT proceed to Phase 2 until the user confirms the PR looks good and merges it.**
**DO NOT proceed to Phase 2 until the user confirms.**
---
## Phase 2: Post-Merge Validation (Local VPS)
> Run these steps only AFTER the user has merged the PR into `main` and all CI jobs have passed.
> Run only AFTER the user has merged the PR into `main` and all CI jobs pass.
### 11. Deploy to Local VPS for Final Validation (MANDATORY)
### 11. Deploy `main` to the Local VPS
Before cutting the official git tag and publishing to the world, deploy the `main` branch to the Local VPS for a final homologation test.
Delegate to the `deploy-vps-local-ag` workflow (single source of truth — do NOT inline SCP/SSH here):
```bash
git checkout main
git pull origin main
# Build and pack locally
cd /home/diegosouzapw/dev/proxys/OmniRoute && rm -f omniroute-*.tgz && rm -rf .next/cache app/.next/cache && npm run build:cli && rm -rf app/logs app/coverage app/.git app/.app-build-backup* && npm pack --ignore-scripts
# Deploy to LOCAL VPS (192.168.0.15)
scp omniroute-*.tgz root@192.168.0.15:/tmp/
ssh root@192.168.0.15 "npm install -g /tmp/omniroute-*.tgz --ignore-scripts && cd /usr/lib/node_modules/omniroute/app && npm rebuild better-sqlite3 && pm2 delete omniroute 2>/dev/null; pm2 start /root/.omniroute/ecosystem.config.cjs --update-env && pm2 save && echo '✅ Local done'"
# Verify
curl -s -o /dev/null -w "LOCAL: HTTP %{http_code}\n" http://192.168.0.15:20128/
```
/deploy-vps-local-ag
```
### 12. 🛑 STOP — Notify User & Await Final OK
### 12. 🛑 STOP — Notify user & await final OK
**This is a mandatory stop point.**
Inform the user that the `main` branch is now running on the Local VPS.
Wait for the user to manually test and give the **OK**.
**DO NOT proceed to Phase 3 until the user confirms the local deploy is stable.**
Provide smoke-test checklist:
- [ ] `GET /` returns 200
- [ ] Dashboard login works (`/dashboard`)
- [ ] `/v1/chat/completions` with default provider returns a stream
- [ ] No critical errors in `pm2 logs omniroute --lines 100`
- [ ] Any release-specific UI features are reachable
Wait for user **OK** before Phase 3.
---
## Phase 3: Official Launch
> Run these steps only AFTER the user gives the final OK from the Phase 2 local validation.
### 13. Create Git Tag and GitHub Release (MANDATORY)
// turbo
### 13. Create git tag and GitHub Release
```bash
git checkout main
git pull origin main
VERSION=$(node -p "require('./package.json').version")
# Extracts the changelog section for this version
NOTES=$(awk "/^## \\[$VERSION\\]/{flag=1; next} /^---/{if(flag) {flag=0; exit}} flag" CHANGELOG.md | sed -e 's/^[[:space:]]*//' -e 's/[[:space:]]*$//')
if [ -z "$NOTES" ]; then NOTES="OmniRoute v$VERSION Release"; fi
[ -z "$NOTES" ] && NOTES="OmniRoute v$VERSION Release"
git tag -a "v$VERSION" -m "Release v$VERSION"
git push origin "v$VERSION"
gh release create "v$VERSION" --repo diegosouzapw/OmniRoute --title "v$VERSION" --notes "$NOTES" --target main || gh release edit "v$VERSION" --repo diegosouzapw/OmniRoute --title "v$VERSION" --notes "$NOTES"
gh release create "v$VERSION" \
--repo diegosouzapw/OmniRoute \
--title "v$VERSION" \
--notes "$NOTES" \
--target main \
|| gh release edit "v$VERSION" \
--repo diegosouzapw/OmniRoute \
--title "v$VERSION" \
--notes "$NOTES"
```
### 14. 🐳 Trigger Docker Hub build (MANDATORY — keep npm and Docker in sync)
> **CRITICAL**: Docker Hub and npm MUST always publish the same version.
> The Docker image is built automatically via GitHub Actions when a new tag is pushed.
> After pushing the tag in step 13, **verify the workflow runs**:
### 14. 🐳 Trigger / verify Docker Hub build
```bash
# Verify the Docker workflow triggered
gh run list --repo diegosouzapw/OmniRoute --workflow docker-publish.yml --limit 3
# Wait for the Docker build to complete (usually 5–10 min)
gh run watch --repo diegosouzapw/OmniRoute
```
### 15. Publish to NPM (Optional/Automated)
Normally handled by CI, but if manual publish is required:
### 15. Publish to npm (usually CI)
```bash
npm publish
```
## Phase 4: Release Monitoring & Artifact Validation
> After triggering the official release, actively monitor the CI pipelines until all artifacts are successfully generated. If any pipeline fails, stop and apply the necessary corrections before continuing.
### 16. Monitor CI Pipelines
Wait for and verify the successful completion of the following automated jobs:
1. **Docker Hub Publish**
2. **Electron Build**
3. **NPM Registry Publish** (Check with `npm info omniroute version`)
```bash
# Monitor Docker Hub workflow
gh run list --repo diegosouzapw/OmniRoute --workflow docker-publish.yml --limit 1
gh run watch <RUN_ID>
# Monitor Electron build
gh run list --repo diegosouzapw/OmniRoute --workflow electron-release.yml --limit 1
gh run watch <RUN_ID>
# Verify NPM version
npm info omniroute version
```
### 17. Handle Failures (If Any)
### 16. Deploy to Akamai VPS (Production)
If a workflow fails:
Delegate to `deploy-vps-akamai-ag` workflow if available, or run the inline equivalent of `deploy-vps-local-ag` against `69.164.221.35`. Do NOT duplicate the procedure here.
- Use `gh run view <RUN_ID> --log-failed` to identify the error.
- Apply the fix on the `main` branch.
- If necessary, re-trigger the workflow using `gh workflow run <workflow_name.yml> --repo diegosouzapw/OmniRoute --ref v3.x.y`
### 18. Preserve release branch
### 17. Rollback playbook (use only if Phase 3 fails after tag push)
```bash
# Branch is kept for historical purposes. Do not delete.
VERSION=$(node -p "require('./package.json').version")
PREV=$(git describe --tags --abbrev=0 "v$VERSION^")
gh release edit "v$VERSION" --repo diegosouzapw/OmniRoute --prerelease
git checkout "$PREV" && /deploy-vps-akamai-ag
npm deprecate "omniroute@$VERSION" "broken release — use $PREV"
```
---
## Phase 4: Release Monitoring & Artifact Validation
### 18. Monitor CI pipelines
```bash
gh run list --repo diegosouzapw/OmniRoute --workflow docker-publish.yml --limit 1
gh run list --repo diegosouzapw/OmniRoute --workflow electron-release.yml --limit 1
gh run watch <RUN_ID>
npm info omniroute version
```
### 19. Handle failures
```bash
gh run view <RUN_ID> --log-failed
VERSION=$(node -p "require('./package.json').version")
gh workflow run <workflow.yml> --repo diegosouzapw/OmniRoute --ref "v$VERSION"
```
### 20. Preserve release branch
Branch is kept for historical purposes. Do not delete.
---
## Notes
- Ensure CHANGELOG, README and `docs/*` are current BEFORE this workflow — run `npm run check:docs-all` and `/version-bump` first (there is no `/update-docs` workflow anymore)
- The `prepublishOnly` script runs `npm run build:cli` automatically during `npm publish`
- After npm publish, verify with `npm info omniroute version`
- Lock file sync errors are caused by skipping `npm install` after version bump
- Use `gh auth switch -u diegosouzapw` if git push fails with wrong account
- Ensure CHANGELOG, README and `docs/*` are current BEFORE this workflow — run `npm run check:docs-all` first.
- The `prepublishOnly` script runs `npm run build:cli` automatically during `npm publish`.
- After npm publish, verify with `npm info omniroute version`.
- Lock file sync errors are caused by skipping `npm install` after version bump.
- Use `gh auth switch -u diegosouzapw` if `git push` fails with the wrong account.
- Deploy procedures live in dedicated workflows (`deploy-vps-local-ag`, `deploy-vps-akamai-ag` if present). Never inline SCP/SSH commands here.
## Known CI Pitfalls
@@ -354,3 +421,4 @@ If a workflow fails:
| `[docs-sync] FAIL - CHANGELOG.md first section must be "## [Unreleased]"` | `## [Unreleased]` missing or not at top of CHANGELOG | Add `## [Unreleased]\n\n---\n` before the first versioned `## [x.y.z]` |
| Electron Linux `.deb` build fails (`FpmTarget` error) | `fpm` Ruby gem not installed on `ubuntu-latest` runner | Already fixed in `electron-release.yml` (`gem install fpm` step) |
| Docker Hub `502 error writing layer blob` | Transient Docker Hub network error during ARM64 push | Re-run the Docker publish workflow; no code change needed |
| Coverage gate fails (statements/lines < 75% or branches < 70%) | Production code changed without tests | Add tests, re-run `npm run test:coverage` (see CLAUDE.md hard rule #9) |

154
.agents/workflows/implement-features-ag.md
View File

@@ -12,17 +12,21 @@ A **5-phase** workflow that systematically harvests feature requests from GitHub
```
_ideia/
├── viable/ # Features approved for implementation
│ ├── need_details/ # ❓ Good idea but waiting for author clarification (issues stay OPEN)
│ │ └── 1015-warp-terminal-mitm.md
│ ├── 1046-native-playground.md # ✅ Ready — researched and planned
├── viable/ # ✅ Approved, awaiting implementation
│ ├── 1046-native-playground.md
│ └── 1046-native-playground.requirements.md
├── implemented/ # 🚧 Implemented but PR not yet merged to main (transient)
├── implemented/ # ✅ Implemented but release PR not yet merged to main (transient)
│ └── 1046-native-playground.md
├── defer/ # ⏭️ Good ideas deferred for future cycles (issues CLOSED after Phase 3 approval)
├── need_details/ # ❓ Issue OPEN — awaiting author clarification (permanent archive)
│ └── 1015-warp-terminal-mitm.md
├── defer/ # ⏭️ Issue CLOSED — good idea, deferred for future cycles (permanent)
│ └── 1041-smart-auto-combos.md
└── notfit/ # ❌ Out of scope / already exists (issues CLOSED after Phase 3 approval)
└── 945-telegram-integration.md
├── notfit/ # ❌ Issue CLOSED — out of scope (permanent)
│ └── 945-telegram-integration.md
├── exists/ # 🔁 Issue CLOSED — feature already shipped (permanent, kept separate from notfit)
│ └── 812-rate-limit-dashboard.md
└── in_flight/ # 🚧 Issue OPEN — third-party PR already addresses it (permanent until reclaim or merge)
└── 988-batch-export.md
_tasks/features-vX.Y.Z/ # Implementation plans (per-release)
└── 1046-native-playground.plan.md
@@ -31,8 +35,8 @@ _tasks/features-vX.Y.Z/ # Implementation plans (per-release)
> **LIFECYCLE RULE:**
> - `viable/` files are **MOVED** to `implemented/` once code lands on the release branch.
> - `implemented/` files are **DELETED** only after the release PR is merged to `main`.
> - This preserves recovery context if implementation fails partially (build green but i18n missing, etc).
> - Files in `defer/` and `notfit/` remain as permanent reference.
> - All other buckets — `need_details/`, `defer/`, `notfit/`, `exists/`, `in_flight/` — are **permanent archives**. Even when the upstream issue is CLOSED, the local file stays. Future cycles can revisit any of them (Phase 1.7 stale-reclaim turns `in_flight/` and `need_details/` back into VIABLE after 15 days of upstream inactivity).
> - This preserves recovery context if implementation fails partially AND lets us re-evaluate old decisions when the project matures.
> **BRANCH RULE**: All implementation work MUST happen on the current `release/vX.Y.Z` branch. Never create separate `feat/` branches. If no release branch exists yet, delegate creation to `/generate-release` (see Phase 1.2) — do NOT reimplement bump logic here.
@@ -188,7 +192,7 @@ For each issue number, check whether an open PR or branch already targets it:
```bash
# Open PRs that link the issue
gh pr list --repo <owner>/<repo> --state open --search "linked:#<NUMBER>" --json number,title,headRefName
gh pr list --repo <owner>/<repo> --state open --search "linked:#<NUMBER>" --json number,title,headRefName,updatedAt,author
# Local branches that mention the issue number
git branch -a | grep -E "(^|/)(feat|fix|refactor)/.*-?<NUMBER>(-|$)" || true
@@ -196,9 +200,73 @@ git branch -a | grep -E "(^|/)(feat|fix|refactor)/.*-?<NUMBER>(-|$)" || true
If a PR or branch already exists:
- Mark the idea file with `> ⚠️ In-flight: PR #<PR_NUMBER> / branch <name>` near the top.
- Mark the idea file with `> ⚠️ In-flight: PR #<PR_NUMBER> by @<author> / branch <name> (last activity <date>)` near the top.
- **Skip Phase 2 research and Phase 4 planning** for this feature — the implementation is already in motion.
- In the Phase 3 report, list it under a separate "🚧 Already in progress" bucket; do NOT count it as VIABLE for implementation.
- The idea file will be moved to `_ideia/in_flight/` in Phase 2.5.2 (it stays there permanently, but Phase 1.7 may reclaim it later).
### 1.7 Stale Reclaim (15-day rule)
Some issues sit in `in_flight/` or `need_details/` forever — third-party PRs go cold, authors disappear, the world moves on. This phase reclaims them when they go quiet.
**Trigger conditions** (run for each issue currently in `_ideia/in_flight/` or `_ideia/need_details/`):
```bash
# For IN FLIGHT — last activity on the linked PR (commit OR comment)
gh pr view <PR_NUMBER> --repo <owner>/<repo> --json updatedAt,commits,comments \
--jq '[.updatedAt, (.commits[-1].committedDate // ""), (.comments[-1].createdAt // "")] | max'
# For NEEDS DETAIL — last activity from the issue author (any comment by them)
gh issue view <NUMBER> --repo <owner>/<repo> --json comments,author \
--jq '.author.login as $a | [.comments[] | select(.author.login == $a) | .createdAt] | max // (.createdAt)'
```
Compute the gap in days between the timestamp above and today.
**Reclaim rule:**
| Bucket | Trigger | Action |
| --------------- | ------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------- |
| 🚧 IN FLIGHT | ≥15 days since last PR activity (commit OR comment by PR author) | Post **intent-to-take-over comment** (template below), wait **48h**, then reclaim if no response |
| ❓ NEEDS DETAIL | ≥15 days since last comment by the issue author | Post **gentle nudge** (template below), wait **48h**, then reclaim as VIABLE if no response |
**Intent-to-take-over comment (🚧 IN FLIGHT path)** — translate to `reply_lang`:
```markdown
Hi @<pr_author> and @<issue_author>! 👋
This PR (#<PR>) addressing issue #<NUMBER> hasn't had updates in <N> days. We'd love to ship this feature in our next release.
**Plan:** if there are no updates in the next **48 hours**, our team will take over the work and merge it as part of `release/vX.Y.Z`. The original PR will be referenced and authorship preserved in the commit trailer.
If you're still working on it, just drop a comment here and we'll hold off. Thanks for the contribution either way! 🙏
```
**Gentle nudge (❓ NEEDS DETAIL path)** — translate to `reply_lang`:
```markdown
Hi @<author>! 👋
It's been <N> days since we asked for more details on this feature request. We'd still love to move forward.
**Plan:** if we don't hear back in the next **48 hours**, we'll proceed with our best interpretation of the original request and add it to our backlog for implementation. We'll tag you on the implementation PR so you can review before it ships.
If you still want to provide the details, just reply here — we'll wait. 🙏
```
**Reclaim execution** (only after the 48h grace period, with no new author/PR-author activity):
1. Move the idea file to `_ideia/viable/` (preserve any prior content + add a `> ♻️ Reclaimed on <date> after 15-day inactivity` banner near the top).
2. If it was IN FLIGHT and a research file does not yet exist, run Phase 2 (Research) for it now.
3. Otherwise create the requirements file based on the existing content + a quick research pass.
4. Add a `viable_origin: stale_reclaim` line to the front-matter so the Phase 3 report can flag it.
5. In Phase 5 (commit / PR), include a commit trailer crediting the original PR author if applicable:
```
Originally-proposed-by: @<pr_author> in #<original_pr_number>
```
(This is NOT `Co-Authored-By` — hard rule #16 still applies. It is a free-form trailer that preserves credit without GitHub re-attributing the commit.)
> **Why 15 days + 48h grace?** Long enough that the original contributor has truly moved on; short enough that the feature still ships in the same release cycle. Grace period is documented in `feedback_issue_triage_independence` so we don't default to "trust prior triage" — we verify the silence is real.
---
@@ -356,12 +424,16 @@ For each researched feature, create a requirements file alongside its idea file:
```bash
mkdir -p <project_root>/_ideia/viable
mkdir -p <project_root>/_ideia/viable/need_details
mkdir -p <project_root>/_ideia/implemented
mkdir -p <project_root>/_ideia/need_details
mkdir -p <project_root>/_ideia/defer
mkdir -p <project_root>/_ideia/notfit
mkdir -p <project_root>/_ideia/exists
mkdir -p <project_root>/_ideia/in_flight
```
> **Permanent archives**: `need_details/`, `defer/`, `notfit/`, `exists/`, `in_flight/`. Even after the upstream issue is closed, the local file stays — future cycles may revisit.
### 2.5.2 Move Idea Files to Category Subdirectories
After classification, move EVERY idea file to its correct subdirectory (still local-only — no GitHub side-effects):
@@ -371,19 +443,23 @@ After classification, move EVERY idea file to its correct subdirectory (still lo
mv _ideia/<NUMBER>-*.md _ideia/viable/
mv _ideia/<NUMBER>-*.requirements.md _ideia/viable/
# ❓ NEEDS DETAIL — viable but waiting for author response
mv _ideia/<NUMBER>-*.md _ideia/viable/need_details/
# ❓ NEEDS DETAIL — viable but waiting for author response (issue stays OPEN)
mv _ideia/<NUMBER>-*.md _ideia/need_details/
# ⏭️ DEFER — move idea files only
# ⏭️ DEFER — issue will be CLOSED but file is kept permanently for future re-evaluation
mv _ideia/<NUMBER>-*.md _ideia/defer/
# ❌ NOT FIT & 🔁 ALREADY EXISTS — move idea files only
# ❌ NOT FIT — issue will be CLOSED but file is kept permanently
mv _ideia/<NUMBER>-*.md _ideia/notfit/
# 🚧 IN FLIGHT — leave in _ideia/ root with a top-of-file banner; do NOT touch the PR/branch
# 🔁 ALREADY EXISTS — issue will be CLOSED but file is kept permanently (separate bucket from NOT FIT)
mv _ideia/<NUMBER>-*.md _ideia/exists/
# 🚧 IN FLIGHT — issue stays OPEN, third-party PR is handling it; file kept permanently for Phase 1.7 stale-reclaim
mv _ideia/<NUMBER>-*.md _ideia/in_flight/
```
No idea files should remain in `_ideia/` root after this step except `🚧 IN FLIGHT` entries.
No idea files should remain in `_ideia/` root after this step.
---
@@ -397,14 +473,15 @@ Present a structured report containing:
#### 3.1a — Feature Summary Table
| # | Issue | Title | Verdict | Local Location | Planned GitHub Action |
| --- | ----- | ----- | --------------- | ----------------------------- | -------------------------------- |
| 1 | #N | Title | ✅ VIABLE | `_ideia/viable/` | Comment + keep OPEN |
| 2 | #N | Title | ⏭️ DEFER | `_ideia/defer/` | Comment + CLOSE |
| 3 | #N | Title | ❌ NOT FIT | `_ideia/notfit/` | Comment + CLOSE |
| 4 | #N | Title | 🔁 EXISTS | `_ideia/notfit/` | Comment with location + CLOSE |
| 5 | #N | Title | ❓ NEEDS DETAIL | `_ideia/viable/need_details/` | Comment with questions + OPEN |
| 6 | #N | Title | 🚧 IN FLIGHT | `_ideia/` (banner) | None — PR #M already handles it |
| # | Issue | Title | Verdict | Local Location | Planned GitHub Action |
| --- | ----- | ----- | ----------------- | ----------------------- | -------------------------------------- |
| 1 | #N | Title | ✅ VIABLE | `_ideia/viable/` | Comment + keep OPEN |
| 2 | #N | Title | ⏭️ DEFER | `_ideia/defer/` | Comment + CLOSE |
| 3 | #N | Title | ❌ NOT FIT | `_ideia/notfit/` | Comment + CLOSE |
| 4 | #N | Title | 🔁 EXISTS | `_ideia/exists/` | Comment with location + CLOSE |
| 5 | #N | Title | ❓ NEEDS DETAIL | `_ideia/need_details/` | Comment with questions + keep OPEN |
| 6 | #N | Title | 🚧 IN FLIGHT | `_ideia/in_flight/` | None — PR #M handles it |
| 7 | #N | Title | ♻️ RECLAIMED | `_ideia/viable/` | Intent comment posted in Phase 1.7 |
#### 3.1b — Viable Features Detail
@@ -791,22 +868,23 @@ rm _ideia/implemented/<NUMBER>-*.md
Present a final summary report to the user:
| Issue | Title | Verdict | Action | Commit |
| ----- | ----- | --------------- | -------------------------------------------------- | --------- |
| #N | Title | ✅ Implemented | Issue closed, idea file in `_ideia/implemented/` | `abc1234` |
| #N | Title | ⏭️ Deferred | Issue closed + saved in `_ideia/defer/` | — |
| #N | Title | ❌ Not Fit | Issue closed + saved in `_ideia/notfit/` | — |
| #N | Title | 🔁 Exists | Issue closed + saved in `_ideia/notfit/` | — |
| #N | Title | ❓ Needs Detail | Issue OPEN, moved to `_ideia/viable/need_details/` | — |
| #N | Title | 🚧 In Flight | Untouched — tracked by PR #M | — |
| Issue | Title | Verdict | Action | Commit |
| ----- | ----- | ---------------- | --------------------------------------------------------------- | --------- |
| #N | Title | ✅ Implemented | Issue closed, idea file in `_ideia/implemented/` (until merge) | `abc1234` |
| #N | Title | ♻️ Reclaimed | Was IN FLIGHT / NEEDS DETAIL, reclaimed after 15d → implemented | `abc1234` |
| #N | Title | ⏭️ Deferred | Issue closed + permanent archive in `_ideia/defer/` | — |
| #N | Title | ❌ Not Fit | Issue closed + permanent archive in `_ideia/notfit/` | — |
| #N | Title | 🔁 Exists | Issue closed + permanent archive in `_ideia/exists/` | — |
| #N | Title | ❓ Needs Detail | Issue OPEN, archive in `_ideia/need_details/` | — |
| #N | Title | 🚧 In Flight | Issue OPEN, archive in `_ideia/in_flight/`, tracked by PR #M | — |
Include:
- Total features harvested
- Total ideas cataloged (`viable/need_details/` + `defer/` + `notfit/`)
- Total ideas archived per bucket (`need_details/` / `defer/` / `notfit/` / `exists/` / `in_flight/`)
- Total features implemented (idea files in `_ideia/implemented/`, awaiting post-merge cleanup)
- Total features deferred
- Total reclaimed via Phase 1.7 (stale 15-day rule)
- Total issues closed
- Total issues left open (NEEDS DETAIL + VIABLE-pending-implementation + IN FLIGHT)
- Total issues left open (NEEDS DETAIL + VIABLE-pending + IN FLIGHT)
- Audit results: lint / typecheck / cycles / build / coverage (pass-count per phase)
- Languages used in posted comments (e.g. "3× pt-BR, 5× en, 1× es")

2
.agents/workflows/review-discussions-ag.md
View File

@@ -41,7 +41,7 @@ For each discussion, extract:
- **Category** (Announcements, General, Ideas, Q&A, Show and tell)
- **Created** + **Last updated** (ISO date)
- **Summary** of original post (1-2 sentences)
- **Comment count** + **last commenter** + **last comment date**
- **Comment count** + **last commenter** + **last comment date** — determine these by **chronological `createdAt`**, not iteration order. Comments and their nested replies must be merged into a single sorted timeline before picking the latest event (otherwise a recent top-level reply gets shadowed by an older nested reply of an earlier comment, and the discussion is misclassified).
- **Maintainer involvement**: whether the repo owner already replied, and how many times
- **Pending action** — derived state, see categories below
- **Attachments**: count of screenshots / videos / pastebin links

438
.claude/commands/generate-release-cc.md
View File

@@ -1,10 +1,10 @@
---
description: Create a new release, bump version up to the .999 patch threshold, update changelog, and manage Pull Requests
description: Create a new release, bump version up to the .999 patch threshold, generate a complete CHANGELOG (with PR co-authors + every commit since the last tag), and manage Pull Requests
---
# Generate Release Workflow
Bump version, finalize CHANGELOG, commit, open a **PR to main** and wait for user confirmation before tagging, publishing, and deploying.
Bump version, build a **complete CHANGELOG** from every commit since the last tag (with PR back-reference and contributor attribution), commit, open a **PR to main** and wait for user confirmation before tagging, publishing, and deploying.
> **VERSION RULE: Always use PATCH bumps (3.x.y → 3.x.y+1)**
> NEVER use `npm version minor` or `npm version major`.
@@ -15,12 +15,16 @@ Bump version, finalize CHANGELOG, commit, open a **PR to main** and wait for use
---
## ⚠️ Two-Phase Flow
## ⚠️ Four-Phase Flow
```
Phase 1 (automated): bump → docs → i18n → commit → push → open PR
↕ 🛑 STOP: Notify user, wait for PR confirmation
Phase 2 (post-merge): tag → publish → GitHub release → Docker → deploy
Phase 0 → security audit (npm + CodeQL + Dependabot)
Phase 1 → bump → full quality gate → changelog from commits → commit → push → open PR
↕ 🛑 STOP: notify user, wait for PR merge
Phase 2 → deploy main to Local VPS for homologation
↕ 🛑 STOP: notify user, wait for OK
Phase 3 → tag → GitHub release → Docker → npm → Akamai
Phase 4 → monitor CI pipelines and validate artifacts
```
**NEVER push directly to main or create tags before the user confirms the PR.**
@@ -29,100 +33,200 @@ Phase 2 (post-merge): tag → publish → GitHub release → Docker → deploy
## Phase 0: Security Verification (MANDATORY)
Before creating the release, you must ensure the codebase and supply chain are secure and free of known vulnerabilities.
Before creating the release, ensure the codebase and supply chain are clean.
1. **Run Local Dependencies Audit:**
```bash
# 1. Local dependency audit
npm audit --production --audit-level=high
```bash
npm audit
```
# 2. GitHub CodeQL alerts (open + high severity)
gh api '/repos/diegosouzapw/OmniRoute/code-scanning/alerts?state=open&severity=high' \
--jq '.[] | {rule: .rule.id, path: .most_recent_instance.location.path, msg: .most_recent_instance.message.text}' \
2>/dev/null || echo "(no CodeQL access or no alerts)"
_Fix any `high` or `critical` vulnerabilities identified._
# 3. Dependabot alerts (open + high/critical)
gh api '/repos/diegosouzapw/OmniRoute/dependabot/alerts?state=open' \
--jq '.[] | select(.security_advisory.severity == "high" or .security_advisory.severity == "critical") | {pkg: .dependency.package.name, sev: .security_advisory.severity, summary: .security_advisory.summary}' \
2>/dev/null || echo "(no Dependabot access or no alerts)"
```
2. **Check GitHub CodeQL & Dependabot Alerts:**
Navigate to the repository's **Security** tab on GitHub, or use the project's `vulnerability-scanner` skill to analyze active alerts. Ensure all static analysis findings (e.g., prototype pollution, insecure randomness, ReDoS, shell injections) are addressed and logically committed on a target branch.
Fix or justify (with `vulnerability-scanner` skill or dismissal comment per Hard Rule #14) any `high`/`critical` findings before proceeding.
---
## Phase 1: Pre-Merge
### 1. Create release branch
### 1. Create or confirm release branch
```bash
git checkout -b release/v3.x.y
# If first release on this minor (e.g. starting 3.9.0):
git checkout -b release/v3.9.0
# If continuing the current cycle, just verify:
git branch --show-current
```
### 2. Determine and sync version
Check current version in `package.json`:
```bash
grep '"version"' package.json
```
> **🔴 BRANCH-VERSION PARITY RULE**: The logical version in `package.json` MUST exactly match the release branch name. For example, if you are on `release/v3.7.0`, the version in `package.json` MUST be `3.7.0`.
>
> - If this is the FIRST time generating a release for a new minor/major branch (e.g., bumping from 3.6.9 to 3.7.0), you MUST ensure the version is bumped to match the new branch logic.
> - If you are just bumping a patch on the current branch (e.g., 3.6.9 to 3.6.10), use:
> `npm version patch --no-git-tag-version`
> **🔴 BRANCH-VERSION PARITY GATE** — auto-checked before any work:
> **⚠️ ATOMIC COMMIT RULE — Version bump MUST happen before committing feature files.**
// turbo
```bash
BRANCH=$(git branch --show-current)
BRANCH_VER=${BRANCH#release/v}
PKG_VER=$(node -p "require('./package.json').version")
if [[ "$BRANCH" != release/v* ]]; then
echo "❌ Not on a release/v* branch (current: $BRANCH). Aborting."; exit 1
fi
# Allow first-bump scenario (branch declares a not-yet-bumped target)
echo "Branch target: $BRANCH_VER"
echo "package.json: $PKG_VER"
```
> **⚠️ ATOMIC COMMIT RULE** — bump and feature/fix code MUST land in the same commit so that `git show vX.Y.Z` always contains both.
>
> **CORRECT order:**
>
> 1. `npm version patch --no-git-tag-version` ← bump first
> 2. implement features / fix bugs
> 3. `git add -A && git commit -m "chore(release): v3.x.y — all changes in ONE commit"`
>
> **OR if features are already staged:**
>
> 1. implement features (do NOT commit yet)
> 2. `npm version patch --no-git-tag-version` ← bump before committing
> 3. `git add -A && git commit -m "chore(release): v3.x.y — all changes in ONE commit"`
>
> **NEVER do this (creates version mismatch in git history):**
>
> - ~~commit features → then bump version → commit package.json separately~~
>
> This ensures that `git show v3.x.y` always contains both code changes and the version bump together.
> The GitHub release tag will point to a commit that includes ALL changes for that version.
> **CORRECT order**: bump → (or already-staged changes) → single commit.
> **NEVER**: commit features first, then bump in a separate commit.
```bash
npm version patch --no-git-tag-version
```
### 3. Regenerate lock file (REQUIRED after version bump)
**Mandatory** — skipping causes `@swc/helpers` lock mismatch and CI failures:
```bash
npm install
```
### 4. Finalize CHANGELOG.md
Skipping this causes `@swc/helpers` lock mismatch and CI failures.
> **🔴 NO MIXUPS RULE**: Ensure you do NOT mix the backlog of the previous version with the new one. The new version section must ONLY contain the features and fixes for the current release.
### 4. Build CHANGELOG from EVERY commit since the last tag
Replace the `[Unreleased]` header with the new version and date.
Keep an empty `## [Unreleased]` section above it, separated by a horizontal rule (`---`).
> **🎯 Goal**: produce a complete CHANGELOG section following the format of PR #2617 — emoji-grouped sections, PR back-reference, and `— thanks @user` attribution. Nothing must slip through.
> **🔴 NO MIXUPS RULE**: do not mix backlog of the previous version. The new section must contain ONLY commits whose merge/landing happened after the previous tag.
#### 4a. Collect raw commit log since last tag
// turbo
```bash
LAST_TAG=$(git describe --tags --abbrev=0)
NEW_VERSION=$(node -p "require('./package.json').version")
TODAY=$(date -u +%F)
echo "Range: $LAST_TAG..HEAD → v$NEW_VERSION ($TODAY)"
# Full commit list (oneline)
git log --no-merges "$LAST_TAG..HEAD" --pretty=format:'%h %s' > /tmp/release_commits.txt
wc -l /tmp/release_commits.txt
# Merge commits (preserve PR numbers + authors)
git log --merges "$LAST_TAG..HEAD" --pretty=format:'%h %s%n author=%an <%ae>' > /tmp/release_merges.txt
# Per-commit detailed list (PR refs, co-authors, body)
git log "$LAST_TAG..HEAD" --pretty=format:'---%n%h | %s%n author=%an <%ae>%n body=%b' > /tmp/release_detailed.txt
```
#### 4b. Enrich with PR metadata + co-authors
For each commit referencing a PR (e.g. `(#2617)` or merge commit `Merge pull request #N`), fetch the PR author and any additional contributors so the entry follows the model below.
// turbo
```bash
# Extract all PR numbers referenced in the range
grep -oE '#[0-9]+' /tmp/release_commits.txt | sort -u > /tmp/release_prs.txt
echo "PRs in range:"; cat /tmp/release_prs.txt
# Fetch author + co-author info for every PR
> /tmp/release_pr_meta.json
while read -r PR; do
N=${PR#\#}
gh pr view "$N" --repo diegosouzapw/OmniRoute \
--json number,title,author,mergeCommit,body \
>> /tmp/release_pr_meta.json 2>/dev/null || echo "(skip $PR — not found)"
echo "" >> /tmp/release_pr_meta.json
done < /tmp/release_prs.txt
```
#### 4c. Assemble the new CHANGELOG section
Using `/tmp/release_commits.txt` + `/tmp/release_pr_meta.json` + `/tmp/release_detailed.txt`, build a new entry that:
1. **Covers every commit** — read the full list and group by Conventional Commit type. A commit is "covered" iff it appears (or is intentionally rolled-up) in the new section.
2. **Groups using these section headers (model from PR #2617)**:
- `### ✨ New Features` — `feat(*)`
- `### 🔧 Bug Fixes` — `fix(*)`
- `### 📝 Maintenance` — `chore(*)`, `refactor(*)`, `docs(*)`, `test(*)`, `ci(*)`, `build(*)`
- `### 🔒 Security` — security-flagged commits (only if any)
3. **Entry format**:
```
- **type(scope):** human-friendly description — extra context if useful. ([#PR](https://github.com/diegosouzapw/OmniRoute/pull/PR) — thanks @author / @coauthor1 / @coauthor2)
```
- When **no PR** is referenced (direct commit on release branch): `(thanks @author)`.
- When the PR closed an external contributor's PR via cherry-pick or re-implementation, attribute BOTH the original author AND the implementer: `thanks @originalAuthor / @diegosouzapw`.
- **Co-authors** must be extracted from the merge commit body (`Co-Authored-By:` lines that pre-date Hard Rule #16) and from PR participants who supplied commits.
4. **Coverage check** — after drafting, diff the section against `/tmp/release_commits.txt`. Any unlisted commit must either be explicitly added or consolidated under a roll-up bullet (e.g. "various lint and test alignments"). Do NOT silently drop commits.
Place the new section in `CHANGELOG.md` right below `## [Unreleased]`, separated by `---`:
```markdown
## [Unreleased]
---
## [3.7.0] — 2026-04-19
## [3.9.0] — 2026-05-27
### ✨ New Features
- **feat(scope):** description ([#1234](https://github.com/diegosouzapw/OmniRoute/pull/1234) — thanks @author)
- ...
### 🐛 Bug Fixes
### 🔧 Bug Fixes
- **fix(scope):** description ([#1235](https://github.com/diegosouzapw/OmniRoute/pull/1235) — thanks @author / @diegosouzapw)
- ...
### 📝 Maintenance
- **chore(scope):** description (thanks @diegosouzapw)
- ...
---
## [3.6.9] — 2026-04-19
## [3.8.999] — 2026-05-20
```
### 5. Update openapi.yaml version ⚠️ MANDATORY
#### 4d. Coverage assertion
// turbo
```bash
NEW_VERSION=$(node -p "require('./package.json').version")
# Count commits in range
COMMITS=$(wc -l < /tmp/release_commits.txt)
# Count bullets under the new section
BULLETS=$(awk "/^## \\[$NEW_VERSION\\]/{flag=1;next} /^## \\[/{flag=0} flag" CHANGELOG.md | grep -c '^- ')
echo "Commits in range: $COMMITS"
echo "Changelog bullets: $BULLETS"
if [ "$BULLETS" -lt $(( COMMITS / 3 )) ]; then
echo "⚠️ Bullet count looks low (< commits/3). Re-review /tmp/release_commits.txt for missed entries."
fi
```
> If a commit cannot be matched to a bullet, EITHER add it or explicitly justify the omission in this session before continuing.
### 5. Sync versioned files ⚠️ MANDATORY
> **CI will fail** if `docs/reference/openapi.yaml` version ≠ `package.json` version (`check:docs-sync` enforces this).
@@ -139,40 +243,52 @@ for dir in electron open-sse; do
echo "✓ $dir/package.json → $VERSION"
fi
done
# Re-run install to assert the workspace lockfile is updated
# Re-run install so workspace lockfile picks up the bumps
npm install
```
### 6. Update README.md and i18n docs
### 6. Sync README.md and i18n docs
Manually perform these documentation updates (there is no `/update-docs` slash command — it was deprecated in v3.8):
There is **no `/update-docs` slash command** (deprecated in v3.8). Updates must happen manually OR via parallel subagents.
- Update feature table rows and "What's new in vX.Y.Z" section in `README.md`
- Sync feature changes to all 40 language `docs/i18n/*/README.md` files (use the same row edits across each translated README)
- Update the relevant `docs/<AREA>.md` if architecture or counts changed (e.g. `docs/frameworks/MCP-SERVER.md` when MCP tools change)
- Re-run `npm run check:docs-sync` and `npm run check:docs-all` to catch drift
**Recommended automation** — dispatch parallel agents to apply the same diff across the 40 translations (see `superpowers:dispatching-parallel-agents`):
### 7. Run tests
1. Apply the substantive change to `README.md` first (feature table row + "What's new in vX.Y.Z" section).
2. Capture the diff: `git diff README.md > /tmp/readme.patch`.
3. Dispatch 5-10 parallel agents, each handling a slice of the 40 `docs/i18n/*/README.md`, translating the diff into the target language.
4. Update `docs/<AREA>.md` if architecture/counts changed (e.g. `docs/frameworks/MCP-SERVER.md` when MCP tools change).
5. Validate: `npm run check:docs-sync && npm run check:docs-all`.
### 7. Full quality gate (MANDATORY — replaces the old `npm test`)
> **Precedent**: the v3.8.2 cycle landed with 49 broken tests because only `npm test` was running. Lint + typecheck + cycles caught zero of those regressions.
// turbo
```bash
set -e
npm run lint
npm run typecheck:core
npm run check:cycles
npm run check:docs-all
npm test
```
All tests must pass before creating the PR.
All five must pass before opening the PR. If any fail, fix and re-run.
### 8. Stage, commit, and push
### 8. Stage, commit, and push (atomic — bump + features + changelog + i18n in ONE commit)
// turbo-all
// turbo
```bash
VERSION=$(node -p "require('./package.json').version")
git add -A
git commit -m "chore(release): v3.x.y — summary of changes"
git push origin release/v3.x.y
git commit -m "chore(release): v$VERSION — $(date -u +%F)"
git push origin "release/v$VERSION"
```
### 9. Open PR to main
> **NEVER** include `Co-Authored-By:` trailers in the release commit (Hard Rule #16). Co-author attribution lives inside the CHANGELOG entries.
### 9. Open PR to main
@@ -181,34 +297,49 @@ git push origin release/v3.x.y
```bash
VERSION=$(node -p "require('./package.json').version")
# Extract the exact changelog entry for this version from the root CHANGELOG.md
# Extract the exact changelog entry for this version
awk "/^## \\[$VERSION\\]/{flag=1; print; next} /^---/{if(flag) {flag=0; exit}} flag" CHANGELOG.md > /tmp/changelog_body.txt
# Append test status and next steps
echo "" >> /tmp/changelog_body.txt
echo "### Tests" >> /tmp/changelog_body.txt
echo "- All tests pass" >> /tmp/changelog_body.txt
echo "" >> /tmp/changelog_body.txt
echo "### ⚠️ After merging: run Phase 2 steps to tag, publish, and deploy." >> /tmp/changelog_body.txt
# Append PR-only metadata (test status + reviewer instructions)
{
echo ""
echo "---"
echo ""
echo "### Quality Gate"
echo "- lint: pass"
echo "- typecheck:core: pass"
echo "- check:cycles: pass"
echo "- check:docs-all: pass"
echo "- tests: pass"
echo ""
echo "### Coverage of commits since previous tag"
LAST_TAG=$(git describe --tags --abbrev=0 HEAD~1 2>/dev/null || echo "(no previous tag)")
COMMITS=$(git rev-list --no-merges "$LAST_TAG..HEAD" | wc -l)
echo "- Range: \`$LAST_TAG..HEAD\`"
echo "- Commits inspected: $COMMITS"
echo ""
echo "### ⚠️ After merging: run Phase 2 (Local VPS homologation) before tagging."
} >> /tmp/changelog_body.txt
gh pr create \
--repo diegosouzapw/OmniRoute \
--base main \
--head release/v$VERSION \
--head "release/v$VERSION" \
--title "Release v$VERSION" \
--body-file /tmp/changelog_body.txt
```
### 10. 🛑 STOP — Notify User & Await PR Confirmation
### 10. 🛑 STOP — Notify user & await PR confirmation
**This is a mandatory stop point.** Present the report in the final response and stop. Do not continue to the next phase until the user explicitly approves.
Present in the final response and stop. Do not continue to Phase 2 until the user explicitly approves.
Inform the user:
Provide:
- PR URL
- Summary of changes
- Test results
- List of files changed
- Summary of changes (top 5 from CHANGELOG)
- Quality gate results
- List of files changed (`git diff --stat $LAST_TAG..HEAD`)
- Coverage count vs commits-in-range
**DO NOT proceed to Phase 2 until the user confirms the PR looks good and merges it.**
@@ -216,41 +347,37 @@ Inform the user:
## Phase 2: Post-Merge Validation (Local VPS)
> Run these steps only AFTER the user has merged the PR into `main` and all CI jobs have passed.
> Run only AFTER the user has merged the PR into `main` and all CI jobs pass.
### 11. Deploy to Local VPS for Final Validation (MANDATORY)
### 11. Deploy `main` to the Local VPS
Before cutting the official git tag and publishing to the world, deploy the `main` branch to the Local VPS for a final homologation test.
Delegate to the `deploy-vps-local-cc` skill (single source of truth for the deploy procedure — do NOT duplicate the SCP/SSH commands here):
```bash
git checkout main
git pull origin main
# Build and pack locally
cd /home/diegosouzapw/dev/proxys/OmniRoute && rm -f omniroute-*.tgz && rm -rf .next/cache app/.next/cache && npm run build:cli && rm -rf app/logs app/coverage app/.git app/.app-build-backup* && npm pack --ignore-scripts
# Deploy to LOCAL VPS (192.168.0.15)
scp omniroute-*.tgz root@192.168.0.15:/tmp/
ssh root@192.168.0.15 "npm install -g /tmp/omniroute-*.tgz --ignore-scripts && cd /usr/lib/node_modules/omniroute/app && npm rebuild better-sqlite3 && pm2 delete omniroute 2>/dev/null; pm2 start /root/.omniroute/ecosystem.config.cjs --update-env && pm2 save && echo '✅ Local done'"
# Verify
curl -s -o /dev/null -w "LOCAL: HTTP %{http_code}\n" http://192.168.0.15:20128/
```
/deploy-vps-local-cc
```
### 12. 🛑 STOP — Notify User & Await Final OK
The skill handles: checkout `main`, `npm pack`, scp to `192.168.0.15`, install, pm2 restart, and HTTP probe.
**This is a mandatory stop point.**
Inform the user that the `main` branch is now running on the Local VPS.
Wait for the user to manually test and give the **OK**.
**DO NOT proceed to Phase 3 until the user confirms the local deploy is stable.**
### 12. 🛑 STOP — Notify user & await final OK
Inform the user that `main` is running on `192.168.0.15:20128`. Provide a smoke-test checklist:
- [ ] `GET /` returns 200
- [ ] Dashboard login works (`/dashboard`)
- [ ] `/v1/chat/completions` with default provider returns a stream
- [ ] No critical errors in `pm2 logs omniroute --lines 100`
- [ ] Any release-specific UI features are reachable
Wait for user **OK** before Phase 3.
---
## Phase 3: Official Launch
> Run these steps only AFTER the user gives the final OK from the Phase 2 local validation.
> Run only AFTER the user gives the final OK from Phase 2.
### 13. Create Git Tag and GitHub Release (MANDATORY)
### 13. Create git tag and GitHub Release
// turbo
@@ -259,98 +386,118 @@ git checkout main
git pull origin main
VERSION=$(node -p "require('./package.json').version")
# Extracts the changelog section for this version
# Extract release notes section from CHANGELOG
NOTES=$(awk "/^## \\[$VERSION\\]/{flag=1; next} /^---/{if(flag) {flag=0; exit}} flag" CHANGELOG.md | sed -e 's/^[[:space:]]*//' -e 's/[[:space:]]*$//')
if [ -z "$NOTES" ]; then NOTES="OmniRoute v$VERSION Release"; fi
[ -z "$NOTES" ] && NOTES="OmniRoute v$VERSION Release"
git tag -a "v$VERSION" -m "Release v$VERSION"
git push origin "v$VERSION"
gh release create "v$VERSION" --repo diegosouzapw/OmniRoute --title "v$VERSION" --notes "$NOTES" --target main || gh release edit "v$VERSION" --repo diegosouzapw/OmniRoute --title "v$VERSION" --notes "$NOTES"
gh release create "v$VERSION" \
--repo diegosouzapw/OmniRoute \
--title "v$VERSION" \
--notes "$NOTES" \
--target main \
|| gh release edit "v$VERSION" \
--repo diegosouzapw/OmniRoute \
--title "v$VERSION" \
--notes "$NOTES"
```
### 14. 🐳 Trigger Docker Hub build (MANDATORY — keep npm and Docker in sync)
### 14. 🐳 Trigger / verify Docker Hub build
> **CRITICAL**: Docker Hub and npm MUST always publish the same version.
> The Docker image is built automatically via GitHub Actions when a new tag is pushed.
> After pushing the tag in step 13, **verify the workflow runs**:
> **CRITICAL**: Docker Hub and npm MUST publish the same version.
```bash
# Verify the Docker workflow triggered
VERSION=$(node -p "require('./package.json').version")
gh run list --repo diegosouzapw/OmniRoute --workflow docker-publish.yml --limit 3
# Wait for the Docker build to complete (usually 5–10 min)
gh run watch --repo diegosouzapw/OmniRoute
```
### 15. Publish to NPM (Optional/Automated)
### 15. Publish to npm (usually CI)
Normally handled by CI, but if manual publish is required:
`prepublishOnly` runs `npm run build:cli`. Manual fallback:
```bash
npm publish
npm info omniroute version # verify
```
### 16. Deploy to AKAMAI VPS (Production)
### 16. Deploy to Akamai VPS (Production)
Now that the release is officially cut, deploy it to the Akamai VPS.
Delegate to the `deploy-vps-akamai-cc` skill:
```
/deploy-vps-akamai-cc
```
The skill handles: build, pack, scp to `69.164.221.35`, install, pm2 restart, HTTP probe.
### 17. Rollback playbook (use only if Phase 3 fails after tag push)
If a fatal regression surfaces after the tag is pushed:
```bash
# Deploy to AKAMAI VPS (69.164.221.35)
scp omniroute-*.tgz root@69.164.221.35:/tmp/
ssh root@69.164.221.35 "npm install -g /tmp/omniroute-*.tgz --ignore-scripts && cd /usr/lib/node_modules/omniroute/app && npm rebuild better-sqlite3 && pm2 delete omniroute 2>/dev/null; pm2 start /root/.omniroute/ecosystem.config.cjs --update-env && pm2 save && echo '✅ Akamai done'"
VERSION=$(node -p "require('./package.json').version")
PREV=$(git describe --tags --abbrev=0 "v$VERSION^")
# Verify
curl -s -o /dev/null -w "AKAMAI: HTTP %{http_code}\n" http://69.164.221.35:20128/
# 1. Mark GitHub release as pre-release (do not delete history)
gh release edit "v$VERSION" --repo diegosouzapw/OmniRoute --prerelease
# 2. Re-deploy previous version to Akamai
git checkout "$PREV" && /deploy-vps-akamai-cc
# 3. Deprecate the broken npm version
npm deprecate "omniroute@$VERSION" "broken release — use $PREV"
# 4. Open follow-up issue and start a new patch cycle from main
```
---
## Phase 4: Release Monitoring & Artifact Validation
> After triggering the official release, actively monitor the CI pipelines until all artifacts are successfully generated. If any pipeline fails, stop and apply the necessary corrections before continuing.
> Actively monitor the CI pipelines until all artifacts succeed. If any fail, stop and fix before continuing.
### 18. Monitor CI Pipelines
### 18. Monitor CI pipelines
Wait for and verify the successful completion of the following automated jobs:
Verify successful completion of:
1. **Docker Hub Publish**
2. **Electron Build**
3. **NPM Registry Publish** (Check with `npm info omniroute version`)
3. **npm Registry Publish**
```bash
# Monitor Docker Hub workflow
gh run list --repo diegosouzapw/OmniRoute --workflow docker-publish.yml --limit 1
gh run watch <RUN_ID>
# Monitor Electron build
gh run list --repo diegosouzapw/OmniRoute --workflow electron-release.yml --limit 1
gh run watch <RUN_ID>
# Verify NPM version
npm info omniroute version
```
### 19. Handle Failures (If Any)
### 19. Handle failures
If a workflow fails:
- Use `gh run view <RUN_ID> --log-failed` to identify the error.
- Apply the fix on the `main` branch.
- If necessary, re-trigger the workflow using `gh workflow run <workflow_name.yml> --repo diegosouzapw/OmniRoute --ref v3.x.y`
```bash
gh run view <RUN_ID> --log-failed
# Fix on main, then re-trigger:
VERSION=$(node -p "require('./package.json').version")
gh workflow run <workflow.yml> --repo diegosouzapw/OmniRoute --ref "v$VERSION"
```
### 20. Preserve release branch
```bash
# Branch is kept for historical purposes. Do not delete.
```
Branch is kept for historical purposes. Do not delete.
---
## Notes
- Ensure CHANGELOG, README and `docs/*` are current BEFORE this workflow — run `npm run check:docs-all` and `/version-bump` first (there is no `/update-docs` slash command anymore)
- The `prepublishOnly` script runs `npm run build:cli` automatically during `npm publish`
- After npm publish, verify with `npm info omniroute version`
- Lock file sync errors are caused by skipping `npm install` after version bump
- Use `gh auth switch -u diegosouzapw` if git push fails with wrong account
- Ensure CHANGELOG, README and `docs/*` are current BEFORE this workflow — run `npm run check:docs-all` first.
- The `prepublishOnly` script runs `npm run build:cli` automatically during `npm publish`.
- After npm publish, verify with `npm info omniroute version`.
- Lock file sync errors are caused by skipping `npm install` after version bump.
- Use `gh auth switch -u diegosouzapw` if `git push` fails with the wrong account.
- Deploy procedures live in dedicated skills (`deploy-vps-local-cc`, `deploy-vps-akamai-cc`, `deploy-vps-both-cc`) — never inline the SCP/SSH commands here, to avoid drift.
## Known CI Pitfalls
@@ -360,3 +507,4 @@ If a workflow fails:
| `[docs-sync] FAIL - CHANGELOG.md first section must be "## [Unreleased]"` | `## [Unreleased]` missing or not at top of CHANGELOG | Add `## [Unreleased]\n\n---\n` before the first versioned `## [x.y.z]` |
| Electron Linux `.deb` build fails (`FpmTarget` error) | `fpm` Ruby gem not installed on `ubuntu-latest` runner | Already fixed in `electron-release.yml` (`gem install fpm` step) |
| Docker Hub `502 error writing layer blob` | Transient Docker Hub network error during ARM64 push | Re-run the Docker publish workflow; no code change needed |
| Coverage gate fails (statements/lines < 75% or branches < 70%) | Production code changed without tests | Add tests, re-run `npm run test:coverage` (see CLAUDE.md hard rule #9) |

190
.claude/commands/implement-features-cc.md
View File

@@ -12,17 +12,21 @@ A **5-phase** workflow that systematically harvests feature requests from GitHub
```
_ideia/
├── viable/ # Features approved for implementation
│ ├── need_details/ # ❓ Good idea but waiting for author clarification (issues stay OPEN)
│ │ └── 1015-warp-terminal-mitm.md
│ ├── 1046-native-playground.md # ✅ Ready — researched and planned
├── viable/ # ✅ Approved, awaiting implementation
│ ├── 1046-native-playground.md
│ └── 1046-native-playground.requirements.md
├── implemented/ # 🚧 Implemented but PR not yet merged to main (transient)
├── implemented/ # ✅ Implemented but release PR not yet merged to main (transient)
│ └── 1046-native-playground.md
├── defer/ # ⏭️ Good ideas deferred for future cycles (issues CLOSED after Phase 3 approval)
├── need_details/ # ❓ Issue OPEN — awaiting author clarification (permanent archive)
│ └── 1015-warp-terminal-mitm.md
├── defer/ # ⏭️ Issue CLOSED — good idea, deferred for future cycles (permanent)
│ └── 1041-smart-auto-combos.md
└── notfit/ # ❌ Out of scope / already exists (issues CLOSED after Phase 3 approval)
└── 945-telegram-integration.md
├── notfit/ # ❌ Issue CLOSED — out of scope (permanent)
│ └── 945-telegram-integration.md
├── exists/ # 🔁 Issue CLOSED — feature already shipped (permanent, kept separate from notfit)
│ └── 812-rate-limit-dashboard.md
└── in_flight/ # 🚧 Issue OPEN — third-party PR already addresses it (permanent until reclaim or merge)
└── 988-batch-export.md
_tasks/features-vX.Y.Z/ # Implementation plans (per-release)
└── 1046-native-playground.plan.md
@@ -31,8 +35,8 @@ _tasks/features-vX.Y.Z/ # Implementation plans (per-release)
> **LIFECYCLE RULE:**
> - `viable/` files are **MOVED** to `implemented/` once code lands on the release branch.
> - `implemented/` files are **DELETED** only after the release PR is merged to `main`.
> - This preserves recovery context if implementation fails partially (build green but i18n missing, etc).
> - Files in `defer/` and `notfit/` remain as permanent reference.
> - All other buckets — `need_details/`, `defer/`, `notfit/`, `exists/`, `in_flight/` — are **permanent archives**. Even when the upstream issue is CLOSED, the local file stays. Future cycles can revisit any of them (Phase 1.7 stale-reclaim turns `in_flight/` and `need_details/` back into VIABLE after 15 days of upstream inactivity).
> - This preserves recovery context if implementation fails partially AND lets us re-evaluate old decisions when the project matures.
> **BRANCH RULE**: All implementation work MUST happen on the current `release/vX.Y.Z` branch. Never create separate `feat/` branches. If no release branch exists yet, delegate creation to `/generate-release` (see Phase 1.2) — do NOT reimplement bump logic here.
@@ -188,7 +192,7 @@ For each issue number, check whether an open PR or branch already targets it:
```bash
# Open PRs that link the issue
gh pr list --repo <owner>/<repo> --state open --search "linked:#<NUMBER>" --json number,title,headRefName
gh pr list --repo <owner>/<repo> --state open --search "linked:#<NUMBER>" --json number,title,headRefName,updatedAt,author
# Local branches that mention the issue number
git branch -a | grep -E "(^|/)(feat|fix|refactor)/.*-?<NUMBER>(-|$)" || true
@@ -196,9 +200,73 @@ git branch -a | grep -E "(^|/)(feat|fix|refactor)/.*-?<NUMBER>(-|$)" || true
If a PR or branch already exists:
- Mark the idea file with `> ⚠️ In-flight: PR #<PR_NUMBER> / branch <name>` near the top.
- Mark the idea file with `> ⚠️ In-flight: PR #<PR_NUMBER> by @<author> / branch <name> (last activity <date>)` near the top.
- **Skip Phase 2 research and Phase 4 planning** for this feature — the implementation is already in motion.
- In the Phase 3 report, list it under a separate "🚧 Already in progress" bucket; do NOT count it as VIABLE for implementation.
- The idea file will be moved to `_ideia/in_flight/` in Phase 2.5.2 (it stays there permanently, but Phase 1.7 may reclaim it later).
### 1.7 Stale Reclaim (15-day rule)
Some issues sit in `in_flight/` or `need_details/` forever — third-party PRs go cold, authors disappear, the world moves on. This phase reclaims them when they go quiet.
**Trigger conditions** (run for each issue currently in `_ideia/in_flight/` or `_ideia/need_details/`):
```bash
# For IN FLIGHT — last activity on the linked PR (commit OR comment)
gh pr view <PR_NUMBER> --repo <owner>/<repo> --json updatedAt,commits,comments \
--jq '[.updatedAt, (.commits[-1].committedDate // ""), (.comments[-1].createdAt // "")] | max'
# For NEEDS DETAIL — last activity from the issue author (any comment by them)
gh issue view <NUMBER> --repo <owner>/<repo> --json comments,author \
--jq '.author.login as $a | [.comments[] | select(.author.login == $a) | .createdAt] | max // (.createdAt)'
```
Compute the gap in days between the timestamp above and today.
**Reclaim rule:**
| Bucket | Trigger | Action |
| --------------- | ------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------- |
| 🚧 IN FLIGHT | ≥15 days since last PR activity (commit OR comment by PR author) | Post **intent-to-take-over comment** (template below), wait **48h**, then reclaim if no response |
| ❓ NEEDS DETAIL | ≥15 days since last comment by the issue author | Post **gentle nudge** (template below), wait **48h**, then reclaim as VIABLE if no response |
**Intent-to-take-over comment (🚧 IN FLIGHT path)** — translate to `reply_lang`:
```markdown
Hi @<pr_author> and @<issue_author>! 👋
This PR (#<PR>) addressing issue #<NUMBER> hasn't had updates in <N> days. We'd love to ship this feature in our next release.
**Plan:** if there are no updates in the next **48 hours**, our team will take over the work and merge it as part of `release/vX.Y.Z`. The original PR will be referenced and authorship preserved in the commit trailer.
If you're still working on it, just drop a comment here and we'll hold off. Thanks for the contribution either way! 🙏
```
**Gentle nudge (❓ NEEDS DETAIL path)** — translate to `reply_lang`:
```markdown
Hi @<author>! 👋
It's been <N> days since we asked for more details on this feature request. We'd still love to move forward.
**Plan:** if we don't hear back in the next **48 hours**, we'll proceed with our best interpretation of the original request and add it to our backlog for implementation. We'll tag you on the implementation PR so you can review before it ships.
If you still want to provide the details, just reply here — we'll wait. 🙏
```
**Reclaim execution** (only after the 48h grace period, with no new author/PR-author activity):
1. Move the idea file to `_ideia/viable/` (preserve any prior content + add a `> ♻️ Reclaimed on <date> after 15-day inactivity` banner near the top).
2. If it was IN FLIGHT and a research file does not yet exist, run Phase 2 (Research) for it now.
3. Otherwise create the requirements file based on the existing content + a quick research pass.
4. Add a `viable_origin: stale_reclaim` line to the front-matter so the Phase 3 report can flag it.
5. In Phase 5 (commit / PR), include a commit trailer crediting the original PR author if applicable:
```
Originally-proposed-by: @<pr_author> in #<original_pr_number>
```
(This is NOT `Co-Authored-By` — hard rule #16 still applies. It is a free-form trailer that preserves credit without GitHub re-attributing the commit.)
> **Why 15 days + 48h grace?** Long enough that the original contributor has truly moved on; short enough that the feature still ships in the same release cycle. Grace period is documented in `feedback_issue_triage_independence` so we don't default to "trust prior triage" — we verify the silence is real.
---
@@ -356,12 +424,16 @@ For each researched feature, create a requirements file alongside its idea file:
```bash
mkdir -p <project_root>/_ideia/viable
mkdir -p <project_root>/_ideia/viable/need_details
mkdir -p <project_root>/_ideia/implemented
mkdir -p <project_root>/_ideia/need_details
mkdir -p <project_root>/_ideia/defer
mkdir -p <project_root>/_ideia/notfit
mkdir -p <project_root>/_ideia/exists
mkdir -p <project_root>/_ideia/in_flight
```
> **Permanent archives**: `need_details/`, `defer/`, `notfit/`, `exists/`, `in_flight/`. Even after the upstream issue is closed, the local file stays — future cycles may revisit.
### 2.5.2 Move Idea Files to Category Subdirectories
After classification, move EVERY idea file to its correct subdirectory (still local-only — no GitHub side-effects):
@@ -371,19 +443,23 @@ After classification, move EVERY idea file to its correct subdirectory (still lo
mv _ideia/<NUMBER>-*.md _ideia/viable/
mv _ideia/<NUMBER>-*.requirements.md _ideia/viable/
# ❓ NEEDS DETAIL — viable but waiting for author response
mv _ideia/<NUMBER>-*.md _ideia/viable/need_details/
# ❓ NEEDS DETAIL — viable but waiting for author response (issue stays OPEN)
mv _ideia/<NUMBER>-*.md _ideia/need_details/
# ⏭️ DEFER — move idea files only
# ⏭️ DEFER — issue will be CLOSED but file is kept permanently for future re-evaluation
mv _ideia/<NUMBER>-*.md _ideia/defer/
# ❌ NOT FIT & 🔁 ALREADY EXISTS — move idea files only
# ❌ NOT FIT — issue will be CLOSED but file is kept permanently
mv _ideia/<NUMBER>-*.md _ideia/notfit/
# 🚧 IN FLIGHT — leave in _ideia/ root with a top-of-file banner; do NOT touch the PR/branch
# 🔁 ALREADY EXISTS — issue will be CLOSED but file is kept permanently (separate bucket from NOT FIT)
mv _ideia/<NUMBER>-*.md _ideia/exists/
# 🚧 IN FLIGHT — issue stays OPEN, third-party PR is handling it; file kept permanently for Phase 1.7 stale-reclaim
mv _ideia/<NUMBER>-*.md _ideia/in_flight/
```
No idea files should remain in `_ideia/` root after this step except `🚧 IN FLIGHT` entries.
No idea files should remain in `_ideia/` root after this step.
---
@@ -397,14 +473,15 @@ Present a structured report containing:
#### 3.1a — Feature Summary Table
| # | Issue | Title | Verdict | Local Location | Planned GitHub Action |
| --- | ----- | ----- | --------------- | ----------------------------- | -------------------------------- |
| 1 | #N | Title | ✅ VIABLE | `_ideia/viable/` | Comment + keep OPEN |
| 2 | #N | Title | ⏭️ DEFER | `_ideia/defer/` | Comment + CLOSE |
| 3 | #N | Title | ❌ NOT FIT | `_ideia/notfit/` | Comment + CLOSE |
| 4 | #N | Title | 🔁 EXISTS | `_ideia/notfit/` | Comment with location + CLOSE |
| 5 | #N | Title | ❓ NEEDS DETAIL | `_ideia/viable/need_details/` | Comment with questions + OPEN |
| 6 | #N | Title | 🚧 IN FLIGHT | `_ideia/` (banner) | None — PR #M already handles it |
| # | Issue | Title | Verdict | Local Location | Planned GitHub Action |
| --- | ----- | ----- | ----------------- | ----------------------- | -------------------------------------- |
| 1 | #N | Title | ✅ VIABLE | `_ideia/viable/` | Comment + keep OPEN |
| 2 | #N | Title | ⏭️ DEFER | `_ideia/defer/` | Comment + CLOSE |
| 3 | #N | Title | ❌ NOT FIT | `_ideia/notfit/` | Comment + CLOSE |
| 4 | #N | Title | 🔁 EXISTS | `_ideia/exists/` | Comment with location + CLOSE |
| 5 | #N | Title | ❓ NEEDS DETAIL | `_ideia/need_details/` | Comment with questions + keep OPEN |
| 6 | #N | Title | 🚧 IN FLIGHT | `_ideia/in_flight/` | None — PR #M handles it |
| 7 | #N | Title | ♻️ RECLAIMED | `_ideia/viable/` | Intent comment posted in Phase 1.7 |
#### 3.1b — Viable Features Detail
@@ -499,20 +576,22 @@ gh issue close <NUMBER> --repo <owner>/<repo> --comment "<translated comment>"
---
#### For ❌ NOT FIT — Comment + CLOSE issue
#### For ❌ NOT FIT — Comment + CLOSE issue (soft-archive)
Politely explain why the feature doesn't fit the project scope.
Politely explain the current limitation, but make clear the idea is **archived, not discarded**. If the situation changes (provider opens a public API, scope shifts, etc.), we revisit and tag the author.
```markdown
Hi @<author>! Thanks for the suggestion! 🙏
After careful analysis, we've determined that this feature **falls outside OmniRoute's core scope** as a proxy/router.
After researching, we've determined this feature isn't viable right now:
**Reason:** <explain why — e.g., "Telegram integration belongs in the application/orchestrator layer that consumes OmniRoute's API, not inside the router itself.">
**Reason:** <explain why — e.g., "CodeBuddy has no public API; YepApi is fronted by Cloudflare bot detection that we won't evade.">
**Alternative:** <suggest an alternative approach if possible>
**Alternative:** <suggest an alternative if one exists, otherwise omit this line>
We appreciate you thinking of ways to improve OmniRoute! If you'd like to discuss this further, feel free to open a Discussion. 🙏
That said, **we've saved your suggestion** to our internal archive rather than discarding it. If circumstances change (a public API is released, the provider opens up, our scope shifts, etc.), we'll revisit it and tag you here.
Closing for now, but the idea isn't lost — we'll let you know if things change. 🙏
```
```bash
@@ -541,23 +620,33 @@ Looking forward to your response! 🚀
---
#### For ✅ VIABLE — Comment (keep OPEN)
#### For ✅ VIABLE — Comment + CLOSE issue (cataloged for future implementation)
Thank the user, confirm we've cataloged their idea, and explain that progress is tracked in releases.
When we **know how to implement** the feature, we accept + catalog + close the issue right away (to keep the open-issue list focused on items still awaiting input). A separate post-implementation comment will reopen the conversation later when code ships. Include a 1-2 sentence summary of what we plan to build so the author knows we understood the request.
```markdown
Hi @<author>! Thanks for the great feature suggestion! 🙏
We've analyzed your request and it aligns well with OmniRoute's roadmap. We've **cataloged this feature** and it's in our implementation backlog.
We've analyzed your request — it aligns with OmniRoute's roadmap and we have a clear implementation path:
**Status:** 📋 Cataloged for future implementation
> <one to two sentence summary of what we plan to build>
This issue will be **closed automatically by the merge commit** when the feature ships. To follow along, you can subscribe to repository releases or watch this issue.
We've **cataloged it internally** and it will be picked up in an upcoming release.
**Status:** ✅ Accepted — cataloged for future implementation
We'll respond here and tag you once the implementation lands so you can test it before it ships.
Closing for now to keep our open-issue list focused on items still awaiting input. The feature is tracked in our internal backlog and won't be forgotten.
Thank you for helping improve OmniRoute! 🚀
```
**⚠️ Do NOT close viable issues — they remain OPEN until the implementation PR closes them via commit message.**
```bash
gh issue close <NUMBER> --repo <owner>/<repo> --comment "<translated comment>"
```
**⚠️ Important**: The VIABLE comment **CLOSES** the issue. When implementation ships later, Phase 5.4 will REOPEN the issue, post the implementation comment, and CLOSE it again. The author still gets the @-mention notification.
---
@@ -791,22 +880,23 @@ rm _ideia/implemented/<NUMBER>-*.md
Present a final summary report to the user:
| Issue | Title | Verdict | Action | Commit |
| ----- | ----- | --------------- | -------------------------------------------------- | --------- |
| #N | Title | ✅ Implemented | Issue closed, idea file in `_ideia/implemented/` | `abc1234` |
| #N | Title | ⏭️ Deferred | Issue closed + saved in `_ideia/defer/` | — |
| #N | Title | ❌ Not Fit | Issue closed + saved in `_ideia/notfit/` | — |
| #N | Title | 🔁 Exists | Issue closed + saved in `_ideia/notfit/` | — |
| #N | Title | ❓ Needs Detail | Issue OPEN, moved to `_ideia/viable/need_details/` | — |
| #N | Title | 🚧 In Flight | Untouched — tracked by PR #M | — |
| Issue | Title | Verdict | Action | Commit |
| ----- | ----- | ---------------- | --------------------------------------------------------------- | --------- |
| #N | Title | ✅ Implemented | Issue closed, idea file in `_ideia/implemented/` (until merge) | `abc1234` |
| #N | Title | ♻️ Reclaimed | Was IN FLIGHT / NEEDS DETAIL, reclaimed after 15d → implemented | `abc1234` |
| #N | Title | ⏭️ Deferred | Issue closed + permanent archive in `_ideia/defer/` | — |
| #N | Title | ❌ Not Fit | Issue closed + permanent archive in `_ideia/notfit/` | — |
| #N | Title | 🔁 Exists | Issue closed + permanent archive in `_ideia/exists/` | — |
| #N | Title | ❓ Needs Detail | Issue OPEN, archive in `_ideia/need_details/` | — |
| #N | Title | 🚧 In Flight | Issue OPEN, archive in `_ideia/in_flight/`, tracked by PR #M | — |
Include:
- Total features harvested
- Total ideas cataloged (`viable/need_details/` + `defer/` + `notfit/`)
- Total ideas archived per bucket (`need_details/` / `defer/` / `notfit/` / `exists/` / `in_flight/`)
- Total features implemented (idea files in `_ideia/implemented/`, awaiting post-merge cleanup)
- Total features deferred
- Total reclaimed via Phase 1.7 (stale 15-day rule)
- Total issues closed
- Total issues left open (NEEDS DETAIL + VIABLE-pending-implementation + IN FLIGHT)
- Total issues left open (NEEDS DETAIL + VIABLE-pending + IN FLIGHT)
- Audit results: lint / typecheck / cycles / build / coverage (pass-count per phase)
- Languages used in posted comments (e.g. "3× pt-BR, 5× en, 1× es")

2
.claude/commands/review-discussions-cc.md
View File

@@ -41,7 +41,7 @@ For each discussion, extract:
- **Category** (Announcements, General, Ideas, Q&A, Show and tell)
- **Created** + **Last updated** (ISO date)
- **Summary** of original post (1-2 sentences)
- **Comment count** + **last commenter** + **last comment date**
- **Comment count** + **last commenter** + **last comment date** — determine these by **chronological `createdAt`**, not iteration order. Comments and their nested replies must be merged into a single sorted timeline before picking the latest event (otherwise a recent top-level reply gets shadowed by an older nested reply of an earlier comment, and the discussion is misclassified).
- **Maintainer involvement**: whether the repo owner already replied, and how many times
- **Pending action** — derived state, see categories below
- **Attachments**: count of screenshots / videos / pastebin links