pi-maestro-flow 0.2.0 → 0.3.0

package/workflows/claude-instructions.md

@@ -0,0 +1,167 @@
+# Maestro
+
+- **Coding Philosophy**: @~/.maestro/workflows/coding-philosophy.md
+
+## Delegate & CLI
+
+- **Delegate Usage**: @~/.maestro/workflows/delegate-usage.md
+- **CLI Endpoints Config**: @~/.maestro/cli-tools.json
+
+**Strictly follow the cli-tools.json configuration**
+
+## Explore
+
+`maestro explore` takes priority over Glob, Grep, and Read. When locating files or searching code patterns, call `maestro explore` first and stop to wait for results.
+
+```bash
+maestro explore "FIND: <target + condition>\nSCOPE: <paths>" [more prompts...] [options]
+```
+
+Lightweight read-only codebase search. 1 prompt = 1 agent. Not for write-mode/long sessions — use `delegate`.
+
+| Option | Description |
+|--------|-------------|
+| `-e, --endpoint <names>` | Endpoint name(s), comma-separated |
+| `--all` | Fan out each prompt to all endpoints |
+| `--max-turns <n>` | Max agent turns per job |
+| `-f, --file <path>` | Load prompts from JSON or text file |
+| `--cd <dir>` | Working directory |
+| `--json` | Output results as JSON |
+
+### Context Injection
+
+Explore agent 无项目认知，调用前注入上下文：
+
+| 注入项 | 写入字段 | 内容 |
+|--------|----------|------|
+| 结构 | SCOPE | 相关目录的具体路径（非通配泛扫） |
+| 领域 | SCOPE | `maestro search` 已返回的关键文件路径 |
+| 约束 | ATTENTION | 框架、语言、命名惯例 |
+
+```
+FIND: authentication middleware that validates JWT tokens
+SCOPE: src/middleware/, src/auth/, src/api/routes/
+ATTENTION: Express.js, middleware files named *.middleware.ts
+```
+
+### Prompt Structure
+
+**FIND + SCOPE 为最低标准。** 每个字段一句陈述句，禁止嵌套条件。
+
+| Field | Required | Rule |
+|-------|----------|------|
+| `FIND` | **Yes** | 可判定的具体目标（什么 + 判定条件） |
+| `SCOPE` | **Yes** | 明确路径或 glob，禁止 `**/*` 泛扫 |
+| `EXCLUDE` | No | 要跳过的文件类型或目录 |
+| `ATTENTION` | No | 框架、命名惯例、已知陷阱 |
+| `EXPECTED` | Recommended | 输出格式：`file:line` 列表 / 摘要 / JSON |
+
+```
+FIND: Functions that call db.query() with string concatenation instead of $1/$2
+SCOPE: src/db/**/*.ts, src/api/**/*.ts
+EXCLUDE: **/*.test.ts
+EXPECTED: file:line list with the SQL string
+```
+
+### Cross-Search
+
+对重要搜索，用 2-3 个不同角度的 prompt 并发，结果由 Claude 交叉验证。
+
+**按角度拆分，不按关键词拆分：**
+
+| 角度 | Prompt A | Prompt B |
+|------|----------|----------|
+| 定义 vs 调用 | 找函数定义 | 找调用点 |
+| 正例 vs 反例 | 找正确用法 | 找遗漏用法 |
+| 入口 vs 实现 | 找 export/路由 | 找内部逻辑 |
+| 按文件类型 | .ts 中的用法 | .vue 中的用法 |
+
+```bash
+maestro explore \
+  "FIND: All functions exported from auth module\nSCOPE: src/auth/\nEXPECTED: function name + file:line" \
+  "FIND: All imports from auth module\nSCOPE: src/**/*.ts\nEXCLUDE: src/auth/\nEXPECTED: import path + file:line" \
+  --json
+```
+
+**结果置信度：**
+- 双命中 → 高置信，直接使用
+- 单命中 → 用 Grep/Read 二次确认
+- 零命中 → 换角度重搜或目标不存在
+
+### Execution
+
+Multi-prompt — background；single lookup — foreground：
+
+```
+Bash({ command: "maestro explore \"p1\" \"p2\" --json", run_in_background: true })
+Bash({ command: "maestro explore \"FIND: ...\nSCOPE: ...\"" })
+```
+
+Session: `maestro explore show` / `maestro explore output <id>`
+
+## Knowledge System
+
+**Gate rule**: run `maestro search` + `maestro load` BEFORE reading code or editing files.
+
+```bash
+maestro search "<query>" [--type <type>] [--category <cat>] [--code] [--kg]
+maestro load --type <type> [--list] [--category <cat>] [--keyword <word>] [--id <id>]
+```
+
+**--type**: `spec`, `knowhow`, `domain`, `issue`, `session`, `scratch`, `note`, `project`, `roadmap`
+**--category** (spec only): `coding`, `arch`, `debug`, `test`, `review`, `learning`, `ui`
+
+### Query Rules
+
+1-3 core keywords per query — multiple short queries beat one long one.
+Separate concepts from symbols. Add `--code` for symbols, `--kg` for full-source.
+
+```bash
+# ❌ keyword dump
+maestro search "topology display frontend DetailedTopologySVG elk"
+
+# ✅ targeted
+maestro search "topology layout"
+maestro search "DetailedTopologySVG" --code
+maestro load --type spec --category coding
+```
+
+### Record
+
+| What | Command |
+|------|---------|
+| Spec | `/spec-add <category> "title" "content" --keywords kw1,kw2 --description "summary"` |
+| Knowhow | `/manage-knowhow-capture` (`--spec-category <cat>` for agent injection) |
+
+Category routing: decisions→`arch`, patterns→`coding`, pitfalls→`debug`/`learning`, rules→`review`, tests→`test`.
+
+### Supersession & Conflict (dual-track)
+
+新知识与旧条目的关系分两种,语义不同、操作不同:
+
+| 关系 | 场景 | 命令 | 效果 |
+|------|------|------|------|
+| **supersede** | 新规则替代旧规则（演化） | `maestro spec supersede <old-sid> --by <new-sid>` | 旧条目 `deprecated`（search/load 排除），演化链保留 |
+| **conflict** | 两条规则均有道理（争议） | `maestro spec conflict mark <file> <line> --note "<reason>"` | 旧条目 `contested`（search ×0.5，`[CONTESTED]` 标注，仍注入），人裁决 |
+
+```bash
+# supersede 流程: add → capture sid → supersede
+maestro spec add coding "新规则" "内容" --keywords kw1,kw2 --json   # → 获取 new-sid
+maestro spec supersede <old-sid> --by <new-sid>                     # → 旧条目 deprecated
+maestro spec history <sid>                                          # → 查看演化链
+
+# conflict 流程: 不确定谁对 → 标记争议 → 审计解决
+maestro spec conflict mark <file> <line> --note "<reason>"
+# Resolution: /manage-knowledge-audit
+```
+
+**三正交轴**: `confidence`（人/审计裁定）⊥ `status`（active/deprecated 生命周期）⊥ time-decay（自动新鲜度）。不要混用。
+
+### Health & Maintenance
+
+```bash
+maestro spec health                  # 生命周期统计 + 悬空/循环 supersedes 校验 + 新鲜度
+maestro spec backfill-sid            # 存量无 sid 条目回填（幂等），启用演化链
+maestro spec history <sid>           # 某条目的演化链（oldest → newest）
+maestro search "<q>" --include-deprecated   # 搜索含 deprecated 条目
+```

