--- name: site-architecture description: Plan or restructure a website's page hierarchy, navigation, URL structure, and internal linking. Use when the user says "sitemap", "site structure", "information architecture", "navigation design", "URL structure", "what pages do I need", or "how should I organize my site". Not for XML sitemaps or indexation problems: use seo-audit. Not for structured data markup: use schema. Not for deciding what content to create: use content-strategy. license: MIT metadata: author: TechTide AI (Alex Cinovoj) provenance: rewritten from patterns in an open SaaS marketing skills pack (MIT) category: SEO & AEO --- # Site Architecture Good architecture means a user reaches any important page in three clicks and a crawler infers the hierarchy from the URL alone. Plan structure before content, and never change a URL without a redirect. ## Intake If a product marketing context file exists (`.agents/product-marketing.md` or `.claude/product-marketing.md`), read it first. Then confirm: what the company does and for whom, top 3 site goals, new build or restructure (and what is broken), site type, page count now and planned, the 5 most important pages, and any URLs that must survive with redirects. ## Workflow 1. **Pick the depth for the site type.** Small business: 1-2 levels. SaaS and content sites: 2-3. E-commerce and docs: 3-4. Go as flat as possible while nav stays clean; a dropdown with 20+ items needs a new level. Read references/structure-templates.md for full page hierarchies, URL patterns, and Mermaid sitemap templates per site type. 2. **Draft the hierarchy.** L0 homepage, L1 primary sections (`/features`, `/pricing`, `/blog`), L2 section pages, L3+ detail pages. Output as an ASCII tree with the URL at every node. 3. **Design navigation.** Header: 4-7 items max, ordered by priority, CTA rightmost, logo links home. Footer: grouped columns (Product, Resources, Company, Legal). Sidebar for docs and blog sections. Breadcrumbs mirror the URL path, every segment clickable except the current page. 4. **Set URL rules.** Human-readable, lowercase, hyphens, hierarchy reflected in the path, one trailing-slash policy, short but descriptive slugs, no dates, no IDs, no query params for content. One parent per concept: never mix `/features/x` and `/product/y`. 5. **Plan internal linking.** No orphans (every page gets at least one inbound link), descriptive anchors, most links to the most important pages, hub-and-spoke for content clusters (hub links all spokes, spokes link back and to each other), related-content blocks on posts, cross-section links from features to case studies. 6. **Deliver the plan.** Five artifacts: ASCII tree, Mermaid visual sitemap, URL map table (page, URL, parent, nav location, priority), navigation spec, internal linking plan with redirect map if restructuring. ## Verification For a restructure, build the redirect map first, then check it: every old URL appears exactly once on the left side and maps to a live new URL. Spot-check with `curl -sI https:///` after launch. Expect a single 301 hop to the new URL and a 200 at the target. A chain or a 404 means the map is incomplete: fix before calling the migration done. For a new plan, walk the tree: every important page reachable in 3 clicks from home, every page has a parent, every URL matches its breadcrumb trail. Any mismatch means the hierarchy and URL design diverged: reconcile them. ## Good vs Bad **Bad:** Blog URLs move from `/blog/2023/05/post-title` to `/blog/post-title` with no redirect map, because "Google will figure it out". Every backlink now hits a 404 and rankings drop for weeks. **Good:** Same migration ships with a one-to-one 301 map, the top 20 linked URLs verified by hand, and the XML sitemap regenerated on launch day. ## Footguns - **URL changes without 301s.** Lost link equity and broken bookmarks. Fix: one mapped redirect per renamed URL, no exceptions. - **Hierarchy that exists only in nav.** URL says `/analytics`, breadcrumb says Home > Features > Analytics. Crawlers and users get conflicting maps. Fix: URL path, breadcrumb, and tree must agree. - **Over-nesting.** `/products/category/subcategory/item/detail` buries pages and bloats URLs. Fix: flatten until each level earns its place. - **Orphan pages after restructure.** Pages kept but unlinked from anywhere. Fix: run the orphan audit in the linking plan; every kept page gets an inbound link. ## Completion Checklist - [ ] Hierarchy drafted with URLs at every node, important pages within 3 clicks - [ ] Header capped at 7 items with CTA, footer grouped, breadcrumbs mirror URLs - [ ] URL rules consistent: lowercase, hyphens, one parent per concept, no dates or IDs - [ ] Internal linking plan covers hubs, spokes, and orphan elimination - [ ] Restructures ship a verified one-to-one 301 map Any box unchecked: not done. Fix or say so.