moicle 1.6.0 → 2.0.0

package/README.md

@@ -14,15 +14,16 @@ 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
+- **20 Skills** - Auto-triggered workflows for the full SDLC (feature, bug, review, release, ops, content)
+- **8 Architecture References** - DDD + stack-specific patterns
 
 
 ## Current Support
 
 - [x] Claude
+- [x] Codex CLI
 - [ ] Antigravity
 - [ ] Cursor
 - [ ] Windsurf
@@ -39,10 +40,12 @@ npm install -g moicle
 # Install agents, commands, skills, architecture
 moicle install
 
+# Install for Codex CLI
+moicle install --target codex --global
+
 # Choose:
-# 1. Global (~/.claude/)     - Use for all projects
-# 2. Project (./.claude/)    - Current project only
-# 3. Both                    - Both locations
+# 1. Pick Claude Code or Codex CLI
+# 2. Pick global or project scope
 ```
 
 ## CLI Commands
@@ -52,6 +55,8 @@ moicle install
 | `moicle install` | Interactive installation menu |
 | `moicle install --global` | Install to ~/.claude/ (symlinks) |
 | `moicle install --project` | Install to ./.claude/ (copies) |
+| `moicle install --target codex --global` | Install Codex skills + architecture to ~/.codex/ |
+| `moicle install --target codex --project` | Install Codex skills + architecture to ./.codex/ |
 | `moicle list` | List all installed items |
 | `moicle status` | Show enabled/disabled status |
 | `moicle enable <item>` | Enable an agent/command/skill |
@@ -107,31 +112,74 @@ moicle install
 | `/brainstorm` | Brainstorm ideas with 6 frameworks |
 | `/doc` | Scan project and generate documentation |
 
-### 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 (20)
+
+Skills are grouped into 5 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:*` — Docs & Content**
+
+| Skill | When to use |
+|-------|-------------|
+| `/docs:write` | Author docs manually (README / API / ARCH / CONTRIB) |
+| `/docs:sync` | Auto-generate structured docs from codebase with review loop |
+| `/docs:content` | Blog posts, social media, newsletters, SEO content |
+| `/docs:logo` | Logo + brand identity specification |
+| `/docs: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
 
@@ -155,6 +203,8 @@ All agents reference architecture files to ensure consistency:
 
 When an agent is invoked, it **reads the architecture file first** before coding according to the defined structure.
 
+For Codex CLI, MoiCle installs architecture docs into `~/.codex/architecture` or `./.codex/architecture`, and converts MoiCle agents, commands, and existing skills into native Codex skills under `.codex/skills`. Restart Codex after a global install so the new skills are loaded.
+
 ## Usage Examples
 
 ### Using Commands

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

@@ -0,0 +1,269 @@
+---
+name: docs-content
+description: Create content writing strategy including blog posts, social media, newsletters, and SEO content plans. Use when user says "write content", "content strategy", "blog post", "social media content", "content plan", "seo content", "newsletter".
+---
+
+# Content Writer
+
+Workflow for creating content strategy: audience research, content pillars, SEO blog posts, social media plans, newsletters.
+
+## When to use this skill
+
+- ✅ Building a content strategy from scratch (pillars, calendar, channels)
+- ✅ Writing one specific piece (blog post, newsletter, social thread)
+- ✅ Repurposing one piece into multi-channel content
+- ❌ Writing API / project documentation → use `/docs:write` or `/docs:sync`
+- ❌ Writing release notes / changelog → use git history + manual
+- ❌ Designing a video → use `/docs:video`
+
+---
+
+## Workflow
+
+```
+RESEARCH → PLAN → WRITE → OPTIMIZE → DISTRIBUTE
+```
+
+---
+
+## Phase 1: RESEARCH
+
+**Goal:** understand audience, competitors, and SEO landscape.
+
+### Gather brief
+Ask the user for (skip what's already known):
+
+| Field | Example |
+|-------|---------|
+| Brand / Product | "Acme — DevOps platform for indie teams" |
+| Voice / Tone | "Casual but technical, no marketing fluff" |
+| Primary audience | "Solo / small-team DevOps engineers" |
+| Pain points | "Too many tools, none integrate well" |
+| Goals (pick ≤2) | SEO traffic, lead gen, brand awareness, education, community, thought leadership |
+| Current channels | Blog / X / LinkedIn / Dev.to / YouTube / Newsletter / Discord |
+| Competitors | 3–5 names + what they do well |
+
+### Audience & SEO research
+- **Search intent** for the topic (informational / navigational / transactional / commercial)
+- **Top 10 SERP** results for 3–5 target keywords — what content ranks?
+- **Gaps** competitors miss (more depth, better examples, fresher data)
+- **Keyword set** — primary + 2–5 long-tails per piece
+
+### Gate
+- [ ] Brief captured (skip fields already covered in conversation)
+- [ ] Target keywords with search intent identified
+- [ ] Competitor gap identified
+
+---
+
+## Phase 2: PLAN
+
+**Goal:** define content pillars + calendar.
+
+### Content pillars
+Pick 3–5 themes that ladder up to the brand's positioning. Each pillar gets a mix of formats.
+
+| Pillar | Why it matters to audience | Formats |
+|--------|---------------------------|---------|
+| {pillar 1} | {pain → outcome} | blog, social, newsletter |
+| {pillar 2} | ... | ... |
+
+### Calendar template
+Plan 4–6 weeks ahead. Use a consistent cadence.
+
+| Week | Blog (long-form) | Social (short-form) | Newsletter |
+|------|------------------|---------------------|------------|
+| W1 | {title} | 3 posts (1 educational, 1 hot take, 1 personal) | {topic} |
+| W2 | ... | ... | ... |
+
+### Content mix rule (per channel)
+- **80/20:** 80% value (educate / entertain), 20% promote
+- **Don't post when you have nothing to say** — skip a slot rather than post filler
+
+### Gate
+- [ ] 3–5 pillars defined with audience rationale
+- [ ] Calendar drafted for ≥4 weeks
+- [ ] Channels matched to audience habits
+
+---
+
+## Phase 3: WRITE
+
+**Goal:** draft the actual content. One format at a time.
+
+### Blog post structure (long-form, SEO)
+
+```
+TITLE (≤60 chars, includes primary keyword)
+META DESCRIPTION (≤155 chars, includes primary keyword + CTA)
+
+H1 (matches title or close variant)
+
+HOOK (2–3 sentences: the problem the reader has)
+
+TL;DR (3 bullets: the answer up front)
+
+H2: Problem context — why this matters now
+H2: The solution — your main argument / approach
+   H3: Step 1 / Aspect 1
+   H3: Step 2
+   H3: Step 3
+H2: Common pitfalls — what NOT to do
+H2: Real example — actual code / screenshot / case
+H2: Next steps — what to do today
+
+CTA (1 line: try the product / subscribe / share)
+```
+
+Target length: 1200–2500 words for SEO; 500–1000 for opinion pieces.
+
+### Social thread (X / LinkedIn)
+
+```
+HOOK (1–2 lines — must work alone in the feed)
+↓
+3–7 posts each ≤280 chars
+- Each post stands alone if shared
+- One idea per post
+- Use line breaks
+↓
+CTA (link to blog / signup)
+```
+
+### Newsletter
+
+```
+SUBJECT (≤50 chars, curiosity > clickbait)
+PREVIEW TEXT (≤90 chars, complements subject)
+
+GREETING (personal, 1–2 lines)
+
+MAIN STORY (1 idea, 200–400 words)
+
+LINKS (3–5 curated, with 1-line why-it-matters)
+
+CTA (one ask only)
+
+SIGNATURE
+```
+
+### Writing rules
+- **One idea per paragraph** (≤4 lines)
+- **Active voice** ("the API returns" not "is returned by the API")
+- **Concrete > abstract** (numbers, code, screenshots, names)
+- **Cut filler:** "in order to" → "to", "due to the fact that" → "because", "very important" → "critical"
+- **Read aloud** before publishing — if you stumble, rewrite
+
+### Gate
+- [ ] Draft matches the format's structure
+- [ ] Primary keyword in title + H1 + first 100 words (blog)
+- [ ] Read aloud — no stumbles
+- [ ] At least 1 concrete example (number, code, screenshot, name)
+
+---
+
+## Phase 4: OPTIMIZE
+
+**Goal:** make the content perform.
+
+### Combined checklist (SEO + quality)
+- [ ] Title ≤60 chars, includes primary keyword
+- [ ] Meta description ≤155 chars
+- [ ] H1 matches search intent
+- [ ] H2/H3 use related keywords naturally
+- [ ] Alt text on all images
+- [ ] Internal links to ≥2 related posts
+- [ ] External links to ≥1 authoritative source per major claim
+- [ ] No keyword stuffing (read naturally)
+- [ ] Mobile-friendly: short paragraphs, clear hierarchy
+- [ ] Reading level appropriate for audience (Hemingway grade ≤10 for general)
+- [ ] No typos (run a checker)
+
+### Gate
+- [ ] All checklist items pass (or explicit waiver)
+
+---
+
+## Phase 5: DISTRIBUTE
+
+**Goal:** get the content in front of the right people.
+
+### Per-channel adaptation
+
+| Channel | Adaptation |
+|---------|------------|
+| Blog | Full piece, optimized for search |
+| X | Thread of 3–7 posts pulling key insights + link to blog |
+| LinkedIn | 1 long-form post (200–500 words), no link in body (link in comments) |
+| Dev.to / Hashnode | Republish blog with canonical link to original |
+| Reddit | Comment in relevant thread first, then share post only if community allows |
+| Newsletter | Featured story or short blurb + link |
+| YouTube Shorts / TikTok | 30–60 sec extract of key insight |
+
+### Tracking
+- UTM tags per channel: `?utm_source=X&utm_medium=social&utm_campaign={pillar}`
+- Track per piece: views, time-on-page, scroll depth, conversions
+- Iterate: double down on what works, kill what doesn't after 3 attempts
+
+### Gate
+- [ ] Adapted for each chosen channel
+- [ ] UTM tags applied
+- [ ] Tracking in place
+
+---
+
+## Final Report
+
+```markdown
+## Content Plan: {brand / campaign}
+
+### Strategy
+- Pillars: {list}
+- Audience: {one line}
+- Goal: {primary}
+
+### Calendar (next 4 weeks)
+{table}
+
+### Pieces Drafted
+| Title | Format | Status | Channel |
+|-------|--------|--------|---------|
+| ... | blog | published | site + X + LinkedIn |
+
+### Metrics to Watch
+- {KPI 1, baseline → target}
+- {KPI 2}
+```
+
+---
+
+## Hard Rules
+
+- **One idea per piece** — if you have two, write two pieces
+- **No filler** — every paragraph earns its place
+- **No keyword stuffing** — write for humans first, search engines second
+- **Skip a slot rather than post filler**
+- **Iterate based on data** — kill what doesn't work after 3 attempts
+
+---
+
+## Related Skills
+
+| When | Use |
+|------|-----|
+| Building brand identity (logo + colors) | `/docs:logo` |
+| Creating video scripts / storyboards | `/docs:video` |
+| Building a full marketing plan | `/marketing` (combines all three) |
+| Writing project documentation | `/docs:write` |
+
+---
+
+## Recommended Agents
+
+| Phase | Agent | Purpose |
+|-------|-------|---------|
+| RESEARCH | `@docs-writer` | Document research findings |
+| PLAN | `@clean-architect` | Structure pillars and calendar |
+| WRITE | `@docs-writer` | Draft pieces |
+| OPTIMIZE | `@security-audit` | Check for sensitive content / claims |
+| DISTRIBUTE | `@docs-writer` | Channel adaptations |

package/assets/skills/{logo-design → docs/logo}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: logo-design
+name: docs-logo
 description: Generate comprehensive logo design specifications, brand identity guidelines, and visual concepts. Use when user says "design logo", "create logo", "brand identity", "logo concept", "visual identity".
 ---
 
@@ -7,26 +7,21 @@ description: Generate comprehensive logo design specifications, brand identity g
 
 Structured workflow for creating professional logo design specifications, brand guidelines, and visual identity systems.
 
-## Workflow Overview
+## When to use this skill
+
+- ✅ Brand new identity (no existing logo)
+- ✅ Rebrand / refresh of an existing logo + guidelines
+- ✅ Need a deliverable spec for a designer to execute
+- ❌ Just need a quick icon variation → use a design tool directly
+- ❌ Want a full marketing plan (logo + content + video) → use `/marketing`
+- ❌ Need video brand visuals → use `/docs:video`
+
+## Workflow
 
 ```
 DISCOVER → CONCEPT → DESIGN → REFINE → DELIVER
