Team Collaboration Guide

Learn how to collaborate effectively with both human team members and AI assistants on Workunit. Share context, preserve decisions, and build together without losing the thread.

Last updated: December 2025

Overview

Workunit is designed for modern teams that collaborate with both humans and AI. Whether you're a solo developer working with multiple AI models or a small team coordinating across time zones, Workunit preserves context so everyone—human and AI—stays aligned without endless catch-up meetings or re-explaining work.

Workunit enables:
  • • AI as first-class team members with full context and decision-making visibility
  • • Seamless handoffs between team members without context loss
  • • Asynchronous collaboration where work history and reasoning are always visible
  • • Trail-of-thought documentation that explains why, not just what

AI as Team Member

The most transformative aspect of Workunit is treating AI models as genuine team members, not just tools. This means AI assistants have the same visibility into project context, can contribute insights, and preserve their reasoning for the benefit of both humans and other AI models.

The Philosophy: AI with Agency, Human Control

Workunit is built on a specific philosophy about human-AI collaboration:

AI Has Context and Agency
AI models aren't passive tools that require constant direction. They have full access to project context—problem statements, task history, decisions made—so they can make informed suggestions, take initiative on well-defined tasks, and reason about next steps independently.
Humans Retain Final Control
While AI can work autonomously on tasks, humans always review, approve, and direct the overall strategy. AI proposes, humans dispose. This balance enables speed without sacrificing oversight or accountability.
Preserve the "Why"
The most valuable output from AI isn't just code or tasks completed—it's the reasoning behind decisions. Workunit captures this through AI context writing, creating a permanent record of why choices were made, what alternatives were considered, and what was learned.
No Context Lost, Ever
When you or another team member picks up work later—whether hours or months later—all the context is there. No searching through chat logs or trying to remember decisions. The workunit is the single source of truth.

Best Practices for Working with AI Team Members

These practices help you get the most value from AI collaboration:

1. Start with Clear Problem Statements
AI works best when it understands the problem deeply, not just the solution you want. Write detailed problem statements that explain the why, constraints, and success criteria. This enables AI to reason about trade-offs and suggest alternatives.
Good: "Users abandon checkout because payment fails silently. Need robust error handling with clear user feedback and automatic retry logic for transient failures."

Poor: "Fix payment errors."
2. Ask AI to Document Decisions
After AI completes significant work, ask it to update the workunit AI context with what it learned, decisions made, and patterns discovered. This creates institutional knowledge that benefits future work.
"After implementing the auth system, update the workunit with technical decisions (JWT vs sessions), libraries used, security patterns applied, and any gotchas you encountered."
3. Use AI for Different Phases
Leverage different AI models for their strengths. Use Claude for planning and architecture, GPT for rapid implementation, Gemini for analysis and optimization. Each model reads the shared context and builds on previous work.
Learn more about multi-model workflows →
4. Review AI Work Like Human Contributions
Treat AI output the same way you'd treat code from a junior developer: review thoroughly, ask questions when reasoning isn't clear, request changes when needed. AI is a collaborator, not an oracle.
5. Keep Tasks Focused and Bounded
AI excels at well-defined tasks with clear scope. Break large features into focused tasks that can be completed in a single session. This makes it easier to review, validate, and integrate AI work.

Practical Human-AI Workflows

Here are proven patterns for effective human-AI collaboration:

Pattern 1: Human Plans, AI Executes
H
You: Create workunit with problem, success criteria, high-level tasks
Define what needs to be built and why. Outline major milestones.
A
AI: Break down into detailed implementation tasks, identify dependencies
AI reads your plan, adds granular tasks, documents approach in AI context.
H
You: Review and approve AI's task breakdown
Adjust priorities, modify scope, clarify requirements.
A
AI: Implement tasks, update status, document decisions
Execute approved tasks, write AI context with implementation notes.
H
You: Review completed work, test, merge to production
Final review ensures quality and alignment with requirements.
Pattern 2: AI Pair Programming
Work interactively with AI on complex problems, alternating between human and AI contributions in real-time.
You: "I'm implementing user search. Start with the database query."
AI: Implements query, marks task in progress, explains indexing strategy.
You: Review query, request pagination support.
AI: Adds pagination, updates AI context with approach.
You: Build UI components using AI's backend work.
AI: Reviews UI integration, suggests optimizations.
Pattern 3: Multi-Specialist AI Team
Use multiple AI models as domain specialists, each contributing their expertise to the same workunit.
You: Create workunit for API redesign.
Claude: Designs architecture, documents patterns, creates task breakdown.
GPT: Implements endpoints and tests based on Claude's design.
Gemini: Analyzes performance, suggests query optimizations.
Claude: Reviews security implications of changes.
You: Review all AI contributions, approve for deployment.

