Agent-first task management for AI workflows

version
0.8.0
GitHub stars
63

Install

/plugin install tasuku@tasuku-marketplace

Run it inside Claude Code after adding the marketplace with /plugin marketplace add iheanyi/tasuku.

Contents

Discovered from source

Commands 18

Add Task

tk task add $ARGUMENTS

If no arguments provided, show usage:

Usage

tk task add "Task description"              # Create with auto-generated ID
tk task add "Task description" --id my-id   # Create with custom ID
tk task add "Subtask" --parent parent-id    # Create as subtask
tk task add "Urgent fix" --priority high    # Create with priority
tk task add "Bug" --tag bug                 # Create with tag

Priority Levels

LevelNameWhen to Use
0criticalBlocking issues, urgent bugs
1highImportant, do soon
2normalDefault priority
3lowCan wait
4backlogFuture work, ideas

Block Task

tk task block $ARGUMENTS

Mark a task as blocked, indicating it cannot proceed until dependencies are resolved.

Usage

tk task block <task-id> --by <blocker-id>           # Block by one task
tk task block <task-id> --by task1 --by task2       # Block by multiple tasks
tk task unblock <task-id>                           # Remove all blockers

When to Use

  • Task requires another task to be completed first
  • Waiting on external dependencies
  • Work discovered to have prerequisites during implementation
  • Parallel tasks that converge

Blocked Task Behavior

  • Blocked tasks won't appear in tk task ready
  • Shows blockers in tk task list output
  • Can view with tk task list --status blocked
  • Auto-unblocks when all blocking tasks are done

Best Practices

  1. Be specific about which task is blocking
  2. Don't block on vague dependencies - create tasks for them
  3. Check blocked tasks when completing work
  4. Use tk task deps <id> to visualize dependency chains

Unblocking

# When blocker is done, blocked task becomes ready automatically
tk task done <blocker-id>

# Or manually unblock
tk task unblock <blocked-id>

Complete Task Workflow

A guided workflow for properly completing a task. This skill combines marking done, prompting for learnings, and showing next steps.

Usage

/tasuku:complete <task-id>

Workflow Steps

When you invoke this skill, follow these steps IN ORDER:

Step 1: Mark the Task Done

tk task done <task-id>

This automatically stops any running timer.

Step 2: Capture Learnings (CRITICAL)

Before moving on, reflect on what you learned:

Ask yourself:

  • What was the root cause of any bugs fixed?
  • What patterns worked well (or poorly)?
  • Any "never do X" or "always do Y" rules discovered?
  • Any gotchas or undocumented behaviors found?

Record each learning:

tk learn "Never manually manipulate ANSI strings - use lipgloss functions"
tk learn "Always process BubbleTea Init() command in tests before assertions"

This is not optional. Knowledge captured now prevents future bugs.

Step 3: Check Impact

Show what tasks are now unblocked:

tk task deps <task-id>

Step 4: Suggest Next Steps

Show the user:

  1. Any tasks that were unblocked
  2. Whether to archive the completed task
  3. The next ready task to pick up
# If task is simple/no longer needed:
tk task archive <task-id>

# Show what's next:
tk task ready

Example Flow

User: /tasuku:complete fix-auth-bug

Agent:
1. Marking task done...
   ✓ tk task done fix-auth-bug

2. Learning capture - what did you discover?
   - Root cause: Missing null check in redirect handler
   - Rule: "Always validate redirect URLs before navigation"

   Recording learnings:
   ✓ tk learn "Always validate redirect URLs before navigation"

3. Impact check:
   ✓ This unblocked: deploy-to-prod, write-auth-tests

4. Next steps:
   - Archive this task? (tk task archive fix-auth-bug)
   - Next ready task: deploy-to-prod (high priority)

Why Use This Skill

  • Ensures learnings are captured - The most common failure is forgetting to document what was learned
  • Shows downstream impact - See what tasks are now unblocked
  • Guides next action - Know what to work on next
  • Creates completion ritual - Proper closure on work

Related Skills

  • /tasuku:learn - Record individual learnings
  • /tasuku:ready - See tasks ready to work on
  • /tasuku:pickup - Start working on the next task

