| name | orca-linear-setup |
| description | Guide users through setting up Linear for ORCA Framework, including states, labels, agent guidance, permissions, smoke tests, and opt-out mapping. |
ORCA Framework Linear Setup
What This Skill Is
A setup workflow for making Linear usable as ORCA Framework's default coordination layer.
Trigger
Use when a user asks to set up Linear, adopt ORCA Framework in a Linear workspace, configure agent guidance, validate Linear readiness, or define an opt-out record.
Do Not Trigger
Do not use when a project has explicitly opted out and the user is not asking about Linear setup.
Required Inputs
- Setup scope: workspace, team, project, or opt-out record
- Coordination preference: Linear-first or opt-out
Optional Inputs
- Existing Linear states
- Existing labels
- Agent connector details
- Permission policy
- Repository or product name
- Smoke-test issue ID
Exact Workflow
- Confirm Linear-first or opt-out mode.
- If Linear-first, identify setup scope and target workspace, team, or project.
- Inventory available states and map them to ORCA Framework gates.
- Inventory labels and recommend missing routing, risk, platform, QA, and approval labels.
- Prepare guidance from
docs/linear-guidance.md for workspace, team, or project installation.
- Define agent permissions for reading, commenting, state changes, label changes, assignment, and delegation.
- Create or recommend a smoke-test issue.
- Verify access only when tools are available; otherwise mark verification as manual.
- Record setup status using
templates/linear-setup-checklist.md.
- If opt-out, map ORCA Framework issue, project, state, comment, and artifact concepts to the chosen record.
Expected Outputs
- Linear setup checklist
- State mapping
- Label recommendation
- Agent guidance placement
- Permission policy
- Smoke-test issue instructions or result
- Opt-out system mapping when applicable
Quality Bar
The setup should let a new agent pick up an issue, know which ORCA Framework gate it is in, post the right comment, and avoid unsafe transitions.
Common Failure Modes
- Treating Linear OAuth as configured without verification.
- Installing guidance too broadly before testing on a project.
- Letting agents move issues to done without evidence.
- Creating labels that do not map to real routing decisions.
- Forgetting that the user can opt out of Linear.
Relationship To Other ORCA Framework Skills And Commands
Feeds orca-linear-intake, orca-linear-core, orca-linear-planner, orca-linear-qa, and orca-linear-release.
