zenkit 0.5.0

package/schemas/checkpoint.schema.json

@@ -0,0 +1,64 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://zenkit.dev/schemas/checkpoint.schema.json",
+  "title": "ZenKit Checkpoint",
+  "description": "A snapshot of workflow state at a specific point in execution.",
+  "type": "object",
+  "required": ["checkpoint_id", "task_id", "status", "timestamp"],
+  "properties": {
+    "checkpoint_id": {
+      "type": "string",
+      "pattern": "^chk-[a-z0-9-]+$"
+    },
+    "task_id": {
+      "type": "string"
+    },
+    "timestamp": {
+      "type": "string",
+      "format": "date-time"
+    },
+    "status": {
+      "type": "string",
+      "enum": ["snapshot", "gate", "rollback_point"]
+    },
+    "stage": {
+      "type": "string",
+      "enum": ["plan", "build", "audit", "ship"]
+    },
+    "state": {
+      "type": "object",
+      "properties": {
+        "files_changed": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "tests_passing": { "type": "boolean" },
+        "lint_passing": { "type": "boolean" },
+        "git_ref": { "type": "string" },
+        "notes": { "type": "string" }
+      }
+    },
+    "gate_conditions": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "condition": { "type": "string" },
+          "met": { "type": "boolean" }
+        },
+        "required": ["condition", "met"]
+      }
+    },
+    "metadata": {
+      "type": "object",
+      "properties": {
+        "agent": { "type": "string" },
+        "command": { "type": "string" },
+        "iteration": { "type": "integer" },
+        "tokens_used": { "type": "integer" },
+        "cost_estimate_usd": { "type": "number" }
+      }
+    }
+  },
+  "additionalProperties": false
+}

package/schemas/feature-spec.schema.json

@@ -0,0 +1,76 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://zenkit.dev/schemas/feature-spec.schema.json",
+  "title": "ZenKit Feature Spec",
+  "description": "Machine-readable feature specification for ZenKit benchmarks.",
+  "type": "object",
+  "required": ["feature_id", "name", "description", "mode", "acceptance_criteria", "constraints", "expected_files", "limitations"],
+  "properties": {
+    "feature_id": {
+      "type": "string",
+      "pattern": "^[a-z0-9-]+$"
+    },
+    "name": {
+      "type": "string",
+      "minLength": 1
+    },
+    "description": {
+      "type": "string"
+    },
+    "mode": {
+      "type": "string",
+      "enum": ["zenkit", "baseline"]
+    },
+    "acceptance_criteria": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "required": ["id", "description", "verification"],
+        "properties": {
+          "id": { "type": "string" },
+          "description": { "type": "string" },
+          "verification": {
+            "type": "object",
+            "required": ["type"],
+            "properties": {
+              "type": {
+                "type": "string",
+                "enum": ["file_exists", "file_contains", "schema_count", "examples_valid", "schemas_consistent", "test_passes", "json_path_equals"]
+              },
+              "path": { "type": "string" },
+              "pattern": { "type": "string" },
+              "command": { "type": "string", "description": "Shell command to run for test_passes verification." },
+              "json_path": { "type": "string", "description": "Dot-separated path into JSON for json_path_equals." },
+              "equals": { "description": "Expected value for json_path_equals." },
+              "expected": { "type": "integer" }
+            }
+          }
+        }
+      }
+    },
+    "constraints": {
+      "type": "array",
+      "items": { "type": "string" }
+    },
+    "expected_files": {
+      "type": "array",
+      "items": { "type": "string" }
+    },
+    "assigned_commands": {
+      "type": "array",
+      "items": { "type": "string" }
+    },
+    "estimated_complexity": {
+      "type": "string",
+      "enum": ["low", "medium", "high"]
+    },
+    "limitations": {
+      "type": "array",
+      "minItems": 1,
+      "items": { "type": "string" },
+      "description": "What this spec does NOT verify. Required — specs must be honest about scope."
+    }
+  },
+  "additionalProperties": false
+}

package/schemas/handoff.schema.json

