moicle 1.7.0 → 2.0.0

package/assets/skills/feature/deprecate/SKILL.md

@@ -0,0 +1,276 @@
+---
+name: feature-deprecate
+description: Deprecation workflow for safely removing features or code. Use when deprecating, removing features, sunsetting functionality, or when user says "deprecate", "remove feature", "sunset", "phase out", "delete feature".
+---
+
+# Deprecation Workflow
+
+Safely sunset a feature, API, or module without breaking users. Built around a **timeline** (T-90 → T+30) and the principle that **announce → warn → migrate → remove → monitor**.
+
+## When to use this skill
+
+- ✅ Sunsetting a public API endpoint, SDK method, or user-facing feature
+- ✅ Removing an internal module that other domains depend on
+- ✅ Migrating consumers from v1 → v2 of anything
+- ❌ Just deleting unused dead code (no consumers) → just delete in PR with explanation
+- ❌ Renaming an internal helper → just rename, no deprecation needed
+- ❌ Removing a feature behind a flag with 0 users → just remove the flag
+
+---
+
+## Workflow
+
+```
+IDENTIFY → PLAN → MIGRATE → REMOVE → VERIFY
+   ↓        ↓        ↓         ↓        ↓
+ announce  warn   migrate   remove   monitor
+ (T-90)  (T-60)  (T-30)     (T-0)   (T+30)
+```
+
+## Read Architecture First
+
+Read `~/.claude/architecture/ddd-architecture.md` + stack doc to understand layer impact before any deprecation.
+
+---
+
+## Deprecation Strategy
+
+| Strategy | When | Timeline |
+|----------|------|----------|
+| **Soft** | Internal API, replacement available, low usage | Announce → warn → migrate → remove (1–3 months) |
+| **Hard** | Security issue, breaking infra change | Announce + remove fast (days to weeks, with mitigation) |
+| **Versioned** | Public API, breaking change | Run v1 + v2 side-by-side, sunset v1 over months/years |
+
+---
+
+## Phase 1: IDENTIFY
+
+**Goal:** know what you're removing and who depends on it.
+
+### Actions
+1. Define the target: feature / endpoint / module / class / method
+2. Find ALL usages:
+   ```bash
+   # adapt per stack
+   grep -rn "{symbol}" --include="*.{ext}" .
+   # for APIs, check access logs:
+   {log_query for endpoint hits over last 30/90 days}
+   ```
+3. Identify consumers:
+   - Internal teams / services
+   - External users / SDK consumers
+   - Third-party integrations
+   - Docs and tutorials that reference it
+4. Assess impact (per architecture layer):
+   - Which layers reference it (domain / application / infra)?
+   - Cross-domain consumers?
+   - Breaking change severity?
+5. Find replacement (or document "no replacement, here's the workaround")
+
+### Output
+
+```markdown
+## Deprecation Analysis: {target}
+
+### What
+- Type: {feature / API / class / method / module}
+- Location: {file:line(s)}
+- Reason: {security / consolidation / better alternative / cost / etc.}
+
+### Replacement
+- {New API / pattern, with migration mapping}
+- OR: {no replacement — rationale}
+
+### Usage
+- Internal callers: {list with team contacts}
+- External callers (last 30d): {N requests / N unique tokens}
+- Docs referencing it: {list}
+
+### Impact
+- Layers affected: {domain / application / infra}
+- Severity: {breaking / non-breaking}
+- Estimated migration effort per consumer: {hours}
+```
+
+### Gate
+- [ ] All usages found (internal + external)
+- [ ] Stakeholders listed with contacts
+- [ ] Replacement defined (or explicit "no replacement")
+- [ ] Impact severity assessed
+
+---
+
+## Phase 2: PLAN
+
+**Goal:** lock the timeline and the communication plan.
+
+### Timeline template
+
+| Phase | Date | Action |
+|-------|------|--------|
+| T-90 | {date} | Announce deprecation (changelog + email + docs banner) |
+| T-60 | {date} | Add runtime warning (log / response header) |
+| T-30 | {date} | Hard warning (UI banner / error in non-prod) |
+| T-0 | {date} | Remove. Return 410 Gone for APIs |
+| T+30 | {date} | Remove deprecation code itself, archive docs |
+
+**Adjust** based on strategy: hard = days, public API = months/quarters.
+
+### Comms checklist
+- [ ] CHANGELOG entry
+- [ ] Release notes
+- [ ] Email to known consumers
+- [ ] Docs banner on the deprecated feature page
+- [ ] Migration guide written (with code diff before/after)
+- [ ] Slack / forum announcement
+- [ ] Updated SDK (if applicable) with deprecation in code
+
+### Gate
+- [ ] Timeline locked with dates
+- [ ] Migration guide drafted
+- [ ] Comms plan signed off by stakeholders
+- [ ] Replacement available and documented
+
+---
+
+## Phase 3: MIGRATE
+
+**Goal:** make consumers stop using the deprecated thing.
+
+### Add deprecation markers (in code)
+
+Pick the language idiom — show **what** is deprecated, **when** it goes away, and **what to use instead**.
+
+```ts
+/** @deprecated Removed on {date}. Use `newFunction()`. See {link}. */
+export function oldFunction() { ... }
+```
+
+```go
+// Deprecated: removed on {date}. Use NewFunction instead. See {link}.
+func OldFunction() { ... }
+```
+
+```php
+/**
+ * @deprecated since 2.0.0, removed in 3.0.0. Use newMethod(). See {link}.
+ */
+public function oldMethod() { ... }
+```
+
+```dart
+@Deprecated('Removed on {date}. Use newWidget(). See {link}.')
+class OldWidget { ... }
+```
+
+### Add runtime signal (for APIs)
+- Response header: `Deprecation: true` + `Sunset: {RFC 3339 date}` + `Link: <docs>; rel="deprecation"`
+- Server log: `deprecated.endpoint.called` with caller identity
+- Metric: counter of deprecated calls, broken down by consumer
+
+### Migrate internal consumers proactively
+- Open PRs against internal consumers yourself when possible
+- Track migration progress (% consumers migrated)
+
+### Gate
+- [ ] Deprecation markers in code
+- [ ] Runtime signals in place (headers, logs, metrics)
+- [ ] Internal usage trending down (verify weekly)
+- [ ] Migration guide proven by ≥1 consumer
+
+---
+
+## Phase 4: REMOVE
+
+**Goal:** delete the deprecated thing safely.
+
+### Pre-removal checks
+- [ ] Today's date ≥ T-0
+- [ ] Usage metric shows 0 calls (or only known stragglers with explicit waiver)
+- [ ] Final removal warning sent to remaining consumers
+- [ ] Replacement still works and is documented
+
+### Removal steps
+1. Delete the code + tests + docs
+2. For APIs: return `410 Gone` (NOT 404 — different meaning) with migration link in body
+3. Remove DB columns / tables in a follow-up migration (NOT same PR — keep removal reversible)
+4. Update CHANGELOG: "Removed: {thing}. See migration guide {link}."
+5. Deploy through normal pipeline
+
+### Gate
+- [ ] Code, tests, docs removed
+- [ ] API returns 410 (if applicable)
+- [ ] CHANGELOG entry
+- [ ] Deployed to all environments
+
+---
+
+## Phase 5: VERIFY (T+30)
+
+**Goal:** confirm clean removal.
+
+### Checks
+- [ ] No errors related to the removed code in monitoring
+- [ ] No customer support tickets about the missing feature
+- [ ] No leftover references in code (grep for the symbol)
+- [ ] Deprecation infra (warning headers, log alerts) cleaned up
+- [ ] DB cleanup migration applied (if any)
+
+### Final report
+
+```markdown
+## Deprecation Complete: {target}
+
+### Timeline
+- Announced: {date}
+- Removed: {date}
+- Verified: {date}
+
+### Outcome
+- Consumers migrated: {N/N}
+- Errors post-removal: {0 / N — explanation}
+- Replacement adoption: {%}
+
+### Cleanup
+- [x] Code removed
+- [x] Tests removed
+- [x] Docs removed
+- [x] DB columns dropped (in {migration})
+- [x] Deprecation infra cleaned
+```
+
+---
+
+## Anti-Patterns
+
+- **Silent removal** — removing without warning. Always announce first.
+- **Vague deprecation** — `@deprecated` with no date and no replacement. Always include both.
+- **Forever-deprecation** — marking deprecated and never removing. Set the date.
+- **Returning 404 instead of 410** — 404 = "doesn't exist", 410 = "intentionally gone". Use 410.
+- **Same-PR removal of API + DB columns** — keep removal reversible; drop columns in a follow-up.
+
+---
+
+## Related Skills
+
+| When | Use |
+|------|-----|
+| Adding the replacement first | `/feature:new` |
+| Restructuring the code that uses the deprecated thing | `refactor` |
+| Documenting the migration guide | `/docs:write` |
+| Reviewing the removal PR | `/review:pr` |
+
+---
+
+## Recommended Agents
+
+| Phase | Agent | Purpose |
+|-------|-------|---------|
+| IDENTIFY | `@refactor` | Dependency analysis |
+| IDENTIFY | `@code-reviewer` | Find all usages |
+| PLAN | `@clean-architect` | Migration strategy |
+| PLAN | `@api-designer` | API versioning |
+| PLAN | `@docs-writer` | Deprecation notice + migration guide |
+| MIGRATE | Stack-specific dev agent | Code changes |
+| VERIFY | `@test-writer` | Migration tests |
+| VERIFY | `@code-reviewer` | Final review |

