Workspace

Workspace

Manage the writing/docs side of a research project: scaffold infrastructure as needed, show the rendered work, save iterations. For managing the research task graph itself (planning, executing typed tasks), use asta-flows.

assets/DEVELOPER.md is a developer-facing template scaffolded into the user's project root (where it becomes DEVELOPER.md for humans and agents working with the project). This SKILL.md is the agent-specific procedure.

Show the user the rendered work

Give the user a web URL for the rendered work. Two URL sources, pick based on your context:

• Local agent (host, local dev container, or Codespace — the user can reach your port): run make preview in the background. Pass the URL Quarto prints (localhost on host/dev container; Codespaces-forwarded URL in a Codespace).
• Headless agent (no user-reachable port): push the branch (see Save), then make deployed-url to fetch the deployed URL from GitHub Pages CI.

Save

git add + git commit -m "<concise message>". Don't git push without explicit user approval.

For a headless agent (the user only sees results via deployed URL):

• Bootstrap main if the repo is empty. On a repo with no commits, the first branch pushed becomes the default — leaving no main to open a PR against. Check with git ls-remote --heads origin main. If absent: prefer having the repo created with an initial commit (GitHub's "Add a README file", or gh repo create <owner>/<name> --add-readme) so main exists up front; otherwise seed it with git push -u origin HEAD:main (legitimate — no prior state to review).
• First save: git push -u origin HEAD:<feature-branch>, gh pr create --fill, then make deployed-url and report the URL.
• Subsequent saves: git push, make deployed-url.
• After explicit merge approval: gh pr merge, make deployed-url.

Don't merge a PR without explicit user approval.

Scaffold components as needed

Add components only when needed; don't proactively offer.

Before writing any file in the steps below, check whether the target path already exists. If it does, ask the user before overwriting, or merge the asset's contents into the existing file.

Quarto build tool

1. Copy assets/_quarto.yml to project root; fill {{TITLE}} and {{REPO_URL}} (use the canonical GitHub URL, e.g. https://github.com/{owner}/{repo}).
2. Create index.qmd with title: frontmatter.
3. Create empty references.bib.
4. Copy assets/evidence.yml to the project root (the keyed quote store — keep it even while empty). The Makefile fetches the hover-snippet extension from this repository before each render, so do not vendor assets/_extensions/evidence/ into the project. See Back claims with supporting evidence below.
5. Append any lines from assets/gitignore missing from the project's .gitignore (create it if absent; don't overwrite existing entries).
6. Copy assets/Makefile to project root, and assets/quarto-check.sh to scripts/quarto-check.sh (vendored verbatim — the Makefile's check target runs it; to update it later, re-copy rather than hand-edit). CI warns when the vendored copy drifts from the canonical one; on that warning, re-copy the asset.
7. Copy assets/README.md; fill {{TITLE}} and {{DESCRIPTION}} from the user.
8. Copy assets/DEVELOPER.md to project root. User owns it — only update later with explicit user permission.

Back claims with supporting evidence

The scaffold fetches a small Quarto extension (_extensions/evidence/) from asta-plugins before each render rather than vendoring a copy that can drift. By default it resolves the latest published asta-plugins version tag, so projects pick up new releases automatically — the same way other asta-plugins consumers upgrade — instead of tracking the mutable main branch. Override with ASTA_PLUGINS_REF=v0.103.0 to pin a specific release, or ASTA_PLUGINS_REF=main to track the in-flight branch. The extension lets a factual claim in the prose carry the evidence backing it: the claim gets a subtle dotted underline, and hovering (or keyboard-focusing) it reveals a verbatim quote plus a body-style citation. It renders with pure CSS — so it also survives onto the what-changed diff page, where a reviewer can check each claim's backing without leaving the diff.

When you write a claim you looked up, back it: add a keyed entry to evidence.yml with the verbatim quote, its cite key (add the paper to references.bib), an optional native citeproc locator (p. 4, sec. 3.2, abstract, …), and optional provenance:. Provenance must record only observed facts: use the exact CLI subcommand (for example, asta papers snippet-search) as method, use the canonical asta:// URI returned for an indexed Asta document as url, and omit unknown fields rather than inferring a skill or producer name. Then mark the claim in the .qmd:

NatureBench has [90 tasks]{.ev key="naturebench-count"}.

Only ever put a verbatim quotation in quote: — there is no paraphrase mode; state your own wording in the prose. Full field reference and design notes are in _extensions/evidence/README.md.

GitHub Pages deploy

1. Copy assets/docs.yml to .github/workflows/docs.yml. It's a thin stub — the build/deploy/preview machinery lives in this repo's reusable workflow (.github/workflows/workspace-quarto-site.yml), so scaffolded projects pick up fixes without re-copying. Project-specific quality gates go in the project's make check target, which the reusable workflow calls. When updating an existing project to this stub, update its Makefile in the same change (the workflow requires a check target), and update any branch-protection required-check names to the new contexts (the build check is now reported as docs / build) — via gh api if the token has admin on the repo, otherwise ask the user.
2. Configure Pages to serve from gh-pages:

   gh api repos/{owner}/{repo}/pages -X POST --input - <<'EOF'
   {"build_type":"legacy","source":{"branch":"gh-pages","path":"/"}}
   EOF
   

On every PR the workflow publishes a full rendered preview under <pages>/pr-preview/pr-<N>/ and a what-changed.html beside it. The latter highlights rendered additions and removals against the deployed base site and collapses unchanged sections. The single preview comment links to the changes first and the full preview second, so reviewers can inspect the affected content directly.

Dev container

Copy assets/devcontainer.json to .devcontainer/devcontainer.json, then pick the flow that matches the user's intent:

• Local container (working on their machine without installs): run make dev to open VS Code attached to the local container.
• Codespaces (browser-based access from anywhere): commit, push to a GitHub remote (creating one if needed), then gh codespace create and give the user the URL.