Plan Tools

Manage implementation plans and track work through the complete development lifecycle

Implementation plans are the technical specifications that guide developers in building features. Each plan contains detailed instructions, tracks work status, supports collaborative workflows, and automatically creates new feature versions when completed.

Plan-Driven Development
Plans bridge the gap between feature requirements (what to build) and actual implementation (how to build it). They track assignments, work progress, and submission artifacts, creating a complete audit trail.

Implementation Workflow

Plans follow a structured workflow from creation through completion. Understanding this lifecycle helps teams coordinate effectively and track progress:

1

Create Plan

Developers create plans with technical specifications for implementing a feature. Plans start in draft status for review and refinement.
2

Ready for Work

Once reviewed, plans are marked as ready. Workers can now discover and claim them to begin implementation.
3

Claim & Implement

Workers claim available plans, moving them to claimed status. As work progresses, they update the plan and the status automatically transitions to in_progress.
4

Submit Work

When implementation is complete, workers submit their work with artifacts (PR links, notes). Plans move to review status for approval or directly to completed if work is pushed to main.
5

Complete & Version

Approved plans are marked completed, automatically creating a new feature version that links the implementation to the feature history.
Automatic Version Creation
When a plan is marked as completed, trame automatically creates a new feature version and links it to that plan. This creates a complete implementation history showing who built what and when.

Tool Reference

create_plan
Create a new implementation plan for a feature. Plans contain technical specifications and guide developers through implementation.

Parameters

feature_id
string
required

UUID of the feature this plan implements

title
string
required

Short descriptive title for the plan

description
string

Brief description of the implementation approach

spec_content
string
required

Detailed technical specification in markdown with implementation details

status
string

Initial status: draft or ready (default: draft)

Returns

The created plan object with ID, feature ID, title, description, spec content, status (draft), and timestamps

Example

Natural Language Examples:

"Create an implementation plan for feature feat_abc123 to add OAuth 2.0 authentication with Google and email providers"

"Add a plan to implement the real-time notifications feature using WebSockets and Redis pub/sub"

"I need a plan for the User Profile Management feature that includes CRUD operations and avatar uploads"

Expected Response:
✓ Implementation Plan created successfully!

Plan: OAuth 2.0 Authentication Implementation
ID: plan_abc123
Feature ID: feat_xyz789
Status: draft
Description: Implement OAuth 2.0 with Passport.js, supporting Google and email/password flows
Created: 2025-02-13T10:00:00Z

The plan is in draft status. Review the specification and mark it as ready when you're satisfied.
Draft by Default
Plans start in draft status to allow review before making them available to workers. Explicitly set status to ready when the plan is finalized and ready for implementation.
list_plans
List implementation plans with optional filtering by project, feature, or status. Useful for finding available work or tracking plan progress.

Parameters

project_id
string

Filter plans by project UUID

feature_id
string

Filter plans by feature UUID

status_filter
string

Filter by status: draft, ready, claimed, in_progress, stalled, review, completed, or failed

Returns

Array of plan objects with metadata including project name, feature title, plan details, status, claimed_by info, and activity timestamps. Auto-filtered by project membership.

Example

Natural Language Examples:

"Show me all ready plans I can work on"

"List all plans for project proj_abc123"

"What plans are currently in review status?"

"Show plans for the User Authentication feature"

Expected Response:
✓ Available Plans (3):

1. OAuth 2.0 Implementation
   ID: plan_abc123
   Feature: User Authentication (v2)
   Project: Task Manager
   Status: ready
   Created: 2025-02-13T10:00:00Z
   
2. WebSocket Notifications
   ID: plan_def456
   Feature: Real-time Notifications (v1)
   Project: Task Manager
   Status: ready
   Created: 2025-02-13T09:00:00Z

3. Profile CRUD Operations
   ID: plan_ghi789
   Feature: User Profiles (v1)
   Project: Task Manager
   Status: claimed
   Claimed by: john@example.com
   Claimed at: 2025-02-13T11:00:00Z
get_plan
Get detailed plan information including full specification content fetched from cloud storage. Use this before starting work to understand implementation requirements.

Parameters

plan_id
string
required

UUID of the plan to retrieve

Returns

Complete plan object with full metadata, specification content from cloud storage, feature information, claimed_by details, work artifacts (if submitted), and all timestamps

Example

Natural Language Examples:

"Show me the details of plan plan_abc123"

"Get the spec for the OAuth implementation plan"

"What's in the WebSocket notifications plan?"

"Read the full specification for plan plan_xyz789"

Expected Response:
✓ Plan: OAuth 2.0 Authentication Implementation

