coulomb/markitect-tool
2
0
Fork 0
generated from coulomb/repo-seed
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

State-hub connect and initial workplans

Browse Source
This commit is contained in:
Bernd Worsch
2026-05-03 20:43:12 +02:00
parent ebc3e3e65b
commit 83a50a38d9
11 changed files with 517 additions and 2 deletions
Download Patch File Download Diff File Expand all files Collapse all files

9
.claude/rules/repo-boundary.md Normal file
View File

@@ -0,0 +1,9 @@
# Repo Boundary
Keep `markitect-tool` focused on provider-neutral markdown primitives:
parse, validate, transform, compose, query, template, generate, configure,
cache, and expose through CLI/API.
Leave infospace lifecycle, persistence/orchestration, project-specific
knowledge models, rendering applications, and service infrastructure to
higher-layer repositories.

9
.claude/rules/repo-identity.md Normal file
View File

@@ -0,0 +1,9 @@
# Repo Identity
- Project: `markitect-tool`
- Domain: `markitect`
- Repo slug: `markitect-tool`
- State Hub topic ID: `5571d954-0d30-4950-980d-7bcaaad8e3e2`
This repository is the markdown syntax/tooling successor to the in-scope core
of `markitect-main`.

7
.claude/rules/session-protocol.md Normal file
View File

@@ -0,0 +1,7 @@
# Session Protocol
1. Read `INTENT.md`, the PRD, the FRS, and active workplans.
2. Check State Hub for dispatch and blockers when available.
3. Treat workplan files as authoritative coordination state.
4. Record durable decisions in repository docs before reflecting them in State Hub.
5. Keep the implementation boundary narrow: syntax-layer toolkit, not platform.

9
.claude/rules/workplan-convention.md Normal file
View File

@@ -0,0 +1,9 @@
# Workplan Convention
Workplans live at `workplans/<id>-<slug>.md`.
Use IDs with the `MKTT-WP-` prefix for this repository. Embedded tasks use
`MKTT-WP-XXXX-TNNN`.
Each workplan should trace back to the PRD/FRS and indicate what is migrated,
reimplemented, deferred, or explicitly out of scope.

61
CLAUDE.md Normal file
View File

@@ -0,0 +1,61 @@
# 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

23
README.md
View File

@@ -1,3 +1,22 @@
# repo-seed
# markitect-tool
A git repository template to bootstrap coulomb projects from.
`markitect-tool` is a markdown-native toolkit and CLI for turning
semi-structured Markdown into structured, queryable, reusable knowledge
artifacts.
This repository is the syntax-layer successor to the in-scope core of
`markitect-main`. Its product boundary is defined in `INTENT.md` and the
requirements documents in `wiki/`.
## Start Here
- `INTENT.md` - project purpose, boundaries, and design principles
- `wiki/ProductRequirementsDocument.md` - product scope and success criteria
- `wiki/FunctionalRequirementsSpecification.md` - observable functional behavior
- `docs/markitect-main-scope-assessment.md` - migration assessment from `markitect-main`
- `workplans/` - source-of-truth implementation and migration plans
## State Hub
The repo is registered with the Custodian State Hub as `markitect-tool` under
the `markitect` domain. See `docs/state-hub-integration.md`.

65
docs/markitect-main-scope-assessment.md Normal file
View File

