playbooks

home / skills / plurigrid / asi / graft-prefer

graft-prefer skill

/skills/graft-prefer

This skill enforces graft as the preferred build system for Basin agents, replacing cargo for builds, tests, and quality checks to ensure consistency.

npx playbooks add skill plurigrid/asi --skill graft-prefer

Review the files below or copy the command above to add this skill to your agents.

Files (1)
SKILL.md
3.4 KB
---
name: graft-prefer
description: >
  Enforces graft as the preferred build system for all agents working in the Basin
  codebase. Activates whenever any agent attempts cargo build/test/check/clippy/fmt
  or needs to compile, test, lint, benchmark, or manage build artifacts.
---

# Graft-Prefer Rules for Basin Agents

## MANDATORY: Use graft instead of cargo for all build operations

This workspace uses **graft** as its build system. Graft wraps cargo with CAS-backed
caching, distributed compilation, unified linting, resilient builds, and multi-language
support. All agents MUST use graft instead of raw cargo.

## Command Mapping (ALWAYS apply these substitutions)

| Instead of | Use |
|------------|-----|
| `cargo build` | `graft build` |
| `cargo check` | `graft check` |
| `cargo test` | `graft test` |
| `cargo clippy` | `graft clippy` |
| `cargo fmt` | `graft fmt` |
| `cargo run` | `graft run` |
| `cargo bench` | `graft run -p basin-observatory-app --release -- sweep` |
| `cargo doc` | `graft doc` |
| `cargo clean` | `graft clean` |
| `cargo fix` | `graft fix` (NEVER use `cargo fix` -- it corrupts files) |
| `cargo nextest` | `graft test` (nextest is used under the hood) |

## Package targeting

- Single crate: `graft build -p <crate-name>`
- Workspace: `graft build --workspace`
- Release: `graft build --release`
- With features: `graft build -p <crate> -F <feature>`

## Quick build aliases (via .cargo/config.toml)

- `cargo kernel` -- core storage only (~30s)
- `cargo dev` -- common products (~60s)
- `cargo fast` -- excludes SQL stack
- `cargo test-unit` -- unit tests only (fastest feedback)
- `cargo test-fast` -- unit + critical integration
- `cargo test-sigil` -- sigil tests with 1s timeout

## Unified quality checking

- `graft lint` -- all checks (clippy + fmt + quality + deps)
- `graft quality run` -- full quality audit (UP01-UP12)
- `graft fix` -- auto-fix with safe transforms

## Diagnostics and debugging

- `graft health --verbose` -- check graft configuration
- `graft cache validate` -- detect stale artifacts
- `graft cache stats` -- cache hit/miss statistics
- `graft memory` -- check memory pressure / recommended jobs
- `graft stream --errors` -- live error feed from builds

## Environment

- Target directory: /Volumes/Basin/cargo-target (external SSD, do NOT change)
- Cache directory: /Volumes/Basin/graft-cache
- GRAFT_ENABLE=1 is set in .cargo/config.toml
- Tests use nextest (configured in .config/nextest.toml)

## Subagent delegation

When a task requires specialized build operations, delegate to these droids:
- **graft-builder**: Standard build/test/check operations
- **graft-analyzer**: Code analysis and intelligence
- **graft-ci**: CI pipeline execution
- **graft-benchmarker**: Performance benchmarking
- **graft-debugger**: Build failure diagnosis
- **graft-sigil-compiler**: Multi-language compilation
- **graft-cluster**: Distributed build management
- **graft-image-builder**: Image building
- **graft-refactorer**: Code refactoring with safety
- **graft-cacher**: Cache management
- **graft-watcher**: Live development feedback

## Anti-patterns (NEVER do these)

1. NEVER run `cargo fix` directly (corrupts files, hardcoded off via GRAFT_NO_WORKSPACE_FIX)
2. NEVER change target-dir from /Volumes/Basin/cargo-target
3. NEVER run `podman/docker run -p` with host port mappings for competitors
4. NEVER use `cargo build` when `graft build` is available
5. NEVER skip durability labels on benchmark results

Overview

This skill enforces graft as the preferred build system for all agents working in the Basin codebase. It automatically substitutes cargo commands with graft equivalents and ensures builds, tests, linting, and artifact management follow the workspace policies and environment constraints. The skill triggers whenever an agent attempts to compile, test, lint, benchmark, or otherwise manage build artifacts.

How this skill works

The skill inspects requested build-related commands and rewrites them to graft equivalents according to a fixed command mapping. It validates target and cache directories, enforces environment variables, and routes specialized requests to dedicated graft subagents. For complex or failing operations it suggests diagnostics and cache checks before delegating to an appropriate subagent.

When to use it

  • When any agent attempts cargo build/test/check/clippy/fmt/run/bench/doc/clean/fix/nextest.
  • When compiling, testing, linting, benchmarking, or producing build artifacts in the Basin workspace.
  • When a build should use CAS-backed caching, distributed compilation, or unified linting.
  • When you need consistent environment settings for target-dir and graft cache.
  • When delegating specialized build tasks (benchmarking, debugging, CI, caching).

Best practices

  • Always substitute cargo commands with the graft mapping (e.g., use graft build instead of cargo build).
  • Keep target-dir set to /Volumes/Basin/cargo-target and cache in /Volumes/Basin/graft-cache.
  • Use graft lint or graft quality run for unified quality checks instead of running tools individually.
  • Avoid running cargo fix; use graft fix which applies safe transforms when needed.
  • Delegate heavy or specialized tasks to the appropriate graft subagent (graft-builder, graft-ci, graft-cacher, etc.).

Example use cases

  • Converting a CI pipeline that used cargo test to use graft test for CAS caching and nextest integration.
  • Running a fast developer build using graft build -p <crate-name> or graft build --workspace for full rebuilds.
  • Performing a quality audit with graft quality run to run clippy, fmt, and additional checks in one command.
  • Diagnosing flaky build failures by running graft health --verbose and graft cache validate, then delegating to graft-debugger.
  • Running benchmarks via the mapped command graft run -p basin-observatory-app --release -- sweep.

FAQ

What if an agent issues cargo fix?

Never run cargo fix directly; rewrite to graft fix. The workspace disallows cargo fix because it can corrupt files.

Can I change the target directory?

No. The target directory must remain /Volumes/Basin/cargo-target to ensure build durability and shared artifacts.