guardian-framework 0.1.0

package/templates/pi/skills/agents/issue-creator.md

@@ -0,0 +1,75 @@
+---
+name: issue-creator
+description: Creates and manages GitHub issues. Use for tracking work items.
+model: inherit
+tools: [Bash, Read]
+---
+
+# Issue Creator
+
+You create and manage GitHub issues for work tracking.
+
+## Context
+- `.pi/context/project.md` — project labels, conventions
+
+## Issue Types & Templates
+
+### Feature Request
+```markdown
+## Feature: [Name]
+
+### Requirements
+- [ ] Requirement 1
+- [ ] Requirement 2
+
+### Scope
+- **Level:** [Simple/Moderate/Complex/Critical]
+- **Files:** [count]
+
+### Acceptance Criteria
+- [ ] Criterion 1
+- [ ] Criterion 2
+```
+
+### Bug Report
+```markdown
+## Bug: [Description]
+
+### Steps to Reproduce
+1. Step 1
+2. Step 2
+
+### Expected vs Actual
+[Comparison]
+```
+
+### Tech Debt
+```markdown
+## Tech Debt: [Description]
+
+### Current vs Desired State
+[Comparison]
+
+### Effort: [Small/Medium/Large]
+```
+
+## Labels
+
+| Category | Labels |
+|----------|--------|
+| Priority | `P0-critical`, `P1-high`, `P2-medium`, `P3-low` |
+| Type | `type:feature`, `type:bug`, `type:tech-debt`, `type:docs` |
+| Status | `status:blocked`, `status:in-progress`, `status:needs-review` |
+
+## Commands
+
+```bash
+# Create issue
+gh issue create --title "..." --body "..." --label "type:feature,P1-high"
+
+# Update issue
+gh issue edit [N] --add-label "status:in-progress"
+
+# Close issue
+gh issue close [N] --comment "Merged in #[PR]"
+```

package/templates/pi/skills/agents/issue-factory.md

@@ -0,0 +1,143 @@
+---
+name: issue-factory
+description: Transforms accepted architecture scope into executable GitLab/GitHub issues with complete session context.
+model: inherit
+tools: [Read, Write, Edit]
+---
+
+# Issue Factory
+
+## Purpose
+
+Transforms accepted architecture scope into executable GitLab/GitHub work items. Every issue generated contains the complete session context needed for a fresh agent to implement correctly.
+
+Related references:
+- [issue-template.md](../../prompts/issue-template.md)
+- [epic-template.md](../../prompts/epic-template.md)
+- [ci-blueprint.md](../../prompts/ci-blueprint.md)
+
+## Workflow
+
+1. Start from an accepted architecture scope (`.pi/architecture/modules/*.md`).
+2. Build a dependency graph of components.
+3. Create one epic per feature or platform hardening stream.
+4. Create issues only at the smallest independently reviewable unit.
+5. Add issue dependencies in execution order.
+6. Add verification issues only when they cannot fit into implementation issues.
+
+## Required Issue Fields
+
+Every issue must contain:
+
+- **Title** — `<Layer or Feature>: <Concrete action>`
+- **Why** — Business or platform reason
+- **Scope** — Exact change
+- **In scope** — Bullet list of what's included
+- **Out of scope** — Bullet list of what's explicitly excluded
+- **Dependencies** — blocked by / blocks relationships
+- **Files/layers affected** — domain, application, infrastructure, api
+- **Acceptance criteria** — Tied to specific Guardian validators
+- **Test requirements** — Unit/integration/e2e/conformance expectations
+- **Rollout/ops notes** — Feature flags, migration steps, monitoring
+- **Canonical references** — Architecture module + ADR paths
+
+## Recommended Labels
+
+| Label | Meaning |
+|-------|---------|
+| `layer::domain` | Domain model, entities, value objects |
+| `layer::application` | Use cases, services, handlers |
+| `layer::infrastructure` | Databases, queues, external APIs |
+| `layer::api` | REST/gRPC endpoints, middleware |
+| `layer::security` | Auth, encryption, secrets |
+| `layer::operations` | Observability, runbooks, DR |
+| `type::feature` | New functionality |
+| `type::hardening` | Security/performance improvement |
+| `type::migration` | Schema or config migration |
+| `type::test` | Test-only work |
+| `risk::high` | Breaks existing behavior |
+| `risk::medium` | Changes internal behavior |
+| `risk::low` | Additive, no breaking changes |
+
+## Epic Shape
+
+### Feature Epic
+
+- domain contract
+- application handler/API work
+- runtime/worker work
+- infrastructure/storage work
+- security review
+- observability and rollout
+
+### Platform Hardening Epic
+
+- architecture change
+- migration and config
+- verification suite
+- rollout and runbook update
+
+## Sizing Rules
+
+### Good Issue
+
+- one primary owner
+- one review path
+- one clear output
+- can be merged independently behind a flag if needed
+
+### Bad Issue
+
+- changes multiple unrelated contracts
+- mixes schema, runtime, and ops with no shared acceptance criterion
+- has vague outputs like 'update backend architecture'
+
+## Dependency Ordering Template
+
+1. contract issue
+2. schema/index issue
+3. repository/service issue
+4. handler/runtime issue
+5. verification issue
+6. rollout/runbook issue
+
+## Agent Issue-Generation Order
+
+1. **Architecture Coordinator** drafts epic map
+2. **Domain/Application/Runtime/Infrastructure agents** draft issue candidates
+3. **Security and Operations agents** append mandatory controls and release criteria
+4. **Integration Agent** removes overlap and resolves dependency conflicts
+5. **Issue Factory Agent** emits final issues
+
+## Issue Generation Process
+
+For each planned component in the architecture module:
+
+```yaml
+Input:  .pi/architecture/modules/auth-system.md#jwt-token-validation
+Output: .pi/issues/ISSUE-001-jwt-token-validation.md
+```
+
+The generated issue file includes:
+
+1. **YAML front matter** — parsed by Guardian for pipeline orchestration
+2. **Intent** — what this issue aims to achieve
+3. **Dependency graph** — ASCII art showing relationships
+4. **In/Out of scope** — explicit boundaries
+5. **Affected layers** — which layers change and how
+6. **Canonical references** — architecture module + ADRs
+7. **Acceptance criteria** — tied to validators
+8. **Implementation notes** — specific technical guidance
+9. **File changes** — expected creates/modifies
+
+## Validation Rules
+
+Before an issue is emitted:
+
+1. **No orphaned issues** — every issue belongs to an epic
+2. **No circular dependencies** — dependency graph must be acyclic
+3. **Clear acceptance criteria** — at least one validator referenced
+4. **Canonical reference exists** — must reference an architecture module
+5. **Scope is bounded** — must have both in-scope and out-of-scope
+6. **Layers are specified** — must list affected layers
+7. **Dependencies are valid** — referenced issues must exist

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

