@wazir-dev/cli 1.0.0

package/skills/writing-skills/anthropic-best-practices.md

@@ -0,0 +1,122 @@
+# Anthropic Best Practices for Skill Authoring
+
+Reference guide for writing effective skills. These principles come from Anthropic's official guidance on custom instructions and skill files.
+
+## Core Principles
+
+### 1. Concise is Key -- Context Window is a Public Good
+
+Every token in a skill competes with the user's actual task for context window space. Treat context like a shared resource:
+
+- Cut ruthlessly. If a sentence doesn't change agent behavior, remove it.
+- Prefer tables and lists over prose paragraphs.
+- One clear statement beats three hedged ones.
+- If the skill is over 200 lines, ask whether every section earns its tokens.
+
+### 2. Default Assumption: The Agent is Already Very Smart
+
+Do not explain things the agent already knows. Skills should add knowledge the agent lacks, not reiterate common programming practices.
+
+- Skip "what is TDD" -- explain YOUR TDD requirements.
+- Skip "why testing matters" -- specify WHICH tests to run and WHEN.
+- Focus on project-specific decisions, not general wisdom.
+
+### 3. Set Appropriate Degrees of Freedom
+
+Match the specificity of your instructions to the fragility of the task:
+
+| Degree | When to Use | Example |
+|--------|-------------|---------|
+| **Low (rigid)** | Exact output format matters, safety-critical steps, commit message conventions | "Run `npm test` before every commit" |
+| **Medium** | General approach matters but details are flexible | "Write tests before implementation" |
+| **High (flexible)** | Creative tasks, exploratory work, agent judgment is valuable | "Improve the error messages" |
+
+Wrong degree of freedom is the most common skill authoring mistake. Too rigid on creative tasks kills quality. Too flexible on critical steps invites shortcuts.
+
+## SKILL.md Format
+
+```yaml
+---
+name: skill-name          # 64 chars max, lowercase-kebab-case
+description: When to use  # 1024 chars max -- this is the discovery mechanism
+---
+```
+
+**The description field is the most important line in the file.** Agents use it to decide whether to invoke the skill. A vague description means the skill is never used. An overly broad description means it fires when it shouldn't.
+
+Good descriptions:
+- "Use when creating new skills, editing existing skills, or verifying skills work before deployment"
+- "Use for implementation work that changes behavior. Follow RED -> GREEN -> REFACTOR with evidence at each step."
+
+Bad descriptions:
+- "A skill for development" (too vague -- when exactly?)
+- "Use always" (no discrimination)
+
+## Authoring Rules
+
+### Only Add Context the Agent Doesn't Already Have
+
+Before writing each line, ask: "Would a strong agent do this wrong without this instruction?" If the answer is no, cut the line.
+
+### Challenge Each Piece for Token Cost
+
+Every instruction has a cost (tokens consumed) and a benefit (behavior changed). Instructions that don't change behavior are pure cost:
+
+- **Keep:** "STOP. Run tests. Read output. Do not proceed until green." (changes behavior)
+- **Cut:** "Testing is an important part of software development." (agent already knows this)
+
+### Use Code Blocks for Precise Operations
+
+When exact commands or formats matter, use code blocks. Text instructions are interpreted; code blocks are followed literally.
+
+```bash
+# Precise -- agent will run this exact command
+git diff --stat HEAD~1
+
+# Imprecise -- agent will improvise
+"Check what changed in the last commit"
+```
+
+### Use Text Instructions for Flexible Guidance
+
+When the agent needs judgment, write in natural language. Code blocks for judgment calls create brittle, over-fitted behavior.
+
+### Match Specificity to Task Fragility
+
+High-stakes steps (verification, commit, deploy) need rigid instructions. Low-stakes steps (naming, comments, code organization) need flexible guidance.
+
+## Testing Skills
+
+Writing a skill is not enough. You must verify it works:
+
+1. **Test with real usage** -- set up scenarios where the skill would be needed.
+2. **Check discovery** -- does the agent find and invoke the skill at the right time?
+3. **Verify compliance** -- does the agent follow the skill's instructions?
+4. **Test edge cases** -- what happens at the boundaries?
+5. **Test pressure** -- does the skill hold up when the agent is under time pressure or facing complexity?
+
+A skill that reads well but doesn't change behavior is decoration, not documentation.
+
+## Structure Guidelines
+
+### Prefer Flat Over Nested
+
+Deeply nested headers (h4, h5) signal a skill that's trying to do too much. Split into multiple skills or flatten the hierarchy.
+
+### Put the Most Important Rule First
+
+Agents weight early content more heavily. Lead with the behavior you most need to change.
+
+### Use Tables for Decision Logic
+
+Tables are denser than if/else prose and easier for agents to parse:
+
+| Situation | Action |
+|-----------|--------|
+| Tests fail | Fix before proceeding |
+| Tests pass | Continue to next step |
+| Tests flaky | Investigate root cause |
+
+### End with a Quick Reference
+
+For longer skills, a condensed summary at the bottom helps agents that loaded the skill but need a fast reminder.

