@guanlin4924/devflow-pi 0.1.0

package/plugins/devflow-implementation/skills/workflow-execute-phase/references/ui-brand.md

@@ -0,0 +1,160 @@
+<ui_patterns>
+
+Visual patterns for user-facing workflow output. Orchestrators @-reference this file.
+
+## Stage Banners
+
+Use for major workflow transitions.
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ WORKFLOW ► {STAGE NAME}
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+**Stage names (uppercase):**
+- `QUESTIONING`
+- `RESEARCHING`
+- `DEFINING REQUIREMENTS`
+- `CREATING ROADMAP`
+- `PLANNING PHASE {N}`
+- `EXECUTING WAVE {N}`
+- `VERIFYING`
+- `PHASE {N} COMPLETE ✓`
+- `MILESTONE COMPLETE 🎉`
+
+---
+
+## Checkpoint Boxes
+
+User action required. 62-character width.
+
+```
+╔══════════════════════════════════════════════════════════════╗
+║  CHECKPOINT: {Type}                                          ║
+╚══════════════════════════════════════════════════════════════╝
+
+{Content}
+
+──────────────────────────────────────────────────────────────
+→ {ACTION PROMPT}
+──────────────────────────────────────────────────────────────
+```
+
+**Types:**
+- `CHECKPOINT: Verification Required` → `→ Type "approved" or describe issues`
+- `CHECKPOINT: Decision Required` → `→ Select: option-a / option-b`
+- `CHECKPOINT: Action Required` → `→ Type "done" when complete`
+
+---
+
+## Status Symbols
+
+```
+✓  Complete / Passed / Verified
+✗  Failed / Missing / Blocked
+◆  In Progress
+○  Pending
+⚡ Auto-approved
+⚠  Warning
+🎉 Milestone complete (only in banner)
+```
+
+---
+
+## Progress Display
+
+**Phase/milestone level:**
+```
+Progress: ████████░░ 80%
+```
+
+**Task level:**
+```
+Tasks: 2/4 complete
+```
+
+**Plan level:**
+```
+Plans: 3/5 complete
+```
+
+---
+
+## Spawning Indicators
+
+```
+◆ Spawning researcher...
+
+◆ Spawning 4 researchers in parallel...
+  → Stack research
+  → Features research
+  → Architecture research
+  → Pitfalls research
+
+✓ Researcher complete: STACK.md written
+```
+
+---
+
+## Next Up Block
+
+Always at end of major completions.
+
+```
+───────────────────────────────────────────────────────────────
+
+## ▶ Next Up
+
+**{Identifier}: {Name}** — {one-line description}
+
+`/clear` then:
+
+`{copy-paste command}`
+
+───────────────────────────────────────────────────────────────
+
+**Also available:**
+- `/workflow-xxx` — description
+- `/workflow-xxx` — description
+
+───────────────────────────────────────────────────────────────
+```
+
+---
+
+## Error Box
+
+```
+╔══════════════════════════════════════════════════════════════╗
+║  ERROR                                                       ║
+╚══════════════════════════════════════════════════════════════╝
+
+{Error description}
+
+**To fix:** {Resolution steps}
+```
+
+---
+
+## Tables
+
+```
+| Phase | Status | Plans | Progress |
+|-------|--------|-------|----------|
+| 1     | ✓      | 3/3   | 100%     |
+| 2     | ◆      | 1/4   | 25%      |
+| 3     | ○      | 0/2   | 0%       |
+```
+
+---
+
+## Anti-Patterns
+
+- Varying box/banner widths
+- Mixing banner styles (`===`, `---`, `***`)
+- Skipping `WORKFLOW ►` prefix in banners
+- Random emoji (`🚀`, `✨`, `💫`)
+- Missing Next Up block after completions
+
+</ui_patterns>

package/plugins/devflow-intel/agents/project-scout.md

@@ -0,0 +1,27 @@
+---
+name: project-scout
+description: Read-only project explorer that locates implementation evidence, architecture boundaries, and affected files without proposing speculative changes.
+tools:
+  - read
+  - grep
+  - find
+  - lsp
+  - devflow_code_index
+model: "@smol"
+thinkingLevel: medium
+autoloadSkills:
+  - code-index-query
+  - workflow-code-index
+---
+
+Act as a read-only evidence collector. Start from project indexes when they are fresh, then verify every material claim against LSP, search results, and source code. An index is an accelerator, never an authority.
+
+Return:
+
+1. relevant entry points and symbols with paths;
+2. cross-layer call paths;
+3. conventions and tests that constrain the change;
+4. unknowns or stale evidence;
+5. the smallest defensible affected-file set.
+
+Do not edit files, mutate workflow state, or widen the task beyond the supplied question.