Project Context

tk context show $ARGUMENTS

Load the complete project context including all tasks, learnings, and decisions.

Usage

tk context show                 # Full context as JSON
tk context show --format yaml   # Full context as YAML

What's Included

The context contains:

Tasks

  • All active tasks with status, priority, and blockers
  • Subtask relationships
  • Owner and claim information

Learnings

  • Insights discovered while working
  • "Never do X" and "Always use Y" patterns
  • Codebase-specific knowledge

Decisions

  • Architectural choices made
  • Alternatives that were considered
  • Reasoning behind each decision

When to Use

  • Starting a new session to understand project state
  • Onboarding to an unfamiliar project
  • Before making decisions that might duplicate past work
  • Understanding why things were built a certain way

Record Decision

tk decide $ARGUMENTS

Capture important decisions with the alternatives considered and reasoning.

Usage

tk decision add --id auth-strategy --chose "JWT tokens" --over "sessions,OAuth" --because "Stateless for microservices"
tk decision list                    # List all decisions
tk decision remove auth-strategy    # Remove a decision

What to Record

Good decisions to document:

  • Technology choices: "Chose PostgreSQL over MongoDB for relational data"
  • Architecture patterns: "Chose event sourcing over CRUD for audit trail"
  • API design: "Chose REST over GraphQL for simplicity"
  • Trade-offs: "Chose performance over memory efficiency"

Decision Structure

Each decision includes:

  • ID: Identifier for the decision
  • Chose: What was selected
  • Over: Alternatives that were considered
  • Because: Reasoning behind the choice

When to Use

  • Selecting a framework or library
  • Designing system architecture
  • Choosing between implementation approaches
  • Making trade-offs that affect future work

Best Practices

  1. Record decisions before implementing them
  2. Include realistic alternatives that were considered
  3. Be specific about the reasoning
  4. Reference decisions in related tasks

Complete Task

tk task done $ARGUMENTS

For guided completion with learning capture, use /tasuku:complete instead.

Usage

tk task done <task-id>           # Mark single task complete
tk task done <id1> <id2> <id3>   # Mark multiple tasks complete

Automatic Behavior

  • Running timers are automatically stopped
  • Elapsed time is added to task's total duration
  • Blocked tasks that depended on this one may become unblocked

After Completing

Consider:

  • Recording learnings: tk learn "what you discovered"
  • Archiving if no longer needed: tk task archive <id>
  • Starting the next ready task: tk task ready

Tasuku Skills Reference

Complete guide to all Tasuku skills, organized by workflow stage.

Quick Reference

When...Use...
Starting a session/tasuku:context
Need to pick up work/tasuku:pickup or /tasuku:ready
Creating a task/tasuku:add
Starting work/tasuku:start
Adding notes/tasuku:note
Task is blocked/tasuku:block
Finishing work/tasuku:complete or /tasuku:done
Recording insights/tasuku:learn or /tasuku:reflect
Making decisions/tasuku:decide
Checking progress/tasuku:stats

Skills by Workflow Stage

Starting a Session

SkillPurpose
/tasuku:contextGet full project context (tasks, learnings, decisions)
/tasuku:readyList tasks ready to work on, sorted by priority
/tasuku:pickupGuided workflow - select and start a task with full context
/tasuku:statsSee project statistics and progress

Creating & Planning Work

SkillPurpose
/tasuku:addCreate a new task
/tasuku:blockMark a task as blocked by others
/tasuku:listList all tasks with optional filtering
/tasuku:showShow detailed task information

During Work

SkillPurpose
/tasuku:startMark a task as in-progress
/tasuku:noteAdd notes to track progress or context
/tasuku:learnRecord learnings as you discover them
/tasuku:decideDocument architectural decisions

Completing Work

SkillPurpose
/tasuku:doneMark a task as complete
/tasuku:completeGuided workflow - done + learning capture + next steps
/tasuku:reflectGuided workflow - extract learnings from recent work

Knowledge Management

SkillPurpose
/tasuku:learnRecord a learning or insight
/tasuku:decideRecord an architectural decision
/tasuku:promotePromote learnings to permanent documentation
/tasuku:reflectGuided learning extraction process

