maestro-flow 0.5.31 → 0.5.33

package/.agents/skills/prompt-generator/specs/conversion-spec.md

@@ -0,0 +1,207 @@
+# Conversion Specification
+
+Rules for restyling existing command/agent files to GSD conventions. **Zero content loss is mandatory.**
+
+## Core Principle
+
+Conversion = structural transformation, NOT content rewriting. Every line of source content must appear in the output. Only the container (XML tags, section ordering, frontmatter format) changes.
+
+## Content Loss Prevention Protocol
+
+### Pre-conversion Inventory
+
+Before converting, count:
+- `$SRC_LINES` — total non-empty lines
+- `$SRC_BLOCKS` — code block count (``` pairs)
+- `$SRC_TABLES` — table count (lines starting with `|`)
+- `$SRC_SECTIONS` — section count (## headers)
+
+### Post-conversion Verification
+
+| Metric | Rule | Action on Fail |
+|--------|------|----------------|
+| Lines | output >= source × 0.95 | STOP — find missing content |
+| Code blocks | output >= source | STOP — find missing blocks |
+| Tables | output >= source | STOP — find missing tables |
+| Sections | output >= source | WARN — sections may have merged |
+
+### Diff Display
+
+After conversion, show summary:
+```
+Conversion Summary:
+  Source: {path} ({src_lines} lines, {src_blocks} code blocks)
+  Output: {path} ({out_lines} lines, {out_blocks} code blocks)
+  Delta:  {+/-} lines, {+/-} code blocks
+  New sections added: {list of TODO sections}
+```
+
+## Artifact Type Detection
+
+Before applying conversion rules, determine the source type:
+
+| Source Location | Type |
+|----------------|------|
+| `.claude/commands/**/*.md` | command |
+| `.claude/skills/*/SKILL.md` | skill |
+| `.claude/agents/*.md` | agent |
+
+**Skill detection signals**: `allowed-tools:` in frontmatter, located in `.claude/skills/` directory, progressive phase loading pattern (`read_file("phases/...")`)
+
+## Skill Conversion Rules
+
+### Critical: No @ References
+
+Skills are loaded **progressively inline** into the conversation context. They CANNOT use `@` file references — these only work in commands.
+
+### Source Pattern → Target Pattern (Skill)
+
+| Source Style | Target Style |
+|-------------|-------------|
+| `# Title` + flat markdown overview | `<purpose>` (2-3 sentences) |
+| `## Implementation` / `## Execution Flow` / `## Phase Summary` | `<process>` with numbered `## N.` steps |
+| Phase file references as prose | `read_file("phases/...")` calls within process steps |
+| `## Success Criteria` / `## Coordinator Checklist` | `<success_criteria>` with checkbox list |
+| `## Auto Mode` / `## Auto Mode Defaults` | `<auto_mode>` section |
+| `## Error Handling` | Preserve as-is within `<process>` or as standalone section |
+| Code blocks, tables, ASCII diagrams | **Preserve exactly** |
+
+### What NOT to Add (Skill-Specific)
+
+| Element | Why NOT |
+|---------|---------|
+| `<required_reading>` | Skills cannot use `@` refs — progressive loading |
+| `@specs/...` or `@phases/...` | `@` syntax not supported in skills |
+| `<offer_next>` | Skills chain via `invoke_skill()` calls, not offer menus |
+
+### What to ADD (Skill-Specific)
+
+| Missing Element | Add |
+|----------------|-----|
+| `<purpose>` | Extract from overview/description |
+| `<process>` wrapper | Wrap implementation steps |
+| `<success_criteria>` | Generate from coordinator checklist or existing content |
+| `<auto_mode>` | If auto mode behavior exists, wrap in tag |
+
+### Frontmatter Conversion (Skill)
+
+| Source Field | Target Field | Transformation |
+|-------------|-------------|----------------|
+| `name` | `name` | Keep as-is |
+| `description` | `description` | Keep as-is |
+| `allowed-tools` | `allowed-tools` | Keep as-is |
+| Missing `allowed-tools` | `allowed-tools` | Infer from content |
+
+## Command Conversion Rules
+
+### Source Pattern → Target Pattern
+
+| Source Style | Target Style |
+|-------------|-------------|
+| `# Title` + `## Phase N:` flat markdown | `<purpose>` + `<process>` with numbered `## N.` steps |
+| `## Implementation` + `### Phase N` | `<process>` with numbered steps, content preserved |
+| `## Overview` / `## Core Principle` | `<purpose>` (merge into 2-3 sentences) + keep details in steps |
+| `## Usage` with examples | Keep as-is inside `<process>` step 1 or before `<process>` |
+| `## Auto Mode` / `## Auto Mode Defaults` | `<auto_mode>` section |
+| `## Quick Reference` | Preserve as-is within appropriate section |
+| Inline `ask_user` calls | Preserve verbatim — these belong in commands |
+| `delegate_subagent()` / agent spawning calls | Preserve verbatim within process steps |
+| Banner displays (`━━━`) | Preserve verbatim |
+| Code blocks (```bash, ```javascript, etc.) | **Preserve exactly** — never modify code content |
+| Tables | **Preserve exactly** — never reformat table content |
+
+### Frontmatter Conversion
+
+| Source Field | Target Field | Transformation |
+|-------------|-------------|----------------|
+| `name` | `name` | Keep as-is |
+| `description` | `description` | Keep as-is |
+| `argument-hint` | `argument-hint` | Keep as-is |
+| `allowed-tools` | `allowed-tools` | Keep as-is |
+| Missing `allowed-tools` | `allowed-tools` | Infer from content (Read, Write, etc.) |
+
+### Section Wrapping
+
+Content that was under plain `##` headers gets wrapped in XML tags:
+
+```
+## Overview / ## Core Principle  → content moves to <purpose>
+## Process / ## Implementation  → content moves to <process>
+## Success Criteria             → content moves to <success_criteria>
+## Error Codes                  → preserve as-is (optional section)
+```
+
+**Everything else**: Wrap in appropriate GSD tag or keep as custom section inside `<process>`.
+
+### What to ADD (with TODO markers)
+
+| Missing Element | Add |
+|----------------|-----|
+| `<purpose>` | Extract from overview/description, mark `<!-- TODO: refine -->` if uncertain |
+| `<success_criteria>` | Generate from existing content, mark `<!-- TODO: verify -->` |
+| `<offer_next>` | Add skeleton with `<!-- TODO: fill next commands -->` |
+| Banners | Add before major transitions if missing |
+
+## Agent Conversion Rules
+
+### Source Pattern → Target Pattern
+
+| Source Style | Target Style |
+|-------------|-------------|
+| Plain prose role description | `<role>` with structured format |
+| `## Core Philosophy` / `## Principles` | `<philosophy>` |
+| `## Execution Process` / `## How to` | Domain section with descriptive name |
+| `## Quality Gates` / `## Standards` | `<quality_gate>` with checkbox format |
+| Flat numbered list of responsibilities | `<role>` core responsibilities bullet list |
+| `## Examples` section | Move examples INTO relevant domain sections |
+
+### Frontmatter Conversion
+
+| Source Field | Target Field | Transformation |
+|-------------|-------------|----------------|
+| `name` | `name` | Keep as-is |
+| `description` | `description` | Append "Spawned by /command orchestrator." if missing |
+| `color` | `color` | Keep as-is |
+| Missing `tools` | `tools` | Infer from content (Read, Write, Bash, etc.) |
+
+### Section Restructuring
+
+1. **`<role>` MUST be first** — gather identity content from wherever it appears
+2. **Add "Spawned by:"** if missing — infer from description or mark `<!-- TODO: specify spawner -->`
+3. **Add "Mandatory Initial Read"** block if missing
+4. **Rename generic sections**: `<rules>` → descriptive name based on content
+5. **Add `<output_contract>`** if missing — with TODO marker
+6. **Add `<quality_gate>`** if missing — with TODO marker
+
+### What NOT to Change
+
+- Code blocks inside sections — preserve exactly
+- Tables — preserve exactly
+- Concrete examples (good/bad comparisons) — preserve exactly
+- Shell commands — preserve exactly
+- Agent prompts — preserve exactly
+- Domain-specific terminology — preserve exactly
+
+## Batch Conversion
+
+For converting multiple files:
+
+```bash
+# List candidates
+ls .claude/commands/**/*.md .claude/agents/*.md
+
+# Convert one at a time, verify each
+/prompt-generator convert .claude/commands/issue/new.md
+/prompt-generator convert .claude/agents/universal-executor.md
+```
+
+## Anti-Patterns
+
+| Anti-Pattern | Why It's Wrong |
+|-------------|----------------|
+| Rewriting code blocks | Content loss — code is sacred |
+| Summarizing verbose sections | Content loss — preserve verbatim |
+| Removing "redundant" content | User may depend on it |
+| Merging sections without inventory | May lose content silently |
+| Adding content beyond structural tags | Conversion adds structure, not content |
+| Skipping post-conversion line count | Cannot verify zero content loss |

package/.agents/skills/prompt-generator/templates/agent-md.md

@@ -0,0 +1,145 @@
+# Agent Template — Structural Reference
+
+Defines the structural pattern for generated **agent definition files**. The generator uses this as a guide to produce concrete, domain-specific content — NOT as a literal copy target.
+
+## Required Structure
+
+```markdown
+---
+name: {$NAME}
+description: {One-line purpose. Spawned by /command-name orchestrator.}
+tools: {Read, Write, Bash, Glob, Grep}
+color: {green|blue|yellow|red}  # optional
+---
+
+<role>
+You are a {role name}. You {primary action} {what you produce}.
+
+Spawned by:
+- `/{command}` orchestrator (standard mode)
+- `/{command} --flag` orchestrator (variant mode)
+
+Your job: {One sentence — what downstream consumers get from you.}
+
+**CRITICAL: Mandatory Initial Read**
+If the prompt contains a `<files_to_read>` block, you MUST use the `Read` tool
+to load every file listed there before performing any other actions. This is your
+primary context.
+
+**Core responsibilities:**
+- {Verb phrase — primary task}
+- {Verb phrase — secondary task}
+- {Verb phrase — quality assurance}
+- Return structured results to orchestrator
+</role>
+
+<philosophy>
+## {Guiding Principle Name}
+
+{Core beliefs — 3-5 bullet points}
+
+**Anti-patterns (delete if seen):**
+- {Anti-pattern 1}
+- {Anti-pattern 2}
+</philosophy>
+
+<{domain_section_1}>
+## {Domain Concept Name}
+
+{Rules, heuristics, decision tables for this aspect.}
+
+| {Condition} | {Action} |
+|-------------|----------|
+| ...         | ...      |
+
+{Concrete examples — good vs bad:}
+
+| TOO VAGUE | JUST RIGHT |
+|-----------|------------|
+| "..." | "..." |
+</{domain_section_1}>
+
+<{domain_section_2}>
+## {Another Domain Concept}
+
+{Format templates, structural rules, required fields.}
+
+Every {output unit} has {N} required fields:
+- **<field_1>:** {What it contains, why it matters}
+- **<field_2>:** {What it contains, why it matters}
+</{domain_section_2}>
+
+<output_contract>
+## Return Protocol
+
+Agent returns one of these markers to the orchestrator:
+
+### Success
+```
+## TASK COMPLETE
+
+{Structured output summary}
+{Artifact locations}
+```
+
+### Blocked
+```
+## TASK BLOCKED
+
+**Blocker:** {What's missing}
+**Need:** {What would unblock}
+```
+
+### Checkpoint
+```
+## CHECKPOINT REACHED
+
+**Question:** {Decision needed from user}
+**Options:**
+1. {Option A} — {effect}
+2. {Option B} — {effect}
+```
+</output_contract>
+
+<quality_gate>
+Before returning, verify:
+- [ ] {Check 1 — concrete, verifiable}
+- [ ] {Check 2 — concrete, verifiable}
+- [ ] {Check 3 — concrete, verifiable}
+- [ ] {Check 4 — concrete, verifiable}
+</quality_gate>
+```
+
+## Section Design Guidelines
+
+### Section Naming
+
+Name sections after the domain concept they cover:
+
+| Good | Bad |
+|------|-----|
+| `<task_breakdown>` | `<rules>` |
+| `<dependency_graph>` | `<guidelines>` |
+| `<code_style>` | `<misc>` |
+| `<review_dimensions>` | `<other>` |
+
+### Section Independence
+
+Each section owns ONE concern. Test: can you explain the section's scope in one sentence?
+
+| One Concern | Multiple Concerns (split it) |
+|-------------|------------------------------|
+| How to size tasks | How to size tasks AND how to order them |
+| Review criteria | Review criteria AND how to present results |
+| Error handling rules | Error handling AND logging AND monitoring |
+
+### Example Density
+
+Domain sections MUST include concrete examples. Minimum per section:
+
+| Section Type | Minimum Examples |
+|-------------|-----------------|
+| Rules/heuristics | 1 good-vs-bad table |
+| Format definitions | 1 complete template |
+| Decision logic | 1 routing table |
+| Quality criteria | 3+ checkbox items |

package/.agents/skills/prompt-generator/templates/command-md.md

@@ -0,0 +1,118 @@
+# Command Template — Structural Reference
+
+Defines the structural pattern for generated **command files**. The generator uses this as a guide to produce concrete, domain-specific content — NOT as a literal copy target.
+
+## Required Structure
+
+```markdown
+---
+name: {$NAME}
+description: {$DESCRIPTION}
+argument-hint: {$ARGUMENT_HINT}  # omit if empty
+allowed-tools: {tools}           # omit if unrestricted
+---
+
+<purpose>
+{2-3 sentences: what it does + when invoked + what it produces}
+</purpose>
+
+<required_reading>
+{@ references to files needed before execution}
+</required_reading>
+
+<process>
+
+## 1. Initialize
+
+{Load context, parse $ARGUMENTS, validate preconditions.}
+
+{Argument table:}
+| Flag/Arg | Required | Description |
+|----------|----------|-------------|
+| `$ARG1`  | Yes      | ...         |
+| `--flag` | No       | ...         |
+
+{Validation: missing required → error, invalid → error with usage hint.}
+
+## 2. {Domain Action}
+
+{Display banner:}
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ SKILL ► ACTION
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+{Core orchestration logic — file checks, state validation, conditional routing.}
+
+## 3. Spawn delegate_subagent(if applicable)
+
+{Construct prompt with <files_to_read>, <objective>, <output> blocks.}
+
+```javascript
+delegate_subagent({
+  subagent_type: "{agent-name}",
+  prompt: filled_prompt,
+  description: "{Verb} {target}",
+  run_in_background: false
+})
+```
+
+## 4. Handle Result
+
+{Route on agent return markers:}
+- `## TASK COMPLETE` → continue to next step
+- `## TASK BLOCKED` → display blocker, offer options
+- `## CHECKPOINT REACHED` → present to user, relay response
+
+## N. Present Status
+
+{Route to <offer_next>.}
+
+</process>
+
+<offer_next>
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ SKILL ► TASK COMPLETE
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+**{Summary line}**
+
+{Status table or key-value pairs}
+
+## Next Up
+
+/{next-command} {args}
+
+**Also available:**
+- /{alt-command-1} — description
+- /{alt-command-2} — description
+</offer_next>
+
+<success_criteria>
+- [ ] {Precondition validated}
+- [ ] {Core action completed}
+- [ ] {Agent spawned and returned (if applicable)}
+- [ ] {Output artifact produced / effect applied}
+- [ ] {Status displayed to user}
+</success_criteria>
+```
+
+## Step Naming Conventions
+
+| Domain | Typical Steps |
+|--------|--------------|
+| Deploy/Release | Initialize, Validate Config, Run Deployment, Verify Health, Present Status |
+| CRUD | Initialize, Validate Entity, Persist Changes, Present Status |
+| Analysis | Initialize, Gather Context, Spawn Analyzer, Present Findings |
+| Multi-Agent | Initialize, Spawn Agent A, Handle A Result, Spawn Agent B, Revision Loop, Present Status |
+| Pipeline | Initialize, Stage 1, Handle Stage 1, Stage 2, Handle Stage 2, Present Status |
+
+## Content Quality Rules
+
+| Rule | Bad | Good |
+|------|-----|------|
+| No placeholders | `[Describe purpose]` | `Deploy to target environment with rollback on failure.` |
+| Concrete steps | `Handle the deployment` | `Run kubectl apply, wait for rollout, check health endpoint` |
+| Specific errors | `Error: invalid` | `Error: --env must be "prod" or "staging"` |
+| Verifiable criteria | `Works correctly` | `Health endpoint returns 200 within 30s` |

package/.agents/skills/scholar-anti-ai-writing/SKILL.md

@@ -0,0 +1,175 @@
+---
+name: scholar-anti-ai-writing
+description: Remove AI writing patterns from academic prose. Detects and fixes inflated symbolism, promotional language, superficial analyses, vague attributions, AI vocabulary, and formulaic structures. Supports English and Chinese. Triggers on "remove AI patterns", "humanize text", "anti-AI polish", "去除AI写作痕迹", "人性化处理".
+allowed-tools: read_file, write_file, edit_file, shell, find_files, search, ask_user, track_tasks
+---
+<!-- Open-standard mirror generated by scripts/build-agents-standard.mjs — do not edit; re-run after editing .claude/ source. -->
+
+
+# Scholar Anti-AI Writing
+
+Detect and eliminate AI writing patterns from academic prose. Based on Wikipedia's "Signs of AI writing" guide. Supports both English and Chinese text.
+
+**Core insight**: LLMs predict the most statistically likely outcome — creating detectable patterns. This skill identifies and rewrites those patterns while preserving meaning and adding authentic voice.
+
+## Pre-load (before execution)
+
+1. **Codebase docs**: If `.workflow/codebase/ARCHITECTURE.md` exists, read for project context
+2. **Specs**: `maestro spec load --category coding` — load coding conventions
+3. **Wiki knowledge**: `maestro search "academic writing research paper" --json` — top 5 entries as prior context
+4. All optional — proceed without if unavailable
+
+## Architecture Overview
+
+```
+User: "Remove AI patterns from my paper"
+         |
+         v
+┌──────────────────────────────────────────────────────────────┐
+│  SKILL.md (Orchestrator)                                      │
+│  Collect preferences → Dispatch phases → Track progress       │
+└──────────┬───────────────────────────────────────────────────┘
+           |
+   ┌───────┼───────────┬──────────────┐
+   v       v           v              v
+┌──────┐┌──────────┐┌──────────────┐
+│ P1   ││ P2       ││ P3           │
+│Detect││ Rewrite  ││ Validate     │
+│ &    ││ & Polish ││ & Score      │
+│Score ││          ││              │
+└──┬───┘└────┬─────┘└──────┬───────┘
+   │         │             │
+   v         v             v
+ pattern   polished     final score
+ report    prose        + diff report
+```
+
+## Key Design Principles
+
+1. **Pattern detection + soul injection**: Removing AI patterns is only half the job — add authentic voice.
+2. **Preserve meaning**: Core content and technical claims must remain intact.
+3. **Language-aware**: English and Chinese have different AI pattern signatures.
+4. **Scoring-driven**: Quantitative 5-dimension scoring (50-point scale) guides revision.
+5. **Academic tone**: Maintain scholarly register — humanize without becoming informal.
+
+## Interactive Preference Collection
+
+Before dispatching to any phase, collect these preferences:
+
+```
+Questions to ask the user:
+
+1. Input Source
+   "What text should I process? (file path, directory, or paste text)"
+   → inputSource
+
+2. Language
+   Options: English | Chinese | Bilingual (auto-detect per section)
+   → language
+
+3. Writing Context
+   Options: Academic Paper | Technical Report | Blog/Article | General Prose
+   → writingContext
+
+4. Aggressiveness
+   Options: Conservative (minimal changes) | Balanced (Recommended) | Aggressive (heavy rewrite)
+   → aggressiveness
+```
+
+Store responses as `antiAiPreferences` context for all phases.
+
+## Auto Mode Defaults
+
+When `workflowPreferences.autoYes === true`:
+- Process all .tex files in cwd
+- Auto-detect language
+- Academic Paper context, Balanced aggressiveness
+- Skip confirmation prompts
+
+## Execution Flow
+
+> **COMPACT DIRECTIVE**: Context compression MUST check track_tasks phase status.
+> The phase currently marked `in_progress` is the active execution phase — preserve its FULL content.
+> Only compress phases marked `completed` or `pending`.
+
+### track_tasks Setup
+
+```
+Anti-AI Writing:
+- [ ] Phase 1: Detect & Score — scan for AI patterns, generate initial score
+- [ ] Phase 2: Rewrite & Polish — rewrite flagged sections, add voice
+- [ ] Phase 3: Validate & Score — re-score, verify quality threshold
+```
+
+### Phase Sequence
+
+```
+Phase 1: Detect & Score
+   └─ Ref: phases/01-detect-score.md
+      ├─ Input: inputSource, language
+      └─ Output: patternReport (flagged passages + initial scores)
+
+Phase 2: Rewrite & Polish
+   └─ Ref: phases/02-rewrite-polish.md
+      ├─ Input: patternReport, writingContext, aggressiveness
+      └─ Output: polishedText (rewritten content)
+
+Phase 3: Validate & Score
+   └─ Ref: phases/03-validate-score.md
+      ├─ Input: polishedText, original text
+      └─ Output: finalReport (before/after scores, diff)
+```
+
+**Phase Reference Documents** (read on-demand when phase executes):
+
+| Phase | Document | Purpose | Compact |
+|-------|----------|---------|---------|
+| 1 | [phases/01-detect-score.md](phases/01-detect-score.md) | Scan patterns, score text | track_tasks driven |
+| 2 | [phases/02-rewrite-polish.md](phases/02-rewrite-polish.md) | Rewrite and humanize | track_tasks driven + sentinel |
+| 3 | [phases/03-validate-score.md](phases/03-validate-score.md) | Re-score, generate report | track_tasks driven |
+
+**Compact Rules**:
+1. **track_tasks `in_progress`** → preserve full content, do not compress
+2. **track_tasks `completed`** → may compress to summary
+3. **sentinel fallback** → phases marked with sentinel contain compact sentinel; if only sentinel remains, **must immediately `read_file()` to recover**
+
+## Core Rules
+
+1. **Never lose meaning**: Technical claims, data, and specific facts must survive rewriting.
+2. **Score before and after**: Every processed text gets a 5-dimension score (50-point scale).
+3. **Flag, don't force**: In Conservative mode, highlight issues but let the user decide.
+4. **Academic register**: For papers, maintain formal-but-natural tone. No slang or casual language.
+5. **Minimum threshold**: Target score >= 35/50 for academic papers, >= 40/50 for submission-ready.
+
+## Quick Scoring System (5 dimensions, 10 points each)
+
+| Dimension | Question | Target |
+|-----------|----------|--------|
+| **Directness** | Direct statements or announcements? | >= 7 |
+| **Rhythm** | Varied or metronomic? | >= 7 |
+| **Trust** | Respects reader intelligence? | >= 7 |
+| **Authenticity** | Sounds human? | >= 7 |
+| **Density** | Anything cuttable? | >= 7 |
+
+## Data Flow
+
+```
+Phase 1 ──patternReport──→ Phase 2
+Phase 2 ──polishedText──→ Phase 3
+Phase 1 ──originalText──→ Phase 3 (for comparison)
+```
+
+## Error Handling
+
+| Error | Action |
+|-------|--------|
+| File not found | Ask user for correct path |
+| Mixed languages in one file | Process each section in detected language |
+| Score below threshold after rewrite | Flag for manual review, suggest specific areas |
+| LaTeX commands broken during rewrite | Preserve LaTeX structure, only modify prose content |
+| User disagrees with changes | Offer side-by-side diff, allow per-section accept/reject |
+
+## Related Skills
+
+- **scholar-writing**: Phase 5 (Anti-AI Polish) uses this skill's patterns
+- **scholar-review**: Uses scoring to assess writing quality