builder-conventions
Project-specific conventions and patterns for the builder agent. Maintains synchronization between template and live project files.
- License 许可
- MIT
- 所属仓库
- jbrinkman/kairon
- 最近更新
- 2026-11-06
- Stars
- ★ 3
- Forks
- 1
01 前言 Front Matter
- name
- builder-conventions
- description
- Project-specific conventions and patterns for the builder agent. Maintains synchronization between template and live project files.
03 SKILL.md 正文
Builder Conventions
Project-specific conventions, patterns, and best practices for the builder agent to follow during implementation tasks.
Mandatory Template Synchronization
Critical for Self-Hosting: Kairon uses itself to build itself. Live project files and embedded templates must stay in sync so that kairon init and kairon update always deploy current configurations.
Sync is one-way (live → template). CI enforces this via task sync:check in the Validate PR workflow.
Sync Mappings
| Live Path | Template Path |
|---|---|
.kiro/agents/*.json |
cmd/kairon/templates/kiro/agents/ |
.kiro/agents/*.md |
cmd/kairon/templates/kiro/agents/ |
.kairon/scripts/*.sh |
cmd/kairon/templates/kairon/scripts/ |
.kairon/themes/*.yaml |
cmd/kairon/templates/kairon/themes/ |
.kairon/evals/fixtures/* (files only; not workspaces/ or hidden/) |
cmd/kairon/templates/kairon/evals/fixtures/ |
.kairon/evals/fixtures/workspaces/<name>/ (only workspaces named by a shipped case's workspace:; any other workspace stays live-only) |
cmd/kairon/templates/kairon/evals/fixtures/workspaces/<name>/ |
.kairon/evals/rubrics/* |
cmd/kairon/templates/kairon/evals/rubrics/ |
.kairon/evals/cases/**/* |
cmd/kairon/templates/kairon/evals/cases/ |
.kiro/skills/sentinel-protocol/* |
cmd/kairon/templates/kiro/skills/sentinel-protocol/ |
.kiro/skills/planner-shared/* |
cmd/kairon/templates/kiro/skills/planner-shared/ |
Exclusion Patterns
Never sync *-conventions skills — they are project-specific and must NOT be distributed in templates.
Sync Commands
Run the appropriate commands after modifying any template-synchronized files:
# Agent files (JSON configs and prompt files)
cp .kiro/agents/*.json cmd/kairon/templates/kiro/agents/
cp .kiro/agents/*.md cmd/kairon/templates/kiro/agents/
# Scripts
cp .kairon/scripts/*.sh cmd/kairon/templates/kairon/scripts/
# Themes
cp .kairon/themes/*.yaml cmd/kairon/templates/kairon/themes/
# Evals (excluding results directory)
# Fixtures: copy regular files only. Subdirectories (fixtures/workspaces/,
# fixtures/hidden/) are excluded from the bulk comparison, and
# `cp .kairon/evals/fixtures/*` would fail on them.
find .kairon/evals/fixtures -maxdepth 1 -type f -exec cp {} cmd/kairon/templates/kairon/evals/fixtures/ \;
# Mirrored workspaces: a workspace named by a shipped case's `workspace:` must
# ship in the templates (the case fails to load without it). sync:check diffs
# each workspace present in the templates against its live counterpart, and
# TestShippedCaseWorkspacesAreMirroredInTemplates checks every one a case names.
# Replace <name> (e.g. planner-evidence); rm first so deleted files do not linger.
rm -rf cmd/kairon/templates/kairon/evals/fixtures/workspaces/<name>
mkdir -p cmd/kairon/templates/kairon/evals/fixtures/workspaces
cp -r .kairon/evals/fixtures/workspaces/<name> cmd/kairon/templates/kairon/evals/fixtures/workspaces/<name>
cp .kairon/evals/rubrics/* cmd/kairon/templates/kairon/evals/rubrics/
mkdir -p cmd/kairon/templates/kairon/evals/cases/
cp -r .kairon/evals/cases/* cmd/kairon/templates/kairon/evals/cases/
# Kairon-managed planner skill (planner-conventions is project-owned: never sync it)
mkdir -p cmd/kairon/templates/kiro/skills/planner-shared/
cp .kiro/skills/planner-shared/* cmd/kairon/templates/kiro/skills/planner-shared/
Verification
Run task sync:check to verify all template-synchronized files match. This is the same check CI runs — if it passes locally, CI will pass.
task sync:check
If verification fails, re-run the sync commands above for the affected file category, then re-run task sync:check.
Workflow Integration
When completing tasks that modify template-synchronized files, follow this sequence:
- Implement — complete the assigned task
- Sync — run the appropriate sync commands from above
- Verify — run
task sync:check(task cannot be marked complete if this fails) - QA — run
task lintandtask test - Complete — create sentinel file documenting results
Sentinel File Requirements
Include sync verification status in sentinel files:
## Task Complete
**Template Sync**: ✅ VERIFIED (or "N/A - no template files modified")
**QA Results**:
- Linting: ✅ PASS
- Tests: ✅ PASS
- Sync Verification: ✅ PASS
**Sync Commands Used**:
- `cp .kiro/agents/builder.json cmd/kairon/templates/kiro/agents/`
Implementation Patterns
Quality Assurance
- Run ALL discovered QA commands before completion
- Use QA discovery results from
.kairon/artifacts/qa-tools.md - Document specific QA command sources (CI vs build tool)
File Modifications
- Preserve existing formatting and structure
- Maintain JSON validity for configuration files
- Verify template sync before task completion
- Document changes in sentinel files including sync status
Error Recovery
- Address validator feedback from
.kairon/artifacts/validator-<issue>.md - Focus on specific failing commands identified by validator
- Include sync verification in error recovery process
- Document how feedback was incorporated
Project Standards
Code Quality
- Follow existing code style and conventions
- Use project's configured linting and formatting tools
- Ensure all tests pass (100% pass rate required)
Documentation
- Update relevant docs when adding features
- Follow project's documentation format
- Include usage examples for new functionality
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.