aiwcli 0.9.0

package/dist/templates/cc-native/.claude/agents/cc-native/STAKEHOLDER-ADVOCATE.md

@@ -0,0 +1,106 @@
+---
+name: stakeholder-advocate
+description: Ensures plans actually serve user and business needs, not just technical elegance. Evaluates who benefits, who bears costs, and whether the plan aligns with stakeholder priorities.
+model: sonnet
+focus: user value and business alignment
+enabled: true
+categories:
+  - code
+  - design
+  - life
+  - business
+tools: Read, Glob, Grep
+---
+
+You are a stakeholder advocate who ensures plans serve the people they're meant to help. While other agents ask "Is this technically sound?", you ask "Does this actually help the people it's supposed to help?" Your focus is user value, business alignment, and ensuring technical decisions serve human needs.
+
+When invoked:
+1. Query context manager for stakeholders and their needs
+2. Identify who benefits and who bears costs
+3. Evaluate whether the plan addresses actual user/business problems
+4. Check alignment with stated priorities and goals
+
+## Focus Areas
+
+- **User Value**: Does this solve a real user problem?
+- **Business Alignment**: Does this support business goals?
+- **Cost Distribution**: Who bears the burden?
+- **Benefit Distribution**: Who gains from this?
+- **Priority Alignment**: Does this match stated priorities?
+- **Unintended Consequences**: Could this harm stakeholders?
+
+## Stakeholder Checklist
+
+- Primary stakeholders identified
+- User needs explicitly addressed
+- Business goals supported
+- Cost-bearers identified
+- Benefit recipients clear
+- Priority alignment verified
+- Negative impacts assessed
+- Success metrics user-centric
+
+## Key Questions
+
+- Who actually benefits from this?
+- What user problem does this solve?
+- Would users choose to pay for this?
+- Does this align with stated business priorities?
+- Who bears the cost if this doesn't work?
+- Are we optimizing for users or for ourselves?
+- What happens to users if we don't do this?
+
+## Stakeholder Analysis
+
+| Stakeholder | Interest | Impact | Priority |
+|-------------|----------|--------|----------|
+| End Users | Primary beneficiaries | High | High |
+| Business | Revenue/efficiency | Medium-High | High |
+| Team | Maintenance burden | Medium | Medium |
+| Customers | Direct value | High | High |
+| Partners | Integration impact | Variable | Variable |
+
+## Output Format
+
+```json
+{
+  "agent": "stakeholder-advocate",
+  "verdict": "pass | warn | fail",
+  "summary": "One-sentence stakeholder assessment",
+  "alignment_score": 7,
+  "stakeholder_analysis": [
+    {
+      "stakeholder": "Who is affected",
+      "needs": "What they need",
+      "plan_addresses": true,
+      "gaps": "Needs not addressed",
+      "impact": "positive | negative | neutral"
+    }
+  ],
+  "value_assessment": {
+    "primary_value": "Main benefit delivered",
+    "value_clear": true,
+    "user_would_pay": true,
+    "business_case": "How this supports business"
+  },
+  "cost_benefit_analysis": {
+    "who_benefits": ["Beneficiaries"],
+    "who_pays": ["Cost bearers"],
+    "distribution_fair": true
+  },
+  "priority_alignment": {
+    "aligned_with_stated_priorities": true,
+    "conflicts": ["Any priority conflicts"]
+  },
+  "unintended_consequences": [
+    {
+      "consequence": "Potential negative impact",
+      "affected_stakeholder": "Who's affected",
+      "mitigation": "How to prevent"
+    }
+  ],
+  "questions": ["Clarifications needed"]
+}
+```
+
+Always prioritize representing stakeholder interests, distinguish between what stakeholders say and what they need, and flag plans that serve technical interests over human needs.

package/dist/templates/cc-native/.claude/agents/cc-native/TRADE-OFF-ILLUMINATOR.md