package/skills/writing-skills/persuasion-principles.md

@@ -0,0 +1,50 @@
+# Persuasion Principles for Skill Design
+
+## Overview
+
+LLMs respond to the same persuasion principles as humans. Understanding this psychology helps you design more effective skills - not to manipulate, but to ensure critical practices are followed even under pressure.
+
+**Research foundation:** Meincke et al. (2025) tested 7 persuasion principles with N=28,000 AI conversations. Persuasion techniques more than doubled compliance rates (33% -> 72%, p < .001).
+
+## The Seven Principles
+
+### 1. Authority
+- Imperative language: "YOU MUST", "Never", "Always"
+- Non-negotiable framing: "No exceptions"
+- Eliminates decision fatigue and rationalization
+
+### 2. Commitment
+- Require announcements: "Announce skill usage"
+- Force explicit choices: "Choose A, B, or C"
+- Use tracking: TodoWrite for checklists
+
+### 3. Scarcity
+- Time-bound requirements: "Before proceeding"
+- Sequential dependencies: "Immediately after X"
+- Prevents procrastination
+
+### 4. Social Proof
+- Universal patterns: "Every time", "Always"
+- Failure modes: "X without Y = failure"
+- Establishes norms
+
+### 5. Unity
+- Collaborative language: "our codebase", "we're colleagues"
+- Shared goals: "we both want quality"
+
+### 6. Reciprocity
+- Obligation to return favors
+- "I'll give you full context, you give me honest assessment"
+
+### 7. Liking
+- Avoid in discipline-enforcing skills
+- Use sparingly for collaborative skills
+
+## Principle Combinations by Skill Type
+
+| Skill Type | Use | Avoid |
+|------------|-----|-------|
+| Discipline-enforcing | Authority + Commitment + Social Proof | Liking, Reciprocity |
+| Guidance/technique | Moderate Authority + Unity | Heavy authority |
+| Collaborative | Unity + Commitment | Authority, Liking |
+| Reference | Clarity only | All persuasion |

package/templates/README.md

@@ -0,0 +1,20 @@
+# templates/
+
+This directory holds canonical artifact templates and examples.
+
+Allowed:
+
+- artifact templates
+- schema-aligned examples
+- documentation templates
+
+Not allowed:
+
+- live run outputs
+- stale copied artifacts used as placeholders
+
+Rules:
+
+- Templates must match their schemas.
+- Examples should be minimal, truthful, and runnable where applicable.
+- Artifact templates under `templates/artifacts/` are the canonical starting point for phase outputs and handoffs.

package/templates/artifacts/README.md

@@ -0,0 +1,10 @@
+# Artifact Templates
+
+These templates are the canonical starting point for Wazir run outputs and committed examples.
+
+Rules:
+
+- include run ID, phase, role, loop number, and sources
+- include approval status when the artifact is approval-gated
+- cite evidence for non-trivial claims
+- do not turn these templates into live run output or placeholder fake artifacts

package/templates/artifacts/accepted-learning.md

@@ -0,0 +1,19 @@
+---
+artifact_type: accepted_learning
+phase: learn
+role: learner
+run_id: <run-id>
+loop: 1
+status: accepted
+sources:
+  - <proposed-learning>
+approval_status: accepted
+---
+
+# Accepted Learning
+
+## Scope Tags
+
+## Evidence
+
+## Adoption Guidance

package/templates/artifacts/accepted-learning.template.json

@@ -0,0 +1,12 @@
+{
+  "run_id": "<run-id>",
+  "phase": "learn",
+  "role": "learner",
+  "loop": 1,
+  "status": "accepted",
+  "sources": [
+    "<proposed-learning>"
+  ],
+  "scope_tags": [],
+  "adoption_guidance": "<guidance>"
+}

package/templates/artifacts/author.md

