# Mostly Good Workbench
**Reproducible environments, useful guardrails, and real evidence for coding agents.**
Workbench helps an agent find its way around a project, make a change, run it, inspect what happened, and verify the result. Use established tools for established problems. Add custom code where it provides evidence those tools do not already supply.
This first release is a **platform-neutral skill pack with adoption references**. Apple development is the first documented application, drawn from building Scribbledeck. Use the pieces that help your existing project; a new application architecture is not required.
## Start here
| Skill | Use it for |
| --- | --- |
| [workbench-adopt](skills/workbench-adopt/SKILL.md) | Improve an existing project's development environment and prove the smallest useful improvement. |
| [workbench-develop](skills/workbench-develop/SKILL.md) | Complete a product change through the project's real build, interaction, and verification loop. |
| [workbench-visual-evidence](skills/workbench-visual-evidence/SKILL.md) | Share deterministic states across previews and tests; inspect real interaction captures and visual differences. |
Each skill is self-contained. You can install one without installing the others. The [adoption guide](docs/ADOPTION.md) explains gradual adoption and what belongs inside each project.
Example requests:
```text
Use $workbench-adopt to improve this project's development feedback. Preserve its working architecture, start with the largest gap, and exercise the resulting workflow.
```
```text
Use $workbench-develop to fix this selection bug. Verify actual selection and movement, then show the relevant evidence.
```
```text
Use $workbench-visual-evidence to inspect this UI change using our existing fixtures and snapshot system.
```
## Install in Codex
Clone a reviewed release to a location you intend to keep:
```sh
git clone --branch v0.1.0 --depth 1 https://github.com/joshdholtz/mostly-good-workbench.git
cd mostly-good-workbench
```
Codex discovers user skills under `~/.agents/skills` and supports symlinked skill folders. Install the ones you want:
```sh
mkdir -p "$HOME/.agents/skills"
ln -s "$PWD/skills/workbench-adopt" "$HOME/.agents/skills/workbench-adopt"
ln -s "$PWD/skills/workbench-develop" "$HOME/.agents/skills/workbench-develop"
ln -s "$PWD/skills/workbench-visual-evidence" "$HOME/.agents/skills/workbench-visual-evidence"
```
Run each `ln` only when its destination does not already exist. Review existing installations instead of overwriting them. The checkout must remain available while those links are installed. Start a new agent conversation if discovery has not refreshed.
For a team, copy the selected **whole skill folder**, including its references, into that project's `.agents/skills/`, and record the Workbench release or commit you adopted. Choose user-wide or project-local installation for a given skill to avoid duplicate discovery. Upgrade deliberately through a reviewed version change.
These are ordinary `SKILL.md` folders using the [Agent Skills format](https://agentskills.io/specification). Other agents can use them through their supported skill installation mechanism; their tool access and discovery behavior need separate verification. See [Codex's skill documentation](https://learn.chatgpt.com/docs/build-skills) for current discovery behavior.
## What is included today
- Three reusable workflows and their focused references.
- An optional Apple profile: Tuist, fastlane, native Xcode/runtime tools, SwiftFormat, SwiftLint, and ordinary CI.
- Environment, credential, fixture, and evidence conventions that can be adopted separately.
- Concrete failure patterns learned from actual development.
- A curated list of upstream Apple skills, with the exact revisions used in Scribbledeck.
Using these instructions does not require Node, fastlane, Xcode, or any particular application framework. The agent uses the tools appropriate to the destination project. Node is used only to lint this repository's Markdown.
## What comes next
The next proof is adoption in a second existing app. That experience should determine which evidence utilities deserve extraction and which defaults are worth a project template. There is currently **no generated app template, fastlane plugin, shared evidence executable, or automatic installer** in this repository.
Scribbledeck established the source workflows on Apple tooling. The generalized skills have initial packaging and documentation checks; they have not yet completed an independent second-project adoption. See [provenance and verification scope](docs/PROVENANCE.md).
## Contribute
To run the same Markdown check as CI, install [mise](https://mise.jdx.dev/getting-started.html), then:
```sh
mise trust
mise install
mise exec -- npm ci
mise exec -- npm run lint
```
Tool versions live in `mise.toml`; npm dependencies are pinned in `package-lock.json`. The check needs no Apple account, simulator, or release credentials. Workbench defines no custom environment variables or secrets. GitHub Actions uses its standard read-only repository token.
For a behavior change to a skill, try a representative task and report what the agent actually did. Markdown lint cannot prove an instruction produces good engineering. Preserve a skill's self-contained references when changing its layout.
## License and acknowledgments
Workbench's original content is [MIT licensed](LICENSE). Referenced third-party projects keep their own licenses and authorship; their skill contents are not bundled here. See [the curated sources](docs/PROVENANCE.md#curated-apple-skills).