TenantAtlas/.github/skills/platform-feature-finish/SKILL.md

---

name: platform-feature-finish description: Commit, push, create a Gitea PR from a TenantPilot platform feature branch into platform-dev, and optionally refresh the platform-dev to dev integration PR by rebase.

Skill: platform-feature-finish

Purpose

Automate the TenantPilot platform feature completion workflow.

Trigger this skill when the user says something like:

• "alles committen pushen und PR gegen platform-dev"
• "feature fertig, bitte PR erstellen"
• "platform feature abschließen"
• "commit push PR mit Gitea MCP"
• "mach PR gegen platform-dev"
• "finish platform feature"
• "platform-dev nach dev vorbereiten"
• "platform-dev PR aktualisieren"
• "out-of-date mit dev beheben"
• "integration PR refresh"
• "platform-dev auf dev rebasen"

This skill handles:

1. Validate current Git branch
2. Commit all feature changes
3. Push current feature branch
4. Create a Gitea pull request into platform-dev
5. Refresh the platform-dev → dev integration PR when explicitly requested
6. Report the PR link and next integration step

---

Branch Model

TenantPilot uses area branches:

dev           = shared integration branch
platform-dev  = platform/application area integration branch
website-dev   = website/marketing area integration branch

For platform features:

platform-dev
  ↓
feature branch
  ↓
PR back to platform-dev
  ↓
platform-dev → dev integration PR

Rules:

• Platform feature branches MUST target platform-dev.
• Do NOT target dev directly unless the user explicitly asks.
• Do NOT use website-dev for platform features.
• platform-dev is the default PR base for TenantPilot platform/application work.
• dev is the shared integration branch.

Solo Workflow Rule

The user works alone on platform-dev.

For refreshing the integration branch before opening or updating the PR platform-dev → dev, prefer rebase over merge.

Do not repeatedly merge origin/dev into platform-dev for refresh.

Avoid creating repeated merge commits like:

Merge remote-tracking branch 'origin/dev' into platform-dev

Use --force-with-lease, never plain --force.

If rebase conflicts occur, stop and report the conflict files.

---

Preconditions

Before committing:

1. Confirm repository root.
2. Confirm current branch is not protected.

Protected branches:

dev
platform-dev
website-dev
main
master

If the current branch is protected, STOP and report:

Ich bin auf einem geschützten Branch. Bitte zuerst einen Feature-Branch auschecken.

3. Confirm remote exists.
4. Confirm there are local changes, untracked files, or unpushed commits.
5. Confirm there are no unresolved conflicts.

Do not ask for confirmation unless:

• The current branch is protected.
• Git status indicates unresolved conflicts.
• There is no remote configured.
• .env or other local secret/config files would be committed.
• Commit fails.
• Push fails.
• Gitea MCP PR creation fails.

---

Required Tools

Use terminal for Git operations.

Use Gitea MCP for pull request creation.

Preferred Gitea MCP operation:

create_pull_request

Required PR parameters:

{
  "owner": "ahmido",
  "repo": "TenantAtlas",
  "head": "<current-feature-branch>",
  "base": "platform-dev",
  "title": "<generated-title>",
  "body": "<generated-body>"
}

---

Workflow

Step 1 — Inspect Git state

Run:

git rev-parse --show-toplevel
git rev-parse --abbrev-ref HEAD
git status --porcelain
git status -sb
git config --get remote.origin.url
git log --oneline --max-count=5

Determine:

• repository root
• current branch
• changed files
• untracked files
• remote URL
• whether there are unpushed commits
• whether unresolved conflicts exist

If the current branch is protected, stop.

If unresolved conflicts exist, stop.

If no remote exists, stop.

---

Step 2 — Check for local environment files

Before git add -A, check whether local environment/config files are modified or untracked:

git status --porcelain | grep -E '(^.. \.env$|^.. apps/platform/\.env$|^.. .*\.env$)' || true

If .env or another environment file is included, STOP and report:

Achtung: Eine .env-/Environment-Datei ist geändert oder untracked. Ich committe das nicht automatisch. Bitte prüfen oder aus dem Commit entfernen.

Do not commit secrets or local runtime configuration.

---

Step 3 — Build commit message

Use the current branch name.

If branch starts with a spec number, for example:

256-external-support-desk-handoff

Generate:

feat(specs/256): external support desk handoff

If branch does not contain a spec number, generate:

feat(platform): complete <branch-name>

Rules:

