Story Lifecycle

Every story in Clears AI follows a defined lifecycle - from creation to completion. Each stage represents a meaningful step in the execution pipeline, with automated transitions driven by AI workflows and manual checkpoints where humans review and approve.

Lifecycle Overview

The Auto Label

The auto label is a key concept in Clears AI. When a story receives this label, it signals the AI pipeline to begin processing the story automatically. The label is applied when you click Run Task on a new story, and it tells the system that this story should be picked up by the automated workflows.

Stories without the auto label are not processed by the AI pipeline. This gives you control over which stories enter the automation flow. You can manually add or remove the auto label at any time from the Board to start or stop AI processing for a specific story.

Status Stages

To Do

The starting state for every story. When you create a story on the Board and click Run Task, the AI agent begins working immediately.

What happens automatically:

1. The story gets an auto label, signaling the AI pipeline to start
2. The AI agent clones your selected repositories and explores the codebase
3. Clarifying questions are generated based on the story description and code analysis
4. A Q&A session starts, and questions appear in the story's Q&A tab (and via Slack if connected)
5. You answer questions by selecting options or typing custom responses
6. The AI generates a structured specification with: TL;DR, detailed description, definition of done, and files to change
7. The story description is updated with the enriched content
8. The story transitions to Enriched

Duration: Typically 2–10 minutes depending on codebase size and number of Q&A questions.

---

Enriched

The story has been analyzed and a specification has been generated. This is a human checkpoint - you review the AI-generated spec before approving.

What you see:

• An "Action Needed" badge on the card
• The enriched description with TL;DR, detailed description, definition of done, and files to change
• Editable summary and description fields - you can refine the spec before approving

Your options:

• Approve → moves to Product Approved (triggers subtask generation)
• Restart Enrichment → sends back to To Do for re-analysis
• Edit → modify the spec inline before approving

---

Product Approved

The spec is approved and the AI begins decomposing the story into implementable subtasks.

What happens automatically:

1. The AI analyzes the approved specification
2. Subtasks are generated, each representing a discrete unit of work
3. Subtasks are created (in Jira if connected, or locally in standalone mode)
4. The story reporter is notified
5. The story transitions to Ready For Dev

Duration: Typically 1–5 minutes.

---

Ready For Dev

Subtasks have been created and the story is ready for AI implementation. This is another human checkpoint.

What you see:

• An "Action Needed" badge
• The list of generated subtasks in the detail panel
• Each subtask with its own description and acceptance criteria

Your options:

• Implement → starts autonomous code implementation
• Review subtasks → check the breakdown before proceeding

---

In Progress

The AI is actively writing code. Each subtask is implemented in sequence.

What happens automatically:

1. For each subtask, the AI:
   • Creates a feature branch ({ISSUE_KEY}/{slug})
   • Reads relevant code in your repository
   • Writes and commits code changes
   • Creates a pull request
2. The Agent Activity tab shows a live terminal view of what the AI is doing
3. GitHub activity indicators on the card update in real time, showing branch, commit, and PR counts
4. If the AI needs approval during implementation, the card shows a "Waiting for Input" indicator

What you can do during implementation:

• Watch progress in the Agent Activity tab
• Send custom prompts to the AI agent via the Agent Session
• Respond to approval requests if the AI pauses for input

Duration: Varies based on story complexity, from minutes to hours for large stories.

---

Validation

Implementation is complete and pull requests are ready for human review.

What you see:

• An "Action Needed" badge
• GitHub activity indicators showing open PRs
• PR details accessible via hover tooltips or by clicking through to GitHub
• AI-generated PR analysis providing context for reviewers

Your options:

• Review PRs on GitHub - check the code, leave comments, request changes
• Request Fix → describe what needs to change and the AI pushes updated commits
• Mark Done → when all PRs are merged and the story is complete

---

Done

The story is complete. All pull requests have been merged and the work is delivered.

What happens automatically:

• Learnings from this execution are captured and stored in the memory system
• Execution context (files changed, decisions made, patterns discovered) is indexed for future reference
• The memory consolidation process can incorporate these learnings into your global and repository knowledge documents

---

Cancelled

A story can be manually cancelled at any stage. Cancelled stories remain visible on the board for reference but no further automation runs on them.

Workflow Activity Indicators

While a story is being processed, the card shows real-time status indicators:

Indicator	Meaning
Running	AI agent actively working (with step descriptions like "Evaluating Conditions," "Running Agent," "Creating PR")
Waiting for Input	Agent paused, needs human approval or feedback
Completed	Workflow finished successfully
Failed	Workflow encountered an error

Action Needed Badges

A yellow "Action Needed" badge appears on cards that require your attention:

• Enriched stories → review the generated specification
• Ready For Dev stories → review subtasks and trigger implementation
• Validation stories → review pull requests
• Waiting for Input → respond to an approval request from the AI agent

Transition Summary

From	To	Trigger
—	To Do	Story created on Board
To Do	Enriched	AI completes analysis and Q&A
Enriched	Product Approved	User approves the spec
Product Approved	Ready For Dev	AI generates subtasks
Ready For Dev	In Progress	User triggers implementation
In Progress	Validation	AI completes all subtask PRs
Validation	Done	User confirms PRs are merged
Any	Cancelled	User manually cancels
Enriched	To Do	User restarts enrichment

Next Steps

• Understand how past executions improve future stories in Memory System
• Learn how to use the Board effectively in Board