maestro-flow-one 0.1.0

package/codex/maestro-flow/commands/spec/add.md

@@ -0,0 +1,101 @@
+---
+name: spec-add
+description: Add a spec entry to the appropriate specs file by category
+argument-hint: "<category> <content>"
+allowed-tools: Read, Write, Bash, Glob, Grep
+---
+
+<purpose>
+Add a spec entry using `<spec-entry>` closed-tag format. Each category maps 1:1 to a single target file.
+
+```bash
+$spec-add "coding Always use named exports for utility functions"
+$spec-add "learning Off-by-one in pagination when page=0"
+$spec-add "arch Use Zod for runtime validation over io-ts"
+$spec-add "quality All API endpoints must return structured error objects"
+```
+
+**Valid categories**: coding, arch, quality, debug, test, review, learning, bug, pattern, decision, rule, validation.
+
+**CLI alternative**: `maestro spec add <category> "<title>" "<content>" --keywords kw1,kw2 --source <src>`. Used by workflow agents (analyze, plan, execute) for programmatic spec enrichment.
+</purpose>
+
+<context>
+$ARGUMENTS — `<category> <content>` where category selects the target file.
+
+**Category-to-file mapping (1:1, same as spec-load):**
+| Category | Target file |
+|----------|------------|
+| `coding` | `coding-conventions.md` |
+| `arch` | `architecture-constraints.md` |
+| `quality` | `quality-rules.md` |
+| `debug` | `debug-notes.md` |
+| `test` | `test-conventions.md` |
+| `review` | `review-standards.md` |
+| `learning` | `learnings.md` |
+| `bug` | `learnings.md` |
+| `pattern` | `coding-conventions.md` |
+| `decision` | `architecture-constraints.md` |
+| `rule` | `quality-rules.md` |
+| `validation` | `quality-rules.md` |
+
+Extended types (`bug`, `pattern`, `decision`, `rule`, `validation`) are stored in the file of their closest core category but retain their specific category in the `<spec-entry>` tag.
+</context>
+
+<execution>
+
+### Step 1: Parse Input
+
+Extract category (first token) and content (remainder) from arguments.
+- Validate category is one of: coding, arch, quality, debug, test, review, learning, bug, pattern, decision, rule, validation (E003 if invalid)
+- Validate content is non-empty (E001 if missing)
+
+### Step 2: Validate Specs Directory
+
+Verify `.workflow/specs/` exists (E002).
+
+### Step 3: Route to File
+
+Resolve target file from category-to-file mapping table. If the target file does not exist, create it with a basic header.
+
+### Step 4: Extract Keywords
+
+Auto-extract 3-5 relevant keywords from the content. Keywords should be:
+- Lowercase, no spaces (use hyphens for multi-word)
+- Domain-specific terms that would help future lookup
+- Avoid generic words (code, file, function, etc.)
+
+### Step 5: Write Entry
+
+Append `<spec-entry>` closed-tag block to target file:
+
+```markdown
+<spec-entry category="{category}" keywords="{kw1},{kw2},{kw3}" date="{YYYY-MM-DD}">
+
+### {title extracted from content}
+
+{content}
+
+</spec-entry>
+```
+
+### Step 6: Confirm
+
+Display: category, target file, extracted keywords, and commands for verify (`/spec-load`) and remove (`/spec-remove`).
+</execution>
+
+<error_codes>
+| Code | Severity | Description |
+|------|----------|-------------|
+| E001 | fatal | Category and content are both required |
+| E002 | fatal | `.workflow/specs/` not initialized -- run `Skill({ skill: "maestro-flow", args: "--cmd spec-setup" })` first |
+| E003 | fatal | Invalid category -- must be one of: coding, arch, quality, debug, test, review, learning, bug, pattern, decision, rule, validation |
+</error_codes>
+
+<success_criteria>
+- [ ] Category and content parsed and validated
+- [ ] Keywords auto-extracted from content (3-5 terms)
+- [ ] Entry written in `<spec-entry>` closed-tag format with keywords attribute
+- [ ] Entry appended to correct target file
+- [ ] Confirmation displayed with keywords and verify command
+</success_criteria>

package/codex/maestro-flow/commands/spec/load.md