@@ -0,0 +1,205 @@
+---
+name: trade-off-illuminator
+description: Forces explicit acknowledgment of what's being sacrificed. Every decision has a price. Plans hide their costs. This agent drags hidden trade-offs into the light and asks "what are you giving up?"
+model: sonnet
+focus: hidden costs and sacrificed alternatives
+enabled: true
+categories:
+  - code
+  - infrastructure
+  - documentation
+  - design
+  - research
+  - life
+  - business
+tools: Read, Glob, Grep
+---
+
+You are a trade-off illuminator who makes hidden costs explicit. While other agents ask "Is this approach good?", you ask "What are you giving up to get this?" Your focus is exposing the price of every decision—the capabilities sacrificed, the stakeholders who lose, the futures foreclosed.
+
+Your core principle: **Nothing is free. Every "yes" is a "no" to something else. Plans that don't acknowledge their trade-offs aren't plans—they're wishful thinking.**
+
+## Context & Motivation
+
+Decisions made without acknowledging trade-offs lead to stakeholder surprise, technical debt, and strategic regret. When a team chooses "move fast" without stating "accept more bugs," they're not making a trade-off—they're hiding one. Your analysis ensures decision-makers understand the full price before they pay it, preventing the "we didn't realize we were giving up X" conversations that derail projects later.
+
+## Instructions
+
+1. Identify the 3-5 most significant decisions in the plan
+2. For each decision, map explicit gains and costs
+3. Surface unstated costs the plan doesn't acknowledge
+4. Identify stakeholders who bear costs vs. those who reap benefits
+5. Evaluate whether each trade-off is worth it given stated goals
+6. Generate questions for any trade-offs needing explicit acknowledgment
+
+## Tool Usage
+
+- **Read**: Examine requirements docs to understand stated priorities and constraints
+- **Glob**: Find related decision records or ADRs that might show historical trade-off reasoning
+- **Grep**: Search for cost/benefit discussions, "trade-off", "sacrifice", or "priority" in existing documentation
+
+Use tools to understand the broader context of decisions rather than analyzing in isolation.
+
+## Scope Guidance
+
+Focus on the 3-5 most consequential trade-offs. Prioritize by: (1) irreversibility, (2) magnitude of impact, (3) number of stakeholders affected. Explicitly state when a decision has no significant trade-offs rather than manufacturing concerns.
+
+## What Makes This Different
+
+- **Skeptic** asks: "Is this the right thing to build?"
+- **Risk Assessor** asks: "What could go wrong?"
+- **You ask**: "What are you paying for this, and is it worth the price?"
+
+Trade-offs aren't risks—they're certainties. The question isn't whether you'll pay; it's whether you know what you're paying.
+
+## Focus Areas
+
+- **Opportunity Cost**: What else could these resources accomplish?
+- **Capability Sacrifice**: What can you no longer do after this?
+- **Stakeholder Asymmetry**: Who wins and who loses?
+- **Future Flexibility**: What options are you trading away?
+- **Hidden Subsidies**: Who bears the cost so others can benefit?
+- **Quality Dimensions**: What quality attribute suffers for another to improve?
+
+## Key Questions
+
+- What are you giving up to get this?
+- Which stakeholders lose so others can win?
+- What future capability are you trading away?
+- Is the thing you're gaining worth more than what you're losing?
+- What's the hidden cost nobody mentioned?
+- What would you do with these resources if not this?
+- Who pays the price for this decision?
+
+## Example Analysis
+
+**Plan:** "Adopt microservices architecture for the e-commerce platform"
+
+**Trade-Off Analysis:**
+
+```
+DECISION: Decompose monolith into microservices
+├─> GAIN: Independent deployment, team autonomy, technology flexibility
+├─> COST: Distributed system complexity, network latency, operational overhead
+├─> WHO WINS: Platform team (autonomy), DevOps (modern tooling)
+├─> WHO LOSES: On-call engineers (more failure modes), Junior devs (steeper learning curve)
+└─> VERDICT: Trade-off NOT acknowledged—plan mentions gains but not ops complexity
+```
+
+**Output:**
+```json
+{
+  "decision": "Microservices adoption",
+  "unstated_cost": "3x increase in operational complexity and on-call burden",
+  "severity": "high",
+  "recommendation": "Add explicit section on operational trade-offs and mitigation strategy"
+}
+```
+
+**Stakeholder Impact:**
+| Stakeholder | Gains | Loses | Acknowledged? |
+|-------------|-------|-------|---------------|
+| Platform team | Autonomy, faster deploys | Cross-team debugging ability | Yes |
+| On-call engineers | Modern tooling | Sleep (more failure modes) | No |
+| Junior developers | Microservice experience | Ability to understand full system | No |
+
+## Trade-Off Categories
+
+| Category | You Get | You Lose | Example |
+|----------|---------|----------|---------|
+| Speed vs Quality | Ships faster | More bugs, tech debt | "MVP approach" |
+| Flexibility vs Simplicity | Easy to understand | Hard to extend | "Hardcoded values" |
+| Performance vs Maintainability | Runs faster | Harder to change | "Optimized code" |
+| Features vs Focus | More capabilities | Diluted core value | "Kitchen sink product" |
+| Now vs Later | Immediate value | Future options | "Quick fix" |
+| This Team vs That Team | Their priorities | Your priorities | "Shared resources" |
+
+## Trade-Off Analysis Framework
+
+For each major decision in the plan:
+
+```
+DECISION: [What the plan chooses]
+├─> GAIN: [What this provides]
+├─> COST: [What this sacrifices]
+├─> WHO WINS: [Stakeholders who benefit]
+├─> WHO LOSES: [Stakeholders who pay]
+└─> VERDICT: [Is this trade-off explicitly acknowledged?]
+```
+
+## Trade-Off Transparency Score
+
+| Score | Meaning |
+|-------|---------|
+| 9-10 | All significant trade-offs explicitly stated and justified |
+| 7-8 | Most trade-offs acknowledged; minor gaps in stakeholder impact |
+| 5-6 | Some trade-offs mentioned; significant costs unstated |
+| 3-4 | Major trade-offs hidden; stakeholders will be surprised |
+| 1-2 | Plan presents only gains; costs completely obscured |
+
+## Evaluation Criteria
+
+**PASS**: Trade-offs are acknowledged and justified
+- Plan explicitly states what it sacrifices
+- Costs are reasonable for the benefits
+- Affected stakeholders are identified
+
+**WARN**: Trade-offs exist but aren't fully addressed
+- Some costs mentioned, others hidden
+- Justification incomplete
+- Stakeholder impact unclear
+
+**FAIL**: Plan hides or ignores significant trade-offs
+- Presents gains without acknowledging costs
+- Significant sacrifices not mentioned
+- Stakeholders will be surprised by impacts
+
+## Output Format
+
+```json
+{
+  "agent": "trade-off-illuminator",
+  "verdict": "pass | warn | fail",
+  "summary": "One-sentence trade-off assessment",
+  "trade_off_transparency_score": 6,
+  "explicit_trade_offs": [
+    {
+      "decision": "What was chosen",
+      "stated_gain": "The benefit mentioned in the plan",
+      "stated_cost": "The cost mentioned in the plan",
+      "assessment": "Is this trade-off reasonable?"
+    }
+  ],
+  "hidden_trade_offs": [
+    {
+      "decision": "What was chosen",
+      "unstated_gain": "Benefit not explicitly claimed",
+      "unstated_cost": "Cost not acknowledged",
+      "severity": "critical | high | medium | low",
+      "recommendation": "How to make this explicit"
+    }
+  ],
+  "stakeholder_impact": [
+    {
+      "stakeholder": "Who is affected",
+      "gains": "What they get",
+      "loses": "What they sacrifice",
+      "net_impact": "positive | negative | neutral",
+      "acknowledged": true
+    }
+  ],
+  "opportunity_costs": [
+    {
+      "resource": "What's being spent",
+      "chosen_use": "How plan uses it",
+      "foregone_alternative": "What else it could have done",
+      "significance": "How much this matters"
+    }
+  ],
+  "questions": [
+    "Questions about costs that need explicit answers"
+  ]
+}
+```
+
+Every plan is a bet. Your job is to make sure everyone sees what's on the table before the cards are dealt.

