@dzhechkov/keysarium-core 1.0.0

package/orchestration/model-routing.md

@@ -0,0 +1,92 @@
+# Model Routing — 3-Tier Model Assignment
+
+> Rules for assigning the right AI model tier to each task in a multi-agent pipeline.
+
+## Overview
+
+Not every task requires the most capable (and expensive) model. A 3-tier routing system assigns the appropriate model based on task complexity, ensuring cost efficiency without sacrificing quality where it matters.
+
+## The 3 Tiers
+
+| Tier | Model Class | Latency | Relative Cost | When to Use |
+|------|-------------|---------|---------------|-------------|
+| Tier 1 | Fast/Cheap (e.g., haiku) | ~500ms | 1x (baseline) | Simple transforms, pattern matching, structural checks |
+| Tier 2 | Balanced (e.g., sonnet) | ~2s | 15x | Research synthesis, analysis, multi-evaluator panels |
+| Tier 3 | Premium (e.g., opus) | ~5s | 75x | Creative work, complex problem solving, novel synthesis |
+
+## Task Classification Rules
+
+### Tier 1 Tasks (Fast/Cheap)
+
+Use the cheapest model for:
+- File formatting and restructuring
+- Simple transforms (slug generation, path construction)
+- Structural validation checks (does the file have required sections?)
+- Pattern matching (does this text contain specific markers?)
+- Quick ranking passes (sorting candidates by simple criteria)
+
+### Tier 2 Tasks (Balanced)
+
+Use the balanced model for:
+- Research synthesis and summarization
+- Analytical work (comparing options, evaluating trade-offs)
+- Multi-evaluator judge panels (domain expert, critic, auditor)
+- Mutation workers in optimization loops
+- Structured generation (scripts, Q&A preparation)
+
+### Tier 3 Tasks (Premium)
+
+Use the premium model for:
+- Creative design work (prototypes, user journeys)
+- Complex problem solving (TRIZ, game theory analysis)
+- Novel synthesis (combining best elements from multiple candidates)
+- Storytelling and narrative construction
+- System architecture design
+
+## Enforcement Rules
+
+1. **NEVER** use Tier 3 for structural checks — this wastes budget with no quality gain
+2. **NEVER** use Tier 1 for evaluator panels — quality will be insufficient for reliable scoring
+3. **NEVER** use Tier 1 for creative work — output will be shallow and predictable
+4. When spawning agents, ALWAYS specify the model tier explicitly
+5. If not specified, the agent inherits the parent's tier (usually Tier 3 by default)
+
+## Cost Impact
+
+Using proper routing can reduce costs by 80-90% compared to using Tier 3 for everything:
+
+```
+Example pipeline with 20 tasks:
+  Without routing: 20 tasks * Tier 3 = 20 * 75x = 1500x
+  With routing:    8 Tier 1 + 8 Tier 2 + 4 Tier 3 = 8 + 120 + 300 = 428x
+  Savings: ~71%
+```
+
+## Per-Pipeline Customization
+
+Each pipeline should define a routing table mapping its specific tasks to tiers:
+
+```markdown
+| Task | Tier | Rationale |
+|------|------|-----------|
+| {Your task 1} | 1 | {Why Tier 1 is sufficient} |
+| {Your task 2} | 2 | {Why Tier 2 is needed} |
+| {Your task 3} | 3 | {Why Tier 3 is required} |
+```
+
+## Anti-Patterns
+
+| Anti-Pattern | Detection | Fix |
+|-------------|-----------|-----|
+| Everything on Tier 3 | No model parameter in agent spawns | Add explicit model routing |
+| Judge on Tier 1 | Quality scores have high variance | Upgrade judges to Tier 2 |
+| Creative work on Tier 1 | Outputs are generic and shallow | Upgrade to Tier 3 |
+| Structural check on Tier 3 | Simple pass/fail taking 5+ seconds | Downgrade to Tier 1 |
+
+## Integration with Orchestration
+
+The Queen Coordinator should:
+1. Load the routing table at INIT
+2. When spawning each agent, consult the routing table
+3. Specify the model parameter based on the task type
+4. Log the model used for each task (for cost tracking)

package/orchestration/queen-protocol.md

