// Use at the start of every session and before completing any coding task.
Use before starting any coding task when Superpowers is not present.
Use after completing a round of code generation.
Use before starting any coding task when Superpowers is not present.
Use after completing a round of code generation.
Use at the start of every session and before completing any coding task.
Use before declaring any coding task complete, done, or finished.
| name | using-harnessed |
| description | Use at the start of every session and before completing any coding task. |
Harnessed ensures that code you write is independently reviewed before being declared complete. Self-critique is useful for improving a draft, but it is not independent verification and it cannot replace the final QA and gate. Harnessed lowers self-evaluation bias and improves issue-finding rate; it does not claim perfect objectivity.
Detect Superpowers: Check if the session context contains references to Superpowers skills (e.g., superpowers: prefix in loaded skills), or if a superpowers plugin directory exists in the project. If Superpowers was loaded by a SessionStart hook, its instructions will already be in your context — look for mentions of "Superpowers" in your system instructions.
harnessed:contract-writing; use Superpowers specs as acceptance criteria.harnessed:contract-writing before any coding task.Both modes USE harnessed:independent-qa after each coding round and harnessed:verification-gate before completion.
Briefly inform the user at these moments:
Keep status messages to one sentence. Do not explain the Harnessed pipeline unless the user asks.
| Task Size | Indicators | Pipeline |
|---|---|---|
| Micro | Single-line fix, typo, config value change, comment edit | Skip contract + QA. Use verification-gate only. |
| Standard | New function, bug fix, UI component, API endpoint, single-function refactor | Full pipeline: contract → code → QA → gate |
| Large | New feature, multi-file refactor (>3 files or public interface changes), architecture change | Full pipeline with explicit user review at contract stage |
When in doubt, treat as Standard. It is always safer to over-verify than under-verify.
Flag the task as high-risk if ANY of the following are true:
High-risk tasks use the expanded QA path in harnessed:independent-qa: corroborating review, disagreement handling, and explicit human-review carry-through where needed.
Before creating any .harnessed/ artifacts, check if .harnessed/ is already in the project's .gitignore. Only append if absent:
grep -qxF '.harnessed/' .gitignore 2>/dev/null || echo '.harnessed/' >> .gitignore
This is automatic, silent, and idempotent. Do not ask the user for permission. QA artifacts should never be committed.
Before writing any artifacts, check for an active session lock:
.harnessed/.lock exists, read its content (PID and timestamp)kill -0 {PID} 2>/dev/null.harnessed/.lock with the current shell's PID ($$) and ISO 8601 timestampThe lock file is advisory, not mandatory — it warns but does not block. Clean up the lock file when the task completes.
When a new task begins, archive stale artifacts to prevent them from misleading the QA evaluator:
.harnessed/contract.md exists from a previous task, rename it to .harnessed/archive/{timestamp}-contract.md.harnessed/qa-report.md exists, rename it to .harnessed/archive/{timestamp}-qa-report.md.harnessed/qa-report-secondary.md exists, rename it to .harnessed/archive/{timestamp}-qa-report-secondary.md.harnessed/qa-report-security.md exists, rename it to .harnessed/archive/{timestamp}-qa-report-security.md.harnessed/qa-report-tiebreak.md exists, rename it to .harnessed/archive/{timestamp}-qa-report-tiebreak.md.harnessed/qa-state.md exists, rename it to .harnessed/archive/{timestamp}-qa-state.md.harnessed/verification-summary.md exists, rename it to .harnessed/archive/{timestamp}-verification-summary.mdUse the format YYYYMMDD-HHMMSS for {timestamp}. Create .harnessed/archive/ if it does not exist. Do NOT archive .harnessed/failure-patterns.md.
| Your Thought | Why It's Wrong | What To Do |
|---|---|---|
| "This change is too small for QA" | 3-line diffs cause production outages. Size does not predict risk. | If it touches logic, run QA. |
| "The user didn't ask for QA" | The user installed Harnessed. That IS asking for QA. | Run QA. |
| "I'll QA everything at the end" | Compound bugs are exponentially harder to find and fix than incremental ones. | QA after each coding round. |
| "The evaluator was too strict last time" | Strictness is the point. If criteria are wrong, fix the criteria. Never weaken the evaluator. | Adjust the contract, not the evaluator's standards. |
| "My self-review already covered this" | Self-review is useful preparation, but it is still biased because you know what you intended to build. | Keep the self-review notes for yourself, then run independent QA anyway. |
| "This project has no tests, so QA can't verify much" | Tier 1 code review still catches logic errors, regressions, and missing handling. Independence is the value, not just execution. | Run QA at the strongest tier available. |
User override: HARD-GATEs prevent agent rationalization, not explicit user instructions. If the user directly requests "skip QA for this task" or "treat this as micro", respect it.
Standalone Mode:
Task → contract-writing → CODE → independent-qa → (fix loop) → verification-gate → Done
Complementary Mode (with Superpowers):
Task → [Superpowers planning] → CODE → independent-qa → (fix loop) → verification-gate → Done
High-Risk Mode:
Task → contract/spec → CODE → independent-qa (corroborating reviewers + possible tie-break) → verification-gate → Done
Micro Task:
Task → CODE → verification-gate → Done