@@ -0,0 +1,85 @@
+---
+name: kanban
+description: Durable task board for tracking multi-session, multi-agent work with state machine transitions.
+model: inherit
+tools: [Read, Bash]
+---
+
+# Guardian Kanban Board
+
+A durable task board backed by `.pi/.guardian-kanban.json`. Tasks have state machines, dependency links, comments, and workspace management. Unlike subagent delegation (RPC-style, blocking), kanban is **fire-and-forget** and **crash-resilient**.
+
+## Task States
+
+```
+triage → todo → ready → running → done → archived
+                ↑         ↓         ↑
+                └── blocked ────────┘
+```
+
+| State | Meaning |
+|-------|---------|
+| `triage` | New task, needs review |
+| `todo` | Ready to be picked up |
+| `ready` | All dependencies met, can start |
+| `running` | Currently being worked on |
+| `blocked` | Cannot proceed (reason recorded) |
+| `done` | Completed |
+| `archived` | Historical record |
+
+## Tools
+
+| Tool | Description |
+|------|-------------|
+| `kanban_create` | Create a new task (title, body, assignee, priority, dependencies) |
+| `kanban_list` | List tasks, optionally filtered by status |
+| `kanban_show` | Show full task details including comments |
+| `kanban_complete` | Mark a task as done (auto-unblocks children) |
+| `kanban_block` | Block a task with a reason |
+| `kanban_comment` | Add a comment to a task |
+
+## Commands
+
+| Command | What it does |
+|---------|-------------|
+| `/kanban` or `/kanban status` | Board summary with task counts by status |
+| `/kanban create <title>` | Quick-create a task |
+| `/kanban list [status]` | List tasks (optionally filter by status) |
+
+## Creating Tasks with Dependencies
+
+```
+kanban_create(
+  title: "Implement auth middleware",
+  body: "Add JWT validation to all /api/* routes",
+  priority: "high",
+  parents: ["TK-0001"]  # depends on TK-0001
+)
+```
+
+When a parent task is marked `done`, dependent tasks automatically transition from `todo` to `ready`.
+
+## Priority Levels
+
+| Priority | Emoji | Use for |
+|----------|-------|---------|
+| `critical` | 🔴 | Blocking issues, security fixes |
+| `high` | 🟠 | Current sprint, important features |
+| `medium` | 🟡 | Normal features, improvements |
+| `low` | 🟢 | Nice-to-have, tech debt |
+
+## When to use Kanban vs. Subagents
+
+| Use Kanban when... | Use Subagents when... |
+|--------------------|----------------------|
+| Work crosses sessions | Parent needs answer before continuing |
+| Work needs human input | No humans involved |
+| Work might be retried by different agent | Result goes back into parent's context |
+| You need a durable audit trail | Short-lived investigation |
+
+## Workspace Types
+
+| Type | Description |
+|------|-------------|
+| `scratch` (default) | Temporary workspace, cleaned on completion |
+| `dir:/absolute/path` | Shared directory (must be absolute path) |

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

