moicle 2.3.0 → 3.0.0

package/assets/skills/research/onboarding/SKILL.md

@@ -1,225 +0,0 @@
----
-name: research-onboarding
-description: Codebase onboarding workflow for understanding new projects. Use when joining a project, exploring codebase, or when user says "explain codebase", "onboard me", "new to project", "understand project", "explore codebase", "project overview".
----
-
-# Codebase Onboarding Workflow
-
-Ramp up on a new codebase quickly: structure, conventions, where things live, how to make a first change.
-
-## When to use this skill
-
-- ✅ Just joined a project / repo and need to ramp up
-- ✅ Returning to a codebase you haven't touched in months
-- ✅ Need to give a teammate a structured walkthrough
-- ❌ Want to generate full docs site → use `/docs-sync`
-- ❌ Need to fix a specific bug → use `/fix-hotfix` / `/fix-root-cause`
-- ❌ Only want a quick file lookup → just use `grep` / `find`
-
-## Read Architecture First
-
-Detect stack with `~/.claude/architecture/_shared/stack-detection.md`. Read `ddd-architecture.md` + the stack doc. Architecture context speeds up everything below by 10x.
-
----
-
-## Workflow
-
-```
-SCAN → ANALYZE → EXPLAIN → GUIDE (first commit checklist)
-```
-
----
-
-## Phase 1: SCAN (10-20 min)
-
-**Goal:** map the territory before reading any business code.
-
-```bash
-# Structure
-tree -L 2 -I 'node_modules|vendor|dist|build|.git'
-
-# Tech surface
-ls -la | grep -E "package.json|pubspec.yaml|go.mod|composer.json|Dockerfile|Makefile"
-
-# Existing docs
-find . -maxdepth 3 -name "README*" -o -name "CONTRIBUTING*" -o -name "ARCHITECTURE*"
-
-# Activity
-git log --oneline -20
-git shortlog -sn --since=3months | head -10
-```
-
-### Capture
-- Top-level layout (≤2 levels)
-- Tech stack + main dependencies (5-10 biggest)
-- Existing docs found (read in next phase)
-- Active contributors + recent commit themes
-
-### Gate
-- [ ] Stack detected (or asked user if ambiguous)
-- [ ] Top-level structure understood
-- [ ] Existing docs inventoried
-
----
-
-## Phase 2: ANALYZE (30-60 min)
-
-**Goal:** understand layer boundaries, conventions, and the "shape" of code.
-
-### Read in this order
-1. `README.md` — purpose + setup
-2. `ARCHITECTURE.md` / `CONTRIBUTING.md` if present
-3. **One existing module end-to-end** — pick the smallest with a full layer stack (e.g., `domain/user/`). Trace: entity → port → usecase → handler → test.
-4. Cross-domain wiring (event bus / DI / router registration)
-5. CI config (`.github/workflows/`, `Makefile`) — what's enforced?
-
-### Capture
-- Architecture pattern (DDD / MVC / clean / hexagonal — match against `ddd-architecture.md`)
-- Naming conventions (file, function, test)
-- Where business logic lives (usecase vs service vs handler)
-- How errors are returned (typed, panics, error wrapping)
-- Test framework + folder convention
-- How code reaches prod (CI checks, release process)
-
-### Gate
-- [ ] One module read end-to-end
-- [ ] Layer boundaries understood
-- [ ] Test + CI conventions known
-
----
-
-## Phase 3: EXPLAIN
-
-**Goal:** produce a 1-page mental model that someone else can read.
-
-```markdown
-## Project: {name}
-
-### Purpose
-{1-2 sentences: what business problem this solves}
-
-### Stack
-- Language: {go 1.22 / node 20 / dart 3.x / ...}
-- Framework: {gin / nestjs / remix / flutter ...}
-- DB: {postgres + sqlc / prisma / eloquent ...}
-- Infra: {docker, k8s on GKE, redis, kafka ...}
-
-### Architecture
-{1 sentence: e.g., "DDD with hexagonal — domain-pure, infra implements ports"}
-
-```
-{ascii or mermaid: top-level layer diagram}
-```
-
-### Domains
-| Domain | Responsibility |
-|--------|----------------|
-| {name} | {one line} |
-
-### Where to find things
-| If you need to... | Look in |
-|-------------------|---------|
-| Add a route | `application/ports/http/<domain>_handler` |
-| Add business logic | `domain/<domain>/usecases` |
-| Add a DB query | `infrastructure/database/<domain>_store` |
-| Add a domain event | `domain/<domain>/events` + register in event bus |
-| Add a test | `*_test.go` next to the source file |
-
-### Conventions
-- Error handling: {pattern}
-- Logging: {library + level convention}
-- Config: {env vars / yaml / both}
-- Branch / commit: {convention}
-
-### Gotchas
-- {anything surprising — e.g., "cache TTL is 30s, not 5 min like the comment says"}
-```
-
-### Gate
-- [ ] 1-page mental model written
-- [ ] "Where to find things" table covers ≥5 common tasks
-- [ ] At least 1 gotcha documented (every codebase has them)
-
----
-
-## Phase 4: GUIDE — first commit checklist
-
-**Goal:** unblock the first real change. The fastest ramp-up is shipping code.
-
-### Pick a "quick win" task
-- ≤30 min change (typo, comment, missing test, small UX nit)
-- Touches one layer only
-- Has a clear success criterion
-
-### First commit checklist
-- [ ] Local env runs: build + lint + tests all green from a fresh clone
-- [ ] Made the change in the right layer (per Phase 3 table)
-- [ ] Added or updated 1 test
-- [ ] Followed naming + error-handling conventions
-- [ ] Commit message matches project style (`git log --oneline`)
-- [ ] PR description follows template (check `.github/PULL_REQUEST_TEMPLATE.md`)
-- [ ] Self-reviewed with `/review-branch` before opening PR
-
-### Who to ask
-- Architecture / "why is it like this": {tech lead from git shortlog}
-- Domain knowledge for area X: {recent committer to that domain}
-- Infra / deploy: {ops contact from README}
-
-### Gate
-- [ ] Local env verified
-- [ ] First "quick win" task picked
-- [ ] First-commit checklist printed
-
----
-
-## Final Report
-
-```markdown
-## Onboarding Complete: {project}
-
-### Mental Model
-- Stack: {...}
-- Architecture: {...}
-- {N} domains identified
-
-### Output
-- Saved 1-page overview to {path}
-- "Where to find things" table → {path}
-- Gotchas list → {path}
-
-### First Commit
-- Task: {quick-win}
-- Local env: ✅ build / ✅ lint / ✅ tests
-- PR will follow: {project PR template}
-```
-
----
-
-## Hard Rules
-
-- **Read one module end-to-end before reading 10 partially** — the trace teaches more than skimming
-- **Capture gotchas as you find them** — they vanish from memory in days
-- **First commit ≤30 min** — bigger first changes get rabbit-holed
-- **Don't refactor on day 1** — earn context before changing conventions
-
----
-
-## Related Skills
-
-| When | Use |
-|------|-----|
-| Generate full doc site after onboarding | `/docs-sync` |
-| Build first real feature after onboarding | `/feature-new` |
-| First bug fix to learn the codebase | `/fix-hotfix` |
-| Author / update the onboarding doc itself | `/docs-write` |
-
-## Recommended Agents
-
-| Phase | Agent | Purpose |
-|-------|-------|---------|
-| SCAN | `@clean-architect` | Identify architecture pattern |
-| ANALYZE | `@clean-architect` | Layer + boundary analysis |
-| ANALYZE | `@code-reviewer` | Conventions + smell check |
-| ANALYZE | `@security-audit` | Security patterns |
-| EXPLAIN | `@docs-writer` | 1-page overview |
-| GUIDE | `@docs-writer` | First-commit checklist |

