@monoes/monomindcli 1.7.0 → 1.9.0

package/.claude/commands/monograph/monograph-build.md

@@ -0,0 +1,79 @@
+---
+name: monograph:monograph-build
+description: Build the knowledge graph from code, docs (md/txt/rst), and PDFs — full index with optional Claude LLM semantic extraction
+---
+
+# monograph build
+
+Build the knowledge graph from code, docs (md/txt/rst), and PDFs.
+
+## Usage
+
+```bash
+npx monomind monograph build [options]
+```
+
+## Options
+
+| Flag | Short | Type | Default | Description |
+|---|---|---|---|---|
+| `--path` | `-p` | string | cwd | Root path to index |
+| `--code-only` | — | boolean | `false` | Index only code files, skip documents |
+| `--llm` | — | boolean | `false` | Enable Claude semantic extraction (requires `ANTHROPIC_API_KEY`) |
+| `--llm-sections` | — | number | `50` | Max sections to enrich with LLM |
+| `--force` | `-f` | boolean | `false` | Force full rebuild even if index is fresh |
+
+## Examples
+
+```bash
+# Build code + all documents (default)
+npx monomind monograph build
+
+# Code only — skip docs and PDFs
+npx monomind monograph build --code-only
+
+# With Claude semantic extraction
+npx monomind monograph build --llm
+
+# Enrich up to 200 sections with Claude
+npx monomind monograph build --llm --llm-sections 200
+
+# Index a specific path
+npx monomind monograph build -p ./src
+
+# Force full rebuild
+npx monomind monograph build --force
+```
+
+## What Gets Indexed
+
+- **Code files** — functions, classes, imports, exports → structured graph nodes
+- **Markdown/MDX** — headings become `Section` nodes; links become edges
+- **Plain text / RST** — chunked into `Section` nodes
+- **PDFs** — text extracted and chunked into nodes
+
+Ignored directories: `node_modules`, `.git`, `dist`, `build`, `__pycache__`, `.cache`, `coverage`, `.monomind`, `vendor`, `target`
+
+## LLM Enrichment
+
+When `--llm` is passed and `ANTHROPIC_API_KEY` is set, Claude extracts typed semantic relationships between sections (e.g. `DESCRIBES`, `CAUSES`, `PART_OF`). These become `INFERRED` edges in the graph, enabling richer semantic search.
+
+## Output
+
+After build, the graph is stored at `.monomind/monograph.db`. Run `monograph stats` to see node/edge counts.
+
+## MCP Tool
+
+```javascript
+mcp__monomind__monograph_build({
+  path: "./",
+  codeOnly: false,
+  force: false
+})
+```
+
+## See Also
+
+- `monograph wiki` — doc/PDF-focused build with better output for documentation projects
+- `monograph stats` — view what was indexed
+- `monograph watch` — auto-rebuild on file changes

package/.claude/commands/monograph/monograph-search.md

