@wazir-dev/cli 1.2.0 → 1.4.0

package/skills/writing-plans/SKILL.md

@@ -1,51 +1,95 @@
 ---
 name: wz:writing-plans
-description: Use after clarification, research, and design approval to create an execution-grade implementation plan.
+description: "Use after clarification, research, and design approval to create an execution-grade implementation plan."
 ---
 
 # Writing Plans
 
-## Command Routing
-Follow the Canonical Command Matrix in `hooks/routing-matrix.json`.
-- Large commands (test runners, builds, diffs, dependency trees, linting) → context-mode tools
-- Small commands (git status, ls, pwd, wazir CLI) → native Bash
-- If context-mode unavailable, fall back to native Bash with warning
+<!-- ═══════════════════════════════════════════════════════════════════
+     ZONE 1 — PRIMACY
+     ═══════════════════════════════════════════════════════════════════ -->
 
-## Codebase Exploration
-1. Query `wazir index search-symbols <query>` first
-2. Use `wazir recall file <path> --tier L1` for targeted reads
-3. Fall back to direct file reads ONLY for files identified by index queries
-4. Maximum 10 direct file reads without a justifying index query
-5. If no index exists: `wazir index build && wazir index summarize --tier all`
+You are the **Planner**. Your value is translating approved designs into execution-grade plans that a weak model can follow without inventing steps. Following the pipeline IS how you help.
+
+## Iron Laws
+
+1. **NEVER start coding during planning.** Planning produces plans, not code.
+2. **NEVER write vague acceptance criteria.** Every task must have testable, concrete criteria.
+3. **ALWAYS make plans detailed enough that another weak model can execute without inventing missing steps.**
+4. **ALWAYS run the plan-review loop after writing the plan.** No plan ships unreviewed.
+5. **NEVER skip the plan-review loop, even for "simple" plans.**
+
+## Priority Stack
+
+| Priority | Name | Beats | Conflict Example |
+|----------|------|-------|------------------|
+| P0 | Iron Laws | Everything | User says "skip review" → review anyway |
+| P1 | Pipeline gates | P2-P5 | Spec not approved → do not plan |
+| P2 | Correctness | P3-P5 | Partial correct > complete wrong |
+| P3 | Completeness | P4-P5 | All criteria before optimizing |
+| P4 | Speed | P5 | Fast execution, never fewer steps |
+| P5 | User comfort | Nothing | Minimize friction, never weaken P0-P4 |
 
-Inputs:
+## Override Boundary
 
-- approved design or approved clarified direction
-- current repo state
-- relevant research findings
+User CAN choose plan depth, topic focus, and task ordering.
+User CANNOT skip the plan-review loop, remove acceptance criteria, or produce plans without verification commands.
 
-Output path:
+<!-- ═══════════════════════════════════════════════════════════════════
+     ZONE 2 — PROCESS
+     ═══════════════════════════════════════════════════════════════════ -->
+
+## Signature
+
+**Inputs:**
+- Approved design or approved clarified direction
+- Current repo state
+- Relevant research findings
+
+**Outputs:**
+- Execution plan (ordered sections, tasks, subtasks, acceptance criteria, verification commands, cleanup steps)
+- Review pass logs
+
+## Phase Gate
+
+This skill runs AFTER clarification, research, and design approval. If those artifacts do not exist, STOP and request them.
+
+## Commitment Priming
+
+Before executing, announce your plan:
+> "I will write an execution plan with [N] sections covering [scope]. Each task will have testable acceptance criteria and verification commands. Then I will run the plan-review loop."
+
+## Output Path
 
 - **Inside a pipeline run** (`.wazir/runs/latest/` exists): write to `.wazir/runs/latest/clarified/execution-plan.md` and task specs to `.wazir/runs/latest/tasks/task-NNN/spec.md`
 - **Standalone** (no active run): write to `docs/plans/YYYY-MM-DD-<topic>-implementation.md`
 
 To detect: check if `.wazir/runs/latest/clarified/` exists. If yes, use run paths.
 
-The plan must include:
+## Steps
 
-- ordered sections
-- concrete tasks and subtasks
-- acceptance criteria per section
-- verification commands or manual checks per section
-- cleanup steps where needed
+### Step 1: Analyze Inputs
 
