Linear Sop
Productivitylinear-sopLinear Sop is an Agent Skill for productivity published in the bybren-llc/safe-agentic-workflow repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.
Ticket management best practices for Linear or equivalent project tracker. Use when creating issues, updating ticket status, attaching evidence, parsing acceptance criteria, or working with ticket UUIDs. Provides evidence templates for dev/staging/done phases.
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
Inspect the Agent Skill at https://github.com/bybren-llc/safe-agentic-workflow/blob/HEAD/.agents/skills/linear-sop/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/linear-sop, but wait for my approval before writing files or running scripts.
Copying this prompt does not install or run the skill. Review third-party files before use.
Linear SOP Skill
TEMPLATE: This skill uses
{{PLACEHOLDER}}tokens. Replace with your project values before use.
Purpose
Guide consistent ticket management. Provides evidence templates for the mandatory dev/staging/UAT evidence policy.
When This Skill Applies
- Creating new issues in the ticket system
- Updating ticket status
- Attaching evidence to tickets
- Parsing acceptance criteria
- Working with UUIDs and issue IDs
Ticket System Operations
Reading Issues
# Get issue by identifier
get_issue({ id: "{{TICKET_PREFIX}}-459" })
# List issues with filters
list_issues({
team: "{{PROJECT_TEAM_NAME}}",
state: "In Progress",
assignee: "me",
})
Creating Issues
create_issue({
title: "feat(scope): description",
team: "{{PROJECT_TEAM_NAME}}",
description: "## Summary\n\n...",
labels: ["feature", "sprint-1"],
parentId: "parent-uuid", // Optional - for sub-issues
})
Updating Issues
update_issue({
id: "{{TICKET_PREFIX}}-459",
state: "Done",
})
Adding Comments
create_comment({
issueId: "{{TICKET_PREFIX}}-459",
body: "**Dev Evidence**\n\n...",
})
Evidence Policy (MUST)
Every issue requires evidence at each phase:
| Phase | Required? | Content |
|---|---|---|
| Dev | MUST | Implementation proof |
| Staging | MUST | UAT validation (or N/A) |
| Done | MUST | Final verification |
Evidence Templates
Dev Evidence Template
**Dev Evidence**
**PR**: https://github.com/{{ORG_NAME}}/{{REPO_NAME}}/pull/XXX
**Commit**: [short-hash]
**Branch**: {{TICKET_PREFIX}}-XXX-description
**Implementation:**
- [x] Feature implemented
- [x] Tests passing
- [x] Lint passing
**Verification:**
{{CI_VALIDATE_COMMAND}}
# Output: All checks passed
Staging/UAT Evidence Template
**Staging Evidence**
**Environment**: {{STAGING_ENV_NAME}}
**URL**: {{STAGING_URL}}
**Validation Steps:**
1. Deployed to staging: [timestamp]
2. Smoke test passed: [yes/no]
3. Feature verified: [description]
**UAT Status:** [Passed/Pending/N/A]
If N/A, reason: [e.g., "Dev tooling only - no user-facing changes"]
Done Evidence Template
**Done Evidence**
**PR Merged**: https://github.com/{{ORG_NAME}}/{{REPO_NAME}}/pull/XXX
**Merge Commit**: [hash]
**Final Checklist:**
- [x] All acceptance criteria met
- [x] Documentation updated (if applicable)
- [x] No regressions detected
Acceptance Criteria Parsing
When reading issue descriptions, extract ACs:
## Acceptance Criteria
- [ ] User can perform action X
- [ ] System responds with Y
- [ ] Error handling for Z
Convert to testable checklist for verification.
Status Workflow
Backlog -> Ready -> In Progress -> Testing -> Ready for Review -> Done
GitHub-Linear Auto-Sync
Tickets referenced in commit messages (e.g., [{{TICKET_PREFIX}}-123]) automatically move to Done when the PR merges. Child stories not referenced in any commit message must be manually closed after merge.
Best practice: Reference Feature-level tickets in commit messages. After merge, manually close orphaned child stories that were not referenced.
Status Update Guidelines
| From | To | When |
|---|---|---|
| Backlog | Ready | Sprint planning |
| Ready | In Progress | Work starts |
| In Progress | Testing | PR created |
| Testing | Ready for Review | Tests pass, UAT complete |
| Ready for Review | Done | POPM approval or auto-sync via PR |
UUID Handling
Most ticket systems use UUIDs internally. When working with APIs:
// Issue identifiers (human-readable)
const issueId = "{{TICKET_PREFIX}}-459";
// UUIDs (API operations)
const uuid = "ef6a5fa0-2b46-417f-8266-dea2d187b10a";
// Get UUID from identifier via API
// Returns issue object with .id property containing UUID
Common Operations
Link PR to Issue
PRs are automatically linked when:
- Branch name contains
{{TICKET_PREFIX}}-XXX - PR title contains
[{{TICKET_PREFIX}}-XXX]
Create Sub-Issue
create_issue({
title: "Sub-task description",
team: "{{PROJECT_TEAM_NAME}}",
parentId: "parent-issue-uuid",
})
Query by Label
list_issues({
label: "sprint-1",
team: "{{PROJECT_TEAM_NAME}}",
})
Authoritative References
- Agent Workflow SOP:
docs/sop/AGENT_WORKFLOW_SOP.md - CONTRIBUTING.md: Workflow documentation