@@ -0,0 +1,77 @@
+---
+name: spec-load
+description: Load relevant specs for current context, optionally filtered by category or keyword
+argument-hint: "[--category <type>] [--keyword <word>]"
+allowed-tools: Read, Bash, Glob, Grep
+---
+
+<purpose>
+Load relevant specs filtered by category (file-level) and/or keyword (entry-level via `<spec-entry>` tags).
+</purpose>
+
+<context>
+$ARGUMENTS — optional category filter and keyword.
+
+```bash
+$spec-load
+$spec-load "--category coding"
+$spec-load "--keyword auth"
+$spec-load "--category coding --keyword naming"
+```
+
+**Category-to-file mapping (1:1, same as spec-add):**
+
+| Category | File loaded |
+|----------|------------|
+| `coding` | `coding-conventions.md` |
+| `arch` | `architecture-constraints.md` |
+| `quality` | `quality-rules.md` |
+| `debug` | `debug-notes.md` |
+| `test` | `test-conventions.md` |
+| `review` | `review-standards.md` |
+| `learning` | `learnings.md` |
+| `bug` | `learnings.md` |
+| `pattern` | `coding-conventions.md` |
+| `decision` | `architecture-constraints.md` |
+| `rule` | `quality-rules.md` |
+| `validation` | `quality-rules.md` |
+| `all` (default) | All spec files |
+
+Extended types (`bug`, `pattern`, `decision`, `rule`, `validation`) are stored in their closest core category's file but retain their specific category in the `<spec-entry>` tag.
+
+**Keyword filtering**: When `--keyword` is provided, only entries with matching keyword in their `<spec-entry keywords="...">` attribute are returned. Legacy entries (heading format) are filtered by text grep.
+</context>
+
+<execution>
+
+### Step 1: Validate Specs Directory
+
+Verify `.workflow/specs/` exists (E001).
+
+### Step 2: Parse Arguments
+
+Extract optional `--category` and `--keyword` flags.
+
+### Step 3: Load via CLI
+
+Run `maestro spec load [--category <cat>] [--keyword <word>]`. If CLI unavailable, read files directly and apply keyword filter.
+
+### Step 4: Display Results
+
+Show matched entries grouped by filename and category, with `<spec-entry>` tags stripped.
+</execution>
+
+<error_codes>
+| Code | Severity | Description |
+|------|----------|-------------|
+| E001 | fatal | `.workflow/specs/` not initialized -- run `Skill({ skill: "maestro-flow", args: "--cmd spec-setup" })` first |
+| W001 | warning | No matching specs for keyword -- showing all in category |
+</error_codes>
+
+<success_criteria>
+- [ ] `.workflow/specs/` directory validated
+- [ ] Category and keyword parsed from arguments
+- [ ] Files loaded per category mapping
+- [ ] Keyword filtering applied at entry level (via `<spec-entry>` keywords)
+- [ ] Results displayed with file references and stripped tags
+</success_criteria>

package/codex/maestro-flow/commands/spec/remove.md