@@ -0,0 +1,78 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://zenkit.dev/schemas/handoff.schema.json",
+  "title": "ZenKit Handoff Contract",
+  "description": "Structured handoff between agents or workflow stages in ZenKit.",
+  "type": "object",
+  "required": ["context", "assumptions", "decision", "deliverable", "next_agent"],
+  "properties": {
+    "context": {
+      "type": "string",
+      "description": "What is the current situation? What has happened so far?"
+    },
+    "assumptions": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Explicit assumptions made during this stage."
+    },
+    "constraints": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Hard constraints that bound this work."
+    },
+    "decision": {
+      "type": "string",
+      "description": "What was decided and why."
+    },
+    "deliverable": {
+      "type": "object",
+      "properties": {
+        "type": {
+          "type": "string",
+          "enum": ["code", "document", "schema", "plan", "review", "test", "artifact"]
+        },
+        "description": { "type": "string" },
+        "files_changed": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "validation_status": {
+          "type": "string",
+          "enum": ["passed", "failed", "partial", "untested"]
+        }
+      },
+      "required": ["type", "description"]
+    },
+    "risks": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "description": { "type": "string" },
+          "severity": { "type": "string", "enum": ["low", "medium", "high", "critical"] },
+          "mitigation": { "type": "string" }
+        },
+        "required": ["description", "severity"]
+      }
+    },
+    "open_questions": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Unresolved questions that the next agent should address."
+    },
+    "next_agent": {
+      "type": "string",
+      "description": "The agent or role that should receive this handoff."
+    },
+    "metadata": {
+      "type": "object",
+      "properties": {
+        "timestamp": { "type": "string", "format": "date-time" },
+        "source_agent": { "type": "string" },
+        "command": { "type": "string" },
+        "iteration": { "type": "integer", "minimum": 0 }
+      }
+    }
+  },
+  "additionalProperties": false
+}

package/schemas/task.schema.json

@@ -0,0 +1,69 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://zenkit.dev/schemas/task.schema.json",
+  "title": "ZenKit Task",
+  "description": "A discrete unit of work within a ZenKit workflow.",
+  "type": "object",
+  "required": ["id", "name", "status", "command"],
+  "properties": {
+    "id": {
+      "type": "string",
+      "pattern": "^[a-z0-9-]+$"
+    },
+    "name": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 200
+    },
+    "description": {
+      "type": "string"
+    },
+    "command": {
+      "type": "string",
+      "enum": ["plan", "build", "audit", "refactor", "spec", "handoff", "checkpoint", "ship"]
+    },
+    "status": {
+      "type": "string",
+      "enum": ["pending", "in_progress", "blocked", "completed", "failed", "skipped"]
+    },
+    "context": {
+      "type": "string"
+    },
+    "assumptions": {
+      "type": "array",
+      "items": { "type": "string" }
+    },
+    "constraints": {
+      "type": "array",
+      "items": { "type": "string" }
+    },
+    "acceptance_criteria": {
+      "type": "array",
+      "items": { "type": "string" }
+    },
+    "files_affected": {
+      "type": "array",
+      "items": { "type": "string" }
+    },
+    "assigned_agent": {
+      "type": "string"
+    },
+    "parent_task": {
+      "type": "string"
+    },
+    "dependencies": {
+      "type": "array",
+      "items": { "type": "string" }
+    },
+    "metadata": {
+      "type": "object",
+      "properties": {
+        "created_at": { "type": "string", "format": "date-time" },
+        "updated_at": { "type": "string", "format": "date-time" },
+        "estimated_tokens": { "type": "integer", "minimum": 0 },
+        "actual_tokens": { "type": "integer", "minimum": 0 }
+      }
+    }
+  },
+  "additionalProperties": false
+}

package/skills/architecture-review.md

@@ -0,0 +1,17 @@
+# Architecture Review
+
+> Review system architecture for coherence, scalability, and alignment with project constraints.
+
+**When to use:**
+- New service/module/feature is being designed or a PR introduces major structural changes
+- Scaling, reliability, or maintainability issues in an existing system
+- Tech-debt audit or migration planning underway
+
+**Input:** System description or codebase reference, requirements/constraints, ADRs if available, and specific concerns from the requester.
+
+**Output:** Structured per ZenKit contract (context, assumptions, constraints, decision, deliverable, risks, open_questions). Deliverable is a ranked list of findings with severity, affected components, and concrete recommendations.
+
+**Watch for:**
+- Reviewing in a vacuum without understanding the team's actual constraints and timeline
+- Recommending full rewrites when incremental improvements suffice
+- Ignoring failure modes and operational concerns (observability, deployment, rollback)

