Turns requirements into structured Linear tasks — validates before decomposing, so downstream design starts clean

GitHub stars
718

Install

/plugin install linear-prism@claude-code-workflows

Run it inside Claude Code after adding the marketplace with /plugin marketplace add shinpr/claude-code-workflows.

Contents

Discovered from source

Skills 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:

  1. Produces a deployable or mergeable increment when completed.
  2. Has an independently observable completion condition.
  3. Depends only on deliverables that must exist before its outcome can be completed or verified.

Task Types

TypeWhen to useExample
value_unitDelivers one coherent user-facing or system-facing value"User can submit review from Word add-in"
shared_prerequisiteTwo 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:

  1. Two or more later value-unit tasks depend on the same missing piece.
  2. The piece changes a shared boundary (contract, interface, infrastructure path, test harness).
  3. 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

TypeDescriptionSequencing
Data dependencyTask B requires a schema, contract, or interface from Task AA completes before B starts
Build dependencyTask B requires compiled output or deployed artifact from Task AA completes before B starts
Knowledge relationshipTask B benefits from insight from Task A but can proceed with a recorded assumptionRecord 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_notes only 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:

FieldRequiredDescription
task_idYesSequential identifier (T1, T2, ...)
task_typeYesvalue_unit or shared_prerequisite
titleYesImperative phrase describing the deliverable
goalYesOne sentence stating the observable condition that proves this task complete
affected_servicesYesList of service names touched by this task
service_scopesYesList of {service, scope} pairs describing implementation responsibility
depends_onYesList of task_ids (empty list if none)
dependency_notesYesList of strings explaining each dependency reason
assumptionsYesList of unresolved conditions that materially constrain this task (empty list if none)
key_decisionsYesList 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

ConditionAction
Linear MCP unavailableReport the missing required dependency and stop
Input URL returns empty or inaccessible contentPresent the error, ask user for alternative input
Agent returns recommended_action: needs_inputAsk only the returned user-owned questions, then re-analyze
User rejects task list in Round 2Collect 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) or linear_issue (Linear URL). Judge readiness from outcome-changing omissions rather than input length.
Modesource typecontextDescription
analyzeRequirement text (PRD body or Linear issue content)—Assess decomposition readiness
decomposeRequirement textAnalysis result + clarificationsProduce task list
reviseCurrent task list JSON (previous decompose output)Adjustment instructions from userApply 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:

CriterionReady conditionNeeds input condition
ObjectiveOne observable product or system result is identifiablePlausible outcomes would materially change task boundaries
ScopeCurrent work and exclusions are identifiable from the source and repository evidenceA missing user-owned scope decision would add or remove a value unit
VerificationAt least one observable completion condition can be derivedOnly 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:

  1. Qualifying shared_prerequisite tasks before their dependents.
  2. value_unit tasks in dependency order, then user-facing priority.

Step 4: Build Dependency Graph

For each dependency edge, state:

  • from: prerequisite task_id
  • to: dependent task_id
  • reason: 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_requirements and coverage_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:

  1. Apply the change while preserving unaffected tasks.
  2. Re-evaluate shared prerequisite extraction conditions against the updated task list.
  3. Rebuild depends_on and dependency_notes for all affected tasks.
  4. Recalculate service_scopes for affected tasks from their implementation responsibilities.
  5. Update coverage_map to reflect the new task-to-requirement mapping.
  6. 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_requirements has at least one task in coverage_map.
  • dependency_graph is acyclic.
  • Each shared_prerequisite task 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

More from shinpr/claude-code-workflows

All 7