@@ -0,0 +1,96 @@
+---
+name: monograph:monograph-search
+description: Search the knowledge graph using BM25 keyword search, semantic (embedding) search, or hybrid RRF-merged results — filter by node type (Section, Function, Class, File, Concept)
+---
+
+# monograph search
+
+Search the knowledge graph using BM25 keyword search, semantic (embedding) search, or hybrid RRF-merged results.
+
+## Usage
+
+```bash
+npx monomind monograph search [options]
+```
+
+## Options
+
+| Flag | Short | Type | Default | Required | Description |
+|---|---|---|---|---|---|
+| `--query` | `-q` | string | — | yes | Search query text |
+| `--limit` | `-l` | number | `15` | no | Maximum results to return |
+| `--label` | — | string | — | no | Filter by node type: `Section`, `Function`, `Concept`, `File`, `Class` |
+| `--mode` | `-m` | string | `hybrid` | no | Search mode: `bm25`, `semantic`, `hybrid` |
+| `--path` | `-p` | string | cwd | no | Root path (location of `.monomind/monograph.db`) |
+
+## Examples
+
+```bash
+# Hybrid search (default) — best general-purpose
+npx monomind monograph search -q "authentication flow"
+
+# Keyword search — exact term matching
+npx monomind monograph search -q "JWT" --mode bm25
+
+# Semantic search — concept/meaning matching
+npx monomind monograph search -q "pipeline architecture" --mode semantic
+
+# Filter to doc sections only
+npx monomind monograph search -q "API design" --label Section
+
+# Find function definitions
+npx monomind monograph search -q "parseToken" --label Function
+
+# More results
+npx monomind monograph search -q "error handling" -l 30
+```
+
+## Search Modes
+
+| Mode | Algorithm | Best For |
+|---|---|---|
+| `hybrid` | RRF merge of BM25 + semantic | General purpose (recommended) |
+| `bm25` | Full-text BM25 ranking | Exact term matching, known symbol names |
+| `semantic` | Embedding cosine similarity | Conceptual queries, meaning-based lookup |
+
+Hybrid mode runs both BM25 and semantic internally, then merges with Reciprocal Rank Fusion (RRF).
+
+## Node Labels (--label filter)
+
+| Label | Represents |
+|---|---|
+| `File` | Source or document files |
+| `Section` | Markdown headings / doc sections |
+| `Function` | Code functions and methods |
+| `Class` | Code classes and interfaces |
+| `Concept` | Extracted semantic concepts |
+
+## Prerequisites
+
+Run `monograph build` or `monograph wiki` first to create the index.
+
+```bash
+# If you see "No knowledge graph found":
+npx monomind monograph build
+```
+
+## MCP Tool
+
+The MCP equivalent for Claude Code integration:
+
+```javascript
+mcp__monomind__monograph_query({
+  query: "authentication flow",
+  limit: 15,
+  label: "Section",
+  mode: "hybrid"
+})
+```
+
+Use `mcp__monomind__monograph_suggest` for task-oriented lookup that returns files ranked by relevance to your current work.
+
+## See Also
+
+- `monograph build` — build the graph index
+- `monograph stats` — see what's indexed
+- `monograph wiki` — doc-focused build

package/.claude/commands/monograph/monograph-stats.md

@@ -0,0 +1,53 @@
+---
+name: monograph:monograph-stats
+description: Show knowledge graph statistics — node counts by type, edge type breakdown, and top concepts by importance score
+---
+
+# monograph stats
+
+Show knowledge graph statistics — node counts by type, edge type breakdown, and top concepts by importance.
+
+## Usage
+
+```bash
+npx monomind monograph stats [options]
+```
+
+## Options
+
+| Flag | Short | Type | Default | Description |
+|---|---|---|---|---|
+| `--path` | `-p` | string | cwd | Root path (location of `.monomind/monograph.db`) |
+| `--top` | — | number | `10` | Number of top concepts to show |
+
+## Examples
+
+```bash
+# Show graph statistics
+npx monomind monograph stats
+
+# Show top 20 concepts
+npx monomind monograph stats --top 20
+
+# Stats for a different project path
+npx monomind monograph stats -p ./other-project
+```
+
+## Output
+
+- **Nodes table** — count per node type (`File`, `Section`, `Function`, `Class`, `Concept`) with bar chart
+- **Edges table** — count per relation type (`IMPORTS`, `TAGGED_AS`, `CO_OCCURS`, `INFERRED`, etc.)
+- **Top N Concepts** — ranked by importance score and section count, shown with star ratings
+- **Summary line** — CO_OCCURS edge count and LLM-inferred edge count
+
+## MCP Tool
+
+```javascript
+mcp__monomind__monograph_stats()
+```
+
+## See Also
+
+- `monograph build` — build or rebuild the graph
+- `monograph search` — search across nodes
+- `monograph watch` — auto-rebuild on changes

package/.claude/commands/monograph/monograph-watch.md