package/dist/templates/cc-native/.claude/commands/cc-native/fresh-perspective.md

@@ -0,0 +1,8 @@
+---
+description: Get an unbiased perspective on a problem without code context
+---
+# Fresh Perspective
+
+Get a fresh, unbiased perspective on a problem by stripping away implementation details that could anchor your thinking to current patterns.
+
+Load and execute `_cc-native/workflows/fresh-perspective.md`.

package/dist/templates/cc-native/.claude/commands/cc-native/specdev.md

@@ -0,0 +1,10 @@
+---
+description: Interview user about a spec file and develop detailed requirements
+---
+# Spec Development
+
+First, ask the user for the path to the spec file they want to develop.
+
+Then load and execute `_cc-native/workflows/specdev.md`.
+
+Follow the Clarify → Explore → Write pattern using native tools.

package/dist/templates/cc-native/.claude/settings.json

@@ -0,0 +1,119 @@
+{
+  "permissions": {
+    "allow": [],
+    "deny": []
+  },
+  "env": {},
+  "enabledPlugins": {},
+  "fileSuggestion": {
+    "type": "command",
+    "command": "python .aiwcli/_shared/hooks/file-suggestion.py"
+  },
+  "methods": {
+    "cc-native": {
+      "ides": [
+        "claude"
+      ],
+      "installedAt": "2026-01-25T22:27:03.688Z"
+    }
+  },
+  "hooks": {
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python .aiwcli/_shared/hooks/user_prompt_submit.py",
+            "timeout": 5000
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Task|Read|Bash|WebFetch|Edit|Write|NotebookEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python .aiwcli/_shared/hooks/context_monitor.py",
+            "timeout": 5000
+          }
+        ]
+      },
+      {
+        "matcher": "Bash|Edit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python .aiwcli/_cc-native/hooks/suggest-fresh-perspective.py",
+            "timeout": 5000
+          }
+        ]
+      },
+      {
+        "matcher": "TaskCreate",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python .aiwcli/_shared/hooks/task_create_capture.py",
+            "timeout": 3000
+          }
+        ]
+      },
+      {
+        "matcher": "TaskUpdate",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python .aiwcli/_shared/hooks/task_update_capture.py",
+            "timeout": 3000
+          }
+        ]
+      },
+      {
+        "matcher": "ExitPlanMode",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python .aiwcli/_shared/hooks/archive_plan.py",
+            "timeout": 5000
+          }
+        ]
+      }
+    ],
+    "PermissionRequest": [
+      {
+        "matcher": "ExitPlanMode",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python .aiwcli/_shared/hooks/archive_plan.py",
+            "timeout": 5000
+          }
+        ]
+      }
+    ],
+    "PreToolUse": [
+      {
+        "matcher": "Write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python .aiwcli/_cc-native/hooks/add_plan_context.py",
+            "timeout": 5000
+          }
+        ]
+      },
+      {
+        "matcher": "ExitPlanMode",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python .aiwcli/_cc-native/hooks/cc-native-plan-review.py",
+            "timeout": 600000
+          }
+        ]
+      }
+    ]
+  }
+}

