These docs are new.

Expect rough edges. If something is missing or hard to follow, tell us on Discord or by mail at hallo@knecht.works.

Integrations

Plane

Everything you need to know about the Plane integration. What it can do and how to set it up.

The Plane integration connects a Plane workspace to your instance, on Plane Cloud or self-hosted. Work items start workflows, the agent reads and answers on them, moves them between states, and Knecht reports the finished pull request back on the work item.

Setup

You need a Plane workspace and an account Knecht acts as. A dedicated account named "Knecht" is worth the extra seat: comments show up under its name, "assign it to Knecht" becomes a normal assignment in Plane, and the account's project memberships limit what Knecht can see. Creating the webhook in step three needs workspace admin rights, once.

Create a Personal Access Token

Sign in to Plane as the account Knecht should use and open the profile settings. Under Developer, "Personal Access Tokens", click "Add access token". Give it a title such as "Knecht", leave "Never expires" on or set an expiration date, and click "Generate token". Copy the token, it starts with plane_api_ and is shown only once.

The Create token dialog in the Plane profile settings, with the title Knecht and Never expires switched on

A token with an expiration date stops working on that day. Create a new one and use "Reconnect" in Knecht before it runs out.

Connect the Account

In your instance, open Settings, Integrations. The Plane panel has three fields:

Plane URL. https://app.plane.so for Plane Cloud, or the address of your own Plane. It has to start with https://.
Workspace slug. The first path segment of your Plane URL. For https://app.plane.so/acme/projects it is acme.
API key. The token from step one.

"Connect" checks the credentials against Plane before anything is stored and shows "Connected as" with the account's name on success. The token is stored encrypted and not shown again. "Reconnect" replaces the token later, "Disconnect" removes the connection.

The Plane panel under Settings, Integrations, connected to an account, with the Plane URL, workspace slug, and API key fields, and the webhook URL and secret below

Create the Webhook in Plane

Plane does not call Knecht until you tell it to. After connecting, the panel shows "Create the webhook in Plane and paste its secret below" with the webhook URL and a copy button. "Set up in Plane" opens the webhook page of your workspace. By hand it is Workspace settings, then "Webhooks" under Developers.

Fill in the form:

Webhook title. Anything, for example "Knecht".
Payload URL. The webhook URL from the panel, it ends in /api/plane/webhook.
V1 scopes. Leave everything unticked, they are deprecated.
V2 scopes. Tick "Work items" and "Work item comments". Everything else stays empty.
Work item v2 filters. Leave it empty. Knecht drops events of projects that are not linked.

The Create webhook form in the Plane workspace settings, with the Knecht payload URL and the V2 scopes Work items and Work item comments ticked

Knecht uses the work item events created, updated, archived, and deleted, and the comment event created. Updated and deleted comments arrive as well and are ignored.

"Create" saves the webhook, and Plane generates a secret key for it. Copy the secret key, paste it into the Secret field of the Plane panel in Knecht, and click "Save". The pencil next to the secret replaces it later, for example after regenerating the key in Plane. The status line switches to "Waiting for Plane".

Link a Project to Its Plane Project

Open the settings of a project in Knecht. The Plane panel has one field, "Plane project", listing the projects the account is a member of. Pick the one whose work items belong to this repository. One Plane project links to one repository and the other way round. Only linked projects can have Plane triggers.

Check That Events Arrive

Edit any work item in the linked Plane project. The status line in the Plane panel under Settings, Integrations switches to "Receiving events" with the last event and work item key. If it does not:

Status line says	What to do
Wrong secret	Replace the secret in the panel with the secret key of the webhook.
Without a body	Create the webhook again, Plane sent an empty delivery.
No project is linked	Link the Plane project in the project settings, see step four. Events Knecht does not use show up here as well.
Still "Waiting for Plane"	Check that the webhook URL is reachable from the internet and that the scopes are ticked.

Capabilities

Triggers

A Plane trigger watches the Plane projects that are linked to the selected projects. When a work item fires it, one run starts in the project that work item's Plane project is linked to. The project field only lists projects that are linked. In the form, "Fires when any of these happens" lists the events and "But only if" the conditions. Any ticked event fires the trigger, and one group of conditions has to hold. How the two sections work in general is on Triggers. What all issue trackers share, such as issues that are created with the label already set, is on Triggers.

