@dzhechkov/harness-cli 0.2.0 → 0.2.2

package/README.md

@@ -1,27 +1,237 @@
 # @dzhechkov/harness-cli
 
-The **`dz`** command-line interface for the DZ cross-platform harness — a thin
-argv shell over [`@dzhechkov/harness-core`](../harness-core).
+The **`dz`** CLI — the main entry point to the DZ Harness Hub. Install AI skills for **Claude Code, Codex, OpenCode, Hermes** from a single command.
 
-## Commands
+## Install
 
+```bash
+npm install -g @dzhechkov/harness-cli
 ```
-dz init   --target <name> [--skills-dir <dir>] [--project <dir>] [--force]
-dz verify [--skills-dir <dir>] [--target <name>]
-dz sync   [--canonical <dir>] [--project <dir>] [--dry-run] [--force]
-dz update   (alias of sync)
-dz doctor [--project <dir>]
+
+## Quick Start
+
+```bash
+# Install a preset (curated skill set) for your platform:
+dz init --target claude-code --preset meta
+
+# That's it — Claude Code will auto-discover the installed skills.
+```
+
+## Presets vs Individual Skills
+
+| Approach | When to use | Example |
+|----------|------------|---------|
+| **Preset** | Want a curated set of skills that work together | `dz init --target claude-code --preset keysarium` |
+| **--select** | Want specific skills by name | `dz init --target claude-code --select explore,feature-adr` |
+| **Standalone npx** | Want a full toolkit with its own CLI | `npx @dzhechkov/keysarium init` |
+
+### Available Presets (7)
+
+| Preset | Skills | Description |
+|--------|--------|-------------|
+| `meta` | 3 | Development process (explore, feature-adr, knowledge-extractor) |
+| `qe-engineer` | 8 | Quality engineering (test-gen, coverage, chaos, defect, ...) |
+| `bto` | 1 | Build-Benchmark-Test-Optimize pipeline |
+| `health` | 8 | Medical AI (diagnostics, drugs, labs, clinical decisions) |
+| `keysarium` | 9 | Full research toolkit (feature-adr, presentation, reverse-eng) |
+| `p-replicator` | 10 | AI product development (/replicate, SPARC PRD, pipeline-forge) |
+| `feature-adr` | 5 | Feature pipeline (feature-adr, explore, frontend-design) |
+
+### Standalone Packages (install via npx, no dz CLI needed)
+
+```bash
+npx @dzhechkov/keysarium init              # full research toolkit
+npx @dzhechkov/p-replicator init           # AI product development
+npx @dzhechkov/health-advisor init         # medical AI (25 skills)
+npx @dzhechkov/skills-bto init             # BTO benchmarking
+npx @dzhechkov/skills-feature-adr init     # 11-step feature pipeline
+npx @dzhechkov/skills-edu-site init        # gamified edu site generator
+npx @dzhechkov/skills-transcript-site init # transcript → interactive site
+npx @dzhechkov/skills-analyst-manual init  # 3-phase analyst composite
+```
+
+**Difference:** `dz init --preset` installs individual skills from `.claude/skills/` source into a target platform tree. Standalone `npx` packages have their own CLI and install a complete toolkit with commands, rules, shards, and agents — a richer but self-contained experience.
+
+## All Commands (11)
+
+```
+dz init      --target <name> [--preset <name>] [--select id,id,...] [--force]
+dz verify    [--skills-dir <dir>] [--target <name>]
+dz sync      [--canonical <dir>] [--project <dir>] [--dry-run] [--force]
+dz update    (alias for sync)
+dz list      [--skills-dir <dir>]
+dz info      --id <skill-id> [--skills-dir <dir>]
+dz migrate   [--project <dir>]
+dz workflow  --task <name> [--dry-run]
+dz doctor    [--project <dir>]
+dz roam      [--apply] [--slug <slug>]
 dz help
 ```
 
