From a9abc6caceefe58d7b6cbd8b653d56147a76b9df Mon Sep 17 00:00:00 2001 From: Parfii-bot Date: Tue, 21 Apr 2026 19:45:20 +0800 Subject: [PATCH] docs: primitives section + compose-solution phase-3/5 cross-refs - README.md: new 'Primitives' section between Cross-tool bridges and Meta-composer. Explains _primitives/ vs _blocks/, lists tomd, names the PreToolUse(Read) hook, notes /compose-solution auto-discovery - phase-3-prior-art.md: extend grep target list to include _primitives/ - phase-5-architecture.md: one-paragraph note on referencing tomd primitive instead of rolling custom binary-format parsing (reuse over rewrite) Co-Authored-By: Claude Opus 4.7 (1M context) --- README.md | 10 ++++++++++ skills/compose-solution/phase-3-prior-art.md | 2 +- skills/compose-solution/phase-5-architecture.md | 6 ++++++ 3 files changed, 17 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index ff9ef57..c623d41 100644 --- a/README.md +++ b/README.md @@ -140,6 +140,16 @@ KeiSeiKit ships 11 verified tool-bridge templates under `_bridges/`. Render them All paths are idempotent: existing bridge files in the project are skipped, never overwritten. See `_bridges/README.md` for the full template→output-path table. +## Primitives + +`_primitives/` holds first-class building blocks that agents and pipelines depend on — executable utilities, not behavioral markdown. Currently one primitive ships with the kit: + +- `tomd` — universal non-native-format → markdown converter (PDF, DOCX, XLSX, PPTX, CSV, code, images with OCR). Ported from [KeiAgent](https://example.invalid/KeiAgent) with KeiSeiKit-style error tags and a configurable cache directory (`KEISEI_TOMD_CACHE`, default `/tmp/keisei-tomd-cache`). + +The matching hook `hooks/tomd-preread.sh` is a `PreToolUse(Read)` entry that auto-redirects Claude to a cached markdown conversion when a Read targets an opaque binary format — no agent has to know about `tomd` explicitly, but any agent that *does* need to shell out can invoke `~/.claude/agents/_primitives/tomd.sh report.pdf > report.md` directly. + +`/compose-solution` auto-discovers primitives: Phase 3's prior-art grep includes `_primitives/` so new composed artefacts can reference the existing converter instead of rolling their own. + ## Meta-composer `/compose-solution` is the meta-creator: tell it what you want to solve in one free-text paragraph, it decomposes the task, greps existing blocks / skills / manifests / bridges for prior art, proposes a minimal math-first architecture, and assembles the right artefact — agent, skill, hook, rule, or block. Every decision except the intake is a click (option-picker), never free-text. diff --git a/skills/compose-solution/phase-3-prior-art.md b/skills/compose-solution/phase-3-prior-art.md index c417d45..fdd99f7 100644 --- a/skills/compose-solution/phase-3-prior-art.md +++ b/skills/compose-solution/phase-3-prior-art.md @@ -8,7 +8,7 @@ For EACH component from Phase 2, run three independent searches in parallel ```bash # Replace with the component's 3-5 distinctive keywords as an # ERE alternation like (foo|bar|baz). -grep -rinlE '' _blocks/ _manifests/ skills/ _bridges/ hooks/ 2>/dev/null +grep -rinlE '' _blocks/ _manifests/ _primitives/ skills/ _bridges/ hooks/ 2>/dev/null ``` ## 3b — Personal bundle reuse (conditional, skip on missing) diff --git a/skills/compose-solution/phase-5-architecture.md b/skills/compose-solution/phase-5-architecture.md index 947cdac..a938627 100644 --- a/skills/compose-solution/phase-5-architecture.md +++ b/skills/compose-solution/phase-5-architecture.md @@ -13,6 +13,12 @@ where block_* ∈ {_blocks/, newly drafted, skills/, _manifests/} invariant: ``` +If the architecture requires parsing binary document formats (PDF / DOCX / +XLSX / PPTX / CSV), reference the `tomd` primitive +(`_primitives/tomd.sh`) instead of rolling custom parsing — RULE "reuse +over rewrite". The PreToolUse(Read) hook `tomd-preread.sh` already redirects +Claude to the converted markdown transparently. + ## 5b — What is UNNECESSARY? For each block listed, justify why it's in. If a block can be removed