Workflow Skills (Recommended)

These skills guide you through complete workflows:

/tasuku:pickup

Use when: Starting work, need to choose what to do next

Does: Shows ready tasks → helps select → loads context → starts task

/tasuku:complete

Use when: Finishing a task

Does: Marks done → prompts for learnings → shows what's unblocked → suggests next task

/tasuku:reflect

Use when: After bug fixes, features, or debugging sessions

Does: Guides you through reflection questions → extracts learnings → records them

Basic Skills

For quick operations without the guided workflow:

SkillCommandNotes
/tasuku:add "desc"tk task add "desc"Add --priority high for important tasks
/tasuku:start <id>tk task start <id>Add --timer to track time
/tasuku:done <id>tk task done <id>Auto-stops timer
/tasuku:learn "..."tk learn "..."Use "Never/Always" for rules
/tasuku:note <id> "..."tk note add <id> "..."Track progress

Pro Tips

  1. Start sessions with context:

    /tasuku:context
    
  2. Use workflow skills for important transitions:

    • /tasuku:pickup when starting work
    • /tasuku:complete when finishing
    • /tasuku:reflect after discoveries
  3. Capture learnings immediately: Don't wait until the end of a session. Use /tasuku:learn as soon as you discover something.

  4. Use "Never/Always" format for rules:

    /tasuku:learn "Never manually truncate ANSI strings"
    /tasuku:learn "Always validate URLs before redirect"
    
  5. Document decisions when you make them:

    /tasuku:decide
    

Related Commands

For operations not covered by skills:

tk task ready              # Tasks ready to work on
tk task list --tree        # Hierarchical view
tk task find "query"       # Search everything
tk task timer status       # Check running timers
tk task archive <id>       # Archive completed task
tk learning rules          # List rule-type learnings
tk rules sync              # Sync to editor rules

Getting Help

  • /tasuku - Overview and quick reference
  • /tasuku:help - This detailed guide
  • tk --help - CLI help
  • tk task --help - Task subcommand help

Record Learning

tk learn $ARGUMENTS

Usage

tk learn "The API rate limits to 100 req/min"     # Add a learning
tk learn "Never use sync calls in handlers"       # Record a "never do" pattern
tk learn "Always validate input before DB write"  # Record an "always do" pattern
tk learn "Use mocks for external APIs" --scope "**/*_test.go"  # Scoped learning

What to Record

  • API behaviors: "The auth endpoint returns 401 for expired tokens, not 403"
  • Code patterns: "Use the withRetry wrapper for all external API calls"
  • Gotchas: "The config file must be loaded before initializing the logger"
  • Never/Always rules: "Never store passwords in plain text"

Scoped Learnings

Use --scope with a glob pattern to apply learnings only to specific files:

tk learn "Use React Query for data fetching" --scope "src/components/**"

Promoting Learnings

For learnings that should be permanent documentation:

tk learning promote <id>                # Promote to CLAUDE.md
tk learning promote <id> --to AGENTS.md # Promote to specific file

List Tasks

tk task list $ARGUMENTS

Usage

tk task list                    # All tasks
tk task list --status ready     # Only ready tasks
tk task list --status in_progress  # Only in-progress
tk task list --status blocked   # Only blocked tasks
tk task list --status done      # Only completed tasks
tk task list --tag bug          # Filter by tag
tk task list --tree             # Hierarchical view with subtasks
tk task list --format json      # Output as JSON

Output Format

Tasks are displayed with:

  • Status symbol: [-] ready, [*] in_progress, [!] blocked, [x] done
  • Task ID
  • Description
  • Blockers (if any)

Add Task Note

tk note add $ARGUMENTS

Attach notes to tasks to capture context, progress, and insights.

Usage

tk note add <task-id> "Note text"   # Add a note to a task
tk note list <task-id>              # List notes for a task
tk note remove <task-id> <index>    # Remove a specific note

When to Add Notes

