Super harness

Super Harness

Overview

Use this skill to install a reusable project harness: persistent project rules, role cards, task package templates, validation logs, and high-density learning comments.

Core principle: files carry the workflow, real subagent dispatch runs the work, and final verification stays with the main agent.

This skill builds the project stage. It is not the same as executing one already-written implementation plan.

When To Use

Use this skill when the user wants to:

• start a new coding project with project-level multi-agent rules;
• convert an existing project from ad hoc single-agent work to a structured harness;
• create AGENTS.md, docs/harness/, and agents/ role cards;
• standardize task packages, validation reports, and main-agent logs;
• require learning-oriented comments for study, onboarding, demos, or thesis defense;
• make a workflow reusable across future repositories.

Do not use it for a one-file quick fix, a pure concept explanation, or a task where subagents cannot own disjoint file scopes.

Target Project Files

Create or update this scaffold, adjusted to the project:

AGENTS.md
docs/harness/
  README.md
  orchestrator.md
  task-package-template.md
  requirements.md
  plan.md
  main-log.md
  lessons-learned.md
  test-reports/
agents/
  product-design-agent.md
  frontend-agent.md
  backend-data-agent.md
  ai-rag-agent.md
  test-review-agent.md
  integration-agent.md

The role list is a starting pool, not a law. Add narrower roles only when they clarify ownership, such as deployment, performance, security, documentation, data migration, or mobile.

Harness Modes

Light Harness
  = main agent handles goal -> minimal change -> verification -> summary.

Live Multi-Agent Harness
  = main agent launches real subagents through the current agent runtime.

Role cards are not running agents. They are prompt assets. A task is only Live Multi-Agent when the main agent actually dispatches a subagent through the current environment, such as spawn_agent in Codex when that tool is available.

Installation Flow

understand project type and tech stack
  ↓
define Light vs Live trigger rules
  ↓
write project AGENTS.md harness section
  ↓
create docs/harness orchestration files
  ↓
create role cards from the project architecture
  ↓
create task package template
  ↓
define validation matrix and protected files
  ↓
read back the docs and run formatting checks

Required Harness Rules

Every harness should state:

• development and cross-file implementation default to Live Multi-Agent unless the user explicitly asks for single-agent mode;
• concept explanations, small read-only checks, and unclear requirements can use Light Harness;
• real multi-agent work requires the available subagent runtime;
• the main agent splits work by disjoint writable file scopes;
• implementation and test/review are separate roles;
• subagents must not roll back or overwrite other workers' changes;
• sensitive files such as .env, private data, generated caches, and user-owned source material are forbidden unless explicitly authorized.

Code-Writing Subagent Block

Copy this block into every subagent task that will add or modify code, including temporary workers:

You are not alone in this repository. Do not revert other workers' changes. Only edit files explicitly allowed by this task package.

Learning-oriented comments are required:
1. Import comments: explain which third-party library, framework API, or local module each important import comes from; what it does; and why this file needs it.
2. File-level navigation: complex files should start with the entry point, core processing flow, output location, and downstream consumers.
3. Declaration comments: functions, components, classes, schemas, tools, helpers, and key variables should explain responsibility, input, output, and data flow.
4. Data examples: adapters, formatters, parsers, API/RAG/schema mappings should include a short "input roughly looks like this -> output roughly looks like this" example.
5. Call-site comments: when calling project-specific helpers, tools, retrievers, server actions, or adapters, explain which step that call performs in the current flow.
6. Boundary notes: authentication, privacy, database writes, model output parsing, RAG instruction isolation, async state, animation fallbacks, and destructive operations should explain why they are handled that way.
7. Restraint: do not mechanically explain obvious syntax such as const, return, simple assignments, or ordinary JSX.

If the project owner prefers Chinese learning comments, the same block can be rendered in Chinese:

你不是独自在代码库里工作；不要回滚别人改动；只修改任务包授权范围内的文件。

学习型详尽注释是硬要求：
1. import 注释：说明依赖来自哪个第三方库、框架 API 或本地模块；它主要做什么；当前业务为什么需要它。
2. 文件顶部导航：复杂文件顶部写入口、核心处理、输出位置和下游。
3. 声明处注释：函数、组件、类、schema、tool、helper、关键变量都说明职责、输入、输出和数据流。
4. 数据例子：adapter、formatter、parser、API/RAG/schema 映射写“输入大概长这样 -> 输出大概长这样”的短例子。
5. 调用处注释：调用项目自写 helper/tool/retriever/server action/adapter 时，在调用附近解释它当前承担哪一步。
6. 边界/坑点：鉴权、隐私、数据库写入、模型输出、RAG 指令隔离、异步状态、动画降级等位置说明为什么这样处理。
7. 克制原则：不机械解释 const、return、简单赋值、普通 JSX 或显而易见语法。

This block must be included even if a role card already has similar rules. A spawned subagent has isolated context and may not see the parent conversation.

Task Package Template

Each subagent prompt should include:

• role and agent type;
• goal and short background;
• why this task is split out;
• allowed files and forbidden files;
• required reading;
• exact implementation requirements;
• learning-comment requirements;
• validation commands;
• final response format.

Keep the prompt self-contained. If a worker cannot complete the task using only the package plus allowed files, the package is too vague.

Review Flow

main agent plans
  ↓
implementation subagent works inside its file scope
  ↓
test-review-agent performs independent read-only review
  ↓
main agent integrates, runs final validation, commits if requested

If review finds missing import comments, missing call-site explanations, no input/output examples, or comments that merely translate syntax, send the work back before finalizing.

Relationship To Execution Skills

super-harness builds the project stage:

AGENTS.md / docs/harness / agents / task package / comment standard

Subagent execution skills or native agent tools execute a specific implementation plan:

dispatch implementer / reviewer / quality reviewer for current tasks

Use this skill when creating or upgrading the project workflow. Use an execution-focused skill or native subagent runtime when a plan is already ready and the current session should implement it.

Common Mistakes

• Treating agents/*.md as if they are already running. They are not; use the actual subagent runtime.
• Saying "add detailed comments" without copying the concrete checklist.
• Letting two subagents edit the same files in parallel.
• Letting implementation agents self-certify final quality without independent review.
• Keeping duplicate runtime code just because old tests reference it. If code is truly redundant, remove or rewrite those tests too.
• Copying project-specific names, paths, commands, or business assumptions into a generic skill.

Porting Checklist

When applying this skill to a new project:

1. Replace product name, tech stack, paths, commands, and protected data rules.
2. Keep the generic harness structure and code-writing subagent block.
3. Add only role cards that match the project architecture.
4. Define which tasks are Light Harness versus Live Multi-Agent.
5. Run one small real task to verify that file scope, comments, and review gates work.