@@ -0,0 +1,154 @@
+# Queen Coordinator Protocol — 10-Step Orchestration Lifecycle
+
+> Standard protocol for the top-level coordinator (the "Queen") in a multi-agent pipeline.
+
+## Overview
+
+The Queen Coordinator is the master orchestrator that manages the lifecycle of a multi-agent pipeline execution. It follows a mandatory 10-step protocol that ensures proper initialization, execution, and finalization.
+
+This protocol is inspired by the Agentic QE 10-phase mandatory coordinator protocol and Ruflo's hierarchical orchestration model.
+
+## The 10 Steps
+
+### Step 1: INIT
+
+**Purpose:** Initialize the working environment.
+
+**Actions:**
+1. Create the project working directory (e.g., `projects/{slug}/`)
+2. Verify directory structure matches expected layout
+3. Initialize metadata files (if applicable)
+
+**Failure mode:** If directory creation fails, abort with error.
+
+### Step 2: HEALTH
+
+**Purpose:** Verify all required resources are available.
+
+**Actions:**
+1. Check that all required skills exist and are readable
+2. Verify governance shards are present for all active stages
+3. Check that the constitution file is accessible
+4. Verify external dependencies (commands, tools) are available
+
+**Failure mode:** If any critical resource is missing, abort with diagnostic message.
+
+### Step 3: LOAD
+
+**Purpose:** Load historical knowledge from memory.
+
+**Actions:**
+1. Call `memory_query()` with the current domain and first stage
+2. Load the most recent dream insights (if available)
+3. Load the brain file (if it exists from a previous export)
+4. Log: "Loaded {N} historical patterns" or "No historical data available (first run)"
+
+**Failure mode:** Graceful degradation — if no memory exists, proceed without it.
+
+### Step 4: DETECT
+
+**Purpose:** Classify the project's domain and characteristics.
+
+**Actions:**
+1. Analyze the input to detect the relevant domain
+2. Identify key characteristics (e.g., regulatory requirements, latency needs)
+3. Set cross-pipeline variables: `{DOMAIN}`, `{PRIMARY_USER}`, etc.
+
+**Failure mode:** If domain cannot be detected, use "general" as default.
+
+### Step 5: SHARD
+
+**Purpose:** Load the governance shard for the current stage.
+
+**Actions:**
+1. Determine the current stage
+2. Read the corresponding governance shard
+3. Validate prerequisites (upstream promises)
+4. Apply domain-specific rules based on the detected domain
+
+**Failure mode:** If shard is missing, fall back to the master configuration.
+
+### Step 6: ORCHESTRATE
+
+**Purpose:** Execute the pipeline stages with appropriate topologies.
+
+**Actions:**
+1. For each active stage:
+   a. Select topology (from `topology-selection.md`)
+   b. Assign model tier (from `model-routing.md`)
+   c. Spawn agents per the topology
+   d. Execute the stage
+   e. Collect results from all agents
+   f. Synthesize results (if parallel agents)
+
+**Failure mode:** If a stage fails, halt at checkpoint and report to human.
+
+### Step 7: MONITOR
+
+**Purpose:** Track execution and enforce checkpoints.
+
+**Actions:**
+1. After each stage, display the checkpoint
+2. Wait for human confirmation
+3. Record the reward based on the human's response
+4. Check time budget vs. actual elapsed time
+5. Warn if budget is exceeded
+
+**Failure mode:** If checkpoint is skipped, halt — INV-003 violated.
+
+### Step 8: COLLECT
+
+**Purpose:** Gather all artifacts produced by the pipeline.
+
+**Actions:**
+1. Enumerate all files created in the project directory
+2. Verify each artifact against its quality gates
+3. Compile a manifest of all outputs
+
+**Failure mode:** If mandatory artifacts are missing, report and halt.
+
+### Step 9: STORE
+
+**Purpose:** Persist knowledge for future use.
+
+**Actions:**
+1. Call `memory_store()` for the final stage outcome
+2. Update the trigger state for the dream engine
+3. If this was a significant execution, trigger knowledge extraction
+
+**Failure mode:** Graceful — if storage fails, log and continue (pipeline output is not lost).
+
+### Step 10: REPORT
+
+**Purpose:** Produce the final output and summary.
+
+**Actions:**
+1. Generate a summary of all stages and their outcomes
+2. List all artifacts created
+3. Report time spent vs. budget per stage
+4. Report any warnings or issues encountered
+5. Emit the final pipeline promise tag
+
+**Failure mode:** N/A — reporting always succeeds.
+
+## Lifecycle Diagram
+
+```
+INIT → HEALTH → LOAD → DETECT → SHARD
+                                   ↓
+                              ORCHESTRATE
+                                   ↓
+                               MONITOR ←→ (repeat per stage)
+                                   ↓
+                              COLLECT → STORE → REPORT
+```
+
+## Customization
+
+To adapt this protocol for your pipeline:
+
+1. Steps 1-3 (INIT, HEALTH, LOAD) are universal — keep as-is
+2. Step 4 (DETECT) — customize detection logic for your domain categories
+3. Step 5 (SHARD) — point to your shard directory
+4. Step 6 (ORCHESTRATE) — define your stages and their topologies
+5. Steps 7-10 (MONITOR, COLLECT, STORE, REPORT) — universal, keep as-is

