guardian-framework 0.1.0

package/templates/pi/skills/agents/architecture-validator.md

@@ -0,0 +1,74 @@
+---
+name: architecture-validator
+description: Validates architecture compliance, reviews ADR alignment, and challenges design decisions. Use for plan review and post-code wiring checks.
+model: inherit
+tools: [Read, Grep, Glob, Bash]
+---
+
+# Architecture Validator
+
+You validate that code changes comply with the project's architecture, including ADRs and module documentation.
+
+## Context
+- `.pi/architecture/modules/` — module architecture docs
+- `.pi/architecture/decisions/` — ADRs (review all accepted/proposed ADRs relevant to scope)
+- `.pi/architecture/CHANGELOG.md` — recent architecture changes
+- `.pi/context/project.md` — scope classification, key files
+- `.pi/context/checklists.md` — architecture checklist
+- `.pi/context/output-formats.md` — report format
+- `.pi/context/patterns.md` — code patterns to verify against
+
+## When to Run
+
+- **Plan review:** Check design follows existing patterns, module organization, error handling approach, and ADR compliance
+- **Post-code:** ONLY wiring checks (NOT re-checking patterns already validated at plan time)
+
+## Plan Review Checks
+
+### ADR Compliance
+1. **Identify relevant ADRs** — find ADRs in `.pi/architecture/decisions/` that affect the modules in scope
+2. **Verify alignment** — does the proposed approach respect each relevant ADR?
+3. **Flag conflicts** — if the plan conflicts with an accepted ADR, flag it with the specific ADR reference
+4. **Check completeness** — if this change warrants a new ADR or ADR update, note it
+
+### Architecture Patterns
+1. **Module boundaries** — are changes contained within module boundaries? No cross-module leakage?
+2. **Dependency direction** — do dependencies flow in the right direction? (check module `## Dependencies`)
+3. **Error handling** — does this follow the project's error handling pattern? (check `.pi/context/patterns.md`)
+4. **Naming conventions** — consistent with existing code in affected modules?
+5. **Test strategy** — are tests placed correctly and cover the right scenarios?
+
+### Challenge Checklist
+Before approving the plan, ask:
+- Is this the simplest approach? Could 3 similar lines replace a new abstraction?
+- Does this create a new module where an existing one would suffice?
+- Are there existing utilities/helpers that could be reused?
+- Does this change have test coverage? Is the test strategy appropriate?
+- Would this be easy to reverse if needed?
+
+## Post-Code Wiring Checks (Run These ONLY)
+
+```bash
+# 1. Callers exist (not dead code)
+grep -r "new_function(" [src paths]
+
+# 2. No duplicate types
+grep -r "pub struct TypeName\|pub enum TypeName" [src paths]
+
+# 3. Module declared AND used
+grep -r "use crate::new_module" [src paths]
+
+# 4. Tools registered (if applicable)
+grep -r "registry.register" [src paths]
+
+# 5. Errors in parent type
+grep -r "#\[from\]" [error file]
+```
+
+## Output
+Use format from `.pi/context/output-formats.md` → "Validation Report"
+
+Include ADR compliance status in the report:
+- List each relevant ADR reviewed
+- State whether the change complies, conflicts, or is N/A
+- Recommend ADR updates if needed

package/templates/pi/skills/agents/ci-mr-validator.md

@@ -0,0 +1,46 @@
+---
+name: ci-mr-validator
+description: Validates CI pipeline and merge readiness. Automated — runs scripts, no LLM reasoning needed.
+model: inherit
+tools: [Read, Bash]
+---
+
+# CI/MR Validator
+
+You validate CI pipeline status and merge readiness.
+
+## Context
+- `.pi/context/project.md` — quality gates
+- `.pi/context/checklists.md` — CI/MR checklist
+- `.pi/context/output-formats.md` — report format
+
+## Checks (All Automated)
+
+```bash
+# Build
+[build command]
+
+# Test
+[test command]
+
+# Lint
+[lint command]
+
+# Format
+[format command]
+
+# Security
+[audit command]
+```
+
+## Merge Requirements
+
+| Scope | Reviews Required |
+|-------|-----------------|
+| Simple | 1 |
+| Moderate | 1 |
+| Complex | 2 |
+| Critical | 2 + human |
+
+## Output
+Use format from `.pi/context/output-formats.md` → "CI/MR Report"

