@dragonflymcp/plugin 1.0.0

package/templates/commands/slo.md.template

@@ -0,0 +1,286 @@
+# SLO Command
+
+View Service Level Objectives performance metrics and violations.
+
+## Usage
+
+```
+/slo [subcommand] [options]
+```
+
+## Subcommands
+
+### `report` (default)
+Generate SLO performance dashboard for a time period.
+
+```
+/slo report
+/slo report --timeframe=7d
+/slo report --timeframe=30d --concept=architecture
+```
+
+**Options**:
+- `--timeframe=<period>` - Time period: 1d, 7d, 30d, all (default: 7d)
+- `--concept=<name>` - Filter by concept name
+
+**Output**:
+```
+SLO Performance Report (Last 7 Days)
+=====================================
+
+Overall Compliance: 94% (47/50 actions within SLOs)
+
+By Concept:
+  story:          100% | p50: 1.2s | avg cost: $0.000175
+  architecture:    94% | p50: 11s  | avg cost: $0.003
+  implementation:  95% | p50: 2.1s | avg cost: $0.000175
+  quality:         92% | p50: 1.8s | avg cost: $0.000175
+  version:        100% | p50: 0.8s | avg cost: $0.000175
+  context:        100% | p50: 1.5s | avg cost: $0.000175
+
+Violations (3):
+  - architecture: 2 timeout (resolved via retry)
+  - quality: 1 cost exceeded (alerted)
+
+Recommendations:
+  - Consider increasing architecture timeout from 60s to 90s
+  - Investigate quality cost spikes in flow-003
+```
+
+### `violations`
+List SLO violations with optional filtering.
+
+```
+/slo violations
+/slo violations --concept=architecture
+/slo violations --type=timeout
+/slo violations --timeframe=30d
+```
+
+**Options**:
+- `--concept=<name>` - Filter by concept
+- `--type=<violation_type>` - Filter by type: timeout, cost_exceeded, context_exceeded, quality_below_target
+- `--timeframe=<period>` - Time period: 1d, 7d, 30d, all (default: 7d)
+- `--status=<status>` - Filter by resolution status: pending, resolved, ignored
+
+**Output**:
+```
+SLO Violations (Last 7 Days)
+============================
+
+viol-001 | 2025-12-05 10:35 | architecture | timeout
+  Expected: max 60s | Actual: 72s (+20%)
+  Handler: retry (1 attempt) -> succeeded
+  Status: resolved
+
+viol-002 | 2025-12-05 14:22 | architecture | timeout
+  Expected: max 60s | Actual: 85s (+42%)
+  Handler: retry (1 attempt) -> failed -> escalated
+  Status: resolved (timeout increased to 90s)
+
+viol-003 | 2025-12-06 09:15 | quality | cost_exceeded
+  Expected: max $0.0005 | Actual: $0.0012 (+140%)
+  Handler: alert sent to budget-alerts
+  Status: pending investigation
+```
+
+### `validate`
+Validate all SLO configurations in sync rules.
+
+```
+/slo validate
+```
+
+**Output**:
+```
+SLO Configuration Validation
+============================
+
+Checking: feature-development.yaml
+  story-to-arch:        OK (6 SLOs defined)
+  arch-to-impl:         OK (6 SLOs defined)
+  impl-to-quality:      OK (6 SLOs defined)
+  quality-to-version:   OK (6 SLOs defined)
+
+Checking: slo-monitoring.yaml
+  post-action-slo-monitor: OK (monitoring rule)
+
+Summary: 5 rules OK, 0 warnings
+
+All SLO configurations valid!
+```
+
+### `concept`
+Show SLO configuration and performance for a specific concept.
+
+```
+/slo concept <concept_name>
+/slo concept architecture
+```
+
+**Output**:
+```
+SLO Configuration: architecture
+================================
+
+Defined in: feature-development.yaml (story-to-arch)
+
+Thresholds:
+  Duration:  expected 12s, max 60s
+  Cost:      expected $0.003, max $0.015
+  Context:   expected 1100 tokens, max 10000
+  Success:   target 95%
+
+Handlers:
+  on_timeout:         retry (max 1) -> escalate
+  on_cost_exceeded:   alert (continue: true)
+  on_context_exceeded: alert + investigate
+
+Last 7 Days:
+  Executions: 12
+  Compliance: 92%
+  Violations: 1 timeout (resolved)
+
+Duration Stats:
+  p50: 11s
+  p95: 14s
+  p99: 18s
+
+Cost Stats:
+  avg: $0.0031
+  p95: $0.0038
+  total: $0.037
+
+Context Stats:
+  avg: 1150 tokens
+  p95: 1400 tokens
+```
+
+## Process
+
+When you run this command:
+
+1. **Parse Subcommand and Options**
+   - Determine which action to invoke
+   - Extract filters and parameters
+
+2. **Invoke SLO Concept**
+   - `report` → `slo.report` action
+   - `violations` → `slo.report` with violation filter
+   - `validate` → `slo.validate` action
+   - `concept` → `slo.report` with concept filter
+
+3. **Load Data**
+   - Monthly metrics from `koan/slo/metrics/{concept}/metrics-{YYYY-MM}.yaml`
+   - Violations from `koan/slo/violations/viol-*.yaml`
+   - SLO configs from `.claude/synchronizations/*.yaml`
+
+4. **Format Output**
+   - Apply filters
+   - Calculate aggregations
+   - Format as human-readable tables
+   - Include actionable recommendations
+
+## Data Storage
+
+SLO data is stored in:
+
+```
+koan/slo/
+├── metrics/
+│   ├── architecture/
+│   │   └── metrics-2025-12.yaml
+│   ├── implementation/
+│   │   └── metrics-2025-12.yaml
+│   └── quality/
+│       └── metrics-2025-12.yaml
+├── violations/
+│   ├── viol-001.yaml
+│   ├── viol-002.yaml
+│   └── viol-003.yaml
+└── reports/
+    └── report-2025-12-06.yaml
+```
+
+## SLO Expectations
+
+SLOs are declared in synchronization rules:
+
+```yaml
+- id: "story-to-arch"
+  when:
+    concept: "story"
+    status: "completed"
+  then:
+    - concept: "architecture"
+      action: "design"
+
+  slo_expectations:
+    expected_duration_ms: 12000
+    max_duration_ms: 60000
+    expected_cost_usd: 0.003
+    max_cost_usd: 0.015
+    expected_context_tokens: 1100
+    max_context_tokens: 10000
+    success_rate_target: 0.95
+
+    on_timeout:
+      action: "retry"
+      max_retries: 1
+      on_exhausted: "escalate"
+
+    on_cost_exceeded:
+      action: "alert"
+      continue: true
+```
+
+## Benefits
+
+1. **Visibility** - See performance expectations and actual metrics
+2. **Anomaly Detection** - Automatic violation detection
+3. **Trend Analysis** - Track performance over time
+4. **Cost Control** - Alert on budget overruns
+5. **Quality Assurance** - Monitor success rates
+6. **Phase 2 Verification** - Confirm context optimizations working
+
+## Integration
+
+SLO monitoring happens automatically:
+- After each concept action completes
+- Compares actual performance to declared expectations
+- Executes handlers for violations
+- Updates monthly metrics
+- No manual intervention required
+
+Use `/slo` commands to view and analyze the collected data.
+
+## Example Workflow
+
+```bash
+# View overall performance
+/slo report
+
+# Check recent violations
+/slo violations --timeframe=7d
+
+# Investigate specific concept
+/slo concept architecture
+
+# Validate configuration after changes
+/slo validate
+```
+
+## Tips
+
+- Set realistic SLO values based on historical data
+- Use progressive thresholds (expected < max)
+- Configure appropriate handlers for each violation type
+- Review violations regularly to identify trends
+- Adjust SLOs as system evolves
+- Use investigation tasks for anomalies
+
+## See Also
+
+- `/costs` - View detailed cost breakdown
+- `/trace` - Follow provenance chains
+- `/health` - Check context health