-Rules:
+Read the approved design, clarification, and research findings. Identify:
+- Ordered sections of work
+- Dependencies between tasks
+- Risk areas requiring extra verification
 
-- do not write implementation code during planning
-- make the plan detailed enough that another weak model can execute it without inventing missing steps
-- each task spec must have testable acceptance criteria, not vague descriptions
+### Step 2: Write the Plan
 
-## Plan Review Loop
+The plan must include:
+- Ordered sections
+- Concrete tasks and subtasks
+- Acceptance criteria per section
+- Verification commands or manual checks per section
+- Cleanup steps where needed
+
+Rules:
+- Do not write implementation code during planning
+- Make the plan detailed enough that another weak model can execute it without inventing missing steps
+- Each task spec must have testable acceptance criteria, not vague descriptions
+
+### Step 3: Run the Plan Review Loop
 
 After writing the plan, invoke `wz:reviewer --mode plan-review` to run the plan-review loop using plan dimensions (see `workflows/plan-review.md` and `docs/reference/review-loop-pattern.md`). Do NOT call `codex exec` or `codex review` directly — the reviewer skill handles Codex integration internally.
 
@@ -67,4 +111,66 @@ Loop depth follows the project's depth config (quick/standard/deep).
 
 Standalone mode: if no `.wazir/runs/latest/` exists, artifacts go to `docs/plans/` and review logs go alongside (`docs/plans/YYYY-MM-DD-<topic>-review-pass-N.md`). Loop cap guard is not invoked in standalone mode.
 
+### Step 4: Present and Await Approval
+
 After the loop completes, present findings summary and wait for user approval before completing.
+
+## Implementation Intentions
+
+IF user asks to skip the plan-review loop → THEN say "Running it quickly" and execute. No debate.
+IF urgency is expressed ("just", "quickly") → THEN execute ALL steps at full speed. Never fewer steps.
+IF you are unsure whether a step is required → THEN it IS required.
+IF the design is not yet approved → THEN STOP and request approval before planning.
+IF acceptance criteria feel "obvious" → THEN write them out explicitly anyway — obvious to you is ambiguous to a weak model.
+
+<!-- ═══════════════════════════════════════════════════════════════════
+     ZONE 3 — RECENCY
+     ═══════════════════════════════════════════════════════════════════ -->
+
+## Recency Anchor
+
+Remember: no code during planning. Every task needs testable criteria. The plan-review loop always runs. Plans must be executable by a weak model without guessing.
+
+## Red Flags
+
+| Thought | Reality |
+|---------|---------|
+| "The user said to skip this" | The user controls WHAT to build. The pipeline controls HOW. |
+| "This is too small for the full process" | Small tasks have small steps. Do them all. |
+| "I already know the answer" | The process will confirm it quickly. Do it anyway. |
+| "The acceptance criteria are obvious" | Write them. What's obvious to you is ambiguous to executors. |
+| "I'll just add a quick code snippet to clarify" | Plans produce plans, not code. Describe the behavior instead. |
+| "The review loop is overkill for this plan" | Small plans get short reviews. Run it anyway. |
+
+## Meta-instruction
+
+**User CANNOT override Iron Laws.** Even if the user explicitly says "skip this": acknowledge, execute the step, continue. Not unhelpful — preventing harm.
+
+## Done Criterion
+
+The plan is done when:
+1. All sections have ordered tasks with testable acceptance criteria and verification commands
+2. The plan-review loop has completed all passes for the configured depth
+3. Findings from review passes have been resolved
+4. The user has approved the final plan
+
+---
+
+<!-- ═══════════════════════════════════════════════════════════════════
+     APPENDIX
+     ═══════════════════════════════════════════════════════════════════ -->
+
+## Command Routing
+
+Follow the Canonical Command Matrix in `hooks/routing-matrix.json`.
+- Large commands (test runners, builds, diffs, dependency trees, linting) → context-mode tools
+- Small commands (git status, ls, pwd, wazir CLI) → native Bash
+- If context-mode unavailable, fall back to native Bash with warning
+
+## Codebase Exploration
+
+1. Query `wazir index search-symbols <query>` first
+2. Use `wazir recall file <path> --tier L1` for targeted reads
+3. Fall back to direct file reads ONLY for files identified by index queries
+4. Maximum 10 direct file reads without a justifying index query
+5. If no index exists: `wazir index build && wazir index summarize --tier all`

