generated from coulomb/repo-seed
102 lines
2.8 KiB
Markdown
102 lines
2.8 KiB
Markdown
# 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:
|
|
|
|
1. `.custodian-brief.md`
|
|
2. `INTENT.md`
|
|
3. `wiki/ProductRequirementsDocument.md`
|
|
4. `wiki/FunctionalRequirementsSpecification.md`
|
|
5. `docs/stack-decision.md`
|
|
6. `docs/markitect-main-scope-assessment.md`
|
|
7. 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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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`:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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.
|