guardian-framework 0.1.0

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

@@ -0,0 +1,85 @@
+---
+name: security-validator
+description: Security review skill. Scans code for injection, auth bypass, secret leakage, unsafe deserialization, weak crypto.
+model: inherit
+tools: [Read, Grep, Glob, Bash]
+---
+
+# Security Validator
+
+Audits code and configuration for security risks.
+
+## Scope
+
+Scan for the following categories:
+
+### 1. Injection Vulnerabilities
+- **SQL injection:** String concatenation in queries, parameterized queries missing
+- **Shell injection:** User input in `exec()`, `system()`, backticks, `${}` without quoting
+- **Path traversal:** `..` in file paths, symlink following, missing path canonicalization
+- **Template injection:** Unescaped user input in HTML/JS templates
+
+### 2. Authentication / Authorization
+- Missing auth checks on sensitive endpoints
+- Hardcoded credentials or API keys
+- Weak password requirements
+- Missing CSRF protection
+- Broken access control (IDOR)
+
+### 3. Secret Leakage
+- Secrets in source code (`.env` files, config files, comments)
+- API keys in client-side code
+- Private keys, certificates in repo
+- Debug/logging of sensitive data (tokens, passwords, PII)
+
+### 4. Unsafe Operations
+- Unsafe deserialization (eval, pickle, yaml.load, JSON.parse with reviver)
+- Weak cryptographic algorithms (MD5, SHA1, DES, ECB mode)
+- Missing certificate validation (TLS skip verify)
+- Insecure random number generation
+
+### 5. Data Handling
+- Missing input validation at trust boundaries
+- XSS via unescaped output
+- Missing Content-Security-Policy headers
+- Sensitive data in URLs or logs
+
+## Tool Restrictions
+
+This validator operates in **read-only** mode. It may:
+- Read files
+- Grep for patterns
+- List directories
+- Run non-mutating commands (e.g., `npm audit`, `cargo audit`)
+
+It must NOT:
+- Write or modify files
+- Execute destructive commands
+- Spawn subagents
+
+## Output Format
+
+For each finding, report:
+
+```
+[CRITICAL/HIGH/MEDIUM/LOW] file:line — issue → recommended fix
+```
+
+Example:
+```
+[CRITICAL] src/auth.ts:42 — hardcoded JWT secret → move to environment variable or secrets manager
+[HIGH] src/api/users.rs:118 — SQL injection via string concat → use parameterized query
+[MEDIUM] config/deploy.yml:7 — AWS key in plaintext → use IAM roles or vault
+[LOW] src/logger.ts:33 — logging request headers (may contain tokens) → redact Authorization header
+```
+
+If no issues are found, report: **"No security issues found."**
+
+## Priority Rules
+
+- **CRITICAL:** Exploitable now, affects production
+- **HIGH:** Exploitable with effort, likely in production
+- **MEDIUM:** Defense-in-depth weakness, may be exploitable
+- **LOW:** Best practice violation, unlikely to be directly exploitable
+
+Do NOT report style/formatting issues. Do NOT propose unrelated cleanups.

package/templates/pi/skills/agents/session-persistence.md

