Skip to content

Make linear PR integration explicit in bootstrap agent guidance #49

Description

@dieterbaier

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:

  1. Update templates/agents/project-agents.md with an explicit Pull Request Integration section.
  2. Update the example AGENTS.md accordingly.
  3. Update skills/bootstrap-project/SKILL.md so bootstrap explicitly installs or preserves this PR integration guardrail.
  4. 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.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions