moicle 1.7.0 → 2.1.0

package/README.md

@@ -14,10 +14,10 @@ A toolkit to bootstrap and accelerate project development with Claude Code throu
 
 ## Features
 
-- **15 AI Agents** - Specialized agents for each tech stack and task
-- **3 Commands** - Automation wizards for project setup, brainstorming, and documentation
-- **12 Skills** - Auto-triggered workflows for feature development, hotfix, PR review, and more
-- **7 Architecture References** - Clean Architecture patterns for all stacks
+- **16 AI Agents** - 6 developer agents + 10 utility agents
+- **4 Commands** - Wizards for bootstrap, brainstorm, documentation, and marketing
+- **21 Skills** - Auto-triggered workflows for the full SDLC (feature, bug, review, release, ops, content)
+- **8 Architecture References** - DDD + stack-specific patterns
 
 
 ## Current Support
@@ -114,29 +114,78 @@ moicle install --target codex --global
 
 ### Skills (21)
 
-| Skill | Trigger |
-|-------|---------|
-| `new-feature` | "implement feature", "add feature", "build feature" |
-| `hotfix` | "fix bug", "hotfix", "urgent fix", "production issue" |
-| `pr-review` | "review pr", "check pr", "review code" |
-| `review-changes` | "review changes", "review branch", "check branch", "review before pr" |
-| `release` | "release", "deploy" |
-| `deep-debug` | "deep debug", "trace bug", "find root cause", "hard bug" |
-| `refactor` | "refactor", "clean up", "improve code" |
-| `tdd` | "tdd", "test first", "test driven" |
-| `onboarding` | "explain codebase", "onboard", "new to project" |
-| `spike` | "spike", "prototype", "poc" |
-| `research` | "research", "tìm giải pháp", "find best practice" |
-| `documentation` | "document", "generate docs", "write docs" |
-| `api-integration` | "integrate api", "add endpoint", "new api" |
-| `incident-response` | "incident", "outage", "production down" |
-| `deprecation` | "deprecate", "remove feature", "sunset" |
-| `fix-pr-comment` | "fix pr comment", "address pr feedback" |
-| `architect-review` | "architect-review", "architecture review", "review ddd" |
-| `sync-docs` | "sync docs", "sync documentation", "doc sync" |
-| `logo-design` | "design logo", "brand identity" |
-| `video-content` | "create video", "video content", "video strategy" |
-| `content-writer` | "write content", "content strategy", "blog post" |
+Skills are grouped into 6 namespaces. Type `/<group>:<tab>` in Claude Code to see all skills in a group.
+
+**`/feature:*` — Build & Change**
+
+| Skill | When to use |
+|-------|-------------|
+| `/feature:new` | Build a new feature end-to-end following DDD |
+| `/feature:refactor` | Restructure existing module to DDD or improve internals |
+| `/feature:api` | Add a new endpoint or integrate an external API |
+| `/feature:deprecate` | Safely sunset a feature, API, or module |
+
+**`/fix:*` — Bugs & Incidents**
+
+| Skill | When to use |
+|-------|-------------|
+| `/fix:hotfix` | Fix a bug fast with a rollback plan |
+| `/fix:root-cause` | Hard-to-trace bug that has been "fixed" multiple times |
+| `/fix:incident` | Production outage / on-call workflow |
+| `/fix:pr-comment` | Address review comments on an existing PR |
+
+**`/review:*` — Review & Quality**
+
+| Skill | When to use |
+|-------|-------------|
+| `/review:branch` | Self-review your branch BEFORE pushing / opening PR |
+| `/review:pr` | Review someone else's open PR |
+| `/review:architect` | DDD compliance check (called by `/feature:new` / `/feature:refactor`) |
+| `/review:tdd` | Drive implementation with test-first discipline |
+
+**`/research:*` — Explore & Learn**
+
+| Skill | When to use |
+|-------|-------------|
+| `/research:web` | Search the web for solutions / best practices |
+| `/research:spike` | Time-boxed prototype to learn / decide |
+| `/research:onboarding` | Get up to speed on a new codebase |
+
+**`/docs:*` — Project Documentation**
+
+| Skill | When to use |
+|-------|-------------|
+| `/docs:write` | Author docs manually (README / API / ARCH / CONTRIB) |
+| `/docs:sync` | Auto-generate structured docs from codebase with review loop |
+
+**`/marketing:*` — Brand & Content** (wrapped by the `/marketing` command)
+
+| Skill | When to use |
+|-------|-------------|
+| `/marketing:content` | Multi-post content strategy (pillars, calendar, channels) |
+| `/marketing:seo-blog` | Write ONE evergreen blog post optimized for Search + AI tools |
+| `/marketing:logo` | Logo + brand identity specification |
+| `/marketing:video` | Video script, storyboard, production plan |
+
+### Skill decision matrix
+
+When more than one skill could fit, use this matrix:
+
+| Situation | Use | Not |
+|-----------|-----|-----|
+| Bug just happened in prod, need fix in <1h | `/fix:hotfix` | `/fix:root-cause` (too slow) |
+| Bug keeps coming back after "fixes" | `/fix:root-cause` | `/fix:hotfix` (will repeat) |
+| About to push / open PR | `/review:branch` | `/review:pr` (that's for others') |
+| Reviewing teammate's PR | `/review:pr` | `/review:branch` (that's for own branch) |
+| Want to verify DDD compliance only | `/review:architect` | `/review:pr` (broader scope) |
+| Don't know the right solution yet | `/research:web` | `/research:spike` (skip if you can decide from docs) |
+| Need to validate an idea by building | `/research:spike` | `/feature:new` (commit only after spike) |
+| Writing README / API docs by hand | `/docs:write` | `/docs:sync` (overkill for single file) |
+| Generating full docs site from codebase | `/docs:sync` | `/docs:write` (manual is slower) |
+
+### Backward compatibility
+
+Old trigger phrases still work — they're kept in the skill `description` so Claude auto-invokes the right skill when the user says e.g. "deep debug", "hotfix", "review changes". The namespace `/group:action` is the new explicit invocation form.
 
 ## Architecture-First Approach
 

package/assets/architecture/_shared/severity-levels.md

@@ -0,0 +1,34 @@
+# Severity Levels — Canonical Reference
+
+Single source of truth for severity classification across review, hotfix, and incident workflows.
+
+## Code / Architecture Severity (review skills)
+
+| Level | Meaning | Examples |
+|-------|---------|----------|
+| **CRITICAL** | Architecture broken; ship-blocker | Build fails, circular imports, domain imports framework, secrets in code |
+| **HIGH** | DDD violation or correctness risk | Cross-domain import, business logic in wrong layer, no ports dir, N+1 query on main table, missing auth check |
+| **MEDIUM** | Structure issue or test gap | Anemic entity, fat controller, missing events, missing test for new code path, missing JSON tags |
+| **LOW** | Convention issue | File naming, redundant code, DTOs in wrong package, style nits |
+
+**Rule:** all CRITICAL/HIGH must be fixed before merge. MEDIUM allowed with explicit waiver. LOW = nice to fix.
+
+## Incident Severity (incident-response, hotfix)
+
+| Level | Description | First response | Examples |
+|-------|-------------|---------------|----------|
+| **P1** | Critical — complete outage / data loss / security breach | <15 min | Site down, DB corrupted, secret leak, all logins broken |
+| **P2** | High — major degradation, ≥50% users affected | <1 h | Login flow broken for one IdP, checkout fails, key endpoint 5xx |
+| **P3** | Medium — partial degradation, <50% users | <4 h | One feature broken, perf regression on a non-critical path |
+| **P4** | Low — minor issue, no significant impact | <24 h | UI glitch, typo in copy, deprecated warning |
+
+**Ambiguous P2 vs P3?** If revenue impact, security risk, or data integrity in question → P2. Otherwise P3.
+
+## Mapping between scales
+
+| Code severity | If found in PR | If found in production |
+|---------------|---------------|------------------------|
+| CRITICAL | Block merge | P1 incident |
+| HIGH | Request changes | P2 incident |
+| MEDIUM | Comment | P3 incident |
+| LOW | Comment / approve | P4 incident |