@@ -0,0 +1,119 @@
+---
+name: session-persistence
+description: Structured session lifecycle with lazy-loaded message history, auto-derived titles, and per-session state isolation.
+model: inherit
+tools: [Read]
+---
+
+# Session Persistence
+
+Sessions provide structured conversation lifecycle with lazy loading, auto-titling, and per-session state isolation.
+
+## Session Storage Format
+
+```json
+{
+  "sessions": [
+    {
+      "id": "s-1a2b3c-x7y8z9",
+      "title": "Fix auth token refresh bug",
+      "createdAt": 1714000000000,
+      "updatedAt": 1714003600000
+    }
+  ],
+  "activeId": "s-1a2b3c-x7y8z9"
+}
+```
+
+### Per-Session Messages
+
+Messages stored under key `messages:{sessionId}`:
+```json
+{
+  "messages:s-1a2b3c-x7y8z9": [
+    { "role": "user", "parts": [...] },
+    { "role": "assistant", "parts": [...] }
+  ]
+}
+```
+
+## Session ID Format
+
+```
+s-{timestamp-base36}-{random-base36}
+```
+
+Example: `s-m5x7k2-a3b9c1`
+
+## Auto-Derived Titles
+
+Title is derived from the **first user message**, stripped of:
+- Terminal context blocks
+- Selection blocks
+- File content blocks
+- Truncated to 40 characters with ellipsis
+
+## Lazy Loading
+
+- **Boot:** Load only session list + active ID (single IPC roundtrip)
+- **Open:** Load messages for the opened session on-demand
+- **Memory:** Keep active session messages in a Map; hydrate others on switch
+
+## Per-Session State
+
+Each session maintains isolated state:
+- **Todos:** Task list with progress tracking (`todos:{sessionId}`)
+- **Shell session:** Persistent shell with cwd survival
+- **Read cache:** File content cache invalidated per mutation
+- **Agent metadata:** Current step, usage stats, model info
+
+## Session Switching
+
+When switching sessions:
+1. Save current session messages
+2. Load target session messages from store
+3. Clear read cache (files may have changed)
+4. Restore per-session todos
+5. Update active session ID
+
+## Auto-Save
+
+Messages are saved to disk on every assistant turn completion.
+Auto-save interval: 200ms debounce.
+
+## Session Lifecycle
+
+```
+Create → Open → Interact (auto-save) → Switch (save + load) → ... → Delete
+```
+
+## Storage Keys
+
+| Key | Content |
+|-----|---------|
+| `sessions` | Array of SessionMeta |
+| `activeId` | Current session ID |
+| `messages:{id}` | Message array for session |
+| `todos:{id}` | Todo array for session |
+
+## Title Derivation Algorithm
+
+```typescript
+function deriveTitle(messages): string {
+  for (const m of messages) {
+    if (m.role !== "user") continue;
+    const text = m.parts
+      .filter(p => p.type === "text")
+      .map(p => p.text)
+      .join(" ")
+      .replace(/<terminal-context[\s\S]*?<\/terminal-context>/g, "")
+      .replace(/<selection[\s\S]*?<\/selection>/g, "")
+      .replace(/<file[\s\S]*?<\/file>/g, "")
+      .trim();
+    if (!text) continue;
+    const first = text.split("\n")[0].trim();
+    return first.length > 40 ? `${first.slice(0, 40)}…` : first;
+  }
+  return "New chat";
+}
+```

package/templates/pi/skills/agents/slash-commands.md

@@ -0,0 +1,117 @@
+---
+name: slash-commands
+description: Slash command interception system for plan mode, workspace initialization, and prompt template injection.
+model: inherit
+tools: [Read]
+---
+
+# Slash Commands
+
+Slash commands intercept user input starting with `/` (or `#` for snippet references) and transform them into structured actions before sending to the agent.
+
+## Command Outcomes
+
+| Outcome | Behavior |
+|---------|----------|
+| `handled` | Command ran; do NOT send a chat message |
+| `send-prompt` | Replace user text with a template prompt, then send |
+| `none` | Not a slash command; send as normal chat message |
+
+## Built-in Commands
+
+### /init — Initialize Workspace
+
+**Outcome:** `send-prompt`
+
+Sends a workspace scanning prompt that instructs the agent to:
+1. Explore the codebase structure
+2. Read key files (package.json, Cargo.toml, etc.)
+3. Identify build/test/lint commands
+4. Produce `TERAX.md` / project memory file at workspace root
+
+**Prompt Template:**
+```
+Scan this workspace and produce a project memory file with:
+- One-paragraph project description
+- Build / test / dev commands
+- Architecture overview (subsystems, data flow, key dirs)
+- Conventions worth knowing
+- Paths to entry points
+Cap under 200 lines.
+```
+
+### /plan — Plan Mode Toggle
+
+**Outcome:** `handled`
+
+Toggles plan mode on/off:
+- `/plan` or `/plan on` → Enable plan mode
+- `/plan off` or `/plan exit` → Disable plan mode
+
+### /validate — Run Validators
+
+**Outcome:** `send-prompt`
+
+Sends a validation prompt instructing the agent to run all configured validators.
+
+### /scope — Classify Task Scope
+
+**Outcome:** `send-prompt`
+
+Sends a scope classification prompt to determine required validators.
+
+## Command Format
+
+```
+/<command> [arguments]
+
+Examples:
+/plan on
+/plan off
+/init
+/validate all
+/scope implement auth module with OAuth2
+```
+
+## Command Marker Protocol
+
+Commands are wrapped in XML markers for agent processing:
+
+```xml
+<terax-command name="init" />
+
+[expanded prompt follows]
+```
+
+This allows the agent to recognize the command context in the conversation.
+
+## Extending Commands
+
+Add new commands by registering in the command registry:
+
+```typescript
+interface SlashCommand {
+  name: string;           // Command name
+  invocation: string;     // "/command"
+  label: string;          // Display label
+  icon: IconComponent;    // UI icon
+  handler: (args: string) => SlashOutcome;
+}
+```
+
+## Snippet References (#handle)
+
+Input starting with `#` that matches a known snippet handle is treated as a snippet expansion:
+
+```
+#security-review — check the auth module
+```
+
+Expands to:
+```
+<snippet name="security-review">
+[security review instructions]
+</snippet>
+
+check the auth module
+```

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