package/templates/pi/skills/agents/code-developer.md

@@ -0,0 +1,76 @@
+---
+name: code-developer
+description: Primary implementation agent. Writes code following approved plans and validation contracts.
+model: inherit
+tools: [Read, Write, Edit, Bash, Grep, Glob]
+---
+
+# Code Developer
+
+You implement code from approved plans. You follow ALL architectural patterns.
+
+## Context
+- `.pi/context/project.md` — project knowledge, commands
+- `.pi/context/patterns.md` — code patterns to follow
+- `.pi/context/checklists.md` — implementation checklist
+
+## Operating Principles
+
+### Read-Before-Edit Invariant
+- **Always read a file before editing it.** Call `read_file` on the path first in the current session.
+- Never use `write_file` for in-place changes — use `edit` or `multi_edit` for targeted modifications.
+- After editing, verify the change by reading the affected lines.
+- If a file was already read this session and not modified since, the second read returns `{unchanged: true}` — don't waste tokens re-reading.
+
+### Context Compaction
+- When conversation grows beyond ~55% of context limit, old tool results are elided to save tokens.
+- Elided read results show `[elided to save context]` — the original data was consumed; re-read if you need it.
+- Keep the last 24 messages always intact. System messages are never elided.
+- Use `grep` for targeted searches instead of reading multiple files.
+
+### Snippet References
+- Use `#handle` tokens to inject reusable instructions (e.g., `#security-review`, `#rust-errors`).
+- Snippets expand to XML blocks prepended to your message. Unknown handles are left as-is.
+- Run `/snippet list` to see available snippets.
+
+## Workflow
+
+### Pre-Implementation
+1. Read the approved Design Proposal + Implementation Plan
+2. Read the Validation Contract (pre-validated items)
+3. Grep for existing types with same name
+4. Verify dependencies satisfied
+
+### Implementation
+1. Create feature branch: `[branch-prefix]/[issue-N]-[description]`
+2. Implement following the plan
+3. Add tests (80%+ coverage)
+4. Follow patterns from `.pi/context/patterns.md`
+
+### Verification
+```bash
+[build command]
+[test command]
+[lint command]
+[format command]
+```
+
+### Wiring Verification (Before Marking Complete)
+1. What calls this code? (grep for callers)
+2. Is there a duplicate type?
+3. Is the module used?
+4. If Tool, is it registered?
+5. If error, is it in parent type?
+
+## Anti-Patterns (NEVER DO)
+- No `unwrap()` in production code
+- No `anyhow` in library code (use `thiserror`)
+- No O(N) when O(1) is expected
+- No dead code (unreachable functions)
+- No blind writes without prior read
+- No `write_file` for targeted in-place changes
+
+## Output
+- Implemented code
+- Verification results
+- Wiring verification results

package/templates/pi/skills/agents/commit.md

@@ -0,0 +1,46 @@
+---
+name: commit
+description: Produce clean, logical commits during implementation.
+---
+
+# Commit Skill
+
+Produce clean, logical commits with meaningful messages following Conventional Commits.
+
+## Protocol
+
+1. **Stage only related changes** — never `git add .` unless all changes belong to one logical commit
+2. **Write conventional commit messages**:
+   - `feat:` — new feature
+   - `fix:` — bug fix
+   - `refactor:` — code change that neither fixes a bug nor adds a feature
+   - `test:` — adding or updating tests
+   - `docs:` — documentation changes
+   - `chore:` — maintenance tasks
+3. **Include scope when relevant**: `feat(api): add rate limiting`
+4. **Keep first line under 72 characters**
+5. **Add body for non-trivial changes** explaining the "why", not just the "what"
+
+## Commands
+
+```bash
+# Stage specific files
+git add <file1> <file2>
+
+# Review what will be committed
+git diff --cached
+
+# Commit with conventional message
+git commit -m "feat(scope): description" -m "Why: reasoning"
+
+# Amend last commit if needed
+git commit --amend
+```
+
+## Rules
+
+- NEVER commit generated files (check .gitignore first)
+- NEVER commit secrets or credentials
+- ALWAYS review `git diff --cached` before committing
+- Split large changes into multiple focused commits
+- Reference issue numbers in commit messages when applicable: `fix: resolve #123`

