using-superharness

name	using-superharness
description	Session start guide: explains how to use superharness skills and conventions. Injected by SessionStart hook.

If you were dispatched as a subagent to execute a specific task, skip this skill. 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.

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:

/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.