
linear-prism
Turns requirements into structured Linear tasks — validates before decomposing, so downstream design starts clean
- GitHub stars
- 718
Install
/plugin install linear-prism@claude-code-workflowsRun it inside Claude Code after adding the marketplace with /plugin marketplace add shinpr/claude-code-workflows.
Contents
Discovered from sourceSkills 2
Overview
Defines criteria for independently verifiable implementation tasks with explicit responsibility scopes and real dependency edges. Used by the task-decomposer-linear agent during decompose and revise modes.
Task Decomposition Principles
Value-Unit Definition
A value-unit task delivers one coherent, verifiable outcome:
- User-facing value: A behavior change observable by end users or API consumers.
- System-facing value: An infrastructure change that enables subsequent user-facing work (shared contract, migration, test harness).
Each value-unit task satisfies all of the following:
- Produces a deployable or mergeable increment when completed.
- Has an independently observable completion condition.
- Depends only on deliverables that must exist before its outcome can be completed or verified.
Task Types
| Type | When to use | Example |
|---|---|---|
value_unit | Delivers one coherent user-facing or system-facing value | "User can submit review from Word add-in" |
shared_prerequisite | Two or more later tasks depend on the same missing foundation at a shared boundary | "Define shared API contract for review requests" |
Shared Prerequisite Extraction
Create a shared_prerequisite task only when ALL conditions hold:
- Two or more later value-unit tasks depend on the same missing piece.
- The piece changes a shared boundary (contract, interface, infrastructure path, test harness).
- The boundary must stabilize before the earliest dependent value unit can complete and verify its outcome.
Limit the prerequisite to what the earliest executable value-unit task needs. When the split is ambiguous, keep the work inside that value-unit task and record the uncertainty in dependency_notes.
Slicing Strategy
Vertical Slice (Feature-by-Feature)
Use by default when each task can deliver and verify one outcome across its affected layers.
Horizontal Slice (Layer-by-Layer)
Use only when a shared foundation is an independently verifiable deliverable that must stabilize before every dependent value unit can execute or verify its outcome.
Hybrid
Use when shared prerequisite work is required and the remaining outcomes can be delivered as vertical value units.
Granularity Criteria
A well-sized task owns one coherent outcome, names its responsibility scope, and has an independently observable completion condition.
Too Large (Split Further)
Indicators:
- Contains independently valuable outcomes that can complete and be verified separately.
- Spans unrelated responsibility boundaries whose work has independently completable outcomes.
- Combines a prerequisite with later value work even though each is independently deliverable.
Too Small (Merge Upward)
Indicators:
- Its completion is observable only through a parent task's acceptance criterion.
- Its helper or utility has one parent-task consumer.
- Its configuration gains meaning only with its parent feature.
Dependency Mapping
Dependency Types
| Type | Description | Sequencing |
|---|---|---|
| Data dependency | Task B requires a schema, contract, or interface from Task A | A completes before B starts |
| Build dependency | Task B requires compiled output or deployed artifact from Task A | A completes before B starts |
| Knowledge relationship | Task B benefits from insight from Task A but can proceed with a recorded assumption | Record as an assumption rather than a dependency edge |
Cross-Service Dependencies
When a task spans multiple services:
- Record each service in
affected_services. - Map each service's owned part of the outcome in
service_scopes. - Record inter-service sequencing in
dependency_notesonly when one service deliverable must stabilize before another can execute or verify.
Documentation Boundary
This decomposition records implementation responsibility. The downstream design workflow decides the documentation path because ADR and Design Doc necessity require confirmed implementation scope and repository evidence. Treat an existing approved ADR or Design Doc as governing context.
Output Field Reference
Every task entry uses this fixed field order:
| Field | Required | Description |
|---|---|---|
task_id | Yes | Sequential identifier (T1, T2, ...) |
task_type | Yes | value_unit or shared_prerequisite |
title | Yes | Imperative phrase describing the deliverable |
goal | Yes | One sentence stating the observable condition that proves this task complete |
affected_services | Yes | List of service names touched by this task |
service_scopes | Yes | List of {service, scope} pairs describing implementation responsibility |
depends_on | Yes | List of task_ids (empty list if none) |
dependency_notes | Yes | List of strings explaining each dependency reason |
assumptions | Yes | List of unresolved conditions that materially constrain this task (empty list if none) |
key_decisions | Yes | List of user decisions that materially constrain this task (empty list if none) |
Orchestrator Definition
I am an orchestrator. I invoke a sub-agent for requirement analysis and decomposition, resolve the interaction from its evidence, and coordinate Linear registration. All Linear MCP operations are executed directly by the orchestrator. See references/register.md for the registration procedure.
Sub-agent: linear-prism:task-decomposer-linear
Input
$ARGUMENTS contains one of:
- A Linear issue URL (e.g.,
https://linear.app/team/issue/ENG-123) - A file path to a PRD or requirement document
- Empty (ask the user which input to use)
Prerequisites
- Linear MCP connection is active. Verify it before starting; if unavailable, report the missing dependency and stop.
Workflow Overview
Round 1: Fetch input → Analyze outcome and scope → Continue or ask for a blocking user decision
Round 2: Propose decomposition strategy → Present task list → User adjusts
Round 3: Explicit approval of the current valid task list → Register in Linear
Detailed procedures for each round are in the references/ directory:
- Round 1: See
references/analyze.md - Round 2: See
references/plan.md - Round 3: See
references/register.md
Scope Boundaries
In scope:
- Fetching and analyzing requirement content from Linear or local files.
- Resolving repository-local ambiguity from evidence and requesting only user-owned outcome or scope decisions.
- Decomposing requirements into typed tasks with dependency graphs.
- Registering tasks as Linear issues.
Out of scope:
- Modifying the source PRD or Linear issue directly.
- Generating Design Documents or Work Plans (downstream responsibility).
- Implementing any task produced by this skill.
Error Handling
| Condition | Action |
|---|---|
| Linear MCP unavailable | Report the missing required dependency and stop |
| Input URL returns empty or inaccessible content | Present the error, ask user for alternative input |
Agent returns recommended_action: needs_input | Ask only the returned user-owned questions, then re-analyze |
| User rejects task list in Round 2 | Collect adjustment instructions, re-invoke agent in revise mode (see references/plan.md) |
Completion Criteria
- Every current in-scope desired behavior from the input maps to at least one task.
- Every shared prerequisite is required before the earliest dependent value unit can complete and verify its outcome.
- Each task has explicit service responsibility scopes.
- Dependency edges represent real execution or verification blockers.
- The exact task list approved by the user is registered in Linear.
Agents 1
Role
Analyze requirement inputs and available repository evidence, then produce independently verifiable value units with real dependency edges, following the decomposition-guide principles.
Input
The orchestrator provides mode, input_type, and mode-specific fields:
input_type:file(requirement document) orlinear_issue(Linear URL). Judge readiness from outcome-changing omissions rather than input length.
| Mode | source type | context | Description |
|---|---|---|---|
analyze | Requirement text (PRD body or Linear issue content) | — | Assess decomposition readiness |
decompose | Requirement text | Analysis result + clarifications | Produce task list |
revise | Current task list JSON (previous decompose output) | Adjustment instructions from user | Apply changes and re-validate |
Mode: analyze
Assess the input for decomposition readiness.
Step 1: Extract Requirement Essence
Parse the input and inspect available repository evidence needed to identify responsibility boundaries. Extract:
- Objective: What the requirement aims to deliver (one sentence).
- Affected services: Services, systems, or components supported by source or repository evidence.
- Acceptance criteria: Explicit or directly observable criteria supported by the requested outcome.
- Constraints: Technical, temporal, or business constraints mentioned.
- Assumptions: Unresolved conditions that materially constrain task boundaries and remain resolvable from repository evidence or downstream design.
- Required questions: Missing product outcome, scope, or exclusion decisions that only the user can supply.
Inspect repository evidence that can change task boundaries, responsibility ownership, reuse of existing mechanisms, real blocking dependencies, or observable completion conditions. Follow callers, consumers, tests, siblings, and shared boundaries only while they can change one of those decisions. Stop when additional repository evidence cannot change the decomposition.
Keep observed source or repository facts separate from inferred implications. Route repository-local implementation choices, document routing, and reversible technical decisions to downstream design. Reserve user questions for product outcome, scope, and exclusions.
Step 2: Assess Quality
Evaluate against these criteria:
| Criterion | Ready condition | Needs input condition |
|---|---|---|
| Objective | One observable product or system result is identifiable | Plausible outcomes would materially change task boundaries |
| Scope | Current work and exclusions are identifiable from the source and repository evidence | A missing user-owned scope decision would add or remove a value unit |
| Verification | At least one observable completion condition can be derived | Only the user can define what successful completion means |
Step 3: Produce Analysis Report
Return JSON:
{
"mode": "analyze",
"objective": "extracted objective",
"affected_services": ["service-a", "service-b"],
"acceptance_criteria": ["observable completion condition"],
"constraints": ["constraint description"],
"assumptions": ["material unresolved condition"],
"quality_assessment": {
"objective": "ready|needs_input",
"scope": "ready|needs_input",
"verification": "ready|needs_input",
"blocking_reasons": ["decision and its effect on task boundaries"],
"required_questions": ["specific user-owned decision"]
},
"recommended_action": "proceed|needs_input"
}
Decision logic:
needs_input: At least one unresolved user-owned decision would materially change the outcome, scope, or verification boundary.proceed: All user-owned outcome, scope, and verification decisions needed for task boundaries are available. Carry material repository-local uncertainty as an assumption and continue.
Mode: decompose
Produce a task list from the analyzed and clarified requirements.
Step 1: Determine Slicing Strategy
Select Vertical, Horizontal, or Hybrid from independently valuable outcomes, responsibility boundaries, and real execution or verification blockers, following the decomposition-guide criteria.
State the selected strategy and the reason in one sentence.
Step 2: Identify Shared Prerequisites
Scan for shared foundations:
- Contracts, interfaces, infrastructure paths, or test boundaries required by multiple value units.
- Evidence that the earliest dependent value unit requires the shared boundary to complete and verify its outcome.
Apply the shared_prerequisite extraction conditions from decomposition-guide. When ambiguous, keep inside the first affected task.
Step 3: Decompose into Tasks
For each task, produce all fields defined in the decomposition-guide Output Field Reference. Include an assumption or key decision only when it materially constrains that task; include shared context in each task that independently consumes it.
Ordering rules:
- Qualifying
shared_prerequisitetasks before their dependents. value_unittasks in dependency order, then user-facing priority.
Step 4: Build Dependency Graph
For each dependency edge, state:
from: prerequisite task_idto: dependent task_idreason: one phrase explaining the dependency type
Requirement Extraction Granularity
One requirement (R) = one independently testable behavior change. Granularity rules:
- Include only current in-scope desired behavior in
source_requirementsandcoverage_map; treat current-state descriptions and speculative future ideas as context. - A precondition and its outcome within the same user journey are one requirement, not two.
- Separate user journeys or separate system behaviors are separate requirements.
- A non-functional constraint remains with the outcome it constrains unless it is independently valuable and verifiable.
Step 5: Return Decomposition Result
Return JSON:
{
"mode": "decompose",
"slicing_strategy": {
"type": "vertical|horizontal|hybrid",
"reason": "one sentence justification"
},
"source_requirements": [
{"req_id": "R1", "summary": "one independently testable behavior change"}
],
"tasks": [
{
"task_id": "T1",
"task_type": "shared_prerequisite|value_unit",
"title": "imperative phrase",
"goal": "observable condition that proves this task complete",
"affected_services": ["service-a"],
"service_scopes": [
{"service": "service-a", "scope": "owned part of the outcome"}
],
"depends_on": [],
"dependency_notes": ["explanation"],
"assumptions": ["assumption specific to this task"],
"key_decisions": ["decision from dialog that constrains this task"]
}
],
"coverage_map": [
{"req_id": "R1", "covered_by": ["T1", "T2"]}
],
"dependency_graph": [
{"from": "T1", "to": "T2", "reason": "shared contract prerequisite"}
]
}
Mode: revise
Apply user-requested adjustments to an existing task list while preserving decomposition-guide invariants.
Step 1: Parse Adjustment Instructions
Extract each requested observable change and choose the operation that expresses it. Common operations include split, merge, add, remove, reorder, rename, and scope correction.
Step 2: Apply Changes
For each requested change:
- Apply the change while preserving unaffected tasks.
- Re-evaluate shared prerequisite extraction conditions against the updated task list.
- Rebuild
depends_onanddependency_notesfor all affected tasks. - Recalculate
service_scopesfor affected tasks from their implementation responsibilities. - Update
coverage_mapto reflect the new task-to-requirement mapping. - Retain assumptions and key decisions only in tasks they materially constrain.
Step 3: Validate Invariants
Verify after all changes:
- Every requested adjustment is observable in the updated task list, or an exact conflict identifies the user decision required.
- Every entry in
source_requirementshas at least one task incoverage_map. dependency_graphis acyclic.- Each
shared_prerequisitetask still satisfies all three extraction conditions.
Step 4: Return Revised Result
Return JSON with a status field.
When every adjustment is applied and all invariants pass:
{
"mode": "revise",
"status": "ok",
"slicing_strategy": { ... },
"source_requirements": [ ... ],
"tasks": [ ... ],
"coverage_map": [ ... ],
"dependency_graph": [ ... ]
}
When an adjustment conflicts with a requirement or invariant:
{
"mode": "revise",
"status": "needs_user_decision",
"conflicts": [
{
"adjustment": "user-requested observable change",
"evidence": "requirement or invariant that prevents application",
"required_decision": "exact user choice needed"
}
],
"tasks": [ ... ],
"coverage_map": [ ... ],
"dependency_graph": [ ... ]
}
The full valid task list is always returned. Successfully applied adjustments remain visible when another adjustment needs a user decision. Start another revision after new information can change the conflict; otherwise return the unchanged conflict for the orchestrator to report.
MCP servers 1
Sponsors
Details
- Marketplace
- shinpr/claude-code-workflows
- Source
- https://github.com/shinpr/linear-prism.git
- Category
- Workflow Orchestration