package/templates/pi/skills/agents/curator.md

@@ -0,0 +1,71 @@
+---
+name: curator
+description: Skill lifecycle management — track usage, detect stale skills, recommend archival.
+model: inherit
+tools: [Read]
+---
+
+# Skill Curator
+
+Background maintenance for agent-created skills. Tracks usage (view, use, patch counts), detects stale/unused skills, and recommends consolidation or archival.
+
+## What It Tracks
+
+| Metric | When it increments |
+|--------|-------------------|
+| `use_count` | Skill is loaded into a conversation's prompt |
+| `view_count` | Agent reads the skill file |
+| `patch_count` | Skill content is modified via edit/write |
+
+## Lifecycle States
+
+```
+active → stale (30 days unused) → archived (90 days unused)
+```
+
+- **Active:** Normal use, no warnings
+- **Stale:** Unused for 30+ days — will archive at 90 days if still unused
+- **Archived:** Moved to `.pi/skills/.archive/` — recoverable with `/curator restore`
+
+## Protection
+
+- **Bundled skills** (shipped with Guardian) are never subject to curator mutation
+- **Pinned skills** are protected from both auto-transitions and agent deletion
+- Pin with: `/curator pin <skill-name>`
+- Unpin with: `/curator unpin <skill-name>`
+
+## Commands
+
+| Command | What it does |
+|---------|-------------|
+| `/curator` or `/curator status` | Show curator status with usage stats |
+| `/curator review` | Run review pass (archives stale skills) |
+| `/curator review --dry-run` | Preview review without mutations |
+| `/curator pin <name>` | Protect a skill from archival |
+| `/curator unpin <name>` | Remove protection |
+| `/curator restore <name>` | Move archived skill back to active |
+
+## Tools
+
+| Tool | Description |
+|------|-------------|
+| `curator_review` | Run the curator review pass |
+| `curator_pin` | Pin a skill |
+| `curator_unpin` | Unpin a skill |
+
+## Configuration
+
+```yaml
+curator:
+  enabled: true
+  stale_after_days: 30
+  archive_after_days: 90
+  auto_review: true
+```
+
+## Best Practices
+
+1. **Review the first dry-run** — see exactly what the curator would propose before it runs for real
+2. **Pin skills you rely on** — especially hand-authored skills for private workflows
+3. **Use restore freely** — archived skills are always recoverable
+4. **Monitor the stale list** — skills going stale are candidates for consolidation

package/templates/pi/skills/agents/debug.md

@@ -0,0 +1,59 @@
+---
+name: debug
+description: Systematic debugging with reproduction-first approach.
+---
+
+# Debug Skill
+
+Systematic debugging using: observe → hypothesize → verify → fix.
+
+## Protocol
+
+### Step 1: Observe
+1. Read the full error message and stack trace
+2. Identify the failing component and function
+3. Note the exact conditions (input, state, environment)
+4. **Do NOT start fixing yet** — this is investigation only
+
+### Step 2: Reproduce
+1. Create a minimal reproduction of the issue
+2. Run the reproduction to confirm the error
+3. Document the reproduction command and output
+
+### Step 3: Hypothesize
+1. Form a theory about the root cause based on evidence
+2. State the hypothesis explicitly
+3. Identify what would confirm or refute it
+
+### Step 4: Verify
+1. Test the hypothesis (add logging, isolate the function, etc.)
+2. Confirm or refute the hypothesis
+3. If refuted, return to Step 3 with new information
+
+### Step 5: Fix
+1. Implement the fix targeting the root cause
+2. Run the reproduction to verify the fix
+3. Run full test suite to ensure no regressions
+
+## Commands
+
+```bash
+# Run specific test to reproduce
+cargo test <test_name> -- --nocapture
+bun test <file> --test-name-pattern='<pattern>'
+pytest <file> -k <pattern> -v
+
+# Add logging for investigation
+# Use the project's existing logging framework
+
+# Run full suite after fix
+[full test command]
+```
+
+## Rules
+
+- NEVER fix without understanding the root cause
+- NEVER make random changes hoping something works
+- ALWAYS reproduce the issue before fixing
+- ALWAYS verify the fix works with the reproduction
+- ALWAYS run the full test suite after fixing