package/workflows/codebase-rebuild.md

@@ -0,0 +1,267 @@
+# Workflow: codebase-rebuild
+
+Full rebuild of the `.workflow/codebase/` documentation system.
+
+## Trigger
+
+- Manual via `/workflow:codebase-rebuild [--force] [--skip-commit]`
+- Auto-triggered by `/workflow:init` when existing code is detected
+- Auto-triggered by `/workflow:map`
+
+## Arguments
+
+| Arg | Description | Default |
+|-----|-------------|---------|
+| `--force` | Clear existing codebase/ and rebuild from scratch | `false` |
+| `--skip-commit` | Skip the final git commit of generated docs | `false` |
+
+## Prerequisites
+
+- Project source code exists (src/ or equivalent)
+- `.workflow/` directory exists
+
+---
+
+## Workflow Steps
+
+### Step 1: Prepare Directory Structure
+
+```
+Create (or clear if --force) .workflow/codebase/:
+  doc-index.json, tech-registry/_index.md, feature-maps/_index.md, action-logs/
+
+If exists and not --force: confirm overwrite or exit.
+```
+
+### Step 2: Scan Project Structure — Components
+
+```
+Scan source directories (src/, lib/, app/, packages/) for components.
+Use project.md Tech Stack for context if available.
+
+Classify files by naming pattern:
+  Models (*model*, *entity*, *schema*), Services (*service*, *provider*),
+  Controllers (*controller*, *handler*, *route*), Utils (*util*, *helper*),
+  Types (*type*, *interface*, *.d.ts), Config (*config*, *constant*),
+  Middleware (*middleware*, *guard*, *interceptor*), Core (*core*, *registry*, *loader*)
+
+For each component: read files, extract exported symbols, determine type.
+Build component entry:
+  {
+    "id": "TC-{NNN}",              // Sequential TC-001, TC-002, ...
+    "name": "{PascalCase name}",
+    "type": "{type}",
+    "code_locations": ["{relative paths}"],
+    "feature_ids": [],              // Populated in Step 3
+    "symbols": ["{exported symbol names}"],
+    "last_updated": "{ISO timestamp}"
+  }
+```
+
+### Step 2.5: Load Project Specs
+
+```
+# MANDATORY, NOT SUBSTITUTABLE by manual Read/Grep
+specs_content = maestro spec load --category arch
+```
+
+Used in Step 2-4 to produce architecture-aware documentation.
+
+---
+
+### Step 3: Scan Project Structure — Features
+
+```
+Group components into features by:
+  directory proximity, naming patterns, import relationships, blueprint/ mapping.
+
+For each feature group: derive name, collect component IDs, map requirements and phase.
+Build feature entry:
+  {
+    "id": "FT-{NNN}",
+    "name": "{Feature Name}",
+    "status": "active",
+    "requirement_ids": [],        // From .spec mapping
+    "component_ids": ["TC-001", "TC-002"],
+    "phase": null                 // From roadmap mapping
+  }
+
+Back-fill component.feature_ids with assigned feature IDs.
+```
+
+### Step 4: Map Requirements (if .spec exist)
+
+```
+If .workflow/blueprint/ exist: parse each SPEC-*/requirements/REQ-*.md,
+match to features by keyword analysis. Build requirement entry:
+  {
+    "id": "REQ-{NNN}",
+    "title": "{requirement title}",
+    "priority": "must|should|could|wont",
+    "feature_id": "FT-{NNN}",
+    "status": "pending|in_progress|completed",
+    "acceptance_criteria": ["{criteria}"]
+  }
+
+If no blueprint: requirements = [] (populated later by maestro-blueprint).
+```
+
+### Step 5: Record Architecture Decisions (if ADRs exist)
+
+```
+If .workflow/blueprint/*/architecture/ADR-*.md exist: parse each ADR,
+map to components by keyword analysis. Build ADR entry:
+  {
+    "id": "ADR-{NNN}",
+    "title": "{ADR title}",
+    "component_ids": ["TC-{NNN}"],
+    "decision": "{decision summary}",
+    "rationale": "{rationale summary}",
+    "evidence_source": "{evidence source — ADR file ref or code anchor}"
+  }
+
+If no ADRs: architecture_decisions = [].
+```
+
+### Step 6: Write doc-index.json
+
+```
+Assemble the complete doc-index.json:
+
+{
+  "version": "1.0",
+  "schema_version": "1.0",
+  "project": "{project name from state.json or package.json}",
+  "last_updated": "{ISO timestamp}",
+  "features": [{feature entries}],
+  "components": [{component entries}],
+  "requirements": [{requirement entries}],
+  "architecture_decisions": [{ADR entries}],
+  "actions": []
+}
+
+Write to: .workflow/codebase/doc-index.json
+```
+
+**GATE Step 6→7**: REQUIRED `doc-index.json` written and valid JSON before tech-registry generation; BLOCKED if `doc-index.json` missing or invalid.
+
+### Step 7: Generate Tech Registry Docs
+
+```
+For each component (slug = lowercase-hyphenated name):
+
+Write .workflow/codebase/tech-registry/{slug}.md:
+  Header table (ID, Type, Features) + sections: Code Locations, Exported Symbols, Dependencies.
+  Footer: *Auto-generated by codebase-rebuild at {timestamp}*
+
+Write .workflow/codebase/tech-registry/_index.md:
+  Summary table (ID, Name, Type, Locations) + component count footer.
+```
+
+### Step 8: Generate Feature Map Docs
+
+```
+For each feature (slug = lowercase-hyphenated name):
+
+Write .workflow/codebase/feature-maps/{slug}.md:
+  Header table (ID, Status, Phase) + sections: Requirements, Components table.
+  Footer: *Auto-generated by codebase-rebuild at {timestamp}*
+
+Write .workflow/codebase/feature-maps/_index.md:
+  Summary table (ID, Name, Status, Components, Requirements) + feature count footer.
+```
+
+### Step 8.5: Update State and Project Artifacts
+
+```
+a. Update state.json: set last_codebase_rebuild and last_updated timestamps.
+
+b. Update project.md Tech Stack (if exists):
+   Compare "## Tech Stack" against detected stack from Step 2.
+   If changes detected: update section + footer timestamp.
+```
+
+**GATE Step 8.5→9**: Glob `.workflow/codebase/doc-index.json` AND `.workflow/codebase/knowledge-graph.json` MUST exist before Step 9 report; BLOCKED if missing.
+
+### Step 9: Report and Commit
+
+```
+Display summary: component/feature/requirement/ADR/file counts.
+If KG pipeline ran: include KG node/edge/layer/tour counts.
+If mapper agents failed: log W001.
+If not --skip-commit: suggest committing generated docs.
+Suggest next:
+  - manage-status (review)
+  - manage-codebase-refresh (incremental updates)
+  - maestro kg stats (verify KG)
+  - maestro wiki list --keyword kg (verify wiki integration)
+  - maestro kg diff-wiki (future change impact analysis)
+```
+
+---
+
+## Knowledge Graph Pipeline (Step 10)
+
+Uses the native `maestro kg index` command (`src/graph/analyzers/fs-analyzer.ts`) to scan the codebase and generate the knowledge graph. No external dependencies required.
+
+### Step 10: Generate Knowledge Graph
+
+```
+# MANDATORY, NOT SUBSTITUTABLE by manual Read/Grep
+maestro kg index --src "$PROJECT_ROOT/src"
+```
+
+  - File system scan and code entity extraction (nodes, edges)
+  - Import/call graph analysis and test pairing (tested_by edges)
+  - Layer classification and topological tour generation
+  - Validation (referential integrity, layer coverage, tour structure)
+  - Write to `.workflow/codebase/knowledge-graph.json`
+
+If validation fails: the graph is still written with `"valid": false` flag.
+
+### Step 11: KG → Wiki Index Integration
+
+```
+When knowledge-graph.json is successfully written:
+  The WikiIndexer automatically indexes KG nodes as virtual wiki entries
+  on next wiki access (via adaptKnowledgeGraph virtual adapter).
+
+  Generated virtual entries:
+    - kg-{node-id} for each GraphNode (type: knowhow, virtualKind: kg-node)
+    - kg-layer-{id} for each Layer (virtualKind: kg-layer)
+    - kg-tour-{order} for each TourStep (virtualKind: kg-tour-step)
+
+  Cross-referencing:
+    - KG nodes are linked to existing codebase-comp-* entries via filePath matching
+    - Edge semantics preserved in ext.kgEdges for downstream semantic traversal
+
+  No manual action required — indexing is lazy and triggered on first wiki access.
+  To verify: run `maestro wiki list --keyword kg` after rebuild.
+```
+
+---
+
+## Error Handling
+
+| Error | Action |
+|-------|--------|
+| No source directories found | Warn and create empty doc-index.json |
+| .workflow/ missing | Fail: "Run /workflow:init first" |
+| File read errors | Log warning, skip file, continue scan |
+| Existing codebase/ without --force | Prompt user for confirmation |
+| KG validation failed | Write knowledge-graph.json with `"valid": false`, log errors |
+| Wiki index rebuild failed | Non-fatal — KG data still written, wiki indexing retries on next access |
+
+## Output Files
+
+| File | Description |
+|------|-------------|
+| `.workflow/codebase/doc-index.json` | Single source of truth for all components/features/requirements |
+| `.workflow/codebase/tech-registry/_index.md` | Component index |
+| `.workflow/codebase/tech-registry/{slug}.md` | Per-component documentation |
+| `.workflow/codebase/feature-maps/_index.md` | Feature index |
+| `.workflow/codebase/feature-maps/{slug}.md` | Per-feature documentation |
+| `.workflow/codebase/knowledge-graph.json` | Knowledge Graph with nodes, edges, layers, and tour |
+| `.workflow/wiki-index.json` | Updated on next wiki access: KG nodes indexed as virtual entries (automatic) |
+| `.workflow/state.json` | Updated: last_codebase_rebuild timestamp |
+| `.workflow/project.md` | Updated: Tech Stack section refreshed |

