Documentation

Environment Variables

All configuration is done through .kntic.env in your project root. Copy bootstrap-templates/kntic.env as your starting point.

Required

.kntic.env is listed in .gitignore and must never be committed to version control.

Required in remote mode (KNTIC_REMOTE_ENABLED=true)

These variables are only required when the orchestrator connects to a remote git repository (the default). When running in local-only mode (KNTIC_REMOTE_ENABLED=false), they can be left empty.

Authentication

Orchestrator

Agent

Container Runtime

General

Task Manifests

Tasks are defined as JSON files in .kntic/manifests/. The dashboard provides a UI for creating and editing them; you can also write them by hand.

Minimal example

{
  "task_id": "FEAT-001",
  "title": "Add user authentication",
  "status": "todo"
}

Full example

{
  "task_id": "FEAT-001",
  "title": "Add user authentication",
  "description": "Implement JWT-based login and session management.",
  "status": "todo",
  "priority": "high",
  "depends_on": ["INFRA-003"],
  "requirements": {
    "features": [
      "POST /auth/login endpoint returning a signed JWT",
      "Token expiry of 24 hours",
      "401 response on invalid credentials"
    ],
    "files_to_create": ["src/auth.py", "tests/test_auth.py"]
  },
  "context_scope": {
    "read_only": [".kntic/adrs/"],
    "write_access": ["src/", "tests/"]
  },
  "notes": "Use the existing User model in src/models/user.py"
}

Status lifecycle

todo  →  in_progress  →  ready_for_merge  →  merged
               │    ↖
               ▼      └──── refactoring
          needs_review

backlog  →  (human promotes)  →  todo

⚠️ The status "done" does not exist. Using it will break orchestration.

Key fields

Omission rule: fields that are empty must be omitted entirely — never set to null, "", or [].

Orchestrator Behaviour

Pulse loop

The orchestrator runs in a continuous pulse loop (5-second interval). Each pulse processes exactly one task:

1. ready_for_merge — validate with GIA; merge and push on pass, set refactoring on fail.
2. todo / refactoring — claim and dispatch to the agent. refactoring always takes priority over todo to prevent a dirty working tree from contaminating the next task.
3. Idle — no actionable work. After 12 idle pulses (~1 minute), pull latest changes from remote.

Within each category, tasks are sorted by: status rank → priority → oldest updated_at first (FIFO).

Claim protocol (multi-orchestrator)

When multiple orchestrators run against the same repository, the claim protocol prevents conflicts:

1. Orchestrator writes status: in_progress + claimed_by + claimed_at to the manifest and pushes.
2. If the push is rejected (another orchestrator pushed first), the claim is abandoned and the task is skipped this pulse.
3. Stale claims (older than KNTIC_AGENT_TIMEOUT) are detected and reclaimed as needs_review.

GIA — Global Impact Analysis

Before any task is merged, the full GIA hook suite runs against the codebase. GIA produces a weighted alignment score (0.0–1.0). Merge is only allowed when the score meets the configured threshold.

Built-in GIA hooks:

When GIA fails, the failure reason, alignment score, dimension breakdown, and hook output are written back to the task manifest (gia_failure field) so the agent knows exactly what to fix on the next attempt.

Custom hooks can be added to .kntic/hooks/gia/specific/ and will be discovered automatically.

Dashboard

The dashboard is available at http://localhost:8000 (or the port configured via KNTIC_UI_PORT).

Features:

• Live task board with real-time WebSocket updates
• Create, edit, and manage task manifests through a structured form
• Per-status and per-prefix filtering
• GIA health indicator showing the current alignment score
• Actions audit log per task
• ADR and documentation viewer
• Repository link (when GIT_HOST and GIT_REPO_PATH are configured)

Authentication: when DASHBOARD_AUTH_TOKEN is set, all state-mutating API endpoints require a Bearer <token> header. The dashboard login page handles this automatically.

Installation

npm install -g @kntic/kntic

Or run directly without installing:

npx @kntic/kntic <command>

Commands

kntic usage

Display all available commands and their options.

kntic usage

Running kntic with no arguments also shows the usage screen.

kntic init

Bootstrap a new KNTIC project in the current directory. Downloads the latest bootstrap archive and scaffolds the full .kntic/ directory structure, kntic.yml (Docker Compose file), and .kntic.env (environment configuration).

kntic init              # Interactive mode (default)
kntic init --quick      # Non-interactive mode
kntic init -q           # Short alias for --quick

Modes

What it does

1. Preflight checks — Verifies the environment (warnings only, never blocks): platform, container runtime (Docker / Podman), GNU screen.
2. Downloads the latest bootstrap archive from the KNTIC artifact server.
3. Extracts the archive into the current directory. If a .gitignore already exists, the archive's entries are appended (with a # --- kntic bootstrap --- separator) instead of overwriting.
4. Auto-detects the git remote by parsing the origin remote URL — supports SSH (git@host:path) and HTTPS (https://host/path) formats. If a glpat-* token is found in the URL, it's extracted into GITLAB_TOKEN. No remote → sets KNTIC_REMOTE_ENABLED=false.
5. Auto-fills the detected compose provider into KNTIC_COMPOSE_PROVIDER.
6. Interactive setup (unless --quick): Prompts for each variable in .kntic.env.

Scaffolded structure

your-project/
├── .kntic/
│   ├── lib/            # Orchestrator engine code
│   ├── adrs/           # Architecture Decision Records
│   ├── hooks/
│   │   └── gia/
│   │       ├── internal/   # Built-in GIA validation hooks
│   │       └── specific/   # Project-specific GIA hooks
│   ├── gia/
│   │   └── weights.json    # GIA scoring weights
│   ├── manifests/      # Task manifests (JSON)
│   └── docs/           # Project documentation
├── kntic.yml           # Docker Compose file for KNTIC services
├── .kntic.env          # Environment configuration
└── .gitignore          # Updated with KNTIC-specific entries

kntic update

Update an existing KNTIC project to the latest version. Downloads the latest bootstrap archive and selectively replaces components.

kntic update              # Full update
kntic update --lib-only   # Update only .kntic/lib
kntic update --compose    # Also replace kntic.yml

Options

Update semantics per component

kntic start

Build and start KNTIC services using the configured container compose provider.

kntic start             # Start in foreground
kntic start --screen    # Start inside a GNU screen session

Options

Screen behavior

• If screen is not installed, falls back to foreground mode with a warning.
• If already inside a screen session (detected via the STY environment variable), skips the screen wrapper and runs in foreground.

The compose command is read from KNTIC_COMPOSE_PROVIDER in .kntic.env. Defaults to docker compose if not set.

kntic stop

Stop running KNTIC services.

kntic stop

Runs <provider> -f kntic.yml --env-file .kntic.env stop using the configured compose provider.

Environment Configuration (.kntic.env)

All runtime configuration lives in .kntic.env at the project root. This file is used by both the CLI and the Docker Compose services.

Auto-detected values are filled in during kntic init based on your environment. All values can be overridden manually.

Preflight Checks

During kntic init, the CLI runs non-blocking preflight checks and prints warnings:

These are advisory only — init always proceeds regardless of warnings.

Error Handling

All commands exit with code 1 on failure and print an error message to stderr. Unknown subcommands print the usage screen and exit with code 1.

$ kntic foobar
Unknown command: "foobar"

kntic v0.10.0 — KNTIC CLI
...

Quick Reference

kntic                         Show usage
kntic usage                   Show usage
kntic init                    Interactive bootstrap (default)
kntic init --quick | -q       Non-interactive bootstrap
kntic update                  Full update (lib, adrs, hooks, weights, env)
kntic update --lib-only       Update .kntic/lib only
kntic update --compose        Also replace kntic.yml (with .bak backup)
kntic start                   Start services in foreground
kntic start --screen          Start services in a screen session
kntic stop                    Stop services