@@ -0,0 +1,63 @@
+---
+name: monograph:monograph-watch
+description: Watch for file changes and incrementally rebuild the knowledge graph — keeps the graph fresh during active development or documentation writing
+---
+
+# monograph watch
+
+Watch for file changes and incrementally rebuild the knowledge graph. Keeps the graph fresh during active development.
+
+## Usage
+
+```bash
+npx monomind monograph watch [options]
+```
+
+## Options
+
+| Flag | Short | Type | Default | Description |
+|---|---|---|---|---|
+| `--path` | `-p` | string | cwd | Root path to watch |
+| `--llm` | — | boolean | `false` | Enable LLM enrichment on each rebuild (requires `ANTHROPIC_API_KEY`) |
+
+## Examples
+
+```bash
+# Watch and rebuild on any file change
+npx monomind monograph watch
+
+# Watch with Claude semantic enrichment on each rebuild
+npx monomind monograph watch --llm
+
+# Watch a specific path
+npx monomind monograph watch -p ./docs
+```
+
+## Behavior
+
+- Runs until `Ctrl+C`
+- Detects changes to code files, markdown, text, RST, and PDFs
+- Triggers incremental rebuild (only changed files re-processed)
+- Outputs progress per phase as changes are detected
+
+## When to Use
+
+- During active documentation writing — graph stays current as you write
+- During refactoring — relationships update as imports change
+- CI environments — run in background to keep graph fresh for search queries
+
+## MCP Tools
+
+```javascript
+// Start watch via MCP
+mcp__monomind__monograph_watch({ path: "./" })
+
+// Stop watch via MCP
+mcp__monomind__monograph_watch_stop()
+```
+
+## See Also
+
+- `monograph build` — one-time full build
+- `monograph wiki` — doc-focused build
+- `monograph stats` — check current graph state

package/.claude/commands/monograph/monograph-wiki.md

@@ -0,0 +1,91 @@
+---
+name: monograph:monograph-wiki
+description: Scan all docs and PDFs and build a searchable knowledge graph — optimized for documentation-heavy projects with Claude LLM semantic extraction
+---
+
+# monograph wiki
+
+Scan all docs and PDFs in the project and build a searchable knowledge graph. Optimized for documentation-heavy projects.
+
+## Usage
+
+```bash
+npx monomind monograph wiki [options]
+```
+
+## Options
+
+| Flag | Short | Type | Default | Description |
+|---|---|---|---|---|
+| `--path` | `-p` | string | cwd | Root path to scan |
+| `--llm` | — | boolean | `false` | Enrich with Claude semantic extraction (requires `ANTHROPIC_API_KEY`) |
+| `--llm-sections` | — | number | `100` | Max sections for LLM enrichment |
+| `--force` | `-f` | boolean | `false` | Force full rebuild |
+
+## Examples
+
+```bash
+# Build knowledge graph from all docs and PDFs
+npx monomind monograph wiki
+
+# With Claude semantic extraction
+npx monomind monograph wiki --llm
+
+# Deep enrichment — process 200 sections with Claude
+npx monomind monograph wiki --llm --llm-sections 200
+
+# Specific docs folder
+npx monomind monograph wiki -p ./docs
+
+# Force full rebuild
+npx monomind monograph wiki --force
+```
+
+## What Gets Indexed
+
+Scans for files with extensions: `.md`, `.mdx`, `.txt`, `.rst`, `.pdf`
+
+| Type | Processing |
+|---|---|
+| `.md` / `.mdx` | Headings → `Section` nodes with hierarchical structure |
+| `.txt` / `.rst` | Chunked → `Section` nodes |
+| `.pdf` | Text extracted → PDF chunk nodes |
+
+## Difference from `build`
+
+| | `build` | `wiki` |
+|---|---|---|
+| Code files | Yes | No |
+| Documents | Yes | Yes |
+| PDFs | Yes | Yes |
+| LLM default sections | 50 | 100 |
+| Best for | Mixed projects | Doc-heavy / knowledge bases |
+
+## LLM Enrichment
+
+With `--llm`, Claude extracts semantic relationships between sections:
+- `DESCRIBES` — section explains a concept
+- `CAUSES` — one event leads to another
+- `PART_OF` — hierarchical membership
+- `CO_OCCURS` — concepts appear together
+
+These `INFERRED` edges make semantic search significantly more accurate.
+
+## After Build
+
+```bash
+# Search your wiki
+npx monomind monograph search -q "your query"
+
+# View statistics
+npx monomind monograph stats
+
+# Auto-rebuild on edits
+npx monomind monograph watch
+```
+
+## See Also
+
+- `monograph build` — full build including code files
+- `monograph search` — search the graph
+- `monograph stats` — node/edge breakdown

package/.claude/commands/monomind/createtask.md

