# Using Superharness

> Session start guide: explains how to use superharness skills and conventions. Injected by SessionStart hook.

- Skill: `mrlyk/using-superharness` (Agent Skill)
- Install (CLI): `npx skillmds@latest add mrlyk/using-superharness`
- Raw SKILL.md: https://api.skillmd.com/api/skills/mrlyk/using-superharness/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: mrlyk (https://skillmd.com/u/mrlyk)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/mrlyk/using-superharness

---


<SUBAGENT-SKIP>
If you were dispatched as a subagent to execute a specific task, skip this skill.
</SUBAGENT-SKIP>

<EXTREMELY-IMPORTANT>
Invoke every relevant superharness skill before responding or acting.This is not negotiable. This is not optional. You cannot rationalize your way out of this.

User instructions remain the highest priority.
</EXTREMELY-IMPORTANT>

# Using Superharness

## Instruction Priority

Superharness skills override default system prompt behavior, but **user instructions always take precedence**:

1. **User's explicit instructions** (CLAUDE.md, project settings, direct requests) — highest priority
2. **Superharness skills** — override default system behavior where they conflict
3. **Default system prompt** — lowest priority

## Workflow Entry

Use `superharness:go` for end-to-end feature work:

```text
/superharness:go "requirement"
/superharness:go [lite] "requirement"
/superharness:go --task {task-id}
```

New tasks run `superharness:batch-grill-me` followed by `superharness:to-prd`. Existing tasks resume only when the user supplies `--task` followed by the exact task directory name. Without `--task`, the argument is always a new requirement description.

## Available Skills

| Skill | When to Use |
|-------|-------------|
| `superharness:go` | Start or resume the complete workflow |
| `superharness:batch-grill-me` | Resolve the complete current decision frontier in each interview round |
| `superharness:to-prd` | Synthesize a resolved discussion into task artifacts |
| `superharness:writing-plans` | Turn an approved PRD into a detailed implementation plan |
| `superharness:subagent-driven-development` | Execute Full plans through parallel implementers in one shared worktree and one final review |
| `superharness:executing-plans` | Execute an approved plan inline with checkpoints |
| `superharness:test-driven-development` | Apply the active profile's testing discipline |
| `superharness:verification-before-completion` | Require fresh evidence before completion claims |
| `superharness:systematic-debugging` | Investigate root cause before a fix |
| `superharness:using-git-worktrees` | Create isolated development environments |
| `superharness:finishing-a-development-branch` | Verify and complete development work |

## Skill Priority

Use process skills before implementation skills:

- New feature: `go` routes through batch-grill-me and to-prd, then writing-plans or lite implementation.
- Bug or unexpected failure: systematic-debugging, then test-driven-development.
- Approved multi-step specification: writing-plans, then the selected execution skill.

## Iron Laws

1. **Testing:** Tests are mandatory in every profile. Full, Lite, and executing-plans use public-seam red-before-green through `superharness:test-driven-development`.
2. **Verification:** Fresh verification evidence is required before completion claims.
3. **Debugging:** Establish root cause before changing a fix.
4. **Lifecycle state:** All phase/status writes go through the shared transition service. The parent controller uses `superharness task transition {task-id} {phase}` before each semantic handoff. Hooks never change task phase or status.
5. **Language adaptation:** All user-facing output (prompts, confirmations, reports, error messages) must be in the language the user is currently using in the conversation — not the language of the skill template.

## Asking the User

When a decision belongs to the user, prefer the AskUserQuestion tool over typing the question out. Fall back to numbered plain text only when the host does not provide it.

## Project Conventions

Project-specific conventions are defined in `.superharness/spec/`. Each `index.md` contains:
- **Pre-Dev Checklist**: Files to read before coding
- **Quality Check**: Items to verify after coding

## Task Identity and Runtime Context

- task.json is the progress source of truth. It stores `implementation.base_sha`, task seams, behavior slices, status, and full commit SHA; new flows create no implementation protocol files.
- The task-id is the directory name under `.superharness/tasks/` and `--task` is the only user-facing task selector.
- go resumes `.superharness/tasks/{task-id}/task.json` exactly only through `/superharness:go --task {task-id}` and never scans for a likely task. Fixing a bug delivered by a completed task is the one bounded exception: invoke superharness:reopen-task, which owns its task locating rules and the reopen transition loop.
- Parent-thread hooks may match `task.json.worktree_path` to the current cwd for session guidance, workflow-state breadcrumbs, and user-prompt trace events.
- worktree_path locates runtime context; it does not select which task the user intended to resume.
- The Full controller reads `depends_on` to find ready tasks, starts each with `task item start`, dispatches independent implementers in parallel in the single shared task worktree, and records each single-commit result with `task item complete --commit`. After each wave it runs typecheck only; the finishing gate reruns the deduplicated focused/verified set once at the end. It transitions to check once after every item is completed. Implement agents never edit task.json.

Lifecycle phases are `plan | implement | check | complete | qa`. The shared transition service validates every legal edge and derives status/timestamps; the CLI is its public adapter.