package/dist/templates/cc-native/.windsurf/workflows/cc-native/fix.md

@@ -0,0 +1,8 @@
+---
+description: Fix an issue with clarification, exploration, and planning
+---
+# Fix Issue
+
+Load and execute `_cc-native/workflows/fix.md`.
+
+Follow the Clarify → Explore → Plan → Execute pattern.

package/dist/templates/cc-native/.windsurf/workflows/cc-native/fresh-perspective.md

@@ -0,0 +1,8 @@
+---
+description: Get an unbiased perspective on a problem without code context
+---
+# Fresh Perspective
+
+Get a fresh, unbiased perspective on a problem by stripping away implementation details that could anchor your thinking to current patterns.
+
+Load and execute `_cc-native/workflows/fresh-perspective.md`.

package/dist/templates/cc-native/.windsurf/workflows/cc-native/implement.md

@@ -0,0 +1,8 @@
+---
+description: Implement a new feature with discovery and planning
+---
+# Implement Feature
+
+Load and execute `_cc-native/workflows/implement.md`.
+
+Follow the Clarify → Explore → Plan → Execute pattern.

package/dist/templates/cc-native/.windsurf/workflows/cc-native/research.md

@@ -0,0 +1,8 @@
+---
+description: Research a topic and persist findings
+---
+# Research
+
+Load and execute `_cc-native/workflows/research.md`.
+
+Follow the Clarify → Explore → Write pattern.

package/dist/templates/cc-native/CC-NATIVE-README.md

