Configuration Loader Reference¶

ConfigurationLoader is the engine that turns .kiket/ files into live boards, workflows, automations, and dashboards. Every sync job (CLI, admin “Sync Now”, marketplace install) runs the same loader so customers and internal teams share the exact behaviour. This guide documents each ingest path, the files it expects, where the data ends up, and how to troubleshoot problems.

Search order & diagnostics¶

ConfigurationLoader looks for definitions in the following order (first match wins):

.kiket/ inside the connected workflow repository.
The project repository root (/workspaces/<repo> in hosted environments).
Organization-level repositories connected via Settings → Workflow Repositories.
Definitions bundled with marketplace packages or defaults shipped under storage/workflow_sources.

Every run records a ProjectConfigurationSyncLog. You can review the results in:

Settings → Workflow Repositories → {repo} – the “Definition diagnostics” alert shows failures and links back to the offending files.
Admin → Extensions → Invocations – the Diagnostics column now surfaces structured payloads for extension invocations if any automation step fails.
CLI: kiket doctor run --workflows --extensions calls /api/v1/diagnostics so you can see the same guidance locally.

To replay the loader without the UI, use the kiket sync CLI command or trigger a manual sync from the Workflow Repositories page.

Ingest matrix¶

Surface	Files / Location	Stored in
Project manifest	`.kiket/project.(yml\|yaml)`	`project.settings["manifest"]`
Board definitions	`.kiket/boards/*.yml` or `board.yml`	Boards + columns
Workflow definitions	`.kiket/workflows/<key>.(yml\|yaml)`	`project.workflow_definition` (via `WorkflowLoader`)
Capacity profiles	`.kiket/workflows/<key>/capacity.yml`	`project.settings["capacity"][key]`
Automation recipes	`.kiket/workflows/<key>/automation_recipes/*.yml`	`automation_recipes` tables keyed by workflow
Extension manifests	`.kiket/extensions/**/manifest.yml` or root `manifest.yml`	`project.settings["extension_manifests"]`
Agent definitions	`.kiket/agents/*.yml`	`project.settings["agents"]`
Dashboards	`.kiket/dashboards/.yml` or `.kiket/analytics/dashboards/.yml`	`project.settings["dashboards"]`
Query definitions	`.kiket/queries/.yml` or `.kiket/analytics/queries/.yml`	`project.settings["queries"]`
Custom data modules	`.kiket/modules/<namespace>/schema.yml`	`custom_data_modules` records + namespaces
Team config	`.kiket/team.(yml\|yaml)`	`project.settings["team"]`
Team calendar	`.kiket/team_calendar.(yml\|yaml)`	`project.settings["team_calendar"]`

Each section below explains the schema expectations and how to recover from errors.

Project manifest¶

Purpose: declare the workspace name, default board, issue templates, and repository-level metadata.
Files: .kiket/project.yml or .kiket/project.yaml.
Troubleshooting: Validation failures appear as Project manifest error entries in the sync log. Re-run the sync from Workflow Repositories or kiket sync after fixing the YAML. Missing mandatory keys (workflow, boards, etc.) will stop the rest of the loader until fixed.

Board definitions¶

Purpose: define Kanban/Scrum columns, WIP limits, swimlanes, and per-column automations.
Files: .kiket/boards/<board>.yml or a single board.yml.
Troubleshooting: Duplicate column keys or mismatched workflow states show up as “Board configuration error in …”. Use Boards → Sync in the UI to reload a single board or run ConfigurationLoader#load_board_configurations. Board changes are non-destructive; you can revert by checking out the previous YAML.

Workflow definitions¶

Purpose: describe allowed states, transitions, conditionals, and extension hooks.
Files: .kiket/workflows/<workflow>.yml.
Troubleshooting: Parser or schema errors bubble up as “Workflow loading error” and the loader falls back to the last valid definition. Use kiket workflows lint (or trigger a dry-run sync) to confirm changes before syncing.

Capacity profiles¶

Purpose: set per-workflow capacity (story points, hours, lead time targets) that power the capacity dashboard.
Files: .kiket/workflows/<workflow>/capacity.yml.
Troubleshooting: Only one capacity file per workflow key is allowed; duplicates trigger the “Duplicate capacity configuration” diagnostic. Remove extra files or rename the workflow directory.

Automation recipes¶

Purpose: reusable actions for workflow states (notifications, approvers, assignments).
Files: .kiket/workflows/<workflow>/automation_recipes/*.yml.
Troubleshooting: Keys must be unique per workflow. Diagnostics call out the duplicate key and the files involved. Use kiket automation lint or the ConfigurationLoader#load_automation_recipes runner to test locally.

Extension manifests¶

Purpose: register inline extensions or marketplace bundles that ship with the definition repo.
Files: .kiket/extensions/**/manifest.yml or a root manifest.yml.
Troubleshooting: Schema errors surface as “Extension manifest error in …”. Remember that manifests with identical IDs override each other; use kiket extensions lint to validate.

