maestro-flow 0.5.31 → 0.5.33

package/.agents/skills/skill-tuning/specs/skill-authoring-principles.md

@@ -0,0 +1,192 @@
+# Skill Authoring Principles
+
+Skill 撰写首要准则。所有诊断和优化以此为纲。
+
+---
+
+## 核心原则
+
+```
+简洁高效 → 去除无关存储 → 去除中间存储 → 上下文流转
+```
+
+---
+
+## 1. 简洁高效
+
+**原则**：最小化实现，只做必要的事
+
+| DO | DON'T |
+|----|-------|
+| 单一职责阶段 | 臃肿的多功能阶段 |
+| 直接的数据路径 | 迂回的处理流程 |
+| 必要的字段 | 冗余的 schema 定义 |
+| 精准的 prompt | 过度详细的指令 |
+
+**检测模式**：
+- Phase 文件 > 200 行 → 需拆分
+- State schema 字段 > 20 个 → 需精简
+- 同一数据多处定义 → 需去重
+
+---
+
+## 2. 去除无关存储
+
+**原则**：不存储不需要的数据
+
+| DO | DON'T |
+|----|-------|
+| 只存最终结果 | 存储调试信息 |
+| 存路径引用 | 存完整内容副本 |
+| 存必要索引 | 存全量历史 |
+
+**检测模式**：
+```javascript
+// BAD: 存储完整内容
+state.full_analysis_result = longAnalysisOutput;
+
+// GOOD: 存路径 + 摘要
+state.analysis = {
+  path: `${workDir}/analysis.json`,
+  summary: extractSummary(output),
+  key_findings: extractFindings(output)
+};
+```
+
+**反模式清单**：
+- `state.debug_*` → 删除
+- `state.*_history` (无限增长) → 限制或删除
+- `state.*_cache` (会话内) → 改用内存变量
+- 重复字段 → 合并
+
+---
+
+## 3. 去除中间存储
+
+**原则**：避免临时文件和中间状态文件
+
+| DO | DON'T |
+|----|-------|
+| 直接传递结果 | 写文件再读文件 |
+| 函数返回值 | 中间 JSON 文件 |
+| 管道处理 | 阶段性存储 |
+
+**检测模式**：
+```javascript
+// BAD: 中间文件
+write_file(`${workDir}/temp-step1.json`, step1Result);
+const step1 = read_file(`${workDir}/temp-step1.json`);
+const step2Result = process(step1);
+write_file(`${workDir}/temp-step2.json`, step2Result);
+
+// GOOD: 直接流转
+const step1Result = await executeStep1();
+const step2Result = process(step1Result);
+const finalResult = finalize(step2Result);
+write_file(`${workDir}/final-output.json`, finalResult);  // 只存最终结果
+```
+
+**允许的存储**：
+- 最终输出（用户需要的结果）
+- 检查点（长流程恢复用，可选）
+- 备份（修改前的原始文件）
+
+**禁止的存储**：
+- `temp-*.json`
+- `intermediate-*.json`
+- `step[N]-output.json`
+- `*-draft.md`
+
+---
+
+## 4. 上下文流转
+
+**原则**：通过上下文传递而非文件
+
+| DO | DON'T |
+|----|-------|
+| 函数参数传递 | 全局状态读写 |
+| 返回值链式处理 | 文件中转 |
+| prompt 内嵌数据 | 指向外部文件 |
+
+**模式**：
+```javascript
+// 上下文流转模式
+async function executePhase(context) {
+  const { previousResult, constraints, config } = context;
+
+  const result = await delegate_subagent({
+    subagent_type: 'universal-executor',
+    description: 'Execute phase with context passing',
+    run_in_background: false,
+    prompt: `
+      [CONTEXT]
+      Previous: ${JSON.stringify(previousResult)}
+      Constraints: ${constraints.join(', ')}
+
+      [TASK]
+      Process and return result directly.
+    `
+  });
+
+  return {
+    ...context,
+    currentResult: result,
+    completed: ['phase-name']
+  };
+}
+
+// 链式执行
+let ctx = initialContext;
+ctx = await executePhase1(ctx);
+ctx = await executePhase2(ctx);
+ctx = await executePhase3(ctx);
+// ctx 包含完整上下文，无中间文件
+```
+
+**State 最小化**：
+```typescript
+// 只存必要状态
+interface MinimalState {
+  status: 'pending' | 'running' | 'completed';
+  target: { name: string; path: string };
+  result_path: string;  // 最终结果路径
+  error?: string;
+}
+```
+
+---
+
+## 应用场景
+
+### 诊断时检查
+
+| 检查项 | 违反时标记 |
+|--------|-----------|
+| Phase 内写入 temp 文件 | `unnecessary_storage` |
+| State 包含 *_history 无限数组 | `unbounded_state` |
+| 文件写入后立即读取 | `redundant_io` |
+| 多阶段传递完整内容 | `context_bloat` |
+
+### 优化策略
+
+| 问题 | 策略 |
+|------|------|
+| 中间文件过多 | `eliminate_intermediate_files` |
+| State 膨胀 | `minimize_state_schema` |
+| 重复存储 | `deduplicate_storage` |
+| 文件中转 | `context_passing` |
+
+---
+
+## 合规检查清单
+
+```
+□ 无 temp/intermediate 文件写入
+□ State schema < 15 个字段
+□ 无重复数据存储
+□ Phase 间通过上下文/返回值传递
+□ 只存最终结果文件
+□ 无无限增长的数组
+□ 无调试字段残留
+```