@@ -0,0 +1,65 @@
# markitect-main Scope Assessment
This assessment compares `/home/worsch/markitect-main` with the `markitect-tool`
PRD, FRS, and intent documents.
## Summary
`markitect-main` already contains many capabilities that map to the new
syntax-layer scope, but they are embedded in a broader platform. The successor
repo should migrate behavior selectively and reimplement the public contract
cleanly.
`markitect-tool` should not become a trimmed copy of `markitect-main`. It
should become the stable contract layer that higher systems can depend on.
## In-Scope Candidates
| FRS area | markitect-main evidence | Recommendation |
| --- | --- | --- |
| FR-001/002 parsing and structure | `markitect/core/parser.py`, `markitect/parser.py`, `markitect/core/section_tree.py`, `markitect/frontmatter.py`, `markitect/matter_*` | Reimplement core parser facade around `markdown-it-py`; migrate tests/fixtures and behavior where deterministic. |
| FR-010/012 schema definition and validation | `markitect/schema/`, `schema_loader.py`, `schema_validator.py`, `schema_generator.py`, `metaschema.py`, `markitect/schemas/` | Migrate concepts and schema fixtures; simplify into provider-neutral schema package. |
| FR-020/022 transformation and composition | `markitect/explode_variants/`, `docs/composition-guide.md`, `docs/md-explode-command.md`, transclusion mentions in infospace/spaces modules | Reimplement as small document operation primitives; avoid bringing infospace lifecycle assumptions. |
| FR-030/031 query and extraction | `markitect/ast_service.py`, JSONPath usage, `markitect/query_paradigms/`, search docs | Reimplement query API over the new structured representation; keep JSONPath-like querying if it remains lightweight. |
| FR-040/041 templating/generation | `markitect/template/`, `draft_generator.py`, schema-guided generation docs | Migrate deterministic templating ideas; keep LLM hooks external. |
| FR-050/052 CLI and automation | `markitect/cli.py`, `batch_processor.py`, output formatting helpers | Reimplement CLI as `mkt` with composable subcommands and structured output. |
| FR-060/061 configuration | `config_manager.py`, `markitect/llm/toml_config.py`, `.markitect.toml` references | Keep project/user config pattern, but drop provider-specific LLM config from core. |
| FR-070/071 caching/incremental | `ast_cache.py`, `cache_service.py`, `performance_tracker.py` | Migrate cache strategy after parser contract stabilizes. |
| FR-080/081 structured errors | `exceptions.py`, `validation_error.py`, `production/error_handler.py` | Reimplement compact typed errors early, because CLI/API behavior depends on them. |
## Out-of-Scope for markitect-tool
These areas belong elsewhere or should remain legacy unless a higher-layer
consumer needs them through the new library contract:
- `markitect/infospace/` and `markitect/spaces/`: project-level knowledge lifecycle.
- `markitect/prompts/`, `markitect/helper/`, `markitect/llm/`: prompt execution and provider adapters, except optional integration hooks through `llm-connect`.
- `markitect/assets/`, `plugins/`, `templates/document.html`, JS UI files: rendering and asset management.
- `markitect/graphql/`, `storage/`, `database.py`: persistent service/data layer experiments.
- `markitect/finance/`, `profile/`, `legacy/`, `gitea`, `tddai`, `services/`, `tools/`: project operations and unrelated tooling.
- Domain schemas and infospace example content, unless copied as test fixtures for generic markdown/schema behavior.
## Migration Principles
1. Start from the PRD/FRS command/API contract, not from old module names.
2. Prefer deterministic behavior and structured outputs before LLM integration.
3. Migrate tests before code when the old behavior is clearly in scope.
4. Treat old code as reference material; do not preserve backward compatibility unless the new contract explicitly needs it.
5. Keep database, platform, and domain lifecycle concerns out of this repo.
## Initial Architecture Target
```text
markitect_tool/
core/ parse, document model, frontmatter, serialization
schema/ schema load/derive/validate/report
ops/ transform, compose, include/transclude
query/ selection/extraction over structured documents
template/ deterministic rendering and generation primitives
cache/ content fingerprints and incremental processing
cli/ mkt command surface
integrations/ optional adapters, including LLM hooks
```
The package name should be decided in the implementation workplan. The product
name is `markitect-tool`; the CLI alias is `mkt`.

50
docs/state-hub-integration.md Normal file
View File

@@ -0,0 +1,50 @@
# State Hub Integration
`markitect-tool` was registered with the Custodian State Hub on 2026-05-03.
| Field | Value |
| --- | --- |
| Domain | `markitect` |
| Repo slug | `markitect-tool` |
| Topic ID | `5571d954-0d30-4950-980d-7bcaaad8e3e2` |
| Local path | `/home/worsch/markitect-tool` |
## Integration Result
The registration workflow:
- Confirmed the State Hub API was reachable.
- Confirmed the `state-hub` MCP server was configured.
- Registered `markitect-tool` as a managed repo under the `markitect` domain.
- Created the onboarding workstream `repo-integration-markitect-tool`.
- Created four onboarding tasks for repo setup, workplans, SBOM, and catalogue hygiene.
## Repository Source of Truth
Per Custodian ADR-001, workplans and work items originate in repository files.
State Hub should index and cache this state, not become the primary store.
The canonical workplan location is:
```text
workplans/
```
## Follow-Up
Once implementation dependencies exist, add an SBOM source and update State Hub
with the SBOM ingestion result. This seed repo currently has no package manifest.
## Registered Extension Points
| ID | Title | Source |
| --- | --- | --- |
| `EP-MKTT-001` | Optional LLM-assisted generation adapter hook | `workplans/MKTT-WP-0003-core-toolkit-implementation.md` |
| `EP-MKTT-002` | Query backend adapter boundary | `docs/markitect-main-scope-assessment.md` |
## Registered Technical Debt
| ID | Title | Source |
| --- | --- | --- |
| `TD-MKTT-001` | Implementation scaffold not yet created | `workplans/MKTT-WP-0003-core-toolkit-implementation.md` |
| `TD-MKTT-002` | Legacy behavior requires test-level migration filter | `workplans/MKTT-WP-0002-markitect-main-migration.md` |