Human Team Collaboration

While AI collaboration is transformative, Workunit is fundamentally designed for small human teams. The same context preservation that makes AI collaboration seamless also enables effortless human collaboration across time zones, schedules, and work styles. Projects group related workunits together, providing organizational structure for collaborative work.

Sharing Projects, Workunits, and Assets

All projects, workunits, and assets within an organization are automatically visible to all organization members. There's no complex permission system—everyone on your team has full context because small teams work best with full transparency.

Automatic Visibility
When you create a project or workunit, your entire team sees it immediately. No sharing step, no access requests, no confusion about who can see what. This is intentional—small teams benefit from transparency, not silos.
Projects Organize Team Work
Projects group related workunits together, making it easy for team members to see all work toward a common goal. When you create workunits within a project, the team understands how individual work fits into the bigger picture.
Shared AI Context
AI context written by one team member's AI assistant is visible to all team members and their AI assistants. This creates organizational knowledge that compounds over time—every decision documented, every pattern preserved, every gotcha recorded for the team's benefit.
Asset Relationships
Link workunits to shared assets (products, systems, people, knowledge) so everyone understands dependencies. When Sara works on the API server, she sees all related workunits. When Tom references the same system, he gets the full context.

Organization Management

Organizations are the container for your team's work. Create one organization for your company or project, invite your team members, and start collaborating.

Your Personal Organization
When you join Workunit, we automatically create a "Personal Organization" for you (unless you were invited to an existing organization). This gives you immediate access to all features and provides a foundation for future growth. You can rename your organization anytime to reflect your team or company name as you scale.
Navigate to Settings → Organization to rename or manage your organization.
Inviting Team Members
Invite team members by entering their email addresses in your organization settings. They'll receive an invitation email with instructions to join your organization with full access to all workunits and assets.
Tip: Invited members must verify their email address before accessing the organization.
Managing Members
View all organization members, see their activity, and remove members who leave the team. Member management is straightforward—everyone is equal, there are no complicated role hierarchies.

Roles and Permissions

Workunit uses a role-based permission system with three levels: Owner, Admin, and Member. Each role balances access with responsibility:

Organization Owner
  • • Manages organization settings and billing
  • • Invites and removes members with any role
  • • Changes member roles (including promoting to owner)
  • • Full access to all workunits, tasks, and assets
  • • Can delete the organization
Organization Admin
  • • Invites and removes members (cannot remove owners/admins)
  • • Changes member roles (up to admin level)
  • • Manages organization profile and preferences
  • • Full access to all workunits, tasks, and assets
  • • Views subscription info (cannot modify billing)
Organization Member
  • • Full access to all workunits, tasks, and assets
  • • Can create, edit, and complete workunits
  • • Can create and manage assets
  • • Cannot manage organization settings or billing
Philosophy: Simple Roles, Full Transparency
Workunit's role system balances access control with team transparency. All roles have full access to workunits and assets because context-sharing is essential for effective collaboration. The role differences focus on administrative capabilities—who manages settings, billing, and team membership—rather than limiting access to work.

Context Preservation Across Team

The real power of Workunit for teams isn't just task management—it's preserving the context and reasoning that makes projects successful. When team members pick up work from each other, they get the full story: why decisions were made, what was tried, what failed, what succeeded.

How Context Flows Across Your Team

Workunit-Level Context
Every workunit has a problem statement, success criteria, and AI context that explain the what and why. When any team member opens the workunit, they immediately understand the goal, constraints, and current approach.
Task-Level Progress
Tasks show who worked on them, when they were completed, and current status. Team members can see at a glance what's done, what's in progress, and what's available to pick up.
AI Context as Team Memory
AI context serves as institutional memory. When Sara's AI documents a security pattern while implementing auth, Tom's AI can read that context later and apply the same pattern to a different feature. The team's knowledge compounds automatically.
Asset Relationships
Linking workunits to assets (systems, products, people, knowledge) creates a web of context. When you view an asset, you see all related workunits. This prevents duplicate work and reveals cross-cutting concerns.

Trail-of-Thought Documentation

Traditional documentation explains what the code does. Trail-of-thought documentation explains why decisions were made, what alternatives were considered, and what was learned. This is invaluable for team continuity.

Example: Authentication Implementation
AI Context Written During Implementation:

Technical Decision: JWT vs Sessions

