dreampiler/kandev
1
0
Fork 0
Code Issues 43 Pull Requests Actions 6 Packages Projects Releases Wiki Activity

docs(plugins): sync WorkflowStep field docs with the shipped contract (#3183)

Browse Source 
Co-authored-by: nova28 <17953305+nova28@users.noreply.github.com>
Co-authored-by: Carlos Florencio <carlosmflorencio@gmail.com>
This commit is contained in:
Henry
2026-08-31 12:28:36 +00:00
committed by GitHub
parent 4b420f4950
commit 2e6f2eb84a
2 changed files with 20 additions and 2 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/plans/plugins/HOST-DATA-API.proto
+13 -1
View File
@@ -1,7 +1,16 @@
// kandev.plugin.v1 Host data API — folded into
// apps/backend/proto/kandev/plugin/v1/plugin.proto and fully wired (reads and
// writes both implemented). This file is the frozen design draft kept for
// reference alongside the ADRs.
// reference alongside the ADRs: a point-in-time SNAPSHOT that has NOT tracked
// the contract since it was written. For the live shape, read
// apps/backend/proto/kandev/plugin/v1/plugin.proto (wire contract) and
// apps/backend/pkg/pluginsdk/data_types.go (Go SDK mirror) directly — do not
// infer current fields from this file. Examples of known-diverged messages
// (not exhaustive — other messages in this file may also have drifted):
// `Task` (17 fields here vs 29 live), `WorkflowStep` (5 here vs 10 live —
// missing `color`, `is_start_step`, `wip_limit`, `agent_profile_id`,
// `on_enter_action_types`), and `Message` (absent here; the whole
// `ListMessages` read path from ADR 0047 postdates this draft).
//
// Extends the existing capability-gated Host service so plugins read AND write
// kandev data through a typed, versioned contract instead of touching the
@@ -133,6 +142,9 @@ message Workflow {
message ListWorkflowsRequest { string workspace_id = 1; Page page = 2; }
message ListWorkflowsResponse { repeated Workflow workflows = 1; PageInfo page_info = 2; }
// DIVERGED from the live contract — see canonical
// apps/backend/proto/kandev/plugin/v1/plugin.proto for fields 6-10
// (color, is_start_step, wip_limit, agent_profile_id, on_enter_action_types).
message WorkflowStep {
string id = 1;
string workflow_id = 2;
docs/specs/plugins/system-design/plugins-02.md
+7 -1
View File
@@ -252,7 +252,7 @@ domain structs. See [ADR 0043](../../../decisions/0043-plugin-host-data-api.md)
| `ListTasks` / `GetTask` | `api_read:tasks` | Tasks (id, workspace, workflow, title, description, state, priority, timestamps, parent, identifier, repositories, metadata) |
| `ListWorkspaces` | `api_read:workspaces` | Workspaces (id, name, owner, defaults, timestamps) |
| `ListWorkflows` | `api_read:workflows` | Workflows for a workspace |
| `ListWorkflowSteps` | `api_read:workflows` | Steps for a workflow (id, name, position, stage type) |
| `ListWorkflowSteps` | `api_read:workflows` | Steps for a workflow (`id`, `workflow_id`, `name`, `position`, `stage_type`, `color`, `is_start_step`, `wip_limit`, `agent_profile_id`, `on_enter_action_types`) |
| `ListAgentProfiles` | `api_read:agent_profiles` | Agent profiles (id, agent id, display name, model, mode) |
| `ListExecutorProfiles` | `api_read:executor_profiles` | Executor profiles (id, display name, executor type) |
| `ListRepositories` | `api_read:repositories` | Repositories for a workspace (id, name, default branch) |
@@ -267,6 +267,12 @@ aggregate the agent-stats plugin previously re-derived by hand from
`task_session_commits` and `task_session_git_snapshots` — so plugins never touch
those raw rows.
`on_enter_action_types` on a step lists the on-enter action *types* configured
for that step (e.g. `auto_start_agent`, `queue_run`), never the action
*config* — target task ids, payloads, and profile ids stay server-side. A type
appearing in this list means it is configured, not a guarantee of when or
whether it fires. Plugins must ignore action types they do not recognize.
**Conversation content (`api_read:messages`, ADR 0047).** `ListMessages` reads
historical user/agent message content — the data a "summarize yesterday"
plugin needs, which the `message.added` bus event alone (live-only,