package/skills/backend-change.md

@@ -0,0 +1,17 @@
+# Backend Change
+
+> Implement backend changes (API endpoints, data models, business logic) following existing patterns.
+
+**When to use:**
+- New API endpoint/route needs to be created or an existing one modified
+- Data model or schema needs to be added or altered
+- Business logic or third-party integration needs implementation
+
+**Input:** Description of the desired change and motivation, affected files/modules, API contract or data model specs if applicable, and acceptance criteria.
+
+**Output:** Structured per ZenKit contract (context, assumptions, constraints, decision, deliverable, risks, open_questions). Deliverable is the code changes -- new/modified files, migrations, and tests.
+
+**Watch for:**
+- Introducing new patterns when established ones already exist in the codebase
+- Writing migrations unsafe for zero-downtime deployments
+- Handling only the success case and leaving error paths incomplete

package/skills/bug-triage.md

@@ -0,0 +1,17 @@
+# Bug Triage
+
+> Investigate and classify bugs, identify root cause, propose fix strategy.
+
+**When to use:**
+- Bug report filed by a user, QA, or automated monitoring
+- Unexpected test failure not caused by an intentional change
+- Production incident needs rapid diagnosis
+
+**Input:** Bug report or description of unexpected behavior, reproduction steps, environment details, relevant logs/errors/screenshots, and recent related changes.
+
+**Output:** Structured per ZenKit contract (context, assumptions, constraints, decision, deliverable, risks, open_questions). Deliverable is a triage report: confirmed/not-confirmed status, severity classification, root cause analysis, affected components, and proposed fix with estimated effort.
+
+**Watch for:**
+- Fixing the symptom without understanding the underlying root cause
+- Classifying severity based on reporter loudness rather than actual impact
+- Skipping reproduction and jumping straight to a fix based on guesswork

package/skills/frontend-change.md

@@ -0,0 +1,17 @@
+# Frontend Change
+
+> Implement frontend changes (components, pages, styles) following existing patterns and design system.
+
+**When to use:**
+- New UI component, page, or feature needs to be built
+- Existing component requires visual or behavioral modification
+- Accessibility or responsive layout improvements needed
+
+**Input:** Description of the UI/UX change with visual references when available, affected components/pages, design system specs, and acceptance criteria including breakpoints and a11y requirements.
+
+**Output:** Structured per ZenKit contract (context, assumptions, constraints, decision, deliverable, risks, open_questions). Deliverable is the code changes -- components, styles, tests, and storybook entries where applicable.
+
+**Watch for:**
+- Hardcoding values instead of using design system tokens or theme variables
+- Creating one-off components when a shared component could be extended
+- Neglecting keyboard navigation, focus management, and cross-browser/viewport testing

package/skills/prompt-pruning.md

@@ -0,0 +1,17 @@
+# Prompt Pruning
+
+> Reduce prompt verbosity and token waste while preserving instruction quality and coverage.
+
+**When to use:**
+- Prompt or system instruction exceeds its token budget
+- Response quality degraded due to overly long context
+- Multiple prompts need consolidation or adaptation for a new model's context limits
+
+**Input:** The prompt(s) to prune, token budget or reduction target, priority ranking of instructions (must-keep vs. nice-to-have), and example outputs to validate against.
+
+**Output:** Structured per ZenKit contract (context, assumptions, constraints, decision, deliverable, risks, open_questions). Deliverable is the pruned prompt(s) with before/after token counts and a change log of what was removed, merged, or rewritten.
+
+**Watch for:**
+- Removing "redundant" instructions that actually reinforce model compliance
+- Over-compressing nuanced instructions into ambiguous shorthand
+- Pruning safety or guardrail instructions because they seem verbose

package/skills/release-check.md

