# markitect-tool Agent Guide

This repository is tracked in the Custodian State Hub as:

- Domain: `markitect`
- Repo slug: `markitect-tool`
- Topic ID: `5571d954-0d30-4950-980d-7bcaaad8e3e2`

At session start, orient from:

1. `INTENT.md`
2. `wiki/ProductRequirementsDocument.md`
3. `wiki/FunctionalRequirementsSpecification.md`
4. `docs/markitect-main-scope-assessment.md`
5. 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; the authoritative work
items live in this repository as Markdown workplans.

Use State Hub to inspect current dispatch, blockers, progress, and cross-repo
coordination, but write durable plans and decisions into repository files first.

## Boundary

`markitect-tool` is the syntax-layer successor to the markdown-core parts of
`markitect-main`. It should stay CLI-first and library-always.

It owns:

- Markdown parsing and structured representation
- Schema definition, loading, derivation, validation, and reporting
- Markdown transformation, composition, and transclusion primitives
- Structured query and extraction over markdown documents and corpora
- Deterministic templating and optional LLM-assisted generation hooks
- Configuration, structured errors, caching, and incremental processing

It does not own:

- Infospace lifecycle, entity quality evaluation, or domain curation
- Persistent knowledge platform behavior or orchestration
- Provider-specific LLM adapters
- Asset management, rendering plugins, visual editing, finance, or project tooling
- GraphQL/database services except as external consumers of the library

## Development Posture

Prefer a clean reimplementation around the new PRD/FRS contract. Migrate
behavior and tests from `markitect-main` only when they fit the new boundary.
Avoid importing legacy platform assumptions just because the old code contains
useful names.

## Workplans

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

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