Merge branch 'feature/common'

Author: eigenverft

.agents/skills/repo-diff-commit-planner/SKILL.md

@@ -7,7 +7,7 @@ description: Analyze repository differences, group related changes into logical
 
 ## Overview
 
-Use this skill to inspect current repository differences, decide what is ready to commit, split the work into logical commit groups, and then execute the git staging and commit steps for all commit-ready groups. It focuses on clean grouping, safe execution, and a buildable commit sequence.
+Use this skill to inspect current repository differences, decide how to group them, and then execute the git staging and commit steps so tracked worktree changes are fully resolved by default. It first checks whether the local branch should be synced from its remote upstream, then proceeds with clean grouping, safe execution, and a buildable commit sequence with no leftover tracked modifications unless the user explicitly says not to commit something or a real blocker prevents normal staging. Ignored local-only files are not candidates for normal commits.
 
 ## When To Use
 
@@ -24,24 +24,40 @@ Use this skill to inspect current repository differences, decide what is ready t
 ## Inputs Needed
 
 - Current branch and repository context.
+- Upstream tracking and remote status for the current branch when available.
 - `git status` and diff summaries for changed files.
 - Any known constraints, such as release urgency or risky files.
 - Build or test command when verification is expected.
 
 ## Workflow
 
+### 0. Upstream Sync Check
+
+- At the start, inspect the current branch, its upstream tracking branch, and whether a normal remote sync is possible.
+- If a remote and upstream are configured, fetch first so ahead/behind state is current.
+- If the upstream branch is ahead and the branch has not diverged, sync before planning by attempting a normal non-interactive fast-forward pull such as `git pull --ff-only`, even when the worktree is already dirty.
+- If that pull fails because local changes would be overwritten, files would conflict, or Git refuses the fast-forward update, stop and report the sync blocker instead of guessing a recovery strategy.
+- If the branch has diverged from upstream, stop and report it instead of choosing a merge or rebase strategy automatically.
+- If there is no upstream tracking branch or no reachable remote, continue with the local repository state and mention that assumption in the final report.
+
 ### 1. Inventory Repository Differences
 
 - List changed, untracked, deleted, and renamed files.
 - Summarize change scope by area (feature, bugfix, docs, config, tests, refactor).
 - Identify potentially sensitive or generated files that should not be committed.
+- Check whether any candidate file is ignored by `.gitignore`, `.git/info/exclude`, or a global excludes file before staging it.
 
 ### 2. Commit-Readiness Analysis
 
 - Mark each change as `commit-now`, `hold`, or `needs-review`.
 - Check dependency links between files to avoid broken intermediate commits.
 - Highlight risky changes needing explicit confirmation.
-- Aim to commit every `commit-now` group before finishing the task.
+- Default every discovered change to `commit-now`.
+- Use `hold` only when the user explicitly says a path or group must not be committed.
+- Use `needs-review` only for a true technical blocker that prevents normal staging or would require a non-trivial policy change.
+- Ignored untracked files stay local-only by default and do not need to be committed.
+- Ignored tracked files should be treated as repository hygiene issues: remove them from version control and commit that removal unless the user explicitly says otherwise.
+- Aim to finish with no leftover tracked modified or staged files unless the user explicitly excluded them or a blocker was reported.
 
 ### 3. Logical Grouping
 
@@ -69,6 +85,11 @@ Use this skill to inspect current repository differences, decide what is ready t
 
 - Stage only the files that belong to the current group.
 - Commit each group with the drafted message using non-interactive git commands.
+- If `git add` reports that a path is ignored, do not use `git add -f` or any force-add switch as a shortcut.
+- When an ignored file seems to be showing up in status anyway, diagnose whether it is already tracked with `git ls-files` and confirm the matching ignore rule with `git check-ignore -v --no-index` before changing anything.
+- If an ignored file is already tracked, do not recommit it as normal content. Prefer removing it from version control with `git rm --cached`, then commit that removal so the file becomes local-only and ignored again.
+- If an ignored file is untracked, leave it local-only and ignored. Do not treat it as a commit blocker unless the user explicitly asks to version it or to change ignore policy.
+- If the user explicitly wants an ignored tracked file to remain versioned, stop and call out that this conflicts with the ignore policy before proceeding.
 - If a git command fails because of `.git/index.lock` or a likely concurrent git process, wait a few seconds and retry before treating it as a blocker.
 - Preferred retry behavior for transient git locking:
   - wait about 2 to 5 seconds