package/workflows/codebase-refresh.md

@@ -0,0 +1,168 @@
+# Workflow: codebase-refresh
+
+Incremental refresh of `.workflow/codebase/` documentation based on changes since the last rebuild or refresh.
+
+Detects which files have changed (via git diff), identifies which codebase docs are affected, selectively re-scans only those areas, and updates timestamps. Much faster than a full rebuild for ongoing maintenance.
+
+## Trigger
+
+- Manual via `/workflow:codebase-refresh [--since <date>] [--deep]`
+
+## Arguments
+
+| Arg | Description | Required |
+|-----|-------------|----------|
+| `--since <date>` | Override change detection window (ISO date or relative like "3d") | No |
+| `--deep` | Force deeper re-scan even for files with minor changes | No |
+
+## Prerequisites
+
+- `.workflow/` directory exists and is initialized
+- `.workflow/codebase/` must contain existing docs (from prior rebuild)
+- `.workflow/codebase/doc-index.json` must exist (run `/workflow:codebase rebuild` first)
+
+---
+
+## Workflow Steps
+
+### Step 1: Parse Input and Validate
+
+```
+Parse --since and --deep flags from $ARGUMENTS.
+Verify .workflow/ initialized (E001 if not) and doc-index.json exists (E002 if not).
+```
+
+### Step 2: Detect Changes
+
+```
+Change window: --since value, else codebase_last_rebuilt/codebase_last_refreshed from state.json.
+Run git diff --name-only to get changed files.
+If no changes: emit W001 and exit.
+```
+
+### Step 3: Identify Affected Documentation
+
+```
+Map changed files to doc-index.json entries via code_locations matching.
+Build affected sets:
+  affected_components = components whose code_locations include changed files
+  affected_features = features whose component_ids include affected components
+```
+
+### Step 3.5: Load Project Specs
+
+```
+# MANDATORY, NOT SUBSTITUTABLE by manual Read/Grep
+specs_content = maestro spec load --category arch
+```
+
+Used in Step 4-5 to validate refreshed docs against architectural expectations.
+
+### Step 3.6: KG Impact Analysis (if KG exists)
+
+```
+If .workflow/codebase/knowledge-graph.json exists:
+  # MANDATORY, NOT SUBSTITUTABLE by manual Read/Grep (when KG exists)
+  Run: maestro kg diff-wiki --json
+  Parse output for affectedWiki entries.
+
+  If affectedWiki is non-empty:
+    Log WARNING for each affected wiki entry:
+      "KG impact: code changes affect [entry.id] — [entry.title] (via [reason])"
+
+    Add affected entry IDs to the refresh queue for human review.
+
+  Log summary: "KG analysis: {directNodes} direct, {impactedNodes} impacted KG nodes,
+    {affectedWiki.length} wiki entries flagged"
+
+If .workflow/codebase/knowledge-graph.json does not exist:
+  Log W0xx "KG not generated — KG impact analysis skipped" and continue; flag KG analysis as [LOW CONFIDENCE] (KG unavailable).
+```
+
+---
+
+### Step 4: Re-scan Affected Components
+
+```
+For each affected component:
+  - Verify code_locations still exist (remove missing, log warning)
+  - Re-extract exported symbols (ESM export + CJS module.exports patterns)
+  - Update symbols[] and last_updated timestamp
+
+If --deep: follow reverse dependency chain to find additional affected components.
+
+Report new files matching component naming patterns (do not auto-add).
+```
+
+**GATE Step 4→5**: REQUIRED affected components re-scanned (symbols[] and last_updated refreshed) before relationship check; BLOCKED if affected components not re-scanned.
+
+### Step 5: Check Relationship Changes
+
+```
+For each refreshed component:
+  Analyze imports to detect cross-feature dependencies (log if found).
+
+For each refreshed feature:
+  Remove stale component_ids, check for new components by directory proximity.
+```
+
+### Step 6: Update Doc Index
+
+```
+Write updated component/feature entries + timestamps to .workflow/codebase/doc-index.json.
+```
+
+### Step 7: Regenerate Affected Docs
+
+```
+For each refreshed component: regenerate tech-registry/{slug}.md
+  (header table + Code Locations + Exported Symbols + refresh timestamp).
+
+For each refreshed feature: regenerate feature-maps/{slug}.md
+  (header table + Components table + Requirements + refresh timestamp).
+
+If entries changed: regenerate tech-registry/_index.md and feature-maps/_index.md.
+```
+
+### Step 8: Update Timestamps
+
+```
+Update .workflow/state.json: set codebase_last_refreshed and last_updated timestamps.
+```
+
+**GATE Step 8→9**: Glob refreshed `tech-registry/{slug}.md` MUST exist before Step 9 report; BLOCKED if missing.
+
+### Step 9: Report
+
+```
+Display summary: changed files, components/features refreshed, symbols added/removed, warnings.
+Suggest next: manage-status to review.
+```
+
+---
+
+## Error Handling
+
+| Code | Meaning |
+|------|---------|
+| E001 | .workflow/ not initialized |
+| E002 | No codebase/ docs exist, use codebase-rebuild instead |
+| W001 | No changes detected since last refresh |
+
+| Error | Action |
+|-------|--------|
+| doc-index.json missing | Fail with E002: "Run /workflow:codebase rebuild first" |
+| .workflow/ missing | Fail with E001 |
+| Code location file missing | Remove from code_locations, log warning |
+| No changes detected | Emit W001, exit gracefully |
+
+## Output Files
+
+| File | Action |
+|------|--------|
+| `.workflow/codebase/doc-index.json` | Updated (affected entries + timestamps) |
+| `.workflow/codebase/tech-registry/{slug}.md` | Regenerated for refreshed components |
+| `.workflow/codebase/feature-maps/{slug}.md` | Regenerated for refreshed features |
+| `.workflow/codebase/tech-registry/_index.md` | Updated if entries changed |
+| `.workflow/codebase/feature-maps/_index.md` | Updated if entries changed |
+| `.workflow/state.json` | Updated with codebase_last_refreshed timestamp |