package/plugins/devflow-intel/extensions/devflow-intel.ts

@@ -0,0 +1,104 @@
+import { existsSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+import type { ExtensionAPI } from "@oh-my-pi/pi-coding-agent";
+
+type ProcessResult = { ok: boolean; exitCode: number; stdout: string; stderr: string };
+
+function resolveSkillRoot(cwd: string): string {
+  const moduleDirectory = path.dirname(fileURLToPath(import.meta.url));
+  const candidates = [
+    process.env.DEVFLOW_KIT_ROOT,
+    path.join(cwd, ".skills"),
+    path.resolve(moduleDirectory, "../skills"),
+    path.resolve(moduleDirectory, "../../.."),
+  ].filter(Boolean) as string[];
+  for (const candidate of candidates) {
+    if (existsSync(path.join(candidate, "workflow-code-index/scripts/code_index.py"))) {
+      return path.resolve(candidate);
+    }
+  }
+  throw new Error("Devflow intel skills not found");
+}
+
+async function run(command: string[], cwd: string): Promise<ProcessResult> {
+  const child = Bun.spawn(command, { cwd, stdout: "pipe", stderr: "pipe" });
+  const [exitCode, stdout, stderr] = await Promise.all([
+    child.exited,
+    new Response(child.stdout).text(),
+    new Response(child.stderr).text(),
+  ]);
+  return { ok: exitCode === 0, exitCode, stdout: stdout.trim(), stderr: stderr.trim() };
+}
+
+function render(result: ProcessResult, details: Record<string, unknown>) {
+  return {
+    content: [
+      {
+        type: "text" as const,
+        text: result.stdout || result.stderr || `Process exited with ${result.exitCode}`,
+      },
+    ],
+    details: { ...details, exitCode: result.exitCode, stderr: result.stderr || undefined },
+    isError: !result.ok,
+  };
+}
+
+export default function devflowIntel(pi: ExtensionAPI) {
+  const { z } = pi.zod;
+
+  pi.registerTool({
+    name: "devflow_code_index",
+    label: "Devflow Code Index",
+    description: "Scan, validate, audit, or query the deterministic project code index.",
+    parameters: z.object({
+      action: z.enum(["scan", "validate", "audit", "query"]),
+      term: z.string().optional(),
+      limit: z.number().int().min(1).max(100).default(20),
+      changedFiles: z.array(z.string()).default([]),
+    }),
+    approval: (args) => {
+      const action = (args as { action?: string }).action;
+      // scan 写 .planning/code-index，按 exec 询问；validate/audit/query 只读，免确认。
+      return action === "scan" ? "exec" : "read";
+    },
+    async execute(_id, params, _signal, _onUpdate, ctx) {
+      const skillRoot = resolveSkillRoot(ctx.cwd);
+      const script = path.join(skillRoot, "workflow-code-index/scripts/code_index.py");
+      const args = ["python3", script, params.action];
+      if (params.action === "scan") {
+        args.push("--root", ctx.cwd, "--output", ".planning/code-index");
+        if (params.changedFiles.length > 0) args.push("--changed-files", ...params.changedFiles);
+      } else if (params.action === "validate") {
+        args.push("--index", ".planning/code-index");
+      } else if (params.action === "audit") {
+        args.push("--root", ctx.cwd, "--index", ".planning/code-index", "--skill-root", skillRoot);
+      } else {
+        if (!params.term) {
+          return render({ ok: false, exitCode: 2, stdout: "", stderr: "term is required" }, {});
+        }
+        args.push("--index", ".planning/code-index", "--term", params.term, "--limit", String(params.limit));
+      }
+      return render(await run(args, ctx.cwd), { action: params.action });
+    },
+  });
+
+  pi.registerTool({
+    name: "devflow_context_cursor",
+    label: "Devflow Context Cursor",
+    description: "Inspect or update repository cursors used by deterministic context reconciliation.",
+    parameters: z.object({ args: z.array(z.string()).default([]) }),
+    approval: "exec",
+    async execute(_id, params, _signal, _onUpdate, ctx) {
+      const skillRoot = resolveSkillRoot(ctx.cwd);
+      const script = path.join(
+        skillRoot,
+        "workflow-context-sync/scripts/context_sync_cursor.py",
+      );
+      return render(await run(["python3", script, ...params.args], ctx.cwd), {
+        action: "context-cursor",
+      });
+    },
+  });
+}

package/plugins/devflow-intel/package.json

@@ -0,0 +1,14 @@
+{
+  "name": "@devflow/omp-intel",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "peerDependencies": {
+    "@oh-my-pi/pi-coding-agent": "*"
+  },
+  "omp": {
+    "extensions": [
+      "./extensions/devflow-intel.ts"
+    ]
+  }
+}

package/plugins/devflow-intel/skills/code-index-query/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: code-index-query
+description: Query a generated .planning/code-index machine index to answer code structure questions. Use when the OMP development agent needs callers, callees, entrypoint flows, imports, resource reads/writes, tested_by links, or symbol locations before reading source evidence.
+---
+
+# Code Index Query
+
+Use this skill to answer source-structure questions from `.planning/code-index/`.
+
+## Required Flow
+
+1. Check that `.planning/code-index/index.sqlite` or JSONL sidecars exist.
+2. Search symbols or relations using the machine index.
+3. Expand relation edges as needed.
+4. Read source files at `evidence_path`.
+5. Answer with path, line, relation type, and confidence.
+
+Do not answer source facts from Markdown alone.
+
+## Commands
+
+Search symbols:
+
+```text
+devflow_code_index(action="query", term="{term}")
+```
+
+If the index is missing or stale:
+
+```text
+devflow_code_index(action="scan")
+devflow_code_index(action="audit")
+```
+
+## Query Patterns
+
+For more detailed query patterns, read `references/query-patterns.md`.

package/plugins/devflow-intel/skills/code-index-query/references/query-patterns.md

@@ -0,0 +1,27 @@
+# Query Patterns
+
+## Who Calls This Symbol
+
+1. Search `symbols` by name, qualified name, or path.
+2. Query `relations` where `to_id = target_symbol_id`.
+3. Read each `evidence_path`.
+4. Report callers grouped by confidence.
+
+## What Does This Entrypoint Call
+
+1. Search entrypoint symbols by name/path/kind.
+2. Expand `routes_to` and `calls`.
+3. Limit depth unless the user asks for full traversal.
+4. Read source evidence for each edge used in the answer.
+
+## Who Reads Or Writes This Resource
+
+1. Normalize target as `table:{name}`, `env:{name}`, `url:{value}`, or another external key.
+2. Query `relations.to_external`.
+3. Filter relation type: `reads`, `writes`, or `config_uses`.
+4. Read evidence lines before answering.
+
+## Missing Or Low Confidence
+
+If results are missing or only heuristic, say that the index has low-confidence evidence and cite diagnostics or source lines instead of claiming certainty.
+

package/plugins/devflow-intel/skills/workflow-code-index/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: workflow-code-index
+description: Build, refresh, validate, or audit a generic code intelligence index for any project. Use when the OMP development agent needs AST/LSP-style symbol, call, relation, JSONL/SQLite, incremental-change, or other machine-readable code facts before source tracing.
+---
+
+# Workflow Code Index
+
+Build a generic code intelligence index for the current project. This skill is project-agnostic: do not hardcode codebase names, business modules, paths, or language stacks.
+
+## Outputs
+
+Write generated artifacts to the target project:
+
+- `.planning/code-index/files.jsonl`
+- `.planning/code-index/symbols.jsonl`
+- `.planning/code-index/relations.jsonl`
+- `.planning/code-index/diagnostics.jsonl`
+- `.planning/code-index/index.sqlite`
+- `.planning/code-index/INDEX.md`
+- `.planning/code-index/SYMBOLS.md`
+- `.planning/code-index/RELATIONS.md`
+- `.planning/code-index/ENTRYPOINTS.md`
+- `.planning/code-index/DATAFLOW.md`
+- `.planning/code-index/AUDIT.md` when auditing
+
+Markdown is a display layer only. JSONL/SQLite is the machine fact layer.
+
+## Required References
+
+Read these references when modifying the skill or interpreting its outputs:
+
+- `references/data-model.md` — File/Symbol/Relation/Diagnostic schema
+- `references/adapter-contract.md` — adapter interface and output rules
+- `references/confidence-rules.md` — exact/inferred/heuristic semantics
+- `references/discovery.md` — project/codebase discovery order
+- `references/query-guide.md` — query and source readback rules
+- `references/audit-checklist.md` — required schema, evidence, freshness, and genericity checks
+
+## Command
+
+Use the OMP runtime tool:
+
+```text
+devflow_code_index(action="scan")
+devflow_code_index(action="validate")
+devflow_code_index(action="audit")
+```
+
+For changed-file indexing:
+
+```text
+devflow_code_index(action="scan", changedFiles=["path/to/file.ext"])
+```
+
+## Audit Gate
+
+`audit` is part of this skill's normal lifecycle, not a separate workflow. Run `validate` before `audit` whenever index files were edited or refreshed, then review `.planning/code-index/AUDIT.md` against `references/audit-checklist.md`.
+
+Blocking findings are stale file hashes, missing indexed files, dangling `to_id` relations, missing relation evidence, and invalid schema. Unresolved heuristic calls, low-confidence diagnostics, and possible project-bound examples in generic skills are non-blocking but must be reported.
+
+## Rules
+
+- Do not use vectors as a fact source.
+- Do not let LLM-authored Markdown create new facts.
+- Do not write relations without `evidence_path`, `evidence_line`, and `confidence`.
+- Do not mark dynamic or string-based matches as `exact`.
+- If adapter support is missing, emit diagnostics and fall back to generic indexing.
+- Query answers must read source files at evidence paths before making factual claims.

package/plugins/devflow-intel/skills/workflow-code-index/references/adapter-contract.md

@@ -0,0 +1,38 @@
+# Adapter Contract
+
+Adapters convert files into the shared data model. They must not invent project-specific conventions unless the source files, manifests, navigation, or framework facts provide evidence.
+
+## Required Interface
+
+Every adapter implements:
+
+- `detect(codebase, files, manifests) -> score`
+- `parse_file(codebase, file_record, text) -> ParseResult`
+- `resolve_relations(codebase, symbols, relations) -> relations`
+- `version() -> str`
+
+## ParseResult
+
+The result contains:
+
+- `symbols`
+- `relations`
+- `diagnostics`
+
+## Resolution Rules
+
+- A parser may emit unresolved calls as `to_external: "call:{name}"`.
+- Resolver may upgrade to `to_id` only when a unique symbol target is found.
+- Unique AST/LSP matches can be `exact`.
+- Naming or directory convention matches are `inferred`.
+- String or regex matches are `heuristic`.
+
+## Adapter Types
+
+- `generic-text`: fallback for all source files.
+- `tree-sitter-*`: AST symbols/imports/basic calls when dependency is available.
+- `lsp-*`: definition/reference/call hierarchy when language service is available.
+- `framework-*`: routes, ORM/database, jobs, config, tests, components.
+
+Core schema and writers must not change when a new adapter is added.
+

package/plugins/devflow-intel/skills/workflow-code-index/references/audit-checklist.md

@@ -0,0 +1,10 @@
+# Audit Checklist
+
+- JSONL records satisfy schema.
+- SQLite exists and can be queried.
+- Every relation has evidence path, line, and confidence.
+- Every `to_id` points to an existing symbol.
+- `exact` is not used for unresolved dynamic calls.
+- Indexed files exist and hashes match current source.
+- Markdown files are generated from machine index.
+- Generic skill references use placeholders instead of project-specific paths or business names.

package/plugins/devflow-intel/skills/workflow-code-index/references/confidence-rules.md

@@ -0,0 +1,43 @@
+# Confidence Rules
+
+## exact
+
+Use only when the target is deterministically known:
+
+- AST/LSP resolves a unique symbol.
+- A manifest or route table maps an entry to one target.
+- A parser can point to a single external entity.
+
+## inferred
+
+Use when the target follows a project or framework convention:
+
+- Route names map to handlers by naming convention.
+- Import path and symbol name imply a unique local target.
+- Test names conventionally map to implementation names.
+
+Include the basis in relation metadata.
+
+## heuristic
+
+Use when the relation comes from text patterns:
+
+- Dynamic calls.
+- String-built routes.
+- SQL snippets.
+- Environment variable names.
+- Reflection, macros, decorators, framework magic, or template strings.
+
+Heuristic relations are candidate evidence only. Query skills must read source before using them in an answer.
+
+## Invalid
+
+Do not write relation records without:
+
+- `evidence_path`
+- `evidence_line`
+- `confidence`
+- `to_id` or `to_external`
+
+Write diagnostics instead.
+

package/plugins/devflow-intel/skills/workflow-code-index/references/data-model.md

@@ -0,0 +1,74 @@
+# Code Index Data Model
+
+All adapters must emit these records. Examples use placeholders only; do not replace them with project-specific paths in this reference.
+
+## File
+
+```json
+{
+  "id": "file:{codebase}:{relative_path}",
+  "codebase": "{codebase}",
+  "path": "{workspace_relative_path}",
+  "language": "{language_id}",
+  "size_bytes": 0,
+  "content_hash": "sha256:{hash}",
+  "indexed_at": "{iso8601_time}",
+  "parser": "{adapter}@{version}"
+}
+```
+
+## Symbol
+
+```json
+{
+  "id": "{language}:{codebase}:{stable_qualified_symbol_key}",
+  "codebase": "{codebase}",
+  "kind": "function|method|class|struct|interface|trait|route|file|table|config|test|component|module",
+  "name": "{short_name}",
+  "qualified_name": "{language_native_qualified_name}",
+  "container_id": "{optional_parent_symbol_id}",
+  "path": "{workspace_relative_path}",
+  "line_start": 1,
+  "line_end": 1,
+  "signature": "{optional_signature}",
+  "language": "{language_id}",
+  "content_hash": "sha256:{hash}",
+  "visibility": "{optional_visibility}",
+  "metadata": {}
+}
+```
+
+Symbol IDs must not depend on line numbers. Use language, codebase, stable qualified name, and signature hash when needed.
+
+## Relation
+
+```json
+{
+  "from_id": "{source_symbol_id}",
+  "relation_type": "contains|imports|calls|extends|implements|routes_to|reads|writes|tested_by|config_uses",
+  "to_id": "{optional_target_symbol_id}",
+  "to_external": "{optional_external_target}",
+  "evidence_path": "{workspace_relative_path}",
+  "evidence_line": 1,
+  "confidence": "exact|inferred|heuristic",
+  "parser": "{adapter}@{version}",
+  "metadata": {}
+}
+```
+
+`to_id` and `to_external` are mutually compatible, but at least one must be present.
+
+## Diagnostic
+
+```json
+{
+  "codebase": "{codebase}",
+  "path": "{workspace_relative_path}",
+  "line": 1,
+  "severity": "info|warning|error",
+  "kind": "parse_failed|adapter_missing|low_confidence|ambiguous_target|skipped_file|stale_index|project_binding",
+  "message": "{message}",
+  "parser": "{adapter}@{version}"
+}
+```
+

package/plugins/devflow-intel/skills/workflow-code-index/references/discovery.md

@@ -0,0 +1,24 @@
+# Discovery
+
+Discover codebases in this order:
+
+1. Explicit CLI arguments: `--codebase name:path[:type]`.
+2. `.planning/navigation/INDEX.md` Codebase Registry.
+3. `.context/spec/index.md` codebase mapping.
+4. Current working directory fallback.
+
+Normalize each codebase to:
+
+```json
+{
+  "name": "{codebase}",
+  "root": "{absolute_root}",
+  "type_hint": "{optional}",
+  "stack_hint": "{optional}",
+  "navigation_path": "{optional}",
+  "spec_path": "{optional}"
+}
+```
+
+Never hardcode project names or directories in the skill. Project-specific names only appear in generated index artifacts for that project.
+

package/plugins/devflow-intel/skills/workflow-code-index/references/query-guide.md

@@ -0,0 +1,20 @@
+# Query Guide
+
+Query flow:
+
+1. Load project rules and navigation if present.
+2. Check `.planning/code-index/index.sqlite` or JSONL sidecars.
+3. Search symbols using exact name, qualified name, path, or FTS.
+4. Expand relations by type and depth.
+5. Read source files at `evidence_path`.
+6. Answer with source path, line number, relation type, and confidence.
+
+Do not answer source facts from Markdown alone.
+
+Common queries:
+
+- Who calls this symbol: find target symbol, then query `relations.to_id`.
+- What does this entrypoint call: find entrypoint, then expand `routes_to` and `calls`.
+- Who reads/writes an external resource: query `to_external` with `reads`, `writes`, or `config_uses`.
+- Which tests cover this: query `tested_by` or diagnostics for unresolved test mapping.
+

package/plugins/devflow-intel/skills/workflow-code-index/scripts/adapters/__init__.py

@@ -0,0 +1 @@
+