code-hardening

Code Hardening

This skill takes a repo with an audit branch and works through all findings — scoring them, planning parallel work streams, setting up isolated git worktrees, and producing summary-response.md and review-response.md as the deliverable.

Run phases in order. Pause for explicit user confirmation at the end of Phase 2 before creating any worktrees or files.

---

Phase 1: Initial Review

Checkout the audit branch. Search the entire repo for audit files — do not assume a fixed location. Audit files may contain findings in different formats — structured tables (typical for security and performance findings) and prose sections with headings (typical for architecture, scalability, and spec deviation reviews). Include findings from both formats.

Pass 1 — Lightweight exploration (all issues in parallel): For each finding, spawn a subagent that reads the finding detail and does a quick exploration of the code files it references. Each subagent returns:

• Whether the issue is confirmed in the code
• An effort estimate: Low, Medium, or High
• A brief initial take on the fix approach

Do not overwrite existing severity ratings. Add Effort as a new attribute alongside each finding.

Pass 2 — Deep dive (High effort issues only): For every issue that came back High effort in Pass 1, spawn a second subagent that goes deeper into the code. This subagent identifies the full scope of the change, dependencies, risks, and produces a detailed recommendation concrete enough for the user to make an informed decision during the interactive review.

Write all results to hardening-initial-review.md on the audit branch — one row per issue with: ID, title, severity, effort estimate, confirmation status, and recommended fix approach (detailed for High effort, concise for Low and Medium). Commit this file before moving to Phase 2.

Present a summary to the user showing total issues found, breakdown by effort level, and any issues that could not be confirmed in the code. Ask the user to confirm before proceeding to Phase 2.

---

Phase 2: Plan and Review

2a — Group

Read references/planning-prompt.md and apply it to the full scored issue list. Propose work streams to the user — include for each: a descriptive name, the issues it covers (ID and title), the files it primarily touches, and estimated total effort. Ask for confirmation or adjustment on the number of work streams before proceeding to the review.

2b — Interactive Review

Walk through each work stream with the user. Within each work stream, group issues thematically — surface clusters of related issues together rather than one by one. Present each cluster using the recommendations from hardening-initial-review.md.

The depth of presentation scales with the effort level of issues in the cluster. Low and Medium effort clusters can be presented concisely for quick approval. Clusters containing High effort issues get fuller treatment — surface the detailed analysis, dependencies, and risks so the user can make an informed decision. High effort issues are still grouped thematically with related issues, not forced into separate discussions.

For each cluster present:

• The issue IDs and titles
• The recommended fix approach (with depth appropriate to effort level)
• Whether any fix risks a behavioral change (flag these explicitly for user sign-off)

Wait for the user's response on each cluster before moving to the next. The user may approve, skip individual issues, or change the approach for any item.

2c — Commit the Plan

Once all issues across all work streams have been reviewed and decided, write hardening-plan.md to the repo. This file records every issue, the agreed fix approach or skip reason, and which work stream it belongs to. Commit this file to the audit branch. This is the source of truth for Phase 3.

Ask the user to confirm the plan before proceeding to Phase 3.

---

Phase 3: Setup

Create worktrees. For each approved work stream, create a git worktree as a sibling directory outside the repo, named after the work stream. For example:

git worktree add ../hardening-auth-secrets -b hardening/auth-secrets
git worktree add ../hardening-database-performance -b hardening/database-performance

Use the actual work stream names from Phase 2a — not generic numbers.

Create pre-populated response doc shells. In each worktree, create two files:

summary-response.md — pre-populate every issue row across all audit categories with status ⬜ Pending and an empty Notes field. Use the format in references/response-format.md. Every issue appears in this file from the start so nothing can be missed.

review-response.md — pre-populate every section from the original review file with an empty **Response:** block below each finding. Every section is present from the start.

Each session will update only the rows assigned to it — changing ⬜ Pending to ✅ Fixed or ⏭ Skip and filling in the Notes. Because different sessions update different rows, git merges these files cleanly.

Generate session prompts. For each work stream, fill in references/work-stream-prompt.md using the decisions recorded in hardening-plan.md and the fix approaches from hardening-initial-review.md. Write the filled prompt as HARDENING-TASK.md in that worktree's root directory. This is the file each session will read on startup.

Discover test command. Search the repo root for package.json, Makefile, pyproject.toml, or equivalent to identify the test command. Tell the user what was found (or that no test command was found). If a test command exists, ask: "Should each work stream run tests after completing all its fixes?" Store the answer — test command or "no tests" — in each HARDENING-TASK.md.

Launch sessions. Follow the instructions in references/launch-sessions.md exactly.

---

Phase 4: Hand Off

Tell the user:

Each session has its work stream loaded. For each issue it will: apply the fix, update its rows in summary-response.md and review-response.md, then commit and push — in that order. Come back here when all sessions are complete.

Tell the user each session is ready and ask them to signal when all sessions are complete before proceeding to Phase 5.

---

Phase 5: Merge

Merge all hardening/[work-stream-name] branches into a new hardening/merged branch.

Because all response doc rows were pre-populated and each session only updated its own rows, git will merge the files cleanly. Resolve any conflicts by preserving all rows and combining in original issue ID order.

If a test command was provided, run the full test suite on hardening/merged before the code review. If tests fail, surface the failures to the user and ask whether to fix them, skip them, or proceed anyway before continuing.

Check for any rows still at ⬜ Pending. If any exist, surface them explicitly to the user — list each one and ask whether to fix them now or mark them as skipped with a reason. Do not proceed until every row is resolved.

Before the final commit, run a code review on hardening/merged. Check if the code-review skill is installed by attempting to invoke it. If installed, run /code-review on the merged branch and surface any findings to the user before proceeding. If not installed, warn the user: "The code-review skill is not installed. A review of hardening/merged is recommended before merging. Install it with /plugin install code-review@claude-plugins-official."

Commit and push the final merged result on hardening/merged. Present the final merged result to the user and confirm completion.

---

Reference Files

• references/planning-prompt.md — prompt used in Phase 2a to group issues into work streams
• references/response-format.md — exact format for summary-response.md and review-response.md
• references/work-stream-prompt.md — template for generating each session's prompt in Phase 3
• references/launch-sessions.md — exact tmux launch pattern, binary detection, verification, and fallback

Intermediate Files (written during execution, committed to audit branch)

• hardening-initial-review.md — written at end of Phase 1: confirmation status, effort estimate, and recommended fix approach per issue
• hardening-plan.md — written at end of Phase 2c: final agreed decisions including any revisions made during interactive review