82
workplans/MKTT-WP-0001-repo-foundation.md Normal file
View File

@@ -0,0 +1,82 @@
---
id: MKTT-WP-0001
type: workplan
title: "markitect-tool Repository Foundation"
domain: markitect
status: active
owner: markitect-tool
topic_slug: markitect
created: "2026-05-03"
updated: "2026-05-03"
state_hub_workstream_id: "4d405d74-faec-440e-873e-692ff9ca96e7"
---
# MKTT-WP-0001: markitect-tool Repository Foundation
## Purpose
Establish this repository as the State Hub-connected successor workspace for
the in-scope core of `markitect-main`.
## P1.1 - Integrate State Hub repository registration
```task
id: MKTT-WP-0001-T001
status: done
priority: high
state_hub_task_id: "34d2fba4-a03c-4d8f-a25c-b19a1c2f698d"
```
Register `markitect-tool` under the `markitect` domain, record the repo slug,
and preserve the integration details in repository documentation.
## P1.2 - Add agent-facing repo rules
```task
id: MKTT-WP-0001-T002
status: done
priority: high
state_hub_task_id: "b19f88a0-850e-428e-8131-4c4af2cbfc42"
```
Create `CLAUDE.md` and `.claude/rules/` material so future sessions start from
the new PRD/FRS and the State Hub-backed workplan convention.
## P1.3 - Establish workplan convention
```task
id: MKTT-WP-0001-T003
status: done
priority: high
state_hub_task_id: "4a770e4f-81b0-4f82-8f46-5886ee2fae36"
```
Create `workplans/` and seed source-of-truth workplans for foundation,
migration assessment, and implementation.
## P1.4 - Add initial project packaging decision
```task
id: MKTT-WP-0001-T004
status: todo
priority: medium
state_hub_task_id: "c15f8492-93d0-43aa-ba12-0d4aaff97c03"
```
Choose package/module names, Python version target, dependency manager, and
test runner. Keep the decision lightweight and aligned with the future `mkt`
CLI entry point.
## P1.5 - Add SBOM source once manifests exist
```task
id: MKTT-WP-0001-T005
status: blocked
priority: medium
state_hub_task_id: "e77a5e46-aaa2-4717-922f-a871fa2fd1cc"
```
After packaging files are introduced, generate or identify the SBOM source and
update State Hub registration metadata.
Blocked because the repository has no implementation package manifest yet.

87
workplans/MKTT-WP-0002-markitect-main-migration.md Normal file
View File

@@ -0,0 +1,87 @@
---
id: MKTT-WP-0002
type: workplan
title: "markitect-main Scope Extraction"
domain: markitect
status: active
owner: markitect-tool
topic_slug: markitect
created: "2026-05-03"
updated: "2026-05-03"
state_hub_workstream_id: "0fe54d2c-d579-4b03-a647-7a15bb835893"
---
# MKTT-WP-0002: markitect-main Scope Extraction
## Purpose
Inventory `markitect-main`, identify which behavior belongs in the new
syntax-layer toolkit, and prepare migration/reimplementation slices.
## P2.1 - Complete first-pass scope assessment
```task
id: MKTT-WP-0002-T001
status: done
priority: high
state_hub_task_id: "950de9fd-7540-4e0f-bc4a-2fa86fc9fccc"
```
Compare the old repo against the new PRD/FRS and document candidate modules,
out-of-scope areas, and migration principles.
## P2.2 - Extract reusable behavior test list
```task
id: MKTT-WP-0002-T002
status: todo
priority: high
state_hub_task_id: "994a8c17-bd13-476b-9b8e-86c50e1c4897"
```
Review `markitect-main/tests`, `testdata`, schema fixtures, and CLI integration
tests. Create a candidate test migration list organized by FRS section.
Technical debt: `TD-MKTT-002`.
## P2.3 - Map legacy commands to `mkt`
```task
id: MKTT-WP-0002-T003
status: todo
priority: high
state_hub_task_id: "f82b1f2c-887b-4378-b70b-84c1cb051742"
```
Inventory old `markitect` CLI commands and classify each as migrate,
reimplement, rename, defer, or out of scope for `mkt`.
## P2.4 - Decide compatibility policy
```task
id: MKTT-WP-0002-T004
status: todo
priority: medium
state_hub_task_id: "56a12905-c3ec-42b0-893a-47ef023ea10a"
```
Define whether any old module paths, command names, file formats, or schema
names deserve compatibility shims in the successor.
## Extension Points
`EP-MKTT-002` tracks the query backend adapter boundary: keep the initial query
API small, but leave room for JSONPath-like or alternate selectors if they fit
the provider-neutral contract.
## P2.5 - Identify external dependencies
```task
id: MKTT-WP-0002-T005
status: todo
priority: medium
state_hub_task_id: "4d51e763-bf5f-483b-8948-6306ff5a58bb"
```
Separate core dependencies from optional integrations. Initial candidates:
`markdown-it-py`, `PyYAML`, `jsonpath-ng`, and optional `llm-connect`.