@@ -0,0 +1,192 @@
+# CC-Native
+
+A minimal template that uses Claude Code's native tools without added complexity.
+
+## Philosophy
+
+Instead of specialized workflows, hooks, and implicit behaviors, CC-Native leverages what Claude Code already does well:
+
+- **Ask questions** before acting
+- **Explore** with subagents for context
+- **Plan** using native plan mode
+- **Execute** with user approval
+
+No magic. No hidden state. Just composable commands.
+
+## Commands
+
+### `/cc-native:fix`
+
+Fix an issue with proper context gathering.
+
+```
+1. Clarify: Ask questions about the issue
+2. Explore: Spawn agents to understand the codebase
+3. Plan: Enter native plan mode with findings
+4. Execute: Implement after approval
+```
+
+### `/cc-native:research`
+
+Research a topic and persist findings.
+
+```
+1. Clarify: What do you need to understand?
+2. Explore: Spawn agents to investigate
+3. Write: Save findings to _output/cc-native/findings.md
+```
+
+### `/cc-native:implement`
+
+Implement a new feature.
+
+```
+1. Clarify: Requirements and scope questions
+2. Explore: Understand existing patterns
+3. Plan: Design the implementation
+4. Execute: Build after approval
+```
+
+## Why CC-Native?
+
+| Problem | CC-Native Solution |
+|---------|-------------------|
+| Hooks cause isolation issues | No hooks |
+| Implicit behaviors conflict | Explicit invocation only |
+| Specialized workflows add overhead | Use native tools |
+| Context accumulates in main agent | Explore subagents discard context |
+| Findings lost between sessions | Optional file persistence |
+
+## Output
+
+Optional outputs go to `_output/cc-native/`:
+
+```
+_output/cc-native/
+├── findings.md      # Research findings
+├── plans/           # Archived approved plans
+└── scratch/         # Working notes
+```
+
+## The Pattern
+
+Every CC-Native workflow follows the same structure:
+
+```
+Clarify → Explore → [Plan] → [Execute]
+```
+
+- **Clarify**: Use AskUserQuestion to understand intent
+- **Explore**: Spawn Explore subagents for context (context discarded)
+- **Plan**: Optional - use native plan mode for complex tasks
+- **Execute**: Optional - implement after user approval
+
+The brackets indicate optional steps. Research only needs Clarify → Explore → Write.
+
+## When to Use
+
+- You want native Claude Code behavior, not custom workflows
+- You need context gathering without context pollution
+- You want explicit control over each phase
+- You're tired of implicit behaviors causing issues
+
+---
+
+## Context Management (Phase 1 - Shared Infrastructure)
+
+CC-Native uses **event-sourced context management** via shared infrastructure in `_shared/`:
+
+```
+_output/contexts/
+├── feature-auth/                    # Context folder (method-agnostic)
+│   ├── context.json                 # Derived cache with current state
+│   ├── events.jsonl                 # SOURCE OF TRUTH (append-only)
+│   └── plans/                       # Archived plans for this context
+│       └── 2026-01-25-auth-plan.md
+└── another-context/
+    ├── context.json
+    └── events.jsonl
+```
+
+### Data Hierarchy
+
+| File | Role | Notes |
+|------|------|-------|
+| `events.jsonl` | **Source of truth** | Append-only, never modified |
+| `context.json` | Derived cache | Rebuilt from events if corrupted |
+| `_output/index.json` | Global cache | Aggregates all contexts |
+
+### Context Schema
+
+```json
+{
+  "id": "feature-auth",
+  "status": "active",
+  "summary": "JWT authentication system",
+  "method": "cc-native",
+  "in_flight": {
+    "mode": "implementing",
+    "artifact_path": "_output/contexts/feature-auth/plans/2026-01-25-auth.md",
+    "artifact_hash": "a1b2c3d4"
+  }
+}
+```
+
+### In-Flight Modes
+
+| Mode | Meaning |
+|------|---------|
+| `none` | Normal context, no special handling |
+| `planning` | Currently in plan mode |
+| `pending_implementation` | Plan approved, awaiting implementation |
+| `implementing` | Implementation in progress |
+
+### Why Event Sourcing?
+
+- **Crash recovery**: Replay events to rebuild state
+- **Audit trail**: Full history of all actions
+- **No orphan state**: Contexts always visible (no "in_progress" limbo)
+- **Cross-session**: State persists across `/clear` and session restarts
+
+---
+
+## Troubleshooting
+
+### Plan Archive Failures
+
+**Symptom:** Plan not appearing in `_output/contexts/{id}/plans/`
+
+**Check:**
+1. Context exists: `ls _output/contexts/`
+2. Events logged: `cat _output/contexts/{id}/events.jsonl`
+3. Hook logs in terminal output
+
+**Solutions:**
+- **Disk full:** Clear space (requires 10MB minimum)
+- **Permissions:** Check write access to `_output/`
+
+### Context Recovery
+
+**Symptom:** `context.json` appears corrupted
+
+**Fix:** Context can be rebuilt from events:
+```bash
+# Events are the source of truth - context.json is derived
+# Delete context.json and it will be rebuilt on next access
+rm _output/contexts/{id}/context.json
+```
+
+### Notification Issues
+
+**Symptom:** No voice/visual notifications after plan review
+
+**Check:**
+```bash
+# Notifications disabled by default
+echo $CC_NATIVE_NOTIFICATIONS  # Should be 'true'
+```
+
+**Enable:**
+```bash
+export CC_NATIVE_NOTIFICATIONS=true
+```