@@ -78,6 +99,7 @@ Use this skill to inspect current repository differences, decide what is ready t
 - After each commit, verify the worktree and confirm the next group is still valid.
 - If build or tests are part of the expected verification, run them at the appropriate point.
 - Continue until all `commit-now` groups are committed or a real blocker is reached.
+- Do not stop early just because some changes look secondary; if they are still modified and not explicitly excluded, they must be grouped and committed before finishing.
 
 ### 7. Final Reporting
 
@@ -93,18 +115,29 @@ Use this skill to inspect current repository differences, decide what is ready t
 - Report any deferred `hold` or `needs-review` items left in the worktree.
 - State any verification commands that were run and their result.
 - State whether push succeeded or failed.
+- If anything remains tracked and modified or staged at the end, explain exactly why it was not committed and whether that came from an explicit user instruction or a blocking constraint.
+- If ignored local-only files remain, mention them only when they are relevant to explain an untrack action or a policy conflict.
+- Prefer a short close-out when the run is clean: brief repository summary, compact list of created commits, push result, and any truly relevant leftover note.
+- Expand to the fuller report structure only when there are deferred items, blockers, non-obvious grouping decisions, risky files, sync problems, or a failed push.
 
 ## Output Format
 
 Keep the final report concise by default. Compress file-by-file detail unless it is needed to explain grouping or a deferred risk.
 
-Provide results using this structure:
+For clean runs, prefer a compact format such as:
+
+- short repository change summary
+- compact execution results like `<hash> [YYYY-MM-DD] <subject>`
+- push result
+- deferred items only if any remain
+
+Use the fuller structure below only when the run is not clean or when the user explicitly asks for more detail:
 
 1. Repository change summary
 2. Commit readiness table (`commit-now` / `hold` / `needs-review`)
 3. Proposed commit groups with short rationale
 4. Ordered commit plan
-5. Draft commit messages (subject and optional body when needed)
+5. Draft commit messages when they add value
 6. Execution result per committed group
 7. Push result
 8. Deferred items and assumptions
@@ -115,17 +148,23 @@ Prefer:
 - compact execution results like `<hash> [YYYY-MM-DD] <subject>`
 - compact push result like `push succeeded` or `push failed: non-fast-forward`
 - brief deferred-item notes
+- omit sections such as draft messages or readiness tables when they add no signal in a clean run
 
 Only expand beyond that when:
 - a group boundary is non-obvious
 - a risky file is being held back
+- the run was blocked or partially complete
 - the user explicitly asks for a detailed breakdown
 
 ## Execution Guardrails
 
 - Do not use destructive commands such as `git reset --hard`, `git checkout --`, or force-push unless explicitly requested.
+- Do not use `git add -f`, `git add --force`, or similar overrides to stage ignored files unless the user has explicitly confirmed that bypassing ignore rules is intended.
 - Do not amend commits unless explicitly requested.
-- Do not commit files marked `hold` or `needs-review` just to empty the worktree.
+- Do not leave tracked modifications behind by default; commit them unless the user explicitly excluded them.
+- Do not commit ignored files as normal repository content.
+- If a tracked file is covered by ignore rules, prefer untracking it and committing the removal rather than recommitting its contents.
+- Do not commit files marked `hold` or `needs-review` just to empty the worktree, but also do not invent `hold` items unless the user explicitly asked for them or a real blocker exists.
 - If unexpected changes appear during execution, stop and report the issue before continuing.
 - Keep commits scoped, reviewable, and logically ordered.
 - Treat transient git lock errors as retryable first, not as immediate hard failures.

.agents/skills/repo-sync-branch-into-main/SKILL.md

