Repo Management

Repo Management

Intro

repo-management gives agents a provider-neutral workflow for routine repository stewardship: inspect open issues and change requests, plan safe actions, merge only ready work, commit local changes, and push. Use it when the user asks to check all open issues or PRs, clean up a repo, reconcile repository state, merge ready work, commit and push, or perform repo-maintenance across providers.

Overview

The default workflow is plan-first and guarded:

1. Call detect_repo_provider(project_root, remote) to identify the remote platform and available local CLI.
2. Call inspect_repo_state(project_root) to inspect branch, dirty state, upstream, ahead/behind status, remotes, and provider support.
3. Call list_repo_issues() and list_repo_change_requests() for the current provider when supported.
4. Call plan_repo_reconcile(scope) to build a concrete action plan.
5. Apply only actions that pass the safety rules below. Use run_repo_reconcile(dry_run=false) for guarded batch work, or call the narrow mutating tools directly.

When the task involves branch policy, review judgment, or release work, also follow the local git-workflow, code-review, and release-semver skill guidance.

/pk-repo-reconcile is the user command for the same workflow. Without extra arguments it means scope=all: local git state, open issues, open change requests, and push readiness. Users may narrow it with issues, prs, local, or push.

Provider support

Unsupported provider actions must return structured evidence instead of pretending the work is complete. Agents should still commit and push local changes through git when the repository policy allows it.

MCP tools

Gotchas

• Do not close issues without evidence. A close action needs a linked merged change, a duplicate reference, a clear no-repro disposition, or explicit user instruction.
• Do not merge drafts or WIP change requests. Draft state is a hard blocker even if checks are green.
• Do not bypass branch protection. Never force-push, override required reviews, skip required checks, or bypass merge queues.
• Do not assume GitHub-only behavior. Detect the provider first and return unsupported evidence for adapters that are not configured.
• Do not treat listing as resolving. If issues or change requests remain open, report the plan or blocker that remains.
• Do not push unrelated local work blindly. Inspect git status and commit only the intended paths or the current complete worktree when the user asked for all local changes.
• Do not run mutating batch actions without a dry-run plan. run_repo_reconcile(dry_run=false) should report the plan it applied and every command result.
• Do not hide external auth failures. Missing gh, glab, tea, bb, az, or hut authentication is an actionable blocker, not a successful no-op.

Full reference

Safety policy

The skill is deliberately conservative:

• No force pushes.
• No direct API bypass of provider protection rules.
• No draft/WIP merge.
• No issue close without a comment or explicit resolution evidence.
• Mutating issue and merge tools require exact confirmation tokens: close-issue:<id> and merge-change-request:<id>.
• Provider-specific actions are serialized by the caller; batch tools return per-action evidence.

Scope names

plan_repo_reconcile() and /pk-repo-reconcile accept these scopes:

Provider notes

GitHub is the first fully mutating adapter because the gh CLI is common in aibox environments and enforces provider-side checks. GitLab, Gitea, Forgejo/Codeberg, Bitbucket Cloud, Azure DevOps, and SourceHut are first-class provider identities in the schema and detection layer; their remote issue and change-request mutation paths return unsupported until the matching local CLI or API credential contract is implemented.