package/assets/architecture/_shared/stack-detection.md

@@ -0,0 +1,34 @@
+# Stack Detection — Canonical Reference
+
+Used by skills that need to pick the right stack-specific architecture doc and conventions.
+
+## Detection Rules
+
+Check files in this order. **First match wins.**
+
+| File / Pattern | Stack | Architecture doc |
+|----------------|-------|------------------|
+| `go.mod` | Go + Gin | `go-backend.md` |
+| `package.json` contains `"@nestjs/core"` | NestJS | `nodejs-nestjs.md` |
+| `package.json` + `vite.config.*` (no NestJS) | React + Vite | `react-frontend.md` |
+| `package.json` + `remix.config.*` | Remix | `remix-fullstack.md` |
+| `pubspec.yaml` | Flutter / Dart | `flutter-mobile.md` |
+| `composer.json` | Laravel / PHP | `laravel-backend.md` |
+| Workspace root has `pnpm-workspace.yaml` / `turbo.json` / `nx.json` | Monorepo | `monorepo.md` (plus the per-package stack above) |
+
+## Architecture Files Location (priority order)
+
+```
+.claude/architecture/{name}.md     # Project-specific — highest priority
+~/.claude/architecture/{name}.md   # Global
+```
+
+Always load **two files**:
+1. `ddd-architecture.md` — cross-stack DDD core rules
+2. The stack-specific doc from the table above
+
+## When stack is ambiguous
+
+- Multi-stack monorepo: ask the user which package / app the task targets
+- New project (no lock files yet): ask the user
+- Multiple lock files (e.g., `go.mod` + `package.json` for a hybrid service): both stacks apply; usually backend = primary

package/assets/commands/marketing.md

@@ -30,13 +30,13 @@ Let the user choose which areas to focus on:
 Which marketing areas do you want to plan?
 
 1. Logo & Brand Identity     — Design logo, colors, typography, brand guidelines
-                               Triggers skill: logo-design
+                               Triggers skill: /marketing:logo
 
 2. Video Content Strategy    — Plan video series, scripts, production, publishing
-                               Triggers skill: video-content
+                               Triggers skill: /marketing:video
 
 3. Content Writing Strategy  — Blog posts, social media, SEO, newsletter
-                               Triggers skill: content-writer
+                               Triggers skill: /marketing:content
 
 4. All of the Above          — Complete marketing plan (Recommended)
 
@@ -55,19 +55,19 @@ MARKETING PLAN WORKFLOW
 
 Phase 1: Brand Foundation
 │
-├── Execute: logo-design skill
+├── Execute: /marketing:logo skill
 │   └── Output: Brand guidelines, color palette, typography
 │
 ▼
 Phase 2: Content Strategy
 │
-├── Execute: content-writer skill
+├── Execute: /marketing:content skill
 │   └── Output: Content pillars, blog plan, social media plan, newsletter
 │
 ▼
 Phase 3: Video Content
 │
-├── Execute: video-content skill
+├── Execute: /marketing:video skill
 │   └── Output: Video series, scripts, production specs, calendar
 │
 ▼
@@ -85,7 +85,7 @@ Phase 5: Launch Plan
 
 ### Execution Notes:
 - Run skills sequentially — brand identity informs content and video decisions
-- Pass brand guidelines (colors, voice, tone) from logo-design into content-writer and video-content
+- Pass brand guidelines (colors, voice, tone) from /marketing:logo into /marketing:content and /marketing:video
 - Ensure consistency across all outputs
 
 ## Step 4: Create Unified Calendar

package/assets/skills/docs/sync/SKILL.md