ID: plan_abc123
Feature: User Authentication (feat_xyz789)
Project: Task Manager
Status: ready
Created: 2025-02-13T10:00:00Z
Updated: 2025-02-13T10:30:00Z

Description:
Implement OAuth 2.0 with Passport.js, supporting Google and email/password flows

Specification Content:

# OAuth 2.0 Implementation Plan

## Technical Approach
Use Passport.js with passport-google-oauth20 and passport-local strategies.

## Implementation Steps
1. Install dependencies: passport, passport-google-oauth20, passport-local
2. Configure Google OAuth credentials in environment
3. Implement authentication routes (/auth/google, /auth/callback)
4. Set up session management with express-session
5. Add JWT token generation for API authentication

## Acceptance Criteria
- Users can sign in with Google
- Users can register/login with email/password
- Sessions persist across requests
- API tokens work for authenticated endpoints

## Testing Requirements
- Unit tests for auth strategies
- Integration tests for auth flows
- E2E tests for login UI
Cloud Storage
Plan specifications are stored in cloud storage (Google Cloud Storage or S3) for scalability. The spec_content is fetched automatically when you retrieve a plan.
update_plan
Update plan specification content as work progresses. Only the claiming user can update a plan. Automatically updates last_activity_at to prevent stalling.

Parameters

plan_id
string
required

UUID of the plan to update

spec_content
string
required

Updated markdown content with progress notes and implementation details

Returns

Updated plan object with new spec_content, last_activity_at timestamp, and updated_at timestamp

Example

Natural Language Examples:

"Update plan plan_abc123 with progress notes - OAuth routes are complete, working on session management"

"Add implementation notes to the WebSocket plan about Redis pub/sub setup"

"Update the plan spec to include the test results and deployment notes"

Expected Response:
✓ Plan updated successfully!

Plan: OAuth 2.0 Authentication Implementation
ID: plan_abc123
Last Activity: 2025-02-13T14:30:00Z
Updated: 2025-02-13T14:30:00Z

The plan specification has been updated with your latest progress.
Stale Detection
Plans with no activity for 24 hours are automatically marked as stalled. Update your plan regularly as you work to show progress and prevent stalling.
set_plan_status
Change plan status following valid status transitions. Used to mark plans ready, transition through workflow states, or mark work complete/failed.

Parameters

plan_id
string
required

UUID of the plan to update

status
string
required

New status: draft, ready, claimed, in_progress, stalled, review, completed, or failed

Returns

Updated plan object with new status and updated_at timestamp. Setting to completed or failed releases the claim (claimed_by set to null).

Example

Natural Language Examples:

"Mark plan plan_abc123 as ready for workers"

"Set the OAuth plan status to completed"

"Change plan plan_def456 status from stalled back to ready"

Expected Response (marking as ready):
✓ Plan status updated!

Plan: OAuth 2.0 Authentication Implementation
ID: plan_abc123
Status: ready (was: draft)
Updated: 2025-02-13T15:00:00Z

The plan is now available for workers to claim.

Expected Response (marking as completed):
✓ Plan completed!

Plan: OAuth 2.0 Authentication Implementation
ID: plan_abc123
Status: completed (was: review)
Updated: 2025-02-13T18:00:00Z
Implemented Version: v3 (created)

A new feature version has been created and linked to this implementation.
The plan is now released and available for reference.
claim_plan
Claim an available implementation plan to work on it. Plan must be in ready status and not already claimed by another user.

Parameters

plan_id
string
required

UUID of the plan to claim

Returns

Updated plan object with status changed to claimed, claimed_by set to your user ID, claimed_at timestamp, and last_activity_at timestamp

Example

Natural Language Examples:

"Claim plan plan_abc123 so I can work on it"

"I want to work on the OAuth implementation plan"

"Claim the WebSocket notifications plan"

Expected Response:
✓ Plan claimed successfully!

Plan: OAuth 2.0 Authentication Implementation
ID: plan_abc123
Feature: User Authentication (feat_xyz789)
Status: claimed
Claimed by: you (john@example.com)
Claimed at: 2025-02-13T11:00:00Z

You can now start working on this plan. Update the plan spec as you make progress.

Errors:
- CONFLICT: Plan not in ready status (may be already claimed or in progress)
- CONFLICT: Plan already claimed by another user
- FORBIDDEN: You are not a member of this project
Multiple Claims
Users can claim multiple plans simultaneously. There are no limits on how many plans you can work on at once - coordinate with your team as needed.
release_plan
Release a claimed plan back to ready status, allowing other users to claim it. Useful when you need to abandon work without completing it.

