convert-repo-format

name	convert-repo-format
description	Convert repo format.
user-invocable	true
allowed-tools	["Bash","Read","Edit","Write","WebFetch"]

convert-repo-format — convert a repo between SERG project formats

Take a repo that's built as one project format and rebuild it as another. The lab has four formats, each with a template repo that is the source of truth for what that format's files, config, and CI look like:

Format	Template	project.type	Output dir	Is it an R package?
R package	rpt	— (no _quarto.yml)	altdoc site	Yes — full package
Quarto website	qwt	website	_site	Yes — light package
Quarto book	qbt	book	docs	No (Type: Book)
Quarto manuscript	qmt	manuscript	_manuscript	Yes — light package

The core move is diff against the target template, not rewrite from scratch. The four formats share most of their scaffolding (R tooling, spell/lint/link checks, the @claude and Copilot workflows). A conversion keeps that shared layer, swaps the project config, and changes only the format-specific files.

When this fires

• "convert this repo to a Quarto book / website / manuscript / R package"
• "crf", "convert repo format", "change this repo's project type"
• "turn this book into a website", "make this manuscript an R package", "reformat this as a Quarto manuscript"
• Any request to re-home an existing repo's content into a different one of the four template formats above.

This is normal new work, so run it issue-first (the st skill): file a tracking issue, branch, convert, open a PR, and ARDI to clean.

Step 1 — detect the current format

Read the signature files. Each format has a tell:

ls -A
cat DESCRIPTION 2>/dev/null
sed -n '1,15p' _quarto.yml 2>/dev/null

• R package (rpt): no _quarto.yml; DESCRIPTION with Package: + Imports:/Suggests: + Roxygen:; R/, man/, NAMESPACE, tests/testthat/, vignettes/, altdoc/, NEWS.md, renv.lock.
• Quarto website (qwt): _quarto.yml with a profile: key plus a _quarto-website.yml whose project.type is website (output-dir: _site); index.qmd, chapters/, reveal.js files (styles-reveal.scss, qwt-reveal-toggle.html, revealjs-*.lua).
• Quarto book (qbt): _quarto.yml with project.type: book (output-dir: docs, pre-render: pre-render.py) and a book: block listing chapters; macros-header.html; DESCRIPTION is Type: Book (not a package).
• Quarto manuscript (qmt): _quarto.yml with project.type: manuscript (output-dir: _manuscript) and a manuscript: block with article: + notebooks:; notebooks/, _repo-links.lua.

State the detected source and the requested target before touching anything.

Step 2 — get the target template as your reference

Work against the actual target template, not memory — the templates evolve.

