pi-maestro-flow 0.2.0 → 0.3.1

package/workflows/quick.md

@@ -0,0 +1,350 @@
+# Quick Task Workflow
+
+Execute small, ad-hoc tasks with workflow guarantees (atomic commits, state tracking). Quick mode spawns workflow-planner (quick mode) + workflow-executor(s), tracks tasks in `.workflow/scratch/`, and updates state.json.
+
+With `--discuss`: lightweight decision extraction before planning. Identifies gray areas, conducts interactive discussion, classifies decisions as Locked/Free/Deferred in context.md so the planner treats Locked decisions as constraints and Free decisions as implementer discretion.
+
+With `--full`: enables plan-checking (max 2 iterations) and post-execution verification.
+
+Flags are composable: `--discuss --full` gives discussion + plan-checking + verification.
+
+---
+
+## Prerequisites
+
+- `.workflow/state.json` must exist (project initialized)
+- Quick tasks can run mid-phase -- validation only checks project exists, not phase status
+
+---
+
+### Step 1: Parse Arguments
+
+**Parse $ARGUMENTS for flags and description:**
+
+Extract:
+- `--full` flag -> store as `$FULL_MODE` (true/false)
+- `--discuss` flag -> store as `$DISCUSS_MODE` (true/false)
+- Remaining text -> use as `$DESCRIPTION`
+
+If `$DESCRIPTION` is empty after parsing:
+```
+AskUserQuestion(
+  header: "Quick Task",
+  question: "What do you want to do?",
+  followUp: null
+)
+```
+
+Store response as `$DESCRIPTION`.
+If still empty, re-prompt: "Please provide a task description."
+
+Display banner: `WORKFLOW > QUICK TASK` with active flag suffix:
+
+| Flags | Banner Suffix | Subtitle |
+|-------|--------------|----------|
+| --discuss + --full | `(DISCUSS + FULL)` | Discussion + plan checking + verification enabled |
+| --discuss only | `(DISCUSS)` | Discussion phase enabled -- surfacing gray areas before planning |
+| --full only | `(FULL MODE)` | Plan checking + verification enabled |
+| none | _(no suffix)_ | _(no subtitle)_ |
+
+---
+
+### Step 2: Validate Project
+
+**Validate project state:**
+
+Check .workflow/ exists and has state.json:
+```bash
+test -f .workflow/state.json && echo "exists" || echo "missing"
+```
+
+If missing: Error -- "Quick mode requires an initialized project. Run /workflow:init first."
+
+Quick tasks can run mid-phase -- validation only checks project exists, not phase status.
+
+---
+
+### Step 3: Create Scratch Directory
+
+**Create scratch directory:**
+
+Generate slug from $DESCRIPTION (lowercase, hyphens, max 40 chars).
+Set date to current date (YYYYMMDD).
+
+```bash
+QUICK_DIR=".workflow/scratch/${date}-quick-${slug}"
+mkdir -p "$QUICK_DIR/.task"
+mkdir -p "$QUICK_DIR/.summaries"
+```
+
+Write index.json:
+```json
+{
+  "id": "{YYYYMMDD}-quick-{slug}",
+  "type": "quick",
+  "title": "{$DESCRIPTION}",
+  "status": "active",
+  "created_at": "{ISO timestamp}",
+  "updated_at": "{ISO timestamp}",
+  "flags": {
+    "discuss": {$DISCUSS_MODE},
+    "full": {$FULL_MODE}
+  },
+  "plan": {
+    "task_ids": [],
+    "task_count": 0
+  },
+  "execution": {
+    "method": "agent",
+    "tasks_completed": 0,
+    "tasks_total": 0
+  }
+}
+```
+
+Report: "Creating quick task: {$DESCRIPTION}\nDirectory: {$QUICK_DIR}"
+
+---
+
+### Step 4: Discussion Phase (only when $DISCUSS_MODE)
+
+**Lightweight discussion:**
+
+Skip entirely if NOT $DISCUSS_MODE.
+
+```
+------------------------------------------------------------
+  WORKFLOW > DISCUSSING QUICK TASK
+------------------------------------------------------------
+Surfacing gray areas for: {$DESCRIPTION}
+```
+
+**4a. Identify gray areas:**
+
+Analyze $DESCRIPTION to identify 2-4 gray areas -- implementation decisions that would change the outcome. Use domain-aware heuristic:
+- Something users **SEE** -> layout, density, interactions, states
+- Something users **CALL** -> responses, errors, auth, versioning
+- Something users **RUN** -> output format, flags, modes, error handling
+- Something users **READ** -> structure, tone, depth, flow
+- Something being **ORGANIZED** -> criteria, grouping, naming, exceptions
+
+**4b. Present gray areas:**
+
+```
+AskUserQuestion(
+  header: "Gray Areas",
+  question: "Which areas need clarification before planning?",
+  options: [
+    { label: "{area_1}", description: "{why_it_matters}" },
+    { label: "{area_2}", description: "{why_it_matters}" },
+    { label: "{area_3}", description: "{why_it_matters}" },
+    { label: "All clear", description: "Skip discussion -- I know what I want" }
+  ],
+  multiSelect: true
+)
+```
+
+If user selects "All clear" -> skip to Step 5 (no context.md written).
+
+**4c. Discuss selected areas:**
+
+For each selected area, ask 1-2 focused questions:
+```
+AskUserQuestion(
+  header: "{area_name}",
+  question: "{specific question}",
+  options: [
+    { label: "{choice_1}", description: "{what this means}" },
+    { label: "{choice_2}", description: "{what this means}" },
+    { label: "You decide", description: "Claude's discretion" }
+  ]
+)
+```
+
+Max 2 questions per area. Collect all decisions.
+
+**4d. Classify decisions:**
+
+- **Locked**: firm decisions that cannot be changed during implementation
+- **Free**: open for implementation discretion (implementer can choose)
+- **Deferred**: postponed (captured but not acted on in this quick task)
+
+**4e. Write context.md:**
+
+```markdown
+# Quick Task: {$DESCRIPTION} - Context
+
+**Gathered:** {date}
+**Status:** Ready for planning
+
+## Task Boundary
+
+{$DESCRIPTION}
+
+## Constraints
+
+### Locked
+{decisions that are final and must be followed}
+
+### Free
+{decisions left to implementer discretion, including "You decide" areas}
+
+### Deferred
+{ideas captured but out of scope for this quick task}
+
+## Code Context
+{relevant code references from discussion, if any}
+```
+
+Write to `${QUICK_DIR}/context.md`.
+Report: "Context captured: ${QUICK_DIR}/context.md"
+
+---
+
+### Step 4.5: Load Project Specs
+
+```
+specs_content = maestro spec load --category coding
+```
+
+Passed inline to planner agent in Step 5.
+
+---
+
+### Step 5: Spawn Planner
+
+**Spawn workflow-planner in quick mode:**
+
+MANDATORY, NOT SUBSTITUTABLE by manual Read/Grep: Spawn `workflow-planner` agent with:
+
+- **Context**: mode (`quick` or `quick-full`), directory, description, state.json, CLAUDE.md, specs, context.md (if discuss mode)
+- **Constraints**: single plan with 1-3 atomic tasks, no research phase. Full mode: ~40% context usage + require files/action/convergence.criteria/implementation per task. Default: ~30% context usage.
+- **Output**: `${QUICK_DIR}/plan.json`, `${QUICK_DIR}/.task/TASK-{NNN}.json`. Return `## PLANNING COMPLETE` with plan path.
+
+After planner returns:
+1. Verify plan.json exists at `${QUICK_DIR}/plan.json`
+2. Update index.json plan fields
+3. Report: "Plan created: ${QUICK_DIR}/plan.json"
+
+If plan not found: "Planner failed to create plan.json"
+
+---
+
+### Step 6: Plan Checker (only when $FULL_MODE)
+
+**Plan-checker loop:**
+
+Skip entirely if NOT $FULL_MODE.
+
+```
+------------------------------------------------------------
+  WORKFLOW > CHECKING PLAN
+------------------------------------------------------------
+Spawning plan checker...
+```
+
+MANDATORY, NOT SUBSTITUTABLE by manual Read/Grep: Spawn `workflow-plan-checker` agent to verify plan.json and TASK-*.json:
+
+- **Check dimensions**: requirement coverage, task completeness (files/action/convergence.criteria/implementation), scope sanity (1-3 tasks), context compliance (if discuss mode).
+- **Return**: `## VERIFICATION PASSED` or `## ISSUES FOUND` with structured issue list.
+
+**Handle checker return:**
+
+- **VERIFICATION PASSED:** Continue to Step 7.
+- **ISSUES FOUND:** Enter revision loop.
+
+**Revision loop (max 2 iterations):**
+
+If iteration_count < 2:
+- Display: "Sending back to planner for revision... (iteration {N}/2)"
+- Spawn planner with revision context + checker issues
+- Re-check with checker
+- Increment iteration_count
+
+If iteration_count >= 2:
+- Display: "Max iterations reached. {N} issues remain."
+- Offer: 1) Force proceed, 2) Abort; if Force proceed, flag plan as [LOW CONFIDENCE] (remaining issues)
+
+---
+
+**GATE Step 6→7**: REQUIRED plan.json verified by plan-checker BEFORE execution; BLOCKED if plan.json not verified
+
+### Step 7: Spawn Executor
+
+**Spawn workflow-executor:**
+
+MANDATORY, NOT SUBSTITUTABLE by manual Read/Grep: Spawn `workflow-executor` agent:
+
+- **Read**: plan.json, TASK-*.json, state.json, CLAUDE.md
+- **Constraints**: execute all tasks, atomic commits per task, write summaries to `${QUICK_DIR}/.summaries/TASK-{NNN}-summary.md`
+
+After executor returns:
+1. Verify summaries exist
+2. Update index.json execution fields
+3. Report completion status
+
+---
+
+### Step 8: Verification (only when $FULL_MODE)
+
+**Post-execution verification:**
+
+Skip entirely if NOT $FULL_MODE.
+
+```
+------------------------------------------------------------
+  WORKFLOW > VERIFYING RESULTS
+------------------------------------------------------------
+Spawning verifier...
+```
+
+MANDATORY, NOT SUBSTITUTABLE by manual Read/Grep: Spawn `workflow-verifier` agent: check plan objectives against actual codebase using plan.json and summaries. Write result to `${QUICK_DIR}/verification.json`.
+
+Read verification result:
+| Status | Action |
+|--------|--------|
+| passed | Store "Verified", continue |
+| gaps_found | Display gaps, offer: 1) Re-run executor, 2) Accept as-is; if Accept as-is, flag execution as [LOW CONFIDENCE] (gaps unresolved) |
+
+---
+
+### Step 9: Update State
+
+**Update state.json:**
+
+Read state.json. Add quick task to accumulated_context or quick_tasks array.
+
+Record:
+```json
+{
+  "id": "{YYYYMMDD}-quick-{slug}",
+  "description": "{$DESCRIPTION}",
+  "completed_at": "{ISO timestamp}",
+  "directory": "{$QUICK_DIR}",
+  "verified": {$FULL_MODE ? verification_status : "skipped"}
+}
+```
+
+Update last_updated timestamp.
+
+---
+
+### Step 10: Commit and Complete
+
+**Final commit and completion:**
+
+Update index.json status to "completed".
+
+Commit quick task artifacts:
+```bash
+git add "${QUICK_DIR}/" .workflow/state.json
+git commit -m "quick({slug}): ${DESCRIPTION}"
+```
+
+Display completion:
+
+Display completion banner `WORKFLOW > QUICK TASK COMPLETE` (with `(FULL MODE)` suffix if applicable):
+- Show: Quick Task name, Summary path (`${QUICK_DIR}/.summaries/`), Directory path
+- Full mode also shows: Verification path + status (`${QUICK_DIR}/verification.json`)
+- Footer: `Ready for next task: /workflow:quick`
+

