Using the Conversational Agent

Practical techniques for phrasing requests and applying changes with the agent. · Recommended

Read this once you understand what the agent is (see 8.1 — Overview). It covers how to phrase requests, what kinds of prompts work well, and how changes land in your project.

Getting started

1. Open any project in the editor and open the chat panel on the right.
2. The agent loads your full project context automatically — you never need to tell it which project you're on.
3. Before typing, glance at the suggested action chips: the highlighted chip is the recommended next generation for your project's state and runs the full pipeline in one click. See 8.1 — Suggested actions.

You can reference entities precisely while typing: # inserts a table reference (e.g. #features), @table: opens a record picker (e.g. @features: then choose one), and any entity's short code (e.g. PG-002, US-014, T-001.email) works directly in plain text. See 8.3 — Entity codes and references for the full syntax.

Example prompts

Adding entities

• "Add a notification feature that sends email and in-app alerts when a task is assigned"
• "Create a persona for an admin user who manages team permissions and billing"
• "Add three user stories for the search feature focused on filtering and sorting"
• "Generate acceptance criteria for the login feature covering email, Google, and GitHub sign-in"

Editing entities

• "Rename the Dashboard feature to Command Center"
• "Update the Developer persona to include API integration as a primary goal"
• "Change the priority of the Payment Processing feature to high"

Removing entities

• "Remove the Guest User persona"
• "Delete the legacy export feature"

⚠️ Watch out: The agent shows an impact analysis before any deletion. Read it — a persona or feature may be referenced by stories, pages, or criteria you'd rather keep.

Asking questions

• "How many features does this project have?"
• "Which personas are not referenced by any user stories?"
• "Summarise the scope of this project in three sentences"

Bulk operations

• "Add acceptance criteria to every feature that is currently missing them"
• "Create user stories for all features tagged as MVP"

Tips for good results

Be specific

The more detail you give, the better the output:

Reference existing entities

Name — or code — the entity you mean: "Add two user stories to the File Upload feature", or "Add two user stories to F-004".

Build incrementally

The agent remembers the conversation within a session, so you can chain requests:

1. "Add a reporting feature"
2. "Now add three user stories for it"
3. "Add acceptance criteria to each of those stories"

Ask before you commit

If you're unsure how a change will play out, ask first: "What would happen if I removed the Notifications feature?"

How changes are applied

1. Immediate update — the entity is created, edited, or removed as soon as the agent confirms.
2. Live UI refresh — the editor updates automatically; no page refresh needed.
3. Conversation log — every change is recorded in the chat history, giving you an audit trail.

Undo and recovery

• Ask the agent to reverse it — "Undo the last change" or "Restore the persona you just deleted".
• Use regeneration — regenerate the affected section for fresh content.
• Edit manually — click any entity in the editor to change it directly.
• Use version history — every change is versioned; see 17.3 — Reverting changes.

⚡ Power-user hints

• One topic per message keeps responses focused; start a new conversation when you switch topics, to reset the context window.
• Prefer entity codes over names when two entities are similarly named — see 8.3.
• Let the agent drive itself: turn on Guided mode and it will propose the next step, interview you before generations, and review the output. See 9.1 — Guided mode.

↔ The traditional way

Hand-editing a spec means opening the document, finding the right section, making the change, and then remembering every other place that needs to stay in sync. The agent takes the instruction, makes the edit, and surfaces the downstream impact — the reconciliation a human editor does from memory happens explicitly and in seconds.

What's next

• 8.3 — Entity codes and references — the #, @, and bare-code syntax in full.
• 9.1 — Guided mode — hand the wheel to the agent.