moicle 2.3.1 → 3.0.0

package/README.md

@@ -16,7 +16,7 @@ A toolkit to bootstrap and accelerate project development with Claude Code throu
 
 - **16 AI Agents** - 6 developer agents + 10 utility agents
 - **4 Commands** - Wizards for bootstrap, brainstorm, documentation, and marketing
-- **22 Skills** - Auto-triggered workflows for the full SDLC (feature, bug, review, release, ops, content)
+- **9 Skills** - Mode-based, auto-triggered workflows for the full SDLC (feature, bug, review, research, docs, marketing)
 - **9 Architecture References** - DDD + Hexagonal + stack-specific patterns
 
 
@@ -124,82 +124,69 @@ moicle install --target cursor --project
 | `/brainstorm` | Brainstorm ideas with 6 frameworks |
 | `/doc` | Scan project and generate documentation |
 
-### Skills (22)
+### Skills (9)
 
-Skills are grouped by a `<group>-` prefix. Type `/<group>-` then `Tab` in Claude Code to see all skills in a group.
+Skills are grouped by a `<group>-` prefix. Type `/<group>-` then `Tab` in Claude Code to see all skills in a group. Each skill bundles several related workflows into **modes** chosen at the top of the file — pick a mode (or let Claude pick it from your natural-language phrasing).
 
 **`/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 |
-| `/feature-track` | Plan + approve, then run a tracked loop: branch → checklist → per-item test/implement/verify/commit |
+| Skill | Modes | When to use |
+|-------|-------|-------------|
+| `/feature-build` | NEW · REFACTOR · API · DEPRECATE | Build a new DDD feature, restructure existing code, add/integrate an API, or safely sunset a feature |
+| `/feature-track` | — | Plan + approve, then run a tracked loop: branch → checklist → per-item test/implement/verify/commit |
 
 **`/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 |
+| Skill | Modes | When to use |
+|-------|-------|-------------|
+| `/fix-bug` | QUICK · DEEP | QUICK: fix fast with rollback plan · DEEP: trace a hard / recurring / intermittent bug |
+| `/fix-incident` | — | Production outage / on-call workflow |
 
 **`/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 |
+| Skill | Modes | When to use |
+|-------|-------|-------------|
+| `/review-code` | SELF · PR · ARCHITECT · TDD · ADDRESS | Self-review a branch, review a teammate's PR, deep DDD audit, test-first development, or address PR comments |
 
 **`/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 |
+| Skill | Modes | When to use |
+|-------|-------|-------------|
+| `/research-explore` | WEB · SPIKE · ONBOARDING | Research solutions via docs, validate by building a prototype, or ramp up 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 |
+| Skill | Modes | When to use |
+|-------|-------|-------------|
+| `/docs-sync` | SINGLE · FULL | SINGLE: hand-author one doc · FULL: auto-generate the whole docs site 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 | Modes | When to use |
+|-------|-------|-------------|
+| `/marketing-content` | STRATEGY · POST | Multi-post content strategy, or write ONE evergreen post optimized for Search + AI |
+| `/marketing-brand` | LOGO · VIDEO | Logo + brand identity spec, or video script/storyboard/production plan |
 
 ### Skill decision matrix
 
