joan-workflow_skill

Overview

This skill explains how to use Joan, a workspace-based knowledge and task management system for AI-assisted development. It focuses on workflows for workspaces, pods (versioned domain knowledge), todos, plans, and context synchronization. Use this skill when you need practical guidance for onboarding, daily use, or managing Joan resources via the CLI.

How this skill works

Joan organizes work into workspaces that contain pods, todos, plans, and members. Pods are versioned markdown documents that capture domain knowledge; todos are scoped tasks; plans are implementation specs linked to todos. The CLI provides commands to init projects, create and sync pods, manage todos and plans, and generate context artifacts like CLAUDE.md for downstream assistants.

When to use it

• Onboarding a new project or connecting a repo to an existing Joan workspace (joan init).
• Preparing to implement a feature: pull pods, read domain context, and create linked plans.
• Documenting learnings or decisions that should be shared with the team (create and push a pod).
• Tracking and assigning work with workspace-scoped todos and linking implementation plans.
• Synchronizing local project context with team knowledge before heavy development (joan context claude).

Best practices

• Initialize the project with joan init and select only the pods relevant to the repo.
• Keep pods focused: one concept per markdown file with clear title, scope, and applicability.
• Pull pods before starting work and push changes promptly to avoid divergent knowledge.
• Create todos at a manageable granularity and link them to pods for immediate context.
• Run joan context claude after changing tracked pods so downstream assistants see the latest context.

Example use cases

• Starting a new microservice: init the workspace, add architecture pods, and generate CLAUDE.md before coding.
• Implementing a feature: list relevant pods, create a plan linked to a todo, and update status as you progress.
• Capturing post-mortem learnings: create a pod describing decisions and push it for team visibility.
• Daily triage: list todos for tracked pods, assign items, and archive completed tasks to keep the workspace clean.