Instruction file imported from svoby/chatbot-harness (.cursor/rules/feature-branching.mdc). Copyright stays with the author.

Git workflow

AGENTS.md is the root source of truth for repo safety and workflow. This rule is the Cursor adapter for that policy.

Ad-hoc work - conservative by default

For non-issue work, the agent must not create, checkout, or switch branches on its own. Work on whatever branch is currently active. If a branch change is needed, ask the user explicitly.

The agent must not run git add, stage files, commit, push, open a PR, merge, or rebase unless the user explicitly asks.

Optionally, when wrapping up ad-hoc work, write the intended commit message to .git/COMMIT_EDITMSG so the user can paste or adjust it in Source Control.

GitHub issue work - built-in exception

When the user launches work with:

Implement GitHub issue #N.

fetch the issue and treat its body as the task contract. This issue-driven workflow may create the issue branch, commit, push, and open a PR without the user repeating those permissions.

Required issue workflow:

1. Read AGENTS.md, fetch the issue, and verify it against current master.
2. Read every file listed in the issue's Required context section before editing.
3. Create the branch named by the issue. If no branch is named, use issue-N-<short-slug>.
4. Edit only files and behavior authorized by the issue.
5. Verify git status and git diff before committing; stop if unexpected files appear.
6. Run the verification requested by the issue.
7. Commit, push, and open a PR against master unless the issue specifies another base.
8. Run the PR review gate and publish the review result on the PR before handoff. The implementation agent must initiate this step after opening the PR. Use .cursor/agents/code-review.md for the independent review pass when available. If a separate reviewer is unavailable, perform the same review pass in-agent and state that fallback in the visible PR comment.
9. Never merge the PR unless a human explicitly requests it.

Branch naming

Use the issue-specified branch name for issue work. If there is no issue-specified branch:

• feat/<task-name> for new features.
• fix/<task-name> for bug fixes.
• chore/<task-name> for tooling, documentation, and refactors.
• test/<task-name> for test-only changes.
• issue-N-<short-slug> for GitHub issue work without a named branch.

Parallel issue agents and worktrees

• One issue = one branch = one PR.
• For parallel issue agents, also use one isolated worktree or checkout per issue.
• Never let two agents share the same mutable working directory.
• Run parallel issue agents only when their allowed file sets do not overlap.
• Before editing issue work, check current branch/status and open PRs for overlap with the issue's allowed files.
• For a single issue in the current checkout, creating the issue branch is enough; worktrees are required only for parallel work or when the launcher environment provides them.

PR body requirements

Every issue-driven PR must include:

• Summary
• Changed files
• Context read
• Verification performed, or an explicit explanation if not run
• Known risks / follow-ups
• Closes #N

Every issue-driven PR must also have a visible review gate result on the PR before the agent calls the work ready for human merge. Prefer a separate review agent; in-agent review is only a fallback that must be disclosed in the PR comment.

When work is done

• For ad-hoc work, do not merge, push, open a PR, or rebase from the agent session unless the user explicitly asks.
• For issue work, push, open the PR, publish the review gate result, then hand off. Humans merge.

Environment and timeout guardrails

Mirror the operating policy in AGENTS.md:

• GitHub Actions Ubuntu is the dependency reproducibility source of truth. CI install remains npm ci; do not add npm install --no-save CI workarounds.
• Generate dependency and package-lock.json changes from Linux/WSL or an equivalent Linux environment unless explicitly asked otherwise.
• If sandboxing blocks .git, npm cache/log dirs, network, or credentials, make at most one sandbox attempt and one justified fallback attempt before stopping with the exact blocker and needed human command/tool action.
• Treat launcher/UI permissions as the effective boundary when they are stricter than local config files.
• Use short timeouts for ordinary inspection commands and interrupt/report hangs. Long waits are reserved for expected installs, downloads, builds, tests, and GitHub/network operations.
• If WSL lacks GitHub credentials, prefer approved connector/tooling or ask the human to push. Use Windows Git only when repo policy permits it and the same checkout/diff has already been verified.
• gh means GitHub CLI. In WSL/Ubuntu local agent sessions, git and gh are normal tools for repository and PR operations when credentials are configured; MCP/ChatGPT/GitHub connector tooling is an alternative control plane, not a requirement for every shell operation.
• If gh is missing, report the missing tool and point to the official GitHub CLI install docs. If gh is installed but unauthenticated, use one focused gh auth status / approved gh auth login path, then stop at the existing credential gate if still blocked.
• Keep dependency and CI verification in WSL/Ubuntu even if GitHub credentials work elsewhere.