Problem
In a bootstrapped downstream project, an agent integrated PRs with merge commits even though the toolkit implement-issue-workflow skill already documents linear PR integration via:
gh pr merge <number> --rebase --delete-branch
The rule exists, but it is too easy to miss when the user says something like "integrate the PR and clean up". The agent may fall back to a generic GitHub workflow and use gh pr merge --merge --delete-branch instead of consulting the toolkit SDLC workflow first.
Why this matters
Bootstrapped projects rely on AGENTS.md and toolkit guidance to make SDLC behavior repeatable. PR integration is an operational safety rule, not only implementation-skill detail. If it is only nested in one skill, other generic GitHub paths can accidentally override the intended linear-history policy.
Proposed change
Strengthen the bootstrap output and toolkit contracts so the rule is visible at the project-agent level:
- Update
templates/agents/project-agents.md with an explicit Pull Request Integration section.
- Update the example
AGENTS.md accordingly.
- Update
skills/bootstrap-project/SKILL.md so bootstrap explicitly installs or preserves this PR integration guardrail.
- Consider adding a short SDLC contract to
general-semantic-contracts.md.
Suggested project-agent wording:
## Pull Request Integration
When asked to integrate, merge, land, or clean up a pull request, first read the
toolkit issue implementation and post-merge synchronization skills.
For clean, mergeable PRs with green checks, prefer linear history:
gh pr merge <number> --rebase --delete-branch
Do not use merge commits or squash unless the user explicitly requests it or
repository policy requires it.
Acceptance criteria
- Bootstrapped
AGENTS.md guidance makes rebase integration the visible default for clean PRs.
- Bootstrap guidance says to include this PR integration guardrail in downstream projects.
- Existing
implement-issue-workflow and post-merge-sync guidance remains consistent.
- Merge commits and squash integration remain allowed only when explicitly requested or required by repository policy.
Problem
In a bootstrapped downstream project, an agent integrated PRs with merge commits even though the toolkit
implement-issue-workflowskill already documents linear PR integration via:The rule exists, but it is too easy to miss when the user says something like "integrate the PR and clean up". The agent may fall back to a generic GitHub workflow and use
gh pr merge --merge --delete-branchinstead of consulting the toolkit SDLC workflow first.Why this matters
Bootstrapped projects rely on
AGENTS.mdand toolkit guidance to make SDLC behavior repeatable. PR integration is an operational safety rule, not only implementation-skill detail. If it is only nested in one skill, other generic GitHub paths can accidentally override the intended linear-history policy.Proposed change
Strengthen the bootstrap output and toolkit contracts so the rule is visible at the project-agent level:
templates/agents/project-agents.mdwith an explicitPull Request Integrationsection.AGENTS.mdaccordingly.skills/bootstrap-project/SKILL.mdso bootstrap explicitly installs or preserves this PR integration guardrail.general-semantic-contracts.md.Suggested project-agent wording:
Acceptance criteria
AGENTS.mdguidance makes rebase integration the visible default for clean PRs.implement-issue-workflowandpost-merge-syncguidance remains consistent.