package/workflows/ralph-amend-goal.md

@@ -0,0 +1,177 @@
+# Ralph Goal Amendment Flow
+
+`A_AMEND_GOAL` 详细流程。加载方式：`maestro-ralph.md` S_AMEND_GOAL via `<deferred_reading>`。
+
+触发：`/maestro-ralph --amend [change_request]`
+GUARD: running ralph session 存在
+
+---
+
+## Phase 1 — 快照
+
+1. 定位最新 running ralph session
+2. Read: `task_decomposition` WHERE `status != "superseded"`, `boundary_contract`, completed steps `completion_summary`
+3. Display:
+   ```
+   📍 Session: {session_id}
+   进度: {completed}/{total} steps
+   目标:
+   {for g in active_goals:}
+     [{status_icon}] {g.id}: {g.goal} — done_when: {g.done_when}
+   {end for}
+   边界: in_scope={count}, out_of_scope={count}
+   修改历史: {goal_changelog.length} 次
+   ```
+
+## Phase 2 — 解析
+
+| Condition | 行为 |
+|-----------|------|
+| `change_request` 非空 | 直接使用 |
+| `change_request` 为空 | AskUserQuestion（4 选项 + 自由输入追加） |
+
+AskUserQuestion options:
+
+| label | description |
+|-------|-------------|
+| 修改现有目标 | 调整子目标范围或完成条件 |
+| 新增目标 | 追加新子目标 |
+| 移除目标 | 取消未完成子目标 |
+| 调整边界 | 修改 in_scope / out_of_scope / constraints |
+
+## Phase 3 — Mini Grill
+
+MANDATORY, NOT SUBSTITUTABLE by manual Read/Grep: Delegate (run_in_background, STOP, wait):
+
+```
+maestro delegate "PURPOSE: 评估目标变更影响
+TASK:
+  1. 对比 current_goals 与 change_request，识别冲突/缺口
+  2. 判定已完成 steps 在新目标下是否有效（基于 completion_summary + completion_decisions）
+  3. 判定 pending steps 是否需重建/跳过
+  4. 评估 risk_level
+CONTEXT:
+  intent             = {session.intent}
+  current_goals      = {task_decomposition where status != superseded}
+  completed_steps    = [{index, skill, stage, completion_summary, completion_decisions}]
+  pending_steps      = [{index, skill, stage, goal_ref}]
+  boundary_contract  = {boundary_contract}
+  change_request     = {change_request}
+EXPECTED:
+  ---IMPACT---
+  CHANGE_TYPE=modify|add|remove|boundary
+  AFFECTED_GOALS=[{id, action: modify|supersede|keep, new_goal?, new_done_when?}]
+  INVALIDATED_STEPS=[{index, reason}]
+  NEW_GAPS=[{goal_id, description, suggested_stages: [analyze|plan|execute|...]}]
+  BOUNDARY_CHANGES={in_scope_add:[], out_of_scope_add:[], constraints_add:[]}
+  RISK_LEVEL=low|medium|high
+  RISK_REASON=...
+  ---END---
+CONSTRAINTS:
+  - 只评估不修改
+  - high: 已完成工作与新目标直接冲突
+  - medium: 部分 steps 需跳过/重建，已完成工作可保留
+  - low: 纯增量，已有工作不受影响"
+--role analyze --mode analysis
+```
+
+**GATE Phase 3→4**: REQUIRED impact_assessment complete; BLOCKED if delegate output missing
+
+## Phase 4 — 确认
+
+Display: 影响摘要（risk_level, affected, invalidated, new_gaps）。AskUserQuestion:
+
+| label | description |
+|-------|-------------|
+| 应用并继续 | 归档旧目标 → 写入新目标 → 重建链路 → handoff |
+| 仅改目标 | 更新目标，保留链路不变 |
+| 取消 | 无修改 |
+
+GUARD: `RISK_LEVEL == high` → auto_confirm 无效
+
+## Phase 5 — 应用
+
+### 5.1 Changelog entry
+
+Append to `session.goal_changelog[]`：
+
+```json
+{
+  "id": "CHG-{NNN}",
+  "timestamp": "{ISO}",
+  "change_type": "{CHANGE_TYPE}",
+  "reason": "{change_request}",
+  "impact_assessment": { "risk_level": "...", "invalidated_steps": [...], "new_steps_inserted": 0, "evidence_source": "delegate impact assessment output" },
+  "before": { "goals": [{"id":"...","goal":"...","done_when":"..."}] },
+  "after":  { "goals": [{"id":"...","goal":"...","done_when":"..."}] }
+}
+```
+
+`NNN` = `(goal_changelog.length + 1).toString().padStart(3, '0')`
+
+**GATE 5.1→5.2**: REQUIRED goal_changelog written; BLOCKED if changelog entry missing
+
+### 5.2 归档
+
+对 AFFECTED_GOALS 中 `action ∈ {modify, supersede}` 的条目：
+- Set `status: "superseded"`, `superseded_by: "CHG-{NNN}"`, `superseded_at: now`
+- GUARD: `status == "done"` 的目标不可 supersede（skip + warn）
+
+### 5.3 写入新目标
+
+| action | 处理 |
+|--------|------|
+| `modify` | 新条目 `id: "{original_id}v{version}"`, `origin: "CHG-{NNN}"`, `status: "pending"` |
+| `add` | 新条目 `id: "G{next_num}"`, `origin: "CHG-{NNN}"`, `status: "pending"` |
+| `remove` | 仅 supersede，不新增 |
+| `keep` | 不变 |
+
+### 5.4 重建链路
+
+GUARD: 用户选"应用并继续"
+
+1. INVALIDATED_STEPS 中 pending step → set `status: "skipped"`
+2. NEW_GAPS → 按 `suggested_stages` 插入 steps + decision nodes
+   - 按 A_BUILD_STEPS 规则构建（goal_ref + command_path 解析 + command_scope 校验）
+   - 插入位置：当前 active step 之后、`post-goal-audit` 之前
+3. 原链路有 `post-goal-audit` → 保留
+4. 原链路无 `post-goal-audit` AND `task_decomposition` 存在 → 在 `milestone-complete` 前插入
+5. Reindex all steps
+
+### 5.5 Boundary
+
+`BOUNDARY_CHANGES` 非空时：
+- `in_scope_add` → append to `boundary_contract.in_scope`
+- `out_of_scope_add` → append to `boundary_contract.out_of_scope`
+- `constraints_add` → append to `boundary_contract.constraints`
+
+### 5.6 Persist + Handoff
+
+1. Write status.json
+2. Display:
+   ```
+   ◆ Goal amendment: {CHG-NNN}
+   {change_type} — {reason}
+   Risk: {RISK_LEVEL} | Superseded: {n} | Added: {n} | Skipped steps: {n} | Inserted steps: {n}
+   ```
+3. Handoff → maestro-ralph-execute（平台适配：Claude 用 `Skill()`，Codex 用 `$` 直调）
+
+---
+
+## Anchor 呈现规则
+
+Goals Overview 输出格式（CLI `buildSessionAnchor` 自动生成）：
+
+```
+**Goals Overview**:
+- [✓] G1: 实现搜索 API — done_when: 测试通过
+- [superseded] G2: 前端搜索页 → 被 CHG-001 替换
+- [○] G2v2: 前端搜索页+迁移兼容 — done_when: 新旧数据均可检索 (via CHG-001)
+- [○] G3: 旧数据迁移脚本 — done_when: 全量测试通过 (via CHG-001)
+- Course corrections: 1 applied
+```
+
+规则：
+- `superseded` 目标 → 单行标注，不展开细节
+- 新目标 → 标注 `(via CHG-xxx)`
+- re-grounding / goal-audit → 仅取 `status != "superseded"`

