Package {harness}

Title:	Curated Agentic Harnesses for R Professional Roles
Version:	0.1.0
Description:	A bootstrapper that launches a command-line coding agent of the user's choice in a terminal tab pre-configured for a professional R role. Each role is described by a curated harness: a subset of community skills, a system prompt, a folder layout, and quality gates. The package does not run an agent loop and does not call a language model; it discovers the chosen coder binary, generates its configuration, links the curated skills, and opens the terminal. Code written by the agent is run manually by the user, by design, so that every generated script passes through a human audit gate before execution.
License:	MIT + file LICENSE
Encoding:	UTF-8
RoxygenNote:	8.0.0
Depends:	R (≥ 4.2)
Imports:	jsonlite, yaml
Suggests:	rstudioapi, testthat (≥ 3.0.0), withr
Config/testthat/edition:	3
URL:	https://github.com/pcbrom/harness
BugReports:	https://github.com/pcbrom/harness/issues
NeedsCompilation:	no
Packaged:	2026-06-04 16:59:39 UTC; pcbrom
Author:	Pedro Carvalho Brom [aut, cre, cph]
Maintainer:	Pedro Carvalho Brom <pcbrom@gmail.com>
Repository:	CRAN
Date/Publication:	2026-06-09 15:40:13 UTC

harness: curated agentic harnesses for R professional roles

Description

The package launches a command-line coding agent of the user's choice in a terminal tab pre-configured for a professional R role. A role is described by a curated harness stored in ⁠inst/harness/<role>.yml⁠: a subset of community skills, a system prompt, a folder layout, and quality gates.

Details

The package does not run an agent loop and does not call a language model. It discovers the chosen coder binary, generates its configuration, links the curated skills, and opens the terminal. Code written by the agent is run manually by the user, so that every generated script passes through a human audit gate before execution.

Entry points: status(), setup(), available_roles(), role() and launch().

Author(s)

Maintainer: Pedro Carvalho Brom pcbrom@gmail.com (ORCID) [copyright holder]

Authors:

• Pedro Carvalho Brom pcbrom@gmail.com (ORCID) [copyright holder]

See Also

Useful links:

• https://github.com/pcbrom/harness

• Report bugs at https://github.com/pcbrom/harness/issues

List the registered adapters

Description

List the registered adapters

Usage

adapters()

Value

A character vector of adapter names.

Examples

adapters()

List the available curated roles

Description

Returns the names of the harnesses bundled with the package, taken from the ⁠inst/harness/<role>.yml⁠ catalogue.

Usage

available_roles()

Value

A character vector of role names, sorted alphabetically.

Examples

available_roles()

Clone the community-skills catalogue

Description

Clones the external community-skills repository into a discoverable location so that community_skills_path() finds it on the next call. The catalogue is an external dependency and is never bundled with this package; this helper only automates the checkout. It is never run when the package is loaded.

Usage

clone_community_skills(
  dest = file.path(path.expand("~"), ".community-skills"),
  url = community_skills_url(),
  shallow = TRUE,
  quiet = FALSE
)

Arguments

Value

The absolute path to the checkout, invisibly.

Examples

## Not run: 
clone_community_skills()

## End(Not run)

Locate the community-skills checkout

Description

Searches, in order, the COMMUNITY_SKILLS_PATH environment variable, ⁠~/.community-skills/⁠ and ⁠~/projects/community-skills/⁠. The community skills catalogue is an external dependency and is never bundled with this package.

Usage

community_skills_path()

Value

The absolute path to the checkout, or NA_character_ when none is found.

Examples

community_skills_path()

Launch a curated coding session

Description

Loads the harness for role, configures the chosen adapter for the project, scaffolds the role's folder layout, and opens the coder in a terminal tab. Inside RStudio the terminal is created with rstudioapi::terminalCreate; otherwise an external terminal emulator is used, and when none is available the launch command is reported for the user to run.

Usage

launch(
  adapter = "claude",
  role,
  project_dir = getwd(),
  scaffold = TRUE,
  dry_run = FALSE,
  config_home = NULL,
  skills_path = NULL,
  binary = NULL
)

Arguments

Details

The package never runs an agent loop and never executes code produced by the agent. Generated scripts are run manually by the user.

Value

An object of class harness_launch, invisibly.

Examples

## Not run: 
launch("claude", role = "data-scientist")

## End(Not run)

Load a curated role

Description

Reads the harness for name from the catalogue, validates it against the schema, and returns it as a harness_role object.

Usage

role(name)

Arguments

Value

An object of class harness_role.

Examples

ds <- role("data-scientist")
ds$skills

Show the full configuration of a role

Description

Prints the complete harness configuration for a role: description, execution policy, skills, folder layout, quality gates, package dependencies and the full system prompt, followed by the path to the source YAML. Unlike the compact print method, this includes the system prompt in full.

Usage

role_config(name)

Arguments

Value

The harness_role object, invisibly.

Examples

role_config("data-scientist")

Tabulate the available roles

Description

Returns a data frame with one row per curated role, summarising its version, the number of skills it declares, and the first line of its description.

Usage

role_list()

Value

A data frame with columns role, version, skills and description.

Examples

role_list()

List the skills of one or more roles

Description

Returns a long data frame with one row per role-skill pair. With available = TRUE, each skill is checked against the community-skills checkout and an available column reports whether its SKILL.md is present.

Usage

role_skills(role_name = NULL, available = FALSE)

Arguments

Value

A data frame with columns role and skill, plus available when requested.

Examples

role_skills("data-scientist")
utils::head(role_skills())

Scaffold the folder layout of a role

Description

Creates the directories declared in the harness layout under project_dir. Existing directories are left untouched. The function never writes code, runs a script, or removes anything; it only ensures the audit folders exist.

Usage

scaffold_layout(role_name, project_dir = getwd(), create = FALSE)

Arguments

Value

A data frame with one row per layout entry, invisibly.

Examples

tmp <- tempfile("proj")
dir.create(tmp)
scaffold_layout("data-scientist", tmp, create = TRUE)

Validate the environment for a role

Description

Checks that a community-skills checkout exists, reports which curated skills for the role are present in that checkout, and which declared CRAN packages are installed. Optionally scaffolds the role's folder layout. The function never installs packages and never runs generated code.

Usage

setup(role_name = NULL, project_dir = getwd(), scaffold = FALSE)

Arguments

Value

An object of class harness_setup, invisibly.

Examples

## Not run: 
setup("data-scientist")

## End(Not run)

Report the harness environment status

Description

Summarises the discoverable environment: the community-skills checkout, the bundled roles, and the registered adapters with their binary availability. The function performs no side effects.

Usage

status()

Value

An object of class harness_status, invisibly printed by default.

Examples

status()

Update the community-skills catalogue

Description

Runs a fast-forward ⁠git pull⁠ on an existing community-skills checkout so that the curated skills track the upstream repository. The update is user-initiated. It can also run when the package is attached, but only when the user opts in through the harness.auto_update option or the HARNESS_AUTO_UPDATE environment variable; the default does nothing on load.

Usage

update_community_skills(dest = community_skills_path(), quiet = FALSE)

Arguments

Value

The absolute path to the checkout, invisibly.

Examples

## Not run: 
update_community_skills()

## End(Not run)