Docs

Quick start

Goal: land on this page, end with a real Linear backlog you can build from, in about five minutes. Every step below is the actual flow a first-time user goes through. You can stop and play at any point.

1. Sign up (about 60 seconds)

Go to https://askparley.dev, click Start free, and sign in. Free plan, no card, three sessions per 30 days.

2. Connect Linear (about 30 seconds)

From the dashboard, click Connect Linear. Linear's consent screen asks you to authorize Parley to read and write your issues, projects, and labels. Authorize, and you bounce back to the dashboard with a workspace registered.

3. Install Parley in your chat client (about 90 seconds)

Pick one. The full per-client steps live in Installing Parley below. The fast paths:

• Claude Desktop: Settings, Connectors, Add custom connector, paste the server URL, sign in. No token to manage.
• Claude Code CLI: generate a token at https://askparley.dev/dashboard/tokens, then run the claude mcp add command shown in the install section below.
• Cursor, Codex, Windsurf, ChatGPT, other: see the matching subsection in Installing Parley.

4. Start your first parley (about 2 to 3 minutes)

In a fresh chat with Parley wired up, kick things off with something like:

Start a new parley for a SaaS that helps pet sitters manage clients, schedule visits, capture photo visit reports, and bill recurring fees.

(Use any product idea of your own if you'd rather. The flow is the same.)

Parley proposes an outline: 6 to 10 epics, 30 to 50 features, each tagged core (specific to your idea) or standard (generic SaaS plumbing like auth, billing, settings). Take a minute to look it over. You can chat about anything you'd like to change:

Add an epic for ratings and reviews.

Drop the team-management epic for now.

What's in the Billing epic?

Move recurring billing into Operations.

Parley updates the outline live as you talk. When you're happy with the shape, push forward:

looks good

Parley silently fills every standard feature from best-practice templates (auth, settings, audit log, and so on) and asks 4 to 6 multi-choice design questions about the core ones. Each question covers a design axis that affects many features at once. Reply with a letter (a, b, c, d) or describe your own answer.

After the questions, if you want to see real issues land in Linear before doing more work, ask:

Draft, approve flesh, and graduate the smallest epic only. Leave the rest in their current draft state.

A few seconds later, your Linear workspace has a real project and issues in Backlog state. Open https://linear.app in another tab to see them. You can keep going (grill more features, push the rest to Linear) or stop here and resume the session later from a different chat.

5. You're done

That's the full loop: idea, outline, design questions, real Linear backlog. Promote each issue from Backlog to Todo in Linear when you approve it; the planning hand-off is complete.

Want to go further? Resuming sessions across chats, multiple workspaces, planning-effort tracking, and running against an existing codebase are all covered below.

What Parley is

Parley is a Model Context Protocol (MCP) server. It does not have its own UI. Instead, it provides structured tools to your chat client, and the structure of the conversation produces a clean Linear backlog.

The name comes from the nautical term for a structured conversation between two parties with a purpose. That is literally what this tool is: a structured conversation whose purpose is producing a buildable plan.

Why it exists

Writing good Linear tickets is slow, repetitive work. Most planning conversations either drift (nothing gets captured) or get bogged down in formatting (the conversation dies). Parley splits the difference: you stay in conversation, Parley keeps the structure in shape, and Linear ends up populated in real time.

What you get out of it

• One Linear project per epic, with a description that reflects the summary you gave.
• One Linear issue per feature, tagged plan (plus plan:core or plan:standard), starting with a sparse draft description and getting promoted to the full conventions-compliant format during Graduate.
• Issues have an imperative title, a four-section description (Context, Acceptance Criteria, Technical Notes, Out of Scope), priority with visible reasoning, and the right labels.

The four phases

A full session runs Shape, Grill, Flesh, Graduate. You can stop and resume between any of them. Issues already written to Linear stay in Linear.

Shape: sketch the whole product

Get the breadth of the product onto Linear at one-bullet-per-feature fidelity. Speed matters here. Aim for a complete-feeling outline, not a perfect one.

Parley proposes more epics than you asked for, including obvious areas you did not mention (user management, error states, settings, exports). For each batch:

• Confirm what looks right.
• Strike what does not apply.
• Add what is missing.
• Reorganize as you go.

Each request writes to Linear immediately. Keep a Linear tab open and watch issues populate.

Grill: fill in the detail that matters

Capture enough detail per feature that the build phase has something concrete to work with. The default is FAST: ask only the must-have questions per feature.

Pick your battles. For one to three features that are genuinely complex or high-stakes, name them and Parley walks you through all ten coverage dimensions. For everything else, let Parley do the triage pass: three questions, three short answers, done.

If you do not have an answer:

• n/a for dimensions that genuinely do not apply.
• tbd when you will figure it out later.
• out of scope when this came up but you are explicitly excluding it.

Flesh: review and polish before commitment

Parley promotes each feature into a full conventions-compliant Linear issue. You can amend any issue before approving:

• Rewrite the title.
• Add or remove acceptance criteria.
• Set the priority and the reasoning.
• Move a feature between epics.

Each amendment is patched to Linear immediately and validated against the conventions schema.

Graduate: flip the switch

Promote each issue from its sparse draft form to its final conventions-compliant form: imperative title, four-section description (Context, Acceptance Criteria, Technical Notes, Out of Scope), module:* + complexity:* labels, priority with visible reasoning. The issue stays in Linear's Backlog workflow state. You (or your team) promote it to Todo manually when you're ready to start building.

Recommendation: graduate selectively. Promote only the features you grilled in detail and reviewed in Flesh. Leave the thin ones in their draft form and come back when you are ready to build that area.

Installing Parley

Parley is a hosted MCP server. The endpoint is:

https://askparley.dev/mcp

Two auth methods are supported on the same endpoint:

• OAuth, for clients with a built-in custom-connector UI (Claude Desktop, ChatGPT Connectors). You click a button, sign in to Parley with the same account you use on the dashboard, and you're connected. No token to manage.
• Personal Access Token (PAT), for command-line and IDE clients (Claude Code CLI, Cursor, Codex, Windsurf, anything that takes a JSON or TOML MCP config). Generate one at https://askparley.dev/dashboard/tokens, paste it into your client's config as a bearer header.

Before installing, make sure you've completed steps 1 and 2 of the quick start above. You need an account and a connected Linear workspace before Parley has anything to do.

Pick your client:

Claude Desktop (OAuth, no token)

1. Open Claude Desktop.
2. Open Settings, then Connectors (or "Custom integrations" depending on build), then Add custom connector.
3. Server URL: https://askparley.dev/mcp
4. Click through the WorkOS sign-in tab that opens. Use the same email as your askparley.dev account.

When the tab closes you'll see Parley in your connectors list, marked Connected. Start a new chat and try:

Start a new parley.

Claude Code CLI (PAT)

1. Generate a PAT at https://askparley.dev/dashboard/tokens and copy it (shown once).

2. Run:

   claude mcp add --transport http parley https://askparley.dev/mcp --header "Authorization: Bearer <YOUR_TOKEN>"
   

3. Verify:

   claude mcp list
   

   You should see parley with status Connected.

The --transport http flag is required. Parley speaks Streamable HTTP, not stdio.

Cursor (PAT)

1. Generate a PAT at https://askparley.dev/dashboard/tokens.

2. Open Settings, then MCP, then Add new MCP server. Or edit ~/.cursor/mcp.json directly:

   {
     "mcpServers": {
       "parley": {
         "url": "https://askparley.dev/mcp",
         "headers": {
           "Authorization": "Bearer <YOUR_TOKEN>"
         }
       }
     }
   }
   

3. Restart Cursor. Parley appears as a tool source in the chat sidebar.

Codex CLI (PAT)

1. Generate a PAT at https://askparley.dev/dashboard/tokens.

2. Edit ~/.codex/config.toml:

   [mcp_servers.parley]
   url = "https://askparley.dev/mcp"
   headers = { Authorization = "Bearer <YOUR_TOKEN>" }
   

3. Restart any Codex sessions. Parley tools become available in the next chat.

Windsurf (PAT)

1. Generate a PAT at https://askparley.dev/dashboard/tokens.

2. Edit ~/.codeium/windsurf/mcp_config.json:

   {
     "mcpServers": {
       "parley": {
         "serverUrl": "https://askparley.dev/mcp",
         "headers": {
           "Authorization": "Bearer <YOUR_TOKEN>"
         }
       }
     }
   }
   

3. Restart Windsurf. Parley shows up in Cascade's tool list.

ChatGPT (Connectors, OAuth)

ChatGPT supports custom MCP connectors on Plus, Team, Pro, Business, Enterprise, and Edu plans (the Free plan is limited to ChatGPT's built-in connectors).

1. Open ChatGPT → Settings → Connectors (web or desktop).
2. Add connector → MCP server → paste https://askparley.dev/mcp.
3. Authorize via the WorkOS sign-in tab that opens.

Once connected, you can enable Parley in any chat from the Tools menu.

Any other MCP-capable client (PAT)

If your client takes a generic MCP config, the values are:

Optional: Serena for existing codebases

If you plan to use Parley against an existing codebase, install Serena as a sibling MCP. It gives Claude symbol-level code reading and lets Parley write Linear issues with code anchors that re-resolve at build time. Without Serena, Parley still works on existing codebases (Claude falls back to filesystem tools), but symbol-level anchors are not possible.

One command, fully local, no API keys required:

uv tool install -p 3.13 serena-agent@latest --prerelease=allow
serena init

Wire Serena into your MCP config alongside Parley with --add-mode=no-onboarding. Parley already drives codebase recon during start_session; skipping Serena's onboarding avoids doubling the token cost.

Running a session

In a fresh chat with your MCP-capable client connected to Parley:

Start a new parley.

That is the only invocation phrase you need to remember. Parley walks you through workspace selection (or registration, the first time), then asks what you are planning. From there you stay in conversation.

Workspace registration

Workspaces are connected through the Parley dashboard, not in chat. Visit your dashboard at /dashboard/workspaces and click Connect Linear. You'll be redirected to Linear's consent screen, asked to authorize Parley to read and write issues + projects + labels in your workspace, and then bounced back to the dashboard with the workspace ready to use.

Parley stores an OAuth access token (encrypted at rest) instead of a long-lived API key. You can revoke Parley's access at any time from Linear's OAuth apps settings; that immediately invalidates the token and Parley stops being able to read or write to your workspace.

The workspace gets an auto-generated alias derived from your Linear workspace name (e.g., atlas-labs). You'll use that alias when starting a session so Parley knows which Linear workspace to push to. Each Parley account can have multiple workspaces connected. Connect once per Linear workspace you want to plan against.

Knowing where you are

Three things to know. You do not have to remember them; just have them in your back pocket.

1. Ask plainly. "Where are we right now?" or "what phase are we in?" prompts Parley to tell you the phase, what is left in it, and what comes next.
2. Ask for a recap. "Show me the current outline" gives you a markdown rendition of every epic and feature with Linear links inline.
3. Open Linear in a browser tab. Linear is the source of truth from the moment you propose your first epic. If Parley and Linear ever disagree, Linear wins.

Resuming a session

Sessions live across chats. In a fresh chat:

Resume my parley.

Parley picks up the most recent active session for the current workspace. If you have multiple sessions:

What parley sessions do I have?

If a session is in Grill or later and you want to add more features or revise the outline, ask Parley to take the session back to Shape briefly. Same pattern for revising coverage answers (back to Grill) or amending issues (back to Flesh).

Multiple workspaces

If you are working on several products, register one workspace alias per product:

Register a new parley workspace.

Pick aliases that match how you think.

Tracking planning effort (Team plan and above)

Linear measures dev velocity by counting story points completed in a cycle. By default, the planning work that produces those issues (the parley itself) is invisible to that report, so a cycle where your team grilled 30 features but shipped no code shows up as zero velocity.

Optionally, you can have Parley mirror each parley's planning work as Linear issues in your team's active cycle, so retros see "we planned 14 stories this cycle" alongside "we shipped 22 points."

When you start a new parley, Parley asks:

Track this planning work as Linear cycle effort? Each feature you grill becomes a Linear issue in your team's current cycle so retros can see the planning weight alongside dev work.

Say yes (or no) and Parley remembers for that session.

When tracking is enabled, after you approve the shape, Parley creates:

• A persistent Initiative in your Linear workspace called Planning effort (one per workspace, created the first time you opt in; rename it in Linear if you prefer something more project-specific).
• A Project named Plan: <your session title> under that initiative.
• One Project Milestone per epic (Foundations, Onboarding, Billing, etc.).
• One Issue per feature, tagged planning, assigned to its epic's milestone, dropped into the team's active cycle, with an estimate of 1 point per feature (planning time is roughly constant per feature regardless of how complex the eventual dev work is; bump individual issues manually in Linear if a particular feature genuinely deserves more credit).

As you work the session:

• The first time you record an answer for a feature, its planning issue moves from Todo to In Progress.
• When the feature graduates to a real dev issue (the normal Parley output), its planning issue moves to Done. That's when the cycle credit lands.
• If you drop a feature mid-grill, the planning issue closes as Done with a dropped label (the effort you already spent still counts; the label tells you the underlying dev work didn't ship).
• If you drop a feature before grilling started, the planning issue is canceled (no credit, no noise).
• If you reset or delete the parley, every planning issue is deleted from Linear too. Deleting your account does the same across every parley you've run.

This is an optional feature gated to the Team plan and above. Free and Pro sessions skip the planning-effort writes entirely and behave exactly as before.

Roadmap dates

A roadmap is the zoomed-out, executive view of a session: a few fat bars on a timeline with phase markers, not one bar per epic. Roadmap dates are opt-in, the same way planning-effort tracking is.

When you start a parley (or at any point afterward), you can say yes to:

Want a rough roadmap timeline? I'll place these epics on a Linear timeline you can drag to refine.

Parley then asks for light direction: a start date (defaults to today) and either a rough pace ("about two weeks per epic") or a finish date ("done by end of Q3"). That's all it needs. The dates are deliberately rough, Parley puts the epics roughly in the right area and you drag them in Linear to refine order and timing.

When roadmap mode is on, after you approve the shape Parley creates:

• One dated delivery Project for the whole session (the roadmap bar), with a start and target date spanning the work.
• One dated Project Milestone per epic (the diamonds on the bar), laid end-to-end in sequence from your start date, in your epic order.
• Each feature's engineering issue is attached to its epic's milestone, so the bar shows real progress as you ship.
• If your Linear plan supports initiatives, the session project is grouped under an initiative, and the initiative's Timeline view is your roadmap. Open the initiative and switch to Timeline.

If your Linear plan does not include initiatives, Parley still lays down the dated project and milestones, and groups them with a short workspace project label derived from your session title (e.g. "Context Management Foundation" becomes CMF). Your roadmap is then a Projects view filtered to that label, switched to Timeline layout. When you run more than one roadmap session, reusing the same label name groups them onto a single timeline.

Notes:

• Rough by design. Parley never tries to nail the exact dates you want. Drag the bar and diamonds in Linear to refine.
• Order is yours to set. The diamonds follow your epic order. Ask Parley to reorder the epics ("put authentication first", "move billing to the end") and, when roadmap dates are on, it re-derives the milestone dates in place to match, on the same delivery project (no duplicate milestones). You can reorder anytime, including after the shape is approved, without reopening it. You can also set the order when you turn the roadmap on.
• Re-running (or reordering) is the only thing that overwrites your edits. Once dates are laid down, Parley leaves them alone. If you ask Parley to redo the roadmap (new start date or pace) or to reorder the epics, it re-derives and overwrites, including any dragging you did, so only do it when you actually want a fresh layout.
• Existing sessions can be back-filled. Ask Parley to add a roadmap to a session you already graduated and it dates the existing projects and milestones in place.

What gets written to Linear

For each session, Parley creates:

• One Linear project per epic. Project name equals the epic name. Project description equals the first sentence of the summary you gave (max 255 chars). Project content (the long body) equals the full summary plus a "Created by Parley, session ..." footer that gets removed when the last feature in that epic graduates.
• One Linear issue per feature. During Shape and Grill, the issue has a sparse description that reflects whatever coverage you recorded so far. After Flesh, the description is rewritten into the conventions four-section format. After Graduate, the title, description, module:* + complexity:* labels, and priority are all in their final form. The plan label (plus plan:core or plan:standard per the feature kind) is applied throughout the lifecycle.

Parley does not modify any Linear data outside what it created during the session. Existing issues, projects, workflows, and team members are untouched.

Concepts and conventions

The conventions repo

Both Parley and the downstream build agent (Shipwright) pin a SHA of a shared repository, vyntric-conventions. It holds conventions/backlog-contract.json and related files that define the issue schema, label vocabulary, and priority reasoning rules. When a convention changes, both tools bump their pin in lockstep.

You do not need to interact with the conventions repo directly. Parley loads it on every boot and validates writes against it.

Labels

• plan: every issue created from a planning session carries this label. Lets you filter "everything Parley produced" with one click.
• plan:core: features identified as core (differentiators specific to the product). Walked one-by-one during Grill.
• plan:standard: features identified as standard (generic SaaS plumbing like auth, billing, settings). Auto-filled from templates without walking each one in chat.
• module:*: one of auth, core, data, ui, etc. Reflects which area of the system the issue touches.
• complexity:*: one of trivial, small, medium, large, xl. Set by the drafter based on coverage and signals.

Priority

Parley assigns a priority during Flesh with visible reasoning. Typical pattern: "medium because: core happy-path features default to medium." You can override the priority for any issue with one amend.

When Parley is the wrong tool

• Day-to-day backlog grooming. Use Linear directly.
• Bug tracking. Bugs do not need the coverage grill.
• One-off chore tickets. Ceremony beats benefit.

A good rule: if you would otherwise spend 30+ minutes talking through a feature before writing a ticket, Parley will be faster and produce better output.

Tips

• Be honest about "I do not know." Saying "tbd" is fine; inventing an answer creates drag in the build phase.
• Use the fast pass. The default Grill behavior is one question per feature, short answer, move on. Resist the urge to dig into every feature; reserve depth for the few that matter.
• Reorganize during Shape, not later. Moving features between epics is cheaper before they have rich coverage answers attached.
• Open Linear in a tab while you work. Watching the issues populate in real time keeps you grounded.
• You can stop anywhere. Linear is the source of truth. If a chat ends abruptly, your work is safe.
• Do not try to grill 64 features in one sitting. Grill the ones you will build first. Come back for the rest as you start each section.
• The thin issues are not failures. A draft with a one-line bullet and an honest "needs detail" Acceptance Criterion is better than a polished issue with fabricated content. Build pipelines should refuse to build the former; that is the right behavior.

Voice input

If your chat client has voice input enabled (or you use STT at the OS level), you can do a full Parley session hands-free. The Grill phase in particular is well-suited to voice: you think out loud, Parley captures the substance.

Privacy and data

Sessions are stored in Parley's Postgres database, scoped to your organization. The OAuth access + refresh tokens Linear issues to Parley are encrypted at rest. You can revoke Parley's Linear access at any time from Linear's OAuth apps settings, and you can rename your organization, export all of your Parley data, and delete your account from the Settings page in the dashboard.

Getting help

• See the changelog for what has shipped recently.
• Hit a bug or have a question? Email support@vyntric.com.
• Reach out to your Vyntric contact for direct support.