Introduction

Welcome to the CrossR Skills documentation.

This book is the canonical reference for the skills and harness process developed in this repository.

What is CrossR Skills?

A curated collection of high-quality Agent Skills together with a complete, self-hosting harness for building reliable, long-running AI coding agents.

The skills follow the official agentskills.io specification. The process layer is defined in the HARNESS-SPEC.md at the root of this repository.

Why This Exists

Most AI coding agents are stateless. Every new session starts from scratch.

The harness turns those stateless sessions into something far more powerful:

• Persistent state across context resets
• Incremental, verifiable progress
• Extremely reviewable changes (target: < 10 minutes deep review per PR)
• Self-verifying handovers
• Mechanical quality enforcement via the GAN cycle (Generator + Adversary)

This combination has been battle-tested on real production work, including a 16-PR security-critical authorization chain.

Core Philosophy

The same standards we apply to production Rust code apply here:

• Functional purity and stratified design
• Zero technical debt
• Handover-clean artifacts
• HTML as a first-class human interface for plans, reviews, and specifications

How to Use This Book

• Start with the Harness Overview to understand the full system.
• The Skills section documents the reusable capabilities.
• Follow Getting Started to bootstrap the harness in your own projects.

This book is itself dogfooded — it was built using the same harness and process it describes.

The Harness — Overview

A harness is the persistent scaffolding that turns stateless AI coding sessions into reliable, multi-session agents that ship production-grade code with clean handovers.

The Problem

Without a harness, agents suffer from:

• Context loss on every new session
• Inconsistent processes across projects
• Unreviewable giant diffs
• No mechanical self-critique
• Poor handoff quality between sessions or between human + agent

The Solution

The CrossR harness provides a minimal but powerful set of artifacts, rituals, and processes that any project can adopt.

It is deliberately lightweight so that it can be bootstrapped into a new project in minutes, yet powerful enough to support 16+ PR security and infrastructure efforts.

Key Components

Design Goals

• Incremental — Never more than one small task per session
• Reviewable — Every PR should be deeply reviewable in under 10 minutes
• Self-verifying — Agents must run the full verification loop before declaring work complete
• Self-hosting — The harness is used to maintain the harness itself (as you are seeing right now)
• Rust-dogfooded — Where tools are needed, we prefer high-quality Rust tools (Zola, mdBook, etc.)

The rest of this section expands on each of these ideas.

HTML as the Primary Human Interface

For any artifact whose primary audience is a human — specifications, architecture reviews, PR summaries, progress reports, dashboards, deployment guides, etc. — generate a self-contained HTML file as the main deliverable.

Rationale

Markdown is excellent for agents and git.

HTML (especially beautiful, self-contained Tailwind-via-CDN single-file HTML) is dramatically more effective for human comprehension and engagement.

This is sometimes called "the unreasonable effectiveness of HTML."

Modern models are exceptionally good at producing high-quality, scannable, visually rich single-file HTML with almost no extra prompting.

Guidelines

• Output a single .html file.
• Use Tailwind CSS via CDN (https://cdn.tailwindcss.com).
• Make the document scannable with clear sections, cards, status pills, and good typography.
• You may still produce a Markdown version for git history and agent handoff.
• Treat the HTML as the primary human-facing artifact.

Examples in This Repository

• docs/plans/harness-improvement-plan.html
• The marketing site you are currently reading (site/) was built with the same philosophy.

This rule is now a first-class part of the harness and is enforced in AGENTS.md.

PETC Loop & Stacked PR Discipline

The PETC Loop

Every session follows the same rhythm:

1. Plan — Read progress.md + features.json + recent git history. Propose the next small task. End the plan with a bulleted list of unresolved questions.
2. Execute — Implement using the appropriate skills and strict adherence to project conventions.
3. Test — Run the full matrix (just check, just test, just clippy, just fmt). Run rust-code-reviewer, rust-code-tester, and rust-architect (or the full GAN team) on the changes.
4. Commit — Small, focused diff + update features.json + append to progress.md + clean git state.

Stacked PR Discipline

Large features are never delivered in one giant PR.

Instead, they are decomposed into a chain of small, stacked PRs (typically 8–16 for major efforts).

Each PR in the stack must answer:

• What this PR contains
• What the next PR will contain
• How this was verified
• Risk level and why review is easy

Historical Example

The 16-PR CD-1873 authz chain in ferro-wave is the canonical real-world demonstration of this pattern at scale. A high-risk security subproject was delivered as a series of tiny, extremely reviewable changes with full traceability and multi-tier verification harnesses.

Why This Matters

• A human reviewer (or agent) can give deep, high-quality feedback in < 10 minutes.
• Progress is visible and motivating.
• Rollback or partial delivery is safe.
• The final merged result is still a clean, coherent feature.

This discipline is non-negotiable for work tracked in this harness.

Skills Overview

All reusable capabilities in this repository live under .agents/skills/ and strictly follow the official agentskills.io specification.

The agentskills.io Format

Each skill is a single file:

.agents/skills/<name>/SKILL.md

With YAML frontmatter containing at minimum:

---
name: skill-name
description: |
  One or two sentence description of what this skill does and when to use it.
---

The rest of the file contains the detailed guidance, rules, anti-patterns, and activation statements.

All skills in this repository follow the canonical portable structure and the Harness Relationship (Stratified) principle. Generic/core skills are fully harness-agnostic. Harness-layer and domain skills include a ## Harness Context (Stratified Disclosure) block that clearly separates portable principles from project-specific realizations (supplied by the invoking harness at activation). The skill-evaluator skill and its permanent GAN personas are the authority for maintaining this standard.

Claude Compatibility

Claude compatibility is generated, never hand-maintained.

The canonical source is always the .agents/skills/ directory.

When a project wants Claude support, it runs the generator (provided by scripts/harness-bootstrap or scripts/sync-skills) to produce the optional .claude/skills/ and .claude/commands/ copies.

This keeps cross-project reuse clean and ensures the official specification is the single source of truth.

Current Skills

See the individual skill documents linked from the table of contents for details. The skills are grouped into:

• Core writing skills (code-writer, rust-code-writer)
• Quality & architecture skills (rust-code-reviewer, rust-code-tester, rust-architect)
• Domain skills (rust-axum-backend, rust-frontend, rust-tui, rust-errors)
• Meta skills (agent-harness, avril, axel, skill-evaluator)
• Planning / execution orchestration (avril planning GAN → axel execution loop)

All skills are designed to be combined. The typical activation pattern is:

Using code-writer + rust-code-writer + rust-axum-backend + agent-harness for this task.

Bootstrapping a New Project

The fastest way to adopt the full harness in a new project is the harness-bootstrap script.

One Command

git clone https://github.com/scull7/crossr-skills.git
./crossr-skills/scripts/harness-bootstrap /path/to/your-new-project

What Gets Created

The bootstrap emits a complete, ready-to-commit harness:

• AGENTS.md (with Plan Mode and skill references)
• features.json + features.schema.json
• progress.md
• justfile with the standard targets
• .agents/skills/ (copy of the skills you choose)
• .gitignore entries for generated artifacts
• CLAUDE.md (optional, generated)
• A harness-validate target

After running the script, you should immediately commit the new harness as the foundation of the project.

After Bootstrapping

Run:

just harness-validate
just init

just harness-validate now also runs just docs-verify to ensure documentation stays aligned with the current canonical standards.

Then begin your first piece of work using the PETC loop.

The bootstrap script itself is part of the harness and is maintained using the same process it enables.