package/assets/skills/research/spike/SKILL.md

@@ -1,228 +0,0 @@
----
-name: research-spike
-description: Spike/Research workflow for exploring unknowns before committing to implementation. Use when researching, prototyping, doing proof of concept, or when user says "spike", "research", "prototype", "poc", "explore", "investigate".
----
-
-# Spike / Research Workflow
-
-Time-boxed exploration to de-risk a decision by **building** (not just reading). Produces a recommendation + ADR, not production code.
-
-## When to use this skill
-
-- ✅ Need to validate a technical assumption by building
-- ✅ Picking between 2+ options and need real comparison
-- ✅ De-risking a critical path before committing
-- ❌ Want to compare options via docs only → use `/research-web`
-- ❌ Already decided on the approach → use `/feature-new`
-- ❌ Stuck on a known bug → use `/fix-root-cause`
-
-## Read Architecture First
-
-Detect stack via `~/.claude/architecture/_shared/stack-detection.md`. Skim stack doc to understand current patterns — the spike output should fit the architecture or explicitly say why it doesn't.
-
----
-
-## Workflow
-
-```
-DEFINE → RESEARCH → PROTOTYPE → EVALUATE
-   ↑                                  │
-   └────── timebox expired ───────────┘
-```
-
----
-
-## Phase 1: DEFINE (15-30 min — never skip)
-
-**Goal:** lock the question, success criteria, timebox. Without these the spike has no exit condition.
-
-### Spike brief
-
-```markdown
-## Spike: {short name}
-
-### Question
-{ONE specific question — answerable yes/no or "pick A vs B vs C"}
-
-### Why now
-{What decision blocks on this answer? When is the decision needed?}
-
-### Options on the table
-- Option A: {name + 1 line}
-- Option B: {name + 1 line}
-- (Option C: only if relevant)
-
-### Success criteria
-- [ ] {Specific, observable — e.g., "P95 latency <50ms at 1k req/s"}
-- [ ] {e.g., "Integration with X library compiles + 1 test passes"}
-- [ ] {e.g., "Estimated migration effort ≤2 sprints"}
-
-### Timebox
-- Quick spike: 2-4 hours
-- Standard: 1-2 days
-- Deep spike: 3-5 days (rare — usually means scope is too big)
-
-### Red flags (stop early if hit)
-- Scope creep into productionising
-- Option requires breaking architecture rules
-- Two options become "obviously the same" after 1 hour
-```
-
-### Gate
-- [ ] Question is ONE specific question
-- [ ] Success criteria are observable (not "feels right")
-- [ ] Timebox + red flags written
-- [ ] User CONFIRMED brief before starting
-
----
-
-## Phase 2: RESEARCH (≤25% of timebox)
-
-**Goal:** know enough to prototype intelligently, don't over-read.
-
-Run `/research-web` for the topic if you haven't already. Capture:
-
-- Official docs URLs (read, don't just bookmark)
-- Known gotchas / GitHub issues for each option
-- Prior art: anyone tried this combo? what was their conclusion?
-- Constraints from existing stack (versions, license, infra)
-
-### Gate
-- [ ] At least 2 sources per option
-- [ ] Known gotchas listed
-- [ ] Constraints documented
-
----
-
-## Phase 3: PROTOTYPE (the bulk of the timebox)
-
-**Goal:** build the smallest thing that answers the question.
-
-### Rules
-- **Quick and dirty** — no tests beyond what's needed to verify the question
-- **One option at a time** — full prototype for A, then full prototype for B
-- **In a sandbox** — separate branch, never merge to main
-- **Time-stamped commits** — `spike: A reaches 1k req/s with sync handler` so the timeline is reviewable
-- **Stop on red flag** — if scope creeps or hits a wall, do not push through
-
-### What "smallest" means
-- Skip auth, skip error handling, skip pagination
-- Hardcode config that you'd normally pull from env
-- Stub anything not under test
-- 1-2 happy-path scenarios is enough to verify success criteria
-
-### Stop early when
-- All success criteria met for one option (don't gold-plate)
-- All options fail the same criterion (pivot the question)
-- Timebox 75% used and not converging (something's wrong — stop, regroup)
-
-### Gate
-- [ ] Each option prototyped to the point of answering the question
-- [ ] Success criteria measured (numbers, not vibes)
-- [ ] Findings captured in spike branch commits
-
----
-
-## Phase 4: EVALUATE
-
-**Goal:** turn the prototype into a recommendation + ADR.
-
-### Comparison matrix
-
-| Criterion | Option A | Option B | Notes |
-|-----------|----------|----------|-------|
-| Success criterion 1 (e.g., latency) | 42ms ✅ | 87ms ❌ | A at 1k rps, B saturates earlier |
-| Success criterion 2 (e.g., effort) | 1 sprint | 3 sprints | B requires new dependency |
-| Fit with architecture | ✅ | ⚠️ Requires port redesign | |
-| Risk | low | medium | B unknowns: lib maturity, no LTS |
-| Team familiarity | high | low | |
-
-### ADR template
-
-```markdown
-# ADR-NNN: {Decision title}
-
-## Status
-Accepted / Superseded / Deprecated
-
-## Context
-{What problem we faced, what alternatives we considered}
-
-## Decision
-{The chosen option}
-
-## Consequences
-**Positive:** {gains}
-**Negative:** {tradeoffs / debt taken on}
-
-## Spike evidence
-{Link to spike branch + key benchmark numbers}
-```
-
-### Cleanup
-- [ ] Spike branch tagged (`spike/{name}-{date}`) so it can be referenced
-- [ ] Spike code NOT merged — production should re-implement properly via `/feature-new`
-- [ ] ADR committed to `docs/adr/` (or equivalent)
-
-### Gate
-- [ ] Comparison matrix filled with real numbers
-- [ ] Recommendation explicit (don't say "both are fine")
-- [ ] ADR written
-- [ ] Spike branch tagged + NOT merged
-
----
-
-## Final Report
-
-```markdown
-## Spike Complete: {name}
-
-### Question
-{From DEFINE}
-
-### Recommendation
-**Pick Option {X}** because {top reason backed by spike evidence}
-
-### Evidence
-{Benchmark numbers, screenshots, error logs — link to spike branch}
-
-### Next step
-- If accepted: `/feature-new` to build it properly
-- If rejected: document why + close the question
-
-### Time spent
-{Actual vs timebox — note overruns for retrospective}
-```
-
----
-
-## Hard Rules
-
-- **Define before building** — undefined spike = unbounded spike
-- **Timebox is sacred** — overrun means the question is wrong, not the answer
-- **Throwaway code** — spike branch never merges to main
-- **Numbers, not vibes** — recommendation must cite measurements
-- **One question per spike** — multiple questions = multiple spikes
-
----
-
-## Related Skills
-
-| When | Use |
-|------|-----|
-| Compare options via docs only (no code) | `/research-web` |
-| Spike done, ready to implement properly | `/feature-new` |
-| Spike revealed a bug to investigate | `/fix-root-cause` |
-| Document the ADR as a doc page | `/docs-write` |
-
-## Recommended Agents
-
-| Phase | Agent | Purpose |
-|-------|-------|---------|
-| DEFINE | `@clean-architect` | Frame the question |
-| RESEARCH | `@api-designer` | API / integration research |
-| RESEARCH | `@db-designer` | Data model research |
-| RESEARCH | `@security-audit` | Security implications |
-| PROTOTYPE | Stack-specific dev agent | Build the POC |
-| EVALUATE | `@clean-architect` | Architecture impact |
-| EVALUATE | `@docs-writer` | Write the ADR |

package/assets/skills/research/web/SKILL.md

@@ -1,204 +0,0 @@
----
-name: research-web
-description: Research solutions on the internet for a given topic or the current conversation context. Use when user says "research", "tìm giải pháp", "search solution", "investigate", "find best practice", "so sánh giải pháp".
-args: "[TOPIC]"
----
-
-# Research Solutions
-
-Research solutions on the web for a specific problem. Output: a written recommendation with sources. **Never implement** — wait for user approval, then hand off to `/feature-new` / `/research-spike`.
-
-**ARGUMENTS:** (optional) topic to research. If omitted, infer from current conversation context.
-
-## When to use this skill
-
-- ✅ You don't know the right solution / library / pattern yet
-- ✅ Need to compare multiple approaches before committing
-- ✅ Stack / framework changed, best practices may have shifted
-- ❌ You already know the approach → `/feature-new` or `/fix-hotfix`
-- ❌ Want to validate by building → `/research-spike`
-- ❌ Debugging a known bug → `/fix-root-cause`
-
----
-
-## Workflow
-
-```
-IDENTIFY → DETECT STACK → SEARCH → SYNTHESIZE → PROPOSE
-```
-
----
-
-## Step 1: IDENTIFY
-
-### Mode 1 — argument provided
-- Use the argument as the topic
-- If too broad, narrow using project context **before** any search
-
-### Mode 2 — no argument
-- Analyze conversation: recent messages, open file, current task
-- **Summarize the problem back to user, get confirmation** before burning search budget
-
-### Research budget guide
-
-| Scope | Budget | When to stop |
-|-------|--------|--------------|
-| Quick lookup (API behavior, error meaning) | 2-3 queries | First authoritative source confirms |
-| Solution comparison (2-3 options) | 5-8 queries | Each option has ≥2 independent sources |
-| Deep dive (new pattern, unfamiliar domain) | 10-15 queries | Recommendation is defensible |
-
-**Hard cap:** if you hit 15 queries without converging → stop, report what's found + ask user to narrow.
-
-### Gate
-- [ ] Problem statement confirmed (Mode 2)
-- [ ] Scope narrow enough to fit in budget
-- [ ] Budget agreed (default: 5-8 queries)
-
----
-
-## Step 2: DETECT STACK
-
-Use `~/.claude/architecture/_shared/stack-detection.md` for canonical detection rules.
-
-Capture for filter use:
-- Language + version (e.g., `Go 1.22`, `Node 20`, `Dart 3.4`)
-- Framework + version (e.g., `NestJS 10`, `Vite 5`, `Laravel 11`)
-- Architecture pattern (DDD / hexagonal / etc. — from project's architecture doc)
-- Hard constraints (license, runtime, infra — e.g., "must run on Cloudflare Workers")
-
-### Gate
-- [ ] Stack + version identified
-- [ ] Architecture context noted
-- [ ] Hard constraints captured
-
----
-
-## Step 3: SEARCH
-
-### Strategy
-1. **Broad first** — overview, common approaches, "X vs Y" comparisons
-2. **Deep dive** — official docs, GitHub issues, release notes, authoritative blogs
-3. **Counter-search** — actively look for criticism / failure stories of the leading option
-
-### Source priority
-
-| Priority | Source | Weight |
-|----------|--------|--------|
-| 1 | Official docs (current version) | Highest |
-| 2 | GitHub issues / release notes (project itself) | High — for quirks + known bugs |
-| 3 | Stack Overflow accepted answers (high score, recent) | Medium-high |
-| 4 | Authoritative blogs (framework authors, well-known engineers) | Medium |
-| 5 | Tutorials, course material | Low — risk of outdated patterns |
-| 6 | AI-generated content | Skip unless you can verify against #1-#4 |
-
-### Search tips
-- **Prefer English queries** — richer index; supplement with framework's primary docs language (e.g., Vietnamese for niche local libs)
-- Include library + version when version-sensitive: `nestjs 10 typeorm migrations`
-- Quote exact error messages
-- Cross-validate ≥2 independent sources before concluding
-
-### When sources conflict
-
-Decision tree:
-1. **Different versions?** → trust the one matching project version
-2. **One is official docs?** → trust official
-3. **Different dates, same authority?** → trust newest, note the change
-4. **Same date, different authority?** → trust higher-authority source per priority table
-5. **Cannot resolve?** → present both, recommend the lower-risk option, explain trade-off
-
-Always **note the conflict** in the report — don't silently pick one side.
-
-### Gate
-- [ ] ≥2 independent sources per option
-- [ ] Sources <2 years old (or evergreen explicitly justified)
-- [ ] Counter-search done for the leading option
-
----
-
-## Step 4: SYNTHESIZE
-
-### Comparison matrix (when ≥2 options)
-
-```markdown
-| Criterion | Option A | Option B | Option C |
-|-----------|----------|----------|----------|
-| Maintenance status | active (releases 2025) | last release 2023 | active |
-| License | MIT | Apache-2.0 | BSL (commercial) |
-| Stack fit ({your stack}) | native support | adapter required | native |
-| Performance (cite source) | 8k rps (link) | 5k rps | 12k rps |
-| Operational complexity | low | medium | high |
-| Community size | 25k stars | 8k stars | 2k stars |
-| Known issues | #1234 (workaround exists) | #56 (no fix) | none |
-| Migration cost from current | low | medium | high |
-```
-
-### Report template
-
-```markdown
-## Problem
-{One paragraph: what we're solving, stack, constraints, goal}
-
-## Options Considered
-{Brief: A, B, C — one line each on what they are}
-
-## Comparison
-{matrix above}
-
-## Recommendation
-**{Option X}** because {1-2 strongest reasons backed by sources}.
-
-Trade-off: {what we give up by picking X over the runner-up}.
-
-## Pseudo-code (not for direct implementation)
-{Minimal sketch showing how X fits the project — adapt before shipping}
-
-## Caveats
-- {gotcha 1 with source link}
-- {gotcha 2}
-
-## Conflicts in sources
-- {if any — what disagreed, how it was resolved}
-
-## References
-- {url} — {what this gave us}
-- ...
-```
-
-### Gate
-- [ ] Recommendation is explicit (don't say "both are fine")
-- [ ] Trade-off named (what's lost by picking the winner)
-- [ ] Every non-trivial claim has a source link
-- [ ] Pseudo-code clearly marked as **not** for direct copy-paste
-
----
-
-## Hard Rules
-
-- **Research and propose — do NOT implement.** Wait for user confirmation
-- **Stack context matters** — idiomatic in one project, wrong in another
-- **Narrow when too broad** — "how to do auth" → "JWT refresh flow with NestJS + Passport"
-- **Flag stale answers** — if top result is 3+ years old and lib has major versions since, check release notes
-- **No hallucinated APIs** — verify method / option exists in official docs
-- **Cite every non-trivial claim**
-- **Note conflicts** between sources, don't silently pick
-- **Honor the budget** — 15 queries is the hard cap
-
----
-
-## Related Skills
-
-| When | Use |
-|------|-----|
-| Want to validate the chosen approach by prototyping | `/research-spike` |
-| Already know the approach, ready to build | `/feature-new` / `/fix-hotfix` |
-| Debugging a known bug | `/fix-root-cause` |
-| Write up the research as a design doc / ADR | `/docs-write` |
-
-## Recommended Agents
-
-| Phase | Agent | Purpose |
-|-------|-------|---------|
-| Search | `@docs-writer` | Frame output as design note |
-| Synthesize (API topics) | `@api-designer` | API pattern depth |
-| Synthesize (auth / crypto / data) | `@security-audit` | Security implications |
-| Synthesize (perf-sensitive) | `@perf-optimizer` | Benchmark interpretation |