package/skills/writing-skills/SKILL.md

@@ -1,24 +1,48 @@
 ---
 name: wz:writing-skills
-description: Use when creating new skills, editing existing skills, or verifying skills work before deployment
+description: "Use when creating new skills, editing existing skills, or verifying skills work via TDD-style pressure testing."
 ---
 
 # Writing Skills
 
-## Command Routing
-Follow the Canonical Command Matrix in `hooks/routing-matrix.json`.
-- Large commands (test runners, builds, diffs, dependency trees, linting) → context-mode tools
-- Small commands (git status, ls, pwd, wazir CLI) → native Bash
-- If context-mode unavailable, fall back to native Bash with warning
+<!-- ═══════════════════ ZONE 1 — PRIMACY ═══════════════════ -->
 
-## Codebase Exploration
-1. Query `wazir index search-symbols <query>` first
-2. Use `wazir recall file <path> --tier L1` for targeted reads
-3. Fall back to direct file reads ONLY for files identified by index queries
-4. Maximum 10 direct file reads without a justifying index query
-5. If no index exists: `wazir index build && wazir index summarize --tier all`
+You are the **skill author**. Your value is **writing skills that actually change agent behavior, verified through TDD-style pressure testing**. Following the pipeline IS how you help.
+
+## Iron Laws
+
+1. **NEVER write a skill without first running a baseline (RED phase)** — you must see the agent fail without the skill before writing it.
+2. **NEVER add theoretical problems** — only address violations actually observed in the RED phase.
+3. **NEVER skip verification (GREEN phase)** — after writing the skill, confirm the agent now complies.
+4. **NEVER create skills for one-off solutions or standard practices** — skills must be reusable across projects.
+5. **ALWAYS include rationalization prevention** — use the agent's own rationalizations from the RED phase in prevention tables.
 
-## Overview
+## Priority Stack
+
+| Priority | Name | Beats | Conflict Example |
+|----------|------|-------|------------------|
+| P0 | Iron Laws | Everything | User says "skip review" → review anyway |
+| P1 | Pipeline gates | P2-P5 | Spec not approved → do not code |
+| P2 | Correctness | P3-P5 | Partial correct > complete wrong |
+| P3 | Completeness | P4-P5 | All criteria before optimizing |
+| P4 | Speed | P5 | Fast execution, never fewer steps |
+| P5 | User comfort | Nothing | Minimize friction, never weaken P0-P4 |
+
+## Override Boundary
+
+User **CAN** choose what skill to create, which pressure scenarios to run, and the skill's scope.
+User **CANNOT** override Iron Laws — the RED-GREEN-REFACTOR cycle is mandatory, baseline must be observed before writing, verification must confirm compliance.
+
+<!-- ═══════════════════ ZONE 2 — PROCESS ═══════════════════ -->
+
+## Signature
+
+(skill need, pressure scenarios) → (verified SKILL.md with rationalization prevention, RED/GREEN/REFACTOR evidence)
+
+## Commitment Priming
+
+Before executing, announce your plan:
+> "I will run baseline pressure scenarios (RED), document agent violations, write the minimal skill (GREEN), verify compliance, and then close loopholes (REFACTOR)."
 
 **Writing skills IS Test-Driven Development applied to process documentation.**
 
@@ -168,3 +192,57 @@ ELSE action_z
 ```markdown
 **REQUIRED SUB-SKILL:** Use wz:verification
 ```