Parameters

plan_id
string
required

UUID of the plan to release

Returns

Updated plan object with status changed to ready, claimed_by set to null, and claimed_at cleared

Example

Natural Language Examples:

"Release plan plan_abc123 so someone else can work on it"

"I can't finish the OAuth plan, release it back to ready"

"Unclaim the WebSocket plan"

Expected Response:
✓ Plan released successfully!

Plan: OAuth 2.0 Authentication Implementation
ID: plan_abc123
Status: ready (was: claimed)
Claimed by: null
Updated: 2025-02-13T12:00:00Z

The plan is now available for other workers to claim.
submit_work
Submit completed work for an implementation plan with artifacts and choose target status. Automatically creates a new feature version when status is set to completed.

Parameters

plan_id
string
required

UUID of the plan to submit work for

artifacts_markdown
string
required

Flexible markdown with PR links, file paths, test results, deployment notes, or any work artifacts

status
string
required

Target status: review (needs approval) or completed (work pushed to main)

Returns

Updated plan object with new status, work_artifacts stored, claim released (claimed_by null), last_activity_at updated. When status is completed, also returns feature_version object with new version number.

Example

Natural Language Examples:

"Submit work for plan plan_abc123 with PR link https://github.com/user/repo/pull/123 for review"

"Submit the OAuth plan as completed - work is pushed to main branch"

"Submit plan plan_def456 with test results and deployment notes"

Expected Response (submitted for review):
✓ Work submitted for review!

Plan: OAuth 2.0 Authentication Implementation
ID: plan_abc123
Status: review (was: in_progress)
Last Activity: 2025-02-13T17:00:00Z
Updated: 2025-02-13T17:00:00Z

Work Artifacts:
## Implementation Complete

### Changes Made
- Added OAuth integration in src/auth/oauth.ts
- Created login UI in src/components/Login.tsx
- Added tests in src/auth/__tests__/oauth.test.ts

### Pull Request
https://github.com/user/repo/pull/123

### Test Results
All tests passing (see CI)

The plan is now awaiting approval. Once approved, use set_plan_status to mark it completed.

Expected Response (completed):
✓ Implementation completed!

Plan: OAuth 2.0 Authentication Implementation
ID: plan_abc123
Status: completed
Implemented Version: v3 (created automatically)
Updated: 2025-02-13T17:30:00Z

A new feature version has been created:
- Feature: User Authentication
- Version: v3
- Implemented by: john@example.com
- Implementation timestamp: 2025-02-13T17:30:00Z

The implementation is now part of the feature history.
Flexible Artifacts
The artifacts_markdown field accepts any markdown content. Include PR links, file paths, test results, deployment notes, screenshots, or anything else that documents your work.

Common Use Cases

Creating and Publishing Plans

Feature owners create detailed implementation plans and make them available for workers:

You: "Create a plan for the OAuth authentication feature with detailed 
implementation steps using Passport.js"

Your AI assistant (internally calls create_plan):
✓ Plan created in draft status!

You: "Review the spec... looks good. Mark it as ready"

Your AI assistant (internally calls set_plan_status with status: ready):
✓ Plan is now ready!

The plan is now available for workers to claim and implement.

Finding and Claiming Work

Workers discover available plans and claim them to start implementation:

You: "Show me ready plans I can work on"

Your AI assistant (internally calls list_plans with status_filter: ready):
✓ Available Plans (2):

1. OAuth 2.0 Implementation - User Authentication feature
2. WebSocket Notifications - Real-time Notifications feature

You: "I'll take the OAuth plan. Get the full spec"

Your AI assistant (internally calls get_plan):
[Shows complete specification with technical details]

You: "Perfect. Claim this plan"

Your AI assistant (internally calls claim_plan):
✓ Plan claimed! You can now start implementing.

Tracking Progress During Implementation

Update the plan specification as you work to track progress and prevent stalling:

You: "Update the OAuth plan - I've completed the Google OAuth routes 
and session management. Now working on email/password authentication"

Your AI assistant (internally calls update_plan with updated spec):
✓ Plan updated!

[Time passes as you continue working]

You: "Update again - email auth is done, all tests passing, 
creating PR now"

Your AI assistant (internally calls update_plan):
✓ Progress recorded!

The plan's last_activity_at keeps updating, preventing it from being 
marked as stalled.

Submitting Completed Work

When implementation is done, submit work with artifacts for review or as completed:

You: "Submit the OAuth plan for review with PR 
https://github.com/user/repo/pull/123"

Your AI assistant (internally calls submit_work with status: review):
✓ Submitted for review!

[After PR is approved and merged]

