anvil-dev-framework 0.1.6

package/global/commands/change.md

@@ -0,0 +1,197 @@
+# /change - Brownfield Change Proposal
+
+> Document proposed changes to existing code with clear delta markers.
+
+## When to Use
+- When modifying existing functionality
+- For refactoring existing code
+- When change impacts multiple existing files
+- To document migration or upgrade plans
+
+## Why This Exists
+Most work is **brownfield** (modifying existing code), not greenfield. Change documents capture:
+- What exists now (baseline)
+- What will change (delta)
+- Impact on existing functionality
+- Migration considerations
+
+## Execution Steps
+
+### Step 1: Document Current State
+Read and understand existing code:
+- Current behavior
+- Current file structure
+- Current dependencies
+- Current tests
+
+### Step 2: Write Change Proposal
+
+Create file at: `.claude/changes/CHANGE-[issue-key]-[slug].md`
+
+Template:
+```markdown
+---
+change_id: CHANGE-[number]
+title: [Change Description]
+status: draft | approved | implemented
+created: YYYY-MM-DD
+linear_issue: [Issue key]
+risk_level: low | medium | high
+---
+
+# Change Proposal: [Title]
+
+## Summary
+[1-2 sentence description of the change]
+
+## Motivation
+[Why is this change needed? What problem does it solve?]
+
+## Current State
+[Description of how things work now]
+
+### Affected Files (Current)
+| File | Purpose | Lines |
+|------|---------|-------|
+| src/components/X.tsx | [Current purpose] | ~150 |
+| src/hooks/useX.ts | [Current purpose] | ~80 |
+
+## Proposed Changes
+
+### File: src/components/X.tsx
+
+#### MODIFIED: Function `handleSubmit`
+```typescript
+// BEFORE (lines 45-55)
+const handleSubmit = async (data: FormData) => {
+  await api.submit(data);
+  router.push('/success');
+};
+
+// AFTER
+const handleSubmit = async (data: FormData) => {
+  // ADDED: Validation step
+  const validated = await validateData(data);
+  if (!validated.success) {
+    setError(validated.error);
+    return;
+  }
+  // MODIFIED: Use validated data
+  await api.submit(validated.data);
+  router.push('/success');
+};
+```
+
+#### ADDED: New state
+```typescript
+// ADDED at line 12
+const [error, setError] = useState<string | null>(null);
+```
+
+#### REMOVED: Deprecated prop
+```typescript
+// REMOVED from props interface
+interface Props {
+  // REMOVED: legacyMode: boolean;
+  onSuccess: () => void;
+}
+```
+
+---
+
+### File: src/hooks/useX.ts
+
+#### MODIFIED: Return type
+```typescript
+// BEFORE
+return { data, loading };
+
+// AFTER
+return { data, loading, error }; // ADDED: error
+```
+
+## New Files
+| File | Purpose |
+|------|---------|
+| src/utils/validation.ts | New validation utilities |
+
+## Deleted Files
+| File | Reason |
+|------|--------|
+| src/legacy/oldHelper.ts | Replaced by new validation |
+
+## Impact Analysis
+
+### Breaking Changes
+- [ ] API contract changes: [Yes/No - details]
+- [ ] Database schema changes: [Yes/No - details]
+- [ ] Environment variable changes: [Yes/No - details]
+
+### Affected Consumers
+| Consumer | Impact | Migration Needed |
+|----------|--------|------------------|
+| [Component/Service] | [Impact] | [Yes/No] |
+
+### Test Impact
+- [ ] Existing tests need updates: [List tests]
+- [ ] New tests needed: [List new tests]
+
+## Migration Plan
+[If breaking changes, how will migration happen?]
+
+1. [Step 1]
+2. [Step 2]
+3. [Step 3]
+
+## Rollback Plan
+[How to revert if something goes wrong]
+
+## Risk Assessment
+| Risk | Likelihood | Impact | Mitigation |
+|------|------------|--------|------------|
+| [Risk] | Low/Med/High | Low/Med/High | [Mitigation] |
+
+## Open Questions
+- [ ] [Question]
+```
+
+### Step 3: Request Approval
+
+Output:
+```
+## Change Proposal Created
+
+**File**: .claude/changes/CHANGE-[key]-[slug].md
+**Risk Level**: [low/medium/high]
+
+### Change Summary
+- **Files Modified**: X
+- **Files Added**: Y  
+- **Files Deleted**: Z
+- **Breaking Changes**: [Yes/No]
+
+### Key Changes
+1. [Change 1 summary]
+2. [Change 2 summary]
+
+**Next Step**: Review and approve change proposal, then run `/plan` to create implementation plan.
+```
+
+## Delta Markers
+Use consistent markers in code blocks:
+- `// ADDED:` - New code being added
+- `// MODIFIED:` - Existing code being changed
+- `// REMOVED:` - Code being deleted
+- `// BEFORE` / `// AFTER` - For showing transformations
+
+## Key Behaviors
+- Always show current state before changes
+- Use delta markers consistently
+- Highlight breaking changes prominently
+- Include rollback plan for risky changes
+- Think about migration for consumers
+
+## Integration Points
+- May follow: `/explore` discovery
+- Precedes: `/plan` (or may replace `/spec` for pure refactors)
+- Creates: `.claude/changes/CHANGE-*.md`

