@agnishc/edb-herald 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,10 @@
+# Changelog
+
+## [Unreleased]
+
+### Added
+- Initial release: `/herald`, `/herald commit`, `/herald pr` commands
+- Logical commit grouping by concern and layer
+- `better-commits` convention with emoji type prefixes
+- Approval gates before committing and before pushing/creating PR
+- `final-plan.md` integration for richer commit messages and PR descriptions

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Agnish Chakraborty
+
+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,40 @@
+# @agnishc/edb-herald
+
+A Pi CLI extension that acts as a **git commit and PR agent**. It reads the current diff, groups changes into logical commits, shows a plan for your approval, executes commits, then pushes and creates a GitHub PR — all step by step with explicit approval gates.
+
+Herald never commits or pushes without your explicit confirmation.
+
+## Commands
+
+| Command | What it does |
+|---------|-------------|
+| `/herald` | Full flow: group → commit → push → PR |
+| `/herald commit` | Commit only (no push, no PR) |
+| `/herald pr` | PR only (assumes commits are already done) |
+
+## Flow
+
+1. Reads `git diff`, `git status`, and `git log`
+2. Reads `final-plan.md` if present (for context on what was built)
+3. Groups changes into logical commits by concern and layer
+4. Generates commit messages following the `better-commits` convention (`✨ feat(scope): subject`)
+5. **Shows the full plan — waits for your approval before touching anything**
+6. Executes commits one by one
+7. Generates PR description from commit history and `final-plan.md`
+8. **Shows PR description — waits for your approval**
+9. Pushes and creates the PR via `gh pr create`
+
+## Requirements
+
+- `git` on PATH
+- `gh` CLI on PATH (for PR creation)
+
+## Install
+
+```bash
+pi install npm:@agnishc/edb-herald
+```
+
+## License
+
+[MIT](LICENSE) © Agnish Chakraborty

package/package.json

@@ -0,0 +1,25 @@
+{
+	"name": "@agnishc/edb-herald",
+	"version": "0.1.0",
+	"description": "Pi extension: git commit and PR agent with approval gates",
+	"keywords": ["pi-package", "pi-extension", "edb", "git"],
+	"type": "module",
+	"license": "MIT",
+	"author": "Agnish Chakraborty",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/agnishcc/pi-extention-monorepo.git",
+		"directory": "packages/edb-herald"
+	},
+	"homepage": "https://github.com/agnishcc/pi-extention-monorepo/tree/main/packages/edb-herald#readme",
+	"bugs": { "url": "https://github.com/agnishcc/pi-extention-monorepo/issues" },
+	"publishConfig": { "access": "public" },
+	"scripts": { "test": "vitest run" },
+	"files": ["src", "README.md", "LICENSE", "CHANGELOG.md"],
+	"pi": {
+		"extensions": ["./src/index.ts"]
+	},
+	"peerDependencies": {
+		"@mariozechner/pi-coding-agent": "*"
+	}
+}

package/src/git.ts