You: "Mark the OAuth plan as completed"

Your AI assistant (internally calls set_plan_status with status: completed):
✓ Implementation completed!

A new feature version (v3) has been created automatically, linking 
this implementation to the feature history.

Handling Stalled Plans

Plans inactive for 24 hours are marked stalled. Release or restart them as needed:

You: "Show stalled plans"

Your AI assistant (internally calls list_plans with status_filter: stalled):
✓ Stalled Plans (1):

WebSocket Notifications - claimed 2 days ago, no updates for 48 hours

You: "I can't finish that one. Release it so someone else can work on it"

Your AI assistant (internally calls release_plan):
✓ Plan released back to ready status!

Other workers can now claim this plan and pick up where it was left off.

Filtering Plans by Feature

View all implementation plans for a specific feature to understand the work breakdown:

You: "Show all plans for the User Authentication feature"

Your AI assistant (internally calls list_plans with feature_id):
✓ Plans for User Authentication (3):

1. OAuth 2.0 Implementation - completed (v3)
2. Two-Factor Authentication - ready
3. Password Reset Flow - draft

You: "Get the 2FA plan details"

Your AI assistant (internally calls get_plan):
[Shows specification for two-factor authentication]

Status Transitions

Plans follow specific status transition rules to maintain workflow integrity:

Draft → Ready

Feature owners review and finalize plans before making them available to workers. Use set_plan_status to transition from draft to ready.

Ready → Claimed

Workers use claim_plan to pick up available work. The plan becomes claimed and is assigned to that user.

Claimed → In Progress

Automatic transition when the claiming user updates the plan spec with update_plan. Shows active work is happening.

In Progress → Review or Completed

Use submit_work to move to review (needs approval) or completed (pushed to main). Completed status automatically creates a new feature version.

Review → Completed or In Progress

Use set_plan_status to mark reviewed work as completed, or send back to in_progress if changes are needed.

Stalled → Ready

Plans with no activity for 24 hours automatically become stalled. Use set_plan_status to reset them to ready for another worker to claim.

Releasing Claims

Use release_plan to move claimed or in_progress plans back to ready, allowing other workers to take over.

Status Validation
Invalid status transitions are rejected with an error. For example, you can't directly change a draft plan to completed - it must go through the workflow steps.

Best Practices

Writing Implementation Specs

  • Include technical approach, implementation steps, and acceptance criteria
  • Reference specific files, functions, or modules to modify
  • List dependencies to install and configuration changes needed
  • Define testing requirements (unit, integration, E2E)
  • Add deployment notes and environment variables required
  • Keep specs focused on "how" to implement, not "what" to implement (that's in the feature)

Managing Work Progress

  • Update plan spec regularly (at least daily) to prevent stalling
  • Add progress notes directly in the markdown to track what's done
  • Use update_plan to record blockers or questions that need resolution
  • Don't update just to avoid stalling - include meaningful progress information
  • If stuck, release the plan so others can help or take over

Submitting Work

  • Use status: review when work needs approval before merging
  • Use status: completed when work is already merged to main
  • Include comprehensive artifacts: PR links, test results, deployment notes
  • Document any deviations from the original plan in artifacts
  • List follow-up work or tech debt items for future plans

Coordinating Teams

  • Use list_plans to see what's available, in progress, or needs review
  • Check claimed_by before assigning work to avoid conflicts
  • Set plans to ready only when they're truly ready for implementation
  • Use failed status for implementations that didn't work out (preserves artifacts)
  • Break large features into multiple smaller plans for parallel work

Handling Failures

  • Use set_plan_status with failed status when implementation can't proceed
  • Document why the approach failed in the final plan update
  • Create a new plan with a different approach for the same feature
  • Failed plans preserve the history and artifacts for future reference
  • Don't delete or hide failed plans - they're learning opportunities

Integration with Features

Plans and features work together to create a complete development workflow:

Feature → Multiple Plans

Complex features can be broken into multiple implementation plans. For example, a User Authentication feature might have plans for OAuth, 2FA, and password reset.

Completed Plans → Feature Versions

When a plan status is set to completed, trame automatically creates a new feature version and links it via implemented_by_plan_id. This creates an audit trail of implementations.

Version History

Use list_feature_versions on the feature to see which plans implemented which versions, who did the work, and when it was completed.

Plan Specifications

Plans reference the feature and contain "how" to implement it. Features contain "what" needs to be built. Read the feature spec using get_feature before creating plans.

Next Steps

Now that you understand implementation plans, you're ready to explore feedback tools for collecting user input and managing API keys.

Learn more in the Feedback Tools documentation.