bybren-llc/safe-agentic-workflow/linear-sop

Linear SOP Skill

Purpose

Guide consistent Linear ticket management. Provides evidence templates for the mandatory dev/staging/UAT evidence policy.

When This Skill Applies

• Creating new Linear issues
• Updating ticket status
• Attaching evidence to tickets
• Parsing acceptance criteria
• Working with UUIDs and issue IDs

Linear Operations (Manual Process)

Since Gemini CLI doesn't have native Linear integration, use the Linear web UI or CLI for these operations:

Reading Issues

# Via Linear Web UI
# Navigate to: https://linear.app/team/{{PROJECT_TEAM_NAME}}/issue/{{TICKET_PREFIX}}-XXX
 
# Or use Linear CLI if installed
linear issue view {{TICKET_PREFIX}}-XXX

Creating Issues

# Via Linear Web UI: Click "New Issue" or press C
# Or use Linear CLI:
linear issue create --title "feat(scope): description" --team {{PROJECT_TEAM_NAME}}

Updating Issues

# Via Linear Web UI: Open issue and update status
# Or use Linear CLI:
linear issue update {{TICKET_PREFIX}}-XXX --state "Done"

Adding Comments

# Via Linear Web UI: Open issue and add comment
# Or use Linear CLI:
linear issue comment {{TICKET_PREFIX}}-XXX "**Dev Evidence**\n\n..."

Program Structure

For work that spans many issues, Linear has objects above the issue. Use them; do not flatten a program into a flat list of tickets.

The Hierarchy

Initiative          the program (one per program)
  └── Project       a Unit of Work — one coherent outcome
       ├── Milestone    an AI-DLC phase: Inception, Construction, Operations
       └── Issue        a Story
            └── Sub-issue   a Mob Elaboration task (created during Inception, not before)

Prerequisite: labels must already exist

Program build-out assumes these label namespaces are pre-created in the workspace. Create them before building the program, not during:

• bolt:0 … bolt:N — which Bolt an issue belongs to
• agent:* — the lead role (must match an actual agent role defined for the project)

Labels are workspace-scoped in Linear — do not create team-scoped duplicates.

Streams

Linear sub-initiatives require an Enterprise plan. If your workspace has it, model program streams as sub-initiatives under the initiative. If it does not, encode the stream as project priority instead — highest-risk stream gets Urgent/High, follow-up stream gets Medium.

Building the Program (Manual Process)

# Create the initiative
# Linear Web UI: Initiatives → New initiative
 
# Add a project (Unit of Work) to the initiative
# Linear Web UI: Initiative → Add project
 
# Add the three AI-DLC phase milestones to each project
# Linear Web UI: Project → Milestones → New milestone
 
# Wire dependencies between issues
# Linear Web UI: Issue → Add relation → "Blocks" / "Blocked by"

Use relatedTo ("Related") for soft links that inform but do not block.

Wire so the enforcement lands before the thing it enforces — see the safe-ai-dlc skill for the four dependency-wiring heuristics.

Re-parenting existing issues

When a program absorbs tickets that already exist, update them into the project — never recreate them. Duplicates break traceability and split the evidence trail.

Evidence Policy (MUST)

Every issue requires evidence at each phase:

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:**
 
\`\`\`bash
yarn ci:validate
 
# Output: All checks passed
 
\`\`\`

Staging/UAT Evidence Template

**Staging Evidence**
 
**Environment**: Pop OS dev server
**URL**: http://pop-os:3000
 
**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:

const acceptanceCriteria = [
  { criterion: "User can perform action X", verified: false },
  { criterion: "System responds with Y", verified: false },
  { criterion: "Error handling for Z", verified: false },
];

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 weren't referenced.

Status Update Guidelines

UUID Handling

Linear uses 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 Linear web UI or API
// The issue URL contains the 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

Use Linear web UI: Click "Add sub-issue" on parent issue

Query by Label

Use Linear web UI filters:

1. Open team view
2. Click "Filter"
3. Select label (e.g., "sprint-1")

Reference

• Agent Workflow SOP: docs/sop/AGENT_WORKFLOW_SOP.md
• Linear Documentation: https://linear.app/docs
• CONTRIBUTING.md: Workflow documentation