@timelesscms-com/mcp-server 0.1.0

package/skills/tcms-redesign-branch.md

@@ -0,0 +1,149 @@
+---
+name: tcms-redesign-branch
+description: Use when the user asks to redesign, modernize, or restructure a TimelessCMS site (or a section of it). Forces branch-isolated work so the live site stays untouched until the redesign is approved.
+---
+
+# Redesign a site without breaking the live one
+
+Site-wide changes are exactly where copy-on-write branches earn their
+keep. This skill enforces the discipline: every redesign happens on a
+branch, preview-checked end-to-end, merged only after user sign-off.
+
+## Recipe
+
+### 1. Discover (always)
+
+```
+get_site
+read_site_settings
+read_partial partial_id="header"
+read_partial partial_id="footer"
+list_pages limit=20
+batch_read_pages page_ids=[<top 3-5 pages>]   # see actual conventions
+list_partials                                  # what free blocks exist
+list_collections                               # any data we need to consider
+```
+
+Write the user a short read-back: *"This is a 12-page agency site
+using CSS variables, primary color #1e40af, Inter heading + Source
+Sans body. Existing pages are content-dense, single-column. Main nav
+has 5 items including a CTA. I'd suggest..."*
+
+Confirm direction before touching anything.
+
+### 2. Create a branch
+
+```
+create_branch name="<descriptive name>"
+```
+
+Save the response's `id` — pass it as `version=<id>` on every
+subsequent call. Branches default `robots_blocked: true` so a
+half-finished redesign won't be indexed.
+
+### 3. Iterate on the branch
+
+For each redesign step:
+
+a. Make the change with `?version=<branch-id>`. Updates here don't
+   touch main:
+
+   ```
+   update_partial partial_id="header" patch={...} version="<branch>"
+   update_page page_id=home patch={...} version="<branch>"
+   ```
+
+b. Preview after every meaningful change:
+
+   ```
+   get_preview_link page_id=home version="<branch>"
+   ```
+
+   Send the URL to the user. The preview navigates the whole branch
+   from one mint.
+
+c. Iterate on feedback. Common rounds: headline tightening, color
+   tweaks, swapping hero images.
+
+### 4. Site-wide changes through partials, not pages
+
+If the redesign touches every page (e.g. new global header, new
+footer, new CTA bar) — edit a partial, not 23 pages. Before editing a
+shared block, check the blast radius:
+
+```
+find_pages_using_block partial_id="header" version="<branch>"
+```
+
+This returns every page that would show the change. Communicate that
+to the user before the save.
+
+### 5. Bulk content cleanups via dry-run first
+
+If the redesign requires content rewrites (e.g. "remove every mention
+of the old company name"), use the bulk tool with dry-run:
+
+```
+search_pages contains="OldCo" version="<branch>"
+bulk_replace_text pattern="OldCo" replacement="NewCo" dry_run=true version="<branch>"
+# Show the user the sample_diffs
+bulk_replace_text pattern="OldCo" replacement="NewCo" dry_run=false version="<branch>"
+```
+
+### 6. Approval round
+
+Send the user a final preview link:
+
+```
+get_preview_link page_id=home version="<branch>" ttl_seconds=86400
+```
+
+The 24h TTL gives them time to share with stakeholders. Wait for an
+explicit "looks good, ship it."
+
+### 7. Merge + deploy
+
+```
+merge_branch version_id="<branch>"        # branch's diffs land on main
+trigger_deploy
+get_deploy_status job_id=<id>             # poll until succeeded
+```
+
+Optionally, after a successful deploy:
+
+```
+delete_branch version_id="<branch>"       # tidy up
+```
+
+(You can also leave the branch around as a record of the redesign;
+disk cost is tiny.)
+
+## Pitfalls
+
+- **Forgetting `version=` on writes.** Every call you make on the
+  branch must include `version=<branch-id>`. A missing one writes
+  straight to main — silent and bad.
+- **Skipping discovery.** "Modernize" without first reading the site
+  produces a confidently-out-of-place result. Always sample existing
+  pages.
+- **Editing the in-portal preview URL by mistake.** That's the user's
+  own preview, not yours. `get_preview_link` returns a signed
+  external URL — always use that for sharing.
+- **Auto-merge.** Don't `merge_branch` without explicit user sign-off.
+  Once merged, the only undo is another branch + reverse edits.
+- **Header rewrites that drop the brand block.** Even when the
+  redesign is dramatic, preserve the brand mark + the nav skeleton
+  unless the user said to redo them.
+
+## When to NOT use a branch
+
+Tiny edits — "fix the typo on the About page" — don't need a branch.
+The in-portal chat handles those directly on main. This skill is for
+work where:
+
+- The user might want to walk away mid-redesign and come back later
+- Multiple changes need to ship together
+- The site is high-traffic and "broken for an hour" is unacceptable
+- Stakeholder review across multiple pages is expected
+
+If none of those apply, edit main directly and move on.