226 lines
5.5 KiB
Markdown
226 lines
5.5 KiB
Markdown
|
# Markitect Tool Product Requirements Document V0.1
|
|||
|
|
|
|||
|
|
## markitect-tool
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 1. Product Overview
|
|||
|
|
|
|||
|
|
### 1.1 Product Name
|
|||
|
|
|
|||
|
|
**markitect-tool** (`markitect`, CLI alias: `mkt`)
|
|||
|
|
|
|||
|
|
### 1.2 Product Definition
|
|||
|
|
|
|||
|
|
markitect-tool is a **markdown-native toolkit and CLI** that transforms semi-structured markdown into **structured, queryable, and reusable knowledge artifacts**.
|
|||
|
|
|
|||
|
|
It provides a **contract layer between markdown and structured knowledge operations**, enabling deterministic and LLM-assisted workflows without binding consumers to specific tools, formats, or providers.
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 2. Product Intent
|
|||
|
|
|
|||
|
|
### 2.1 Problem Statement
|
|||
|
|
|
|||
|
|
Markdown is widely used but suffers from:
|
|||
|
|
|
|||
|
|
* Lack of enforced structure and consistency
|
|||
|
|
* Limited automation and transformation capabilities
|
|||
|
|
* Weak support for large-scale knowledge management
|
|||
|
|
* Tight coupling to manual workflows or ad-hoc tooling
|
|||
|
|
|
|||
|
|
This results in fragmented, hard-to-maintain knowledge systems.
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
### 2.2 Intended Outcomes
|
|||
|
|
|
|||
|
|
markitect-tool enables:
|
|||
|
|
|
|||
|
|
* Treating markdown as **structured data rather than plain text**
|
|||
|
|
* Reliable **validation, transformation, and composition** of documents
|
|||
|
|
* Efficient **automation and reuse of knowledge artifacts**
|
|||
|
|
* A stable interface for **human and AI interaction with knowledge**
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
### 2.3 Success Criteria
|
|||
|
|
|
|||
|
|
The product is successful when:
|
|||
|
|
|
|||
|
|
* Users can **operate on large markdown corpora** with consistency and automation
|
|||
|
|
* Applications can depend on **provider-neutral, stable primitives**
|
|||
|
|
* LLM agents can interact with markdown as a **predictable, structured protocol**
|
|||
|
|
* Higher-layer systems (e.g. kontextual-engine) can use markitect without workarounds
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 3. Scope Definition
|
|||
|
|
|
|||
|
|
### 3.1 In Scope
|
|||
|
|
|
|||
|
|
* Markdown parsing into structured representations
|
|||
|
|
* Schema definition, validation, and enforcement
|
|||
|
|
* Transformation and composition (including transclusion-like mechanisms)
|
|||
|
|
* Querying and extraction of structured content
|
|||
|
|
* Templating and generation (deterministic and optionally LLM-assisted)
|
|||
|
|
* CLI-based workflows (`mkt`)
|
|||
|
|
* Programmatic API for integration
|
|||
|
|
* Caching and incremental processing for efficiency
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
### 3.2 Out of Scope
|
|||
|
|
|
|||
|
|
* Persistent knowledge system or ECM functionality
|
|||
|
|
* Multi-format content management beyond markdown-native handling
|
|||
|
|
* User management, permissions, or service orchestration
|
|||
|
|
* Domain-specific knowledge models or workflows
|
|||
|
|
* Full application frameworks or agent systems
|
|||
|
|
* Secret management or infrastructure concerns
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
### 3.3 Boundary Clarification
|
|||
|
|
|
|||
|
|
markitect-tool provides **primitives**, not systems.
|
|||
|
|
|
|||
|
|
* System-level orchestration → `kontextual-engine`
|
|||
|
|
* Project-level knowledge application → `infospace-bench`
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 4. Functional Expectations
|
|||
|
|
|
|||
|
|
### 4.1 Core Capabilities
|
|||
|
|
|
|||
|
|
The product must support:
|
|||
|
|
|
|||
|
|
* **Parsing & Structuring**
|
|||
|
|
Convert markdown into machine-interpretable representations
|
|||
|
|
|
|||
|
|
* **Validation**
|
|||
|
|
Enforce schemas and structural constraints
|
|||
|
|
|
|||
|
|
* **Transformation**
|
|||
|
|
Modify and compose documents programmatically
|
|||
|
|
|
|||
|
|
* **Templating**
|
|||
|
|
Generate markdown from structured input + rules/templates
|
|||
|
|
|
|||
|
|
* **Querying**
|
|||
|
|
Extract information from documents and collections
|
|||
|
|
|
|||
|
|
* **Automation Support**
|
|||
|
|
Enable repeatable workflows via CLI and API
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
### 4.2 Interaction Modes
|
|||
|
|
|
|||
|
|
* CLI-first interaction (`mkt`)
|
|||
|
|
* Library/API integration
|
|||
|
|
* Automation/agent execution
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 5. Non-Functional Expectations
|
|||
|
|
|
|||
|
|
### 5.1 Performance
|
|||
|
|
|
|||
|
|
* Efficient handling of large document sets (hundreds to thousands)
|
|||
|
|
* Incremental updates and caching to avoid redundant work
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
### 5.2 Reliability
|
|||
|
|
|
|||
|
|
* Deterministic behavior for core operations
|
|||
|
|
* Explicit failure modes for invalid input or schema violations
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
### 5.3 Extensibility
|
|||
|
|
|
|||
|
|
* Plugin/adaptor model for extending functionality
|
|||
|
|
* Ability to integrate LLM capabilities without coupling core logic
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
### 5.4 Usability
|
|||
|
|
|
|||
|
|
* Clear CLI interface with composable commands
|
|||
|
|
* Predictable behavior across workflows
|
|||
|
|
* Minimal required configuration for common use cases
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 6. Assumptions and Dependencies
|
|||
|
|
|
|||
|
|
### 6.1 Assumptions
|
|||
|
|
|
|||
|
|
* Markdown remains the primary human/agent interaction format
|
|||
|
|
* Users are comfortable with CLI-based workflows
|
|||
|
|
* Structured knowledge benefits from schema-driven approaches
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
### 6.2 Dependencies
|
|||
|
|
|
|||
|
|
* LLM capabilities (optional, via `llm-connect`)
|
|||
|
|
* File system as primary storage medium
|
|||
|
|
* Downstream systems for persistence and orchestration
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 7. Constraints
|
|||
|
|
|
|||
|
|
* Must remain **implementation-agnostic at the interface level**
|
|||
|
|
* Must not introduce coupling to specific providers or platforms
|
|||
|
|
* Must maintain **clear separation from higher-layer systems**
|
|||
|
|
* Must keep core primitives **small, stable, and composable**
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 8. Risks
|
|||
|
|
|
|||
|
|
* Scope creep toward full platform/ECM functionality
|
|||
|
|
* Over-reliance on LLMs reducing determinism
|
|||
|
|
* Complexity growth reducing usability
|
|||
|
|
* Fragmentation if primitives are not well-defined
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 9. Related Systems
|
|||
|
|
|
|||
|
|
* **kontextual-engine** – system layer (persistence, orchestration)
|
|||
|
|
* **infospace-bench** – application layer (knowledge projects)
|
|||
|
|
* **llm-connect** – provider abstraction for LLM integration
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 10. Ecosystem Context
|
|||
|
|
|
|||
|
|
This product is part of a layered knowledge system:
|
|||
|
|
|
|||
|
|
```text
|
|||
|
|
markitect-tool → makes markdown structured and manipulable
|
|||
|
|
kontextual-engine → makes knowledge persistent and operable
|
|||
|
|
infospace-bench → makes knowledge concrete and meaningful
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
Layers:
|
|||
|
|
|
|||
|
|
* **Syntax layer** → markitect-tool
|
|||
|
|
* **System layer** → kontextual-engine
|
|||
|
|
* **Application layer** → infospace-bench
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 11. PRD Type
|
|||
|
|
|
|||
|
|
**Hybrid / Boundary PRD**
|
|||
|
|
|
|||
|
|
This PRD defines stable product intent and boundaries while allowing flexibility in implementation and evolution.
|
|||
|
|
|