Configuration Reference

Use this reference when authoring .kiket/ directories across repositories.

Directory Layout

.kiket/
├── workflows/
├── boards/
├── analytics/
│   ├── metrics/
│   ├── dashboards/
│   └── reports/
├── extensions/
├── email_templates/
├── project.yaml
├── team.yaml
├── inbound_email.yaml
└── config.yaml

Key Files

• project.yaml – Project metadata, integrations, defaults, and normalized team/permission data. The loader applies .kiket/project.yaml after every workflow sync, creating pending memberships for email-only entries, storing team.defaults, and reconciling manifest-managed integrations.
• team.yaml – Roles, permissions, and onboarding checklists.
• config.yaml – Feature flags, sync configuration, environment overrides.
• inbound_email.yaml – Email-to-issue mappings, sender policies, and auto-reply configuration.
• workflows/*.yaml – Workflow state machines.
• boards/*.yaml – Kanban, Scrum, and timeline boards.
• analytics/**/*.kql – DSAL metrics and reports.
• extensions/*/manifest.yaml – Extension manifests.
• email_templates/*.liquid – Liquid templates for auto-reply emails.

Loader Behavior Highlights

• Email-only team members in manifests become ProjectMembership invitations (with invited_at) until the user signs up.
• Role definitions, groups, and defaults from the manifest are cached under project.settings['team'] for fast UI access.
• project_permissions now always contains allowed_actions, inheritance, and public keys, even when omitted in YAML.
• Manifest-managed integrations are reconciled on each sync—missing entries are removed, and survivors receive refreshed settings and timestamps.
• Workflows define states only; keep board layouts in .kiket/boards/*.yaml and reference them from project.yaml.
• Every configuration artifact must declare model_version (current schema: 1.0) so future parser changes can be rolled out safely.

Project Manifest Deep Dive

model_version: 1.0
version: "1.0"
project:
  name: "Payments Platform"
  key: "PAY"
  visibility: team
  settings:
    auto_assign: true
    require_approval: false

team:
  lead: lead@acme.dev
  defaults:
    role: developer
    groups:
      - Core Services
  members:
    - email: alice@acme.dev
      role: developer
    - email: qa@acme.dev
      role: qa
  roles:
    - name: developer
      permissions: ["issues:*", "deploys:staging"]
    - name: qa
      permissions: ["issues:comment", "tests:run"]
  groups:
    - name: Core Services
      members:
        - lead@acme.dev
        - alice@acme.dev

permissions:
  default: developer
  public: false
  allowed_actions: [read, comment, vote]
  overrides:
    postmortems:
      visibility: private

integrations:
  - type: github
    enabled: true
    config:
      repo: acme/payments
  - type: slack
    enabled: true
    config:
      channel: "#payments-alerts"

boards:
  - boards/sprint-board.yaml
  - boards/research-board.yaml

workflows:
  - workflows/default.yaml
  - workflows/release-management.yaml

The manifest wires together the discrete configuration files. During sync the loader:

1. Applies project metadata and settings.
2. Creates or updates manifest-managed memberships (inviting email-only members when necessary) and stores team.defaults.
3. Hydrates project_permissions with defaults and overrides even if portions were omitted from YAML.
4. Reconciles integrations sourced from the manifest—missing entries are pruned, surviving records are refreshed.
5. Resolves referenced workflow and board files using the loader precedence (repository → project → organization → defaults).

Workflow File Anatomy

model_version: 1.0
name: "Release Management"
version: 1.0
states:
  planned:
    type: initial
    metadata:
      description: "Scope captured and ready to execute"
  ready_for_qa:
    type: active
    metadata:
      icon: 🧪
  qa_in_progress:
    type: active
    wip_limit: 5
  ready_for_release:
    type: active
  releasing:
    type: active
  completed:
    type: final

transitions:
  - from: planned
    to: ready_for_qa
    name: start_qa
    guards:
      - checklist: release_planning
  - from: ready_for_qa
    to: qa_in_progress
    name: begin_testing
  - from: ready_for_release
    to: releasing
    name: deploy
    guards:
      - approvals:
          roles: [lead, product]
  - from: releasing
    to: completed
    name: close_release

checklists:
  release_planning:
    - Risks documented
    - Rollback plan published

Keep workflow files focused on business flow: states, transitions, guards, and automation. Avoid embedding board definitions—reference dedicated board configs instead.

Board Files

model_version: 1.0
name: "Sprint Board"
type: kanban
workflow: default
columns:
  - name: Sprint Backlog
    states: [todo]
    wip_limit: 20
  - name: In Development
    states: [in_progress]
    wip_limit: 10
  - name: Peer Review
    states: [review]
    wip_limit: 6
  - name: Done
    states: [done]
    wip_limit: 40

swimlanes:
  enabled: true
  group_by: assignee
  show_empty: false

filters:
  labels:
    exclude: [research]

card_template:
  fields:
    primary: [title, assignee]
    secondary: [story_points, due_date]
  badges:
    - type: priority

Create as many board files as you need (.kiket/boards/*.yaml). Manifests reference them by path, letting teams share workflows while tailoring visual boards per project.

Tips for Board Definitions

• Ensure every workflow state used in the project is mapped to at least one column—otherwise cards in those states disappear from the board.
• Use filters to create specialized views (e.g., exclude research items from a delivery board).
• Prefer swimlanes when you need secondary grouping (assignee, priority, epic).
• Keep card templates minimal on busy boards; detailed cards can land in secondary views (e.g., report dashboards).

Project Custom Fields

Define project-level fields inside .kiket/project.yaml (or in a dedicated .kiket/custom_fields.yaml that the manifest references) so the configuration loader can create or update issue_field_definitions during syncs. Each entry should at least provide a field_key, label, data_type, and project key. Supported data types: string, text, number, boolean, enum.

model_version: 1.0
project:
  key: platform-v2
  name: "Platform V2"
  custom_fields:
    - field_key: customer_impact
      label: Customer Impact
      data_type: enum
      options: [low, medium, high, critical]
      issue_type: UserStory
      helper_text: "How visible is this change to customers?"
      position: 5
      show_in_table: true
      show_in_popover: true
    - field_key: go_live_blocker
      label: Go-Live Blocker
      data_type: boolean
      default: false
      required: true
      position: 10
      show_in_table: true
      show_in_popover: true

• Create new fields by adding entries with unique field_key values. The sync job upserts definitions without touching existing issue data or existing values.
• Edit labels, helper text, defaults, enum options, or requirement flags directly in YAML; rerun the sync to push changes consistently to every environment. Existing issue_field_values remain intact.
• Reorder by adjusting position (lower numbers render first in forms, detail panes, and exports). Update multiple fields at once; the loader applies the changes in a single transaction.
• Deprecate by setting active: false to hide a field while preserving historical values; remove the block entirely when downstream automation no longer depends on it. You can re-enable later by flipping active: true without data loss.

Additional attributes: use options for enums, issue_type to scope a field to a specific issue type, scope: organization when a definition should be shared across projects from a single repository, and show_in_table / show_in_popover to opt the field into or out of index table columns and quick-view popovers. For shared repositories managing multiple project manifests, include the project: slug to target the desired project configuration.

Issue Templates

Issue templates live in .kiket/templates/issues/*.yaml. Sync jobs parse each file, validate the schema, and publish active templates to projects or the entire organization depending on scope.

model_version: 1.0
template:
  key: feature_request
  name: Feature Request
  description: Capture user problems and desired outcomes.
  scope: organization # auto (default), organization, project, or project_key
  defaults:
    issue_type: UserStory
    priority: medium
    status: "To Do"
    labels: [feature, discovery]
    custom_fields:
      product_area: core
  required_fields:
    - description
  fields:
    product_area:
      type: enum
      options: [core, growth, platform]
      hint: "Select the product area impacted by this feature."
    expected_value:
      type: text
      placeholder: "Summarize the user value and business impact."
    high_risk:
      type: boolean
      boolean_label: "This feature carries notable risk"

• key must be unique per organization/project combination; it is what the UI submits when a user selects the template.
• scope controls visibility:
• auto (default) follows the repository context (project-specific repos map to that project; organization repos stay global).
• organization makes the template available to every project in the org.
• project restricts to the associated repo’s project.
• project_key requires a project/project_key entry in the payload to target another project explicitly.
• defaults pre-populate issue attributes (including custom_fields). Values only apply when the field is blank, so manual edits are preserved.
• required_fields ensures the issue cannot be saved until those attributes are filled.
• fields describes template-specific custom fields. Supported types: string, text, number, boolean, and enum (requires options).

Inbound Email Configuration

Configure email-to-issue functionality in .kiket/inbound_email.yaml:

inbound_email:
  enabled: true
  mappings:
    - email_address: support@acme.inbound.kiket.dev
      description: Customer support inbox
      sender_policy: open          # open | known_users | known_domains
      issue_defaults:
        issue_type: Ticket
        priority: medium
        status: todo
        labels:
          - support
          - incoming
      auto_reply: true
      auto_reply_template: confirmation
      blockchain_anchoring: false

    - email_address: bugs@acme.inbound.kiket.dev
      description: Bug reports
      sender_policy: known_users
      issue_defaults:
        issue_type: Bug
        priority: high
      auto_reply: true
      auto_reply_template: bug_received

Sender Policies

Policy	Description
open	Accept emails from anyone (default)
known_users	Only accept from organization members
known_domains	Only accept from domains with existing org members

Auto-Reply Templates

Place Liquid templates in .kiket/email_templates/. Available variables:

• inbound_email.from_name, inbound_email.from_email, inbound_email.subject
• issue.key, issue.title, issue.url, issue.status, issue.priority
• organization.name, organization.subdomain
• project.name, project.key

See the Inbound Email Guide for complete setup instructions.

Naming Conventions

• Use lowercase, hyphen-separated filenames (development.yaml, incident-response.yaml).
• Keep keys unique per project (workflow field) to avoid collisions.
• Prefix experimental configs with _ if you do not want them synced yet.

Provenance Metadata

• Sync jobs add provenance data (repository, path, commit) to boards and workflows.
• Use this data in the UI to trace configuration origins.

Validation Commands

• kiket definitions lint – Lint all definition assets
• kiket workflows validate
• kiket boards validate
• kiket analytics lint
• kiket extensions lint

The definitions lint command validates projects, workflows, dashboards, inbound email configs, and dbt models. Use flags to skip specific categories:

kiket definitions lint --no-inbound-email --no-dbt

Environments

• Use config.yaml to designate environments (dev/staging/prod) and override feature flags or endpoints per environment.
• Repositories can contain multiple environment folders (environments/dev/config.yaml).

This reference complements the deeper internal configuration-as-code guides shared through the customer enablement portal.