@@ -0,0 +1,59 @@
+---
+name: land
+description: Execute the PR merge loop with full validation before merging.
+---
+
+# Land Skill
+
+When a ticket reaches `Merging` state, execute the land loop: validate, merge, and move to Done.
+
+**NEVER call `gh pr merge` or `glab mr merge` directly.** Use this skill.
+
+## Protocol
+
+1. **Verify PR is approved** — check review status
+2. **Verify all checks pass** — CI, lint, tests
+3. **Verify workpad is complete** — all acceptance criteria checked
+4. **Verify no outstanding review comments** — run feedback sweep
+5. **Merge** the PR using the configured repository tool
+6. **Delete** the feature branch (remote and local)
+7. **Move ticket** to Done state
+8. **Update tracking** — update changelog if needed
+
+## GitHub
+
+```bash
+# Check PR status
+gh pr view <number> --json state,mergeStateStatus,reviewDecision,statusCheckRollup
+
+# Verify checks pass
+gh pr checks <number>
+
+# Verify reviews
+gh pr view <number> --json reviews
+
+# Merge (squash for clean history, or merge for preserving commits)
+gh pr merge <number> --squash --delete-branch
+
+# Or rebase merge
+gh pr merge <number> --rebase --delete-branch
+```
+
+## GitLab
+
+```bash
+# Check MR status
+glab mr view <iid>
+
+# Merge MR
+glab mr merge <iid> --when-pipeline-succeeds --should-remove-source-branch
+```
+
+## Rules
+
+- NEVER merge if any check is failing
+- NEVER merge if review is not approved
+- NEVER merge if acceptance criteria are incomplete
+- ALWAYS delete the feature branch after merge
+- ALWAYS move the ticket to Done after merge
+- If merge fails, document the failure in the workpad and notify

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

@@ -0,0 +1,43 @@
+---
+name: operations-validator
+description: Validates production readiness. Performance, observability, error handling, cancellation.
+model: inherit
+tools: [Read, Grep, Glob, Bash]
+---
+
+# Operations Validator
+
+You ensure code changes are production-ready.
+
+## Context
+- `.pi/context/project.md` — project knowledge
+- `.pi/context/checklists.md` — operations checklist
+- `.pi/context/output-formats.md` — report format
+- `.pi/context/patterns.md` — required patterns
+
+## Core Checks
+
+1. **Performance** — No O(N²) where O(N) expected, proper data structures
+2. **Observability** — Tracing on public functions, events for state changes
+3. **Cancellation** — CancellationToken in all async ops, proper cleanup
+4. **Resource Management** — Files closed, no leaks, bounded structures
+5. **Atomic Writes** — Write-rename pattern for persistence
+
+## Automated Checks (Run via Script)
+
+```bash
+# Tracing coverage
+grep -r "#\[instrument\]" [src] --include="*.[ext]"
+
+# Cancellation handling
+grep -r "cancel_token" [src] --include="*.[ext]"
+
+# Atomic writes
+grep -r "fs::rename" [src] --include="*.[ext]"
+
+# Benchmarks
+[bench command]
+```
+
+## Output
+Use format from `.pi/context/output-formats.md` → "Validation Report"

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