• Use lowercase subject.
• Use feature-style subject.
• Do not include WIP.
• Do not include final.
• Do not include overly generic updates.

Examples:

feat(specs/256): external support desk handoff
feat(specs/252): platform localization v1
feat(platform): improve tenant review workspace

---

Step 4 — Commit all changes

Run:

git add -A
git commit -m "<commit-message>"

If there are no local changes to commit, continue only if the branch has unpushed commits.

Check unpushed commits with:

git status -sb
git log --oneline origin/<current-branch>..HEAD

If there are no local changes and no unpushed commits, report:

Es gibt keine lokalen Änderungen und keine unpushed commits. Ich erstelle keinen leeren Commit.

Then continue to PR creation only if the branch already exists remotely or can be pushed.

---

Step 5 — Push branch

Run:

git push --set-upstream origin <current-branch>

If the upstream already exists, this is acceptable.

Never force-push unless the user explicitly requests it.

---

Step 6 — Create PR into platform-dev via Gitea MCP

Use Gitea MCP to create a pull request:

{
  "owner": "ahmido",
  "repo": "TenantAtlas",
  "head": "<current-feature-branch>",
  "base": "platform-dev",
  "title": "<commit-message>",
  "body": "Implements platform feature branch `<current-feature-branch>`.\n\nTarget branch: `platform-dev`.\n\nFollow-up integration path after merge:\n\n`platform-dev` → `dev`."
}

If a PR already exists for the same branch and base, do not create a duplicate.

Report the existing PR if available.

---

Optional Step — Check platform-dev to dev PR

After creating the feature PR, check whether an open integration PR exists:

platform-dev → dev

If a Gitea MCP list/search pull request function is available, use it.

If one exists, report:

Der Folge-PR `platform-dev` → `dev` existiert bereits: <url>

If none exists, report:

Nach dem Merge dieses Feature-PRs sollte der Integrations-PR `platform-dev` → `dev` erstellt oder aktualisiert werden.

Do not automatically create the platform-dev → dev PR unless the user explicitly asks for it.

Reason: before the feature PR is merged into platform-dev, the integration PR may not include the new feature yet.

---

Integration Refresh Mode

Use this mode when the user explicitly says one of the following:

• "platform-dev nach dev vorbereiten"
• "platform-dev PR aktualisieren"
• "out-of-date mit dev beheben"
• "integration PR refresh"
• "platform-dev auf dev rebasen"
• "auch platform-dev nach dev"
• "und danach platform-dev nach dev"
• "full integration"
• "kompletten platform-dev zu dev PR machen"
• "folge-pr erstellen"

This mode prepares or updates the integration PR:

platform-dev → dev

Because the user works alone on platform-dev, prefer rebase over merge.

Integration Refresh Preconditions

Before running this mode:

1. Ensure the working tree is clean.
2. Ensure there are no unresolved conflicts.
3. Fetch remote branches.
4. Ensure origin/platform-dev exists.
5. Ensure origin/dev exists.

If the working tree is dirty, STOP and report:

Der Working Tree ist nicht sauber. Bitte erst Änderungen committen, stashen oder verwerfen, bevor `platform-dev` auf `dev` rebased wird.

If unresolved conflicts exist, STOP and report the conflict files.

Integration Refresh Workflow

Run:

git fetch origin
git checkout platform-dev
git reset --hard origin/platform-dev
git rebase origin/dev
git push --force-with-lease origin platform-dev

After pushing, verify that origin/dev is now an ancestor of origin/platform-dev:

git fetch origin
git merge-base --is-ancestor origin/dev origin/platform-dev \
  && echo "OK: platform-dev contains dev" \
  || echo "OUTDATED: platform-dev does not contain dev"

If the verification prints OUTDATED, stop and report it. Do not claim the PR is up-to-date.

Rules:

• Do not merge origin/dev into platform-dev for this refresh.
• Do not create repeated merge commits from origin/dev into platform-dev.
• Use git push --force-with-lease origin platform-dev after a successful rebase.
• Never use plain git push --force.
• If git rebase origin/dev reports conflicts, stop immediately.
• Do not continue to PR creation while a rebase is unresolved.
• Do not auto-merge the PR.
• Do not claim Gitea will remove the out-of-date warning unless the ancestor check succeeds.

If rebase conflicts occur, report:

Rebase-Konflikte erkannt. Ich habe gestoppt.

Konfliktdateien:
<files>

Bitte Konflikte lösen, dann `git rebase --continue` ausführen oder den Rebase mit `git rebase --abort` abbrechen.