The trigger dialog with Plane selected as source, one linked project, the event Assigned to Knecht ticked, and the conditions Label is Bug and Priority is urgent

Events

Event	Fires when	Notes
Created	A new work item appears in the project.
Assigned to Knecht	The work item is assigned to the account behind the connection.	Ticked by default. Makes "give it to Knecht" a normal assignment in Plane. Knecht joining the assignees itself does not fire.
Label added	One of the picked labels is added to a work item.	The labels are picked from the labels of the Plane project.
State reached	A work item moves into one of the picked states or state groups.	The default is "Any Completed". A work item created in a state does not fire.

State Reached

The state list has two groups.

Group. "Any Backlog", "Any Unstarted", "Any Started", "Any Completed", and "Any Cancelled" stand for Plane's five state groups, whatever the states of a project are called.
Exact state. The states of the selected projects.

Triggers explains when a group and when an exact state fires, Matching what happens with several projects. If the form warns about a missing state, pick a group, a state all projects share, or create a second trigger.

Conditions

Field	Compares against
State	The state the work item is in, as a group such as "Any Started" or an exact state.
Assignee	"Knecht", the account behind the connection.
Label	The labels on the work item, read from the Plane project.
Priority	The priority of the work item: `urgent`, `high`, `medium`, `low`, or `none`.

Each condition takes "is" or "is not". Every value is picked from a list and compared exactly, upper and lower case included. The rules are the same for every source, see Matching.

Inputs

The work item fills the run inputs: identifier is the key such as WEB-42, title the name, body the description converted to Markdown, url the work item link, status the state name, labels the labels, assignee and author the names of the assignees and the creator. event is issue. Pausing, versioning, and shared behavior are on Triggers.

Sessions on Work Items

A run started by a work item joins the session of that work item, like a run on a GitHub issue. The session keeps the checkout, the environment, and the agent conversation, so a second trigger on the same work item or a mention continues the work. The session closes when the work item reaches a state in the Completed or Cancelled group, is archived, or is deleted, its environment stops once no run needs it any more, and it opens again when the work item is moved back.

Knecht Holds the Work Item

Knecht joins the assignees of a work item while it works on it, as on every issue tracker, see Triggers. A work item takes several assignees, so the people already on it stay on it, and when Knecht leaves, they keep the work item. If Knecht was the only assignee, the work item goes to the person whose change started the run, else to the creator, else it is left unassigned.

The Agent on Work Items

When the run's session belongs to a work item, the agent gets four commands inside the environment. The prompt of an AI step only has to name what to do with them.

Read the work item. State, creator, assignees, labels, the description, and the last ten comments, live from Plane.
Reply. Posts a comment on the work item. The agent writes Markdown, Knecht converts it to Plane's format and appends the preview link and, when one exists, the pull request link. An @Name of a project member becomes a real mention that notifies that person.
Set labels. Adds or removes labels of the Plane project. Knecht never creates labels. If a name does not exist, the agent gets the list of existing labels instead.
Move the work item. Sets the state by name, for example "In Review". Plane has no transition rules, so every state of the project is reachable.

Opening a pull request works through the git steps or the agent's own command, see GitHub.

Mentions

Write a comment on a work item of a linked Plane project, mention the Knecht account the way you mention a colleague, and add the instruction:

@Knecht fix the broken footer link

@knecht typed as plain text works as well. Knecht runs the comment as a follow-up and posts the answer as a comment.

Whoever can comment on the work item can mention Knecht, the Plane workspace is the gate.

The one-time setup, what happens step by step, and what to check when Knecht stays silent is on Mentions.

Examples

The workflows below can be built in the editor or imported from YAML under Workflows, "Import". Triggers are added in the editor after the import. All of them assume the project is linked to its Plane project.

Software Factory

Three workflows that hand a work item from one to the next. The triage checks every new work item, sets the label Bug or Enhancement, and moves it to "Todo". That move fires the trigger of the workflow whose label condition matches. A bug comes back with a pull request and a work item in review, an enhancement with a plan that a mention in the comments turns into a pull request.

All of it runs in the session of the work item. The triage boots the site once and every later run finds it running, so only the triage has a boot step. The prompts do not repeat name or description, because the agent reads the work item of its session itself.