package/orchestration/topology-selection.md

@@ -0,0 +1,175 @@
+# Topology Selection — Agent Arrangement Patterns
+
+> 6 topology types for organizing agents within a pipeline stage.
+
+## Overview
+
+When a pipeline stage uses multiple agents, the agents must be arranged in a topology that defines communication patterns and coordination. This document defines 6 standard topologies and provides guidance on when to use each.
+
+## Topology Types
+
+### 1. Star
+
+```
+        Coordinator
+       /     |     \
+    Agent1  Agent2  Agent3
+```
+
+**Description:** One coordinator spawns worker agents and collects their results. Workers do not communicate with each other.
+
+**Best for:**
+- Simple parallel tasks with independent sub-problems
+- Tasks where a single synthesis step combines all results
+- When fault isolation is important (one worker failure does not affect others)
+
+**Properties:**
+- Coordination: centralized
+- Communication: hub-and-spoke
+- Fault tolerance: medium (coordinator is single point of failure)
+- Scalability: good (add more workers without topology change)
+
+### 2. Mesh
+
+```
+    Agent1 ←→ Agent2
+       ↕          ↕
+    Agent3 ←→ Agent4
+```
+
+**Description:** All agents can communicate with all other agents. Each agent operates autonomously and shares findings.
+
+**Best for:**
+- Fault-tolerant research where any agent can cover for another
+- Tasks where agents may discover information relevant to other agents
+- When no single coordinator is needed
+
+**Properties:**
+- Coordination: decentralized
+- Communication: all-to-all
+- Fault tolerance: high (any agent can be lost)
+- Scalability: limited (communication overhead grows quadratically)
+
+### 3. Hierarchical
+
+```
+           Queen
+          /     \
+    Manager1    Manager2
+    /    \      /    \
+  W1     W2   W3    W4
+```
+
+**Description:** Multi-level hierarchy. The Queen delegates to managers, who delegate to workers. Results flow upward.
+
+**Best for:**
+- Complex stages with sub-stages
+- When different expertise levels are needed at different tiers
+- Large-scale parallelism (10+ agents)
+
+**Properties:**
+- Coordination: hierarchical
+- Communication: parent-child only
+- Fault tolerance: medium (manager failure affects its workers)
+- Scalability: excellent (add more levels as needed)
+
+### 4. Ring
+
+```
+    Agent1 → Agent2 → Agent3 → Agent4
+       ↑                          |
+       └──────────────────────────┘
+```
+
+**Description:** Agents pass work sequentially in a ring. Each agent processes the work and passes it to the next, adding refinements.
+
+**Best for:**
+- Iterative refinement tasks (draft -> review -> polish -> finalize)
+- When each agent adds a specific type of value
+- Pipeline-within-a-pipeline scenarios
+
+**Properties:**
+- Coordination: sequential
+- Communication: unidirectional ring
+- Fault tolerance: low (any break stops the ring)
+- Scalability: limited (latency increases linearly)
+
+### 5. Hybrid
+
+```
+           Coordinator
+          /           \
+    [Star cluster]   [Mesh cluster]
+    /    |    \       A1 ←→ A2
+  W1    W2    W3      ↕       ↕
+                      A3 ←→ A4
+```
+
+**Description:** Combines two or more topologies. Different parts of the stage use different agent arrangements.
+
+**Best for:**
+- Stages with heterogeneous sub-tasks
+- When some sub-tasks need isolation (star) and others need collaboration (mesh)
+
+**Properties:**
+- Coordination: mixed
+- Communication: varies by cluster
+- Fault tolerance: varies
+- Scalability: good (each cluster scales independently)
+
+### 6. Adaptive
+
+**Description:** The topology starts as one type and evolves during execution based on conditions.
+
+**Rules:**
+- Start with Star
+- If agent disagreement detected (scores differ by > 3 points): switch to Mesh for reconciliation
+- If task is simple and progressing well: stay as Star
+- If complexity exceeds threshold: elevate to Hierarchical
+
+**Best for:**
+- Uncertain tasks where the right topology is not known in advance
+- When the system should self-organize based on outcomes
+
+**Properties:**
+- Coordination: dynamic
+- Communication: evolves
+- Fault tolerance: high (adapts around failures)
+- Scalability: good (adapts structure to load)
+
+## Selection Guide
+
+| Stage Characteristic | Recommended Topology | Rationale |
+|---------------------|---------------------|-----------|
+| Independent parallel tasks | **Star** | Simple, reliable, easy to synthesize |
+| Fault-tolerant research | **Mesh** | Any agent can cover for another |
+| Multi-evaluator panel | **Star** (isolated) | Judges must NOT communicate |
+| Iterative refinement | **Ring** | Each pass adds specific value |
+| Complex multi-level work | **Hierarchical** | Delegate and aggregate |
+| Heterogeneous sub-tasks | **Hybrid** | Match topology to sub-task type |
+| Uncertain complexity | **Adaptive** | Start simple, evolve as needed |
+
+## Integration with Model Routing
+
+Each topology can specify model tiers for its agents:
+
+```
+Star:
+  Coordinator: opus (complex synthesis)
+  Workers: sonnet (analytical work) or haiku (simple tasks)
+
+Hierarchical:
+  Queen: opus
+  Managers: sonnet
+  Workers: haiku
+
+Mesh:
+  All agents: same tier (usually sonnet)
+```
+
+## Implementation Note
+
+In Claude Code, topologies are implemented using the Agent tool:
+- Star/Hierarchical: Orchestrator spawns Agent tool calls
+- Mesh: Multiple Agent calls that read shared files
+- Ring: Sequential Agent calls, each reading the previous agent's output

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@dzhechkov/keysarium-core",
+  "version": "1.0.0",
+  "description": "Core framework for multi-agent pipelines: governance, memory, orchestration, verification, trust tiers, and multi-platform support",
+  "main": "index.md",
+  "files": [
+    "index.md",
+    "governance/",
+    "memory/",
+    "orchestration/",
+    "verification/",
+    "trust-tiers/",
+    "platform/"
+  ],
+  "keywords": [
+    "claude",
+    "claude-code",
+    "ai",
+    "multi-agent",
+    "pipeline",
+    "framework",
+    "governance",
+    "orchestration",
+    "verification",
+    "trust-tiers",
+    "memory",
+    "reward-learning",
+    "keysarium-core"
+  ],
+  "author": "dzhechko",
+  "license": "MIT",
+  "engines": {
+    "node": ">=16.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/dzhechko/product-keysarium-2026",
+    "directory": "packages/dz-keysarium-core"
+  },
+  "homepage": "https://github.com/dzhechko/product-keysarium-2026#keysarium-core",
+  "bugs": {
+    "url": "https://github.com/dzhechko/product-keysarium-2026/issues"
+  }
+}