PROACTIVELY add notes when:

  1. Starting a task: Note your planned approach

    tk note add auth-feature "Planning to use JWT with refresh tokens, 1hr expiry"
    
  2. Making progress: Note milestones or partial work

    tk note add auth-feature "Login endpoint complete, working on refresh flow"
    
  3. Encountering issues: Note blockers or failed approaches

    tk note add auth-feature "OAuth library incompatible with Node 20, trying alternative"
    
  4. Discovering context: Note findings for future agents

    tk note add auth-feature "Found existing token validation in utils/auth.ts"
    

Best Practices

  1. Add notes at the start of each work session
  2. Note any unexpected findings or gotchas
  3. Document failed approaches so they aren't repeated
  4. Include file paths and line numbers when relevant
  5. Notes persist across sessions - use them for continuity

Pick Up Next Task

A guided workflow for selecting and starting your next piece of work. Shows what's available, provides context, and gets you started efficiently.

Usage

/tasuku:pickup [task-id]

If no task-id provided, shows ready tasks and helps you choose.

Workflow Steps

Step 1: Show What's Ready

tk task ready

This shows tasks sorted by priority (critical → high → normal → low → backlog).

Step 2: Select a Task

If task-id was provided, use that. Otherwise, recommend based on:

  • Priority level
  • Whether it unblocks other tasks
  • Time since creation

Step 3: Show Task Context

Before starting, surface relevant context:

# Show full task details
tk task show <task-id>

# Surface related learnings
tk find "<keywords from task>"

Step 4: Start the Task

tk task start <task-id>

Optionally with timer:

tk task start <task-id> --timer

Step 5: Surface Related Knowledge

Show any learnings or decisions related to this work:

  • Search learnings for relevant keywords
  • Show related decisions if any exist

Example Flow

User: /tasuku:pickup

Agent:
1. Ready tasks (by priority):

   CRITICAL:
   - fix-auth-regression: "Fix authentication bypass in admin panel"

   HIGH:
   - implement-rate-limiting: "Add rate limiting to API endpoints"
   - update-docs: "Update API documentation for v2"

   NORMAL:
   - refactor-logger: "Clean up logging utilities"

2. Recommendation: fix-auth-regression (critical priority, security issue)

3. Task details:
   - Description: Fix authentication bypass in admin panel
   - Tags: security, bug
   - Created: 2 hours ago

4. Related learnings:
   - "Always validate session tokens on every admin request"
   - "Never trust client-side auth state"

5. Starting task...
   ✓ tk task start fix-auth-regression

   Ready to work on: fix-auth-regression

With Specific Task

User: /tasuku:pickup implement-rate-limiting

Agent:
1. Task details:
   - implement-rate-limiting: "Add rate limiting to API endpoints"
   - Priority: high
   - Tags: api, performance

2. Related decisions:
   - rate-limit-strategy: Chose "token bucket" over "fixed window"

3. Related learnings:
   - "Use Redis for distributed rate limit counters"

4. Starting task...
   ✓ tk task start implement-rate-limiting

Why Use This Skill

  • Informed selection - See all options with priorities
  • Context loading - Relevant learnings and decisions surfaced automatically
  • Quick start - Goes from "what should I do?" to working in one command
  • Knowledge continuity - Previous learnings about this area are shown

Related Skills

  • /tasuku:ready - Just list ready tasks (no workflow)
  • /tasuku:start - Just start a task (no context loading)
  • /tasuku:show - Show task details
  • /tasuku:complete - When you finish the task

Promote Learning

tk learning promote $ARGUMENTS

Move a learning from Tasuku's context to permanent project documentation.

Usage

tk learnings                        # List learnings with indices
tk promote <index>                  # Promote to auto-detected context file
tk promote <index> --to CLAUDE.md   # Promote to specific file
tk promote <index> --keep           # Keep in learnings after promoting

Auto-Detected Context Files

Tasuku looks for these files (in priority order):

  1. CLAUDE.md - Claude Code
  2. .cursorrules - Cursor
  3. .github/copilot-instructions.md - GitHub Copilot
  4. AGENTS.md - Generic AI agents

If none exist, defaults to creating CLAUDE.md.

When to Promote

Promote learnings when they:

  • Have proven valuable multiple times
  • Are "never/always" rules worth enforcing
  • Should persist beyond the current task
  • Would help future developers or agents