-    │          │         │        │         │
-    ▼          ▼         ▼        ▼         ▼
-  Brand    3 Logo    Specify   Iterate   Final
-  Audit    Concepts  Colors    Based on  Assets &
-  & Brief           & Type    Feedback  Guidelines
 ```
 
-## Recommended Agents
-
-| Phase | Agent | Purpose |
-|-------|-------|---------|
-| DISCOVER | @docs-writer | Document brand brief |
-| CONCEPT | @clean-architect | Structure design system |
-| DESIGN | @docs-writer | Specification documents |
-| DELIVER | @docs-writer | Brand guidelines document |
-
 ---
 
 ## Phase 1: DISCOVER
@@ -475,3 +470,23 @@ colors: {
 - [ ] Social media sizes specified
 - [ ] Brand guidelines document delivered
 - [ ] Developer implementation notes provided
+
+---
+
+## Related Skills
+
+| When | Use |
+|------|-----|
+| Full marketing plan (logo + content + video) | `/marketing` |
+| Write content using the new brand | `/docs:content` |
+| Create video using the brand | `/docs:video` |
+| Document the brand guidelines | `/docs:write` |
+
+## Recommended Agents
+
+| Phase | Agent | Purpose |
+|-------|-------|---------|
+| DISCOVER | `@docs-writer` | Document brand brief |
+| CONCEPT | `@clean-architect` | Structure the design system |
+| DESIGN | `@docs-writer` | Specification documents |
+| DELIVER | `@docs-writer` | Brand guidelines document |

package/assets/skills/{sync-docs → docs/sync}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: sync-docs
+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".
 ---
 
@@ -7,6 +7,15 @@ description: Sync documentation workflow - reads codebase and docs folder to gen
 
 Automated workflow that reads codebase and existing docs to generate a complete, structured documentation output with architecture overview, use case diagrams, and a README index linking all sub-files.
 
+## When to use this skill
+
+- ✅ Need to (re)generate a whole `docs/` site from current codebase state
+- ✅ Existing docs have drifted from code and you want batch sync + review loop
+- ✅ Onboarding a project that has no structured docs at all
+- ❌ Authoring a single doc by hand (README / API.md only) → use `/docs:write`
+- ❌ Need to understand the codebase, not document it → use `/research:onboarding`
+- ❌ Adding one new endpoint's doc only → use `/feature:api` Phase 4
+
 ## Workflow Overview
 
 ```