• If the template repo is checked out locally (a sibling dir), read it there.
• Otherwise fetch files over raw HTTP (works for public repos even when gh/MCP aren't scoped to them): https://raw.githubusercontent.com/<owner>/<template>/main/<path> (UCD-SERG for rpt/qwt/qbt, the repository owner for qmt).
• List the target's .github/workflows/ and top-level files first so you know the full target shape.

Step 3 — keep the shared scaffolding

These exist in every format; carry them across unchanged (update repo-specific strings only):

• R/build tooling: .Rbuildignore, .Rprofile, .lintr.R, .gitattributes, .gitignore, project.Rproj, inst/WORDLIST.
• Repo docs: LICENSE, README.Rmd → README.md, CONTRIBUTING.md / CODE_OF_CONDUCT.md.
• Shared CI: .github/workflows/ claude.yml, claude-code-review.yml, copilot-setup-steps.yml, check-spelling.yaml. Most workflows are thin callers of the reusable workflows in Morrison-Lab/gha pinned @v1, so "convert the CI" mostly means copying the target template's .github/workflows/ and updating repo-specific inputs — not rewriting logic.

Step 4 — swap the project config and format-specific files

Add what the target needs; remove what only the source needed. Per target:

→ R package (rpt)

• Remove all Quarto config and content: _quarto.yml, _quarto-website.yml, _extensions/, *.qmd site pages, styles*.css/scss, reveal.js filters, macros/ (submodule), lychee.toml, pre-render.py, _repo-links.lua, references.qmd.
• Add the full package skeleton: R/, man/ (generated), NAMESPACE (generated), tests/testthat/, vignettes/, data-raw/, altdoc/, NEWS.md, renv.lock, codecov.yml, CHECKLIST.md.
• DESCRIPTION becomes a full package: real Imports:/Suggests:, Roxygen: list(markdown = TRUE), Config/testthat/edition: 3, VignetteBuilder, Config/Needs/website: quarto. Move any prose content into a vignette (.qmd/.Rmd) under vignettes/.
• Docs are built by altdoc (not pkgdown, no _quarto.yml) via the docs.yaml workflow. The rpt template uses the lab's own altdoc config — a committed altdoc/ directory (altdoc/quarto_website.yml, _extensions/, scripts/) plus a custom d-morrison/altdoc fork — so render_docs() generates .qmd files into altdoc/man/ from man/*.Rd at build time (not committed), then renders the site. Mirror rpt's altdoc/ directory rather than configuring altdoc from scratch.

→ Quarto website (qwt)

• Add _quarto.yml (with profile: default: website) and _quarto-website.yml (project.type: website, output-dir: _site, the website: nav/footer block). Add index.qmd, chapters/, references.qmd + references.bib, styles.css, _extensions/, the reveal.js slide files (styles-reveal.scss, qwt-reveal-toggle.html, revealjs-*.lua), lychee.toml, and the macros/ submodule.
• Keep a light R package (R/<pkg>-package.R, man/, NAMESPACE, DESCRIPTION with Depends/Suggests) — it's what gives the repo R tooling.

→ Quarto book (qbt)

• Add _quarto.yml with project.type: book (output-dir: docs, pre-render: pre-render.py) and a book: block listing chapters: (index.qmd, chapter*.qmd, references.qmd) and appendices:. Add pre-render.py, macros-header.html, styles.css, references.bib, lychee.toml, and the macros/ submodule.
• DESCRIPTION is minimal (Type: Book, no Imports/Roxygen). The book template is not a full R package — there's no R//NAMESPACE, and qbt carries no top-level CLAUDE.md. Drop the package skeleton if converting from a package or light-package format.

→ Quarto manuscript (qmt)

• Add _quarto.yml with project.type: manuscript (output-dir: _manuscript) and a manuscript: block (article: index.qmd, notebooks:). Add index.qmd (the article), notebooks/ (supplementary notebooks), _repo-links.lua, _extensions/, styles.css, references.bib, lychee.toml.
• Keep a light R package skeleton, like the website format.

Step 5 — convert the CI workflows

Replace the source's .github/workflows/ with the target's set (keeping the shared four from Step 3). The format-specific workflows:

• R package (rpt): R-CMD-check.yaml, R-check-docs.yml, check-readme.yaml, docs.yaml (altdoc deploy), lint-changed-files.yaml, news.yaml, pr-commands.yaml, test-coverage.yaml, version-check.yaml.
• Quarto, all three: check-bibliography-dois.yml, check-links.yml, check-non-standard-chars.{yaml,yml} (the extension varies by template — .yaml in qwt/qmt, .yml in qbt), lint-project.yaml, preview.yml, publish.yml (deploy to gh-pages), summary.yml. The website and manuscript formats also carry lint-changed-files.yaml; the book format does not.

Update each workflow's repo-specific inputs (output dir, deploy paths, package name). Don't hand-rewrite reusable-workflow logic — adjust the caller's with:.

Step 6 — verify against the target's checks

Run the checks the target format uses, not the source's:

• R package: devtools::document() (sync man//NAMESPACE), lintr::lint_package(), devtools::test(), devtools::check(); add a NEWS.md bullet.
• Quarto (any): quarto render (output lands in the format's output dir), lintr::lint_dir(), spell check against inst/WORDLIST, link check (lychee.toml), and scan the rendered HTML for broken cross-refs/citations (the crr / check-rendered-refs skill).

Then open the PR (Closes #<issue>), explain the source → target conversion in the body, and ARDI it to clean.

Notes

• Scope the diff honestly. A conversion is large; keep it to the format change. Don't smuggle in content rewrites beyond what the new format requires (e.g. splitting prose into chapters for a book, or into a vignette for a package).
• macros/ is a git submodule in qwt/qbt — add it with git submodule add <url> macros, don't copy the files. Read <url> from the target template's .gitmodules (currently https://github.com/d-morrison/macros).
• Generated files (man/, NAMESPACE, README.md, _site//docs// _manuscript/) are build outputs — regenerate them, don't hand-edit.
• When the conversion is between the two light-package Quarto formats (website ↔ manuscript), the R skeleton and most workflows are already right — the change is mostly the _quarto.yml project block and the content entrypoints.