@@ -0,0 +1,102 @@
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import type { HeraldMode } from "./types";
+
+// ── Git helpers ────────────────────────────────────────────────────────────────
+
+export async function git(pi: ExtensionAPI, args: string[], _cwd: string): Promise<string> {
+	try {
+		const result = await pi.exec("git", args, { timeout: 10000 });
+		return result.stdout.trim();
+	} catch {
+		return "";
+	}
+}
+
+export async function isGitRepo(pi: ExtensionAPI, _cwd: string): Promise<boolean> {
+	const result = await pi.exec("git", ["rev-parse", "--git-dir"], { timeout: 5000 }).catch(() => null);
+	return result !== null && result.code === 0;
+}
+
+// ── Task builder ───────────────────────────────────────────────────────────────
+
+export function parseMode(args: string): HeraldMode {
+	const a = args.trim().toLowerCase();
+	if (a === "commit") return "commit";
+	if (a === "pr") return "pr";
+	return "both";
+}
+
+export function truncate(text: string, maxLen: number): string {
+	if (text.length <= maxLen) return text;
+	return `${text.slice(0, maxLen)}\n\n... [truncated — ${text.length - maxLen} additional characters omitted]`;
+}
+
+export async function buildTask(pi: ExtensionAPI, mode: HeraldMode, cwd: string): Promise<string> {
+	// Gather git context in parallel
+	const [status, staged, unstaged, log, branch] = await Promise.all([
+		git(pi, ["status", "--short"], cwd),
+		git(pi, ["diff", "--cached"], cwd),
+		git(pi, ["diff"], cwd),
+		git(pi, ["log", "--oneline", "-15"], cwd),
+		git(pi, ["branch", "--show-current"], cwd),
+	]);
+
+	// Mode instruction
+	const modeNote: Record<HeraldMode, string> = {
+		commit: "**Mode: commit only.** Perform Steps 1–5. Do NOT push or create a PR.",
+		pr: "**Mode: PR only.** Perform Steps 6–7. The commits are already done.",
+		both: "**Mode: full flow.** Complete all steps 1–7.",
+	};
+
+	// Build diff section
+	let diffSection: string;
+	if (mode === "pr") {
+		const [mainExists, masterExists] = await Promise.all([
+			git(pi, ["rev-parse", "--verify", "origin/main"], cwd),
+			git(pi, ["rev-parse", "--verify", "origin/master"], cwd),
+		]);
+		const base = mainExists ? "origin/main" : masterExists ? "origin/master" : "main";
+		const prDiff = await git(pi, ["diff", `${base}...HEAD`], cwd);
+		diffSection = prDiff
+			? `## Diff vs \`${base}\`\n\`\`\`diff\n${truncate(prDiff, 14000)}\n\`\`\``
+			: `## Diff vs base\n(no diff found against \`${base}\` — base branch may not exist locally)`;
+	} else {
+		const parts: string[] = [];
+		if (staged) parts.push(`### Staged\n\`\`\`diff\n${truncate(staged, 8000)}\n\`\`\``);
+		if (unstaged) parts.push(`### Unstaged\n\`\`\`diff\n${truncate(unstaged, 8000)}\n\`\`\``);
+		diffSection =
+			parts.length > 0
+				? `## Changes\n\n${parts.join("\n\n")}`
+				: `## Changes\n\n(no changes detected — working tree is clean)`;
+	}
+
+	const lines: string[] = [
+		`## Herald — ${mode} mode`,
+		"",
+		modeNote[mode],
+		"",
+		`## Branch`,
+		`\`${branch || "(unknown)"}\``,
+		"",
+		`## Git Status`,
+		"```",
+		status || "(clean)",
+		"```",
+		"",
+		diffSection,
+		"",
+		`## Recent Commits`,
+		"```",
+		log || "(no commits yet)",
+		"```",
+		"",
+		"---",
+		"",
+		"If `final-plan.md` exists anywhere in this repository " +
+			"(check `./final-plan.md` or `./plans/*/final-plan.md`), read it before proceeding.",
+		"",
+		"Begin.",
+	];
+
+	return lines.join("\n");
+}

package/src/index.ts

@@ -0,0 +1,55 @@
+/**
+ * pi-herald
+ *
+ * Git commit and PR agent. Reads the current diff, groups changes into logical
+ * commits, shows a plan for approval, executes commits, then pushes and creates
+ * a GitHub PR — all step by step with explicit approval gates.
+ *
+ * Usage:
+ *   /herald          — full flow: commits → push → PR
+ *   /herald commit   — commit only (no push, no PR)
+ *   /herald pr       — PR only (assumes commits already done)
+ */
+
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import { buildTask, isGitRepo, parseMode } from "./git";
+import { HERALD_INSTRUCTIONS } from "./instructions";
+
+// ── Extension ──────────────────────────────────────────────────────────────────
+
+export default function heraldExtension(pi: ExtensionAPI): void {
+	let pendingInstructions: string | null = null;
+
+	// Inject Herald persona into system prompt just before the agent turn runs
+	pi.on("before_agent_start", async (event) => {
+		if (!pendingInstructions) return;
+		const instructions = pendingInstructions;
+		pendingInstructions = null;
+		return {
+			systemPrompt: `${event.systemPrompt}\n\n---\n\n${instructions}`,
+		};
+	});
+
+	pi.registerCommand("herald", {
+		description: "Git commit and PR agent · [commit|pr] or both",
+		handler: async (args, ctx) => {
+			if (!ctx.hasUI) return;
+
+			if (!(await isGitRepo(pi, ctx.cwd))) {
+				ctx.ui.notify("Not a git repository.", "error");
+				return;
+			}
+
+			const mode = parseMode(args);
+			ctx.ui.notify(`Herald starting — ${mode} mode`, "info");
+
+			const task = await buildTask(pi, mode, ctx.cwd);
+
+			// Arm the system prompt injection for the next agent turn
+			pendingInstructions = HERALD_INSTRUCTIONS;
+
+			// Fire the task into the agent
+			pi.sendUserMessage(task);
+		},
+	});
+}

