
tasuku
Agent-first task management for AI workflows
- version
- 0.8.0
- GitHub stars
- 63
Install
/plugin install tasuku@tasuku-marketplaceRun it inside Claude Code after adding the marketplace with /plugin marketplace add iheanyi/tasuku.
Contents
Discovered from sourceCommands 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
| Level | Name | When to Use |
|---|---|---|
| 0 | critical | Blocking issues, urgent bugs |
| 1 | high | Important, do soon |
| 2 | normal | Default priority |
| 3 | low | Can wait |
| 4 | backlog | Future 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 listoutput - Can view with
tk task list --status blocked - Auto-unblocks when all blocking tasks are done
Best Practices
- Be specific about which task is blocking
- Don't block on vague dependencies - create tasks for them
- Check blocked tasks when completing work
- 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:
- Any tasks that were unblocked
- Whether to archive the completed task
- 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
- Record decisions before implementing them
- Include realistic alternatives that were considered
- Be specific about the reasoning
- 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
| Skill | Purpose |
|---|---|
/tasuku:context | Get full project context (tasks, learnings, decisions) |
/tasuku:ready | List tasks ready to work on, sorted by priority |
/tasuku:pickup | Guided workflow - select and start a task with full context |
/tasuku:stats | See project statistics and progress |
Creating & Planning Work
| Skill | Purpose |
|---|---|
/tasuku:add | Create a new task |
/tasuku:block | Mark a task as blocked by others |
/tasuku:list | List all tasks with optional filtering |
/tasuku:show | Show detailed task information |
During Work
| Skill | Purpose |
|---|---|
/tasuku:start | Mark a task as in-progress |
/tasuku:note | Add notes to track progress or context |
/tasuku:learn | Record learnings as you discover them |
/tasuku:decide | Document architectural decisions |
Completing Work
| Skill | Purpose |
|---|---|
/tasuku:done | Mark a task as complete |
/tasuku:complete | Guided workflow - done + learning capture + next steps |
/tasuku:reflect | Guided workflow - extract learnings from recent work |
Knowledge Management
| Skill | Purpose |
|---|---|
/tasuku:learn | Record a learning or insight |
/tasuku:decide | Record an architectural decision |
/tasuku:promote | Promote learnings to permanent documentation |
/tasuku:reflect | Guided 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:
| Skill | Command | Notes |
|---|---|---|
/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
-
Start sessions with context:
/tasuku:context -
Use workflow skills for important transitions:
/tasuku:pickupwhen starting work/tasuku:completewhen finishing/tasuku:reflectafter discoveries
-
Capture learnings immediately: Don't wait until the end of a session. Use
/tasuku:learnas soon as you discover something. -
Use "Never/Always" format for rules:
/tasuku:learn "Never manually truncate ANSI strings" /tasuku:learn "Always validate URLs before redirect" -
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 guidetk --help- CLI helptk 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
withRetrywrapper 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:
-
Starting a task: Note your planned approach
tk note add auth-feature "Planning to use JWT with refresh tokens, 1hr expiry" -
Making progress: Note milestones or partial work
tk note add auth-feature "Login endpoint complete, working on refresh flow" -
Encountering issues: Note blockers or failed approaches
tk note add auth-feature "OAuth library incompatible with Node 20, trying alternative" -
Discovering context: Note findings for future agents
tk note add auth-feature "Found existing token validation in utils/auth.ts"
Best Practices
- Add notes at the start of each work session
- Note any unexpected findings or gotchas
- Document failed approaches so they aren't repeated
- Include file paths and line numbers when relevant
- 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):
CLAUDE.md- Claude Code.cursorrules- Cursor.github/copilot-instructions.md- GitHub CopilotAGENTS.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
--keepis used
Best Practices
- Let learnings prove their value before promoting
- Use
--toto choose the appropriate file - Review promoted content for clarity
- 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:
-
What did you just finish?
- Bug fix? Feature? Refactor? Exploration?
-
What broke / what was tricky?
- Error messages, unexpected behaviors, gotchas
-
What was the fix / solution?
- The actual change that resolved it
-
What rule prevents this in the future?
- "Never..." or "Always..." statement
-
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
- Only have one task in_progress at a time for focus
- Use
--timerif tracking time spent - 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)
| Command | When to Use |
|---|---|
/tasuku:pickup | Starting work - shows options, loads context, starts task |
/tasuku:complete | Finishing work - marks done, captures learnings, shows next |
/tasuku:reflect | After discoveries - guided learning extraction |
/tasuku:help | See all available commands |
Basic Commands
| Command | Purpose |
|---|---|
/tasuku:context | Full project context at session start |
/tasuku:add | Create a new task |
/tasuku:list | List tasks with filtering |
/tasuku:ready | Tasks ready to work on |
/tasuku:start | Begin working on a task |
/tasuku:done | Mark task complete |
/tasuku:learn | Record learnings and insights |
/tasuku:decide | Record architectural decisions |
/tasuku:note | Add notes to tasks |
/tasuku:show | View task details |
/tasuku:block | Mark task as blocked |
/tasuku:stats | Project statistics |
/tasuku:promote | Promote learnings to docs |
Task Lifecycle
- Start session:
/tasuku:contextor/tasuku:pickup - During work:
/tasuku:note,/tasuku:learnas you go - Finish work:
/tasuku:complete(guided) or/tasuku:done(quick)
MCP servers 1
Sponsors
Details
- Marketplace
- iheanyi/tasuku
- Source
- plugins/tasuku
- Category
- Community