package/global/commands/clarify.md

@@ -0,0 +1,252 @@
+# /clarify - Interactive Requirement Disambiguation
+
+> Use AskUserQuestion to gather explicit decisions when requirements are ambiguous.
+
+## When to Use
+- Requirements contain "or" / alternatives
+- Multiple valid approaches exist
+- Scope is fuzzy or negotiable
+- Before writing a specification with open questions
+- When you need explicit decisions before implementation
+
+## When NOT to Use
+- Requirements are clear and unambiguous
+- User has already provided detailed specifications
+- Simple yes/no questions (just ask directly)
+
+## Execution Steps
+
+### Step 1: Identify Ambiguities
+
+Analyze the request for:
+- **Alternatives**: "We could use X or Y"
+- **Scope questions**: "Should this include Z?"
+- **Technical choices**: "Which library/pattern/approach?"
+- **Priorities**: "What matters most: speed, cost, simplicity?"
+- **Constraints**: "Any limitations on the solution?"
+
+### Step 2: Convert to Structured Questions
+
+For each ambiguity, create an AskUserQuestion entry:
+
+**Guidelines:**
+- **header**: Max 12 characters, noun-like ("Provider", "Scope", "Priority")
+- **question**: Full sentence ending with "?"
+- **multiSelect**: `true` if multiple options can be chosen together
+- **options**: 2-4 choices, most recommended first with "(Recommended)"
+- **descriptions**: Why this option, what it enables/implies
+
+### Step 3: Present Questions via AskUserQuestion
+
+```typescript
+AskUserQuestion({
+  questions: [
+    {
+      header: "[short-label]",
+      question: "[Full question text?]",
+      multiSelect: [true/false],
+      options: [
+        { label: "[Option 1] (Recommended)", description: "[Why choose this]" },
+        { label: "[Option 2]", description: "[Why choose this]" },
+        { label: "[Option 3]", description: "[Why choose this]" }
+      ]
+    },
+    // ... up to 4 questions per call
+  ]
+})
+```
+
+**Note**: User can always select "Other" to provide custom input.
+
+### Step 4: Chain Additional Questions if Needed
+
+If more than 4 questions, or if answers reveal new questions:
+- Process first batch of answers
+- Ask follow-up questions based on selections
+- Continue until all ambiguities resolved
+
+### Step 5: Generate Clarification Report
+
+After gathering all answers, output:
+
+```markdown
+## Clarification Report
+
+**Feature**: [Feature name]
+**Date**: [YYYY-MM-DD]
+
+### Decisions Captured
+
+| Question | Answer | Rationale |
+|----------|--------|-----------|
+| [Question 1] | [Selected option] | [From description or user input] |
+| [Question 2] | [Selected option(s)] | [Rationale] |
+
+### Resolved Ambiguities
+1. **[Topic]**: Decided on [choice] because [reason]
+2. **[Topic]**: Decided on [choice] because [reason]
+
+### Remaining Open Questions
+- [Any questions that couldn't be resolved]
+
+### Next Steps
+- Run `/spec` to create specification with these decisions
+- Or run `/explore` if more discovery needed first
+```
+
+---
+
+## Examples
+
+### Example 1: Authentication Feature
+
+**Input**: "Add user authentication to the app"
+
+**Analysis**: Multiple ambiguities detected:
+- Which auth provider?
+- Session handling approach?
+- 2FA requirement?
+
+**AskUserQuestion call**:
+```typescript
+AskUserQuestion({
+  questions: [
+    {
+      header: "Provider",
+      question: "Which authentication provider should we implement?",
+      multiSelect: false,
+      options: [
+        { label: "Google OAuth (Recommended)", description: "Widest adoption, fastest setup" },
+        { label: "GitHub OAuth", description: "Developer-focused audience" },
+        { label: "Email/Password", description: "Traditional, no external dependency" },
+        { label: "Multiple providers", description: "Support several options" }
+      ]
+    },
+    {
+      header: "2FA",
+      question: "Is two-factor authentication required?",
+      multiSelect: false,
+      options: [
+        { label: "Yes (Recommended)", description: "Required for security compliance" },
+        { label: "Optional", description: "Users can enable if they want" },
+        { label: "No", description: "Not needed for this use case" }
+      ]
+    },
+    {
+      header: "Session",
+      question: "How long should user sessions last?",
+      multiSelect: false,
+      options: [
+        { label: "24 hours (Recommended)", description: "Balance between UX and security" },
+        { label: "1 week", description: "Convenience-focused" },
+        { label: "1 hour", description: "High-security environment" }
+      ]
+    }
+  ]
+})
+```
+
+### Example 2: Feature Scope
+
+**Input**: "Improve the search functionality"
+
+**Analysis**: Scope is vague - what improvements?
+
+**AskUserQuestion call**:
+```typescript
+AskUserQuestion({
+  questions: [
+    {
+      header: "Scope",
+      question: "Which search improvements should we prioritize?",
+      multiSelect: true,
+      options: [
+        { label: "Faster results", description: "Optimize query performance" },
+        { label: "Better relevance", description: "Improve ranking algorithm" },
+        { label: "More filters", description: "Add filtering options" },
+        { label: "Autocomplete", description: "Suggestions as user types" }
+      ]
+    },
+    {
+      header: "Priority",
+      question: "What matters most for this improvement?",
+      multiSelect: false,
+      options: [
+        { label: "User experience (Recommended)", description: "Make it feel fast and intuitive" },
+        { label: "Accuracy", description: "Ensure results are highly relevant" },
+        { label: "Feature parity", description: "Match competitor capabilities" }
+      ]
+    }
+  ]
+})
+```
+
+### Example 3: Technical Architecture
+
+**Input**: "Add real-time updates to the dashboard"
+
+**Analysis**: Technical approach unclear
+
+**AskUserQuestion call**:
+```typescript
+AskUserQuestion({
+  questions: [
+    {
+      header: "Approach",
+      question: "Which real-time technology should we use?",
+      multiSelect: false,
+      options: [
+        { label: "WebSockets (Recommended)", description: "Full duplex, lowest latency" },
+        { label: "Server-Sent Events", description: "Simpler, server-to-client only" },
+        { label: "Polling", description: "Simplest, works everywhere" }
+      ]
+    },
+    {
+      header: "Updates",
+      question: "Which dashboard elements need real-time updates?",
+      multiSelect: true,
+      options: [
+        { label: "Metrics/stats", description: "Numbers and charts" },
+        { label: "Activity feed", description: "Recent actions list" },
+        { label: "Notifications", description: "Alerts and messages" },
+        { label: "All elements", description: "Full dashboard refresh" }
+      ]
+    }
+  ]
+})
+```
+
+---
+
+## Best Practices
+
+### Question Design
+1. **Be specific**: "Which auth provider?" not "How should auth work?"
+2. **Provide context**: Descriptions should explain implications
+3. **Recommend wisely**: First option should be genuinely best for most cases
+4. **Limit options**: 2-4 choices per question, not exhaustive lists
+
+### When to Chain Questions
+- First question reveals scope for follow-ups
+- User selects "Other" and provides context that needs clarification
+- More than 4 distinct decision points exist
+
+### Storing Decisions
+Always capture clarification answers for future reference:
+- Include in specification document
+- Reference in implementation plan
+- Add to Linear issue description
+
+---
+
+## Integration Points
+- **Precedes**: `/spec`, `/plan`, `/explore`
+- **Used by**: Any command encountering ambiguity
+- **Stores**: Decisions in clarification report
+- **References**: Linear issues, existing specifications
+
+## Key Behaviors
+- **Always offer "Other"**: AskUserQuestion includes this automatically
+- **Don't over-ask**: If answer is obvious, don't ask
+- **Batch related questions**: Group related decisions in one call
+- **Follow up intelligently**: New questions based on answers, not pre-planned