Plane creates the label Bug with every project, add Enhancement under the project settings, "Labels", first. Knecht only applies labels that exist, and a trigger only offers labels that exist. The state "In Review" is not a default either: add it under "States" in the Started group, a state in the Completed group would close the session.

Triage

Source	Fires When	But Only If
Plane	Created	No conditions

plane-work-item-triage.yaml

version: 1
name: Plane Work Item Triage
description: Check every new work item and label it as bug or enhancement.
steps:
  - type: ddev-start
    id: boot_project
  - type: ai
    prompt: >-
      Read the work item of this session. Try to reproduce it in the preview and
      in the code. Do not fix anything. Then apply exactly one label: "Bug" if
      something is broken, "Enhancement" if it was never built and then move it
      to "Todo".

      If the work item lacks the details to decide, apply no label and ask the
      creator in a comment for clarification.
    id: triage
    label: Triage

Bug Fix

Source	Fires When	But Only If
Plane	State reached: `Todo`	Label is `Bug`

plane-bug-fix.yaml

version: 1
name: Plane Bug Fix
description: Fix a work item labeled as bug and open a pull request.
steps:
  - type: ai
    prompt: >-
      The work item of this session was confirmed as a bug. When you are
      beginning your work move the work item to "In Progress". Then fix it on a
      work branch, verify the fix on the preview, commit in logical batches, and
      open a pull request.

      Comment a short summary of the change on the work item and move it to "In
      Review".
    id: bug_fix
    label: Bug Fix

Add Enhancement

Source	Fires When	But Only If
Plane	State reached: `Todo`	Label is `Enhancement`

plane-add-enhancement.yaml

version: 1
name: Plane Add Enhancement
description: Plan a work item labeled as enhancement and post the plan.
steps:
  - type: ai
    prompt: >-
      The work item of this session is an enhancement.

      Work out how it would be built in this project: the files to touch, the
      steps in order, and what is open.

      Do not change any files or the state. Just post the plan as a comment,
      written for the person who created the work item.
    id: plan_enhancement
    label: Plan Enhancement

When the team agrees with the plan, a comment that mentions the Knecht account, such as "implement it and open a PR", is enough. Knecht continues in the same session and answers with the pull request.

A work item that a person labels and moves to "Todo" without the triage having seen it starts these workflows without a booted site. Add a boot step to them if that happens in your team.

Urgent Bugs to Knecht

No triage: the team assigns a work item to the Knecht account like to any colleague, and Knecht implements it. The conditions keep it to urgent bugs, everything else assigned to Knecht stays untouched. This workflow stands on its own, so it boots the site itself.

Source	Fires When	But Only If
Plane	Assigned to Knecht	Label is `Bug` and Priority is `urgent`

plane-assigned-work-item.yaml

version: 1
name: Plane Assigned Work Item
description: Implement a work item that was assigned to Knecht.
steps:
  - type: ddev-start
    id: boot_project
    label: Boot the Site
  - type: ai
    prompt: The work item of this session was assigned to you. Read it with its
      comments, implement it on a work branch, verify it on the preview, commit,
      and open a pull request. Comment a short summary on the work item and move
      it to "In Review".
    id: implement
    label: Implement

Estimate Work Items

A work item that is moved to "In Planning" gets an estimate and lands in "Todo". The agent reads the work item, looks up the code it touches, and comments how big the work is and why. An estimate needs the code, not the running site, so there is no boot step. Pick the exact state of your project in the trigger, the names here are examples.

Source	Fires When	But Only If
Plane	State reached: In Planning	No conditions

plane-estimate-work-item.yaml

version: 1
name: Plane Estimate Work Item
description: Estimate a work item in planning and move it to Todo.
steps:
  - type: ai
    prompt: 'Estimate the work item of this session. Find the code it touches and
      judge the effort. Do not change any files. Comment the estimate on the
      work item: a size (S, M, L, or XL), the hours you expect, what drives the
      effort, and what is unclear. Then move the work item to "Todo". If it is
      too vague to estimate, comment your questions and leave it where it is.'
    id: estimate
    label: Estimate

Was this page helpful?

Provide Feedback to this Page

Jira

Everything you need to know about the Jira integration. What it can do and how to set it up.

Linear

Everything you need to know about the Linear integration. What it can do and how to set it up.