@monoes/monomindcli 2.15.3 → 2.15.4

package/org-skills/site-architecture/SKILL.md

@@ -0,0 +1,360 @@
+---
+name: site-architecture
+description: "When the user wants to plan, map, or restructure their website's page hierarchy, navigation, URL structure, or internal linking."
+tags: ["marketing","design","frontend"]
+tools: []
+license: MIT
+source: https://github.com/coreyhaines31/marketingskills
+source_path: "skills/site-architecture"
+source_commit: 5b2c0007766c6a1cf1d53fd8fc73e979e0821022
+---
+# Site Architecture
+
+You are an information architecture expert. Your goal is to help plan website structure — page hierarchy, navigation, URL patterns, and internal linking — so the site is intuitive for users and optimized for search engines.
+
+## Before Planning
+
+**Check for product marketing context first:**
+If `.agents/product-marketing.md` exists (or `.claude/product-marketing.md`, or the legacy `product-marketing-context.md` filename, in older setups), read it before asking questions. Use that context and only ask for information not already covered or specific to this task.
+
+Gather this context (ask if not provided):
+
+### 1. Business Context
+- What does the company do?
+- Who are the primary audiences?
+- What are the top 3 goals for the site? (conversions, SEO traffic, education, support)
+
+### 2. Current State
+- New site or restructuring an existing one?
+- If restructuring: what's broken? (high bounce, poor SEO, users can't find things)
+- Existing URLs that must be preserved (for redirects)?
+
+### 3. Site Type
+- SaaS marketing site
+- Content/blog site
+- E-commerce
+- Documentation
+- Hybrid (SaaS + content)
+- Small business / local
+
+### 4. Content Inventory
+- How many pages exist or are planned?
+- What are the most important pages? (by traffic, conversions, or business value)
+- Any planned sections or expansions?
+
+---
+
+## Site Types and Starting Points
+
+| Site Type | Typical Depth | Key Sections | URL Pattern |
+|-----------|--------------|--------------|-------------|
+| SaaS marketing | 2-3 levels | Home, Features, Pricing, Blog, Docs | `/features/name`, `/blog/slug` |
+| Content/blog | 2-3 levels | Home, Blog, Categories, About | `/blog/slug`, `/category/slug` |
+| E-commerce | 3-4 levels | Home, Categories, Products, Cart | `/category/subcategory/product` |
+| Documentation | 3-4 levels | Home, Guides, API Reference | `/docs/section/page` |
+| Hybrid SaaS+content | 3-4 levels | Home, Product, Blog, Resources, Docs | `/product/feature`, `/blog/slug` |
+| Small business | 1-2 levels | Home, Services, About, Contact | `/services/name` |
+
+**For full page hierarchy templates**: See [references/site-type-templates.md](references/site-type-templates.md)
+
+---
+
+## Page Hierarchy Design
+
+### The 3-Click Rule
+
+Users should reach any important page within 3 clicks from the homepage. This isn't absolute, but if critical pages are buried 4+ levels deep, something is wrong.
+
+### Flat vs Deep
+
+| Approach | Best For | Tradeoff |
+|----------|----------|----------|
+| Flat (2 levels) | Small sites, portfolios | Simple but doesn't scale |
+| Moderate (3 levels) | Most SaaS, content sites | Good balance of depth and findability |
+| Deep (4+ levels) | E-commerce, large docs | Scales but risks burying content |
+
+**Rule of thumb**: Go as flat as possible while keeping navigation clean. If a nav dropdown has 20+ items, add a level of hierarchy.
+
+### Hierarchy Levels
+
+| Level | What It Is | Example |
+|-------|-----------|---------|
+| L0 | Homepage | `/` |
+| L1 | Primary sections | `/features`, `/blog`, `/pricing` |
+| L2 | Section pages | `/features/analytics`, `/blog/seo-guide` |
+| L3+ | Detail pages | `/docs/api/authentication` |
+
+### ASCII Tree Format
+
+Use this format for page hierarchies:
+
+```
+Homepage (/)
+├── Features (/features)
+│   ├── Analytics (/features/analytics)
+│   ├── Automation (/features/automation)
+│   └── Integrations (/features/integrations)
+├── Pricing (/pricing)
+├── Blog (/blog)
+│   ├── [Category: SEO] (/blog/category/seo)
+│   └── [Category: CRO] (/blog/category/cro)
+├── Resources (/resources)
+│   ├── Case Studies (/resources/case-studies)
+│   └── Templates (/resources/templates)
+├── Docs (/docs)
+│   ├── Getting Started (/docs/getting-started)
+│   └── API Reference (/docs/api)
+├── About (/about)
+│   └── Careers (/about/careers)
+└── Contact (/contact)
+```
+
+**When to use ASCII vs Mermaid**:
+- ASCII: quick hierarchy drafts, text-only contexts, simple structures
+- Mermaid: visual presentations, complex relationships, showing nav zones or linking patterns
+
+---
+
+## Navigation Design
+
+### Navigation Types
+
+| Nav Type | Purpose | Placement |
+|----------|---------|-----------|
+| Header nav | Primary navigation, always visible | Top of every page |
+| Dropdown menus | Organize sub-pages under parent | Expands from header items |
+| Footer nav | Secondary links, legal, sitemap | Bottom of every page |
+| Sidebar nav | Section navigation (docs, blog) | Left side within a section |
+| Breadcrumbs | Show current location in hierarchy | Below header, above content |
+| Contextual links | Related content, next steps | Within page content |
+
+### Header Navigation Rules
+
+- **4-7 items max** in the primary nav (more causes decision paralysis)
+- **CTA button** goes rightmost (e.g., "Start Free Trial," "Get Started")
+- **Logo** links to homepage (left side)
+- **Order by priority**: most important/visited pages first
+- If you have a mega menu, limit to 3-4 columns
+
+### Footer Organization
+
+Group footer links into columns:
+- **Product**: Features, Pricing, Integrations, Changelog
+- **Resources**: Blog, Case Studies, Templates, Docs
+- **Company**: About, Careers, Contact, Press
+- **Legal**: Privacy, Terms, Security
+
+### Breadcrumb Format
+
+```
+Home > Features > Analytics
+Home > Blog > SEO Category > Post Title
+```
+
+Breadcrumbs should mirror the URL hierarchy. Every breadcrumb segment should be a clickable link except the current page.
+
+**For detailed navigation patterns**: See [references/navigation-patterns.md](references/navigation-patterns.md)
+
+---
+
+## URL Structure
+
+### Design Principles
+
+1. **Readable by humans** — `/features/analytics` not `/f/a123`
+2. **Hyphens, not underscores** — `/blog/seo-guide` not `/blog/seo_guide`
+3. **Reflect the hierarchy** — URL path should match site structure
+4. **Consistent trailing slash policy** — pick one (with or without) and enforce it
+5. **Lowercase always** — `/About` should redirect to `/about`
+6. **Short but descriptive** — `/blog/how-to-improve-landing-page-conversion-rates` is too long; `/blog/landing-page-conversions` is better
+
+### URL Patterns by Page Type
+
+| Page Type | Pattern | Example |
+|-----------|---------|---------|
+| Homepage | `/` | `example.com` |
+| Feature page | `/features/{name}` | `/features/analytics` |
+| Pricing | `/pricing` | `/pricing` |
+| Blog post | `/blog/{slug}` | `/blog/seo-guide` |
+| Blog category | `/blog/category/{slug}` | `/blog/category/seo` |
+| Case study | `/customers/{slug}` | `/customers/acme-corp` |
+| Documentation | `/docs/{section}/{page}` | `/docs/api/authentication` |
+| Legal | `/{page}` | `/privacy`, `/terms` |
+| Landing page | `/{slug}` or `/lp/{slug}` | `/free-trial`, `/lp/webinar` |
+| Comparison | `/compare/{competitor}` or `/vs/{competitor}` | `/compare/competitor-name` |
+| Integration | `/integrations/{name}` | `/integrations/slack` |
+| Template | `/templates/{slug}` | `/templates/marketing-plan` |
+
+### Common Mistakes
+
+- **Dates in blog URLs** — `/blog/2024/01/15/post-title` adds no value and makes URLs long. Use `/blog/post-title`.
+- **Over-nesting** — `/products/category/subcategory/item/detail` is too deep. Flatten where possible.
+- **Changing URLs without redirects** — Every old URL needs a 301 redirect to its new URL. Without them, you lose backlink equity and create broken pages for anyone with the old URL bookmarked or linked.
+- **IDs in URLs** — `/product/12345` is not human-readable. Use slugs.
+- **Query parameters for content** — `/blog?id=123` should be `/blog/post-title`.
+- **Inconsistent patterns** — Don't mix `/features/analytics` and `/product/automation`. Pick one parent.
+
+### Breadcrumb-URL Alignment
+
+The breadcrumb trail should mirror the URL path:
+
+| URL | Breadcrumb |
+|-----|-----------|
+| `/features/analytics` | Home > Features > Analytics |
+| `/blog/seo-guide` | Home > Blog > SEO Guide |
+| `/docs/api/auth` | Home > Docs > API > Authentication |
+
+---
+
+## Visual Sitemap Output (Mermaid)
+
+Use Mermaid `graph TD` for visual sitemaps. This makes hierarchy relationships clear and can annotate navigation zones.
+
+### Basic Hierarchy
+
+```mermaid
+graph TD
+    HOME[Homepage] --> FEAT[Features]
+    HOME --> PRICE[Pricing]
+    HOME --> BLOG[Blog]
+    HOME --> ABOUT[About]
+
+    FEAT --> F1[Analytics]
+    FEAT --> F2[Automation]
+    FEAT --> F3[Integrations]
+
+    BLOG --> B1[Post 1]
+    BLOG --> B2[Post 2]
+```
+
+### With Navigation Zones
+
+```mermaid
+graph TD
+    subgraph Header Nav
+        HOME[Homepage]
+        FEAT[Features]
+        PRICE[Pricing]
+        BLOG[Blog]
+        CTA[Get Started]
+    end
+
+    subgraph Footer Nav
+        ABOUT[About]
+        CAREERS[Careers]
+        CONTACT[Contact]
+        PRIVACY[Privacy]
+    end
+
+    HOME --> FEAT
+    HOME --> PRICE
+    HOME --> BLOG
+    HOME --> ABOUT
+
+    FEAT --> F1[Analytics]
+    FEAT --> F2[Automation]
+```
+
+**For more Mermaid templates**: See [references/mermaid-templates.md](references/mermaid-templates.md)
+
+---
+
+## Internal Linking Strategy
+
+### Link Types
+
+| Type | Purpose | Example |
+|------|---------|---------|
+| Navigational | Move between sections | Header, footer, sidebar links |
+| Contextual | Related content within text | "Learn more about [analytics](/features/analytics)" |
+| Hub-and-spoke | Connect cluster content to hub | Blog posts linking to pillar page |
+| Cross-section | Connect related pages across sections | Feature page linking to related case study |
+
+### Internal Linking Rules
+
+1. **No orphan pages** — every page must have at least one internal link pointing to it
+2. **Descriptive anchor text** — "our analytics features" not "click here"
+3. **5-10 internal links per 1000 words** of content (approximate guideline)
+4. **Link to important pages more often** — homepage, key feature pages, pricing
+5. **Use breadcrumbs** — free internal links on every page
+6. **Related content sections** — "Related Posts" or "You might also like" at page bottom
+
+### Hub-and-Spoke Model
+
+For content-heavy sites, organize around hub pages:
+
+```
+Hub: /blog/seo-guide (comprehensive overview)
+├── Spoke: /blog/keyword-research (links back to hub)
+├── Spoke: /blog/on-page-seo (links back to hub)
+├── Spoke: /blog/technical-seo (links back to hub)
+└── Spoke: /blog/link-building (links back to hub)
+```
+
+Each spoke links back to the hub. The hub links to all spokes. Spokes link to each other where relevant.
+
+### Link Audit Checklist
+
+- [ ] Every page has at least one inbound internal link
+- [ ] No broken internal links (404s)
+- [ ] Anchor text is descriptive (not "click here" or "read more")
+- [ ] Important pages have the most inbound internal links
+- [ ] Breadcrumbs are implemented on all pages
+- [ ] Related content links exist on blog posts
+- [ ] Cross-section links connect features to case studies, blog to product pages
+
+---
+
+## Output Format
+
+When creating a site architecture plan, provide these deliverables:
+
+### 1. Page Hierarchy (ASCII Tree)
+Full site structure with URLs at each node. Use the ASCII tree format from the Page Hierarchy Design section.
+
+### 2. Visual Sitemap (Mermaid)
+Mermaid diagram showing page relationships and navigation zones. Use `graph TD` with subgraphs for nav zones where helpful.
+
+### 3. URL Map Table
+
+| Page | URL | Parent | Nav Location | Priority |
+|------|-----|--------|-------------|----------|
+| Homepage | `/` | — | Header | High |
+| Features | `/features` | Homepage | Header | High |
+| Analytics | `/features/analytics` | Features | Header dropdown | Medium |
+| Pricing | `/pricing` | Homepage | Header | High |
+| Blog | `/blog` | Homepage | Header | Medium |
+
+### 4. Navigation Spec
+- Header nav items (ordered, with CTA)
+- Footer sections and links
+- Sidebar nav (if applicable)
+- Breadcrumb implementation notes
+
+### 5. Internal Linking Plan
+- Hub pages and their spokes
+- Cross-section link opportunities
+- Orphan page audit (if restructuring)
+- Recommended links per key page
+
+---
+
+## Task-Specific Questions
+
+1. Is this a new site or are you restructuring an existing one?
+2. What type of site is it? (SaaS, content, e-commerce, docs, hybrid, small business)
+3. How many pages exist or are planned?
+4. What are the 5 most important pages on the site?
+5. Are there existing URLs that need to be preserved or redirected?
+6. Who are the primary audiences, and what are they trying to accomplish on the site?
+
+---
+
+## Related Skills
+
+- **content-strategy**: For planning what content to create and topic clusters
+- **programmatic-seo**: For building SEO pages at scale with templates and data
+- **seo-audit**: For technical SEO, on-page optimization, and indexation issues
+- **cro**: For optimizing individual pages for conversion
+- **schema**: For implementing breadcrumb and site navigation structured data
+- **competitors**: For comparison page frameworks and URL patterns

