guardian-framework 0.1.0

package/templates/pi/extensions/snippets.ts

@@ -0,0 +1,201 @@
+/**
+ * Snippets Extension for pi
+ *
+ * Manages reusable prompt fragments (snippets) that can be referenced via
+ * #handle tokens in chat. When the agent or user types #handle, the snippet
+ * body is expanded into an XML block prepended to the message.
+ *
+ * Handles:
+ *   - #handle expansion in user input
+ *   - /snippet list | add | remove | edit commands
+ *   - Persistent storage in guardian-snippets.json
+ */
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+
+interface Snippet {
+	id: string;
+	handle: string;
+	name: string;
+	description: string;
+	content: string;
+}
+
+const SNIPPETS_FILE = "guardian-snippets.json";
+const HANDLE_RE = /^[a-z0-9][a-z0-9-]*$/;
+
+function loadSnippets(cwd: string): Snippet[] {
+	const p = path.join(cwd, SNIPPETS_FILE);
+	if (!fs.existsSync(p)) return [];
+	try {
+		return JSON.parse(fs.readFileSync(p, "utf-8")) as Snippet[];
+	} catch {
+		return [];
+	}
+}
+
+function saveSnippets(cwd: string, snippets: Snippet[]): void {
+	const p = path.join(cwd, SNIPPETS_FILE);
+	const tmp = `${p}.tmp`;
+	fs.writeFileSync(tmp, JSON.stringify(snippets, null, 2), "utf-8");
+	fs.renameSync(tmp, p);
+}
+
+function newSnippetId(): string {
+	return `sn-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 6)}`;
+}
+
+function normalizeHandle(raw: string): string {
+	return raw
+		.trim()
+		.toLowerCase()
+		.replace(/\s+/g, "-")
+		.replace(/[^a-z0-9-]/g, "")
+		.replace(/-+/g, "-")
+		.replace(/^-+|-+$/g, "");
+}
+
+/** Expand #handle tokens in text, returning the body with tokens stripped and snippet XML blocks. */
+function expandSnippetTokens(
+	text: string,
+	snippets: readonly Snippet[],
+): { body: string; blocks: string[] } {
+	const byHandle = new Map(snippets.map((s) => [s.handle, s]));
+	const matched = new Map<string, Snippet>();
+
+	const re = /(^|\s)#([a-z0-9][a-z0-9-]*)\b/gi;
+	const body = text.replace(re, (full, lead: string, raw: string) => {
+		const h = raw.toLowerCase();
+		const snip = byHandle.get(h);
+		if (!snip) return full;
+		matched.set(snip.id, snip);
+		return lead;
+	});
+
+	const blocks = Array.from(matched.values()).map(
+		(s) => `<snippet name="${s.handle}">\n${s.content}\n</snippet>`,
+	);
+	return { body: body.replace(/[ \t]+\n/g, "\n").trim(), blocks };
+}
+
+export default function (pi: ExtensionAPI) {
+	let snippets: Snippet[] = [];
+
+	pi.on("session_start", async (_event, ctx) => {
+		snippets = loadSnippets(ctx.cwd);
+		if (snippets.length > 0) {
+			pi.appendEntry({
+				key: "guardian:snippets",
+				value: snippets.map((s) => `#${s.handle} — ${s.description}`).join("\n"),
+			});
+		}
+	});
+
+	// Intercept input for #handle expansion
+	pi.on("input", async (event, _ctx) => {
+		const input = (event as { input?: string }).input;
+		if (!input) return;
+		const trimmed = input.trim();
+
+		// Only expand #handle tokens (not slash commands)
+		if (
+			!trimmed.startsWith("#") ||
+			(trimmed.startsWith("# ") === false && !trimmed.match(/^#[a-z0-9][a-z0-9-]*/i))
+		)
+			return;
+
+		const { body, blocks } = expandSnippetTokens(input, snippets);
+		if (blocks.length > 0) {
+			event.input = [...blocks, body].join("\n\n");
+		}
+	});
+
+	// Snippet management commands
+	pi.registerCommand("snippet", {
+		description: "Manage snippets: list, add, remove, edit",
+		handler: async (args, ctx) => {
+			snippets = loadSnippets(ctx.cwd); // reload
+			const [subcmd, ...rest] = args;
+
+			if (!subcmd || subcmd === "list") {
+				if (snippets.length === 0) {
+					ctx.ui.notify(
+						"No snippets configured. Use /snippet add <handle> [name] to create one.",
+						"info",
+					);
+				} else {
+					const list = snippets
+						.map((s) => `#${s.handle.padEnd(20)} ${s.name.padEnd(25)} ${s.description}`)
+						.join("\n");
+					ctx.ui.notify(
+						`Snippets (${snippets.length}):\n\nHandle               Name                      Description\n${"─".repeat(72)}\n${list}`,
+						"info",
+					);
+				}
+				return;
+			}
+
+			if (subcmd === "add") {
+				const rawHandle = rest[0];
+				if (!rawHandle) {
+					ctx.ui.notify("Usage: /snippet add <handle> [name]", "error");
+					return;
+				}
+				const handle = normalizeHandle(rawHandle);
+				if (!HANDLE_RE.test(handle)) {
+					ctx.ui.notify(
+						`Invalid handle: "${rawHandle}". Use lowercase letters, numbers, and hyphens.`,
+						"error",
+					);
+					return;
+				}
+				if (snippets.some((s) => s.handle === handle)) {
+					ctx.ui.notify(`Snippet #${handle} already exists. Use /snippet edit to modify.`, "warn");
+					return;
+				}
+				const name = rest.slice(1).join(" ") || handle;
+				const content = await ctx.ui.input(`Content for #${handle}`, "Enter snippet body...");
+				if (!content) return;
+				snippets.push({ id: newSnippetId(), handle, name, description: name, content });
+				saveSnippets(ctx.cwd, snippets);
+				ctx.ui.notify(`Snippet #${handle} created.`, "success");
+				return;
+			}
+
+			if (subcmd === "remove") {
+				const handle = normalizeHandle(rest[0] ?? "");
+				const before = snippets.length;
+				snippets = snippets.filter((s) => s.handle !== handle);
+				if (snippets.length === before) {
+					ctx.ui.notify(`Snippet #${handle} not found.`, "error");
+				} else {
+					saveSnippets(ctx.cwd, snippets);
+					ctx.ui.notify(`Snippet #${handle} removed.`, "success");
+				}
+				return;
+			}
+
+			if (subcmd === "edit") {
+				const handle = normalizeHandle(rest[0] ?? "");
+				const existing = snippets.find((s) => s.handle === handle);
+				if (!existing) {
+					ctx.ui.notify(`Snippet #${handle} not found.`, "error");
+					return;
+				}
+				const content = await ctx.ui.input(`New content for #${handle}`, existing.content);
+				if (!content) return;
+				existing.content = content;
+				saveSnippets(ctx.cwd, snippets);
+				ctx.ui.notify(`Snippet #${handle} updated.`, "success");
+				return;
+			}
+
+			ctx.ui.notify(
+				"Usage: /snippet list | /snippet add <handle> [name] | /snippet remove <handle> | /snippet edit <handle>",
+				"info",
+			);
+		},
+	});
+}

package/templates/pi/extensions/validation-runner.ts

@@ -0,0 +1,100 @@
+/**
+ * Validation Runner Extension for pi
+ *
+ * Runs validation scripts as pi tools and commands.
+ * See coordinator.ts for guardian_scope and guardian_validate tools.
+ */
+
+type ShellResult = {
+	exitCode: number;
+	stdout: string;
+	stderr?: string;
+};
+
+type ExtensionContext = {
+	ui: { notify(message: string, level?: string): void };
+	shell: { execute(command: string, options?: { signal?: AbortSignal }): Promise<ShellResult> };
+	tools: { execute(name: string, params: Record<string, unknown>): Promise<unknown> };
+};
+
+type ExtensionAPI = {
+	on(event: string, handler: (event: unknown, ctx: ExtensionContext) => void | Promise<void>): void;
+	registerTool(options: {
+		name: string;
+		label: string;
+		description: string;
+		parameters: unknown;
+		execute(
+			toolCallId: string,
+			params: Record<string, unknown>,
+			signal: AbortSignal,
+			onUpdate: (update: { type: string; message: string }) => void,
+			ctx: ExtensionContext,
+		): unknown | Promise<unknown>;
+	}): void;
+	registerCommand(
+		name: string,
+		options: {
+			description: string;
+			handler(args: string[], ctx: ExtensionContext): unknown | Promise<unknown>;
+		},
+	): void;
+};
+
+const VALIDATORS = {
+	architecture: ".pi/scripts/validate-architecture.sh",
+	canonical: ".pi/scripts/validate-canonical.sh",
+	ci: ".pi/scripts/validate-ci.sh",
+	integration: ".pi/scripts/validate-integration.sh",
+	operations: ".pi/scripts/validate-operations.sh",
+	security: ".pi/scripts/validate-security.sh",
+	tests: ".pi/scripts/validate-tests.sh",
+} as const;
+
+type ValidatorName = keyof typeof VALIDATORS;
+
+function isValidatorName(value: string): value is ValidatorName {
+	return Object.hasOwn(VALIDATORS, value);
+}
+
+export default function (pi: ExtensionAPI) {
+	// Session initialization
+	pi.on("session_start", async (_event, ctx) => {
+		ctx.ui.notify("Guardian validation runner initialized", "info");
+	});
+
+	// Register validate command — runs scripts directly via shell
+	pi.registerCommand("validate", {
+		description: "Run all or specific validators",
+		handler: async (args, ctx) => {
+			const validators =
+				args.length > 0
+					? args.filter(isValidatorName)
+					: ["ci", "tests", "operations", "security", "canonical"];
+			ctx.ui.notify(`Running validators: ${validators.join(", ")}`, "info");
+
+			const results: Record<string, { passed: boolean; output: string }> = {};
+
+			for (const validator of validators) {
+				const scriptPath = VALIDATORS[validator];
+				try {
+					const result = await ctx.shell.execute(`bash ${scriptPath}`);
+					results[validator] = {
+						passed: result.exitCode === 0,
+						output: result.stdout,
+					};
+				} catch (error) {
+					results[validator] = { passed: false, output: `Error: ${error}` };
+				}
+			}
+
+			const allPassed = Object.values(results).every((r) => r.passed);
+			ctx.ui.notify(
+				allPassed ? "All validations passed" : "Some validations failed",
+				allPassed ? "success" : "error",
+			);
+
+			return { summary: allPassed ? "All validations passed" : "Some validations failed", results };
+		},
+	});
+}

package/templates/pi/github/agents/architecture-coordinator.agent.md

@@ -0,0 +1,27 @@
+---
+description: Turn goals into bounded execution streams with issue order and controls
+model: gpt-5.4
+preflight: scripts/ci/run_preflight.sh
+---
+
+# Architecture Coordinator Agent
+
+**This is a platform wrapper.** Core content in `.pi/agents/architecture-coordinator.md`.
+
+## GitHub Models-Specific Notes
+
+- Use `.github/workflows/01-planning-workflow.md` for detailed step-by-step execution
+- Output validated by `scripts/ci/check_planning_packet.py` and `scripts/ci/validate_agent_output.py`
+- Integrate with preflight engine: `./scripts/ci/run_preflight.sh`
+
+## Execution Flow
+
+1. Read `.pi/agents/architecture-coordinator.md` for role definition
+2. Follow `.github/workflows/01-planning-workflow.md` for step-by-step
+3. Draft the planning packet
+4. Run `python scripts/ci/check_planning_packet.py --input=<packet>`
+5. Hand off to Issue Factory when validated
+
+---
+
+**Token count:** ~30 lines (wrapper only)

package/templates/pi/github/agents/architecture-validator.agent.md

@@ -0,0 +1,20 @@
+---
+description: Validate issue/epic output against architecture policy before merge
+model: gpt-5.4
+preflight: scripts/ci/run_preflight.sh
+---
+
+# architecture validator Agent
+
+**This is a platform wrapper.** Core content in `.pi/agents/architecture-validator.md`.
+
+## GitHub Models-Specific Notes
+
+- Output validated by `scripts/ci/validate_agent_output.py`
+- Integrate with preflight engine: `./scripts/ci/run_preflight.sh`
+
+## Execution Flow
+
+1. Read `.pi/agents/architecture-validator.md` for role definition
+2. Follow the relevant workflow for your execution phase
+3. Run deterministic validation before handing off

package/templates/pi/github/agents/bootstrap-implementer.agent.md

@@ -0,0 +1,20 @@
+---
+description: Execute one issue at a time with strict acceptance-criteria closure
+model: gpt-5.4
+preflight: scripts/ci/run_preflight.sh
+---
+
+# uootstrap implementer Agent
+
+**This is a platform wrapper.** Core content in `.pi/agents/bootstrap-implementer.md`.
+
+## GitHub Models-Specific Notes
+
+- Output validated by `scripts/ci/validate_agent_output.py`
+- Integrate with preflight engine: `./scripts/ci/run_preflight.sh`
+
+## Execution Flow
+
+1. Read `.pi/agents/bootstrap-implementer.md` for role definition
+2. Follow the relevant workflow for your execution phase
+3. Run deterministic validation before handing off

package/templates/pi/github/agents/epic-planner.agent.md

@@ -0,0 +1,70 @@
+---
+name: Epic Planner
+description: Analyzes architecture and creates epic-level plans
+model: gpt-4o
+tools:
+  - view
+  - grep
+  - glob
+  - terminal
+---
+<!--
+Canonical Reference: .pi/github/agents/epic-planner.agent.md
+Blueprint Source: Guardian Framework v1.2
+DO NOT EDIT DIRECTLY - Source: .pi/prompts/epic-plan.md
+-->
+
+# Epic Planner Agent
+
+You analyze architecture and create epic-level implementation plans.
+
+## Workflow
+
+### 1. Architecture Analysis
+
+```bash
+# Read architecture modules
+for f in .pi/architecture/modules/*.md; do cat "$f"; done
+
+# Understand dependencies
+grep "Dependencies" .pi/architecture/modules/*.md
+```
+
+### 2. Epic Slicing Criteria
+
+Slice epics by:
+- **Module boundaries**: One epic per major module change
+- **Dependency order**: Deps must be complete before dependents
+- **Scope estimation**: Files × complexity per issue
+- **Validation requirements**: Complex epics need more validators
+
+### 3. Validator Review
+
+Run validators on epic proposal:
+- Architecture validator: Check alignment
+- Security validator: Check for security implications
+- Operations validator: Check production readiness
+
+### 4. Output Format
+
+```markdown
+## Epic: [EPIC_NAME]
+
+### Architecture Impact
+- Modules affected: [list]
+- New dependencies: [list]
+- Breaking changes: [yes/no]
+
+### Issues
+1. #[issue] - [title] - [scope] - [validators]
+2. #[issue] - [title] - [scope] - [validators]
+
+### Validation Contract
+- Architecture: ✅ Signed
+- Security: ✅ Signed
+- Operations: ✅ Signed
+```
+
+---
+
+*Source: .pi/prompts/epic-plan.md*

package/templates/pi/github/agents/issue-factory.agent.md

@@ -0,0 +1,20 @@
+---
+description: Convert approved planning packets into independently-reviewable issues
+model: gpt-5.4
+preflight: scripts/ci/run_preflight.sh
+---
+
+# issue factory Agent
+
+**This is a platform wrapper.** Core content in `.pi/agents/issue-factory.md`.
+
+## GitHub Models-Specific Notes
+
+- Output validated by `scripts/ci/validate_agent_output.py`
+- Integrate with preflight engine: `./scripts/ci/run_preflight.sh`
+
+## Execution Flow
+
+1. Read `.pi/agents/issue-factory.md` for role definition
+2. Follow the relevant workflow for your execution phase
+3. Run deterministic validation before handing off

package/templates/pi/github/agents/operations-validator.agent.md

@@ -0,0 +1,20 @@
+---
+description: Verify implementations are production-ready with proper observability and runbooks
+model: gpt-5.4
+preflight: scripts/ci/run_preflight.sh
+---
+
+# operations validator Agent
+
+**This is a platform wrapper.** Core content in `.pi/agents/operations-validator.md`.
+
+## GitHub Models-Specific Notes
+
+- Output validated by `scripts/ci/validate_agent_output.py`
+- Integrate with preflight engine: `./scripts/ci/run_preflight.sh`
+
+## Execution Flow
+
+1. Read `.pi/agents/operations-validator.md` for role definition
+2. Follow the relevant workflow for your execution phase
+3. Run deterministic validation before handing off

package/templates/pi/github/agents/security-validator.agent.md

@@ -0,0 +1,20 @@
+---
+description: Verify implementations maintain security controls without regressions
+model: gpt-5.4
+preflight: scripts/ci/run_preflight.sh
+---
+
+# security validator Agent
+
+**This is a platform wrapper.** Core content in `.pi/agents/security-validator.md`.
+
+## GitHub Models-Specific Notes
+
+- Output validated by `scripts/ci/validate_agent_output.py`
+- Integrate with preflight engine: `./scripts/ci/run_preflight.sh`
+
+## Execution Flow
+
+1. Read `.pi/agents/security-validator.md` for role definition
+2. Follow the relevant workflow for your execution phase
+3. Run deterministic validation before handing off

package/templates/pi/github/copilot/settings.json

@@ -0,0 +1,16 @@
+{
+	"$schema": "https://raw.githubusercontent.com/github/copilot-cli/main/schemas/settings.json",
+	"mergeStrategy": "squash",
+	"disabledSkills": [],
+	"extraKnownMarketplaces": [],
+	"customInstructions": {
+		"enabled": true,
+		"paths": [".github/copilot-instructions.md", ".github/instructions/*.instructions.md"]
+	},
+	"agents": {
+		"paths": [".github/agents/*.agent.md"]
+	},
+	"workflows": {
+		"paths": [".github/workflows/*.md"]
+	}
+}

package/templates/pi/github/copilot-instructions.md

@@ -0,0 +1,155 @@
+---
+description: 'Guardian Framework - Token-optimized agentic development workflow'
+applyTo: '**/*'
+---
+<!--
+Canonical Reference: .pi/github/copilot-instructions.md
+Blueprint Source: Guardian Framework v1.2
+Generated: {{GENERATED_TIMESTAMP}}
+DO NOT EDIT DIRECTLY - Modify source in .pi/agent/AGENTS.md
+-->
+
+# {{PROJECT_NAME}} - Guardian Framework Project
+
+**Version:** {{PROJECT_VERSION}}
+**Language:** {{LANGUAGE}}
+**Architecture:** Pi-first with canonical references
+
+---
+
+## Project Overview
+
+[Project description - edit in .pi/agent/AGENTS.md]
+
+---
+
+## Development Commands
+
+### Build
+```bash
+{{BUILD_COMMAND}}
+```
+
+### Test
+```bash
+{{TEST_COMMAND}}
+```
+
+### Lint
+```bash
+{{LINT_COMMAND}}
+```
+
+### Format
+```bash
+{{FORMAT_COMMAND}}
+```
+
+---
+
+## Architecture
+
+This project uses **pi-first architecture** with canonical references:
+
+- `.pi/` is the source of truth
+- `.claude/`, `.opencode/`, `.github/` are generated exports
+- All implementation files reference `.pi/architecture/modules/`
+
+### Key Files to Read
+
+| File | Purpose |
+|------|---------|
+| `.pi/INDEX.md` | Framework quick reference |
+| `.pi/architecture/modules/*.md` | Module architecture docs |
+| `.pi/context/project.md` | Project facts and commands |
+| `.pi/context/patterns.md` | Code templates |
+
+---
+
+## Canonical Reference Requirement
+
+**All implementation files must include architecture reference:**
+
+```typescript
+/**
+ * Canonical Reference: .pi/architecture/modules/[module].md#[section]
+ * Implements: [spec from architecture]
+ * Last Architecture Sync: [check CHANGELOG.md]
+ */
+```
+
+**Before coding:**
+1. Check `.pi/architecture/CHANGELOG.md` for pending changes
+2. Verify architecture module doc for target module
+3. Reference specific section (not just file)
+
+---
+
+## Coding Standards
+
+### Error Handling
+{{ERROR_HANDLING_PATTERN}}
+
+### Logging
+{{TRACING_PATTERN}}
+
+### Cancellation
+{{CANCELLATION_PATTERN}}
+
+### Atomic Writes
+{{ATOMIC_WRITE_PATTERN}}
+
+---
+
+## Validation
+
+Before any commit, ensure:
+
+```bash
+# Run all validators
+bash .pi/scripts/validate-ci.sh
+bash .pi/scripts/validate-canonical.sh
+
+# For moderate+ scope, also run:
+bash .pi/scripts/validate-architecture.sh
+
+# For complex+ scope, also run:
+bash .pi/scripts/validate-security.sh
+```
+
+---
+
+## Workflows
+
+| Command | Purpose |
+|---------|---------|
+| `/epic-plan` | Architecture analysis + epic slicing |
+| `/blueprint-validate` | Validate .pi/ integrity |
+| `/sync-check` | Verify exports match blueprint |
+| `/issue-closeout` | Validate + create compliance MR |
+
+---
+
+## Repository Tool
+
+Using: **{{REPOTOOL}}**
+
+| Tool | Commands |
+|------|----------|
+| `gh` | `gh issue create`, `gh pr create`, `gh pr merge` |
+| `glab` | `glab issue create`, `glab mr create`, `glab mr merge` |
+
+---
+
+## Quality Gates
+
+- [ ] Build succeeds
+- [ ] Tests pass
+- [ ] Lint clean
+- [ ] Canonical references ≥50% coverage
+- [ ] Architecture CHANGELOG checked
+
+---
+
+*Framework version: 1.2.0*
+*Generated by guardian-framework*