@@ -0,0 +1,94 @@
+---
+name: repo-sync-branch-into-main
+description: Verify a branch is fully synced, switch to mainline, refresh mainline, and merge the branch into main locally.
+---
+
+# Repo Branch Into Main Sync
+
+## Overview
+
+Use this skill when the goal is to bring the current non-main branch onto the repository's mainline branch. The skill verifies that the source branch is fully synced with its remote upstream first, switches to the detected mainline branch, refreshes mainline from remote again, and then merges the source branch into mainline locally. The default outcome is a local mainline merge result that can be reviewed and pushed afterward.
+
+## When To Use
+
+- You want to bring the current feature, fix, or release branch onto `main` or `master`.
+- You want a repeatable promotion flow with explicit upstream checks before touching mainline.
+- You want mainline refreshed from remote immediately before merging the source branch.
+- You want the branch promotion captured locally on mainline, typically as an explicit merge commit.
+
+## When Not To Use
+
+- Do not use this skill for rebases, cherry-picks, or history rewrites.
+- Do not use this skill when the source branch still needs local commits, push, or pull work before promotion.
+- Do not use this skill when you want automatic mainline push as part of the default flow.
+- Do not use this skill to guess a source branch while already on `main` or `master` unless the user explicitly names the branch to merge.
+
+## Inputs Needed
+
+- Current branch name.
+- Upstream tracking state for the current branch.
+- Detected mainline branch, preferring `main`, then `master`, then the remote default branch when discoverable.
+- Optional explicit source branch if the current branch is already the detected mainline branch.
+
+## Workflow
+
+### 0. Detect Branch Roles
+
+- Detect the mainline branch in this order:
+  - local `main`
+  - local `master`
+  - the branch pointed to by `origin/HEAD`, if available
+- If no mainline branch can be determined, stop and report that blocker.
+- If the current branch is not the detected mainline branch, treat the current branch as the source branch.
+- If the current branch is already the detected mainline branch, require the user to explicitly name the source branch to merge. Do not guess from checkout history or reflog.
+
+### 1. Source Branch Sync Gate
+
+- Fetch remotes first so branch status is current.
+- Verify that the source branch has an upstream tracking branch.
+- Verify that the source branch is fully synced with upstream: ahead `0` and behind `0`.
+- If the source branch is ahead, behind, or diverged, stop and report that the branch must be fully synced before promotion.
+- Verify the worktree has no tracked modifications or staged changes before switching branches.
+- Ignored local-only files may remain as long as they do not block checkout or merge.
+- If checkout would be blocked by local files, stop and report the exact blocker instead of stashing automatically.
+
+### 2. Switch To Mainline And Refresh It
+
+- Checkout the detected mainline branch.
+- Fetch again after switching so mainline state is current at the moment of promotion.
+- If mainline has an upstream and is behind but not diverged, sync it with a normal non-interactive fast-forward pull such as `git pull --ff-only`.
+- If mainline is ahead of upstream, leave those local mainline commits intact and continue unless the user explicitly wants a different policy.
+- If mainline has diverged from upstream, stop and report it instead of choosing merge or rebase automatically.
+
+### 3. Bring Source Branch Onto Mainline
+
+- Merge the source branch into mainline locally.
+- Default to an explicit local merge commit by using a non-interactive merge such as `git merge --no-ff --no-edit <source-branch>`.
+- If the source branch is already fully contained in mainline, report that mainline is already up to date and stop without creating a new commit.
+- If Git reports merge conflicts, stop and report the conflicted state clearly. Do not auto-resolve conflicts.
+
+### 4. Post-Merge State
+
+- After a successful merge, report the resulting mainline commit state and whether the branch is now ahead of remote.
+- Do not push mainline by default. The default endpoint of this skill is a local mainline merge result ready for review or a later explicit push.
+- If the user explicitly asks to push after the merge, only then perform a normal push and report the result.
+
+## Final Reporting
+
+- For a clean successful run, keep the summary short:
+  - source branch
+  - detected mainline branch
+  - whether source was already fully synced
+  - whether mainline was refreshed from remote
+  - resulting merge commit or "already up to date"
+  - whether mainline is now ahead of remote locally
+- Expand only when there are blockers, sync mismatches, conflicts, or the user asks for more detail.
+
+## Execution Guardrails
+
+- Do not use destructive commands such as `git reset --hard`, `git checkout --`, force-push, or history rewriting unless explicitly requested.
+- Do not auto-stash or auto-commit local work to make the branch switch succeed.
+- Do not promote a source branch that is not fully synced with its remote upstream.
+- Do not guess a merge strategy beyond the default local merge commit flow.
+- Do not auto-push mainline unless the user explicitly asks for it.
+- Do not suppress checkout, pull, or merge blockers; report them clearly.

.agents/skills/repo-sync-branch-into-main/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Repo Branch Into Main Sync"
+  short_description: "Sync a branch and bring it onto main"
+  default_prompt: "Use $repo-sync-branch-into-main to verify the current branch is fully synced with remote, switch to the detected mainline branch, refresh mainline from remote, and merge the branch into main locally."