package/.agents/skills/skill-tuning/specs/tuning-strategies.md

@@ -0,0 +1,392 @@
+# Tuning Strategies
+
+Fix strategies for each problem category. Implementation patterns + verification methods.
+
+## Usage Context
+
+| Phase | Usage |
+|-------|-------|
+| action-propose-fixes | Strategy selection + implementation guidance |
+| action-apply-fix | Apply implementation pattern |
+| action-verify | Run verification method |
+
+---
+
+## Selection Decision Tree
+
+```
+Context Explosion?
+├── history grows unbounded? → sliding_window
+├── full content in prompts? → path_reference
+├── no summarization? → context_summarization
+└── text-based context? → structured_state
+
+Long-tail Forgetting?
+├── constraints not in phases? → constraint_injection
+├── no requirements in state? → state_constraints_field
+├── no recovery points? → checkpoint_restore
+└── goal drift risk? → goal_embedding
+
+Data Flow?
+├── multiple state files? → state_centralization
+├── no validation? → schema_enforcement
+└── inconsistent names? → field_normalization
+
+Agent Coordination?
+├── no error handling? → error_wrapping
+├── no result validation? → result_validation
+└── nested agent calls? → flatten_nesting
+
+Authoring Violation?
+├── intermediate files? → eliminate_intermediate_files
+├── state bloat (>15 fields)? → minimize_state
+├── write→read relay? → context_passing
+└── duplicate storage? → deduplicate_storage
+
+Token Consumption?
+├── verbose prompts? → prompt_compression
+├── full content passing? → lazy_loading
+├── verbose output? → output_minimization
+├── bloated state? → state_field_reduction
+└── multiple output files? → in_memory_consolidation
+
+Documentation?
+├── repeated definitions? → consolidate_to_ssot
+├── hardcoded configs? → centralize_mapping_config
+└── conflicting values? → reconcile_conflicting_definitions
+```
+
+---
+
+## Authoring Principles Strategies (P0)
+
+> **Core Principle**: Simplicity → Remove intermediate files → Context passing
+
+### eliminate_intermediate_files
+
+```javascript
+// Before: File relay between steps
+const step1 = await analyze();
+write_file(`${workDir}/step1.json`, JSON.stringify(step1));
+const step1Data = JSON.parse(read_file(`${workDir}/step1.json`));
+const step2 = await transform(step1Data);
+
+// After: Direct context passing
+const step1 = await analyze();
+const step2 = await transform(step1);  // No file
+return finalize(step2);                // Only final result persisted
+```
+
+**Verification**: `ls ${workDir}` — no temp/intermediate files
+
+### minimize_state
+
+**Rules**: ≤15 fields, delete `debug_*`, `*_cache`, `*_temp`, apply sliding window to `*_history`.
+
+```typescript
+// Before: Bloated
+interface State { status; target; user_input; parsed_input; intermediate_result; debug_info; analysis_cache; full_history; step1_output; step2_output; final_result; ... }
+
+// After: Minimal
+interface State {
+  status: 'pending'|'running'|'completed'|'failed';
+  target: { name: string; path: string };
+  result_path: string;
+  error?: string;
+}
+```
+
+### context_passing
+
+```javascript
+async function executeWorkflow(initialContext) {
+  let ctx = initialContext;
+  ctx = await executePhase1(ctx);   // Pass context directly
+  ctx = await executePhase2(ctx);   // Continue passing
+  const result = await executePhase3(ctx);
+  write_file(`${ctx.workDir}/result.json`, JSON.stringify(result));  // Only final
+  return result;
+}
+```
+
+### deduplicate_storage
+
+```javascript
+// Before: state.user_request = state.original_request = state.input_text = input
+// After:  state.input = input;  // Single source
+```
+
+---
+
+## Context Explosion Strategies
+
+### sliding_window
+
+```javascript
+const MAX_HISTORY = 5;
+function updateHistory(state, newItem) {
+  return { ...state, history: [...(state.history || []), newItem].slice(-MAX_HISTORY) };
+}
+```
+
+### path_reference
+
+```javascript
+// Before: const prompt = `Analyze: ${read_file('data.json')}`;
+// After:  const prompt = `Analyze file at: ${dataPath}. Read it first.`;
+```
+
+### context_summarization
+
+```javascript
+// Add summarization before passing to next phase
+const summary = await delegate_subagent({
+  subagent_type: 'universal-executor',
+  description: 'Summarize content for context compression',
+  run_in_background: false,
+  prompt: `Summarize in <100 words: ${fullContent}\nReturn JSON: { summary, key_points[] }`
+});
+nextPhasePrompt = `Previous summary: ${summary.summary}`;
+```
+
+---
+
+## Long-tail Forgetting Strategies
+
+### constraint_injection
+
+```javascript
+// Add to EVERY phase prompt
+const phasePrompt = `
+[CONSTRAINTS - FROM ORIGINAL REQUEST]
+${state.original_requirements.map(r => `- ${r}`).join('\n')}
+
+[CURRENT TASK]
+${taskDescription}
+
+[REMINDER] Output MUST satisfy all constraints above.
+`;
+```
+
+### state_constraints_field
+
+Add to state-schema + action-init:
+```javascript
+state.original_requirements = extractRequirements(userInput);
+state.goal_summary = summarizeGoal(userInput);
+```
+
+### checkpoint_restore
+
+```javascript
+function createCheckpoint(state, workDir, name) {
+  write_file(`${workDir}/checkpoints/${name}.json`, JSON.stringify({
+    state, timestamp: new Date().toISOString(), name
+  }));
+}
+// Use at key phase boundaries
+```
+
+---
+
+## Data Flow Strategies
+
+### state_centralization
+
+```javascript
+// Single state manager — replace all direct writes
+const StateManager = {
+  read: (dir) => JSON.parse(read_file(`${dir}/state.json`)),
+  update: (dir, updates) => {
+    const next = { ...StateManager.read(dir), ...updates, updated_at: Date.now() };
+    write_file(`${dir}/state.json`, JSON.stringify(next, null, 2));
+    return next;
+  }
+};
+```
+
+### schema_enforcement
+
+```javascript
+function validateState(state) {
+  const errors = [];
+  if (!['pending','running','completed','failed'].includes(state.status))
+    errors.push(`Invalid status: ${state.status}`);
+  if (typeof state.target_skill?.name !== 'string')
+    errors.push('target_skill.name must be string');
+  if (errors.length) throw new Error(`Validation failed:\n${errors.join('\n')}`);
+}
+// Call before every state write
+```
+
+### field_normalization
+
+```javascript
+const NORMALIZATIONS = { 'title': 'name', 'identifier': 'id', 'state': 'status' };
+function normalizeData(data) {
+  if (typeof data !== 'object' || !data) return data;
+  return Object.fromEntries(
+    Object.entries(data).map(([k, v]) => [NORMALIZATIONS[k] || k, normalizeData(v)])
+  );
+}
+```
+
+---
+
+## Agent Coordination Strategies
+
+### error_wrapping
+
+```javascript
+async function safeTask(config, state, updateState) {
+  for (let attempt = 1; attempt <= 3; attempt++) {
+    try {
+      const result = await Task(config);
+      if (!result) throw new Error('Empty result');
+      return result;
+    } catch (error) {
+      if (attempt === 3) {
+        updateState({ error_count: state.error_count + 1 });
+        throw error;
+      }
+      await new Promise(r => setTimeout(r, 1000 * attempt));
+    }
+  }
+}
+```
+
+### result_validation
+
+```javascript
+function validateAgentResult(result, requiredFields) {
+  const parsed = typeof result === 'string' ? JSON.parse(result) : result;
+  for (const field of requiredFields) {
+    if (!(field in parsed)) throw new Error(`Missing: ${field}`);
+  }
+  return parsed;
+}
+```
+
+### flatten_nesting
+
+```javascript
+// Before: Agent A's prompt tells it to call delegate_subagent({subagent_type: 'B'})
+// After: Agent A returns signal, orchestrator handles
+// Agent A: return { needs_agent_b: true, context: {...} }
+// Orchestrator:
+if (parsedA.needs_agent_b) {
+  resultB = await delegate_subagent({
+    subagent_type: 'B',
+    description: 'Handle delegated task from Agent A',
+    run_in_background: false,
+    prompt: `Context: ${parsedA.context}`
+  });
+}
+```
+
+---
+
+## Token Consumption Strategies
+
+### prompt_compression
+
+```javascript
+// Before: Long inline prompt with role, detailed instructions, full code
+// After: Key instructions only
+const prompt = `Analyze ${codePath} for: patterns, security, performance.
+Return JSON: { issues: [], severity: string }`;
+```
+
+### lazy_loading
+
+```javascript
+// Before: const prompt = `Analyze:\n${read_file(filePath)}`;
+// After:  const prompt = `Analyze file at: ${filePath}\n(Read if needed)\nReturn: { summary, issues[] }`;
+```
+
+### output_minimization
+
+```javascript
+const prompt = `
+Analyze the code. Return ONLY this JSON:
+{ "status": "pass|review|fail", "issues": [{"id","severity","file","line"}], "summary": "one sentence" }
+Do not include explanations.
+`;
+```
+
+### state_field_reduction
+
+Audit checklist:
+```javascript
+function auditStateFields(schema) {
+  const candidates = Object.keys(schema).filter(k =>
+    k.startsWith('debug_') || k.endsWith('_cache') ||
+    k.endsWith('_temp') || k.includes('intermediate')
+  );
+  return { total: Object.keys(schema).length, removable: candidates };
+}
+```
+
+### in_memory_consolidation
+
+```javascript
+// Before: Multiple files — diagnosis-report.md, summary.json, tuning-report.md
+// After: Single state.json with final_report rendered on demand
+const consolidated = { ...state, final_report: { summary, generated_at: Date.now() } };
+write_file(`${workDir}/state.json`, JSON.stringify(consolidated, null, 2));
+```
+
+---
+
+## Documentation Strategies
+
+### consolidate_to_ssot
+
+```javascript
+// 1. Identify canonical source (priority: specs/ > phases/ > SKILL.md)
+// 2. Ensure canonical has full definition
+// 3. Replace other locations with reference links
+//    e.g., "See [state-schema.md](phases/state-schema.md)"
+```
+
+### centralize_mapping_config
+
+```javascript
+// 1. Extract hardcoded mappings → specs/category-mappings.json
+// 2. Runtime loads config: const map = JSON.parse(read_file('specs/category-mappings.json'));
+// 3. Replace all inline definitions with config lookup
+```
+
+### reconcile_conflicting_definitions
+
+```javascript
+// 1. Present conflict to user via ask_user
+// 2. Apply chosen version across all files
+// 3. Verify no remaining conflicts
+```
+
+---
+
+## General Optimization Areas (via Gemini CLI)
+
+For issues in these categories, use Gemini CLI for custom analysis:
+
+| Category | Issues | Gemini Analysis |
+|----------|--------|-----------------|
+| Prompt Engineering | Vague instructions, format drift | prompt optimization, structured output |
+| Architecture | Phase overlap, tight coupling | phase_decomposition, interface_contracts |
+| Performance | Slow execution, high tokens | token_budgeting, parallel_execution |
+| Error Handling | Silent failures, no degradation | graceful_degradation, error_propagation |
+| Output Quality | Inconsistent results | quality_gates, output_validation |
+| User Experience | No progress visibility | progress_tracking, interactive_checkpoints |
+
+**Gemini CLI Template**:
+```bash
+maestro delegate "
+PURPOSE: [optimization goal for skill at ${skillPath}]
+TASK: • [specific analysis steps]
+MODE: analysis
+CONTEXT: @${skillPath}/**/*
+EXPECTED: [specific deliverable]
+" --tool gemini --mode analysis
+```