@@ -0,0 +1,99 @@
+---
+name: snippets
+description: Reusable prompt fragments injected via #handle tokens. Compressed skill loading for on-demand context injection without full file reads.
+model: inherit
+tools: [Read]
+---
+
+# Snippets System
+
+Snippets are reusable prompt fragments referenced by `#handle` tokens in chat. When the agent (or user) types `#handle`, the snippet body is expanded into an XML block and prepended to the message.
+
+## Handle Format
+
+- **Syntax:** `#handle` — lowercase alphanumeric with hyphens
+- **Pattern:** `^[a-z0-9][a-z0-9-]*$`
+- **Examples:** `#security-review`, `#rust-error-handling`, `#api-conventions`
+
+## Expansion
+
+`#handle` tokens are replaced with:
+
+```xml
+<snippet name="handle">
+[snippet content]
+</snippet>
+```
+
+Multiple handles expand to multiple `<snippet>` blocks, prepended to the user message. Unknown handles are left as-is (no error).
+
+## Snippet Structure
+
+```typescript
+interface Snippet {
+  id: string;            // Unique ID: sn-{timestamp}-{random}
+  handle: string;        // The #handle used to reference it
+  name: string;          // Human-readable name
+  description: string;   // One-line description shown in autocomplete
+  content: string;       // The snippet body (injected as XML)
+}
+```
+
+## Use Cases
+
+### 1. Skill Quick-Load
+
+Instead of loading a full skill file, reference a snippet:
+
+```
+#security-review — check the auth module for vulnerabilities
+```
+
+### 2. Code Patterns
+
+```
+#rust-result-types — use Result<T, E> with thiserror, never unwrap()
+```
+
+### 3. Project Conventions
+
+```
+#naming-conventions — use snake_case for functions, PascalCase for types
+```
+
+### 4. Common Instructions
+
+```
+#no-comments — don't add comments unless the WHY is non-obvious
+```
+
+## Token Efficiency
+
+| Approach | Tokens |
+|----------|--------|
+| Load full skill file | 500–2000 tokens |
+| Reference snippet | 50–300 tokens |
+| **Savings** | **70–90% reduction** |
+
+## Snippet Categories
+
+| Category | Handles | Purpose |
+|----------|---------|---------|
+| Security | `#security-review`, `#threat-model` | Security-specific instructions |
+| Patterns | `#rust-errors`, `#ts-strict`, `#go-interfaces` | Language-specific patterns |
+| Conventions | `#naming`, `#no-comments`, `#dry` | Project-wide conventions |
+| Workflow | `#test-first`, `#commit-clean`, `#pr-body` | Process instructions |
+| Quality | `#no-unwrap`, `#validate-input`, `#handle-errors` | Quality gates |
+
+## Persistence
+
+Snippets are persisted in `.pi/snippets.json` (JSON array) in the workspace root. They survive sessions and can be managed via `/snippet` commands.
+
+## Slash Commands
+
+| Command | Action |
+|---------|--------|
+| `/snippet list` | List all snippets with handles and descriptions |
+| `/snippet add <handle>` | Create a new snippet interactively |
+| `/snippet remove <handle>` | Delete a snippet |
+| `/snippet edit <handle>` | Edit snippet content |

package/templates/pi/skills/agents/subagent-registry.md