What Gets Promoted

  • The learning text is appended to the context file
  • Adds under a "## Learnings" section if not present
  • Removes from Tasuku learnings unless --keep is used

Best Practices

  1. Let learnings prove their value before promoting
  2. Use --to to choose the appropriate file
  3. Review promoted content for clarity
  4. Periodically audit context files for outdated learnings

Ready Tasks

tk task ready $ARGUMENTS

Shows all tasks that are ready to be worked on, sorted by priority.

Priority Order

Tasks are sorted by priority level:

  • Critical (0): Urgent, blocking issues
  • High (1): Important, do soon
  • Normal (2): Default priority
  • Low (3): Can wait
  • Backlog (4): Future work

When to Use

  • Looking for the next task to work on
  • Starting a new work session
  • Checking what's available after completing a task

Next Steps

After viewing ready tasks, use tk task start <id> to begin work on one.

Reflect and Extract Learnings

A guided process for extracting and recording learnings from your recent work. This skill walks you through reflection questions to ensure valuable knowledge is captured.

Usage

/tasuku:reflect

When to Use

  • After fixing a bug - What was the root cause? What prevents it next time?
  • After completing a feature - What patterns worked well?
  • After debugging session - What did you discover about the codebase?
  • When hooks prompt you - "Tests passing after failure - document your fix!"
  • Before ending a session - Capture insights before context is lost

Reflection Process

Step 1: Identify What Happened

Look at recent activity:

  • What tasks were completed?
  • What bugs were fixed?
  • What code was changed?
# Check recent git activity
git log --oneline -10

# Check completed tasks
tk task list --status done

Step 2: Ask Reflection Questions

For each significant piece of work, answer:

Root Cause Analysis (for bug fixes):

  • What was the actual bug?
  • What was the root cause?
  • Why wasn't this caught earlier?
  • What rule would prevent this?

Pattern Recognition:

  • Did you discover any codebase patterns?
  • Any undocumented behaviors in libraries/APIs?
  • Any "this is how things work here" insights?

Decision Points:

  • Did you choose between approaches?
  • What tradeoffs did you consider?
  • Why did you choose what you chose?

Step 3: Formulate Learnings

Good learnings are:

  • Specific - Include enough context to be actionable
  • Rule-based - "Never X" or "Always Y" when applicable
  • Scoped - Can apply to specific paths if relevant

Examples:

# Root cause learning
tk learn "Never manually manipulate ANSI-styled strings - use lipgloss.Width/Place which handle escape sequences"

# Pattern learning
tk learn "BubbleTea async pattern: Init() returns Cmd, Update() processes result Msg, always restore selection after list refresh"

# Gotcha learning
tk learn "lipgloss.Truncate doesn't exist - use charmbracelet/x/ansi.Truncate for ANSI-aware string truncation"

# Scoped learning (applies to specific paths)
tk learn "Always force UTC timezone in golden tests" --scope "**/*_test.go"

Step 4: Record Decisions

If you made architectural choices:

tk decide --id "rate-limit-algo" \
  --chose "token bucket" \
  --over "fixed window, sliding window" \
  --because "Better burst handling and distributed-system friendly"

Step 5: Verify Capture

# List recent learnings
tk learning list

# Check for rule learnings that should be promoted
tk learning rules

Guided Prompts

When you invoke this skill, I'll ask:

  1. What did you just finish?

    • Bug fix? Feature? Refactor? Exploration?
  2. What broke / what was tricky?

    • Error messages, unexpected behaviors, gotchas
  3. What was the fix / solution?

    • The actual change that resolved it
  4. What rule prevents this in the future?

    • "Never..." or "Always..." statement
  5. Any decisions made?

    • Choices between approaches worth documenting

Example Session

/tasuku:reflect

Agent: What did you just work on?

User: Fixed the TUI tests that were failing

Agent: What was the problem?

User: Tests were showing "Loading tasks..." instead of actual content

Agent: What was the root cause?

User: The tests weren't waiting for the async Init() command to complete.
BubbleTea's New() doesn't load data - Init() returns a Cmd that does.

Agent: What's the rule to prevent this?