117
workplans/MKTT-WP-0003-core-toolkit-implementation.md Normal file
View File

@@ -0,0 +1,117 @@
---
id: MKTT-WP-0003
type: workplan
title: "Core Markdown Toolkit Implementation"
domain: markitect
status: active
owner: markitect-tool
topic_slug: markitect
created: "2026-05-03"
updated: "2026-05-03"
state_hub_workstream_id: "9fefb57d-985e-4125-8daf-03554844f45e"
---
# MKTT-WP-0003: Core Markdown Toolkit Implementation
## Purpose
Build the first usable `markitect-tool` implementation around the PRD/FRS
contract and the `mkt` CLI.
## P3.1 - Bootstrap package and tests
```task
id: MKTT-WP-0003-T001
status: todo
priority: high
state_hub_task_id: "9d9501fe-6809-4b4f-bda6-ec5e5952ddc7"
```
Create project metadata, package layout, test structure, and a minimal CLI
entry point that can be installed or run locally.
## P3.2 - Implement structured markdown parse contract
```task
id: MKTT-WP-0003-T002
status: todo
priority: high
state_hub_task_id: "7dead033-e249-46b0-9eb3-908ae231a987"
```
Implement FR-001 and FR-002: parse markdown files, preserve headings,
frontmatter, sections, and content blocks, and expose structured output via
API and CLI.
## P3.3 - Implement schema load and validation
```task
id: MKTT-WP-0003-T003
status: todo
priority: high
state_hub_task_id: "36a22def-d415-4c08-a793-836ee52e4308"
```
Implement FR-010 through FR-012: define/derive schemas, validate documents,
and report structured violations with file/location context.
## P3.4 - Implement query and extraction
```task
id: MKTT-WP-0003-T004
status: todo
priority: medium
state_hub_task_id: "e4f72218-601e-488f-a5df-171b91a747d2"
```
Implement FR-030 and FR-031 over the structured representation. Start with a
small query language or JSONPath-like adapter only if it remains simple.
## P3.5 - Implement transform, compose, and include primitives
```task
id: MKTT-WP-0003-T005
status: todo
priority: medium
state_hub_task_id: "205d69eb-dd34-46a5-af0b-cc2de9d213d0"
```
Implement FR-020 through FR-022 as deterministic document operations. Keep
transclusion syntax and resolution rules explicit and testable.
## P3.6 - Implement templating and generation hooks
```task
id: MKTT-WP-0003-T006
status: todo
priority: medium
state_hub_task_id: "307fa072-b1ce-42e8-9309-e2a92e130ae1"
```
Implement FR-040 through FR-042 with deterministic templates first and optional
LLM-assisted hooks supplied by external providers.
Extension point: `EP-MKTT-001`.
## P3.7 - Add caching and incremental processing
```task
id: MKTT-WP-0003-T007
status: todo
priority: low
state_hub_task_id: "236f90e3-1d79-473f-8c57-bcbbde9ece02"
```
Implement FR-070 and FR-071 after the parse/schema contracts are stable.
## Known Technical Debt
```task
id: MKTT-WP-0003-T008
status: todo
priority: medium
state_hub_task_id: "94067c7e-e68b-45be-a1d6-90547eb15422"
```
Resolve `TD-MKTT-001` by adding the implementation scaffold: package metadata,
module layout, test runner, and `mkt` CLI entry point.