-When more than one skill could fit, use this matrix:
+When more than one skill / mode 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) |
-| Driving a multi-step task as a checklist with commit-per-step | `/feature-track` | `/feature-new` (single full DDD feature), `/review-tdd` (one unit, no branch/commit) |
-| 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) |
+| Bug just happened in prod, need fix in <1h | `/fix-bug` (QUICK) | `/fix-bug` DEEP (too slow) |
+| Bug keeps coming back after "fixes" | `/fix-bug` (DEEP) | `/fix-bug` QUICK (will repeat) |
+| About to push / open PR | `/review-code` (SELF) | `/review-code` PR (that's for others') |
+| Reviewing teammate's PR | `/review-code` (PR) | `/review-code` SELF (that's for own branch) |
+| Want to verify DDD compliance only | `/review-code` (ARCHITECT) | `/review-code` PR (broader scope) |
+| Don't know the right solution yet | `/research-explore` (WEB) | SPIKE (skip if you can decide from docs) |
+| Need to validate an idea by building | `/research-explore` (SPIKE) | `/feature-build` NEW (commit only after spike) |
+| Driving a multi-step task as a checklist with commit-per-step | `/feature-track` | `/feature-build` NEW (single full DDD feature), `/review-code` TDD (one unit, no branch/commit) |
+| Writing README / API docs by hand | `/docs-sync` (SINGLE) | `/docs-sync` FULL (overkill for single file) |
+| Generating full docs site from codebase | `/docs-sync` (FULL) | `/docs-sync` SINGLE (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 flattened name `/group-action` is the explicit invocation form.
+The 22 original skills were consolidated into 9 mode-based skills. Old trigger phrases still work — they're kept in each skill's `description` so Claude auto-invokes the right skill **and the right mode** when the user says e.g. "deep debug" (→ `/fix-bug` DEEP), "hotfix" (→ `/fix-bug` QUICK), "review changes" (→ `/review-code` SELF). The flattened name `/group-action` is the explicit invocation form.
 
 ## Architecture-First Approach
 

package/assets/commands/marketing.md

@@ -30,10 +30,10 @@ 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: /marketing-logo
+                               Triggers skill: /marketing-brand (LOGO mode)
 
 2. Video Content Strategy    — Plan video series, scripts, production, publishing
-                               Triggers skill: /marketing-video
+                               Triggers skill: /marketing-brand (VIDEO mode)
 
 3. Content Writing Strategy  — Blog posts, social media, SEO, newsletter
                                Triggers skill: /marketing-content
@@ -55,19 +55,19 @@ MARKETING PLAN WORKFLOW
 
 Phase 1: Brand Foundation
 │
-├── Execute: /marketing-logo skill
+├── Execute: /marketing-brand (LOGO mode)
 │   └── Output: Brand guidelines, color palette, typography
 │
 ▼
 Phase 2: Content Strategy
 │
-├── Execute: /marketing-content skill
+├── Execute: /marketing-content (STRATEGY mode)
 │   └── Output: Content pillars, blog plan, social media plan, newsletter
 │
 ▼
 Phase 3: Video Content
 │
-├── Execute: /marketing-video skill
+├── Execute: /marketing-brand (VIDEO mode)
 │   └── 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 /marketing-logo into /marketing-content and /marketing-video
+- Pass brand guidelines (colors, voice, tone) from /marketing-brand (LOGO) into /marketing-content and /marketing-brand (VIDEO)
 - Ensure consistency across all outputs
 
 ## Step 4: Create Unified Calendar

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

@@ -1,70 +1,189 @@
 ---
 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".
+description: Documentation workflow with two modes — SINGLE (hand-author a specific doc like README/API.md/ARCHITECTURE.md with full control over voice) and FULL (auto-generate the whole docs/ site — business, architecture, use-cases with sequence diagrams, README index — with a 3-iteration review loop). Use when user says "document", "generate docs", "write docs", "create documentation", "update docs", "sync docs", "sync documentation", "doc sync".
+args: "[MODE]"
 ---
 
-# Sync Docs Workflow
+# Documentation 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.
+One skill, two depths: hand-author a single doc, or batch-generate a whole docs site.
 
-## When to use this skill
+## Pick your mode
 
-- ✅ 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
+| Situation | Mode | Jump to |
+|-----------|------|---------|
+| Authoring / updating a specific doc with opinionated prose | **SINGLE** | [Mode SINGLE](#mode-single) |
+| Re-generating the whole `docs/` site from current code | **FULL** | [Mode FULL](#mode-full) |
+
+- ❌ Just need API reference from OpenAPI → use `/feature-build` (API mode), Phase 4
+- ❌ Understand the codebase, not document it → use `/research-explore` (ONBOARDING)
 
-## Read Architecture First
+## Read Architecture First (both modes)
 
-Detect stack via `~/.claude/architecture/_shared/stack-detection.md`. Read `ddd-architecture.md` + stack doc.
+Detect stack via `~/.claude/architecture/_shared/stack-detection.md`. Read `ddd-architecture.md` + the stack doc. Docs must reflect the architecture, not contradict it.
 
+---
 ---
 
+# Mode SINGLE
+
+Hand-author project docs (README, API.md, ARCHITECTURE.md, CONTRIBUTING.md) with full control over voice and structure.
+
+## When to use
+- ✅ Authoring or updating a specific document
+- ✅ Need opinionated prose, not just structure
+- ✅ Doc is small / scoped — a single file or section
+- ❌ Want automated multi-doc generation → **Mode FULL**
+
 ## Workflow
 
 ```
-SCAN → CONFIRM mode → GENERATE → REVIEW loop (≤3x) → COMPLETE
+SCAN → ANALYZE → GENERATE → REVIEW (loop)
+```
+
+## Phase 1: SCAN
+
+```bash
+tree -L 3 -I 'node_modules|vendor|dist|build'
+find . -maxdepth 3 -name "*.md" -o -name "README*"
+```
+
+Identify what needs work: README, API.md, ARCHITECTURE.md, CONTRIBUTING.md, setup/deployment/runbook, DB schema, config reference.
+
+### Gate
+- [ ] Architecture doc read · Existing docs inventoried · Gaps identified, priorities set
+
+## Phase 2: ANALYZE
+
+For each doc define: **Purpose** (what problem it solves), **Audience** (new contributor / API consumer / on-call), **Source** (which code feeds it).
+
+### Required sections per doc type
+
+**README.md** — one-line description + badges · quick start (≤5 commands) · tech stack (link to architecture) · common commands · project structure (top 2 levels) · links to other docs
+
+**API.md** — auth method + credentials · base URL per env · per endpoint (method, path, request, response, errors, example) · pagination (one block) · error format (one block) · rate limits, versioning
+
+**ARCHITECTURE.md** — one mermaid layer diagram · domain list with 1-line responsibility · cross-domain communication (events) · key tech decisions with rationale · link to `~/.claude/architecture/<stack>.md`
+
+**CONTRIBUTING.md** — local dev setup (≤5 steps) · branch + commit conventions · PR flow + review expectations · test commands + coverage · where to ask for help
+
+### Gate
+- [ ] Each doc has purpose, audience, source · Required sections listed · Aligned with architecture doc
+
+## Phase 3: GENERATE
+
+### Rules
+- **Use real code from the repo** — never invent examples
+- **Link to architecture docs**, don't duplicate them
+- **Code blocks must be runnable** — copy verbatim from working files
+- **Diagrams** — mermaid; one per major concept
+- **Tables** for any list with >3 parallel items
+
+### Minimal skeletons
+
+**README.md** (≤80 lines for most projects)
+```markdown
+# {Project Name}
+> One-line value proposition.
+## Quick Start
+`{install}` then `{run}`
+## Tech Stack
+- {language + version}, {framework}, {DB / queue}  → see [ARCHITECTURE.md](./ARCHITECTURE.md)
+## Commands
+| Command | Purpose |
+## Docs
+- [API.md](./API.md) · [ARCHITECTURE.md](./ARCHITECTURE.md) · [CONTRIBUTING.md](./CONTRIBUTING.md)
 ```
 
-`CONFIRM` asks the user to pick **REFACTOR** (full restructure of `docs/`) or **UPDATE** (keep existing structure, refresh content).
+**API.md** (per-endpoint block)
+```markdown
+### POST /resource
+Create a resource. Idempotent via `Idempotency-Key` header.
+**Auth:** Bearer
+**Request** `{ "field": "value" }`
+**Response 201** `{ "id": "...", "field": "value" }`
+**Errors:** `invalid_field` 400 · `unauthorized` 401 · `already_exists` 409
+```
+
+**ARCHITECTURE.md** opener
+```markdown
+# Architecture
+## Overview
+{1-2 paragraphs: what this system does, key constraints}
+## Layers
+```mermaid
+graph TD
+  App[Application] --> Domain
+  Domain --> Infra[Infrastructure]
+```
+See [DDD rules](~/.claude/architecture/ddd-architecture.md) for layer details.
+## Domains
+| Domain | Responsibility |
+```
+
+**CONTRIBUTING.md** opener
+```markdown
+# Contributing
+## Setup
+`{1-5 commands}`
+## Branch + Commits
+- Branch: `{prefix}/{ticket}-{slug}` · Commit: Conventional Commits
+## PR Flow
+1. Open PR vs `{base}` → 2. CI green → 3. ≥1 review approval → 4. Squash merge
+```
+
+### Gate
+- [ ] All planned docs drafted · Code examples from real files · Diagrams render · Cross-links work
+
+## Phase 4: REVIEW
+
+### Per-doc checklist
+- [ ] Reflects current architecture (not outdated)
+- [ ] All commands run as written (try them)
+- [ ] All file paths exist · All endpoints / functions referenced still exist
+- [ ] Internal + external links resolve · Code blocks compile · Diagrams match code
+
+### Cross-doc consistency
+- [ ] Same terminology everywhere · No duplicated info — link instead
+
+### Loop
+If any issue → return to Phase 3 for that doc, fix, re-review.
 
+---
 ---
 
-## Phase 1: SCAN
+# Mode FULL
+
+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
+- ✅ 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 → **Mode SINGLE**
+- ❌ Understand the codebase, not document it → `/research-explore` (ONBOARDING)
 
-**Goal:** map codebase + existing docs in one pass.
+## Workflow
+
+```
+SCAN → CONFIRM mode → GENERATE → REVIEW loop (≤3x) → COMPLETE
+```
+
+## Phase 1: SCAN
 
 ```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/
+# Entry points 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 "GoRoute" lib/
 ```
 
-### Extract
-- Stack + framework
-- All domains / modules
-- All user-facing flows (endpoints / screens / commands)
-- Existing docs structure (if any)
+**Extract:** stack + framework, all domains/modules, all user-facing flows, existing docs structure.
 
 ### Gate
-- [ ] Stack identified
-- [ ] All domains listed
-- [ ] All use cases listed (count + brief name)
-- [ ] Existing docs inventoried
-
----
+- [ ] Stack identified · All domains listed · All use cases listed (count + name) · Existing docs inventoried
 
 ## Phase 1.5: CONFIRM
 
@@ -72,21 +191,16 @@ 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 |
+| **REFACTOR** | Existing docs messy / partial / wrong structure | Restructure `docs/` from scratch, may delete old files |
+| **UPDATE** | Existing structure fine, content stale | Keep file paths + headings, refresh content + add missing sections |
 
-If the user is unsure: default to **UPDATE** (less destructive).
+If unsure: default to **UPDATE** (less destructive).
 
 ### Gate
-- [ ] User confirmed mode
-- [ ] If REFACTOR: explicit OK to remove old files
-
----
+- [ ] User confirmed mode · If REFACTOR: explicit OK to remove old files
 
 ## Phase 2: GENERATE
 
-**Goal:** produce the target `docs/` tree.
-
 ### Target structure (REFACTOR mode)
 
 ```
@@ -96,150 +210,74 @@ docs/
 ├── 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
-│   └── ...
+│   └── <use-case>.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
+- **`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.
+- **`docs/architecture.md`** — for engineers. Layer diagram (mermaid), domain list, cross-domain communication, tech decisions with rationale, link to `~/.claude/architecture/<stack>.md`.
+- **`docs/use-cases/<name>.md`** — one per flow: trigger (who, what), preconditions, sequence diagram (mermaid `sequenceDiagram`: actor → handler → usecase → infra → response), postconditions / side effects, errors (HTTP code + meaning).
+- **`docs/api.md`** — only if external API exists. Auth, base URL, error format, pagination → then endpoint table. Deep ref → link to OpenAPI spec.
+- **`docs/runbook.md`** — for ops/on-call: local dev (≤5 commands), deploy steps, common failures + recovery, 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)
+Sequence diagrams for use cases · class diagrams only when ER is non-obvious · validate syntax · ≤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)
-
----
+- [ ] All target files written · business.md has zero code/endpoints · Every use case has a sequence diagram · README links to every file · All file paths resolve
 
 ## Phase 3: REVIEW LOOP (≤3 iterations)
 
-**Goal:** auto-check + fix until docs pass.
-
 For each iteration:
+- **3.1 Structure** — all target files exist · README links resolve · no duplicate content
+- **3.2 Business** — plain language (no `API`/`JSON`/`class`/file paths) · covers all top-level journeys
+- **3.3 Architecture** — layer diagram matches code · every domain has a table row
+- **3.4 Use cases** — one file per identified use case · each has trigger/preconditions/sequence/postconditions/errors · diagrams render
+- **3.5 Consistency** — same terminology everywhere · no nonexistent file paths / endpoints referenced
 
-### 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
-
----
+**Loop:** any check fails → fix that section, restart the relevant subset. 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}
-
+### Files: Created {N} · Updated {N} · Deleted {N — REFACTOR only}
+### Coverage: Domains {N/N} · Use cases {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)
+### Next steps: review business.md with product · validate use-cases with leads · set up doc lint in CI
 ```
 
+---
 ---
 
-## 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
+## Hard Rules (both modes)
 
----
+- **Real examples only** — invented code drifts and lies.
+- **Link, don't duplicate** — refer to architecture docs, don't restate rules.
+- **Test every command** before publishing.
+- **Update the doc when you change the code** — stale docs are worse than no docs.
+- **SINGLE:** opinionated prose, full voice control.
+- **FULL:** business.md is for humans (strip jargon, no code/paths); one use case per file; mermaid only if it renders; **REFACTOR mode requires explicit user OK** — never delete docs without confirmation; max 3 review iterations.
 
 ## 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` |
+| Document a newly added API endpoint | `/feature-build` (API mode), Phase 4 |
+| Onboard self / new dev | `/research-explore` (ONBOARDING) |
+| Architecture itself needs review | `/review-code` (ARCHITECT mode) |
+| Write blog / social content | `/marketing-content` |
 
 ## 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 |
+| SCAN | `@clean-architect` | Identify doc needs / domains + patterns |
+| ANALYZE / GENERATE (API) | `@api-designer` | API doc structure + accuracy |
+| ANALYZE / GENERATE (DB) | `@db-designer` | Database doc structure + accuracy |
+| GENERATE | `@docs-writer` | Write all docs |
+| REVIEW | `@code-reviewer` | Verify accuracy vs code |