package/platform/adapter-registry.md

@@ -0,0 +1,93 @@
+# Platform Adapter Registry
+
+> Central registry for multi-platform support. Maps each supported AI coding platform to its configuration format, output paths, and translation strategy.
+
+## Supported Platforms
+
+| Platform | Config Format | Output Structure | Complexity |
+|----------|---------------|------------------|------------|
+| Claude Code | `.claude/` directory | Native — skills, rules, commands, shards | Native |
+| Cursor | `.cursorrules` + optional `.cursor/skills/` | Flat rules file with inlined skills | Low |
+| OpenCode | `.opencode/` directory | Directory hierarchy mirroring Claude Code | Low |
+| GitHub Copilot | `.github/copilot-instructions.md` | Single markdown file | Medium |
+
+## Platform Details
+
+### Claude Code (Native)
+
+| Property | Value |
+|----------|-------|
+| Config directory | `.claude/` |
+| Skills | `.claude/skills/{name}/SKILL.md` |
+| Rules | `.claude/rules/{name}.md` |
+| Commands | `.claude/commands/{name}.md` |
+| Shards | `.claude/shards/{name}.shard.md` |
+| Notes | This is the native format. No translation needed. |
+
+### Cursor
+
+| Property | Value |
+|----------|-------|
+| Config file | `.cursorrules` (project root) |
+| Format | Plain text / markdown |
+| Skills | Key instructions extracted and inlined; large skills in `.cursor/skills/` |
+| Rules | All rules concatenated under sections |
+| Max size | Recommended < 10,000 tokens |
+
+### OpenCode
+
+| Property | Value |
+|----------|-------|
+| Config directory | `.opencode/` |
+| Config file | `.opencode/config.yaml` |
+| Skills | `.opencode/skills/{name}.md` (one file per skill) |
+| Rules | `.opencode/rules/{name}.md` (one file per rule) |
+| Notes | Most structurally similar to Claude Code |
+
+### GitHub Copilot
+
+| Property | Value |
+|----------|-------|
+| Config file | `.github/copilot-instructions.md` |
+| Format | Single markdown file |
+| Skills | Summarized into sections within the file |
+| Rules | Merged into the instructions file |
+| Max size | Recommended < 8,000 tokens |
+
+## Translation Strategy
+
+### Source Structure
+
+The source of truth is the Claude Code `.claude/` directory (or equivalent). Translation generates platform-specific configs from this source.
+
+### Translation Rules
+
+| Source Element | Cursor | OpenCode | Copilot |
+|----------------|--------|----------|---------|
+| `Read: .claude/skills/X/SKILL.md` | "Follow the X skill protocol" | `See: .opencode/skills/X.md` | Summarize inline |
+| Agent tool references | "Break into sub-tasks" | "Break into sub-tasks" | "Break into sub-tasks" |
+| Model routing | Omit (platform-managed) | Omit (platform-managed) | Omit (platform-managed) |
+| `$ARGUMENTS` variable | "User-provided input" | "User-provided input" | "User-provided context" |
+| Promise tags | Keep as markers | Keep as markers | Keep as markers |
+| Checkpoint protocol | "Pause and confirm" | "Pause and confirm" | "Confirm before proceeding" |
+| Governance shards | Omit (single-file) | Include if directory-based | Omit (single-file) |
+
+## Adding a New Platform
+
+To add support for a new platform:
+
+1. Create a template file in `platform/templates/{platform-name}.md`
+2. Add an entry to the "Supported Platforms" table above
+3. Add a "Platform Details" section
+4. Define translation rules for the new platform
+5. Test generation with the new platform
+
+## Template Format
+
+Each platform template file should include:
+
+1. **Target Format** — Description of the platform's config format
+2. **Generation Protocol** — Step-by-step instructions for generating the config
+3. **Content Adaptation Rules** — Table mapping source elements to target format
+4. **Size Constraints** — Token/word limits for the platform
+5. **Example Output Structure** — What the generated files look like