@@ -0,0 +1,245 @@
+---
+name: docs-sync
+description: Sync documentation workflow - reads codebase and docs folder to generate structured output docs with architecture, use cases, diagrams, and README index. Includes automated review loop. Use when user says "sync docs", "sync documentation", "generate docs", "update docs sync", "doc sync".
+---
+
+# Sync Docs Workflow
+
+Generate a complete `docs/` site (business overview, architecture, use cases with sequence diagrams, README index) from the current codebase. Includes a 3-iteration auto-review loop.
+
+## When to use this skill
+
+- ✅ Re-generate the whole `docs/` site from current code
+- ✅ Existing docs have drifted; want batch sync with review loop
+- ✅ Project has no structured docs at all
+- ❌ Authoring a single doc by hand (README / API.md only) → use `/docs:write`
+- ❌ Understand the codebase, not document it → use `/research:onboarding`
+- ❌ Adding doc for one endpoint → use `/feature:api` Phase 4
+
+## Read Architecture First
+
+Detect stack via `~/.claude/architecture/_shared/stack-detection.md`. Read `ddd-architecture.md` + stack doc.
+
+---
+
+## Workflow
+
+```
+SCAN → CONFIRM mode → GENERATE → REVIEW loop (≤3x) → COMPLETE
+```
+
+`CONFIRM` asks the user to pick **REFACTOR** (full restructure of `docs/`) or **UPDATE** (keep existing structure, refresh content).
+
+---
+
+## Phase 1: SCAN
+
+**Goal:** map codebase + existing docs in one pass.
+
+```bash
+# Existing docs
+find . -name "*.md" -not -path "*/node_modules/*" -not -path "*/vendor/*" -not -path "*/.dart_tool/*" | sort
+ls docs/ 2>/dev/null
+
+# Code surface
+tree -L 4 -I 'node_modules|vendor|dist|build|.dart_tool|.git'
+
+# Entry points / use cases (per stack)
+# Go:       grep -r "func.*Handler" internal/
+# NestJS:   grep -r "@Controller\|@Get\|@Post" src/
+# Laravel:  cat routes/web.php routes/api.php
+# Remix:    ls app/routes/
+# Flutter:  grep -r "MaterialPageRoute\|GoRoute" lib/
+```
+
+### Extract
+- Stack + framework
+- All domains / modules
+- All user-facing flows (endpoints / screens / commands)
+- Existing docs structure (if any)
+
+### Gate
+- [ ] Stack identified
+- [ ] All domains listed
+- [ ] All use cases listed (count + brief name)
+- [ ] Existing docs inventoried
+
+---
+
+## Phase 1.5: CONFIRM
+
+Ask the user **explicitly** which mode:
+
+| Mode | When to use | Effect |
+|------|-------------|--------|
+| **REFACTOR** | Existing docs are messy / partial / wrong structure | Restructure `docs/` from scratch, may delete old files |
+| **UPDATE** | Existing structure is fine, content is stale | Keep file paths + headings, refresh content + add missing sections |
+
+If the user is unsure: default to **UPDATE** (less destructive).
+
+### Gate
+- [ ] User confirmed mode
+- [ ] If REFACTOR: explicit OK to remove old files
+
+---
+
+## Phase 2: GENERATE
+
+**Goal:** produce the target `docs/` tree.
+
+### Target structure (REFACTOR mode)
+
+```
+docs/
+├── README.md              # Index linking to everything below
+├── business.md            # WHAT the system does, for non-engineers
+├── architecture.md        # HOW it's structured (layers + domains + tech)
+├── use-cases/
+│   ├── README.md          # Index of use cases
+│   ├── <use-case-1>.md    # One file per user-facing flow, with sequence diagram
+│   └── ...
+├── api.md                 # If service has external API
+└── runbook.md             # How to run / deploy / debug
+```
+
+### File rules
+
+**`docs/README.md`** — index only (≤30 lines).
+- One-line description, link to each sub-doc, last-updated timestamp.
+
+**`docs/business.md`** — for non-engineers.
+- NO API endpoints, NO code blocks, NO file paths
+- Cover: what problem this solves, who uses it, key user journeys (named like a PRD), success metrics
+- Plain language, no jargon
+
+**`docs/architecture.md`** — for engineers.
+- Layer diagram (mermaid)
+- Domain list with 1-line responsibility
+- Cross-domain communication pattern
+- Tech decisions (DB, queue, cache, auth — with rationale)
+- Link to `~/.claude/architecture/<stack>.md` for layer rules
+
+**`docs/use-cases/<name>.md`** — one per flow.
+- Trigger (who, what action)
+- Preconditions
+- Sequence diagram (mermaid `sequenceDiagram`) showing actor → handler → usecase → infra → response
+- Postconditions / side effects (events raised, notifications sent)
+- Errors (each with HTTP code + meaning)
+
+**`docs/api.md`** — only if external API exists.
+- Auth, base URL, error format, pagination — then endpoint table
+- For deep API ref, link to OpenAPI spec
+
+**`docs/runbook.md`** — for ops / on-call.
+- Local dev (≤5 commands)
+- Deploy steps
+- Common failures + how to recover
+- Monitoring dashboards + log queries
+
+### Mermaid rules
+
+- Sequence diagrams for use cases
+- Class diagrams only when ER is non-obvious
+- Validate syntax: `mermaid-cli` if available, otherwise eyeball test
+- ≤7 actors per sequence (split if more)
+
+### Gate
+- [ ] All target files written
+- [ ] business.md has zero code / endpoints
+- [ ] Every use case has a sequence diagram
+- [ ] README.md links to every file
+- [ ] All file paths in docs resolve (no broken references)
+
+---
+
+## Phase 3: REVIEW LOOP (≤3 iterations)
+
+**Goal:** auto-check + fix until docs pass.
+
+For each iteration:
+
+### 3.1 Structure
+- [ ] All target files exist
+- [ ] README.md links resolve
+- [ ] No duplicate content across files
+
+### 3.2 Business
+- [ ] business.md uses plain language (no `API`, `JSON`, `class`, file paths)
+- [ ] business.md covers all top-level user journeys
+
+### 3.3 Architecture
+- [ ] Layer diagram matches actual code structure
+- [ ] Every code domain has a row in domain table
+
+### 3.4 Use cases
+- [ ] One file per identified use case (Phase 1)
+- [ ] Each has trigger / preconditions / sequence / postconditions / errors
+- [ ] Sequence diagrams render
+
+### 3.5 Consistency
+- [ ] Same terminology everywhere (e.g., "domain" vs "module")
+- [ ] No file paths referenced that don't exist
+- [ ] No endpoints referenced that don't exist in code
+
+### Loop
+- If any check fails → fix that section, restart the relevant subset of checks
+- Max 3 iterations; if still failing → report what's blocking + ask user
+
+---
+
+## Phase 4: COMPLETE
+
+```markdown
+## Docs Sync Complete
+
+### Mode: {REFACTOR / UPDATE}
+
+### Files
+- Created: {N}
+- Updated: {N}
+- Deleted: {N — REFACTOR mode only}
+
+### Coverage
+- Domains documented: {N/N}
+- Use cases documented: {N/N}
+- Diagrams: {N}
+
+### Review iterations: {1/2/3}
+
+### Next steps for the team
+- Review `docs/business.md` with product
+- Validate `docs/use-cases/*.md` flows with team leads
+- Set up doc lint in CI (broken-link checker)
+```
+
+---
+
+## Hard Rules
+
+- **business.md is for humans** — strip jargon, no code, no file paths
+- **architecture.md links to canonical rules**, doesn't duplicate them
+- **One use case per file** — easier to update, easier to review
+- **Mermaid only if it renders** — broken diagrams worse than no diagrams
+- **REFACTOR mode requires explicit user OK** — never delete docs without confirmation
+- **Max 3 review iterations** — beyond that, the prompt or scope is the problem, not the docs
+
+---
+
+## Related Skills
+
+| When | Use |
+|------|-----|
+| Author single doc by hand | `/docs:write` |
+| Onboard self / new dev | `/research:onboarding` |
+| Doc only one new endpoint | `/feature:api` Phase 4 |
+| Architecture itself needs review | `/review:architect` |
+
+## Recommended Agents
+
+| Phase | Agent | Purpose |
+|-------|-------|---------|
+| SCAN | `@clean-architect` | Identify domains + patterns |
+| GENERATE | `@docs-writer` | Write all doc files |
+| GENERATE | `@api-designer` | API reference accuracy |
+| GENERATE | `@db-designer` | Data model accuracy |
+| REVIEW | `@code-reviewer` | Verify code refs resolve |