@@ -0,0 +1,78 @@
+---
+name: subagent-registry
+description: Delegates isolated investigations to scoped subagents with restricted tool access. Supports leaf and orchestrator roles for nested delegation.
+model: inherit
+tools: [Read, Grep, Glob, Bash]
+---
+
+# Subagent Registry
+
+Spawn subagents for self-contained investigations without polluting your context. Each subagent has a **restricted tool whitelist**, a **fresh message history**, and a **role** that controls whether it can delegate further.
+
+## Delegation Roles
+
+| Role | Can Delegate? | Use Case |
+|------|--------------|----------|
+| `leaf` (default) | No | Single-task investigations, code review, security audit |
+| `orchestrator` | Yes (bounded by `max_spawn_depth`) | Multi-stage workflows: research → synthesis, parallel decomposition |
+
+### Role Rules
+- **`leaf`** (default): Cannot spawn subagents. Identical to original flat-delegation behavior.
+- **`orchestrator`**: Can delegate to leaf children. Gated by `delegation.max_spawn_depth` (default 1 = flat, so orchestrator is a no-op at defaults). Raise to 2 to allow orchestrator children to spawn leaf grandchildren.
+- **Cost warning**: With `max_spawn_depth: 3` and `max_concurrent_children: 3`, the tree can reach 27 concurrent leaf agents. Each extra level multiplies spend.
+
+## Subagent Types
+
+### explore
+- **Tools:** read_file, list_directory, grep, glob (read-only)
+- **Purpose:** Locate files, trace references, summarize architecture
+- **Max steps:** 12
+- **Returns:** Concise summary with file paths, key findings, line numbers
+
+### code-review
+- **Tools:** read_file, list_directory, grep, glob (read-only)
+- **Purpose:** Review code for correctness, architecture, performance
+- **Max steps:** 12
+- **Returns:** ACTIONABLE findings formatted as "[MUST/SHOULD/NIT] file:line — issue → fix"
+
+### security-review
+- **Tools:** read_file, list_directory, grep, glob (read-only)
+- **Purpose:** Audit for injection, auth bypass, secret leakage, unsafe deserialization
+- **Max steps:** 12
+- **Returns:** Concrete findings with file:line and severity
+
+### general-research
+- **Tools:** read_file, list_directory, grep, glob (read-only)
+- **Purpose:** General-purpose multi-step research across many files
+- **Max steps:** 12
+- **Returns:** Tight summary with evidence (paths, line numbers)
+
+## Delegation Rules
+
+1. **Use subagents for:** Large codebase exploration, multi-file code review, security audits, research spanning ≥3 files
+2. **Do NOT use subagents for:** Single-file edits, trivial lookups, commands you can run yourself
+3. **Include all context:** Subagents have NO memory of your conversation — include file paths, relevant context, and the exact question in the prompt
+4. **Pick the right type:** Match subagent type to the job — don't use general-research when explore suffices
+
+## Anti-Recursion
+
+By default (`max_spawn_depth: 1`), subagents CANNOT spawn subagents. If a subagent needs to delegate, it returns its findings and the parent agent decides whether to spawn another. When `max_spawn_depth` is raised, only `role: orchestrator` subagents can spawn leaf children.
+
+## Tool Scoping
+
+Subagents are scoped to **read-only tools only**. They cannot:
+- Write files
+- Run shell commands
+- Create directories
+- Spawn other subagents
+
+## When to Delegate
+
+| Situation | Action |
+|-----------|--------|
+| "Where is X defined?" in a large codebase | → explore subagent |
+| "Review this PR's changes" | → code-review subagent |
+| "Check for security issues in auth module" | → security-review subagent |
+| "How does data flow from A to B?" | → general-research subagent |
+| "Read this one file" | → Do it yourself |
+| "Run the tests" | → Do it yourself |

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

@@ -0,0 +1,42 @@
+---
+name: test-validator
+description: Validates test coverage and quality. Use post-implementation.
+model: inherit
+tools: [Read, Grep, Glob, Bash]
+---
+
+# Test Validator
+
+You validate test coverage and quality.
+
+## Context
+- `.pi/context/project.md` — project knowledge
+- `.pi/context/checklists.md` — test checklist
+- `.pi/context/output-formats.md` — report format
+
+## Checks
+
+1. **All tests pass** — Run full test suite
+2. **Coverage ≥ 80%** — Run coverage tool
+3. **New code tested** — Every new function has tests
+4. **AAA pattern** — Arrange-Act-Assert structure
+5. **No flaky tests** — Deterministic, no timing dependencies
+
+## Automated (Run via Script)
+
+```bash
+# Run all tests
+[test command]
+
+# Coverage
+[coverage command]
+
+# Architecture contracts
+[contract test command]
+
+# E2E tests
+[e2e test command]
+```
+
+## Output
+Use format from `.pi/context/output-formats.md` → "Validation Report"

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