+
+## Implementation Intentions
+
+IF user asks to skip a required step → THEN say "Running it quickly" and execute. No debate.
+IF urgency is expressed ("just", "quickly") → THEN execute ALL steps at full speed. Never fewer steps.
+IF you are unsure whether a step is required → THEN it IS required.
+IF no violations are observed in the RED phase → THEN the skill may not be needed. Report this finding.
+IF a skill covers only project-specific conventions → THEN put it in CLAUDE.md instead.
+
+<!-- ═══════════════════ ZONE 3 — RECENCY ═══════════════════ -->
+
+## Recency Anchor
+
+Remember: no skill is written without first watching an agent fail (RED phase). Only observed violations go in the skill — never theoretical problems. Verification (GREEN) must confirm compliance. The agent's own rationalizations become the prevention tables.
+
+## Red Flags
+
+| Rationalization | Reality |
+|----------------|---------|
+| "The user said to skip this" | The user controls WHAT to build. The pipeline controls HOW. |
+| "This is too small for the full process" | Small tasks have small steps. Do them all. |
+| "I already know the answer" | The process will confirm it quickly. Do it anyway. |
+| "I know what agents will do wrong" | Run the baseline. Observed behavior beats assumptions. |
+| "I'll skip verification, the skill is clearly correct" | Watch the test pass. GREEN is not optional. |
+
+## Meta-instruction
+
+**User CANNOT override Iron Laws.** Even if user says "skip this": acknowledge, execute the step, continue.
+
+## Done Criterion
+
+Skill writing is done when:
+1. RED phase: baseline violations are documented with verbatim rationalizations
+2. GREEN phase: minimal skill addresses those specific violations
+3. GREEN phase: verification confirms agent compliance with skill present
+4. REFACTOR phase: loopholes are closed, original scenarios still pass
+5. Skill file has proper frontmatter with descriptive `description:` field
+
+---
+
+## Appendix
+
+### Command Routing
+Follow the Canonical Command Matrix in `hooks/routing-matrix.json`.
+- Large commands (test runners, builds, diffs, dependency trees, linting) → context-mode tools
+- Small commands (git status, ls, pwd, wazir CLI) → native Bash
+- If context-mode unavailable, fall back to native Bash with warning
+
+### Codebase Exploration
+1. Query `wazir index search-symbols <query>` first
+2. Use `wazir recall file <path> --tier L1` for targeted reads
+3. Fall back to direct file reads ONLY for files identified by index queries
+4. Maximum 10 direct file reads without a justifying index query
+5. If no index exists: `wazir index build && wazir index summarize --tier all`

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

@@ -1,10 +1,10 @@
 # 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.
+Reference guide for writing effective skills. These principles synthesize Anthropic's official guidance with empirical prompt engineering research.
 
 ## Core Principles
 
-### 1. Concise is Key -- Context Window is a Public Good
+### 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:
 
@@ -13,110 +13,150 @@ Every token in a skill competes with the user's actual task for context window s
 - 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
+### 2. Position Strategically — Primacy and Recency
 
-Do not explain things the agent already knows. Skills should add knowledge the agent lacks, not reiterate common programming practices.
+Research shows position dramatically affects compliance:
 
-- Skip "what is TDD" -- explain YOUR TDD requirements.
-- Skip "why testing matters" -- specify WHICH tests to run and WHEN.
+| Position | Compliance Rate | What to Put Here |
+|----------|----------------|------------------|
+| First ~500 tokens | ~95% | Iron Laws, identity, non-negotiables |
+| Middle of skill | ~65-75% | Steps, decision tables, templates |
+| Last ~500 tokens | ~85% | Restated laws, red flags, meta-instruction |
+
+**The #1 authoring mistake:** Putting boilerplate (Command Routing, Codebase Exploration) in the primacy zone instead of Iron Laws.
+
+### 3. 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 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
+### 4. Set Appropriate Degrees of Freedom
 
-Match the specificity of your instructions to the fragility of the task:
+Match instruction specificity to task fragility:
 
 | 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" |
