Managing Assets - Workunit

Overview

Assets are the building blocks of your project's context system. They represent the products you're building, the systems you're working with, the people on your team, and the knowledge your AI assistants need to be effective. By organizing and linking assets to workunits, you create a rich context graph that helps both humans and AI understand your project's structure.

This guide will teach you how to create, organize, and leverage assets to maximize context preservation and team productivity.

What Are Assets?

Assets represent the tangible and intangible resources in your project ecosystem. When you link assets to workunits, AI models automatically receive context about what systems they're working with, who's involved, what products are affected, and what knowledge is relevant.

Four Asset Types

Workunit provides four asset types, each serving a specific purpose in your project's context graph:

Knowledge

Documentation, patterns, standards, and institutional knowledge that AI models need to understand. Examples: API documentation, coding standards, architecture decision records, onboarding guides.

People

Team members, stakeholders, and AI assistants working on or affected by the project. Examples: developers, designers, product managers, customers, AI models (Claude, GPT, Gemini).

Product

Applications, features, or user-facing deliverables being built or modified. Examples: mobile apps, web platforms, API products, feature modules, customer-facing tools.

System

Technical infrastructure, services, and tools that support your products. Examples: databases, APIs, authentication services, CI/CD pipelines, monitoring systems, third-party integrations.

Creating and Organizing Assets

Creating assets is straightforward, but thoughtful organization makes them more valuable over time. Follow these guidelines to build a useful asset library.

Creating Your First Asset

To create an asset, navigate to the Assets page and click 'New Asset'. You'll need to provide:

Name (Required)

Clear, descriptive name for the asset. Be specific enough to distinguish similar assets.

Good examples:

"PostgreSQL Production Database"

"API Authentication System"

"React Component Library Documentation"

Type (Required)

Choose the asset type that best matches what you're creating: Knowledge, People, Product, or System.

Description (Optional but Recommended)

Brief description of the asset's purpose, scope, or key characteristics. This helps AI models understand when to reference this asset.

Example: "Primary PostgreSQL database for production environment. Stores user data, workunit records, and task information. Connection handled via SQLC."

URL (Optional)

Link to relevant documentation, repository, service dashboard, or profile. Makes it easy for team members and AI to find more information.

Example: "https://github.com/yourorg/api-docs" or "https://dashboard.stripe.com"

Naming Conventions

Consistent naming makes assets easier to find and understand. Consider these patterns:

For Systems: Include Environment or Scope

• "PostgreSQL Production Database"

• "Stripe Payment API (Production)"

• "Redis Cache (Staging)"

• "GitHub Actions CI/CD"

For Products: Use Official Product Names

• "Workunit Platform"

• "Mobile App - iOS"

• "Admin Dashboard"

• "Public API v2"

For Knowledge: Indicate Content Type

• "API Integration Guide"

• "Go Coding Standards"

• "Security Best Practices"

• "Deployment Runbook"

For People: Use Full Names or Roles

• "Sarah Chen (Lead Engineer)"

• "Product Management Team"

• "Claude AI Assistant"

• "External Security Auditor"

Organization Strategies

As your asset library grows, organization becomes critical. Use these strategies to maintain clarity:

Start with Core Assets

Create assets for your most frequently referenced resources first. Don't try to document everything upfront—let your asset library grow organically as you create workunits.

Group by Domain or Project

If you have multiple products or distinct systems, use prefixes or naming conventions to group related assets. For example, "Payment - Stripe API", "Payment - Database", "Payment - Documentation".

Keep Descriptions Current

Update asset descriptions when systems change, people change roles, or documentation moves. Stale descriptions reduce the value of asset links.

Archive Obsolete Assets

When systems are decommissioned or documents are deprecated, archive the assets rather than deleting them. This preserves historical context for old workunits.

Linking Assets to Workunits

The real power of assets comes from linking them to workunits. When you link assets, AI models automatically understand what systems they're working with, who's involved, what products are affected, and what knowledge they should reference.

How to Link Assets

You can link assets to workunits in two ways:

1. When Creating or Editing a Workunit

In the workunit form, use the "Linked Assets" section to search for and select relevant assets. This is the most common approach.

Tip: You can link multiple assets at once. Think about all the systems, people, products, and knowledge relevant to this workunit.

2. Via AI Assistant Commands

AI models can link assets programmatically using MCP calls. This is useful when AI discovers relevant assets during work.

"Link the PostgreSQL database asset to this workunit"

When to Link Assets

Link assets when they're directly relevant to the workunit. Over-linking creates noise; under-linking loses context. Use these guidelines:

Link Systems When:

• The workunit modifies or depends on the system
• Configuration changes affect the system
• Performance or reliability concerns involve the system
• Integration or API usage requires system knowledge

Link Products When:

