Template

By Specship · Last updated May 26, 2026

AI agent ticket template for reviewable pull requests.

Use this structure before assigning work to Specship, GitHub Copilot coding agent, Cursor background agents, Devin-style agents, or any AI system that writes code and opens a pull request.

Use with Specship Read the guide
What this prevents
  • Vague acceptance criteria
  • Untestable implementation
  • PRs that drift from the request
  • Unsafe changes to billing, auth, or data
Direct answer: an AI-agent-ready ticket should include context, scope, acceptance criteria, test expectations, edge cases, protected areas, and a PR review checklist before the agent writes code.

Copy this ticket template

# Title
<Verb + object + outcome>

## Context
Why this change matters:
- User/customer problem:
- Current behavior:
- Desired behavior:

## Scope
In scope:
- 

Out of scope:
- 

Likely files, components, or endpoints:
- 

Protected areas that require human review:
- Auth:
- Billing:
- Data migration:
- Permissions:

## Acceptance criteria
- [ ] 
- [ ] 
- [ ] 

## Test expectations
Write failing tests before implementation.

Test runner / pattern to use:
- 

Required cases:
- Happy path:
- Empty state:
- Error state:
- Permission or role case:
- Regression case:

## Implementation constraints
- Match existing project conventions.
- Prefer existing components and helpers.
- Keep the diff focused on this ticket.
- Do not change public API behavior unless listed in acceptance criteria.

## PR review checklist
- [ ] Acceptance criteria are covered by tests.
- [ ] New tests fail before implementation and pass after.
- [ ] Existing test suite remains green.
- [ ] Risky files are called out in the PR description.
- [ ] Human reviewer can verify behavior without re-reading the whole diff.
Tool variants

Use the same agent-ready structure in GitHub Issues, Linear, and Jira.

The fields should stay stable across tools. Change labels and ownership metadata, but keep the acceptance criteria, test expectations, protected areas, and PR checklist visible where reviewers will see them.

GitHub Issues

Issue body for code changes

Use labels like agent-ready, tests-required, and human-review. Link the final pull request back to the issue.

Linear

Ticket fields for async work

Keep scope and acceptance criteria in the description. Add engineering owner, target repo, and design link as structured fields.

Jira

Enterprise ticket hygiene

Separate business context from implementation notes. Put permissions, audit, and data-migration constraints where reviewers cannot miss them.

Filled example

Example: export filtered table rows to CSV.

This synthetic example shows the level of detail that makes an AI-generated pull request reviewable. The ticket does not over-specify implementation, but it gives the coding agent enough behavior, tests, and constraints to stay inside the intended change.

Acceptance criteria

  • Export only the rows visible after filters and search are applied.
  • Preserve column order from the current table view.
  • Show an empty-state toast if no rows match the current filters.
  • Do not change billing, permissions, or table query behavior.

Test expectations

  • Failing test for filtered export count before implementation.
  • Regression test for empty filtered results.
  • Existing table rendering tests remain green.
See the full ticket-to-PR example
FAQ

AI agent ticket template questions

What makes a ticket ready for an AI coding agent?

A ticket is agent-ready when it includes the desired behavior, acceptance criteria, test expectations, constraints, edge cases, and review gates.

Should an AI coding agent write tests before code?

For bounded software changes, tests should come before implementation so reviewers can inspect the intended behavior before reviewing the diff.

Can the same template work in GitHub Issues, Linear, and Jira?

Yes. The core structure is portable. Adapt ownership, labels, and status fields to the tool while keeping criteria and review rules visible.

What should reviewers check on an AI-generated pull request?

Reviewers should check criteria coverage, tests, unrelated changes, risky files, and whether sensitive paths stayed behind human review.

Idea-to-PR AI agentShape rough product ideas into scoped tickets, tests, and pull requests. Spec-driven AI codingTurn rough intent into acceptance criteria, tests, and review rules. Ticket-to-PR AI agentSee how agent-ready tickets become pull requests. Security controlsReview budget, credential, protected-path, and merge-policy boundaries.