Planning Sessions

Planning is where most projects fail. It's not a lack of ideas or talent: it's that teams jump straight into building without validating assumptions, without challenging scope, without identifying the risks right in front of them.

Planning Sessions in Almirant is not a task generation tool. It's your AI planning partner that challenges you, questions you, and forces you to think before writing a single line of code.

What are Planning Sessions

A Planning Session is a multi-turn conversation with the AI. It's not a single prompt that produces a list of items: it's an iterative dialogue where the AI acts as a sparring partner, challenging every decision you make:

• Questions assumptions you take for granted
• Identifies risks in your planning
• Proposes alternatives you hadn't considered
• Refines scope so it's clear what's in and what's out

The result isn't just a list of work items: it's validated scope and challenged assumptions.

Your planning partner, not a generator

The difference is fundamental. A generator takes your input and produces output. A planning partner questions your input. It asks why, what alternatives you considered, where the risks are.

Starting a session

1. Navigate to the /plan route from the project where you want to plan.
2. Select the target board where the resulting work items will be created.
3. Optionally, select ideation seeds to provide initial context.
4. Write your initial message describing what you want to achieve.
5. Start the conversation.

Session title

When starting, you can assign a descriptive title to the session. This title will help you identify the session in the history. Examples:

• "OAuth authentication planning"
• "Database migration analysis"
• "Notification system design"

Conversational flow

The session follows a natural dialogue flow:

1. You present your idea

You describe what you want to achieve. You don't need to have everything figured out: that's precisely what the sparring is for.

2. The AI challenges

Instead of generating items immediately, the AI asks questions:

• Why is this necessary?
• What alternatives did you consider?
• Where are the blind spots?
• What happens if this fails?

3. You defend or reconsider

You answer the questions. Sometimes you defend your position, sometimes you realize there's a better approach.

4. Scope gets refined

With each iteration, the scope becomes clearer. The AI understands your context better and you understand the risks better.

5. Work item generation

When the scope is validated, the AI generates structured work items: epics, features, stories, and tasks with definitions of done.

6. Review and acceptance

You review each suggested item. Accept the ones that apply, reject the ones that don't. Accepted items are automatically created on the selected board.

Session phases

Each session goes through different phases that you can see in the interface:

Phase	Description
idle	Waiting for you to start the conversation
booting	Preparing the session and context
chatting	Exchanging messages with the AI
streaming	Receiving response in real time
thinking	AI processes and reasons (thinking mode active)
waiting_for_answer	AI is waiting for your answer to a question
reviewing	Reviewing suggested items to accept or reject
completed	Session finished with items created
paused	Session paused to continue later

Selecting ideation Seeds

Before starting the dialogue, you can select seeds: previous ideas captured in Almirant that serve as a starting point. Seeds provide initial context to the session:

• Saved brainstorming notes
• Ideas from previous sessions
• Requirements captured from stakeholder conversations
• Processed user feedback

When you select seeds, the AI analyzes them as part of the initial context, enabling more informed planning.

How to select seeds

1. On the session start screen, you'll see the Available Seeds section.
2. Check the seeds relevant to this planning.
3. Selected seeds will be included in the session's initial context.

The seedsProcessed field in the session result indicates how many seeds were analyzed.

Generating work items

When the conversation reaches a point where the scope is clear, the AI generates a proposal of structured work items:

Types of items generated

Type	Description
Epic	A large initiative that groups multiple features
Feature	A concrete functionality that delivers value
Story	A user story with acceptance criteria
Task	A specific, actionable technical task

Structure of each item

Each proposed item includes:

• Title descriptive and actionable
• Description detailed with context
• Priority suggested (urgent, high, medium, low)
• Hierarchy (parentTempId indicates the parent item)
• Origin (fromSeedId if it came from a specific seed)

Review and accept

In the review phase you can:

• Accept individual items
• Reject items that don't apply
• Accept all if the entire proposal looks good to you

Accepted items are automatically created on the selected board, respecting the proposed hierarchy.

Session history

All sessions are automatically saved and you can access them later:

Status	Description
active	Session in progress. You can continue the dialogue.
completed	Session finished. Items created on the board.
archived	Session saved for future reference.

From the history you can:

• View the complete dialogue of any session
• Check the items that were created
• Reactivate an archived session to continue

Cost tracking

Each session records usage metrics so you can optimize your quota consumption:

Metric	Description
totalInputTokens	Tokens sent to the AI
totalOutputTokens	Tokens received from the AI
estimatedCost	Estimated session cost
durationMs	Total session duration

These metrics let you understand how much each session consumes and optimize your AI quota usage.

Session configuration

Each session can have its own configuration:

Field	Description
model	AI model to use (e.g., claude-3-opus)
provider	AI provider (anthropic, openai, etc.)
systemPrompt	Custom system prompt
temperature	Generation temperature (0.0 - 1.0)

The default configuration comes from the organization settings, but you can customize it for specific sessions.

Response modes

The AI can operate in different modes depending on the complexity of what you're discussing:

Streaming

You see the response as it's being generated. Ideal for rapid iteration and fluid dialogue.

Thinking

The AI reasons step by step before responding. Better for complex problems where you need deep analysis.

You can alternate between modes during the session.

Writing effective prompts

Your first message matters. Here are examples of good starting points:

Good starting points

Prompt	Why it works
"I want to add social auth, but I'm not sure if it's worth the effort vs magic links"	Invites the AI to compare alternatives
"I need to improve product listing performance, users are complaining about slowness"	Defines the real problem, not the assumed solution
"We need to migrate from REST to GraphQL, the team says it's better but I'm not convinced"	Opens space to challenge the decision

Avoid

Prompt	Problem
"Generate tasks for authentication"	Closes dialogue space, asks for direct output
"Build a user CRUD"	No problem to solve, just mechanics
"Improve the whole system"	No focus, impossible to challenge

Prerequisites

To use Planning Sessions you need:

• An AI provider configured with a valid API key
• Available quota in your organization
• A project with at least one active board where the items will be created

For Developers

Data structure

The session is stored with the following main fields:

Field	Type	Description
id	uuid	Unique identifier
organizationId	text	Owning organization
projectId	uuid	Associated project
boardId	uuid	Board where items are created
title	text	Session title
status	enum	active, completed, archived
config	json	model, provider, systemPrompt, temperature
result	json	summary, workItemsCreated, seedsProcessed

Session messages

Each conversation message has:

Field	Type	Description
role	enum	user, assistant, system
content	text	Message content
messageType	varchar	Message type
inputTokens	integer	Input tokens
outputTokens	integer	Output tokens

MCP Tools

Tool	Description	Main parameters
record_ai_session	Records a planning session	projectId, prompt, response, tokensUsed
get_ai_sessions	Retrieves the session history for a project	projectId, limit

Example: Recording a session

Tool: record_ai_session
Parameters:
  projectId: "project-uuid"
  prompt: "I need a push notification system"
  response: "AI-generated proposal..."
  tokensUsed: 1250

Access route

The main route for Planning Sessions is /plan. From there you can start new sessions, view history, and continue paused sessions.