package/assets/skills/{new-feature → feature/new}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: new-feature
+name: feature-new
 description: DDD feature development workflow with phase-based checks and review loop. Use when implementing new features, building functionality, or when user says "implement feature", "add feature", "build feature", "create feature", "new feature".
 args: "[DOMAIN] [FEATURE]"
 ---
@@ -10,27 +10,32 @@ Build a new feature following DDD architecture, with automated checks after each
 
 **ARGUMENTS:** `<domain> <feature>` — e.g., `wallet savings`, `notification broadcast`, `catalog products`
 
-## Read Architecture First
+## When to use this skill
+
+- ✅ Building a feature that spans multiple DDD layers (domain + app + infra)
+- ✅ The feature is well-understood (no major research / prototype needed)
+- ✅ You want automated architecture review at the end
+- ❌ Quick bug fix → use `/fix:hotfix`
+- ❌ Don't know the right approach yet → use `/research:web` or `/research:spike` first
+- ❌ Restructuring existing code → use `refactor`
 
-**Before starting, MUST read TWO files:**
+## Read Architecture First
 
-1. **Core DDD spec**: `.claude/architecture/ddd-architecture.md`
-2. **Stack-specific doc**: detect stack → read the corresponding architecture doc
+Before starting, read:
+1. `ddd-architecture.md` (core DDD spec)
+2. Stack-specific doc based on detected stack
 
 ### Stack Detection
 | File | Stack Doc |
 |------|-----------|
 | `go.mod` | `go-backend.md` |