@@ -0,0 +1,113 @@
+---
+name: pipeline
+description: Multi-step workflow engine for iterating over items with per-step prompts and acceptance gates.
+model: inherit
+tools: [Read, Bash, Edit]
+---
+
+# Pipeline Engine
+
+A multi-step workflow that iterates over items (issues, tasks, etc.) with per-step prompts and acceptance conditions. Each step can require validators to pass before advancing.
+
+## When to use it
+
+Use `/pipeline` when you need to repeat a structured workflow across multiple items:
+
+- "Close all P1 bugs" → implement → validate → create MR → merge
+- "Add tests to these 5 modules" → implement tests → validate tests → commit
+- "Security review for these 10 endpoints" → security-review → validate → document
+
+Unlike `/goal` (single objective, auto-iterate), `/pipeline` is a **step-by-step state machine** with explicit gates.
+
+## Commands
+
+| Command | Effect |
+|---------|--------|
+| `/pipeline <name> --items "id1,id2,id3" --steps "implement,validate,create-mr"` | Start a pipeline |
+| `/pipeline <name> --items "id1,id2" --steps "implement,validate" --merge-on-valid` | Start with auto-merge |
+| `/pipeline` or `/pipeline status` | Show current pipeline progress |
+| `/pipeline pause` | Pause at current step |
+| `/pipeline resume` | Resume from where paused |
+| `/pipeline skip-step` | Skip current step, move to next |
+| `/pipeline retry-step` | Retry the current step |
+| `/pipeline abort` | Kill pipeline |
+
+## Built-in Steps
+
+| Step | Prompt | Acceptance Gate |
+|------|--------|-----------------|
+| `implement` | `.pi/prompts/issue-implementation-series.md` | CI validator |
+| `validate` | — | CI + tests + security validators |
+| `create-mr` | `.pi/prompts/issue-closeout.md` | None |
+| `merge` | — | CI + canonical validators |
+| `document` | `.pi/prompts/blueprint-update.md` | Canonical validator |
+| `test` | — | Tests validator |
+| `security-review` | — | Security validator |
+
+## Example: Close all P1 bugs
+
+```
+You: /pipeline "Close P1 bugs" --items "1234,1235,1236" --steps "implement,validate,create-mr,merge" --merge-on-valid
+
+▶ Pipeline "Close P1 bugs" started (PL-0001)
+Items: 1234, 1235, 1236
+Steps: implement → validate → create-mr → merge
+Merge on valid: enabled
+
+[Step 1/12] Item 1234 → implement
+  Agent: [loads issue-implementation-series.md, implements fix]
+  ✓ CI passes → advance
+
+[Step 2/12] Item 1234 → validate
+  Agent: [runs ci, tests, security validators]
+  ✓ All pass → advance
+
+[Step 3/12] Item 1234 → create-mr
+  Agent: [creates merge request]
+  ✓ MR created → advance
+
+[Step 4/12] Item 1234 → merge
+  ✓ Merged → advance to next item
+
+[Step 5/12] Item 1235 → implement
+  ...continues
+```
+
+## Acceptance Gates
+
+Each step can have a different acceptance condition:
+
+| Type | Behavior |
+|------|----------|
+| `validator` | Runs specified validators. Must all pass to advance. |
+| `shell` | Runs a custom shell command. Exit 0 = pass. |
+| `llm` | LLM evaluates completion against a prompt. |
+| `none` | No gate. Always advances. |
+
+## Tools
+
+| Tool | Description |
+|------|-------------|
+| `pipeline_status` | Show current pipeline status and progress |
+| `pipeline_advance` | Mark current step as passed and advance |
+| `pipeline_fail` | Mark current step as failed, skip remaining steps for this item |
+
+## Pipeline States
+
+```
+running → paused (user) → running (user)
+   ↓         ↓
+ done      aborted (user)
+   ↓
+failed (step failure without retry)
+```
+
+## Custom Steps
+
+You can add custom steps by name. Unknown steps have no prompt and no acceptance gate:
+
+```
+/pipeline "Custom flow" --items "task1,task2" --steps "implement,custom-review,validate"
+```
+
+The `custom-review` step will run with no prompt and no gate — the agent works freely.

package/templates/pi/skills/agents/plan-mode.md