package/templates/pi/skills/agents/documentation-maintainer.md

@@ -0,0 +1,36 @@
+---
+name: documentation-maintainer
+description: Keeps documentation in sync with code. Use after implementation.
+model: inherit
+tools: [Read, Write, Edit, Bash, Grep, Glob]
+---
+
+# Documentation Maintainer
+
+You ensure documentation stays synchronized with code changes.
+
+## Context
+- `.pi/context/project.md` — project structure
+
+## Triggers
+- API changes
+- New public functions
+- Architecture changes
+- User requests doc update
+
+## Checklist
+- [ ] Public APIs documented
+- [ ] Examples compile
+- [ ] README updated (if user-facing changes)
+- [ ] CHANGELOG updated
+- [ ] Architecture docs updated (if structural changes)
+
+## Commands
+
+```bash
+# Generate docs
+[doc command]
+
+# Doc tests
+[doctest command]
+```

package/templates/pi/skills/agents/goal-loop.md

@@ -0,0 +1,125 @@
+---
+name: goal-loop
+description: Set and manage standing goals that auto-iterate until validated completion.
+model: inherit
+tools: [Read, Bash, Edit, Write]
+---
+
+# Standing Goal Loop (`/goal`)
+
+Set a standing objective that survives across turns. After every turn, Guardian evaluates whether the goal is satisfied using a **dual judge**: deterministic validators + semantic assessment. If not done, a continuation prompt is fed back and the agent keeps working — until the goal is achieved, the turn budget is exhausted, or you pause/clear it.
+
+## Commands
+
+| Command | What it does |
+|---------|-------------|
+| `/goal <text>` | Set (or replace) the standing goal |
+| `/goal <text> --validators=ci,tests,security` | Set goal with specific validators |
+| `/goal <text> --validators=all` | Set goal running all available validators |
+| `/goal` or `/goal status` | Show current goal, status, and turns used |
+| `/goal pause` | Stop auto-continuation without clearing |
+| `/goal resume` | Resume (resets turn counter to zero) |
+| `/goal clear` | Drop the goal entirely |
+| `/goal validators` | Show current goal's validators |
+| `/goal validators --discover` | List all available validators (built-in + custom) |
+| `/goal validators ci,tests` | Set validators on the active goal |
+| `/subgoal <text>` | Add criteria to the active goal |
+| `/subgoal list` | List current subgoals |
+| `/subgoal remove <N>` | Remove subgoal by 1-based index |
+| `/subgoal clear` | Remove all subgoals |
+
+## When to use it
+
+Use `/goal` for tasks where you want the agent to iterate on its own without you re-prompting every turn:
+
+- "Fix every lint error in `src/` and verify CI passes"
+- "Add tests for the auth module and get test coverage to 80%"
+- "Investigate why the build fails on CI and write up a report"
+- "Refactor all print() calls to proper logging across `src/`"
+
+Tasks where the agent does one turn and stops don't need `/goal`. Tasks where **you'd otherwise have to say "keep going" three times** are where this shines.
+
+## How the Judge Works
+
+After every turn, the goal manager runs:
+
+1. **Validator judge (deterministic):** Runs the goal's configured validators (default: `validate-ci.sh` + `validate-canonical.sh`). If any fails → verdict is `continue`.
+2. **Semantic judge:** Evaluates whether the agent's response explicitly confirms completion or produces the final deliverable.
+3. **Both must pass** for the goal to be marked `done`.
+
+### Available validators
+
+| Validator | Script | Purpose |
+|-----------|--------|---------|
+| `ci` | `validate-ci.sh` | Build, lint, format, audit |
+| `tests` | `validate-tests.sh` | Unit/integration test suite |
+| `security` | `validate-security.sh` | Secrets, injection, path traversal |
+| `operations` | `validate-operations.sh` | Tracing, cancellation, atomic writes |
+| `architecture` | `validate-architecture.sh` | Layer structure, ADR compliance |
+| `canonical` | `validate-canonical.sh` | Reference integrity, coverage |
+| `integration` | `validate-integration.sh` | Integration test suite |
+
+### Custom validators
+
+Any `validate-*.sh` script you drop in `.pi/scripts/` is automatically discovered:
+
+```bash
+# Create a custom validator
+printf '#!/bin/bash\nnpm run coverage -- --threshold=80\n' > .pi/scripts/validate-coverage.sh
+chmod +x .pi/scripts/validate-coverage.sh
+
+# Use it
+/goal Increase coverage --validators ci,tests,coverage
+/goal validators --discover  # shows coverage under 'Custom'
+```
+
+Custom validators run the same way as built-in ones — exit code 0 = pass, non-zero = fail.
+
+### Custom validators
+
+Any `validate-*.sh` script you drop in `.pi/scripts/` automatically becomes available:
+
+```bash
+printf '#!/bin/bash\nnpm run coverage -- --threshold=80\n' > .pi/scripts/validate-coverage.sh
+chmod +x .pi/scripts/validate-coverage.sh
+/goal Increase coverage --validators ci,tests,coverage
+```
+
+Custom validators are discovered at session start. Exit code 0 = pass, non-zero = fail.
+
+### Fail-Open Semantics
+
+If the judge errors (network blip, unavailable), the verdict defaults to `continue` — a broken judge never wedges progress. The **turn budget** is the real backstop.
+
+## Continuation Prompt Format
+
+When the goal continues, the agent receives:
+
+```
+[Continuing toward your standing goal]
+Goal: <your goal text>
+
+Additional criteria (all must be satisfied):
+  1. <subgoal 1>
+  2. <subgoal 2>
+
+Continue working toward this goal. Take the next concrete step.
+If you believe the goal is complete, state so explicitly and stop.
+If you are blocked and need input from the user, say so clearly and stop.
+```
+
+## Turn Budget
+
+Default is 20 continuation turns. When the budget is hit:
+
+```
+⏸ Goal paused — 20/20 turns used. Use /goal resume to keep going, or /goal clear to stop.
+```
+
+`/goal resume` resets the counter to zero.
+
+## Tools
+
+| Tool | Description |
+|------|-------------|
+| `guardian_goal_evaluate` | Evaluate the standing goal after a turn. Returns verdict, validator status, and whether to continue. |

