sentinel-protocol
Core Kairon completion-signalling protocol. Defines the sentinel file path format and write rules that every pipeline agent uses to signal task completion to krew-lead, and that krew-lead uses to detect it. This is engine behavior, not a project convention — do not override it per project.
- License 许可
- MIT
- 所属仓库
- jbrinkman/kairon
- 最近更新
- 2026-11-06
- Stars
- ★ 3
- Forks
- 1
01 前言 Front Matter
- name
- sentinel-protocol
- description
- Core Kairon completion-signalling protocol. Defines the sentinel file path format and write rules that every pipeline agent uses to signal task completion to krew-lead, and that krew-lead uses to detect it. This is engine behavior, not a project convention — do not override it per project.
03 SKILL.md 正文
Sentinel Protocol
Kairon detects agent/task completion via sentinel files written to
.kairon/artifacts/, using a naming convention (NOT via agent JSON config
fields). This skill is the single source of truth for that path format and the
write rules. Every pipeline agent (architect, builder, validator, documenter)
writes a sentinel; krew-lead reads it. All of them reference this skill so the
convention is defined once.
Path Format
Plan-based tasks (a task has an id):
.kairon/artifacts/<agent>-<issue-number>-<task-id>.md
<agent>— the writing agent's name (e.g.builder,validator).<issue-number>— the GitHub issue number being processed.<task-id>— the plan task'sidfield (unique per plan).
Including <task-id> is required: a single plan can assign several tasks to
the same agent (e.g. two builder tasks). Without the task id those tasks
would write and read the same file, so a later task could overwrite an
earlier task's sentinel, or a completion check could misread a stale sentinel
from a previous task as the current task's success.
Legacy / non-plan fallback
When there is no plan and therefore no task id (the legacy sequential workflow), and for whole-issue signals that are not tied to a specific plan task, use the task-less form:
.kairon/artifacts/<agent>-<issue-number>.md
A reader that expects a plan task MUST use the <task-id> form and MUST NOT
fall back to the task-less form to satisfy a task-scoped check (that is exactly
the stale-read this protocol prevents).
Write Rules (writing agents)
- After completing your work, write your sentinel at the path above for your agent name, the current issue number, and — for a plan task — the task id.
- Write to that path only. Do not write sentinels for other agents or tasks.
- Include a brief summary of what you produced so krew-lead can recover your result from the file if your response is otherwise empty.
- A sentinel's presence with a success summary signals successful completion.
- If you could not deliver all of your assigned work, write the sentinel with
**Status**: BLOCKED, quote each item you could not deliver, and say why. Never write a success summary for partial work. krew-lead treats BLOCKED as a failure and escalates it to a human.
Read Rules (krew-lead)
- A plan task is complete only when its task-scoped sentinel
(
<agent>-<issue-number>-<task-id>.md) exists with a success status. - On an empty subagent response, check for the sentinel before retrying:
test -f .kairon/artifacts/<agent>-<issue-number>-<task-id>.md; if it exists, read it to recover the summary and continue; if missing, proceed with normal retry escalation. - Never accept a task-less sentinel as proof a specific plan task completed.
- A sentinel with
**Status**: BLOCKEDis a failure, never a completion.
Examples (issue 42, plan task implement-api handled by builder)
- Plan task:
.kairon/artifacts/builder-42-implement-api.md - Legacy/no-plan builder:
.kairon/artifacts/builder-42.md
04 同仓库更多 Skills
selftest-conventions
Self-test override hook supplied by a case workspace fixture.
engine-skill
Engine skill for the audit fixtures.
demo-conventions
暂无简介
sentinel-protocol
Core Kairon completion-signalling protocol. Defines the sentinel file path format and write rules that every pipeline agent uses to signal task completion to krew-lead, and that krew-lead uses to detect it. This is engine behavior, not a project convention — do not override it per project.
planner-shared
Kairon-managed contract shared by both planner agents. Defines the restrictions, the stage-output document the planner returns, how to investigate and classify a request, the issue-body standard and the hard bars.
validator-conventions
Structured templates and patterns for strict criterion-by-criterion validation. Enforces exact specification compliance and provides copy-paste report templates.