@@ -0,0 +1,74 @@
+---
+artifact_type: author
+phase: author
+role: author
+run_id: <run-id>
+loop: 1
+status: draft
+sources:
+  - <spec-artifact>
+approval_status: required
+---
+
+# Author Artifact
+
+## Microcopy
+
+| Key | Text | Context | Max Length |
+|-----|------|---------|-----------|
+|     |      |         |           |
+
+## i18n Keys
+
+| Key | EN | Description |
+|-----|-----|-------------|
+|     |     |             |
+
+## Seed Data
+
+| Entity | Records |
+|--------|---------|
+|        |         |
+
+## Terminology
+
+| Term | Definition | Avoid |
+|------|------------|-------|
+|      |            |       |
+
+## Asset Metadata
+
+| Asset | Alt Text | Purpose |
+|-------|----------|---------|
+|       |          |         |
+
+## State Coverage
+
+| State   | Copy |
+|---------|------|
+| empty   |      |
+| loading |      |
+| error   |      |
+| success |      |
+| partial |      |
+
+## Notifications
+
+| Trigger | Message | Channel |
+|---------|---------|---------|
+|         |         |         |
+
+## Editorial Constraints
+
+| Constraint    | Value |
+|---------------|-------|
+| tone          |       |
+| voice         |       |
+| reading_level |       |
+| banned_words  |       |
+
+## Coverage Matrix
+
+| Screen | States Covered | Notes |
+|--------|----------------|-------|
+|        |                |       |

package/templates/artifacts/author.template.json

@@ -0,0 +1,19 @@
+{
+  "run_id": "<run-id>",
+  "phase": "author",
+  "role": "author",
+  "loop": 1,
+  "status": "draft",
+  "sources": [
+    "<spec-artifact>"
+  ],
+  "microcopy": [],
+  "i18n_keys": [],
+  "seed_data": [],
+  "terminology": [],
+  "asset_metadata": [],
+  "state_coverage": {},
+  "notifications": [],
+  "editorial_constraints": {},
+  "coverage_matrix": []
+}

package/templates/artifacts/clarification.md

@@ -0,0 +1,21 @@
+---
+artifact_type: clarification
+phase: clarify
+role: clarifier
+run_id: <run-id>
+loop: 1
+status: draft
+sources:
+  - input/<briefing-file>
+approval_status: not_required
+---
+
+# Clarification
+
+## Scope Summary
+
+## Open Questions
+
+## Constraints
+
+## Evidence

package/templates/artifacts/clarification.template.json

@@ -0,0 +1,12 @@
+{
+  "run_id": "<run-id>",
+  "phase": "clarify",
+  "role": "clarifier",
+  "loop": 1,
+  "status": "draft",
+  "sources": [
+    "input/<briefing-file>"
+  ],
+  "scope_summary": "<summary>",
+  "questions": []
+}

package/templates/artifacts/execute-notes.md

@@ -0,0 +1,19 @@
+---
+artifact_type: execute_notes
+phase: execute
+role: executor
+run_id: <run-id>
+loop: 1
+status: in_progress
+sources:
+  - <implementation-plan>
+approval_status: not_required
+---
+
+# Execution Notes
+
+## Tasks Completed
+
+## Commands Run
+
+## Deviations Or Blockers

package/templates/artifacts/implementation-plan.md

@@ -0,0 +1,21 @@
+---
+artifact_type: implementation_plan
+phase: plan
+role: planner
+run_id: <run-id>
+loop: 1
+status: draft
+sources:
+  - <approved-spec>
+approval_status: required
+---
+
+# Implementation Plan
+
+## Sections
+
+## Tasks And Subtasks
+
+## Acceptance Criteria
+
+## Verification

package/templates/artifacts/implementation-plan.template.json

@@ -0,0 +1,11 @@
+{
+  "run_id": "<run-id>",
+  "phase": "plan",
+  "role": "planner",
+  "loop": 1,
+  "status": "draft",
+  "sources": [
+    "<approved-spec>"
+  ],
+  "sections": []
+}

package/templates/artifacts/learning-proposal.md

@@ -0,0 +1,19 @@
+---
+artifact_type: proposed_learning
+phase: learn
+role: learner
+run_id: <run-id>
+loop: 1
+status: proposed
+sources:
+  - <review-findings>
+approval_status: required
+---
+
+# Proposed Learning
+
+## Scope
+
+## Evidence
+
+## Expected Benefit

package/templates/artifacts/next-run-handoff.md

@@ -0,0 +1,21 @@
+---
+artifact_type: next_run_handoff
+phase: prepare_next
+role: planner
+run_id: <run-id>
+loop: 1
+status: draft
+sources:
+  - <run-summary>
+approval_status: not_required
+---
+
+# Next Run Handoff
+
+## Current State
+
+## Required Inputs
+
+## Open Blockers
+
+## Approved Carry-Forward Context

package/templates/artifacts/plan-review.md