package/workflows/refactor.md

@@ -0,0 +1,87 @@
+# Refactor Workflow
+
+Reduce tech debt through scope analysis, task planning, and reflection-driven execution. Tests MUST pass after every change.
+
+Output: `scratch/{YYYYMMDD}-refactor-{slug}/` with index.json + reflection-log.md + .task/ + .summaries/
+
+---
+
+### Step 1: Parse Scope
+
+| Input | Action |
+|-------|--------|
+| Module path (e.g., "src/auth") | Scan that directory |
+| Feature area (e.g., "authentication") | Search for related files |
+| "all" | Full codebase scan |
+| Empty | Prompt user |
+
+Generate slug (lowercase, hyphens, max 40 chars). Set date = YYYYMMDD.
+
+---
+
+### Step 2: Create Scratch Directory
+
+Create `REFACTOR_DIR=".workflow/scratch/${date}-refactor-${slug}"` with `.task/` and `.summaries/` subdirs.
+
+Write index.json: id, type="refactor", title, status="active", scope, plan (empty task_ids), execution (method=agent, counts=0), reflection (rounds=0).
+
+---
+
+### Step 2.5: Load Project Specs
+
+```
+specs_content = maestro spec load --category coding
+```
+
+---
+
+### Step 3: Scope Analysis
+
+Read all files in scope. Use specs_content to detect convention violations. Categorize:
+
+1. **Duplication** - copy-paste patterns
+2. **Complexity** - long functions, deep nesting, high cyclomatic complexity
+3. **Naming** - inconsistent or unclear names
+4. **Dependencies** - circular deps, tight coupling, god objects
+5. **Dead code** - unused functions, unreachable branches
+6. **Pattern violations** - inconsistent with specs/ conventions
+
+Present summary table. Confirm with user before planning.
+
+---
+
+### Step 4: Plan Refactoring
+
+Write plan.json + `.task/TASK-{NNN}.json` per issue (id, title, status=pending, type=refactor, category, files, convergence criteria, risk level).
+
+Order: quick wins first, high risk last, dependencies respected.
+
+Present plan to user (affected files, risk areas, dependency impacts). Ask: approve / modify / reject.
+
+---
+
+### Step 5: Execute with Reflection
+
+For each task:
+- **5a.** Implement the change
+- **5b.** Run test suite
+- **5c.** Record in reflection-log.md: strategy, result, test status, adjustment, files changed
+- **5d.** On test failure: revert, retry with adjusted strategy (max 2 retries). Still failing → mark "blocked"
+- **5e.** Update task status, write summary, update index.json
+
+---
+
+### Step 6: Final Verification
+
+Run full test suite. Record final state in reflection-log.md.
+
+---
+
+### Step 7: Complete
+
+Glob plan.json AND .summaries/ MUST exist before marking completed; BLOCKED if missing.
+
+Update index.json: `status="completed"`.
+
+Present: tasks completed/blocked, reflection rounds, strategy adjustments, test status, key learnings. If regressions: list affected tests, suggest quality-debug.
+