Chose JWT tokens over session-based auth for horizontal scaling. Our deployment uses multiple web servers behind a load balancer, and session state would require Redis or sticky sessions.

Token Expiry: 24 Hours

Balanced security (reasonable expiry) with UX (users don't re-login constantly). Considered 1-hour expiry with refresh tokens, but added complexity wasn't justified for our threat model.

Password Hashing: bcrypt cost=12

Increased from default cost=10 after reviewing OWASP guidelines. Measured ~200ms hashing time on production hardware, acceptable for registration/login flows.

Gotcha: Token Refresh Timing

Initial implementation had race condition when token expired during API call. Fixed by checking expiry before requests and preemptively refreshing within 5-minute window.

Result: When Tom picks up "Add OAuth support" three months later, he reads this context and understands the authentication architecture, security considerations, and known edge cases. He doesn't repeat Sara's research or make conflicting decisions.

Seamless Handoffs Between Team Members

With context properly preserved, team members can hand off work with minimal synchronous communication:

Scenario: Timezone Handoff (Sara → Tom)
10:00 AM PST - Sara starts: Creates workunit for payment integration, defines problem and success criteria, asks Claude to create task breakdown.
2:00 PM PST - Sara progress: Implements Stripe API client, marks task complete, AI writes context about error handling approach.
5:00 PM PST - Sara ends day: Marks "webhook processing" task as in progress, asks AI to document current implementation and next steps in AI context.
9:00 AM CET - Tom starts (Sara asleep): Opens workunit, reads problem statement, reviews completed tasks, reads AI context to understand Sara's approach.
9:15 AM CET - Tom continues: Picks up webhook task where Sara left off, completes it using patterns from AI context, marks complete, AI documents completion.
12:00 PM CET - Tom continues: Starts testing task, finds issue with Sara's error handling, fixes it, AI documents the bug and fix in context.
10:00 AM PST - Sara returns: Sees Tom's progress, reads AI context about the bug fix, learns from Tom's improvement, continues with next task.
Total synchronous communication needed: Zero. Both team members worked effectively by reading and writing to shared context.

Communication Patterns

Workunit reduces the need for constant communication by making work and reasoning visible. However, smart communication patterns make collaboration even more effective.

Asynchronous Collaboration Best Practices

Write Context as You Work
Don't wait until a session ends to document decisions. Update AI context throughout the day as you make decisions, discover patterns, or encounter gotchas. This makes your reasoning immediately available to teammates in other timezones.
Clear Task Status
Update task status immediately when you start, block, or complete work. This prevents duplicate effort when teammates check workunit status. Use "In Progress" to claim tasks, "Blocked" to signal help needed, "Done" when complete.
Document Blockers Clearly
When blocked, update AI context with what you tried, why it didn't work, and what you need to proceed. This gives teammates full context to either unblock you or work around the issue.
End-of-Day Context Updates
Before signing off, spend 5 minutes updating AI context with where you stopped and what should happen next. This creates a smooth handoff point for teammates or your future self.

Status Updates and Progress Visibility

With proper context preservation, status updates become trivial:

Ask AI to Generate Status Updates
Instead of manually writing status reports, ask your AI assistant to generate them from workunit context:
To your AI:
"Generate a status summary for workunit 'API v2 Migration' - include completed tasks, current progress, blockers, and next steps"

AI generates:

API v2 Migration - Status Update

Completed: Database schema migration (5 tasks), API endpoint migration (8 of 12 tasks), authentication refactor

In Progress: Payment integration testing (Sara), Webhook migration (Tom)

Blocked: Email service migration waiting for vendor API access

Next: Complete remaining 4 endpoint migrations, then deploy to staging

Weekly Team Summaries
Use AI to generate weekly summaries across all active workunits for team standups or stakeholder updates. The AI reads all workunit context and produces comprehensive summaries in seconds.
Visual Progress Tracking
The workunit dashboard shows all active work at a glance. Use tags to organize by project, filter by status, and see team-wide progress without asking anyone "what's your status?"

Next Steps

Ready to collaborate effectively with your team and AI assistants?

Organization Setup

Create your organization, invite team members, and configure collaboration settings

AI Features Guide

Deep dive into multi-LLM workflows, AI context writing, and intelligent collaboration

Quick Start Guide

Create your first workunit and connect AI assistants in 10 minutes

Asset Management

Track products, systems, people, and knowledge to preserve team context

Questions About Team Collaboration?

We're here to help you build effective collaboration patterns for your team.

DocumentationCommunity Discussions