+| `package.json` + NestJS dep | `nodejs-nestjs.md` |
 | `package.json` + `vite.config.*` | `react-frontend.md` |
 | `pubspec.yaml` | `flutter-mobile.md` |
 | `composer.json` | `laravel-backend.md` |
 | `remix.config.*` | `remix-fullstack.md` |
 
-### Architecture Files Location
-```
-.claude/architecture/{name}.md     # Project-specific (priority)
-~/.claude/architecture/{name}.md   # Global
-```
+Architecture files location: `.claude/architecture/{name}.md` (project) → `~/.claude/architecture/{name}.md` (global).
 
 ---
 
@@ -43,7 +48,7 @@ PHASE 1: Analyze & Plan
   → PHASE 4: Build Application Layer
   → PHASE 5: Registration & Wiring
   → PHASE 6: Domain Tests
-  → REVIEW LOOP (run /architect-review, fix issues, repeat until clean)
+  → REVIEW LOOP (run /review:architect, fix issues, repeat until clean)
 ```
 
 ---
@@ -236,7 +241,7 @@ After all phases complete, run the architecture review. **Keep looping until ALL
 
 ```
 LOOP:
-  1. Run /architect-review {stack} {domain}
+  1. Run /review:architect {stack} {domain}
   2. Collect violations
   3. IF violations with severity >= MEDIUM:
      a. Fix all violations