User: Always process Init() command in tests before making assertions

Agent: Recording learnings...

✓ tk learn "In BubbleTea tests, always process Init() command before assertions - New() starts empty, Init() returns the load Cmd"

Any architectural decisions made?

User: No decisions, just a bug fix.

Agent: Done! Learning recorded. Run `tk learning rules` to see if it should be promoted.

Why Use This Skill

  • Structured extraction - Guided questions ensure thorough reflection
  • Prevents knowledge loss - Capture insights while they're fresh
  • Builds project memory - Learnings persist across sessions
  • Improves future work - Rules prevent the same mistakes

Related Skills

  • /tasuku:learn - Quick learning capture (no guided process)
  • /tasuku:decide - Record architectural decisions
  • /tasuku:complete - Task completion workflow (includes reflection)

Show Task Details

tk task show $ARGUMENTS

Usage

tk task show <task-id>              # Show task details
tk task show <task-id> --format json   # Output as JSON

Information Displayed

  • Task ID and description
  • Status (ready, in_progress, blocked, done)
  • Priority level
  • Blockers (if any)
  • Owner/assignee
  • Parent task (if subtask)
  • Tags and custom fields
  • Notes attached to the task
  • Time tracked
  • Created and updated timestamps

Start Task

tk task start $ARGUMENTS

For guided workflow with context loading, use /tasuku:pickup instead.

Usage

tk task start <task-id>              # Start working on task
tk task start <task-id> --timer      # Start with time tracking
tk task start <task-id> --unblock    # Clear blockers and start

Flags

  • --timer - Start time tracking automatically
  • --unblock - Clear any blockers before starting (for blocked tasks)

Best Practices

  1. Only have one task in_progress at a time for focus
  2. Use --timer if tracking time spent
  3. Use tk task pause <id> if you need to switch tasks

After Starting

  • Record learnings: tk learn "insight"
  • Add notes: tk note add <id> "progress update"
  • When done: tk task done <id>

Task Statistics

tk task stats $ARGUMENTS

Display project statistics including task counts, completion rates, and progress.

Usage

tk task stats                   # Show statistics
tk task stats --format json     # Output as JSON

Metrics Displayed

  • Total task count
  • Tasks by status (ready, in_progress, blocked, done)
  • Completion percentage
  • Blocked task count

When to Use

  • Getting a quick project health check
  • Reporting progress to stakeholders
  • Understanding project velocity
  • Identifying bottlenecks (high blocked count)

Interpreting Results

  • High blocked count: Dependencies need resolution
  • Many in_progress: Consider focusing on completion
  • Low ready count: May need to plan next tasks

Tasuku Task Management

Tasuku is an agent-first task management system. Manage tasks, track learnings, and coordinate work across sessions.

Quick Start

tk task add "description"   # Create a task
tk task ready               # What can I work on?
tk task start <id>          # Begin work
tk task done <id>           # Complete task
tk learn "insight"          # Record learning

Workflow Commands (Recommended)

CommandWhen to Use
/tasuku:pickupStarting work - shows options, loads context, starts task
/tasuku:completeFinishing work - marks done, captures learnings, shows next
/tasuku:reflectAfter discoveries - guided learning extraction
/tasuku:helpSee all available commands

Basic Commands

CommandPurpose
/tasuku:contextFull project context at session start
/tasuku:addCreate a new task
/tasuku:listList tasks with filtering
/tasuku:readyTasks ready to work on
/tasuku:startBegin working on a task
/tasuku:doneMark task complete
/tasuku:learnRecord learnings and insights
/tasuku:decideRecord architectural decisions
/tasuku:noteAdd notes to tasks
/tasuku:showView task details
/tasuku:blockMark task as blocked
/tasuku:statsProject statistics
/tasuku:promotePromote learnings to docs

Task Lifecycle

  1. Start session: /tasuku:context or /tasuku:pickup
  2. During work: /tasuku:note, /tasuku:learn as you go
  3. Finish work: /tasuku:complete (guided) or /tasuku:done (quick)

MCP servers 1

Sponsors

Details

Marketplace
iheanyi/tasuku
Source
plugins/tasuku
Category
Community