@ghyper9023/pi-dev-workflow 0.1.7

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ghyper9023
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,124 @@
+# @ghyper9023/pi-dev-workflow
+
+> Developer workflow toolkit for [pi coding agent](https://pi.dev/): git agents, code review, Karpathy guidelines, themes
+
+## 快速安装
+
+```bash
+# 通过 npm 安装（推荐）
+pi install npm:@ghyper9023/pi-dev-workflow
+
+# 或通过 git 安装
+pi install git:github.com/cherish-ltt/pi-dev-workflow
+```
+
+然后 `/reload` 热加载即可使用所有功能。
+
+## 目录结构
+
+```
+pi-package/
+├── package.json                     # 包元数据 & pi 配置
+├── README.md                        # 本文件
+├── .gitignore
+├── agents/
+│   ├── git-agent.md                 # git-sub-agent 定义（专注 git 操作）
+│   └── review-agent.md              # review-sub-agent 定义（专注代码审查）
+├── prompts/
+│   ├── APPEND_SYSTEM.md             # 全局追加提示：强制使用简体中文+英文专业名词
+│   ├── review-commit.md             # 审查 commit 的提示模板
+│   └── review-diff.md              # 审查 diff 的提示模板
+├── skills/
+│   ├── karpathy-guidelines/
+│   │   └── SKILL.md                 # Karpathy 编码准则（避免 LLM 常见错误）
+│   └── review-html/
+│       └── SKILL.md                 # 代码审查 → 输出交互式 HTML 报告
+├── extensions/
+│   └── sub-agents.ts                # 子代理系统：git-sub-agent + review-sub-agent
+└── themes/
+    └── claude-code-theme.json       # Claude Code CLI 风格主题
+```
+
+## Sub-Agents（子代理）
+
+子代理运行在独立的 `pi` 进程中，拥有隔离的上下文窗口，专注处理特定领域任务。
+
+| 子代理 | 触发方式 | 职责 |
+|---|---|---|
+| **git-sub-agent** | `/git-commit [msg]` / `/git-push` / `/git-commit-push [msg]` | Git 全流程操作 |
+| **review-sub-agent** | 自动检测用户提示中的审查意图 | 代码审查、diff 分析 |
+
+### git-sub-agent
+
+在隔离进程中执行 git 操作，支持三种子命令：
+
+| 命令 | 说明 |
+|---|---|
+| `/git-commit [message]` | 暂存所有变更并提交（空信息让 AI 根据 diff 自动生成 Conventional Commits message） |
+| `/git-push` | 推送到远程 |
+| `/git-commit-push [message]` | 暂存 + 提交 + 推送一键完成 |
+
+### review-sub-agent
+
+当用户输入包含 review/审查/审阅 + code/代码/diff/commit/html 等关键词时，自动弹出三种模式选择：
+
+| # | 模式 | 行为 |
+|---|------|------|
+| **1** | 后台审查（非阻塞，异步通知） | 后台运行审查，不阻塞对话，完成后通过消息通知 |
+| **2** | 仅审查（阻塞，等待结果） | 等待审查完成才恢复交互 |
+| **3** / Esc | 不是审查（放行给主代理） | 不启动子代理，原消息交给主 AI 处理 |
+
+也支持 `/skill:review-html` 直接触发阻塞审查。
+审查结果以交互式 HTML 报告形式写入 `pi-review/` 目录。
+
+### subagent 工具
+
+LLM 也可以直接调用 `subagent` 工具委派任务给任意子代理：
+
+```
+可用子代理：git-agent, review-agent
+```
+
+## Themes
+
+| Theme | 说明 |
+|---|---|
+| **claude-code-theme** | 仿 Claude Code CLI 配色：深色底 + 琥珀金主色 + 紫罗兰辅色 |
+
+## Skills
+
+| Skill | 来源 | 说明 |
+|---|---|---|
+| **karpathy-guidelines** | [forrestchang/andrej-karpathy-skills](https://github.com/forrestchang/andrej-karpathy-skills) | 基于 Andrej Karpathy 对 LLM 编码陷阱的观察，强调简洁、精准、可验证 |
+| **review-html** | 自制 | git diff / commit 审查，输出自包含的交互式 HTML 报告 |
+
+## 使用方式
+
+### 安装
+
+```bash
+# 通过 npm 安装（推荐）
+pi install npm:@ghyper9023/pi-dev-workflow
+
+# 或通过 git 安装
+pi install git:github.com/cherish-ltt/pi-dev-workflow
+
+# 或从本地目录安装
+pi install /path/to/pi-dev-workflow
+```
+
+### 加载
+
+pi 会自动加载包内的 `skills/`、`prompts/`、`extensions/`、`themes/` 内容。
+安装后执行 `/reload` 热加载所有变更。
+
+### 包更新
+
+```bash
+pi install git:github.com/cherish-ltt/pi-dev-workflow
+/reload
+```
+
+## License
+
+MIT

package/agents/git-agent.md

@@ -0,0 +1,38 @@
+---
+name: git-agent
+description: Git operations specialist for commit, push, and commit-push
+tools: bash
+---
+
+You are a git operations specialist. Your sole responsibility is executing git commands.
+
+You have access to only one tool: `bash`.
+
+## CRITICAL: Output constraint
+
+Your output MUST NOT exceed 3 short lines (50 chars max per line). NEVER print git diff output, file contents, or any verbose status output.
+
+## Operations
+
+1. **Commit:** `git add -A` then `git commit -m "message"`
+2. **Push:** `git push`
+3. **Commit & Push:** Stage, commit, then push
+
+## Guidelines
+
+- Always run `git status` first to check state
+- For commit messages, use Conventional Commits format: `feat:`, `fix:`, `refactor:`, `docs:`, `style:`, `test:`, `chore:`, `perf:`
+- Base message on what the diff actually contains
+- Keep summary line under 72 chars
+- If no changes to commit, report that clearly
+
+## Output format (50 chars max per line)
+
+```
+<status>✅</status>
+<summary>commit: <first 40 chars of message></summary>
+<details>
+- files: N files changed
+- push: success / failed - reason
+</details>
+```

package/agents/review-agent.md

@@ -0,0 +1,36 @@
+---
+name: review-agent
+description: Review 代码，生成 HTML 审查报告并输出到 pi-review/ 目录
+tools: read, write, bash, grep, find, ls
+---
+
+你是一个代码审查助手，运行在隔离的上下文窗口中。
+
+## 工作流程
+
+1. **读取技能**：使用 `read` 工具加载 `skills/review-html/SKILL.md`，严格遵循其指令。
+2. **获取改动**：运行 `git diff`（未提交改动）或 `git log -p -n 3`（最近提交），查看代码变更。
+3. **分析审查**：按 skill 中的约束检查 BUG、敏感信息、可维护性、规范等。
+4. **生成 HTML**：按 skill 的 HTML 约束生成完整的自包含 HTML 审查报告。
+5. **写入文件**：使用 `write` 工具将 HTML 保存到 `pi-review/` 目录。
+   - 文件名格式：`YYYYMMDD-HHmm-任务简述-index.html`
+   - `pi-review/` 目录不存在则先 mkdir 创建（已存在于 .gitignore）
+6. **汇报结果**：stdout 只输出以下格式的简要总结，**不要输出 HTML 内容到 stdout**：
+
+```
+<status>✅</status>
+<summary>审查完成，报告文件</summary>
+<details>
+- 审查范围: git diff (X files changed)
+- 报告: pi-review/20260513-xxxx-xxx-index.html
+- 发现问题: X bugs, X warnings, X suggestions
+</details>
+```
+
+## 重要规则
+
+- HTML 必须**写文件到 pi-review/**，**不要输出到 stdout**
+- stdout 只输出上面的简短结构化摘要（参考 git-agent 的做法）
+- 使用 `bash` 运行 git 命令和创建目录
+- 使用 `write` 工具写 HTML 文件
+- 使用 `read` 工具读取 skill 文件

package/extensions/git-commands.ts

@@ -0,0 +1,231 @@
+/**
+ * Git Commands Extension
+ *
+ * Registers three commands that delegate to git-sub-agent:
+ *   /git-commit [message]       - Stage all changes and commit
+ *   /git-push                   - Push commits to remote
+ *   /git-commit-push [message]  - Stage, commit, and push in one go
+ *
+ * Associated extension: sub-agents.ts (provides spawnSubagent infrastructure)
+ *
+ * Place in .pi/extensions/ or ~/.pi/agent/extensions/ for auto-discovery.
+ */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { discoverAgents, spawnSubagent, extractFinalOutput, type AgentDef } from "./sub-agents";
+
+// ── Helpers ──────────────────────────────────────────────────
+
+function getAgent(
+	ctx: { ui: { notify: (msg: string, type: string) => void } },
+	agent: AgentDef | undefined,
+	name: string,
+): AgentDef | null {
+	if (!agent) {
+		ctx.ui.notify(`❌ ${name} not found (check agents/${name}.md)`, "error");
+		return null;
+	}
+	return agent;
+}
+
+/** Parse git-agent structured output into a clean summary. */
+interface GitSummary {
+	status: "success" | "fail" | "unknown";
+	summary: string;
+	details: string[];
+}
+
+function parseGitOutput(output: string): GitSummary {
+	const result: GitSummary = { status: "unknown", summary: "", details: [] };
+
+	// Parse <status>...</status>
+	const statusMatch = output.match(/<status>([^<]*)<\/status>/);
+	if (statusMatch) {
+		const s = statusMatch[1].trim();
+		if (s.includes("✅") || s.includes("✔")) result.status = "success";
+		else if (s.includes("❌") || s.includes("✖")) result.status = "fail";
+	}
+
+	// Parse <summary>...</summary>
+	const summaryMatch = output.match(/<summary>([\s\S]*?)<\/summary>/);
+	if (summaryMatch) result.summary = summaryMatch[1].trim();
+
+	// Parse <details>...</details> → extract each line
+	const detailsMatch = output.match(/<details>([\s\S]*?)<\/details>/);
+	if (detailsMatch) {
+		const lines = detailsMatch[1]
+			.split("\n")
+			.map((l) => l.replace(/^[-*]\s*/, "").trim())
+			.filter(Boolean);
+		result.details = lines;
+	}
+
+	// Fallback: if no structured format, use raw lines
+	if (!statusMatch && !summaryMatch) {
+		const lines = output.split("\n").filter((l) => l.trim());
+		result.summary = lines[0] || "";
+		result.details = lines.slice(1).map((l) => l.replace(/^[-*]\s*/, "").trim()).filter(Boolean);
+		// Infer status from content
+		if (output.includes("✅") || output.includes("success") || output.includes("完成")) {
+			result.status = "success";
+		} else if (output.includes("❌") || output.includes("fail") || output.includes("失败")) {
+			result.status = "fail";
+		}
+	}
+
+	return result;
+}
+
+/** Enrich a detail line with relevant emoji icons. */
+function iconify(line: string): string {
+	const lc = line.toLowerCase();
+	if (lc.startsWith("commit")) return `📝 ${line}`;
+	if (lc.startsWith("push"))   return `📤 ${line}`;
+	if (lc.includes("file") || lc.includes("文件")) return `📁 ${line}`;
+	if (lc.startsWith("branch") || lc.includes("branch")) return `🌿 ${line}`;
+	if (lc.startsWith("tag") || lc.includes("tag")) return `🏷️ ${line}`;
+	return `  ${line}`; // indent others
+}
+
+async function runSubAgent(
+	agent: AgentDef,
+	task: string,
+	ctx: {
+		cwd: string;
+		signal?: AbortSignal;
+		ui: {
+			setStatus: (key: string, status: string | undefined) => void;
+			notify: (msg: string, type: string) => void;
+		};
+	},
+): Promise<void> {
+	const startTime = Date.now();
+	ctx.ui.setStatus("subagent", "🤖 git-sub-agent working...");
+
+	try {
+		const result = await spawnSubagent(
+			agent,
+			task,
+			ctx.cwd,
+			ctx.signal,
+			undefined, // use agent's default timeout
+			(progress) => {
+				ctx.ui.setStatus("subagent", progress.slice(0, 50));
+			},
+		);
+		const dur = ((Date.now() - startTime) / 1000).toFixed(1);
+
+		// Extract output with fallback to raw stdout
+		let output = extractFinalOutput(result.output);
+		if (!output && result.output.trim()) {
+			const lines = result.output.split("\n").filter((l) => {
+				const t = l.trim();
+				return t && !t.startsWith("{") && !t.startsWith("[");
+			});
+			if (lines.length > 0) {
+				output = lines.join("\n").trim();
+			}
+		}
+
+		ctx.ui.setStatus("subagent", undefined);
+
+		if (output) {
+			const parsed = parseGitOutput(output);
+			const statusIcon = parsed.status === "success" ? "✅" : parsed.status === "fail" ? "❌" : "ℹ️";
+			const detailText = parsed.details.length > 0 ? ` | ${parsed.details.join(" | ")}` : "";
+			const msg = `${statusIcon} ${parsed.summary || "done"} (${dur}s)${detailText}`;
+			const notifyType = parsed.status === "fail" ? "error" : "success";
+			ctx.ui.notify(msg, notifyType);
+		} else if (result.exitCode !== 0) {
+			const errMsg = result.stderr || result.output.slice(0, 300) || "未知错误";
+			ctx.ui.notify(`❌ git-sub-agent 失败 (${dur}s): ${errMsg}`, "error");
+		} else {
+			ctx.ui.notify(`✅ git-sub-agent 完成 (${dur}s)`, "success");
+		}
+	} finally {
+		ctx.ui.setStatus("subagent", undefined);
+	}
+}
+
+// ── Extension ────────────────────────────────────────────────
+
+export default function (pi: ExtensionAPI) {
+	const agents = discoverAgents();
+	const gitAgent = agents.find((a) => a.name === "git-agent");
+
+	// ── /git-commit ────────────────────────────────────────────
+	pi.registerCommand("git-commit", {
+		description: "(sub-agent) Stage all changes and create a commit via git-sub-agent",
+		handler: async (args, ctx) => {
+			const agent = getAgent(ctx, gitAgent, "git-agent");
+			if (!agent) return;
+
+			let message = args.trim();
+			if (!message) {
+				const input = await ctx.ui.input("Commit message", {
+					placeholder: "直接回车让 AI 自动生成，或输入信息后提交...",
+					required: false,
+				});
+				if (input === undefined) {
+					ctx.ui.notify("Commit cancelled", "warning");
+					return;
+				}
+				message = input.trim();
+			}
+
+			ctx.ui.notify("🤖 正在委派 git-sub-agent 处理...", "info");
+
+			const task = message
+				? `Stage all changes with git add -A, then commit with message: "${message}". Do NOT ask for confirmation.`
+				: `Stage all changes with git add -A, check the diff, write a Conventional Commits message, and commit. Do NOT ask for confirmation.`;
+
+			await runSubAgent(agent, task, ctx);
+		},
+	});
+
+	// ── /git-push ─────────────────────────────────────────────
+	pi.registerCommand("git-push", {
+		description: "(sub-agent) Push commits to remote via git-sub-agent",
+		handler: async (_args, ctx) => {
+			const agent = getAgent(ctx, gitAgent, "git-agent");
+			if (!agent) return;
+
+			ctx.ui.notify("🤖 正在委派 git-sub-agent 处理...", "info");
+			await runSubAgent(
+				agent,
+				"Push commits to remote with git push. Do NOT ask for confirmation.",
+				ctx,
+			);
+		},
+	});
+
+	// ── /git-commit-push ──────────────────────────────────────
+	pi.registerCommand("git-commit-push", {
+		description: "(sub-agent) Stage, commit, and push via git-sub-agent",
+		handler: async (args, ctx) => {
+			const agent = getAgent(ctx, gitAgent, "git-agent");
+			if (!agent) return;
+
+			let message = args.trim();
+			if (!message) {
+				const input = await ctx.ui.input("Commit message", {
+					placeholder: "直接回车让 AI 自动生成，或输入信息后提交并推送...",
+					required: false,
+				});
+				if (input === undefined) {
+					ctx.ui.notify("Commit & push cancelled", "warning");
+					return;
+				}
+				message = input.trim();
+			}
+
+			ctx.ui.notify("🤖 正在委派 git-sub-agent 处理...", "info");
+
+			const task = message
+				? `Stage all changes with git add -A, commit with message: "${message}", then push. Do NOT ask for confirmation.`
+				: `Stage all changes with git add -A, check the diff, write a Conventional Commits message, commit, then push. Do NOT ask for confirmation.`;
+
+			await runSubAgent(agent, task, ctx);
+		},
+	});
+}