Initial commit

2025-11-30 08:56:23 +08:00
commit 1c24761eb8
14 changed files with 2028 additions and 0 deletions
--- a/.claude-plugin/plugin.json
+++ b/.claude-plugin/plugin.json
@@ -0,0 +1,22 @@
+{
+  "name": "shavakan-commands",
+  "description": "Slash commands for dev docs workflow and repository cleanup",
+  "version": "1.2.3",
+  "author": {
+    "name": "shavakan",
+    "email": "cs.changwon.lee@gmail.com"
+  },
+  "commands": [
+    "./shavakan/docs-feature-plan.md",
+    "./shavakan/docs-save-context.md",
+    "./shavakan/docs-update.md",
+    "./shavakan/docs-readme.md",
+    "./shavakan/cleanup.md",
+    "./shavakan/cleanup-architecture.md",
+    "./shavakan/cleanup-comments.md",
+    "./shavakan/cleanup-dead-code.md",
+    "./shavakan/cleanup-deps.md",
+    "./shavakan/cleanup-docs.md",
+    "./shavakan/cleanup-duplication.md"
+  ]
+}
--- a/README.md
+++ b/README.md
@@ -0,0 +1,3 @@
+# shavakan-commands
+
+Slash commands for dev docs workflow and repository cleanup
--- a/plugin.lock.json
+++ b/plugin.lock.json
@@ -0,0 +1,85 @@
+{
+  "$schema": "internal://schemas/plugin.lock.v1.json",
+  "pluginId": "gh:Shavakan/claude-marketplace:commands",
+  "normalized": {
+    "repo": null,
+    "ref": "refs/tags/v20251128.0",
+    "commit": "537e63aadb037599f1137fd244b9404c8013bd6d",
+    "treeHash": "f1e210cb9a94275654e2a224bbd8fd0ea046e4928cc633b1f61e9286c26f32a8",
+    "generatedAt": "2025-11-28T10:12:47.499750Z",
+    "toolVersion": "publish_plugins.py@0.2.0"
+  },
+  "origin": {
+    "remote": "git@github.com:zhongweili/42plugin-data.git",
+    "branch": "master",
+    "commit": "aa1497ed0949fd50e99e70d6324a29c5b34f9390",
+    "repoRoot": "/Users/zhongweili/projects/openmind/42plugin-data"
+  },
+  "manifest": {
+    "name": "shavakan-commands",
+    "description": "Slash commands for dev docs workflow and repository cleanup",
+    "version": "1.2.3"
+  },
+  "content": {
+    "files": [
+      {
+        "path": "README.md",
+        "sha256": "8aadc078dbc46783be01f8a0c91a81fe37cf32eca6580220e925bc8bda571eda"
+      },
+      {
+        "path": "shavakan/cleanup-comments.md",
+        "sha256": "c27eac958c27c604e5a865fce7cb91f22895a822cdb0d0819d410d74470ae9b6"
+      },
+      {
+        "path": "shavakan/cleanup-docs.md",
+        "sha256": "eedfcaab655a7524a2ea171b6f57f3ec258154d5e02d8b0c7f6aad5577821d65"
+      },
+      {
+        "path": "shavakan/cleanup-deps.md",
+        "sha256": "708e12f702ecbbf1b20bab4c038e722ff218cb0f7ba3325368ffeb0112eff5d0"
+      },
+      {
+        "path": "shavakan/cleanup-duplication.md",
+        "sha256": "49c250a4f755fff5d806fd5f405d8fde27f082e6dcc71f2e4d3b5228c6b47c66"
+      },
+      {
+        "path": "shavakan/docs-readme.md",
+        "sha256": "e27c3d24002c063b13bc1189d6722038bf2d9ff0a7cd6dd6b5bc68ec4cfadb39"
+      },
+      {
+        "path": "shavakan/docs-update.md",
+        "sha256": "c5274ba3c55aae07cdeeb581539d6ff42ad8bbb2fbcdbd82a34c5dbb4c9e07c6"
+      },
+      {
+        "path": "shavakan/cleanup-architecture.md",
+        "sha256": "7609423379c561a316a6d1a752a62fd3cd746728ed8a7e4505ae9cde4d7c5e72"
+      },
+      {
+        "path": "shavakan/docs-feature-plan.md",
+        "sha256": "36e811a574035a7898172b08600cecb10ccd1908e80e6f0455a7a383ee6b377f"
+      },
+      {
+        "path": "shavakan/cleanup.md",
+        "sha256": "42590b55e38ee076e98b1dc3b95bde2388ef978f757e6b70ca512de479985acd"
+      },
+      {
+        "path": "shavakan/docs-save-context.md",
+        "sha256": "933c1ecb3b72247314dc067b6cb641a312434ceb5cdb8ea860b08fbc701756db"
+      },
+      {
+        "path": "shavakan/cleanup-dead-code.md",
+        "sha256": "8148a1cfcda965d74abde221dc10164b7ec81bf45a38624d815b17481c23f72b"
+      },
+      {
+        "path": ".claude-plugin/plugin.json",
+        "sha256": "525366c855b8eaf9d75089a653d3a1d287e965649e1a485130aaefff5fc5dfb2"
+      }
+    ],
+    "dirSha256": "f1e210cb9a94275654e2a224bbd8fd0ea046e4928cc633b1f61e9286c26f32a8"
+  },
+  "security": {
+    "scannedAt": null,
+    "scannerVersion": null,
+    "flags": []
+  }
+}
--- a/shavakan/cleanup-architecture.md
+++ b/shavakan/cleanup-architecture.md
@@ -0,0 +1,235 @@
+---
+description: Refactor structure - split god objects, break circular deps, improve separation of concerns
+---
+
+# Refactor Architecture
+
+Improve code structure: split god objects, break circular dependencies, improve separation of concerns.
+
+## Prerequisites
+
+**Safety requirements:**
+1. Git repository with clean working tree
+2. All tests passing before refactoring
+3. Backup branch created automatically
+4. Test validation after each refactor
+
+**Run prerequisite check:**
+
+```bash
+# Get the plugin root (where scripts are located)
+PLUGIN_ROOT="$HOME/.claude/plugins/marketplaces/shavakan"
+
+# Validate plugin root is under home directory
+if [[ ! "$PLUGIN_ROOT" =~ ^"$HOME"/.* ]]; then
+  echo "ERROR: Invalid plugin root path"
+  exit 1
+fi
+
+# Run prerequisites check and source output
+PREREQ_SCRIPT="$PLUGIN_ROOT/commands/cleanup/scripts/check-prerequisites.sh"
+if [[ ! -f "$PREREQ_SCRIPT" ]]; then
+  echo "ERROR: Prerequisites script not found at $PREREQ_SCRIPT"
+  exit 1
+fi
+
+# Capture output to temp file and source it
+PREREQ_OUTPUT=$(mktemp)
+if "$PREREQ_SCRIPT" > "$PREREQ_OUTPUT" 2>&1; then
+  source "$PREREQ_OUTPUT"
+  rm "$PREREQ_OUTPUT"
+else
+  cat "$PREREQ_OUTPUT"
+  rm "$PREREQ_OUTPUT"
+  exit 1
+fi
+```
+
+This exports: `TEST_CMD`, `BACKUP_BRANCH`, `LOG_FILE`
+
+---
+
+## Additional Instructions
+
+$ARGUMENTS
+
+---
+
+## Objective
+
+Identify and fix architecture issues that make code hard to maintain: god objects, circular dependencies, poor layer separation, high complexity, and long parameter lists.
+
+### Architecture Smells
+
+**God objects** - Files >300 lines or classes with too many responsibilities (detect via file size, import count, mixed concerns)
+
+**Circular dependencies** - Module A imports B, B imports A (creates tight coupling, import errors)
+
+**Poor separation** - Files mixing layers (controller + service + repository in one file, UI with business logic)
+
+**High complexity** - Functions with cyclomatic complexity >10, deeply nested conditionals, >50 lines
+
+**Long parameter lists** - Functions with 5+ parameters (should use options objects)
+
+---
+
+## Execution
+
+### Phase 1: Detect Architecture Issues
+
+Scan codebase for architecture smells using appropriate analysis tools for the language. For each issue found:
+- Identify the specific problem (what makes this a god object? which modules form the cycle?)
+- Assess impact (how is this hurting maintainability?)
+- Propose solution (split by domain? extract interface? introduce layer?)
+
+Present findings with prioritization:
+- **Critical**: Circular deps causing build issues, god objects blocking development
+- **High**: Poor separation causing bugs, complexity >15
+- **Medium**: Large files that are manageable, complexity 10-15
+
+**Gate**: User must review full audit before proceeding.
+
+### Phase 2: Prioritize with User
+
+Present audit findings with impact assessment:
+```
+Refactor architecture issues?
+
+□ Safest - Extract complex functions + convert long param lists
+□ Low risk - Split god objects by domain boundaries
+□ Medium risk - Break circular deps + separate mixed layers
+□ High risk - Major architectural refactoring
+□ Custom - Select specific issues
+□ Cancel
+```
+
+**Gate**: Get user approval on which issues and risk level to address.
+
+### Phase 3: Refactor Systematically
+
+For each approved issue:
+
+**Split god objects:**
+- Analyze file to identify distinct responsibilities (auth vs profile vs settings)
+- Propose domain-driven split with clear boundaries
+- Create new files for each responsibility
+- Move methods to appropriate files
+- Update all imports
+- Test after each file is moved
+
+**Break circular dependencies:**
+- Analyze cycle to understand why it exists
+- Choose approach: extract shared types, introduce interface, dependency inversion
+- Implement solution (e.g., create UserSummary type to break User ↔ Post cycle)
+- Update imports
+- Verify no circular reference remains
+
+**Separate layers:**
+- Identify mixed concerns (route handling + validation + business logic + DB in one file)
+- Create appropriate layer files (Controller, Validator, Service, Repository)
+- Move logic to correct layers
+- Update dependencies to flow one direction
+- Test layer boundaries work correctly
+
+**Reduce complexity:**
+- Extract methods for logical blocks
+- Replace nested conditionals with guard clauses
+- Introduce state pattern for workflow steps
+- Test behavior unchanged
+
+**Simplify parameters:**
+- Create options interface with all parameters
+- Update function signature
+- Update all call sites
+- Test all cases still work
+
+**Critical**: Each refactoring must preserve exact behavior. Tests must pass. If tests fail, rollback and investigate the difference.
+
+**Gate**: Tests must pass before moving to next refactoring.
+
+### Phase 4: Report Results
+
+Summarize improvements: god objects split (N → M files), circular deps broken (N cycles eliminated), complexity reduced (N functions simplified), maintainability impact.
+
+Delete the backup branch after successful completion:
+```bash
+git branch -D "$BACKUP_BRANCH"
+```
+
+---
+
+## Refactoring Patterns
+
+### Split God Object
+Extract cohesive responsibilities into focused modules:
+```typescript
+// Before: UserService (847 lines, does everything)
+class UserService {
+  authenticate() { }
+  updateProfile() { }
+  sendNotification() { }
+}
+
+// After: Split by domain
+class AuthService { authenticate() { } }
+class ProfileService { updateProfile() { } }
+class NotificationService { sendNotification() { } }
+```
+
+### Break Circular Dependency
+Extract shared types or introduce interfaces:
+```typescript
+// Before: User imports Post, Post imports User
+// Create shared type
+interface UserSummary { id: string; name: string; }
+
+// User can import Post (full)
+// Post only imports UserSummary (breaks cycle)
+```
+
+### Separate Layers
+Controller → Service → Repository:
+```typescript
+// Before: Everything in one function
+async function createOrder(req, res) {
+  if (!req.body.items) return res.status(400).send();
+  const total = calculateTotal(req.body.items);
+  const order = await db.orders.create({...});
+  res.json(order);
+}
+
+// After: Proper layering
+// Controller: HTTP handling only
+// Service: Business logic
+// Repository: Database access
+```
+
+---
+
+## Safety Constraints
+
+**CRITICAL:**
+- One refactoring at a time - test after each structural change
+- Preserve exact behavior - all tests must pass
+- Commit granularly - each refactoring gets its own commit
+- Never batch refactors - if one breaks, you can't identify which
+- Keep interfaces stable - don't break public APIs
+- Use types to catch breaking changes at compile time
+
+**If tests fail**: Rollback immediately, identify the specific change that broke behavior, understand why it's different from original.
+
+---
+
+## After Cleanup
+
+**Review with code-reviewer agent before pushing:**
+
+Use `shavakan-agents:code-reviewer` to verify refactorings don't introduce issues.
+
+---
+
+## Related Commands
+
+- `/shavakan-commands:cleanup` - Full repository audit
+- `/shavakan-commands:cleanup-dead-code` - Remove unused code
+- `/shavakan-commands:cleanup-duplication` - Remove code duplication
--- a/shavakan/cleanup-comments.md
+++ b/shavakan/cleanup-comments.md
@@ -0,0 +1,158 @@
+---
+description: Remove obvious comments, commented code, outdated TODOs - keep 'why' explanations
+---
+
+# Remove Comment Noise
+
+Remove comments that add zero value. Code should be self-documenting. Keep comments that explain "why" not "what".
+
+## Prerequisites
+
+**Safety requirements:**
+1. Git repository with clean working tree
+2. Backup branch created automatically
+3. Test validation after each change category (if tests exist)
+
+**Run prerequisite check:**
+
+```bash
+PLUGIN_ROOT="$HOME/.claude/plugins/marketplaces/shavakan"
+
+if [[ ! "$PLUGIN_ROOT" =~ ^"$HOME"/.* ]]; then
+  echo "ERROR: Invalid plugin root path"
+  exit 1
+fi
+
+PREREQ_SCRIPT="$PLUGIN_ROOT/commands/cleanup/scripts/check-prerequisites.sh"
+if [[ ! -f "$PREREQ_SCRIPT" ]]; then
+  echo "ERROR: Prerequisites script not found"
+  exit 1
+fi
+
+PREREQ_OUTPUT=$(mktemp)
+if "$PREREQ_SCRIPT" --skip-tests > "$PREREQ_OUTPUT" 2>&1; then
+  source "$PREREQ_OUTPUT"
+  rm "$PREREQ_OUTPUT"
+else
+  cat "$PREREQ_OUTPUT"
+  rm "$PREREQ_OUTPUT"
+  exit 1
+fi
+```
+
+This exports: `TEST_CMD`, `BACKUP_BRANCH`, `LOG_FILE`
+
+---
+
+## Additional Instructions
+
+$ARGUMENTS
+
+---
+
+## Objective
+
+Identify and remove comment noise across the codebase while preserving valuable "why" explanations.
+
+### Remove These
+
+**Obvious comments** - Repeat what code does ("increment counter" above `count++`)
+
+**Commented code blocks** - 5+ consecutive commented lines with code syntax (belongs in git history)
+
+**Outdated TODOs/FIXMEs** - >1 year old or already completed (check git blame)
+
+**Redundant documentation** - JSDoc/docstrings that add no value beyond signature (`@param user The user`)
+
+**Visual separators** - ASCII art, "end of section" markers (use file structure instead)
+
+### Preserve These
+
+**Non-obvious "why" explanations** - Why this approach vs alternatives
+
+**Workarounds** - Performance trade-offs, security considerations, edge cases
+
+**Hacks with justification** - Browser quirks, API limitations, temporary fixes with context
+
+---
+
+## Execution
+
+### Phase 1: Identify Comment Noise
+
+Scan codebase for all five categories. For each finding, capture:
+- Location (file:line or range)
+- Comment content and surrounding code
+- Why it's noise vs valuable
+
+Present findings grouped by category with counts. Include examples of valuable comments you're preserving to demonstrate understanding.
+
+Identify refactoring opportunities where improving code clarity (better names, extracted functions) would eliminate the need for explanatory comments.
+
+**Gate**: User must review findings before removal.
+
+### Phase 2: Confirm Scope
+
+Present findings to user:
+```
+Remove comment noise?
+
+□ Safest - Visual separators + obvious comments
+□ Low risk - Commented code blocks + redundant docs
+□ Needs review - Outdated TODOs (might still be relevant)
+□ Custom - Select specific categories
+□ Cancel
+```
+
+**Gate**: Get user approval on which categories to remove.
+
+### Phase 3: Execute Removals
+
+For each approved category:
+
+1. Consider refactoring first: If comment explains complex logic, can you make the code self-documenting instead?
+
+2. Remove comments: Edit files safely. Process one category completely before starting next.
+
+3. Test and commit: Run `$TEST_CMD` after each category. If tests pass, commit with message explaining what was removed. If tests fail, rollback and report which removal caused the issue.
+
+**Gate**: Tests must pass before proceeding to next category.
+
+### Phase 4: Report Results
+
+Summarize what was removed (counts per category), what was preserved, code improvements made, and impact (lines reduced, readability improved).
+
+Delete the backup branch after successful completion:
+```bash
+git branch -D "$BACKUP_BRANCH"
+```
+
+---
+
+## Safety Constraints
+
+**CRITICAL:**
+- One category at a time with test validation between each
+- Commit granularly - each category gets its own commit
+- When in doubt, preserve the comment
+- If comment explains complex code, refactor the code instead of removing comment
+- Never remove comments that justify non-obvious technical decisions
+- Test failure → rollback immediately, investigate before retrying
+
+**If tests fail**: Rollback with `git checkout . && git clean -fd`, identify which specific removal broke tests, decide whether to skip that item or investigate further.
+
+---
+
+## After Cleanup
+
+**Review with code-reviewer agent before pushing:**
+
+Use `shavakan-agents:code-reviewer` to verify changes don't introduce issues.
+
+---
+
+## Related Commands
+
+- `/shavakan-commands:cleanup` - Full repository audit
+- `/shavakan-commands:cleanup-dead-code` - Remove unused code
+- `/shavakan-commands:cleanup-deps` - Clean dependencies
--- a/shavakan/cleanup-dead-code.md
+++ b/shavakan/cleanup-dead-code.md
@@ -0,0 +1,155 @@
+---
+description: Remove unused imports, functions, variables, commented blocks, unreachable code
+---
+
+# Remove Dead Code
+
+Find and safely remove unused code: imports, functions, variables, commented blocks, unreachable code, unused files.
+
+## Prerequisites
+
+**Safety requirements:**
+1. Git repository with clean working tree
+2. All tests passing before cleanup
+3. Backup branch created automatically
+4. Test validation after each removal category
+
+**Run prerequisite check:**
+
+```bash
+PLUGIN_ROOT="$HOME/.claude/plugins/marketplaces/shavakan"
+
+if [[ ! "$PLUGIN_ROOT" =~ ^"$HOME"/.* ]]; then
+  echo "ERROR: Invalid plugin root path"
+  exit 1
+fi
+
+PREREQ_SCRIPT="$PLUGIN_ROOT/commands/cleanup/scripts/check-prerequisites.sh"
+if [[ ! -f "$PREREQ_SCRIPT" ]]; then
+  echo "ERROR: Prerequisites script not found"
+  exit 1
+fi
+
+PREREQ_OUTPUT=$(mktemp)
+if "$PREREQ_SCRIPT" > "$PREREQ_OUTPUT" 2>&1; then
+  source "$PREREQ_OUTPUT"
+  rm "$PREREQ_OUTPUT"
+else
+  cat "$PREREQ_OUTPUT"
+  rm "$PREREQ_OUTPUT"
+  exit 1
+fi
+```
+
+This exports: `TEST_CMD`, `BACKUP_BRANCH`, `LOG_FILE`
+
+---
+
+## Additional Instructions
+
+$ARGUMENTS
+
+---
+
+## Objective
+
+Identify and remove dead code that clutters the codebase without affecting functionality.
+
+### Categories
+
+**Unused imports** - Modules imported but never referenced
+
+**Unused functions** - Defined but never called, private methods with no references, exported with no external usage
+
+**Unused variables** - Declared but never read, parameters never used, constants not referenced
+
+**Commented code** - 5+ consecutive commented lines with code syntax (belongs in git history)
+
+**Unreachable code** - After return/throw/break, conditional branches that never execute
+
+**Unused files** - Source files with no imports, test files for deleted features, replaced implementations
+
+---
+
+## Execution
+
+### Phase 1: Detect Dead Code
+
+Scan codebase for unused code using language-appropriate static analysis. For each category:
+- Report locations with context
+- Verify findings (check for dynamic references, reflection, callbacks)
+- Count impact (lines that can be removed)
+
+**Be cautious with:**
+- Public API exports - check for external usage first
+- Test utilities - may be needed later even if not currently used
+- Code called dynamically (eval, reflection, event handlers)
+
+**Gate**: User must review findings before removal.
+
+### Phase 2: Confirm Removals
+
+Present findings to user with risk assessment:
+```
+Remove dead code?
+
+□ Safe - Unused imports + variables (auto-fixable)
+□ Low risk - Unused private functions + commented code
+□ Needs review - Unused public functions + unused files
+□ Custom - Select specific items
+□ Cancel
+```
+
+**Gate**: Get user approval on which categories to remove.
+
+### Phase 3: Execute Removals
+
+For each approved category:
+
+1. Remove items using language-specific tools when available (eslint --fix, autoflake). For functions/files, manual removal with careful validation.
+
+2. Test and commit: Run `$TEST_CMD` after each category. If passing, commit. If failing, rollback and report which removal broke tests.
+
+3. Continue safely: Process one category at a time. Stop on test failure.
+
+**Gate**: Tests must pass before moving to next category.
+
+### Phase 4: Report Results
+
+Summarize: items removed per category, files affected, lines eliminated, code coverage maintained.
+
+Delete the backup branch after successful completion:
+```bash
+git branch -D "$BACKUP_BRANCH"
+```
+
+---
+
+## Safety Constraints
+
+**CRITICAL:**
+- One category at a time with test validation
+- Never remove public API exports without confirming no external usage
+- Verify zero references using code search before removing
+- Test after each removal - rollback on failure
+- Commit granularly
+- Use `git rm` for file removal to preserve history
+- Check for dynamic references (code may be called via string identifiers)
+
+**If tests fail**: Rollback, identify which specific removal caused failure, decide whether to skip that item or investigate why it was actually needed.
+
+---
+
+## After Cleanup
+
+**Review with code-reviewer agent before pushing:**
+
+Use `shavakan-agents:code-reviewer` to verify removals don't introduce issues.
+
+---
+
+## Related Commands
+
+- `/shavakan-commands:cleanup` - Full repository audit
+- `/shavakan-commands:cleanup-comments` - Clean up comments
+- `/shavakan-commands:cleanup-architecture` - Refactor structure
--- a/shavakan/cleanup-deps.md
+++ b/shavakan/cleanup-deps.md
@@ -0,0 +1,174 @@
+---
+description: Clean dependencies - remove unused, fix security issues, update outdated, deduplicate
+---
+
+# Clean Up Dependencies
+
+Remove unused packages, fix security vulnerabilities, update outdated packages, eliminate duplicate versions.
+
+## Prerequisites
+
+**Safety requirements:**
+1. Git repository with clean working tree
+2. All tests passing before cleanup
+3. Backup branch created automatically
+4. Test validation after each dependency change
+
+**Run prerequisite check:**
+
+```bash
+PLUGIN_ROOT="$HOME/.claude/plugins/marketplaces/shavakan"
+
+if [[ ! "$PLUGIN_ROOT" =~ ^"$HOME"/.* ]]; then
+  echo "ERROR: Invalid plugin root path"
+  exit 1
+fi
+
+PREREQ_SCRIPT="$PLUGIN_ROOT/commands/cleanup/scripts/check-prerequisites.sh"
+if [[ ! -f "$PREREQ_SCRIPT" ]]; then
+  echo "ERROR: Prerequisites script not found"
+  exit 1
+fi
+
+PREREQ_OUTPUT=$(mktemp)
+if "$PREREQ_SCRIPT" > "$PREREQ_OUTPUT" 2>&1; then
+  source "$PREREQ_OUTPUT"
+  rm "$PREREQ_OUTPUT"
+else
+  cat "$PREREQ_OUTPUT"
+  rm "$PREREQ_OUTPUT"
+  exit 1
+fi
+```
+
+This exports: `TEST_CMD`, `BACKUP_BRANCH`, `LOG_FILE`
+
+---
+
+## Additional Instructions
+
+$ARGUMENTS
+
+---
+
+## Objective
+
+Clean up project dependencies across four categories:
+
+**Unused dependencies** - Installed but never imported, dev deps not used in build/test
+
+**Security vulnerabilities** - Packages with known CVEs (critical/high priority)
+
+**Outdated dependencies** - Packages with newer stable versions, major updates available
+
+**Duplicates** - Same package at multiple versions, conflicting peer dependencies
+
+---
+
+## Execution
+
+### Phase 1: Detect Package Manager & Scan
+
+Identify package manager (npm/pnpm/yarn/pip/cargo/go) from lockfiles.
+
+Scan dependencies for all four categories. Present findings grouped by category with counts and severity:
+- Critical vulnerabilities (fix immediately)
+- Unused packages (safe to remove)
+- Outdated packages (by semver level: major/minor/patch)
+- Duplicates (version conflicts)
+
+**Gate**: User must see full audit before proceeding.
+
+### Phase 2: Prioritize with User
+
+Present findings with risk assessment:
+- **Critical**: Security vulnerabilities (URGENT - fix immediately)
+- **Safe**: Unused dependencies (safe to remove after verification)
+- **Low risk**: Minor/patch updates (backwards compatible)
+- **Medium risk**: Major version updates (review breaking changes)
+- **Needs review**: Duplicate resolution (check compatibility)
+
+Offer update strategies:
+```
+Choose cleanup strategy:
+
+□ Conservative - Patch only, critical security fixes
+□ Moderate - Minor + patch, all security fixes
+□ Aggressive - All major updates (extensive testing required)
+□ Custom - Select specific categories
+□ Cancel
+```
+
+**Gate**: Get user approval on which categories and strategy level.
+
+### Phase 3: Execute Cleanup
+
+For each approved category:
+
+**Security vulnerabilities:**
+- Update to patched version
+- Check release notes for breaking changes
+- Update code if API changed
+- Test thoroughly
+
+**Unused dependencies:**
+- Verify not imported anywhere (check for dynamic requires)
+- Remove from package manifest
+- Clean lockfile
+- Test immediately
+
+**Outdated packages:**
+- Check CHANGELOG for breaking changes
+- Update one package at a time (or related packages together)
+- Update code for API changes
+- Test after each update
+
+**Duplicates:**
+- Choose version to keep (usually newer)
+- Use resolutions/overrides if needed
+- Rebuild lockfile
+- Test compatibility
+
+**Critical safety constraint**: One change at a time. Test after each. Commit on success, rollback on failure.
+
+**Gate**: Tests must pass before moving to next category.
+
+### Phase 4: Report Results
+
+Summarize: vulnerabilities fixed (by severity), unused removed, packages updated (major/minor/patch), duplicates resolved, overall security/maintenance improvement.
+
+Delete the backup branch after successful completion:
+```bash
+git branch -D "$BACKUP_BRANCH"
+```
+
+---
+
+## Safety Constraints
+
+**CRITICAL:**
+- Security fixes first - prioritize over cosmetic improvements
+- One package change at a time - test between each
+- Read release notes before major updates
+- Commit granularly
+- Don't blindly auto-fix - some fixes introduce breaking changes
+- Keep lockfiles - commit package-lock.json, yarn.lock, etc.
+- Check peer dependencies after updates
+
+**If tests fail**: Rollback, check if jumping too many versions, try intermediate version, review release notes for breaking changes.
+
+---
+
+## After Cleanup
+
+**Review with code-reviewer agent before pushing:**
+
+Use `shavakan-agents:code-reviewer` to verify changes don't introduce issues.
+
+---
+
+## Related Commands
+
+- `/shavakan-commands:cleanup` - Full repository audit
+- `/shavakan-commands:cleanup-dead-code` - Remove unused code
+- `/shavakan-commands:cleanup-architecture` - Refactor structure
--- a/shavakan/cleanup-docs.md
+++ b/shavakan/cleanup-docs.md
@@ -0,0 +1,181 @@
+---
+description: Sync documentation with code - fix dead links, update API docs, remove outdated content
+---
+
+# Sync Documentation with Code
+
+Ensure docs accurately reflect current codebase. Remove outdated content, fix dead links, update API docs.
+
+## Prerequisites
+
+**Safety requirements:**
+1. Git repository with clean working tree
+2. Backup branch created automatically
+3. Validation after each doc update category (if tests exist)
+
+**Run prerequisite check:**
+
+```bash
+PLUGIN_ROOT="$HOME/.claude/plugins/marketplaces/shavakan"
+
+if [[ ! "$PLUGIN_ROOT" =~ ^"$HOME"/.* ]]; then
+  echo "ERROR: Invalid plugin root path"
+  exit 1
+fi
+
+PREREQ_SCRIPT="$PLUGIN_ROOT/commands/cleanup/scripts/check-prerequisites.sh"
+if [[ ! -f "$PREREQ_SCRIPT" ]]; then
+  echo "ERROR: Prerequisites script not found"
+  exit 1
+fi
+
+PREREQ_OUTPUT=$(mktemp)
+if "$PREREQ_SCRIPT" --skip-tests > "$PREREQ_OUTPUT" 2>&1; then
+  source "$PREREQ_OUTPUT"
+  rm "$PREREQ_OUTPUT"
+else
+  cat "$PREREQ_OUTPUT"
+  rm "$PREREQ_OUTPUT"
+  exit 1
+fi
+```
+
+This exports: `TEST_CMD`, `BACKUP_BRANCH`, `LOG_FILE`
+
+---
+
+## Additional Instructions
+
+$ARGUMENTS
+
+---
+
+## Objective
+
+Synchronize documentation with current codebase state - eliminate inaccuracies, fix broken references, ensure examples work.
+
+### Documentation Issues
+
+**Dead links** - Internal links to moved/deleted files, external 404s, broken anchor references
+
+**Outdated API docs** - Function signatures changed, parameters added/removed/renamed, return types mismatched, deprecated methods still documented
+
+**Stale content** - Removed features still documented, old tooling instructions, architecture docs contradicting code, examples using deprecated APIs
+
+**Incorrect paths** - Wrong import examples, outdated file structure diagrams, command examples referencing moved files
+
+**Missing docs** - New features without documentation, API endpoints undescribed, configuration options undocumented, breaking changes not in changelog
+
+---
+
+## Execution
+
+### Phase 1: Audit Documentation
+
+Scan all docs and cross-reference with codebase. Documentation typically lives in: README.md, docs/ directory, API documentation (JSDoc/docstrings), CHANGELOG.md, CONTRIBUTING.md, inline examples.
+
+For each issue found, capture location, problem description, and suggested fix. Present findings grouped by category with counts and severity.
+
+**Gate**: User must review full audit before proceeding.
+
+### Phase 2: Prioritize Fixes
+
+Present audit findings with impact assessment:
+```
+Fix documentation issues?
+
+□ Critical - Dead links + wrong API signatures + missing docs
+□ High - Stale setup + removed features + incorrect paths
+□ Medium - Outdated diagrams + deprecated tool references
+□ Custom - Select specific categories
+□ Cancel
+```
+
+**Gate**: Get user approval on which categories to fix.
+
+### Phase 3: Fix Issues
+
+For each approved category:
+
+**Dead links:** Update to new location if file moved, remove if deleted, find replacement for broken external URLs, fix anchor links to match current headings
+
+**Outdated API docs:** Compare documented signatures with actual code, update parameters/return types to match reality, add version notes ("Changed in v2.0.0"), note breaking changes in CHANGELOG
+
+**Stale content:** Remove sections about deleted features, update setup instructions for current tools, note what replaced old features, update architecture diagrams, test and fix code examples
+
+**Incorrect paths:** Find current file locations, update import examples, fix command line examples, correct file tree diagrams
+
+**Missing docs:** Document new public APIs, add configuration option descriptions, note breaking changes in CHANGELOG, write migration guides for major changes
+
+**Critical**: Test all code examples actually work. Verify links resolve correctly. One category at a time with test validation between each.
+
+**Gate**: Tests must pass before moving to next category.
+
+### Phase 4: Report Results
+
+Summarize: dead links fixed, API docs synchronized, stale content removed/updated, paths corrected, missing docs added, documentation accuracy improvement.
+
+Delete the backup branch after successful completion:
+```bash
+git branch -D "$BACKUP_BRANCH"
+```
+
+---
+
+## Documentation Priority Tiers
+
+**Essential** (always accurate): README.md, API documentation, CHANGELOG.md, migration guides, setup/installation
+
+**Important** (reasonably current): Architecture docs, contributing guide, examples, troubleshooting
+
+**Nice-to-have** (update as needed): Tutorials, design decisions, performance notes, comparisons
+
+---
+
+## Example API Doc Correction
+
+```markdown
+<!-- Before (outdated) -->
+## authenticate(username, password)
+Authenticates a user with username and password.
+
+<!-- After (corrected) -->
+## authenticate(credentials)
+Authenticates a user with credentials object.
+
+**Parameters:**
+- `credentials.email` (string) - User email
+- `credentials.password` (string) - User password
+
+**Changed in v2.0.0:** Previously accepted separate username and password parameters.
+```
+
+---
+
+## Safety Constraints
+
+**CRITICAL:**
+- Verify content is truly outdated before removing - check git history
+- Test all code examples actually compile and run
+- Keep migration context - when removing features, note what replaced them
+- Update CHANGELOG when fixing API documentation errors
+- One category at a time with test validation
+- Commit granularly - separate commits for dead links, API updates, etc.
+- Check markdown renders correctly after edits
+
+**If examples fail**: Don't update docs to match broken code. Fix the code or mark the feature as broken in docs with an issue reference.
+
+---
+
+## After Cleanup
+
+**Review with code-reviewer agent before pushing:**
+
+Use `shavakan-agents:code-reviewer` to verify changes don't introduce issues.
+
+---
+
+## Related Commands
+
+- `/shavakan-commands:cleanup` - Full repository audit
+- `/shavakan-commands:cleanup-dead-code` - Remove unused code
--- a/shavakan/cleanup-duplication.md
+++ b/shavakan/cleanup-duplication.md
@@ -0,0 +1,221 @@
+---
+description: Find and refactor duplicated code - similar blocks, copy-paste functions, repeated strings
+---
+
+# Remove Code Duplication
+
+Find DRY (Don't Repeat Yourself) violations and refactor duplicated code into reusable abstractions.
+
+## Prerequisites
+
+**Safety requirements:**
+1. Git repository with clean working tree
+2. All tests passing before refactoring
+3. Backup branch created automatically
+4. Test validation after each refactoring
+
+**Run prerequisite check:**
+
+```bash
+PLUGIN_ROOT="$HOME/.claude/plugins/marketplaces/shavakan"
+
+if [[ ! "$PLUGIN_ROOT" =~ ^"$HOME"/.* ]]; then
+  echo "ERROR: Invalid plugin root path"
+  exit 1
+fi
+
+PREREQ_SCRIPT="$PLUGIN_ROOT/commands/cleanup/scripts/check-prerequisites.sh"
+if [[ ! -f "$PREREQ_SCRIPT" ]]; then
+  echo "ERROR: Prerequisites script not found"
+  exit 1
+fi
+
+PREREQ_OUTPUT=$(mktemp)
+if "$PREREQ_SCRIPT" > "$PREREQ_OUTPUT" 2>&1; then
+  source "$PREREQ_OUTPUT"
+  rm "$PREREQ_OUTPUT"
+else
+  cat "$PREREQ_OUTPUT"
+  rm "$PREREQ_OUTPUT"
+  exit 1
+fi
+```
+
+This exports: `TEST_CMD`, `BACKUP_BRANCH`, `LOG_FILE`
+
+---
+
+## Additional Instructions
+
+$ARGUMENTS
+
+---
+
+## Objective
+
+Identify and eliminate code duplication - extract common patterns into reusable functions, constants, and abstractions.
+
+### Duplication Types
+
+**Duplicated blocks** - Similar/identical code in multiple files (>80% similarity, 5+ lines), copy-pasted logic with minor variations
+
+**Duplicated functions** - Same logic with different names, utility functions reimplemented across files, helper methods duplicated in multiple classes
+
+**Magic strings/numbers** - Repeated literals (strings like "admin", "error" used 3+ times), hard-coded numbers (excluding 0, 1, -1), configuration values scattered throughout code
+
+**Similar patterns** - Nearly identical implementations with slight variations, common algorithms reimplemented differently, parallel code structures that could be unified
+
+---
+
+## Execution
+
+### Phase 1: Detect Duplication
+
+Scan codebase for duplicated code. Look for similar blocks, repeated functions, magic values, and patterns that could be unified.
+
+For each duplication found, capture location, similarity percentage, and proposed extraction. Present findings grouped by type with counts and estimated impact.
+
+**Gate**: User must review full audit before proceeding.
+
+### Phase 2: Prioritize Refactorings
+
+Present audit findings with risk assessment:
+```
+Refactor code duplication?
+
+□ Safest - Extract magic strings/numbers to constants
+□ Low risk - Consolidate identical functions + extract utilities
+□ Medium risk - Extract duplicated blocks + parameterize variations
+□ High risk - Unify similar patterns into abstractions
+□ Custom - Select specific duplications
+□ Cancel
+```
+
+**Gate**: Get user approval on which duplications to refactor.
+
+### Phase 3: Refactor Systematically
+
+For each approved duplication:
+
+**Extract duplicated blocks:** Identify common functionality, create shared function with appropriate parameters, replace all occurrences, preserve exact behavior
+
+**Consolidate functions:** Compare implementations to find canonical version, merge variations into single configurable function, update all call sites, remove duplicate definitions
+
+**Extract magic values:** Create constants with descriptive names (ROLE_ADMIN, DEFAULT_TIMEOUT), replace all occurrences with constant reference, group related constants together
+
+**Unify patterns:** Design common abstraction that handles all cases, implement generic version with configuration, migrate each usage, remove old implementations
+
+**Critical**: One refactoring at a time. Test after each. Commit on success, rollback on failure.
+
+**Gate**: Tests must pass before moving to next refactoring.
+
+### Phase 4: Report Results
+
+Summarize: duplicated blocks extracted, functions consolidated, magic values extracted to constants, patterns unified, code reduction percentage, maintainability improvement.
+
+Delete the backup branch after successful completion:
+```bash
+git branch -D "$BACKUP_BRANCH"
+```
+
+---
+
+## When NOT to Refactor
+
+**Don't extract if:**
+- Only 2 occurrences (wait for third) - "Rule of Three"
+- Code happens to look similar but serves different purposes
+- Abstraction would be more complex than duplication
+- Duplication is in different contexts (tests vs. production code)
+- Changes are likely to diverge in the future
+
+**Bad extraction example:**
+```typescript
+// Don't do this - over-abstraction for trivial code
+function addOneToNumber(n: number): number {
+  return n + 1;
+}
+// Just use n + 1 directly
+```
+
+---
+
+## Refactoring Patterns
+
+### Extract Function
+```typescript
+// Before: Duplicated in 3 files
+if (user.role === 'admin' || user.role === 'owner') {
+  return true;
+}
+
+// After: Extract to shared utility
+// utils/auth.ts
+export function canManageResources(user: User): boolean {
+  return user.role === 'admin' || user.role === 'owner';
+}
+
+// Usage
+import { canManageResources } from './utils/auth';
+if (canManageResources(user)) { }
+```
+
+### Extract Constants
+```typescript
+// Before: Magic strings repeated
+if (user.role === 'admin') { }
+
+// After: Extract to constants
+// constants/roles.ts
+export const ROLE_ADMIN = 'admin';
+
+// Usage
+import { ROLE_ADMIN } from './constants/roles';
+if (user.role === ROLE_ADMIN) { }
+```
+
+### Parameterize Variations
+```typescript
+// Before: Similar functions with variations
+function fetchUsers() { return api.get('/users'); }
+function fetchPosts() { return api.get('/posts'); }
+
+// After: Single parameterized function
+function fetchResource<T>(resource: string): Promise<T[]> {
+  return api.get(`/${resource}`);
+}
+
+// Usage
+const users = await fetchResource<User>('users');
+```
+
+---
+
+## Safety Constraints
+
+**CRITICAL:**
+- One refactoring at a time - test between each
+- Preserve behavior exactly - all tests must pass
+- Follow "Rule of Three" - extract when you have 3+ duplicates, not 2
+- Name clearly - extracted functions should have descriptive names
+- Don't over-abstract - complex abstraction worse than simple duplication
+- Test thoroughly - edge cases may differ between duplicates
+- Commit granularly - each extraction gets its own commit
+
+**If tests fail**: Rollback immediately, identify which specific extraction broke behavior, understand the difference between duplicates.
+
+---
+
+## After Cleanup
+
+**Review with code-reviewer agent before pushing:**
+
+Use `shavakan-agents:code-reviewer` to verify refactorings don't introduce issues.
+
+---
+
+## Related Commands
+
+- `/shavakan-commands:cleanup` - Full repository audit
+- `/shavakan-commands:cleanup-architecture` - Refactor god objects
+- `/shavakan-commands:cleanup-dead-code` - Remove unused code
--- a/shavakan/cleanup.md
+++ b/shavakan/cleanup.md
@@ -0,0 +1,172 @@
+---
+description: Comprehensive repository audit and cleanup (dead code, comments, docs, architecture, deps)
+---
+
+# Repository Cleanup Audit
+
+Scan the codebase for cleanup opportunities across all categories. Generate comprehensive report, then execute improvements based on user priorities.
+
+## Prerequisites
+
+**Safety requirements:**
+1. Git repository with clean working tree
+2. All tests passing before cleanup
+3. Backup branch created automatically
+4. Test validation after each cleanup operation
+
+**Run prerequisite check:**
+
+```bash
+PLUGIN_ROOT="$HOME/.claude/plugins/marketplaces/shavakan"
+
+if [[ ! "$PLUGIN_ROOT" =~ ^"$HOME"/.* ]]; then
+  echo "ERROR: Invalid plugin root path"
+  exit 1
+fi
+
+PREREQ_SCRIPT="$PLUGIN_ROOT/commands/cleanup/scripts/check-prerequisites.sh"
+if [[ ! -f "$PREREQ_SCRIPT" ]]; then
+  echo "ERROR: Prerequisites script not found"
+  exit 1
+fi
+
+PREREQ_OUTPUT=$(mktemp)
+if "$PREREQ_SCRIPT" > "$PREREQ_OUTPUT" 2>&1; then
+  source "$PREREQ_OUTPUT"
+  rm "$PREREQ_OUTPUT"
+else
+  cat "$PREREQ_OUTPUT"
+  rm "$PREREQ_OUTPUT"
+  exit 1
+fi
+```
+
+This exports: `TEST_CMD`, `BACKUP_BRANCH`, `LOG_FILE`
+
+---
+
+## Additional Instructions
+
+$ARGUMENTS
+
+---
+
+## Objective
+
+Perform comprehensive audit of codebase for cleanup opportunities across all categories, then execute selected improvements systematically.
+
+### Cleanup Categories
+
+1. **Dead Code** - Unused imports, functions, variables, files
+2. **Comments** - Obvious comments, commented code, outdated TODOs
+3. **Documentation** - Broken links, outdated docs, missing API docs
+4. **Architecture** - God objects, circular deps, poor separation
+5. **Dependencies** - Unused packages, vulnerabilities, outdated deps
+6. **Duplication** - Repeated code, magic values, similar patterns
+
+---
+
+## Execution
+
+### Phase 1: Comprehensive Scan
+
+Scan entire codebase for cleanup opportunities across all categories. For each category, identify issues with location, severity, and estimated impact.
+
+Present audit findings grouped by category with counts. Include priority assessment:
+- **Critical**: Security vulnerabilities, god objects blocking development, circular dependencies causing bugs
+- **High**: Dead code cluttering codebase, broken documentation, architecture issues
+- **Medium**: Comment noise, code duplication, outdated dependencies (non-security)
+
+**Gate**: User must review full audit before proceeding.
+
+### Phase 2: Prioritize with User
+
+Present cleanup options with impact assessment:
+```
+Execute cleanup operations?
+
+□ Critical only - Security fixes + blocking issues
+□ Safe cleanups - Dead code + unused imports + obvious comments
+□ Structural - Architecture + dead code + duplication
+□ Full cleanup - All categories (comprehensive)
+□ Custom - Select specific categories
+□ Cancel
+```
+
+**Gate**: Get user approval on which categories to clean.
+
+### Phase 3: Execute Cleanups
+
+**IMPORTANT**: This command orchestrates by invoking specialized subcommands. Do not implement cleanup logic directly - use the subcommands:
+
+- Security/unused/outdated deps → invoke `/shavakan-commands:cleanup-deps`
+- Architecture issues → invoke `/shavakan-commands:cleanup-architecture`
+- Dead code → invoke `/shavakan-commands:cleanup-dead-code`
+- Comments → invoke `/shavakan-commands:cleanup-comments`
+- Duplication → invoke `/shavakan-commands:cleanup-duplication`
+- Documentation → invoke `/shavakan-commands:cleanup-docs`
+
+**Execution order**: Security first, then structural improvements, then code quality, then documentation/maintenance.
+
+**Between each subcommand**: Verify tests pass. If passing, proceed to next. If failing, rollback and report issue. User can cancel at any point.
+
+**Gate**: Tests must pass after each subcommand before proceeding.
+
+### Phase 4: Report Results
+
+Summarize metrics (lines reduced, files removed, issues resolved), what was cleaned (by category with counts), impact analysis (code coverage maintained, build size reduced, maintainability improved).
+
+Delete the backup branch after successful completion:
+```bash
+git branch -D "$BACKUP_BRANCH"
+```
+
+Note: All commits granular and revertable.
+
+---
+
+## Auto-Fix Mode
+
+For safe automated fixes, execute:
+- Remove unused imports (linter auto-fix)
+- Remove obvious comments (unambiguous patterns only)
+- Fix dead internal links (update to new file locations)
+- Extract magic strings to constants (3+ occurrences)
+
+Each fix tested independently. Rollback on any test failure. Commit each fix type separately.
+
+---
+
+## Safety Constraints
+
+**CRITICAL:**
+- One category at a time - complete and test each before next
+- Security first - fix critical vulnerabilities before cosmetic changes
+- Test continuously - run tests after each category
+- Commit granularly - each fix gets its own commit
+- Preserve rollback - keep backup branch until changes verified
+- User confirmation - ask before executing each major change
+- Stop on failure - don't continue if tests fail
+
+**Error handling**: If cleanup fails, report which categories completed successfully (with commits), which category failed (with error), and offer options: skip failed category and continue, stop to investigate, or rollback all changes.
+
+---
+
+## After Cleanup
+
+**Review with code-reviewer agent before pushing:**
+
+Use `shavakan-agents:code-reviewer` to verify all changes.
+
+**Final verification**: Run full test suite, check build succeeds, review commits, update CHANGELOG if significant changes.
+
+---
+
+## Related Commands
+
+- `/shavakan-commands:cleanup-dead-code` - Remove unused code
+- `/shavakan-commands:cleanup-deps` - Manage dependencies
+- `/shavakan-commands:cleanup-comments` - Clean up comments
+- `/shavakan-commands:cleanup-docs` - Fix documentation
+- `/shavakan-commands:cleanup-architecture` - Refactor structure
+- `/shavakan-commands:cleanup-duplication` - Remove duplication
--- a/shavakan/docs-feature-plan.md
+++ b/shavakan/docs-feature-plan.md
@@ -0,0 +1,197 @@
+---
+description: Create comprehensive strategic plan + context files (plan.md, context.md, tasks.md)
+---
+
+# Feature Plan - Strategic Planning and Documentation
+
+Create comprehensive implementation plans that prevent losing context during complex features.
+
+## Additional Instructions
+
+$ARGUMENTS
+
+---
+
+## Objective
+
+Create comprehensive implementation plans for complex features that prevent context loss during development. Research codebase, design strategic plan with phases and risks, generate planning files in features/ directory.
+
+**Output Structure:**
+```
+features/[task-name]/
+├── plan.md      # Comprehensive accepted plan
+├── context.md   # Key files, architectural decisions, integration points
+└── tasks.md     # Markdown checklist of work items
+```
+
+---
+
+## Execution
+
+### Phase 1: Research and Plan
+
+Analyze user requirements and research codebase for architecture, existing patterns, and integration points. Create comprehensive strategic plan including:
+
+- Executive summary (what and why)
+- Implementation phases with specific tasks
+- Risks and mitigation strategies
+- Success metrics and timeline estimates
+
+Reference specific file paths, function names, and existing patterns to follow.
+
+**Gate**: Present complete plan to user for review before creating files.
+
+### Phase 2: Confirm Approach
+
+Present the strategic plan with options:
+```
+Create feature plan files?
+
+□ Approve plan - Create files in features/ directory
+□ Revise approach - Adjust strategy before creating files
+□ Change scope - Modify phases or tasks
+□ Cancel
+```
+
+After approval, ask for task name (kebab-case format).
+
+**Gate**: User must approve plan and provide task name.
+
+### Phase 3: Generate Planning Files
+
+Create `features/[task-name]/` directory with three files:
+
+**plan.md** - Comprehensive implementation plan (executive summary, phases, tasks, risks, success metrics, timeline)
+
+**context.md** - Key files, architectural decisions, integration points, patterns to follow, next steps for resuming work
+
+**tasks.md** - Markdown checklist organized by phase, including testing and documentation tasks
+
+**Gate**: All files created successfully.
+
+### Phase 4: Report Results
+
+Summarize what was created: directory location, files generated, next steps for implementation. Remind user to keep context.md updated during implementation and mark tasks complete in tasks.md.
+
+---
+
+## File Format Examples
+
+### plan.md Format
+```markdown
+# [Feature Name] Implementation Plan
+
+## Executive Summary
+[2-3 sentences describing what and why]
+
+## Context
+- Current state
+- Why this change is needed
+- What problems it solves
+
+## Implementation Phases
+
+### Phase 1: [Name]
+**Goal:** [What this phase achieves]
+
+**Tasks:**
+1. Task description with file references
+2. Another task
+
+**Risks:**
+- Risk and mitigation
+
+### Phase 2: [Name]
+...
+
+## Success Metrics
+- How we know it's working
+- What to test
+
+## Timeline
+Estimated: X days/weeks
+```
+
+### context.md Format
+```markdown
+# [Feature Name] - Context & Key Decisions
+
+**Last Updated:** [timestamp]
+
+## Key Files
+- `path/to/file.ts` - Purpose and why it matters
+- `path/to/another.ts` - Purpose
+
+## Architectural Decisions
+1. **Decision:** What we decided
+   **Rationale:** Why we decided it
+   **Impact:** What it affects
+
+2. **Decision:** ...
+
+## Integration Points
+- How this feature connects with X
+- Dependencies on Y service
+- Data flow: A → B → C
+
+## Important Patterns
+- Pattern we're using and why
+- Existing code to follow as example
+
+## Next Steps
+[When resuming work, start here]
+```
+
+### tasks.md Format
+```markdown
+# [Feature Name] - Task Checklist
+
+**Last Updated:** [timestamp]
+
+## Phase 1: [Name]
+- [ ] Task 1 description
+- [ ] Task 2 description
+- [ ] Task 3 description
+
+## Phase 2: [Name]
+- [ ] Task 1 description
+- [ ] Task 2 description
+
+## Testing
+- [ ] Unit tests for X
+- [ ] Integration tests for Y
+- [ ] Manual testing of Z
+
+## Documentation
+- [ ] Update API docs
+- [ ] Update README
+```
+
+---
+
+## Best Practices
+
+- Be specific with file paths and function names
+- Break large tasks into 2-4 hour chunks
+- Flag risks early (breaking changes, performance impacts, security)
+- Reference existing code patterns to follow
+- Keep context.md updated with decisions made during implementation
+- Mark tasks complete immediately in tasks.md
+
+## When to Use
+
+- Large features (more than a few hours of work)
+- Complex refactors touching multiple files
+- Features spanning multiple repos or services
+- Anything where losing context would be costly
+
+## Example
+
+User request: "I want to add real-time notifications using WebSockets"
+
+Workflow:
+1. Research WebSocket patterns in codebase
+2. Create comprehensive plan covering server setup, client integration, state management, fallbacks
+3. Show plan to user for approval
+4. After approval, create `features/websocket-notifications/` with all three files
+5. Confirm creation and next steps
--- a/shavakan/docs-readme.md
+++ b/shavakan/docs-readme.md
@@ -0,0 +1,156 @@
+---
+description: Generate/update condensed developer README for project usage and contribution
+---
+
+# README Generator
+
+Create/update README.md in project root. **Constraints: < 200 lines, scannable in 30 seconds, technical tone (no marketing).**
+
+## Additional Instructions
+
+$ARGUMENTS
+
+---
+
+## Analysis Phase
+
+Check files in order, record findings:
+
+1. `flake.nix` → Nix flake present (Y/N)
+2. `.envrc` + `.envrc.example` → direnv present (Y/N)
+3. `Makefile` → Make targets available (Y/N)
+4. `package.json` / `pyproject.toml` / `go.mod` / `Cargo.toml` → Language ecosystem
+5. Existing `README.md` → Preserve badges, screenshots, custom sections
+6. Entry points → `main.py`, `index.ts`, `cmd/main.go`, etc
+
+## Build System Priority
+
+**Select primary build interface based on presence:**
+
+| Priority | System | When | Commands |
+|----------|--------|------|----------|
+| 1 | Nix | `flake.nix` exists | `nix develop`, `nix build`, `nix run` |
+| 2 | Make | `Makefile` exists | `make install`, `make test`, `make build` |
+| 3 | Package manager | `package.json` / `Cargo.toml` | `npm install`, `cargo build` |
+| 4 | Direct | None above | `python -m`, `go run`, etc |
+
+**If multiple exist**: Use highest priority as primary, mention others as alternatives.
+
+## Environment Management
+
+**If `.envrc` exists:**
+- Prerequisites: Add "direnv" requirement
+- Install step: Add `cp .envrc.example .envrc && direnv allow`
+- Configuration section: Reference `.envrc.example` for variables
+
+**If no direnv**:
+- Use `.env` files or manual `export` commands
+- Configuration section: List env vars inline
+
+## README Composition
+
+**Required sections (generate in order):**
+
+### 1. Title + Summary
+```
+# [Project Name]
+> [Single sentence: does X for Y users]
+```
+
+### 2. Quick Start
+
+**Prerequisites**: List tools with versions. Omit language version if Nix manages it. Include Nix/direnv if detected.
+
+**Install**: Commands to get dependencies. Prioritize by build system table above.
+
+**Run**: Command to start/execute. Include port/URL for web apps.
+
+**Test**: Command to run tests. Use `nix flake check` if available.
+
+### 3. Project Structure
+
+Tree diagram of key directories with inline comments:
+```
+src/
+  core/       # Business logic
+  api/        # Endpoints
+tests/        # Test suite
+```
+
+### 4. Development
+
+**Setup**: Additional dev steps (direnv, pre-commit hooks, etc)
+
+**Build/Lint/Format**: Commands using primary build system
+
+**Common tasks**: 2-3 bullet points for frequent operations
+
+### 5. Optional Sections (include only if applicable)
+
+**Architecture**: 2-3 sentences on design decisions and tradeoffs. Include if non-obvious.
+
+**Configuration**: Env vars with descriptions. Required vs optional. Include if app needs config.
+
+**Deployment**: Deploy command or link. Include for deployable apps.
+
+**Contributing**: Link to CONTRIBUTING.md or inline if < 5 rules.
+
+**License**: License type. Include if LICENSE file exists.
+
+## Output Format Rules
+
+**Command syntax:**
+- Multi-word commands: Always use code blocks, never inline
+- Good: "Run:\n```bash\nnpm run dev\n```"
+- Bad: "Run `npm run dev`"
+
+**Section length**: Each section < 15 lines. Link to detailed docs if longer.
+
+**Style**: Technical, direct. Explain WHY for architecture, not WHAT code does. No "easy", "simple", "just".
+
+**Preservation**: Keep existing badges, screenshots, unique sections from old README.
+
+## Project Type Adaptations
+
+| Type | Adaptations |
+|------|-------------|
+| CLI tool | Add "Usage" with examples, omit "Running" |
+| Library | Add "Installation" + "Usage" with API examples, omit "Running" |
+| Web app | Include PORT/URL in "Run", add "Deployment" |
+| Monorepo | Show workspace structure, document per-package commands |
+| Nix multi-output | Add `nix flake show` output, document available apps/packages |
+
+## Execution Workflow
+
+1. Run analysis phase → Collect build system, env management, project type
+2. Generate README content using composition rules
+3. Show preview with summary: "[Project type] with [build system]. README uses [commands]. ~[N] lines."
+4. **If approved** → Write to `README.md`
+5. **If rejected** → Ask what to change, regenerate from step 2
+
+## Edge Cases
+
+**No build system found**: Use direct language commands (python, go run, etc) and warn in preview.
+
+**Nix without devShell**: Use `nix-shell` or `nix develop` with warnings about flake completeness.
+
+**Multiple entry points**: List all in "Run" section with descriptions.
+
+**Secrets in .envrc**: Never read actual `.envrc`, only `.envrc.example`. Remind about `.gitignore`.
+
+## Example Execution
+
+**Input**: "Generate README"
+
+**Analysis**:
+- flake.nix: Yes (Nix development shell + app)
+- .envrc: Yes (with .envrc.example)
+- Makefile: Yes (install/test/build targets)
+- package.json: Yes (Next.js)
+- Entry: pages/index.tsx
+
+**Build priority**: Nix (priority 1), mention Make as fallback
+
+**Preview**: "Next.js web app with Nix flake and direnv. README uses `nix run` for primary interface, notes `make` commands as alternative. Includes .envrc.example setup. ~90 lines. Approve?"
+
+**Output**: README.md with Nix-first commands, direnv setup, project structure showing pages/ and components/, development section with `nix build` and `nix flake check`.
--- a/shavakan/docs-save-context.md
+++ b/shavakan/docs-save-context.md
@@ -0,0 +1,155 @@
+---
+description: Save conversation context before compaction (context.md, tasks.md)
+---
+
+# Save Context - Pre-Compaction State Preservation
+
+Preserve current conversation state and decisions before approaching token limit or natural break point.
+
+## Additional Instructions
+
+$ARGUMENTS
+
+---
+
+## Objective
+
+Preserve conversation state before compaction or natural break points. Extract decisions made, document current progress, update context files for continuity.
+
+**Use when:**
+- Approaching token limit (compaction warning)
+- Natural break point in complex work
+- Before switching contexts
+- After important architectural decisions
+
+---
+
+## Execution
+
+### Phase 1: Analyze Current State
+
+Extract from conversation:
+
+**Decisions made** - What was decided and why, trade-offs considered, alternatives rejected, rationale for approach
+
+**Current progress** - What's completed, partially done, blocked (and why)
+
+**Next steps** - Immediate next actions, dependencies to resolve, open questions
+
+Check if feature context already exists in `features/[task-name]/` directory.
+
+**Gate**: Present summary of extracted state to user.
+
+### Phase 2: Confirm Context Strategy
+
+Present options based on whether context files exist:
+```
+Save context state?
+
+□ Update existing - Append to features/[task-name]/ files
+□ Create new - Start fresh context directory
+□ Review first - Show extracted state before saving
+□ Cancel
+```
+
+If creating new, ask for task name (kebab-case format).
+
+**Gate**: User must confirm approach and provide task name if needed.
+
+### Phase 3: Update or Create Files
+
+**If updating existing:**
+- Append new decisions to context.md with timestamp
+- Update "Next Steps" section
+- Mark completed tasks in tasks.md
+- Add new tasks if discovered
+
+**If creating new:**
+- Create `features/[task-name]/` directory
+- Generate context.md with current state and decisions
+- Generate tasks.md with remaining work checklist
+
+Note: plan.md not needed for context saves (only for feature-plan command).
+
+**Gate**: All files updated or created successfully.
+
+### Phase 4: Report Results
+
+Summarize what was saved: location of files, key decisions captured, tasks marked complete, next steps documented for resuming work
+
+---
+
+## File Formats
+
+### context.md Format
+
+```markdown
+# [Feature Name] - Context
+
+**Last Updated:** [timestamp]
+
+## Current State
+
+[Where we are in implementation - 2-3 sentences]
+
+## Recent Decisions
+
+### [Decision Title]
+**What:** What was decided
+**Why:** Rationale and trade-offs
+**When:** [timestamp]
+**Impact:** What this affects
+
+## Key Files
+
+- `path/to/file.ts` - Purpose and current state
+- `path/to/another.ts` - What was changed
+
+## Next Steps
+
+[When resuming work, start here - specific actionable items]
+
+## Open Questions
+
+- Question that needs resolution
+- Blocker or dependency
+```
+
+### tasks.md Format
+
+```markdown
+# [Feature Name] - Tasks
+
+**Last Updated:** [timestamp]
+
+## Completed
+- [x] Task that was finished
+- [x] Another completed task
+
+## In Progress
+- [ ] Task currently being worked on (50% done)
+
+## Blocked
+- [ ] Task blocked by X dependency
+
+## Todo
+- [ ] Next task to do
+- [ ] Subsequent task
+```
+
+---
+
+## Best Practices
+
+- **Be specific**: Include file paths, function names, line numbers
+- **Capture why**: Decisions without rationale lose value
+- **Update timestamps**: Always update "Last Updated" field
+- **Mark progress**: Move tasks from todo → in progress → completed
+- **Note blockers**: Document what's preventing progress and why
+
+---
+
+## Related Commands
+
+- `/shavakan-commands:docs-feature-plan` - Create comprehensive feature plan from scratch
+- `/shavakan-commands:docs-update` - Update existing context files
--- a/shavakan/docs-update.md
+++ b/shavakan/docs-update.md
@@ -0,0 +1,114 @@
+---
+description: Update feature context and tasks before compaction
+---
+
+# Update Feature Context
+
+Update existing feature context files (context.md, tasks.md) to preserve current state before compaction or break point.
+
+## Additional Instructions
+
+$ARGUMENTS
+
+---
+
+## Objective
+
+Update existing feature context files to preserve current state. Add recent progress and decisions to context.md, mark completed tasks in tasks.md, document next steps for continuation.
+
+**Use when:**
+- Approaching token limit (compaction warning)
+- Before long pause (end of day/week)
+- After significant architectural decisions
+- When switching to different feature
+
+---
+
+## Execution
+
+### Phase 1: Locate and Backup
+
+Find existing feature directory in `features/[task-name]/`. If multiple exist or none found, ask user which feature to update.
+
+Create timestamped backups before modifying:
+- `context.md.backup-[timestamp]`
+- `tasks.md.backup-[timestamp]`
+
+**Gate**: Feature directory located and backups created successfully.
+
+### Phase 2: Review Updates
+
+Present what will be updated:
+```
+Update feature context files?
+
+□ Update both - context.md + tasks.md
+□ Context only - Add progress and decisions
+□ Tasks only - Mark completed tasks
+□ Review first - Show current state before updating
+□ Cancel
+```
+
+**Gate**: User must confirm which files to update.
+
+### Phase 3: Apply Updates
+
+**For context.md:**
+- Update timestamp to current date/time
+- Add Recent Progress section (Completed, In Progress, Next Steps, Issues/Blockers)
+- Add new files to Key Files section
+- Add architectural decisions with rationale
+- Update integration points if dependencies changed
+
+**For tasks.md:**
+- Update timestamp to current date/time
+- Mark completed tasks (change `- [ ]` to `- [x]`)
+- Add new tasks discovered during work
+- Reorder if priorities changed
+
+Include specific file references and actionable next steps.
+
+**Gate**: All updates applied successfully with no syntax errors.
+
+### Phase 4: Validate and Report
+
+Verify updates meet quality standards:
+- Timestamps current
+- Recent Progress section complete with Next Steps
+- At least one task marked complete or new task added
+- No unclosed code blocks or syntax errors
+
+If validation passes, remove backup files. If validation fails, restore from backups.
+
+Report what was updated: files modified, completed tasks count, next steps documented
+
+---
+
+## Quality Standards
+
+### context.md Requirements
+
+- Timestamp current
+- Recent Progress with all subsections (Completed, In Progress, Next Steps, Issues/Blockers)
+- Specific file references (not vague like "fix the bug")
+- Clear next steps (numbered, actionable)
+
+### tasks.md Requirements
+
+- Timestamp current
+- Completed tasks marked with [x]
+- At least one change made
+- Tasks have specific descriptions with file paths
+
+---
+
+## Rollback
+
+If any step fails after backups created, restore original files from backups and report error.
+
+---
+
+## Related Commands
+
+- `/shavakan-commands:docs-save-context` - Save context (works without existing files)
+- `/shavakan-commands:docs-feature-plan` - Create new feature plan from scratch