@@ -0,0 +1,77 @@
+---
+name: plan-mode
+description: Queues file mutations for batch review instead of executing immediately. User reviews all changes as a single diff before accepting/rejecting.
+model: inherit
+tools: [Read, Write, Edit]
+---
+
+# Plan Mode Extension
+
+Plan Mode intercepts all mutating tool calls (`write_file`, `edit`, `multi_edit`, `create_directory`) and **queues** them for batch review instead of executing immediately. The agent works in a read-only research mode, then the user reviews all queued changes at once.
+
+## Flow
+
+1. User enables plan mode: `/plan` or `/plan on`
+2. Agent reads files, researches, and **queues** mutations without executing
+3. Agent stops and presents a summary of planned changes
+4. User reviews all queued edits as a side-by-side diff
+5. User accepts/rejects each change (or all at once)
+6. Accepted changes are applied; rejected changes are discarded
+7. Plan mode can stay on for iterative refinement
+
+## Queued Edit Structure
+
+```typescript
+interface QueuedEdit {
+  id: string;           // Unique edit ID (stable across updates)
+  kind: "edit" | "multi_edit" | "write_file" | "create_directory";
+  path: string;         // Absolute file path
+  originalContent: string;
+  proposedContent: string;
+  isNewFile: boolean;   // true for write_file/create_directory on non-existent paths
+  description?: string; // Optional human-readable description
+}
+```
+
+## Behavior by Tool
+
+| Tool | Normal Mode | Plan Mode |
+|------|------------|-----------|
+| `read_file` | Execute | Execute (read-only always runs) |
+| `grep` | Execute | Execute |
+| `list_directory` | Execute | Execute |
+| `edit` | Execute immediately | Queue for review |
+| `multi_edit` | Execute immediately | Queue for review |
+| `write_file` | Execute immediately | Queue for review |
+| `create_directory` | Execute immediately | Queue for review |
+| `bash_run` | Execute (with approval) | **Refuse** — no shell in plan mode |
+| `bash_background` | Execute (with approval) | **Refuse** — no shell in plan mode |
+
+## Validation in Plan Mode
+
+While plan mode is active, the agent should:
+- Use `todo_write` to track planned changes before queueing
+- Stop after queuing all mutations (don't continue acting)
+- Provide a brief summary: files changed, lines added/removed, new files created
+
+## Anti-Abuse
+
+- Shell commands (`bash_run`, `bash_background`) are refused in plan mode
+- Subagent spawning is allowed but subagents also inherit plan mode restrictions
+- The queue is per-session — switching sessions clears the queue
+
+## Pi Extension API
+
+```typescript
+// Plan mode state managed via Zustand-style store
+const planModeStore = {
+  active: boolean,
+  queue: QueuedEdit[],
+  enable() { this.active = true; },
+  disable() { this.active = false; this.queue = []; },
+  enqueue(edit: QueuedEdit) { this.queue.push(edit); },
+  clear() { this.queue = []; },
+  accept(ids: string[]) { /* Apply queued edits */ },
+  reject(ids: string[]) { /* Discard queued edits */ },
+};
+```

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

@@ -0,0 +1,40 @@
+---
+name: pull
+description: Keep branch updated with latest origin/main before handoff.
+---
+
+# Pull Skill
+
+Sync with latest origin/main before implementation or handoff.
+
+## Protocol
+
+1. **Fetch** latest from remote
+2. **Merge** origin/main into current branch
+3. **Record** the result in workpad or notes
+4. **Rerun** validations if conflicts were resolved
+
+## Commands
+
+```bash
+# Fetch latest
+git fetch origin
+
+# Check what would change
+git log HEAD..origin/main --oneline
+
+# Merge into current branch
+git merge origin/main --no-edit
+
+# Record evidence
+# merge source: origin/main
+# result: clean / conflicts resolved
+# HEAD: <short-sha>
+```
+
+## When to Run
+
+- Before starting any implementation
+- Before pushing changes
+- After being asked to rebase
+- When reviewer comments suggest the branch is out of date

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

@@ -0,0 +1,41 @@
+---
+name: push
+description: Keep remote branch current and publish updates.
+---
+
+# Push Skill
+
+Publish local changes to remote and keep branch updated.
+
+## Protocol
+
+1. **Before push:** run all validations for the scope
+2. **Merge latest origin/main** into the branch and resolve conflicts
+3. **Rerun validations** after merge
+4. **Push** to remote
+
+## Commands
+
+```bash
+# Fetch latest
+git fetch origin
+
+# Merge main into current branch
+git merge origin/main
+
+# If conflicts: resolve, then
+git add <resolved-files>
+git commit -m "fix: resolve merge conflicts"
+
+# Push branch (create if needed)
+git push -u origin <branch-name>
+
+# Force push only with --force-with-lease (never --force)
+git push --force-with-lease
+```
+
+## Rules
+
+- ALWAYS merge origin/main before pushing
+- NEVER use `git push --force` — use `--force-with-lease` only when necessary
+- ALWAYS re-run validations after resolving conflicts