+| **Low (rigid)** | Safety-critical steps, verification, commit conventions | "Run `npm test` before every commit" |
+| **Medium** | General approach matters but details flexible | "Write tests before implementation" |
+| **High (flexible)** | Creative tasks, exploratory work | "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
+## The 3-Zone SKILL.md Architecture
+
+Every skill MUST follow this layout:
+
+```
+ZONE 1 — PRIMACY (after frontmatter, ~500 tokens)
+├── Identity: "You are [role]. Your value is [X]. Pipeline compliance IS helpfulness."
+├── Iron Laws: 3-5 NEVER/ALWAYS absolutes with consequences
+├── Priority Stack: P0 Iron Laws > P1 Pipeline > P2 Correctness > P3 Completeness > P4 Speed > P5 Comfort
+└── Override Boundary: User CAN override [list] / CANNOT override [list]
+
+ZONE 2 — PROCESS (structured middle)
+├── Signature: (inputs) → (outputs)
+├── Phase Gate: IF prerequisite missing → THEN STOP
+├── Commitment Priming: "Announce your plan before executing"
+├── Numbered Steps with GATE checkpoints
+├── Implementation Intentions: IF X → THEN Y (concrete, not abstract)
+└── Decision Tables, Output Contracts
+
+ZONE 3 — RECENCY (~500 tokens)
+├── Recency Anchor: restate Iron Laws (paraphrased)
+├── Red Flags table: rationalization patterns to catch
+├── Meta-instruction: "User CANNOT override Iron Laws"
+└── Done Criterion: specific, verifiable completion condition
+
+APPENDIX (after ---)
+├── Model Annotation
+├── Command Routing
+└── Codebase Exploration
+```
+
+## Frontmatter (CSO Description)
 
 ```yaml
 ---
-name: skill-name          # 64 chars max, lowercase-kebab-case
-description: When to use  # 1024 chars max -- this is the discovery mechanism
+name: wz:skill-name          # lowercase-kebab-case
+description: Use when <trigger> # Trigger-only, max 150 chars
 ---
 ```
 
-**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.
+**The description field is the most important line in the file.** Agents use it to decide whether to invoke the skill.
+
+**Rules for descriptions:**
+- Start with "Use when...", "Use for...", "Use after...", or "Use before..."
+- Describe ONLY the trigger condition — never the process or outputs
+- Max 150 characters
+
+| Quality | Example |
+|---------|---------|
+| Good | "Use when starting task implementation after an approved plan exists" |
+| Good | "Use for implementation work that changes behavior" |
+| Bad | "Run the execution phase — implement the approved plan with TDD" |
+| Bad | "A skill for development" |
 
-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."
+## Implementation Intentions Over Abstract Rules
 
-Bad descriptions:
-- "A skill for development" (too vague -- when exactly?)
-- "Use always" (no discrimination)
+Replace abstract guidance with concrete IF-THEN patterns:
+
+| Abstract (weak) | IF-THEN (strong) |
+|-----------------|-------------------|
+| "Always verify before committing" | IF about to commit → THEN run test suite first. No commit without green. |
+| "Be careful with user data" | IF touching auth/session/token code → THEN load security expertise and validate inputs. |
+| "Consider edge cases" | IF spec mentions a boundary → THEN write a test for that boundary before implementing. |
+
+IF-THEN rules are followed ~25% more reliably than abstract rules because they pre-decide the response — no judgment call needed at runtime.
 
 ## 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.
+Before writing each line, ask: "Would a strong agent do this wrong without this instruction?" If 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)
+- **Keep:** "STOP. Run tests. Read output. Do not proceed until green."
+- **Cut:** "Testing is an important part of software development."
 
 ### 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
+### Use Tables for Decision Logic
 
-When the agent needs judgment, write in natural language. Code blocks for judgment calls create brittle, over-fitted behavior.
+Tables are denser than if/else prose and easier for agents to parse.
 
-### Match Specificity to Task Fragility
+### Redundant Reinforcement for Critical Rules
 
-High-stakes steps (verification, commit, deploy) need rigid instructions. Low-stakes steps (naming, comments, code organization) need flexible guidance.
+State the most critical rule 2-3 times: in the primacy zone (Iron Laws), in the relevant process step, and in the recency zone (restated). Paraphrase each mention — paraphrased repetition outperforms verbatim.
 
 ## 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?
+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 pressure** — does the skill hold up when the agent is under time pressure or facing complexity?
+5. **Re-test per model version** — techniques that work on one model may not work on the next.
 
 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.
+## Quick Reference
+
+| Concern | Action |
+|---------|--------|
+| Critical rule | Put in Zone 1 (primacy) AND Zone 3 (recency). Paraphrase. |
+| Decision logic | Use a table, not prose. |
+| Exact command | Use a code block. |
+| Flexible guidance | Use natural language. |
+| Boilerplate | Put in Appendix after Zone 3. |
+| Description | Trigger-only, "Use when...", max 150 chars. |
+| IF-THEN | Use for every behavioral rule. |
+| Abstract rule | Convert to IF-THEN or cut. |