package/templates/commands/spec.md.template

@@ -0,0 +1,164 @@
+---
+name: spec
+description: "Define a specification and generate type-safe code"
+---
+
+# /spec Command
+
+Define structured specifications with types, contracts (pre/post conditions), effects, and properties. Then generate idiomatic code in any target language (Go, Swift, Rust, TypeScript, Python).
+
+## Usage
+
+```
+/spec "string utilities in Go"         # Create a new spec interactively
+/spec generate <id>                     # Generate code from a saved spec
+/spec list                              # List saved specs
+/spec get <id>                          # View a spec
+/spec export <id> "path/to/file.json"  # Export spec to portable JSON
+/spec import "path/to/file.json"       # Import specs from JSON file
+```
+
+## Workflow
+
+### 1. Parse user intent
+
+Determine the action from the arguments:
+- If args contain "generate": go to step 4
+- If args contain "list": go to step 5
+- If args contain "get": go to step 6
+- If args contain "export": go to step 7
+- If args contain "import": go to step 8
+- Otherwise: create a new spec (step 2)
+
+### 2. Define the specification interactively
+
+Work with the user to build the spec:
+
+a) **Identify the module**: Name, description, target language
+b) **Define types**: Custom types with fields and constraints
+c) **Define functions**: For each function, capture:
+   - Name, parameters (with types and constraints), return type
+   - Preconditions (`requires`): What must be true before calling
+   - Postconditions (`ensures`): What must be true after returning
+   - Effects: IO, network, database, filesystem, or none
+   - Error cases: What can go wrong
+d) **Define properties**: Invariants that should hold for all inputs
+   - Use `forall` for universally quantified variables
+   - Express as boolean expressions
+
+### 3. Save the specification
+
+Call `zen_spec_save` with the assembled SpecData:
+
+```
+zen_spec_save({
+  name: "string-utils",
+  data: {
+    name: "string-utils",
+    description: "String utility functions with safe truncation",
+    target_language: "go",
+    types: [...],
+    functions: [
+      {
+        name: "truncate",
+        params: [
+          { name: "s", type: "string" },
+          { name: "maxLen", type: "int", constraints: "> 0" }
+        ],
+        returns: "string",
+        requires: ["maxLen > 0"],
+        ensures: ["len(result) <= maxLen"],
+        errors: ["maxLen <= 0"],
+        effects: [{ type: "none" }],
+        description: "Truncate string to maxLen characters"
+      }
+    ],
+    properties: [
+      {
+        name: "truncate-bounded",
+        description: "Truncated string never exceeds maxLen",
+        forall: ["s: string", "n: int"],
+        body: "len(truncate(s, n)) <= n"
+      }
+    ]
+  }
+})
+```
+
+Show the user a summary of the saved spec.
+
+### 4. Generate code prompt
+
+Call `zen_spec_generate` with the spec ID:
+
+```
+zen_spec_generate({ id: "<spec-id>" })
+```
+
+The returned `prompt` field contains a structured code generation prompt with:
+- Type definitions mapped to the target language
+- Function signatures with contracts as comments
+- Property-based test specifications
+- A verification checklist
+
+Use this prompt to generate the actual code. After generating:
+- Review the code against the verification checklist
+- Ensure all preconditions are enforced
+- Ensure all postconditions hold
+- Write property-based tests
+
+### 5. List specs
+
+Call `zen_spec_list` with optional filters:
+- `status`: draft, ready, generating, generated, verified
+- `target_language`: go, swift, rust, typescript, python
+- `limit`: max results (default 20)
+
+### 6. Get a spec
+
+Call `zen_spec_get` with:
+- `id`: specific spec ID
+- `name`: latest spec with that name
+- `latest: true`: most recent spec
+
+Display the full spec with types, functions, properties, and status.
+
+### 7. Export specs
+
+Call `zen_spec_export` with:
+- `id`: export a single spec by ID
+- `name`: export a single spec by name
+- `all: true`: export all specs
+- `file_path`: output path (e.g., `specs/my-specs.zenspec.json`)
+
+The exported file uses a portable JSON format (array of specs) that strips internal fields like `id` and timestamps. Share the file across projects or check it into version control.
+
+### 8. Import specs
+
+Call `zen_spec_import` with:
+- `file_path`: path to the `.zenspec.json` file
+- `overwrite`: set to `true` to replace existing specs with the same name (default: skip)
+
+New IDs are generated for each imported spec. Reports imported count, skipped count, and any validation errors.
+
+## Spec Language Reference
+
+### Type Notation
+- Primitives: `string`, `int`, `float`, `bool`, `bytes`, `any`
+- Lists: `[]string`, `[]int`
+- Optionals: `?string`, `?int`
+- Maps: `map[string]int`
+- Custom: Any identifier (e.g., `Config`, `UserProfile`)
+
+Types are automatically mapped to the target language:
+| Spec    | Go        | Swift     | Rust         | TypeScript | Python       |
+|---------|-----------|-----------|--------------|------------|--------------|
+| string  | string    | String    | String       | string     | str          |
+| int     | int       | Int       | i64          | number     | int          |
+| []T     | []T       | [T]       | Vec\<T\>     | T[]        | list[T]      |
+| ?T      | *T        | T?        | Option\<T\>  | T\|undef   | Optional[T]  |
+
+## Related Commands
+
+- `/feature` - Full feature workflow (story → architecture → implementation)
+- `/checkpoint` - Save session state

