markitect-tool/CLAUDE.md

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