Items and Task Items

Items are the foundational building blocks of a Statement of Work, with Task Items being a specific type of item that represents actionable work to be accomplished within a project. The platform supports different item types to organize work at various levels of detail.

Overview

Items exist within Statements of Work (SOWs) and cannot be created independently. Each SOW can contain multiple items of different types that collectively define the complete scope of deliverables.

Item Types

The platform supports two primary item types:

Requirements (🔷)

High-level work organization items that structure and contain other work items:

• Purpose: Define broad work packages and deliverable categories
• Visual: Blue styling with diamond icon (🔷)
• Contains: Other requirements, task items, milestones, and deliverables
• Testing: Cannot have direct tests; tests belong to child task items
• Status: Aggregated from child items

Task Items (📋)

Specific, actionable work items with clear deliverables and testable outcomes:

• Purpose: Define specific work that can be tested and verified
• Visual: Green styling with clipboard icon (📋)
• Contains: Other task items (sub-tasks)
• Testing: Can have acceptance criteria and tests
• Status: Based on direct test results

How Items Structure Work

Items provide hierarchical organization to a Statement of Work by:

• Breaking down complex deliverables into manageable, testable units
• Establishing clear relationships between different levels of work
• Separating high-level organization (requirements) from specific execution (task items)
• Linking tests to the appropriate level of granularity
• Enabling progress tracking at both strategic and tactical levels

This approach ensures that every aspect of the project scope is clearly defined and testable, while maintaining logical separation between planning and execution.

The Item Model

Hierarchical Rules

The item type system enforces logical hierarchy rules:

• Requirements can contain:

  • Other requirements (sub-requirements)
  • Task items
  • Future item types (milestones, deliverables)

• Task Items can contain:

  • Other task items (sub-tasks)
  • Cannot contain requirements (maintains logical flow from planning to execution)

Creating Items

Via the UI

1. Navigate to a Statement of Work
2. Click the "Add Item" button
3. Choose the item type:
   • Requirement: For high-level work organization
   • Task Item: For specific, testable work
4. Fill in the required information:
   • Title
   • Description
   • Parent item (if applicable)
5. Click "Save Item"

The UI will enforce hierarchy rules - for example, you cannot create a requirement under a task item.

Via the API

// Create a new Requirement
const newRequirement = await apiClient.sows.items.create(
  "sow_id", 
  {
    title: "User Management System",
    description: "Complete user authentication and authorization system",
    type: "requirement",
    parentId: null, // Top-level requirement
  }
);

// Create a Task Item under the requirement
const newTaskItem = await apiClient.sows.items.create(
  "sow_id", 
  {
    title: "Implement OAuth Integration",
    description: "Add OAuth support for Google and GitHub",
    type: "task_item",
    parentId: newRequirement.id,
  }
);

Example: Complete Project Structure

Here's how requirements and task items work together to organize a project:

🔷 User Management System (requirement)
  ├── 📋 Implement user registration (task_item)
  ├── 📋 Add email verification (task_item)
  └── 🔷 Authentication Features (requirement)
      ├── 📋 OAuth integration (task_item)
      ├── 📋 Two-factor authentication (task_item)
      └── 📋 Password reset flow (task_item)

🔷 Payment Processing (requirement)
  ├── 📋 Stripe integration (task_item)
  ├── 📋 Invoice generation (task_item)
  └── 📋 Subscription management (task_item)

Hierarchical Organization

Items support unlimited nesting with type-aware constraints:

• Requirements organize broad work areas and can contain other requirements or task items
• Task Items define specific work and can be broken into sub-tasks
• Mixed Hierarchies: Requirements can contain task items, which can have sub-tasks

To create effective hierarchical structures:

1. Start with high-level requirements to organize major work areas
2. Break requirements into specific task items
3. Subdivide complex task items into manageable sub-tasks
4. Use the drag-and-drop interface to reorganize items visually

Ordering Items

Items can be reordered to reflect priority, sequence, or logical flow:

1. In the UI, use drag-and-drop to reorder items within their parent
2. Through the API, update the sortOrder field

// Reorder Items
await apiClient.sows.items.reorder(
  "sow_id", 
  "parent_id", // null for top-level items
  ["item_id_1", "item_id_2", "item_id_3"] // Array of item IDs in desired order
);

Relationship to Statements of Work

Understanding the relationship between Items and their parent Statement of Work:

1. Containment: All items belong to a specific Statement of Work
2. Completeness: The collection of requirements and task items defines the complete scope
3. Shared Context: Items inherit context from their parent SOW (project goals, timelines)
4. Versioning: When a SOW is versioned, all its items are also versioned

Managing Tests and Criteria

Testing behavior differs by item type:

• Requirements: Cannot have direct tests; status is aggregated from child task items
• Task Items: Can have acceptance criteria and tests for verification

Each Task Item should have one or more criteria that define completion. Each criterion must have a binary outcome (pass/fail) with no ambiguity. See the Tests documentation for details.

Dependencies Between Items

Items can have dependencies on other items or external systems. See the Dependencies documentation for details on:

• Internal dependencies (item-to-item relationships)
• External dependencies (third-party systems, vendors)
• Risk management and SLA tracking
• Escalation workflows

Best Practices

For Requirements

• High-Level Focus: Organize broad work areas, not specific implementation details
• Logical Grouping: Group related task items under common themes
• Balanced Scope: Neither too broad (entire project) nor too narrow (single feature)
• Clear Ownership: Assign to stakeholders responsible for the work area

For Task Items

• Be Specific: Each task item should represent a single, clear piece of work
• Action-Oriented: Frame as work to be completed, not just descriptions
• Testable Design: Ensure each item can be verified through testing
• Appropriate Granularity: Detailed enough to be actionable, not so detailed as to be micromanagement

For Both Types

• Consistent Naming: Use clear, descriptive titles
• Complete Information: Include all relevant details in descriptions
• Logical Hierarchy: Structure items to reflect natural work relationships

API Reference

Query Parameters

• type: Filter items by type (requirement or task_item)
• parentId: Filter items by parent (use null for top-level items)

For complete API details, refer to the API Reference.