package/org-skills/site-architecture/references/mermaid-templates.md

@@ -0,0 +1,216 @@
+# Mermaid Diagram Templates
+
+Copy-paste-ready Mermaid diagrams for visual sitemaps. Customize node labels and connections for your site.
+
+---
+
+## Basic Hierarchy
+
+Simple top-down page hierarchy.
+
+```mermaid
+graph TD
+    HOME["Homepage<br/>/"] --> FEAT["Features<br/>/features"]
+    HOME --> PRICE["Pricing<br/>/pricing"]
+    HOME --> BLOG["Blog<br/>/blog"]
+    HOME --> ABOUT["About<br/>/about"]
+
+    FEAT --> F1["Analytics<br/>/features/analytics"]
+    FEAT --> F2["Automation<br/>/features/automation"]
+    FEAT --> F3["Integrations<br/>/features/integrations"]
+
+    BLOG --> B1["Post: SEO Guide<br/>/blog/seo-guide"]
+    BLOG --> B2["Post: CRO Tips<br/>/blog/cro-tips"]
+```
+
+---
+
+## Hierarchy with Navigation Zones
+
+Uses subgraphs to show which pages appear in which navigation area.
+
+```mermaid
+graph TD
+    subgraph "Header Nav"
+        HOME["Homepage"]
+        FEAT["Features"]
+        PRICE["Pricing"]
+        BLOG["Blog"]
+        CTA["Get Started ★"]
+    end
+
+    subgraph "Feature Pages"
+        F1["Analytics"]
+        F2["Automation"]
+        F3["Integrations"]
+    end
+
+    subgraph "Footer Nav"
+        ABOUT["About"]
+        CAREERS["Careers"]
+        CONTACT["Contact"]
+        PRIVACY["Privacy"]
+        TERMS["Terms"]
+    end
+
+    HOME --> FEAT
+    HOME --> PRICE
+    HOME --> BLOG
+    FEAT --> F1
+    FEAT --> F2
+    FEAT --> F3
+    HOME --> ABOUT
+    ABOUT --> CAREERS
+    HOME --> CONTACT
+```
+
+---
+
+## Hierarchy with URL Labels
+
+Each node shows the page name and URL path.
+
+```mermaid
+graph TD
+    HOME["Homepage<br/><small>/</small>"] --> PROD["Product<br/><small>/product</small>"]
+    HOME --> PRICE["Pricing<br/><small>/pricing</small>"]
+    HOME --> BLOG["Blog<br/><small>/blog</small>"]
+    HOME --> DOCS["Docs<br/><small>/docs</small>"]
+    HOME --> ABOUT["About<br/><small>/about</small>"]
+
+    PROD --> P1["Analytics<br/><small>/product/analytics</small>"]
+    PROD --> P2["Reports<br/><small>/product/reports</small>"]
+
+    DOCS --> D1["Getting Started<br/><small>/docs/getting-started</small>"]
+    DOCS --> D2["API Reference<br/><small>/docs/api</small>"]
+```
+
+---
+
+## Hub-and-Spoke Content Model
+
+Shows a hub page connected to spoke articles, with spokes linking to each other.
+
+```mermaid
+graph TD
+    HUB["SEO Guide<br/>(Hub Page)"]
+
+    HUB --> S1["Keyword Research"]
+    HUB --> S2["On-Page SEO"]
+    HUB --> S3["Technical SEO"]
+    HUB --> S4["Link Building"]
+
+    S1 -.-> S2
+    S2 -.-> S3
+    S3 -.-> S4
+
+    style HUB fill:#f9f,stroke:#333,stroke-width:2px
+```
+
+Legend:
+- Solid lines = primary hub-spoke links
+- Dashed lines = cross-links between spokes
+
+---
+
+## Internal Linking Flow
+
+Shows how different site sections link to each other.
+
+```mermaid
+graph LR
+    subgraph "Marketing"
+        HOME["Homepage"]
+        FEAT["Features"]
+        PRICE["Pricing"]
+    end
+
+    subgraph "Content"
+        BLOG["Blog"]
+        GUIDE["Guides"]
+        CASE["Case Studies"]
+    end
+
+    subgraph "Product"
+        DOCS["Docs"]
+        API["API Ref"]
+        CHANGE["Changelog"]
+    end
+
+    BLOG --> FEAT
+    BLOG --> CASE
+    CASE --> FEAT
+    CASE --> PRICE
+    FEAT --> DOCS
+    GUIDE --> BLOG
+    GUIDE --> DOCS
+    HOME --> FEAT
+    HOME --> BLOG
+    HOME --> CASE
+```
+
+---
+
+## Before/After Restructuring
+
+Compare current and proposed site structures side by side.
+
+```mermaid
+graph TD
+    subgraph "Before"
+        B_HOME["Homepage"] --> B_P1["Page 1"]
+        B_HOME --> B_P2["Page 2"]
+        B_HOME --> B_P3["Page 3"]
+        B_HOME --> B_P4["Page 4"]
+        B_HOME --> B_P5["Page 5"]
+        B_HOME --> B_P6["Page 6"]
+        B_HOME --> B_P7["Page 7"]
+        B_HOME --> B_P8["Page 8"]
+    end
+
+    subgraph "After"
+        A_HOME["Homepage"] --> A_S1["Features"]
+        A_HOME --> A_S2["Resources"]
+        A_HOME --> A_S3["Company"]
+        A_S1 --> A_P1["Feature A"]
+        A_S1 --> A_P2["Feature B"]
+        A_S2 --> A_P3["Blog"]
+        A_S2 --> A_P4["Guides"]
+        A_S3 --> A_P5["About"]
+        A_S3 --> A_P6["Contact"]
+    end
+```
+
+---
+
+## Color-Coding Conventions
+
+Use styles to highlight page status, priority, or type.
+
+```mermaid
+graph TD
+    HOME["Homepage"] --> FEAT["Features"]
+    HOME --> PRICE["Pricing"]
+    HOME --> BLOG["Blog"]
+    HOME --> NEW["New Section"]
+    HOME --> REMOVE["Deprecated Page"]
+
+    FEAT --> F1["Existing Feature"]
+    FEAT --> F2["New Feature"]
+
+    style HOME fill:#4CAF50,color:#fff
+    style PRICE fill:#4CAF50,color:#fff
+    style FEAT fill:#4CAF50,color:#fff
+    style BLOG fill:#4CAF50,color:#fff
+    style F1 fill:#4CAF50,color:#fff
+    style NEW fill:#2196F3,color:#fff
+    style F2 fill:#2196F3,color:#fff
+    style REMOVE fill:#f44336,color:#fff
+```
+
+Color key:
+- **Green** (`#4CAF50`): Existing pages (no changes)
+- **Blue** (`#2196F3`): New pages to create
+- **Red** (`#f44336`): Pages to remove or redirect
+- **Yellow** (`#FFC107`): Pages to restructure or move
+- **Purple** (`#9C27B0`): High-priority / CTA pages