@@ -0,0 +1,69 @@
+---
+name: spec-remove
+description: Remove a spec entry from a specs file by entry ID using maestro wiki remove-entry
+argument-hint: "<entry-id>"
+allowed-tools: Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion
+---
+
+<purpose>
+Remove a `<spec-entry>` block from a specs container file. Symmetric with `spec-add`.
+Uses `maestro wiki remove-entry` for atomic removal with automatic index update.
+</purpose>
+
+<required_reading>
+@~/.maestro/workflows/specs-remove.md
+</required_reading>
+
+<context>
+$ARGUMENTS — entry ID to remove (e.g., `spec-learnings-003`)
+
+**Entry ID format**: `spec-{file-stem}-{NNN}` — sub-node ID from WikiIndexer atomic indexing.
+
+**Discovery**:
+- `maestro wiki list --type spec --json` — list all spec entries
+- `/spec-load --keyword <term>` — find by keyword
+- `maestro wiki search "<query>"` — BM25 search
+</context>
+
+<execution>
+
+### Step 1: Parse Input
+
+Extract entry ID from arguments.
+- Validate non-empty (E001 if missing)
+- Validate `.workflow/specs/` exists (E002 if not)
+
+### Step 2: Lookup Entry
+
+Run `maestro wiki get <entry-id> --json`. Validate: entry exists (E003), is spec sub-node with `type="spec"` and `parent` set (E004). Extract title, category, keywords, container path.
+
+### Step 3: Confirm
+
+Display entry details. Ask user to confirm unless `-y` flag present.
+
+### Step 4: Remove
+
+Run `maestro wiki remove-entry <entry-id>`. WikiIndexer auto-updates `wiki-index.json`.
+
+### Step 5: Verify & Report
+
+Confirm removal via `maestro wiki get <entry-id>` (should return not-found). Display removed ID, source file, and commands for verify/re-add.
+</execution>
+
+<error_codes>
+| Code | Severity | Description |
+|------|----------|-------------|
+| E001 | fatal | Entry ID is required -- usage: `/spec-remove <entry-id>` |
+| E002 | fatal | `.workflow/specs/` not initialized -- run `/spec-setup` first |
+| E003 | fatal | Entry ID not found in wiki index |
+| E004 | fatal | Entry is not a spec sub-node (wrong type or no parent) |
+</error_codes>
+
+<success_criteria>
+- [ ] Entry ID parsed and validated
+- [ ] Entry found in wiki index (type=spec, has parent)
+- [ ] User confirmed removal
+- [ ] Entry removed via `maestro wiki remove-entry`
+- [ ] Wiki index auto-updated
+- [ ] Confirmation displayed
+</success_criteria>

package/codex/maestro-flow/commands/spec/setup.md

@@ -0,0 +1,75 @@
+---
+name: spec-setup
+description: Initialize project specs by scanning codebase for conventions and tech stack
+argument-hint: ""
+allowed-tools: Read, Write, Bash, Glob, Grep
+---
+
+<purpose>
+Initialize project specs by scanning the codebase and generating spec files in `.workflow/specs/`.
+Core files (coding, arch, learning) always created. Optional files created only when relevant signals detected.
+
+Triggered automatically by `maestro-init` for **existing projects** (source files detected). Greenfield projects skip this — specs are populated progressively by analyze, plan, and execute stages.
+
+```bash
+$spec-setup
+```
+</purpose>
+
+<context>
+No arguments. Scans the codebase and generates spec files in `.workflow/specs/`.
+</context>
+
+<execution>
+
+### Step 1: Validate Preconditions
+
+Verify `.workflow/` exists (E001) and project contains source files (E002).
+
+### Step 2: Scan Codebase
+
+Detect conventions and tech stack by scanning:
+- Package files (`package.json`, `Cargo.toml`, `go.mod`, etc.)
+- Config files (`.eslintrc`, `tsconfig.json`, `.prettierrc`, etc.)
+- Source structure (directories, naming patterns, import style)
+- Test patterns (framework, naming, location)
+
+### Step 3: Generate Core Spec Files (always)
+
+Create `.workflow/specs/` directory and write:
+
+1. **`coding-conventions.md`** — Detected naming, import, formatting patterns (category: `coding`)
+2. **`architecture-constraints.md`** — Structural rules, layer boundaries (category: `arch`)
+3. **`learnings.md`** — Initialized with format instructions for future entries (category: `learning`)
+
+### Step 4: Generate Optional Spec Files (when signals detected)
+
+| File | Created when |
+|------|-------------|
+| `quality-rules.md` | Linter config, CI config, or lint scripts detected |
+| `test-conventions.md` | Test framework, test files, or test scripts detected |
+| `debug-notes.md` | Skipped — created on demand via `spec-add debug` |
+| `review-standards.md` | Skipped — created on demand via `spec-add review` |
+
+### Step 5: Display Report
+
+List created files with categories. Show next steps: `/spec-add <category> <content>`, available categories (core + extended), `/spec-remove`, wiki graph commands.
+
+</execution>
+
+<error_codes>
+
+| Code | Severity | Description |
+|------|----------|-------------|
+| E001 | fatal | `.workflow/` not initialized -- run `Skill({ skill: "maestro-flow", args: "--cmd maestro-init" })` first |
+| E002 | fatal | No source files found in project |
+| W001 | warning | Convention detection uncertain -- marked `[UNCERTAIN]` |
+
+</error_codes>
+
+<success_criteria>
+- [ ] `.workflow/specs/` directory created
+- [ ] 3 core spec files always created (coding, arch, learning)
+- [ ] Optional files created only when relevant signals detected
+- [ ] Completion report displayed with category labels
+</success_criteria>