@@ -0,0 +1,19 @@
+---
+artifact_type: plan_review
+phase: plan_review
+role: reviewer
+run_id: <run-id>
+loop: 1
+status: draft
+sources:
+  - <implementation-plan>
+approval_status: required
+---
+
+# Plan Review
+
+## Blocking Findings
+
+## Follow-Up Tasks
+
+## Review Verdict

package/templates/artifacts/proposed-learning.template.json

@@ -0,0 +1,12 @@
+{
+  "run_id": "<run-id>",
+  "phase": "learn",
+  "role": "learner",
+  "loop": 1,
+  "status": "proposed",
+  "sources": [
+    "<review-findings>"
+  ],
+  "scope_tags": [],
+  "evidence": []
+}

package/templates/artifacts/research.md

@@ -0,0 +1,21 @@
+---
+artifact_type: research
+phase: discover
+role: researcher
+run_id: <run-id>
+loop: 1
+status: draft
+sources:
+  - input/<briefing-file>
+approval_status: not_required
+---
+
+# Research
+
+## Questions
+
+## Findings
+
+## Sources
+
+## Risks And Unknowns

package/templates/artifacts/research.template.json

@@ -0,0 +1,12 @@
+{
+  "run_id": "<run-id>",
+  "phase": "discover",
+  "role": "researcher",
+  "loop": 1,
+  "status": "draft",
+  "sources": [
+    "input/<briefing-file>"
+  ],
+  "findings": [],
+  "citations": []
+}

package/templates/artifacts/review-findings.md

@@ -0,0 +1,19 @@
+---
+artifact_type: review
+phase: review
+role: reviewer
+run_id: <run-id>
+loop: 1
+status: draft
+sources:
+  - <verification-proof>
+approval_status: required
+---
+
+# Review Findings
+
+## Findings
+
+## Evidence
+
+## Verdict

package/templates/artifacts/review.template.json

@@ -0,0 +1,11 @@
+{
+  "run_id": "<run-id>",
+  "phase": "review",
+  "role": "reviewer",
+  "loop": 1,
+  "status": "draft",
+  "sources": [
+    "<verification-proof>"
+  ],
+  "findings": []
+}

package/templates/artifacts/run-manifest.template.json

@@ -0,0 +1,8 @@
+{
+  "run_id": "<run-id>",
+  "project_slug": "<project-slug>",
+  "state_root": ".wazir-state/",
+  "phase": "clarify",
+  "status": "running",
+  "started_at": "<iso8601>"
+}

package/templates/artifacts/spec-challenge.md

@@ -0,0 +1,19 @@
+---
+artifact_type: spec_challenge
+phase: spec_challenge
+role: reviewer
+run_id: <run-id>
+loop: 1
+status: draft
+sources:
+  - <spec-artifact>
+approval_status: required
+---
+
+# Spec Challenge
+
+## Blocking Findings
+
+## Medium Findings
+
+## Resolved Questions

package/templates/artifacts/spec-challenge.template.json

@@ -0,0 +1,11 @@
+{
+  "run_id": "<run-id>",
+  "phase": "spec_challenge",
+  "role": "reviewer",
+  "loop": 1,
+  "status": "draft",
+  "sources": [
+    "<spec-artifact>"
+  ],
+  "findings": []
+}

package/templates/artifacts/spec.md

@@ -0,0 +1,21 @@
+---
+artifact_type: spec
+phase: specify
+role: specifier
+run_id: <run-id>
+loop: 1
+status: draft
+sources:
+  - <clarification-artifact>
+approval_status: required
+---
+
+# Specification
+
+## Objective
+
+## Acceptance Criteria
+
+## Non-Goals
+
+## Assumptions

package/templates/artifacts/spec.template.json

@@ -0,0 +1,12 @@
+{
+  "run_id": "<run-id>",
+  "phase": "specify",
+  "role": "specifier",
+  "loop": 1,
+  "status": "draft",
+  "sources": [
+    "<clarification-artifact>"
+  ],
+  "acceptance_criteria": [],
+  "non_goals": []
+}

package/templates/artifacts/verification-proof.md

@@ -0,0 +1,19 @@
+---
+artifact_type: verification_proof
+phase: verify
+role: verifier
+run_id: <run-id>
+loop: 1
+status: draft
+sources:
+  - <execution-notes>
+approval_status: required
+---
+
+# Verification Proof
+
+## Claims
+
+## Commands And Results
+
+## Pass Fail Summary

package/templates/artifacts/verification-proof.template.json

@@ -0,0 +1,11 @@
+{
+  "run_id": "<run-id>",
+  "phase": "verify",
+  "role": "verifier",
+  "loop": 1,
+  "status": "draft",
+  "sources": [
+    "<execution-notes>"
+  ],
+  "checks": []
+}