package/platform/templates/copilot.md

@@ -0,0 +1,81 @@
+# GitHub Copilot Platform Template
+
+> Generates `.github/copilot-instructions.md` from pipeline source configuration.
+
+## Target Format
+
+GitHub Copilot reads custom instructions from `.github/copilot-instructions.md`. This is a single markdown file with all project-level instructions.
+
+## Generation Protocol
+
+### Step 1: Generate `.github/copilot-instructions.md`
+
+```markdown
+# {Project Name} -- Copilot Instructions
+
+> Auto-generated from pipeline configuration. Source of truth: {source path}
+
+## Project Overview
+{Purpose, key concepts, directory structure overview}
+
+## Core Rules
+{For each rule, 5-10 actionable bullet points.
+ Focus on constraints and do/don't instructions.}
+
+## Skills Reference
+{For each skill:
+ **Purpose:** one-line
+ **Key protocol:** 3-5 steps
+ **Quality gates:** 2-4 checks}
+
+## Pipeline Overview
+{Phase | Purpose | Key Output table}
+
+## Anti-Patterns
+{Pattern | Fix table}
+
+## Domain-Specific Guidance
+{3-4 bullet points per domain}
+
+## File Conventions
+{Key naming and directory rules}
+```
+
+### Step 2: Size Check
+
+Verify the file is under 8,000 tokens (~6,000 words). Priority for trimming:
+1. Core Rules (keep all)
+2. Anti-Patterns (keep all)
+3. Skills Reference (summarize further)
+4. Pipeline Overview (keep)
+5. Domain-Specific Guidance (trim)
+
+### Step 3: Directory Safety
+
+If `.github/copilot-instructions.md` already exists, generate to `copilot-instructions.generated.md` and warn.
+
+## Content Adaptation Rules
+
+| Source Element | Copilot Adaptation |
+|----------------|---------------------|
+| Skill references | Summarize inline (no separate files) |
+| Agent tool references | "Break complex tasks into sub-tasks" |
+| Model routing | Omit entirely |
+| Promise tags | Keep as phase completion markers |
+| Checkpoint protocol | "Confirm with user before moving to next phase" |
+| Governance shards | Summarize key constraints only |
+
+## Copilot-Specific Notes
+
+1. Copilot reads the entire file on each interaction — shorter is better
+2. No directory-based skills — everything in one markdown file
+3. Copilot does not support slash commands — reference as "workflows" or "procedures"
+4. Focus on rules and constraints — Copilot benefits most from clear do/don't
+5. Code patterns over prose — show examples instead of descriptions
+
+## Example Output
+
+```
+.github/
+└── copilot-instructions.md    (single file, <8K tokens)
+```