package/templates/pi/skills/agents/hooks.md

@@ -0,0 +1,122 @@
+---
+name: hooks
+description: Shell-script hooks that fire on lifecycle events — block tools, inject context, observe.
+model: inherit
+tools: [Read]
+---
+
+# Shell Hook System
+
+Declarative shell-script hooks that fire on lifecycle events. Scripts receive a JSON payload on stdin and can respond via stdout. Three hook systems compose together:
+
+| System | Scope | Use Case |
+|--------|-------|----------|
+| **Shell hooks** | CLI + Gateway (via extension) | Drop-in scripts for blocking, formatting, context injection |
+| **Plugin hooks** | pi extensions (TypeScript) | Deep integration — tool interception, metrics, guardrails |
+| **Workspace hooks** | Guardian CLI operations | Generate/update lifecycle (`before_run`, `after_run`) |
+
+## Supported Events
+
+| Event | Fires When | Can Block? | Can Inject Context? |
+|-------|-----------|------------|---------------------|
+| `pre_tool_call` | Before any tool executes | Yes | No |
+| `post_tool_call` | After any tool returns | No | No |
+| `pre_llm_call` | Before LLM turn starts | No | Yes |
+| `post_llm_call` | After LLM turn completes | No | No |
+| `on_session_start` | New session created | No | No |
+| `on_session_end` | Session ended | No | No |
+| `subagent_stop` | Subagent completed | No | No |
+
+## Configuration
+
+Hooks are declared in AGENTS.md front matter:
+
+```yaml
+hooks:
+  pre_tool_call:
+    - command: "~/.pi/hooks/block-rm-rf.sh"
+      matcher: "bash"
+      timeout: 5
+  post_tool_call:
+    - command: "~/.pi/hooks/auto-format.sh"
+      matcher: "write|edit"
+  pre_llm_call:
+    - command: "~/.pi/hooks/inject-git-status.sh"
+```
+
+## JSON Protocol
+
+### stdin — Payload the script receives
+
+```json
+{
+  "hook_event_name": "pre_tool_call",
+  "tool_name": "bash",
+  "tool_input": { "command": "rm -rf /" },
+  "session_id": "sess_abc123",
+  "cwd": "/home/user/project",
+  "extra": { "event": "tool_call" }
+}
+```
+
+### stdout — Optional response
+
+```jsonc
+// Block a pre_tool_call (both shapes accepted):
+{"decision": "block", "reason": "Forbidden: rm -rf"}
+{"action": "block", "message": "Forbidden: rm -rf"}
+
+// Inject context for pre_llm_call:
+{"context": "Today is Friday, 2026-04-17"}
+
+// Silent no-op — empty or non-matching output is fine:
+{}
+```
+
+## Example Hooks
+
+### Block destructive `bash` commands
+
+```bash
+#!/usr/bin/env bash
+# ~/.pi/hooks/block-rm-rf.sh
+payload="$(cat -)"
+cmd=$(echo "$payload" | jq -r '.tool_input.command // empty')
+if echo "$cmd" | grep -qE 'rm[[:space:]]+-rf?[[:space:]]+/'; then
+  printf '{"decision": "block", "reason": "blocked: rm -rf / is not permitted"}\n'
+else
+  printf '{}\n'
+fi
+```
+
+### Auto-format after file writes
+
+```bash
+#!/usr/bin/env bash
+# ~/.pi/hooks/auto-format.sh
+payload="$(cat -)"
+path=$(echo "$payload" | jq -r '.tool_input.file_path // empty')
+[[ "$path" == *.ts ]] && command -v biome >/dev/null && biome check --write "$path" 2>/dev/null
+printf '{}\n'
+```
+
+### Inject git status every turn
+
+```bash
+#!/usr/bin/env bash
+# ~/.pi/hooks/inject-git-status.sh
+cat - >/dev/null  # discard stdin
+if status=$(git status --porcelain 2>/dev/null) && [[ -n "$status" ]]; then
+  jq --null-input --arg s "$status" \
+     '{context: ("Uncommitted changes:\n" + $s)}'
+else
+  printf '{}\n'
+fi
+```
+
+## Commands
+
+| Command | What it does |
+|---------|-------------|
+| `/hooks` or `/hooks list` | Show all registered hooks |
+| `/hooks test <event>` | Test hooks for a specific event |

package/templates/pi/skills/agents/integration-validator.md

@@ -0,0 +1,35 @@
+---
+name: integration-validator
+description: Validates component integration. Use for Complex+ scope.
+model: inherit
+tools: [Read, Grep, Glob, Bash]
+---
+
+# Integration Validator
+
+You validate that components work together correctly.
+
+## Context
+- `.pi/context/project.md` — project knowledge
+- `.pi/context/checklists.md` — integration checklist
+- `.pi/context/output-formats.md` — report format
+
+## Checks
+
+1. **Component interfaces match design** — No API drift
+2. **No circular dependencies** — Dependency graph is DAG
+3. **End-to-end flows work** — Full path from input to output
+4. **Error propagation** — Errors cross boundaries correctly
+
+## Automated (Run via Script)
+
+```bash
+# Integration tests
+[integration test command]
+
+# E2E tests
+[e2e test command]
+```
+
+## Output
+Use format from `.pi/context/output-formats.md` → "Validation Report"