@@ -573,3 +582,24 @@ Documentation sync is complete when:
 6. All file paths and names match actual codebase
 7. All mermaid diagrams are valid
 8. Review loop passed all checks
+
+---
+
+## Related Skills
+
+| When | Use |
+|------|-----|
+| Authoring a single doc by hand | `/docs:write` |
+| Onboarding self / a new dev to the project | `/research:onboarding` |
+| Adding only an endpoint's doc | `/feature:api` Phase 4 |
+| The architecture itself needs a review | `/review:architect` |
+
+## Recommended Agents
+
+| Phase | Agent | Purpose |
+|-------|-------|---------|
+| SCAN | `@clean-architect` | Identify domains and patterns |
+| GENERATE | `@docs-writer` | Write all doc files |
+| GENERATE | `@api-designer` | API reference accuracy |
+| GENERATE | `@db-designer` | Data model doc |
+| REVIEW | `@code-reviewer` | Verify code references resolve |

package/assets/skills/{video-content → docs/video}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: video-content
+name: docs-video
 description: Plan and produce video content strategy including scripts, storyboards, and production specs. Use when user says "create video", "video content", "video script", "video strategy", "youtube content", "video plan".
 ---
 
@@ -7,27 +7,21 @@ description: Plan and produce video content strategy including scripts, storyboa
 
 Structured workflow for planning video content — from strategy and scripting to production specs and publishing schedule.
 
