Skill: Kaiza MCP Operations

Purpose

Ensure all code modifications are made within approved plans, tracked via Kaiza MCP, and auditable via KAIZA-AUDIT blocks.

When to Use This Skill

• Starting any coding task (feature, bug fix, refactoring, release)
• When Kaiza MCP is available in the environment
• Before reading or writing files

Steps

1) Kaiza preflight

• Call Kaiza read_prompt to load WINDSURF_CANONICAL (authoritative config)
• Call Kaiza list_plans to see approved plans for this workspace
• Select a plan that matches the scope of your task

If no matching plan exists:

• Stop and propose a plan
• Do not proceed until the plan is approved

2) Understand plan boundaries

Each plan has:

• scope: What files/modules it covers
• authority: Which rules govern it
• risk level: How much change is permitted
• verification: What checks must pass

Example plan:

Plan: "implement-feature-x"
Scope: src/features/x, tests/features/x, docs/features/x
Authority: AGENTS.md, GLOBAL_RULES.md, @no-placeholders-production-code
Risk: moderate (new code, within isolated feature)
Verification: all tests pass, lint clean, coverage >80%

3) Read files using Kaiza

Use Kaiza read_file for all reads (not standard file operations). This ensures:

• Reads are tracked for audit
• Permissions are checked against the plan
• Context is loaded into the MCP session

4) Write files with provenance metadata

For every file write using Kaiza write_file, include:

• plan: Name of the approved plan (e.g., "implement-feature-x")
• role: executable | boundary | library | infra | test | docs
• purpose: What does this file exist to do?
• usedBy: What imports/invokes it?
• connectedVia: How it integrates (routes, DI, CLI, job scheduler)
• executedVia: How it runs (node, python, docker, CI)
• failureModes: Known failure patterns
• authority: Which rules govern this file

Example write metadata:

plan: "implement-feature-x"
role: "boundary"
purpose: "HTTP handler for feature X endpoints"
usedBy: "app.js (main router), tests/features/x.test.js"
connectedVia: "Express route registration in /features route group"
executedVia: "Node.js, runs on every HTTP request"
failureModes: "Invalid input → 400, Database down → 500, Timeout → 504"
authority: "AGENTS.md (route patterns), @secure-by-default (input validation)"

5) Run verification gates after every change

After each write:

npm test
npm run lint
npm run typecheck
python scripts/ci/forbidden_markers_scan.py --root .

If any gate fails, stop and fix before continuing.

6) Produce KAIZA-AUDIT block

After all changes are complete, produce a machine-checkable audit block:

KAIZA-AUDIT
Plan: implement-feature-x
Scope: src/features/x/handler.js, src/features/x/model.js, tests/features/x.test.js
Intent: Add HTTP API for feature X with structured logging and input validation
Key Decisions:
  - Used Express middleware for input validation (familiar, proven)
  - Stored feature X in new module to avoid tight coupling
  - Added correlation ID propagation for observability
Verification:
  - npm test: PASS (all tests pass, +3 new test cases)
  - npm run lint: PASS
  - npm run typecheck: PASS
  - forbidden_markers_scan.py: PASS
  - Coverage: 92% for feature X module (target: >80%)
Results: All gates pass. Code is ready for review.
Risk Notes: Feature X depends on external service Y; timeouts configured to 5s
Rollback: Revert commits or feature-flag can disable feature X via ENV var
KAIZA-AUDIT-END

7) Embed KAIZA-AUDIT in PR description

If using GitHub/GitLab:

• Paste the KAIZA-AUDIT block into the PR description
• CI will validate it has all required fields
• Reviewers use it to understand the scope and safety checks

Quality Checklist

• Approved plan selected (or proposed)
• All reads use Kaiza read_file
• All writes use Kaiza write_file with provenance metadata
• All verification gates pass after each change
• KAIZA-AUDIT block is produced with all required fields
• Plan scope is respected (no out-of-scope changes)
• Risk level is appropriate for the change
• Authority rules are referenced in KAIZA-AUDIT

Verification Commands

# Check that Kaiza tools are available
which kaiza || echo "Kaiza not available"

# Check that plans can be listed
kaiza list_plans

# Verify KAIZA-AUDIT format (locally)
grep -A 8 "^KAIZA-AUDIT$" PR_DESCRIPTION.md | grep -E "Plan:|Scope:|Intent:|Key Decisions:|Verification:|Results:|Risk Notes:|Rollback:"

How to Recover if Plan Boundary is Breached

If you realize you've made changes outside the plan scope:

1. Revert the out-of-scope changes
2. Propose a new or amended plan
3. Wait for approval
4. Resume the task with the updated plan

If a verification gate fails:

1. Stop and fix the issue
2. Re-run the gate
3. Continue only after gate passes

KAIZA-AUDIT Compliance

Every task using this skill must produce a KAIZA-AUDIT block with:

• Plan: Approved plan name
• Scope: Files/modules touched
• Intent: What outcome is delivered
• Key Decisions: Why these choices
• Verification: Exact commands executed and results
• Results: Pass/fail with artifacts
• Risk Notes: Remaining risks + mitigations
• Rollback: How to revert safely