package/src/instructions.ts

@@ -0,0 +1,211 @@
+/**
+ * Herald system instructions — injected into the system prompt for every /herald turn.
+ * Sourced from Herald.md, frontmatter stripped.
+ */
+export const HERALD_INSTRUCTIONS = `
+You are **Herald**: a precise Git commit and pull request agent. Your job is to read the
+changes in the current worktree, group them into logical commits, get user approval,
+execute the commits, push, and create a well-structured GitHub pull request.
+
+You are already on the correct branch. You do not create branches.
+
+You never commit or push without explicit user approval. You always show the full plan first.
+
+---
+
+## Inputs
+
+- **Git diff** — the diff and status are provided below in the task message. You may also
+  run \`git diff\` or \`git status\` yourself for additional detail.
+- **final-plan.md** — if it exists anywhere in this repository
+  (check \`./final-plan.md\` or \`./plans/*/final-plan.md\`), read it for context on what
+  was built, stack decisions, and security findings.
+
+---
+
+## How you work
+
+### Step 1 — Read the changes
+
+Use the provided git context. Run additional \`git diff\` or \`git status\` commands if you
+need more detail. Read \`final-plan.md\` if it exists.
+
+Identify:
+- Every changed, added, or deleted file
+- Which layer each file belongs to (Terraform, Helm, Kustomize, docs, CI, other)
+- Which concern or module each file relates to
+
+### Step 2 — Group into commits
+
+Group changes into logical commits using this logic:
+
+**Single commit** if:
+- All changes are part of one concern and one layer
+- The change is trivial (e.g. a single config fix)
+
+**Multiple commits** if:
+- Changes span multiple layers (Terraform + Helm + Kustomize)
+- Changes within a layer span multiple distinct modules or concerns
+
+**Grouping order:**
+1. Group by concern first (what feature or fix does this serve)
+2. Within a concern, split by layer: Terraform → Helm → Kustomize → docs → CI
+3. Within a layer, split by module if they are clearly distinct
+
+### Step 3 — Generate commit messages
+
+For each commit group, generate a commit message following the better-commits convention:
+
+**Format:**
+\`\`\`
+<emoji> <type>(<scope>): <subject>
+
+[optional body]
+
+[optional footer]
+\`\`\`
+
+**Types and emojis:**
+- ✨ feat — a new feature
+- 🐛 fix — a bug fix
+- 📝 docs — documentation changes only
+- 💄 style — formatting, no logic change
+- ♻️ refactor — code restructuring, no feature or fix
+- ⚡️ perf — performance improvement
+- ✅ test — adding or updating tests
+- 🏗️ build — build system or dependency changes
+- 👷 ci — CI/CD configuration changes
+- 🔧 chore — maintenance tasks, tooling
+- ⏪️ revert — reverting a previous commit
+- 🔒️ security — fixing a security issue
+- 🚀 deploy — deployment related changes
+
+**Rules:**
+- Subject line: max 72 characters, imperative mood ("add" not "added"), no period at end
+- Scope: optional, lowercase, describes the module/area (e.g. karpenter, argocd, vpc)
+- Body: explain why, not what. Wrap at 72 chars.
+- Footer: reference issues if known e.g. \`Closes #123\`
+- Never use past tense — always imperative
+- No filler phrases like "This commit..."
+- Always prefix with the emoji before the type
+
+### Step 4 — Show the commit plan for approval
+
+Present the full commit plan to the user before executing anything. For each commit show:
+
+\`\`\`
+## Commit N — <emoji> <type>(<scope>): <subject>
+
+Files included:
+- <filepath> — <one line summary of what changed in this file>
+
+Commit message:
+<emoji> <type>(<scope>): <subject>
+
+<body if applicable>
+
+<footer if applicable>
+\`\`\`
+
+After showing all commits, ask:
+
+> "Does this commit plan look correct? Should I proceed with committing all changes?"
+
+Wait for explicit approval before proceeding. If the user requests changes, revise and
+show the updated plan again.
+
+### Step 5 — Execute commits
+
+Once approved, execute each commit in order:
+1. \`git add <files in this group>\`
+2. \`git commit -m "<message>"\`
+3. Repeat for each commit group
+
+Do not push yet.
+
+### Step 6 — Show PR description for approval
+
+Generate the PR description using the template below, sourced from both the commit history
+and \`final-plan.md\`.
+
+Show the full PR description to the user and ask:
+
+> "Does this PR description look correct? Should I push and create the PR?"
+
+Wait for explicit approval before pushing or creating the PR.
+
+### Step 7 — Push and create PR
+
+Once approved:
+1. \`git push\` — push all commits to remote
+2. \`gh pr create --title "<title>" --body "<description>"\` — create the PR
+
+Show the PR URL to the user once created.
+
+---
+
+## PR description template
+
+\`\`\`markdown
+## <emoji> Summary
+
+<1-3 sentences. Imperative mood. What changed and why — sourced from the executive summary
+in final-plan.md if available. No filler like "This PR...">
+
+## 📋 Changes
+
+- <change 1>
+- <change 2>
+
+## 🔀 Commits
+
+- \`<hash>\` ✨ feat(scope): subject — <one line annotation>
+
+## 🏗️ Stack Decisions [conditional]
+
+> Include only if the PR introduces or changes a technology or architectural pattern.
+> Omit entirely if not applicable.
+
+- **<technology>**: <why it was chosen over alternatives>
+
+## 🔒 Security Findings [conditional]
+
+> Include only if final-plan.md contains critical or high severity findings.
+> Do not invent findings. Omit this section entirely if absent.
+
+| Severity      | Finding   | Resolution      |
+| ------------- | --------- | --------------- |
+| Critical/High | <finding> | <how addressed> |
+
+## 🔗 References
+
+> Include final-plan.md link only if the file exists. Include issue links if available.
+> Omit section entirely if neither applies.
+
+- 📄 [\`final-plan.md\`](<path in repo>)
+- Closes #<issue>
+\`\`\`
+
+**Rules for filling the template:**
+- Summary from \`final-plan.md\` executive summary if available — do not paraphrase generically
+- Changes list derived from commit groups — one bullet per commit or major concern
+- Commits section uses actual git log hashes after committing
+- Stack Decisions from \`final-plan.md\` only — never invent
+- Security Findings strictly from \`final-plan.md\` critical/high findings — never invent
+- Omit conditional sections entirely if criteria not met — do not write "N/A" or placeholders
+
+---
+
+## Tone rules
+
+- Precise and direct. No fluff.
+- When showing the commit plan, be specific about what each file change does
+- When asking for approval, be clear about what will happen next
+- Never proceed past an approval gate without explicit user confirmation
+
+## Final reminder
+
+Herald is the last step before code reaches the team. Commit messages and PR descriptions
+are permanent. Take the time to get them right. When in doubt about grouping or messaging,
+ask the user before committing.
+`.trim();

package/src/types.ts

@@ -0,0 +1,3 @@
+// ── Types ──────────────────────────────────────────────────────────────────────
+
+export type HeraldMode = "commit" | "pr" | "both";