Joan Workflow

Joan is a workspace-based knowledge and task management system for AI-assisted development. This skill covers when and how to use Joan's core concepts.

Core Concepts

Workspaces

Workspaces are the top-level organizational unit in Joan. Each workspace contains:

• Pods: Versioned domain knowledge documents


• Todos: Tasks scoped to the workspace


• Plans: Implementation specs linked to todos


• Members: Team members with roles (admin, member)

Pods

Pods are versioned markdown documents containing domain knowledge. Use pods to:

• Document project architecture and design decisions


• Store domain-specific terminology and business rules


• Share knowledge across team members and AI assistants


• Maintain living documentation that evolves with the project

Pod lifecycle:

Create locally with joan pod create

Edit the markdown file in .joan/pods/

Push to server with joan pod push

Pull latest with joan pod pull

Todos

Todos are tasks scoped to a workspace. Use todos to:

• Track work items across team members


• Assign tasks and set priorities


• Link implementation plans to tasks

Todo workflow:

Create with joan todo create

List with joan todo list

Update status as work progresses

Archive when complete

Plans

Plans are implementation specs linked to todos. Use plans to:

• Document how a feature will be implemented


• Break down complex tasks into steps


• Share implementation approach with team

CLI Commands Reference

Project Initialization

joan init                    # Interactive workspace selection
joan init -w <workspace-id>  # Non-interactive with specific workspace
joan status                  # Show project and auth status

Pod Management

joan pod list               # List tracked pods
joan pod list --all         # List all workspace pods
joan pod add                # Add workspace pods to project
joan pod create             # Create new pod locally
joan pod pull               # Pull pods from server
joan pod push               # Push local pods to server
joan pod open               # Open pod in browser

Todo Management

joan todo list              # List todos for tracked pods
joan todo list --mine       # List todos assigned to me
joan todo create            # Create new todo
joan todo update <id>       # Update todo fields
joan todo archive <id>      # Archive completed todo

Plan Management

joan plan list <todo-id>    # List plans for a todo
joan plan create <todo-id>  # Create implementation plan
joan plan pull <todo-id>    # Pull plans from server
joan plan push <todo-id>    # Push plans to server

Context Generation

joan context claude         # Generate CLAUDE.md with Joan context

When to Use What

Starting a New Project

Run joan init to connect project to a workspace

Select pods relevant to the project domain

Run joan context claude to inject context into CLAUDE.md

Read the generated pod references before coding

Before Coding a Feature

Check if relevant pods exist: joan pod list --all

Add any missing pods: joan pod add

Pull latest: joan pod pull

Read pods to understand domain context

After Completing Work

Consider if learnings should become a pod

Update or create todos to reflect progress

Push any local changes: joan pod push and joan todo push

Documenting New Knowledge

Create a pod: joan pod create

Write domain knowledge in markdown

Push to share: joan pod push

Update CLAUDE.md context: joan context claude

MCP Integration

Joan provides an MCP server at with tools: - list_workspaces - List accessible workspaces - list_pods - List pods in a workspace - get_pod - Retrieve pod content The MCP server uses OAuth 2.1 authentication. Authenticate via the CLI first with joan auth login. ## Project Configuration Joan stores project config in .joan/config.yaml: __CODE_BLOCK_5__ Pods are stored locally in .joan/pods/ as markdown files. ## Best Practices ### Pod Authoring - Use clear, descriptive titles - Include context about when the knowledge applies - Keep pods focused on a single domain concept - Update pods when knowledge evolves - Reference related pods when helpful ### Todo Management - Create todos at the right granularity (not too big, not too small) - Link todos to relevant pods for context - Update status promptly to keep team informed - Archive completed todos to reduce noise ### Context Synchronization - Run joan context claude` after changing tracked pods

• Pull pods before starting significant work


• Push changes promptly to share with team