@@ -0,0 +1,277 @@
+---
+name: monomind:createtask
+description: "Monomind — Ingest a prompt, file, or folder, deeply understand it, generate agent-optimized tasks on monotask with smart grouping, prerequisites, and session memory"
+version: 1.0.0
+triggers:
+  - /monomind:createtask
+  - create tasks from spec
+  - decompose into tasks
+  - turn this into tasks
+  - break this down into tasks
+  - create implementation tasks
+---
+
+If `$ARGUMENTS` is empty, output this and STOP:
+
+> **Usage:** `/monomind:createtask <prompt | path-to-file | path-to-folder>`
+>
+> Examples:
+> - `/monomind:createtask Build a webhook delivery system with retries and dead-letter queue`
+> - `/monomind:createtask docs/superpowers/specs/2026-04-27-swarm-tab-redesign-design.md`
+> - `/monomind:createtask docs/superpowers/specs/`
+>
+> This command deeply analyzes your input, generates an implementation plan, and creates **agent-optimized** tasks on monotask — grouped so each agent gets full context, with prerequisites ensuring execution order.
+
+Do NOT proceed further if no arguments were provided.
+
+---
+
+## Step 0: Verify monotask CLI
+
+```bash
+command -v monotask || (command -v cargo && cargo install monotask)
+```
+If neither exists, tell user to install Rust + monotask and STOP.
+
+---
+
+## Step 1: Classify and Ingest Input
+
+Parse `$ARGUMENTS`:
+- `test -f` → file: read with Read tool, store as `RAW_CONTENT`, store filename as `INPUT_LABEL`
+- `test -d` → folder: `find "$ARGUMENTS" -maxdepth 2 -type f ! -name '.*' | head -30`, read each, concatenate with `--- FILE: <path> ---` separators as `RAW_CONTENT`
+- Otherwise → prompt: store text directly as `RAW_CONTENT`
+
+---
+
+## Step 2: Enrich with Project Context
+
+Run ALL in parallel (skip errors):
+1. `mcp__monomind__monograph_suggest` with first 200 chars of `RAW_CONTENT`
+2. `mcp__monomind__monograph_query` for module/component names found in `RAW_CONTENT` (up to 5)
+3. `mcp__monomind__memory_search` with input summary
+4. Read `README.md` (first 200 lines)
+5. Read first found: `package.json`, `Cargo.toml`, `pyproject.toml`, `go.mod`
+6. Repo name from `git remote get-url origin` (strip path, strip `.git`) — store as `REPO_NAME`
+
+Bundle everything into `FULL_CONTEXT`.
+
+---
+
+## Step 3: Setup Monotask Space and Board
+
+**Space**: Find or create space named `$REPO_NAME`. Store `SPACE_ID`.
+
+**Board**: Retrieve stored board ID first: `npx monomind@latest memory search "monomind-task board_id"`. If found, use it as `TASK_BOARD_ID`. Otherwise, list boards in the space via `monotask space boards list $SPACE_ID` and check each via `monotask column list <ID> --json` for a `Backlog` column. If still not found, create:
+```bash
+monotask board create "monomind-task" --json   # captures TASK_BOARD_ID from .id
+monotask space boards add $SPACE_ID $TASK_BOARD_ID
+npx monomind@latest memory store --key "monomind-task board_id" --value "$TASK_BOARD_ID" --namespace monomind
+```
+Create columns in order: `Backlog` → `Todo` → `In Progress` → `Review` → `Human in Loop` → `Done`
+
+Store all column IDs mapped by name. Store `TASK_BOARD_ID`.
+
+---
+
+## Step 4: Deep Analysis
+
+Spawn a `Software Architect` agent. Provide `FULL_CONTEXT` + `$ARGUMENTS`.
+
+Required output:
+```json
+{
+  "summary": "2-3 sentence overview",
+  "goals": ["high-level goals"],
+  "components": [
+    {
+      "name": "component name",
+      "description": "what it does",
+      "dependencies": ["other components"],
+      "files_likely_affected": ["paths from monograph or educated guesses"]
+    }
+  ],
+  "technical_constraints": ["stack requirements, limitations"],
+  "acceptance_criteria": ["testable conditions for when the whole thing is done"],
+  "risks": ["pitfalls, ambiguities, unknowns"]
+}
+```
+
+Store as `ANALYSIS`.
+
+---
+
+## Step 5: Generate Professional Tasks
+
+Spawn a `planner` agent. Provide analysis + `FULL_CONTEXT`.
+
+### Task Grouping Rules (enforce all 7)
+
+1. **Context Affinity**: Work sharing the same files, types, or domain model goes in ONE task. Tests always travel with their implementation.
+2. **Size Limit**: If a context group exceeds 30 minutes, split into a prerequisite chain.
+3. **Independence**: Work touching different modules with no shared types should be separate (parallelizable).
+4. **Test Colocation**: Never create standalone "write tests" tasks — only exception is integration/e2e tests spanning multiple components.
+5. **Prerequisite Chains**: Use `prerequisites` to enforce ordering. Same agent picks up the chain in sequence.
+6. **Chain Size Limit**: Max 4 tasks per chain. Split larger chains into two sub-chains linked by prerequisite.
+7. **Agent Capability**: Agent type must match the domain (no frontend agent on DB migrations, no backend-dev on CSS).
+
+### Task Card Format
+
+For each task, produce:
+```json
+{
+  "title": "Action-oriented title (verb + noun + context)",
+  "description": "## What\nExact deliverable.\n\n## Why\nMotivation.\n\n## Where\nFile paths, module boundaries.\n\n## Patterns\nExisting conventions to follow.",
+  "context": "All relevant context: patterns, related files, API shapes, data models. Include file paths from monograph.",
+  "definition_of_done": ["Specific, binary, verifiable condition"],
+  "testing_criteria": {
+    "unit_tests": ["function(input) → expected outcome"],
+    "integration_tests": ["endpoint + method → status + response shape"],
+    "edge_cases": ["boundary condition → expected behavior"]
+  },
+  "checklist": [
+    "Write failing test for [specific behavior]",
+    "Implement [function/class] in [file path]",
+    "Run tests — verify green",
+    "Commit: '[type]: [description]'"
+  ],
+  "agent_type": "best-fit agent from 230+ roster",
+  "priority": "critical | high | medium | low",
+  "effort": "1-10",
+  "prerequisites": ["titles of tasks that MUST complete first"],
+  "parallel_safe": true,
+  "context_group": "name of context chain, or 'independent'"
+}
+```
+
+Store as `TASKS` array.
+
+---
+
+## Step 6: Create Cards on Monotask
+
+For each task, in prerequisite order:
+
+1. **Create card** in `Todo` (no prerequisites) or `Backlog` (has prerequisites):
+   ```bash
+   monotask card create $TASK_BOARD_ID $COLUMN_ID "<title>" --json
+   ```
+
+2. **Set description**:
+   ```bash
+   monotask card set-description $TASK_BOARD_ID $CARD_ID "<description>\n\n## Context\n<context>\n\n## Context Group\n<context_group>"
+   ```
+
+3. **Add DOD comment**:
+   ```bash
+   monotask card comment add $TASK_BOARD_ID $CARD_ID "## Definition of Done\n- [ ] <condition 1>\n..."
+   ```
+
+4. **Add testing criteria comment**:
+   ```bash
+   monotask card comment add $TASK_BOARD_ID $CARD_ID "## Testing Criteria\n\n### Unit Tests\n- <test 1>\n\n### Integration Tests\n- <test 1>\n\n### Edge Cases\n- <case 1>"
+   ```
+
+5. **Add agent assignment + metadata**:
+   ```bash
+   monotask card comment add $TASK_BOARD_ID $CARD_ID "Assigned agent: <agent_type>\nContext group: <context_group>\nParallel safe: <true|false>\nPriority: <priority>\nEffort: <effort>/10\nPrerequisites: <task titles or none>\nSource: monomind:createtask"
+   ```
+
+6. **Set priority**: Extract priority from the current task, map to integer, then call:
+   ```bash
+   PRIORITY="<current task's priority field — one of: critical, high, medium, low>"
+   case "$PRIORITY" in
+     critical) PNUM=1 ;; high) PNUM=2 ;; medium) PNUM=3 ;; *) PNUM=4 ;;
+   esac
+   monotask card set-priority $TASK_BOARD_ID $CARD_ID $PNUM
+   ```
+
+7. **Create checklist**: Create the checklist, capture each item's ID from stdout, and store all IDs in a comment for `/monomind:do` to use when marking items complete:
+   ```bash
+   checklist_result=$(monotask checklist add $TASK_BOARD_ID $CARD_ID "Implementation Steps" --json)
+   CHECKLIST_ID=$(echo "$checklist_result" | jq -r '.id // empty')
+   ITEM_IDS=""
+   # For each checklist step <step>:
+   item_out=$(monotask checklist item-add $TASK_BOARD_ID $CARD_ID $CHECKLIST_ID "<step>")
+   ITEM_ID=$(echo "$item_out" | grep -oE '[0-9a-f-]{36}$')
+   ITEM_IDS="${ITEM_IDS:+$ITEM_IDS,}$ITEM_ID"
+   # (repeat for each step)
+   # After all items added, persist IDs:
+   monotask card comment add $TASK_BOARD_ID $CARD_ID "CHECKLIST_ID: $CHECKLIST_ID"
+   monotask card comment add $TASK_BOARD_ID $CARD_ID "ITEM_IDS: $ITEM_IDS"
+   ```
+
+---
+
+## Step 7: Store Session Memory
+
+Call `mcp__monomind__memory_store` with:
+```json
+{
+  "key": "task-strategy:<REPO_NAME>:<timestamp>",
+  "content": {
+    "source": "monomind:createtask: <first 100 chars of $ARGUMENTS>",
+    "total_tasks": "N",
+    "context_groups": [
+      { "name": "group name", "task_titles": ["..."], "recommended_agent": "agent type", "sequential": true }
+    ],
+    "independent_tasks": ["titles of parallel-safe tasks"],
+    "recommended_execution_mode": "parallel | minimal | sequential",
+    "reasoning": "Why this mode fits"
+  },
+  "tags": ["task-strategy", "monomind:createtask"]
+}
+```
+
+Mode selection: **parallel** = mostly independent tasks; **minimal** = mixed; **sequential** = heavy shared state.
+
+---
+
+## Step 8: Final Dependency Review
+
+Spawn a fresh `Code Reviewer` agent. Provide the complete `TASKS` array and `REPO_NAME`.
+
+The agent MUST check:
+- **Prerequisite integrity**: all referenced prerequisites exist, no circular deps, no orphans
+- **Context group consistency**: compatible agent types per group, no group >4 tasks, tasks in group are chained
+- **Critical path**: identify longest chain, flag if >6 tasks or any single task >effort 7
+- **Parallel safety**: `parallel_safe: true` tasks don't share modified files
+- **Agent assignment**: no frontend agent on backend tasks, no agent in >5 context groups
+
+**If APPROVED**: present summary and proceed to execution offer.
+**If NEEDS_FIXES**: auto-fix blockers (update card comments), present warnings to user, max 2 fix cycles.
+
+---
+
+## Step 9: Gap Analysis
+
+Spawn a fresh `Software Architect` agent as critical reviewer. Provide `ANALYSIS` + all created tasks.
+
+Identify:
+- **Missing pieces**: testing gaps, error handling holes, security oversights, missing migrations
+- **Follow-ups**: natural extensions, performance optimizations
+
+Present as tables. Ask user which to add (`numbers`, `all`, or `none`). Selected missing pieces → `Todo`; follow-ups → `Backlog`.
+
+---
+
+## Step 10: Summary and Execution Offer
+
+Output:
+```
+## Task Creation Complete
+
+**Source:** <input>
+**Space:** $REPO_NAME | **Board:** monomind-task
+
+| # | Title | Agent | Priority | Effort | Column | Deps |
+|---|-------|-------|----------|--------|--------|------|
+| 1 | ...   | ...   | high     | 3      | Todo   | —    |
+
+**Total:** N tasks (X in Todo, Y in Backlog)
+```
+
+If there are tasks in Todo:
+> **N tasks ready.** Start `/monomind:do` to execute them autonomously?
+
+If yes: `Skill("monomind:do", "--space $SPACE_ID --board $TASK_BOARD_ID")`