Skip to main content

Creating Your First AI Story

This guide walks you through creating a story on the Board and watching the AI agent analyze, implement, and deliver working code as pull requests. Each step follows the Board columns (Prepare, Build, Review and Done) and the Ticket Panel, the side panel that opens when you click a card.

Prerequisites​

Before you begin, make sure you have:

  • Connected a VCS provider (GitHub, GitLab, or Bitbucket)
  • Configured your Anthropic API key in Settings → General (required for AI execution)

Step 1: Create a Story​

  1. Open the Board from the left sidebar
  2. Click Add Task in the toolbar. When Jira is connected, a menu opens: choose Create new. Otherwise the Create task form opens directly

The Create task form

  1. Fill in the Create task form:
    • Summary - a clear, concise title for what you want built
    • Description (Optional) - additional context, requirements, or acceptance criteria
    • Images (Optional) - drag and drop screenshots, mockups, or diagrams to provide visual context
    • Project - select the project (if you have multiple)
    • Parent epic (Optional) - link to an existing epic
    • Priority - how urgent the story is
    • When Jira is connected, the form also shows your Jira fields
  2. Click Create Task

The form has no repository field. You choose the repositories in Step 4, when the story is ready to run.

:::tip Writing effective stories The more context you provide, the better the AI performs. Include:

  • What the feature should do (user-facing behavior)
  • Where it fits in the existing codebase (if you know)
  • Any constraints or edge cases to handle
  • Screenshots or mockups for UI work :::

Step 2: Watch Clears Triage the Story​

The new story appears in the Prepare column. Clears starts triage on it if your account's triage settings allow it. Otherwise the card shows Start Triage: click it to start triage.

  1. Codebase exploration - the agent reads your repository to understand the architecture, patterns, and conventions
  2. Triage - the agent scores the story's readiness, complexity and risk

While Clears works, the card shows a status line and a Current activity block with what it is doing right now. Click the card to open the Ticket Panel.

When triage is done, the card shows Answer questions if Clears has questions for you (see Step 3), or Run if the story is ready to run (see Step 4).

Step 3: Answer Clarifying Questions​

When triage has questions about your requirements, the card says Waiting for you and shows Answer questions.

Answering questions in the Ticket Panel

  1. Click Answer questions to open the Ticket Panel. It reads Clears paused · needs your answers
  2. For each question:
    • Select one of the suggested options, or
    • Type a custom answer in the text field
  3. Click Submit Answers
  4. Clears picks the story back up with your answers, and the card shows Run when the story is ready to run

If Slack or Microsoft Teams is connected, you'll also receive questions as direct messages and can respond there. See Answer triage questions.

Step 4: Run the Story​

When the story is ready to run, the card shows Run. Click the card to open the Ticket Panel. It reads Triaged · ready to run with the heading Ready to run, and shows Run settings:

  • Repositories - the repositories Clears works in, with a base branch for each. Triage's suggestions are pre-selected.
  • Skills (optional) - the skills Clears uses on the run

If triage left optional questions open, they are in a folded section such as "2 questions from triage", marked Optional. Answer them to re-run triage with your answers, or click Skip to run the story as it is.

Check the settings, then click Run in the panel to start. To start a low-priority run, open the menu beside it and choose Run (Low priority). See Run for details.

note

Run on the card starts the run straight away, with the repositories saved for the story or suggested by triage, and doesn't open the panel. To check or change the repositories first, click the card and use Run in the panel.

Clears may ask more questions while it enriches the story. The card shows Answer questions again. These questions appear one at a time, and you send each answer with Submit.

Step 5: Review the Specification and the Breakdown​

Review the specification, then the breakdown into subtasks, both in the Ticket Panel.

  1. Click Review enrichment on the card. The panel shows Review enriched content with the enriched description: a brief overview, the technical approach, the definition of done, and the files to change. Read it, then click Approve and breakdown to subtasks. See Review enrichment.
  2. Click Review breakdown on the card. The panel shows Approve the breakdown with the list of subtasks. Expand a subtask to see its criteria, repository and files. You can rename a subtask, edit its description, or remove it. Click Approve breakdown to start the build. See Approve the breakdown.

Approving the breakdown in the Ticket Panel

Step 6: Watch Clears Build​

After you approve the breakdown, the card moves to Build and Clears implements each subtask:

  1. Each subtask gets its own branch and commits
  2. The card's Current activity block shows the progress, for example "Subtask 1 of 3 in progress"
  3. Open the AI session tab of the Ticket Panel to watch the live run. A dot on the tab shows that Clears is working
  4. Type in the prompt field to send a prompt, attach images, or redirect the agent while it works

The AI session tab

See AI session tab.

note

Builds work with all supported VCS providers. If you're using GitLab, "pull requests" appear as "merge requests" in the GitLab UI.

Step 7: Review Pull Requests​

When implementation is complete, the card moves to Review and shows Review PRs (Review PR when there is one pull request):

  1. Click Review PRs. The panel reads Ready for your review and lists each pull request with its repository and checks
  2. Review each pull request on GitHub, and leave comments there. Each pull request's title links to it. Open in GitHub opens the first pull request only
  3. Click Approve & Merge when you are satisfied with all of them. After you confirm, Clears approves and merges every open pull request in the list

Reviewing pull requests in the Ticket Panel

Open in GitHub and Approve & Merge work for GitHub pull requests only. Pull requests on GitLab or Bitbucket are listed with links, and you review and merge them in your provider. See Review pull requests.

If you find issues in a pull request, describe what needs to change in a prompt in the AI session tab, and Clears works on it.

What Happens Next​

Once every PR is merged, the card stays in Review as Delivered with Mark as done. The panel shows a Validation needed alert with Mark as Done (see Validation). Once the ticket is closed, the card moves to Done. The AI captures learnings from this execution into the memory system, improving its performance on future stories in the same repository.

Quick Reference: Story Lifecycle​

StageBoard columnWhat's Happening
CreatedPrepareStory created, Clears triages it (or click Start Triage)
QuestionsPrepareAnswer clarifying questions
Ready to runPrepareChoose repositories and click Run
ApprovalPrepareReview the enriched content and approve the breakdown
ImplementationBuildAI writes code for each subtask
ReviewReviewPRs ready for review; Delivered once merged
CompleteDoneTicket closed, learnings captured

Next Steps​

Now that you've created your first story, explore:

  • Ticket Panel for every step that waits for you, and the AI session
  • Core Concepts to understand the full execution pipeline
  • Board features for the Board columns and agent interaction
  • Memory to see how the AI learns from your codebase