# Workspace

> Show the user the agent's work on a research project and save iterations on the user's behalf. Scaffold rendering and deploy infrastructure (Quarto today, GitHub Pages, dev container), show the rendered output, save iterations. Doesn't handle research execution (use `asta-flows`).

- Skill: `allenai/workspace` (Agent Skill, multi-file: 15 files)
- Install (CLI): `npx skillmds@latest add allenai/workspace`
- Raw SKILL.md: https://api.skillmd.com/api/skills/allenai/workspace/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- Author: allenai (https://skillmd.com/u/allenai)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/allenai/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.

| Component | When to add |
|---|---|
| **Quarto build tool** | Always — it's the project structure. |
| **GitHub Pages deploy** | When you have no user-reachable port, or the user asks for a deployed URL. |
| **Dev container** | User wants to avoid installing host dependencies, or wants browser-only access from another machine. See subsection for the two flows. |

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`:

```markdown
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`:
   ```bash
   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.