Agent definitions¶

Purpose: enable AI agents (context, prompts, safety settings) that show up in the command palette.
Files: .kiket/agents/*.yml.
Troubleshooting: A failed agent definition prevents that agent from appearing but does not block the rest of the loader. Messages include the exact parser error. See Agent Definition DSL for the schema.

Dashboard definitions¶

Purpose: configure analytics dashboards shipped with marketplace packages or org templates.
Files: .kiket/dashboards/*.yml or .kiket/analytics/dashboards/*.yml.
Troubleshooting: The parser wraps errors with “Dashboard definition error”. Ensure every panel references an existing query ID.

Query definitions¶

Purpose: define DSAL/SQL queries that power dashboards, skill matrices, and automation.
Files: .kiket/queries/*.yml or .kiket/analytics/queries/*.yml.
Troubleshooting: The loader enforces the current schema version; mismatches produce SchemaVersion errors. Use the analytics lint command (kiket analytics lint) or rerun the sync to validate locally.

Custom data modules¶

Purpose: register custom tables (modules) so extensions and workflows can read/write domain-specific records.
Files: .kiket/modules/<namespace>/schema.yml.
Troubleshooting: Failed migrations or duplicate module IDs halt module sync but allow the rest of the loader to continue. Diagnostics point to Custom data module error. Verify the namespace matches the repository and avoid renaming modules without a migration plan.

Team configuration¶

Purpose: seed team members, roles, and default reviewers for a project.
Files: .kiket/team.yml.
Troubleshooting: YAML errors or missing keys (members, role, etc.) result in “Team configuration error”. You can clear the configuration by removing the file and re-running the loader.

Team calendar¶

Purpose: define working hours, holidays, and rotations for capacity planning.
Files: .kiket/team_calendar.yml.
Troubleshooting: If the file is deleted, the loader automatically clears the calendar (project.settings["team_calendar"] = nil). Use kiket doctor --workflows to verify the calendar synced.

Troubleshooting checklist¶

Review sync logs: Admin → Workflow Repositories lists every run with timestamps, errors, and the new Diagnostics alert.
Use the CLI: kiket doctor run --workflows --extensions pulls the same diagnostics JSON exposed via /api/v1/diagnostics.
Re-run specific loaders: Targeted sync commands (kiket boards sync, kiket workflows lint, etc.) let you focus on a subset of definitions without waiting for the full pipeline.
Check permissions: Ensure the GitHub token connected to the workflow repository can read the relevant directories.
Isolate via branches: Use feature branches for configuration changes; the loader will pick up whichever branch the workflow repository is pinned to.

When opening support tickets, include the ProjectConfigurationSyncLog ID, the repository/branch, and the file path called out in the diagnostics so the ops team can reproduce the issue quickly.

Multi-repository configurations¶

Projects can attach multiple workflow repositories to compose configurations from different sources. This is useful for combining a base template (like Scrum or Kanban) with domain-specific modules (like Engineering, Support, or Sales workflows).

How it works¶

When multiple repositories are attached:

Merging: Definitions from all active repositories are merged into the project
Conflict detection: If two repositories define the same workflow ID, the system raises a conflict error
Explicit overrides: Add override: true to a workflow definition to intentionally replace one from another repository
Board tracking: Each board tracks its source workflow via the workflow_key field

Example: Platform + Engineering module¶

# Base repository: platform workflows
# .kiket/workflows/development.yaml
workflow:
  id: development
  name: Development Workflow
  states: [backlog, in_progress, review, done]

# Engineering module repository
# .kiket/workflows/bug.yaml
workflow:
  id: bug
  name: Bug Tracking
  states: [reported, triaging, fixing, testing, resolved]

# .kiket/workflows/incident.yaml
workflow:
  id: incident
  name: Incident Response
  states: [detected, investigating, mitigating, resolved]

After syncing, the project has three workflows: development, bug, and incident.

Handling conflicts¶

If both repositories define the same workflow ID:

Workflow 'main' is already provided by platform-repo;
engineering-repo attempted to override it without `workflow.override: true`.

To resolve:

Rename one workflow to use a unique ID
Add explicit override if the override is intentional:

workflow:
  id: main
  name: Custom Main Workflow
  override: true  # Explicitly overrides the other repository
  states: [...]

Stale board cleanup¶

When boards are removed from a workflow repository, the next sync automatically deletes them from the project (if workflow_auto_boards is enabled). Manually created boards are never automatically deleted.