@@ -0,0 +1,17 @@
+# Release Check
+
+> Pre-release validation: tests pass, no regressions, docs updated, changelog current, deploy gates met.
+
+**When to use:**
+- Release branch or tag is being prepared, or deploy to staging/production is imminent
+- Sprint or milestone is being closed out
+- Hotfix or previously blocked release needs validated release
+
+**Input:** Branch/tag/commit range to validate, deployment gate requirements, list of changes included (PRs, commits, tickets), and target environment.
+
+**Output:** Structured per ZenKit contract (context, assumptions, constraints, decision, deliverable, risks, open_questions). Deliverable is a completed checklist with pass/fail per gate: test results, regression check, docs review, changelog verification, dependency audit, and environment readiness. Verdict: go, no-go, or conditional-go.
+
+**Watch for:**
+- Treating the release check as a formality and rubber-stamping items
+- Validating only the happy path without checking error handling and edge cases
+- Missing environment-specific config differences between staging and production

package/skills/security-review.md

@@ -0,0 +1,17 @@
+# Security Review
+
+> Audit code for OWASP top 10 vulnerabilities, auth issues, data exposure, and injection risks.
+
+**When to use:**
+- New code handles user input, authentication, authorization, or sensitive data
+- Feature touches payment processing, PII, or external integrations
+- Pre-release security gate or dependency update with new/major packages
+
+**Input:** Code to review (files, PR, or module reference), description of security-relevant behavior, threat model if available, and compliance requirements (SOC 2, GDPR, HIPAA, PCI-DSS).
+
+**Output:** Structured per ZenKit contract (context, assumptions, constraints, decision, deliverable, risks, open_questions). Deliverable is a list of findings with vulnerability type (CWE), severity (Critical/High/Medium/Low/Info), affected location, proof-of-concept, and remediation steps.
+
+**Watch for:**
+- Reporting only injection flaws while ignoring authorization and business logic issues
+- Providing generic remediation ("sanitize input") instead of specific contextual fixes
+- Missing security issues in config files, env vars, or build pipelines

package/templates/agent.template.md

@@ -0,0 +1,18 @@
+# {{Agent Role}}
+
+> {{one_line_description}}
+
+**Owns:** {{what this agent is responsible for}}
+**Receives from:** {{upstream agent}}
+**Hands off to:** {{downstream agent}}
+
+**Must produce:** context, assumptions, constraints, decision, deliverable, risks, open_questions, next_agent
+
+**Must NOT:**
+- {{boundary_1}}
+- {{boundary_2}}
+- {{boundary_3}}
+
+**Quality bar:**
+- {{standard_1}}
+- {{standard_2}}

package/templates/command.template.md

@@ -0,0 +1,21 @@
+# /{{command_name}}
+
+> {{one_line_description}}
+
+**Position:** {{where in spec → plan → build → audit → checkpoint → ship}}
+**Input:** {{what this command expects}}
+**Output:** Structured per ZenKit contract (context, assumptions, constraints, decision, deliverable, risks, open_questions, next_agent).
+
+**When to use:**
+- {{scenario_1}}
+- {{scenario_2}}
+- {{scenario_3}}
+
+**Example:**
+```
+> /{{command_name}} "{{brief_example}}"
+context: {{example_context}}
+decision: {{example_decision}}
+deliverable: {{example_deliverable}}
+next_agent: {{example_next}}
+```

package/templates/skill.template.md

@@ -0,0 +1,15 @@
+# {{Skill Name}}
+
+> {{one_line_description}}
+
+**When to use:**
+- {{trigger_1}}
+- {{trigger_2}}
+
+**Input:** {{what the skill expects}}
+
+**Output:** Structured per ZenKit contract (context, assumptions, constraints, decision, deliverable, risks, open_questions).
+
+**Watch for:**
+- {{pitfall_1}}
+- {{pitfall_2}}

package/templates/task.template.md

@@ -0,0 +1,19 @@
+# {{Task Name}}
+
+**ID:** {{task_id}}
+**Command:** {{spec|plan|build|audit|refactor|handoff|checkpoint|ship}}
+**Status:** {{pending|in_progress|blocked|completed|failed|skipped}}
+**Agent:** {{assigned_agent}}
+
+## Context
+{{what_is_being_done_and_why}}
+
+## Acceptance Criteria
+- {{criterion_1}}
+- {{criterion_2}}
+
+## Constraints
+- {{constraint_1}}
+
+## Dependencies
+- {{dependency_task_id}}