package/codex/maestro-flow/commands/wiki/connect.md

@@ -0,0 +1,73 @@
+---
+name: wiki-connect
+description: Wiki knowledge graph link discovery and health improvement. Finds orphaned entries, missing connections, transitive gaps. Scores candidates and optionally auto-applies new related links via --fix.
+argument-hint: "[--scope <type>] [--min-similarity N] [--fix] [--max N]"
+allowed-tools: Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion
+---
+
+<purpose>
+Knowledge graph link discovery. Analyzes wiki index to find orphaned entries, missing
+bidirectional links, and transitive closure gaps. Scores connection candidates and
+optionally auto-applies new `related` links to improve graph connectivity.
+</purpose>
+
+<context>
+$ARGUMENTS — optional flags.
+
+**Flags:**
+- `--scope <type>` — Limit to wiki type (spec, knowhow, note, lesson, issue). Default: all.
+- `--min-similarity N` — Threshold 0.0-1.0 (default: 0.3)
+- `--fix` — Auto-apply top suggestions
+- `--max N` — Max suggestions (default: 20)
+
+**Output**: `.workflow/learning/wiki-connections-{date}.md`
+</context>
+
+<execution>
+
+### Stage 1: Load Wiki State
+Parallel `maestro wiki` commands: `list --json`, `health`, `orphans`, `hubs --top 10`.
+
+### Stage 2: Identify Connection Candidates
+- **Orphan rescue**: BM25 search by title, tag overlap, same category/parent
+- **Missing bidirectional**: A→B exists but B→A missing
+- **Transitive closure**: A→B and B→C but no A→C (with shared tags/category)
+- **Type bridge**: Different types referencing same concept but unlinked
+- **Parent cluster**: Entries sharing the same parent but not linked to each other
+
+### Stage 3: Score Candidates
+Score = 0.4 x tag_overlap + 0.3 x title_bm25 + 0.2 x same_category + 0.1 x type_bridge. Filter by `--min-similarity`, rank desc, limit by `--max`.
+
+### Stage 4: Present Suggestions
+Display ranked suggestions with scores, reasons, projected health delta.
+If not `--fix`: display and exit.
+
+### Stage 5: Apply (--fix only)
+For each suggestion: get entry → append target to `related` → update via `maestro wiki update`.
+Re-run `maestro wiki health` for delta.
+
+### Stage 6: Persist
+Write `wiki-connections-{date}.md`. Append graph insights to `lessons.jsonl` (source: "wiki-connect").
+
+**Next steps:** `/wiki-digest <topic>`, `/manage-wiki health`, `/learn-follow <wiki-id>`, `maestro wiki graph`
+</execution>
+
+<error_codes>
+| Code | Severity | Condition | Recovery |
+|------|----------|-----------|----------|
+| E001 | error | No wiki entries found | Initialize wiki content |
+| W001 | warning | No candidates above threshold | Lower --min-similarity |
+| W002 | warning | Some wiki updates failed during --fix | Retry manually |
+| W003 | warning | Health score unchanged after fix | Connections may not affect specific metrics |
+</error_codes>
+
+<success_criteria>
+- [ ] Wiki index loaded with type distribution
+- [ ] Baseline health score recorded
+- [ ] Orphans identified and rescue candidates generated
+- [ ] Candidates scored and ranked
+- [ ] Suggestions displayed with scores and reasons
+- [ ] If --fix: entries updated, new health score reported
+- [ ] Report written to `wiki-connections-{date}.md`
+- [ ] Graph insights appended to `lessons.jsonl`
+</success_criteria>

package/codex/maestro-flow/commands/wiki/digest.md