@@ -284,6 +289,17 @@ When review loop passes:
 
 ---
 
+## Related Skills
+
+| When | Use |
+|------|-----|
+| Don't know approach yet | `/research:web` → then this skill |
+| Want to validate approach with prototype first | `/research:spike` → then this skill |
+| Adding only an endpoint, not a whole feature | `/feature:api` |
+| Restructuring existing module to DDD | `refactor` |
+| Final architecture check (called automatically in Phase 7) | `/review:architect` |
+| Write tests inline during build | `/review:tdd` |
+
 ## Recommended Agents
 
 | Phase | Agent | Purpose |

package/assets/skills/{refactor → feature/refactor}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: refactor
+name: feature-refactor
 description: DDD refactoring workflow with phase-based checks and review loop. Refactor existing code to DDD architecture or improve existing DDD structure. Use when user says "refactor", "clean up", "improve code", "restructure", "migrate to ddd", "refactor ddd".
 args: "[MODULE] [DOMAIN]"
 ---
@@ -10,27 +10,30 @@ Refactor existing code into DDD architecture, or improve existing DDD structure.
 
 **ARGUMENTS:** `<module> <domain>` — e.g., `marketing notification`, `users identity`, `products catalog`
 
-## Read Architecture First
+## When to use this skill
+
+- ✅ Migrating a legacy module into DDD layers
+- ✅ Existing DDD module has drifted (fat controller, anemic entity, mixed concerns)
+- ✅ Splitting one domain into multiple bounded contexts
+- ❌ Building a brand-new feature → use `/feature:new`
+- ❌ Just renaming files / variables → just do it, no skill needed
+- ❌ Fixing a bug → use `/fix:hotfix` or `/fix:root-cause`
 
-**Before starting, MUST read TWO files:**
+## Read Architecture First
 
-1. **Core DDD spec**: `.claude/architecture/ddd-architecture.md`
-2. **Stack-specific doc**: detect stack → read the corresponding architecture doc
+Read `ddd-architecture.md` + stack-specific doc.
 
 ### Stack Detection
 | File | Stack Doc |
 |------|-----------|
 | `go.mod` | `go-backend.md` |
+| `package.json` + NestJS dep | `nodejs-nestjs.md` |
 | `package.json` + `vite.config.*` | `react-frontend.md` |
 | `pubspec.yaml` | `flutter-mobile.md` |
 | `composer.json` | `laravel-backend.md` |
 | `remix.config.*` | `remix-fullstack.md` |
 
-### Architecture Files Location
-```
-.claude/architecture/{name}.md     # Project-specific (priority)
-~/.claude/architecture/{name}.md   # Global
-```
+Architecture files: `.claude/architecture/{name}.md` (project) → `~/.claude/architecture/{name}.md` (global).
 
 ---
 
@@ -44,7 +47,7 @@ PHASE 0: Foundation Check
   → PHASE 4: Build Application Layer
   → PHASE 5: Domain Tests
   → PHASE 6: Integration & Cleanup
-  → REVIEW LOOP (run /architect-review, fix, repeat until clean)
+  → REVIEW LOOP (run /review:architect, fix, repeat until clean)
 ```
 
 Each phase has a Rule Check. DO NOT skip any phase.
@@ -258,7 +261,7 @@ After all phases complete, run the full architecture review. **Keep looping unti
 
 ```
 LOOP:
-  1. Run /architect-review {stack} {domain}
+  1. Run /review:architect {stack} {domain}
   2. Collect violations
   3. IF violations with severity >= MEDIUM:
      a. Fix all violations
@@ -326,6 +329,15 @@ When review loop passes with score >= B:
 
 ---
 
+## Related Skills
+
+| When | Use |
+|------|-----|
+| Building from scratch (no existing code) | `/feature:new` |
+| Just adding tests to existing untested code | `/review:tdd` |
+| Reviewing the refactor before merging | `/review:branch` |
+| Final architecture compliance check (called in review loop) | `/review:architect` |
+
 ## Recommended Agents
 
 | Phase | Agent | Purpose |

package/assets/skills/{hotfix → fix/hotfix}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: hotfix
+name: fix-hotfix
 description: Quick bug fix workflow with rollback plan. Use when fixing bugs, hotfixes, urgent issues, production bugs, or when user says "fix bug", "hotfix", "urgent fix", "production issue".
 ---
 
@@ -7,38 +7,18 @@ description: Quick bug fix workflow with rollback plan. Use when fixing bugs, ho
 
 Fast-track workflow for fixing bugs with safety rollback plan.
 
-## IMPORTANT: Read Architecture First
+## When to use this skill
 
-**Before fixing, you MUST read the appropriate architecture reference:**
+- ✅ Bug is reproducible and root cause is clear (or quickly identifiable)
+- ✅ Need a fix shipped fast with a rollback plan
+- ✅ Severity ranges from low (minor UI) to high (feature broken)
+- ❌ Production is down right now → use `/fix:incident` first
+- ❌ Bug has been "fixed" multiple times and keeps returning → use `/fix:root-cause`
+- ❌ Building a new feature → use `/feature:new`
 
-### Global Architecture Files
-```
-~/.claude/architecture/
-├── clean-architecture.md    # Core principles for all projects
-├── flutter-mobile.md        # Flutter + Riverpod
-├── react-frontend.md        # React + Vite + TypeScript
-├── go-backend.md            # Go + Gin
-├── laravel-backend.md       # Laravel + PHP
-├── remix-fullstack.md       # Remix fullstack
-└── monorepo.md              # Monorepo structure
-```
+## Read Architecture First
 
-### Project-specific (if exists)
-```
-.claude/architecture/        # Project overrides
-```
-
-**Understand the codebase structure before making changes.**
-
-## Recommended Agents
-
-| Phase | Agent | Purpose |
-|-------|-------|---------|
-| FIX | `@react-frontend-dev`, `@go-backend-dev`, `@laravel-backend-dev`, `@flutter-mobile-dev`, `@remix-fullstack-dev` | Stack-specific bug fix |
-| FIX | `@security-audit` | Security-related bugs |
-| VERIFY | `@test-writer` | Regression test |
-| VERIFY | `@code-reviewer` | Quick code review |
-| DEPLOY | `@devops` | CI/CD & deployment |
+Read `ddd-architecture.md` + stack-specific doc to understand layer placement of the fix.
 
 ## Workflow Overview
 
@@ -395,3 +375,25 @@ On-call: [contact]
 Backend lead: [contact]
 DevOps: [contact]
 ```
+
+---
+
+## Related Skills
+
+| When | Use |
+|------|-----|
+| Production is down right now | `/fix:incident` (then hotfix) |
+| Bug keeps coming back after fixes | `/fix:root-cause` |
+| Need to write regression test first | `/review:tdd` |
+| Bug is on an open PR | `/fix:pr-comment` |
+| After fix: reviewing own branch | `/review:branch` |
+
+## Recommended Agents
+
+| Phase | Agent | Purpose |
+|-------|-------|---------|
+| FIX | Stack-specific dev agent | Bug fix |
+| FIX | `@security-audit` | Security-related bugs |
+| VERIFY | `@test-writer` | Regression test |
+| VERIFY | `@code-reviewer` | Quick code review |
+| DEPLOY | `@devops` | CI/CD + deployment |