• The workunit adds features to the product
• User experience changes affect the product
• Product-level architecture decisions are involved
• Cross-product integration is required

Link People When:

• The person is directly working on the workunit
• Their approval or review is required
• They're a stakeholder who needs updates
• Their expertise is relevant to decisions

Link Knowledge When:

• The documentation contains required patterns or standards
• Compliance or security guidelines must be followed
• Architecture decisions reference the knowledge
• New team members need the context for onboarding

How AI Uses Asset Links

When AI models query a workunit via MCP, they receive all linked asset information automatically. This provides rich context without you needing to explain:

Example: Payment Integration Workunit

Linked Assets:

• System: "Stripe Payment API (Production)"
• System: "PostgreSQL Production Database"
• Product: "E-commerce Platform"
• Knowledge: "PCI Compliance Guidelines"
• People: "Sarah Chen (Lead Engineer)"
• People: "Security Team"

What AI Understands Automatically:

• This involves Stripe integration (System asset provides API details)
• Database schema changes may be needed (System asset)
• E-commerce product will be affected (Product asset)
• PCI compliance must be considered (Knowledge asset)
• Sarah is the technical lead (People asset)
• Security review required (People asset)

You to Claude:

"Get workunit 'Stripe Payment Integration' and review the implementation plan"

Claude's Response (with asset context):

"I see this integrates Stripe into your e-commerce platform. Given the PCI compliance requirements and security team involvement, I recommend focusing on webhook signature verification and ensuring all payment data flows through Stripe's secure APIs rather than your database..."

Pro Tip: Asset Links as Documentation

Well-linked assets act as living documentation. When systems change or team members rotate, asset links ensure AI models always have current context without requiring you to update every workunit description.

Asset Relationships and Dependencies

Assets rarely exist in isolation. Understanding and documenting relationships between assets creates a powerful context graph that helps teams and AI navigate complex systems.

Understanding Relationships

Common asset relationships include:

System Dependencies

One system depends on another system functioning correctly.

Example: "API Server" depends on "PostgreSQL Database" and "Redis Cache"

Product-System Relationships

Products are built on or use specific systems.

Example: "Mobile App" uses "REST API v2" and "Firebase Push Notifications"

Knowledge-System Associations

Documentation relates to specific systems or products.

Example: "API Integration Guide" documents "REST API v2"

People-Domain Expertise

Team members have expertise with specific systems or products.

Example: "Sarah Chen" is the expert for "PostgreSQL Database" and "API Server"

Managing Dependencies

Document dependencies through asset descriptions and workunit links. This helps AI understand impact and sequencing:

Document in Asset Descriptions

Include key dependencies in the asset's description field.

API Server (System Asset)

"Depends on: PostgreSQL Database, Redis Cache, Stripe API. Used by: Mobile App, Web Dashboard, Admin Portal."

Link Related Assets to Workunits

When a workunit affects one system, link dependent systems too so AI understands potential impact.

Use Workunit Success Criteria

Document dependency considerations in success criteria.

Example: "Database migration completes successfully. API server integration tests pass. Redis cache invalidation works correctly."

Best Practices

Follow these best practices to build and maintain a valuable asset library that enhances both human and AI productivity:

Start Simple, Grow Organically

• Begin with 5-10 core assets: Your most critical systems, primary product, key documentation, and active team members
• Create assets as needed: Don't build a comprehensive asset library upfront. Add assets when you create workunits that need them
• Iterate on descriptions: Start with basic descriptions, refine them as you learn what context AI models need
• Follow your workflow: If you're constantly explaining the same system to AI, create an asset for it

Maintain Consistent Naming

• Use official names: Match asset names to how your team refers to systems and products in conversation
• Be specific about environments: "Production Database" vs "Staging Database" prevents confusion
• Avoid abbreviations: Unless they're universally understood by your team, spell out full names
• Update names when they change: If your team renames a product or system, update the asset name to match

Regular Maintenance and Cleanup

• Review quarterly: Every few months, review your asset list for outdated information or duplicate entries
• Archive don't delete: When systems are retired, archive assets to preserve historical context for old workunits
• Update URLs: Keep documentation links current. Broken links reduce asset value
• Consolidate duplicates: If you find multiple assets for the same thing, consolidate them and update workunit links
• Delegate to AI: Ask AI models to help identify outdated or inconsistent assets based on workunit patterns

Next Steps

Ready to build your asset library? Here's where to go next:

Create Your First Asset

Start building your asset library with your core systems, products, and team members

Quick Start Guide

Learn how to create workunits and link assets for maximum context

Core Concepts

Understand how assets, workunits, and tasks work together

AI Features

See how AI models use asset links to provide better assistance

Questions About Assets?

Join our community or check the documentation for more guidance on organizing your project context.

Documentation Community Discussions