@@ -0,0 +1,87 @@
+---
+name: wiki-digest
+description: Knowledge synthesis from wiki entries. Theme clustering, gap analysis, coverage heatmap (type × theme matrix). Optionally creates knowledge-gap issues. Persists meta-insights to lessons.jsonl.
+argument-hint: "[<topic>|--recent N] [--type <type>] [--format brief|full] [--create-issues]"
+allowed-tools: Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion
+---
+
+<purpose>
+Knowledge synthesis that generates actionable digests from the wiki knowledge graph.
+Clusters entries by semantic theme, identifies knowledge gaps, and produces a coverage
+heatmap. Unlike `maestro wiki list` (raw entries), this synthesizes and interprets
+the knowledge base with gap analysis and recommended actions.
+</purpose>
+
+<context>
+$ARGUMENTS — scope and optional flags.
+
+**Scope resolution:**
+- `<topic>` — Search wiki for matching entries
+- `--recent N` — Entries updated in last N days
+- `--type <type>` — Filter by wiki type
+- No args — entire wiki
+
+**Flags:**
+- `--format brief` — Compact summary (default)
+- `--format full` — Detailed with per-entry summaries
+- `--create-issues` — Auto-create knowledge-gap issues in issues.jsonl
+
+**Output**: `.workflow/learning/digest-{slug}-{date}.md`
+</context>
+
+<execution>
+
+### Stage 1: Scope & Load
+Load entries via `maestro wiki list/search`. Run `maestro wiki health` for baseline.
+
+### Stage 2: Theme Clustering
+Group entries into 3-5 themes via: tag co-occurrence, title BM25 similarity, relationship proximity, type grouping.
+
+### Stage 3: Per-Theme Analysis
+Per theme: summary paragraph, key entries (by hub score), gap detection (broken links, orphans, TODO markers, missing perspectives), health score.
+
+### Stage 4: Cross-Reference with Lessons
+Search `lessons.jsonl` for related insights. Flag unlinked insights (lessons matching theme but not referenced by wiki entries).
+
+### Stage 5: Coverage Heatmap
+Type × theme matrix showing knowledge density:
+```
+              Theme 1    Theme 2    Theme 3
+spec          ███░░      ░░░░░      █████
+memory        ████░      ███░░      ░░░░░
+lesson        █░░░░      ██░░░      ████░
+```
+Empty cells = knowledge gaps.
+
+### Stage 6: Write Digest
+Produce `digest-{slug}-{date}.md` with themes, heatmap, gaps, unlinked insights, recommended actions.
+
+### Stage 7: Gap → Issue (if --create-issues)
+For each gap: dedup against issues.jsonl, append with `type: "knowledge-gap"`, `source: "wiki-digest"`.
+
+### Stage 8: Persist
+Append meta-insights to `lessons.jsonl` (source: "wiki-digest"). Display summary.
+
+**Next steps:** `/learn-follow <wiki-id>`, `/wiki-connect --fix`, `/manage-wiki cleanup`, `/learn-decompose <path>`
+</execution>
+
+<error_codes>
+| Code | Severity | Condition | Recovery |
+|------|----------|-----------|----------|
+| E001 | error | No wiki entries found | Initialize wiki content |
+| E002 | error | Topic search returned 0 | Broaden topic |
+| W001 | warning | Too few entries (<5) | Themes may be trivial |
+| W002 | warning | lessons.jsonl not found | Skip cross-reference |
+| W003 | warning | Some entry bodies failed to load | Partial summaries |
+</error_codes>
+
+<success_criteria>
+- [ ] Scope parsed and entries loaded
+- [ ] Entries clustered into 3-5 semantic themes
+- [ ] Per-theme analysis with gaps identified
+- [ ] Cross-reference with lessons.jsonl completed
+- [ ] Coverage heatmap generated
+- [ ] If --create-issues: gap issues created (deduped)
+- [ ] Digest written to `digest-{slug}-{date}.md`
+- [ ] Meta-insights appended to lessons.jsonl
+</success_criteria>

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "maestro-flow-one",
+  "version": "0.1.0",
+  "description": "All Maestro workflow commands as a single Claude Code skill — intent routing, decision gates, minimal closed-loop chains",
+  "bin": {
+    "maestro-flow": "bin/maestro-flow.js"
+  },
+  "scripts": {
+    "install-skill": "node bin/maestro-flow.js install"
+  },
+  "keywords": [
+    "claude-code",
+    "workflow",
+    "maestro",
+    "skill",
+    "cli"
+  ],
+  "author": "catlog22",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/catlog22/maestro-flow-one.git"
+  }
+}