-- `--target` — one of `claude-code`, `codex`, `opencode`, `hermes`
-- `init` compiles a skills directory for a target and writes it **additively**
-  (existing files are never overwritten without `--force`)
-- `sync` compares the canonical pack to the legacy `.claude/skills` tree
-- `doctor` reports environment diagnostics
+### Targets (4 platforms)
+
+| Target | Skills directory |
+|--------|-----------------|
+| `claude-code` | `.claude/skills/` |
+| `codex` | `.agents/skills/` |
+| `opencode` | `.opencode/skills/` |
+| `hermes` | `.hermes/skills/` |
+
+### Workflows (Opus 4.8+ dynamic workflows)
+
+```bash
+dz workflow --task coverage-lift     # parallel coverage improvement
+dz workflow --task mutation-kill     # kill surviving mutants
+dz workflow --task canonicalize      # canonicalize new packages
+dz workflow --task security-audit    # adversarial security scan
+```
+
+## How it works
+
+- `dz init` compiles canonical skills from the [agentskills.io](https://agentskills.io) standard into the target platform's layout
+- Writing is **additive** — existing files are never overwritten without `--force`
+- All 4 platform adapters produce **byte-identical** output (ADR-005)
+- `dz doctor` runs 7 health checks (node version, adapters, config, SQLite, skills)
+- `dz migrate` detects legacy keysarium/bto installations and recommends migration path
+
+---
+
+## Use Cases
+
+### 1. Short-term product research (one-off study)
+
+**Goal:** Quickly research a product idea, competitors, market — get a structured report.
+
+```bash
+# Option A: via dz CLI
+dz init --target claude-code --preset meta
+# Then in Claude Code:
+#   /explore "Research the market for AI-powered code review tools"
+#   /feature-adr "Summarize findings into an ADR"
+
+# Option B: via keysarium (full 7-phase pipeline)
+npx @dzhechkov/keysarium init
+# Then in Claude Code:
+#   /casarium "AI-powered code review tools — market analysis"
+#   → Phase 0: Discovery → Phase 1: Exploration → Phase 2: Paranoid Research
+#   → Phase 3: Solution Design → Phase 4: Architecture → Phase 5: Presentation
+```
+
+**What you get:**
+- `meta` preset: `/explore` clarifies the problem → `/feature-adr` structures findings as ADR decisions
+- `keysarium`: full 7-phase pipeline with dream cycles, background workers, and presentation generation
+
+**Best for:** Quick study (hours), competitive analysis, technology evaluation.
+
+---
+
+### 2. Long-term product research (evolving over time)
+
+**Goal:** Continuously gather data, add new sources, and "recalculate" the product vision as insights accumulate.
+
+```bash
+# Install keysarium + memory layer
+npx @dzhechkov/keysarium init
+npm install -g @dzhechkov/harness-cli
+dz init --target claude-code --preset meta
+
+# Additionally install the memory package for persistent learning:
+# (already included if using keysarium)
+```
+
+**Workflow — iterative research cycles:**
+
+```
+Week 1:  /casarium "Product X — initial research"
+         → researches/ directory created with findings
+         → .keysarium/memory/ stores patterns + reward scores
+
+Week 2:  Add new data → /casarium "Product X — update with Q2 metrics"
+         → Memory recalls Week 1 patterns (reward-calibrated learning)
+         → New findings merged with existing, conflicts resolved
+         → Product vision "recalculated" based on accumulated evidence
+
+Week N:  /casarium "Product X — pivot analysis after customer feedback"
+         → Full history available via memory layer
+         → /harvest extracts reusable knowledge patterns
+```
+
+**Key features for long-term research:**
+- **Reward-calibrated memory** (`@dzhechkov/memory` Reflexion): each checkpoint response trains the system — "ок" = excellent (1.0), feedback = good (0.7), rework = needs_work (0.3)
+- **Agent SDK Dreaming**: between sessions, patterns are consolidated and distilled
+- **`/harvest`** (knowledge-extractor skill): extracts reusable patterns from completed research into `lib/` templates
+- **SQLite + FTS5 backend**: scales to 100k+ records with full-text search across all research sessions
+
+**Best for:** Product strategy over months, continuous market monitoring, evolving product vision.
+
+---
+
+### 3. Product research + working prototype
+
+**Goal:** Research the product AND build a functional prototype.
+
+#### Option A: Sequential — research first, then code
+
+```bash
+# Step 1: Install research + development presets
+npx @dzhechkov/keysarium init
+# OR:
+dz init --target claude-code --preset keysarium
+
+# Step 2: Research phase
+#   /casarium "SaaS platform for team retrospectives"
+#   → Phase 0-2: Discovery, Exploration, Paranoid Research
+#   → Phase 3: Solution Design (with CJM prototype)
+#   → Result: researches/<slug>/ with full analysis
+
+# Step 3: Switch to development
+dz init --target claude-code --preset feature-adr
+
+# Step 4: Build using research outputs
+#   /feature-adr "Build the retrospective platform based on research in researches/<slug>/"
+#   → Step 0: Router classifies as L/XL
+#   → Step 1-5: Requirements, ADRs, DDD, Architecture (informed by research)
+#   → Step 6: Implementation plan
+#   → Step 7: Code generation (with /frontend-design for UI)
+#   → Step 8-9: QE review + fleet assessment
+```
+
+**What you get:** Research artifacts in `researches/`, then code in `features/<slug>/` + actual repository changes. Research directly feeds into ADR decisions.
+
+#### Option B: Parallel — research and code simultaneously with p-replicator
+
+```bash
+# Install the full product development toolkit
+npx @dzhechkov/p-replicator init
+
+# Single pipeline: research → requirements → prototype
+#   /replicate "SaaS platform for team retrospectives"
+#   → Reverse-engineers similar products (reverse-engineering-unicorn)
+#   → Generates SPARC PRD (sparc-prd-mini)
+#   → Validates requirements (requirements-validator)
+#   → Creates the project structure (pipeline-forge)
+#   → Builds the prototype (cc-toolkit-generator-enhanced)
+#   → Reviews with brutal honesty (brutal-honesty-review)
+```
+
+**What you get:** A working prototype generated from research in a single `/replicate` pipeline run. Faster but less deep than Option A.
+
+#### Comparison
+
+| Aspect | Option A (Sequential) | Option B (p-replicator) |
+|--------|----------------------|------------------------|
+| **Research depth** | Deep (7-phase keysarium) | Moderate (reverse-engineering) |
+| **Code quality** | High (11-step feature-adr + QE) | Good (pipeline-forge + review) |
+| **Time** | Days to weeks | Hours to days |
+| **Best for** | Complex products, regulated domains | MVPs, hackathons, quick validation |
+| **Packages** | `keysarium` + `feature-adr` preset | `p-replicator` |
+| **Research artifacts** | `researches/` directory | Embedded in PRD |
+| **Code artifacts** | `features/<slug>/` + repo changes | Generated project |
+
+**Tip:** For maximum rigor, combine both — use `p-replicator` for a quick prototype, then run `/feature-adr --full-qe-extended` on the generated code for production-grade quality engineering.
+
+---
 
 ## Status
 
-`0.1.0` — alpha, part of the `extended-a-migration` feature (Phase 6).
-`--preset <name>` (Phase 10) selects a named skill set — see
-`@dzhechkov/harness-presets`. The `paperclip` target is planned for a later phase.
+`v0.2.1` — published on npm. Part of [DZ Harness Hub](https://github.com/djd1m/dz-harness-hub).

package/package.json

@@ -1,15 +1,21 @@
 {
   "name": "@dzhechkov/harness-cli",
-  "version": "0.2.0",
-  "description": "The dz CLI - init / sync / verify / doctor for the DZ cross-platform harness.",
+  "version": "0.2.2",
+  "description": "The dz CLI — install AI skills for Claude Code, Codex, OpenCode, Hermes. 11 commands, 7 presets, 4 platform adapters.",
   "type": "module",
   "license": "MIT",
   "author": "dzhechko",
   "keywords": [
     "agent-skills",
+    "agentskills.io",
     "harness",
     "cli",
-    "claude-code"
+    "claude-code",
+    "codex",
+    "opencode",
+    "hermes",
+    "ai-skills",
+    "cross-platform"
   ],
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",