kontextual-engine Agent Guide

This repository is tracked in the Custodian State Hub as:

Domain: markitect
Repo slug: kontextual-engine
Topic ID: 5571d954-0d30-4950-980d-7bcaaad8e3e2
Workplan prefix: KONT-WP

At session start, orient from:

.custodian-brief.md
INTENT.md
wiki/ProductRequirementsDocument.md
wiki/FunctionalRequirementsSpecification.md
docs/stack-decision.md
docs/markitect-main-scope-assessment.md
Active files in workplans/

State Hub

This repo is registered with State Hub through the local Custodian service. State Hub is an index/cache for coordination state; authoritative work items live in this repository as Markdown workplans.

Local API:

curl -s http://127.0.0.1:8000/state/health
curl -s http://127.0.0.1:8000/repos/kontextual-engine | python3 -m json.tool

At session close, record notable progress:

curl -s -X POST http://127.0.0.1:8000/progress/ \
  -H "Content-Type: application/json" \
  -d '{"summary":"what changed","event_type":"note","author":"codex"}'

After workplan file changes, ask the custodian operator to run from /home/worsch/the-custodian/state-hub:

make fix-consistency REPO=kontextual-engine

Boundary

kontextual-engine is the system-layer successor to the runtime/platform parts of markitect-main.

It owns:

Persistent knowledge artifacts and collections.
Artifact metadata and relationships.
Ingestion and normalization interfaces.
Query, retrieval, and composition service contracts.
Workflow orchestration and operation tracking.
Agent-operable context and action surfaces.
Integration boundaries to markitect-tool and llm-connect.

It does not own:

Markdown syntax primitives or document-level schema tooling.
End-user visual UI applications or rendering plugins.
Domain-specific knowledge content.
Provider-specific LLM adapters.
Legacy finance, issue, profile, release, or project-management utilities.

Development Posture

Prefer clean reimplementation around the new PRD/FRS. Use markitect-main as reference material for behavior, tests, and domain vocabulary, not as an architecture to copy wholesale.

Stack And Commands

Python target: 3.12+
Distribution: kontextual-engine
Import package: kontextual_engine
Build backend: setuptools
Test runner: pytest
Source layout: src/kontextual_engine
Service framework: FastAPI as an optional boundary after the programmatic API stabilizes

Run tests:

python3 -m pytest

Workplans

Workplans live in workplans/ and follow the Custodian ADR-001 convention:

Frontmatter declares type: workplan, domain: markitect, repo: kontextual-engine, and owner: codex.
Tasks are embedded as headed sections with fenced task blocks.
State Hub may index these files, but the files remain authoritative.

2.8 KiB Raw Blame History