Create or Report Integration PR

After the rebase, push, and ancestor verification succeeded, use Gitea MCP to create or report the integration PR:

{
  "owner": "ahmido",
  "repo": "TenantAtlas",
  "head": "platform-dev",
  "base": "dev",
  "title": "chore(platform): merge platform-dev into dev",
  "body": "Integrates latest TenantPilot platform changes from `platform-dev` into `dev`.\n\nThis PR was created by agent on user request; do not merge automatically."
}

If an open PR already exists for platform-dev → dev, do not create a duplicate. Report the existing PR.

Integration Refresh Reporting Format

Final response for this mode must include:

Fertig.

- Branch aktualisiert: platform-dev
- Refresh-Methode: rebase auf origin/dev
- Ancestor-Check: origin/dev ist Ancestor von origin/platform-dev
- Push: --force-with-lease origin/platform-dev
- Integration PR: <url>
- Base: dev
- Hinweis: PR wurde nicht automatisch gemerged.

Do not claim tests passed unless they were actually executed.

---

Reporting Format

Final response must be concise and include:

Fertig.

- Branch: <branch>
- Commit: <commit-sha or "keine neuen Änderungen">
- Push: origin/<branch>
- PR: <url>
- Base: platform-dev
- Nächster Schritt: Nach Merge `platform-dev` → `dev` PR aktualisieren/erstellen

If tests were not run, say:

Tests wurden in diesem Skill nicht automatisch ausgeführt.

Do not claim tests passed unless the tool actually ran them.

---

Safety Rules

• Never commit directly to dev, platform-dev, website-dev, main, or master.
• Never force-push unless explicitly requested.
• For Integration Refresh Mode only, git push --force-with-lease origin platform-dev is allowed because the user works alone on platform-dev; never use plain --force.
• Never auto-merge PRs unless explicitly requested.
• Never target dev directly for platform feature PRs unless explicitly requested.
• Never delete branches unless explicitly requested.
• Never claim tests were run unless the tool actually ran them.
• Never commit .env, secrets, local tokens, local mock-server configuration, or temporary runtime-only changes.
• If migrations were created, mention that the target environment needs migration execution after deployment.
• If unresolved conflicts exist, stop.

---

Useful Commands

Inspect:

git rev-parse --show-toplevel
git rev-parse --abbrev-ref HEAD
git status --porcelain
git status -sb
git config --get remote.origin.url

Detect protected branch:

branch="$(git rev-parse --abbrev-ref HEAD)"
case "$branch" in
  dev|platform-dev|website-dev|main|master)
    echo "PROTECTED_BRANCH:$branch"
    exit 2
    ;;
esac

Detect unresolved conflicts:

git diff --name-only --diff-filter=U

Detect .env changes:

git status --porcelain | grep -E '(^.. \.env$|^.. apps/platform/\.env$|^.. .*\.env$)' || true

Commit:

git add -A
git commit -m "<message>"

Push:

git push --set-upstream origin "$(git rev-parse --abbrev-ref HEAD)"

Latest commit:

git rev-parse --short HEAD
git log -1 --pretty=%s

Integration refresh:

git fetch origin
git checkout platform-dev
git reset --hard origin/platform-dev
git rebase origin/dev
git push --force-with-lease origin platform-dev

Verify integration refresh:

git fetch origin
git merge-base --is-ancestor origin/dev origin/platform-dev \
  && echo "OK: platform-dev contains dev" \
  || echo "OUTDATED: platform-dev does not contain dev"

Check rebase conflicts:

git diff --name-only --diff-filter=U

---

Example User Request

User:

alles committen pushen und pr gegen platform-dev mit gitea mcp

Assistant should:

1. Check current branch.
2. Stop if branch is protected.
3. Stop if .env or secrets would be committed.
4. Commit all changes.
5. Push current branch.
6. Create PR into platform-dev with Gitea MCP.
7. Report result.

Do not ask unnecessary follow-up questions.

---

Example Integration Refresh Request

User:

platform-dev PR aktualisieren

Assistant should:

1. Ensure the working tree is clean.
2. Fetch origin.
3. Checkout platform-dev.
4. Reset local platform-dev to origin/platform-dev.
5. Rebase platform-dev onto origin/dev.
6. Push with --force-with-lease.
7. Verify origin/dev is an ancestor of origin/platform-dev.
8. Create or report the PR platform-dev → dev.
9. Report result.

Do not merge the PR automatically.