package/templates/commands/status.md.template

@@ -0,0 +1,53 @@
+---
+name: status
+description: "Show unified project dashboard: git, tests, sync rules, workflow, health"
+---
+
+# /status Command
+
+Show a unified project dashboard in a single call.
+
+## What to Do
+
+Gather data from these sources in parallel, then display a formatted summary:
+
+1. **Git status** — Run `git branch --show-current` and `git log --oneline -1` via Bash
+2. **Framework status** — Call `zen_framework_status` MCP tool
+3. **Health status** — Call `zen_health_get` MCP tool
+4. **Workflow state** — Call `zen_get_workflow_state` MCP tool (may return no active session)
+
+## Output Format
+
+```
+Project Status
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Git:       {branch} @ {short_sha} — {commit_message}
+Health:    {zone} ({usage}% context used)
+Framework: {concept_count} concepts, {command_count} commands, {sync_rules} sync rules
+Workflow:  {active_session_info or "No active workflow"}
+Tests:     Run `npm test` in zen-server for count
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+## Example
+
+```
+Project Status
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Git:       main @ 5958925 — feat: Wire sync rules into zen_advance_workflow
+Health:    green (45% context used)
+Framework: 22 concepts, 28 commands, 200 sync rules
+Workflow:  wf-abc123 — story (completed) → implementation (in_progress)
+Tests:     240 passing (zen-server)
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+## Notes
+
+- All data gathering should happen in parallel for speed
+- If any source fails, show "unavailable" for that line
+- Keep output concise — this is a quick glance, not a deep report