@@ -0,0 +1,43 @@
+# Architecture Validator Skill
+
+Validates architecture compliance. Use for plan review and post-code wiring checks.
+
+## When to Run
+
+| Phase | Scope | Checks |
+|-------|-------|--------|
+| Plan review | Moderate+ | Design follows patterns, module organization |
+| Post-code | All | Wiring checks only (callers, duplicates, imports) |
+
+## Context Files
+
+- `.pi/context/project.md` — scope classification
+- `.pi/context/checklists.md` — architecture checklist
+- `.pi/context/output-formats.md` — report format
+
+## Post-Code Wiring Checks
+
+```bash
+# 1. Callers exist (not dead code)
+grep -r "new_function" [src paths]
+
+# 2. No duplicate types
+grep -r "struct TypeName|class TypeName" [src paths]
+
+# 3. Module used
+grep -r "import.*module" [src paths]
+
+# 4. Tools registered (if applicable)
+grep -r "register" [registry file]
+```
+
+## Tools
+
+- Read: Read files
+- Grep: Search patterns
+- Glob: Find files
+- Bash: Run validation scripts
+
+## Output
+
+Use `.pi/context/output-formats.md` → "Validation Report"

package/templates/pi/skills/validators/ci-validator.md

@@ -0,0 +1,27 @@
+# CI Validator Skill
+
+Automated CI/merge validator. Runs scripts, minimal LLM reasoning.
+
+## Validation
+
+Run `.pi/scripts/validate-ci.sh` for:
+- Build success
+- Tests pass
+- Lint passes
+- Format check
+- Security audit
+
+## Enforcement
+
+- **All checks must pass** before merge
+- **No partial approvals**
+- Report failures with specific errors
+
+## Tools
+
+- Bash: Run all validation scripts
+- Read: Check CI configuration
+
+## Output
+
+Script outputs standardized report. No additional LLM processing needed.

package/templates/pi/skills/validators/context-compaction.md

@@ -0,0 +1,73 @@
+---
+name: context-compaction
+description: Strategies for managing context window limits through intelligent elision and compaction.
+model: inherit
+tools: [Read]
+---
+
+# Context Compaction Strategy
+
+When conversations grow large, apply these compaction strategies to stay within context limits.
+
+## Budget-Aware Thresholds
+
+| Context Usage | Action |
+|---------------|--------|
+| 0–55% | No compaction needed |
+| 55–70% | Elide superseded read results |
+| 70–90% | Elide all old tool results (keep last 24 messages) |
+| 90%+ | Aggressive compaction — summarize early conversation |
+
+## Superseded Read Elision
+
+When a file has been **mutated** (edit, write_file, multi_edit) since it was last read, the old read result no longer provides useful context. Replace it with:
+
+```
+[elided to save context — see prior tool call in history]
+```
+
+**Rule:** Track mutation paths from tool calls. If a `read_file` result's path appears in any subsequent mutation tool call input, elide that read result.
+
+## Tail Preservation
+
+Never elide the **last 24 messages**. Recent context is always more valuable than distant history. Keep the conversation tail intact at all cost levels.
+
+## System Message Protection
+
+**Never** elide system messages. They contain operating principles, tool descriptions, and behavioral instructions that govern every turn.
+
+## Read Cache Invalidation
+
+After any mutation to a file:
+1. Remove the file from your read cache
+2. Next `read_file` on that path will return fresh content
+3. If you read the same file twice without intervening edits, the second call returns `{unchanged: true}` — skip re-reading
+
+## Token Budget Rules
+
+- `read_file` defaults to first 2000 lines / 25KB — use `offset`/`limit` for large files
+- One focused `grep` beats three `list_directory` calls
+- Don't re-read files you already have in context unless they were modified
+- Before 5+ tool calls in a row, write a one-line plan via `todo_write`
+
+## Compact Format
+
+When space is tight, prefer compact tool results:
+
+```
+# Verbose (200 tokens)
+{
+  "path": "/src/auth.ts",
+  "content": "import { ... } ... [100 lines of code]"
+}
+
+# Compact (8 tokens)
+{
+  "path": "/src/auth.ts",
+  "size": 2456,
+  "lines": 120
+}
+```
+
+Use compact format for: file listings, grep summaries, directory trees.
+Use verbose format only when you need the actual content to reason about changes.