-## Workflow Overview
+## When to use this skill
+
+- ✅ Planning a video series or campaign (multi-video)
+- ✅ Need a script + storyboard + production spec for a single video
+- ✅ Repurposing existing long-form into shorts / clips
+- ❌ Just need ideas, not a plan → use `brainstorm`
+- ❌ Want full marketing plan (logo + content + video) → use `/marketing`
+- ❌ Writing a blog post or thread, not video → use `/docs:content`
+
+## Workflow
 
 ```
 STRATEGY → SCRIPT → STORYBOARD → PRODUCTION → PUBLISH
-    │          │          │            │           │
-    ▼          ▼          ▼            ▼           ▼
-  Define    Write      Visual       Tech        Calendar
-  Series    Scripts    Flow &      Specs &     & Platform
-  & Goals   & Hooks   Scenes      Checklist   Distribution
 ```
 
-## Recommended Agents
-
-| Phase | Agent | Purpose |
-|-------|-------|---------|
-| STRATEGY | @docs-writer | Document content strategy |
-| SCRIPT | @docs-writer | Write scripts and outlines |
-| STORYBOARD | @docs-writer | Scene descriptions |
-| PRODUCTION | @devops | Technical setup specs |
-| PUBLISH | @docs-writer | Publishing calendar |
-
 ---
 
 ## Phase 1: STRATEGY
@@ -649,3 +643,24 @@ VIDEO KPIs
 - [ ] Publishing calendar created
 - [ ] Cross-posting strategy defined
 - [ ] KPIs set and tracking plan ready
+
+---
+
+## Related Skills
+
+| When | Use |
+|------|-----|
+| Full marketing plan (logo + content + video) | `/marketing` |
+| Need brand visuals first | `/docs:logo` |
+| Repurposing video → blog / threads | `/docs:content` |
+| Brainstorm video topics | `brainstorm` |
+
+## Recommended Agents
+
+| Phase | Agent | Purpose |
+|-------|-------|---------|
+| STRATEGY | `@docs-writer` | Document content strategy |
+| SCRIPT | `@docs-writer` | Write scripts and hooks |
+| STORYBOARD | `@docs-writer` | Scene descriptions |
+| PRODUCTION | `@devops` | Tech setup specs |
+| PUBLISH | `@docs-writer` | Publishing calendar |