Skip to content

ericrisco/rsc-harness / skills/harness

harness

Flagged

Use when governing a workspace's control plane, code or not — the `01-TOOLS/` tooling layer, the `02-DOCS/` chaos→knowledge wiki, the root Knowledge map. Audits it, migrates legacy `XX-*` folders, scaffolds provider tooling, sweeps the inbox, eats a file the person hands over ("cómete este fichero", "guárdalo en la documentación": moved into 02-DOCS/raw/ and documented), writes root CLAUDE.md/AGENTS.md. NOT the bootstrap front door (that is `init`, which hands off here).

references/tools-readme-template.md

View on GitHub
# 01-TOOLS

> Template generated by `harness` on {{TODAY}}.

Operational arsenal for **{{PROJECT_NAME}}**. Each subdirectory is a
**tool** that combines (a) credentials co-located in its own `.env` and
(b) the scripts/CLIs that consume them. Everything needed to operate an
external service lives under `01-TOOLS/<SERVICE>/`.

> **Operations, not runtime.** The scripts here are the ones an operator
> runs from the terminal. The SDK that the app consumes in production
> **does not live here** — it lives in the corresponding product repo.

## Conventions

### Names and structure

- **Tool folder**: UPPERCASE with `_` separators (no accents or spaces) —
  `STRIPE`, `MAILJET`, `GOOGLE_OAUTH`.
- **One folder = one external provider.**
- **Scripts**: snake_case, verb in infinitive + object —
  `test_connection.sh`, `listar_precios.sh`, `crear_servidor.py`.
- **`.env` variables**: UPPERCASE with `_`, provider prefix —
  `STRIPE_SECRET_KEY`, `MAILJET_API_KEY`. Exception: variables the
  provider SDK requires literally (Fastlane `MATCH_*`) — document in
  `CREDENTIALS.md`.

### Files per tool

| File | Required | Purpose |
|------|----------|---------|
| `.env` | yes (if secrets) | Real credentials — `chmod 600`, gitignored. |
| `.env.example` | yes | Public template with variable names and empty values. |
| `.gitignore` | yes | At least `.env` and `keys/`. |
| `README.md` | yes | What it does and how to run the scripts. |
| `CREDENTIALS.md` | yes | Detail of each variable, provider dashboard, rotation. |
| `test_connection.{py,sh}` | yes unless `manual_only` | Smoke-test, no parameters. |

### Script conventions

- **Python 3.11+** by default. Bash only for short wrappers around `curl`
  or `psql`. Node only when the SDK requires it.
- **`argparse` is mandatory** in Python scripts — `--help` must explain
  what the script does and all parameters.
- **`.env` resolution**: `$SCRIPT_DIR/.env` (bash) or
  `Path(__file__).parent / ".env"` (Python).
- **Output**: readable on stdout, errors with exit code `≠ 0` on stderr.
- **Destructive actions** (delete, cancel, charge, bulk send) require an
  explicit `--confirmar` flag. Without it, dry-run with preview.

## Catalog

{{TOOLS_CATALOG}}

## Common flows

```bash
# Smoke-test for each tool
{{SMOKE_TEST_EXAMPLES}}
```

## Adding a new tool

1. `cp -r 01-TOOLS/_TEMPLATE 01-TOOLS/<NAME>`
2. Fill in `.env.example` with the real variable names from the provider
   (prefix `<TOOL>_<VAR>` unless documented otherwise).
3. Create real `.env` with values from the dashboard. `chmod 600 .env`.
4. **Implement `test_connection.{py,sh}` first** — a dumb smoke-test.
5. Add other scripts on demand — only the ones you need now.
6. Update the tool's `README.md`.
7. Add a row to the catalog in this README.

## Philosophy

- **No speculative tools.** A tool gets added when the integration is in
  runtime or when there's a recurring manual operation that hurts.
- **Smoke-test first.** Before any other script, prove that credentials
  work.
- **Co-location.** Credentials and scripts live together. Rotating a key
  = opening one folder.

## See also

- `02-DOCS/` — project LLM wiki. When a tool gains recurring operations
  worth documenting beyond the local README, the `harness`
  protocol ingests the README + `CREDENTIALS.md` into
  `02-DOCS/raw/operations/` and compiles them in
  `02-DOCS/wiki/operations/`.
rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first.Stars: 194kUpdated Claude CodeCodexVerifiedInstall