Hammer

Hammer

Automated quality loop. Delegates a worker-leader that hammers away at an implement-review-iterate cycle until the work reaches 10/10 or max iterations (10) are exhausted. The main coordinator only hears back when it's done.

Architecture

Main Agent (you)
  |-- delegates --> Loop Coordinator (worker-leader, hasTools: true)
       |-- delegates --> Implementer (sub-worker, shares worktree)
       |   |-- implements, tests, commits
       |-- delegates --> Reviewer (sub-worker, shares worktree)
       |   |-- reviews code, writes review TICKET with score in frontmatter
       |-- reads review ticket frontmatter
       |   score < 10? --> new Implementer with changes_requested
       |   score = 10 + no changes? --> DONE, report back

When to Use

• Delegating any task that should meet high quality standards
• Work that benefits from independent review (a different agent reviews than implements)
• When the coordinator should not be bothered with iteration details

How to Use

Step 1: Prepare the Task

Gather the full task description and all requirements. Be explicit and complete -- the loop coordinator passes these verbatim to its sub-workers.

Step 1.b: Announce Hammertime

read the ./hammertime.png image.

Step 2: Delegate the Loop Coordinator

Read the loop coordinator prompt template at references/loop-coordinator-prompt.md (relative to this skill directory). Fill in the placeholders and delegate:

teams({ action: 'delegate', tasks: [{
  text: <filled loop coordinator prompt>,
  assignee: '<descriptive-name>',
  hasTools: true
}]})

hasTools: true gives the loop coordinator the teams tool so it can spawn implementer and reviewer sub-workers.

Step 3: Wait

The loop coordinator manages everything internally:

• Spawns an implementer for the task
• Spawns a reviewer after implementation completes
• Reads the review ticket, checks the score
• Loops (up to 10 iterations) if score < 10
• Reports back via team_comment when done

What Comes Back

The loop coordinator's final note contains:

• Final review score
• Number of iterations taken
• Review ticket ID (for the passing review)
• Summary of what was implemented

If max iterations are exhausted without reaching 10/10, it reports the best score achieved and the last review ticket so the main agent can decide what to do.

Prompt Templates

All prompt templates live in references/ relative to this skill directory:

• references/loop-coordinator-prompt.md -- the worker-leader prompt (fill in placeholders)
• references/reviewer-prompt.md -- used by the loop coordinator when spawning reviewers

Placeholders in the loop coordinator prompt:

The Review Ticket Contract

The reviewer writes a tk ticket with structured YAML frontmatter. This is the contract between reviewer and loop coordinator -- no text parsing, just frontmatter fields:

---
id: p-xxxx
status: closed
type: task
tags: [review, 4step]
score: 8
changes_requested:
  - "Missing null check in auth.ts:45"
  - "No test for token expiry edge case"
---
# Review: <task> (iteration 2)

## Suggest Fixing
...
## Possible Simplifications
...

The loop coordinator reads .tickets/<id>.md and checks:

• score: 10 AND changes_requested: [] --> done
• Anything else --> feed changes_requested back to a new implementer

Key Design Decisions

• Review as ticket: Score and feedback in YAML frontmatter. No regex, no text parsing.
• No GitHub: Purely local. No PRs, no GitHub API.
• Separate agents: Implementer and reviewer are different agents for objectivity.
• Cleanup cascade: Worker-leader death kills all sub-workers automatically.
• `hasTools` flag: Teams extension feature that gives a worker the teams tool for sub-delegation. Default is false; only the loop coordinator needs true.

Loop Coordinator Prompt Template

Fill in the placeholders and pass this as the text for a teams delegation with hasTools: true.

---

You are a loop coordinator. Your job is to manage an implement-review cycle until the work reaches 10/10 quality.

## Task

{{TASK_DESCRIPTION}}

## Working Directory

{{WORKING_DIRECTORY}}

## Additional Context

{{ADDITIONAL_CONTEXT}}

## Resuming From a Previous Run

Before starting fresh, check if there is prior work from a previous run of this task:

1. Run `tk ls --tags=4step` to find existing review tickets for this task
2. Run `git log --oneline -5` to see if implementation commits already exist

If a review ticket exists with score < 10, you can skip straight to delegating a new implementer with that review's `changes_requested` as feedback. No need to redo work that's already committed.

If a review ticket exists with score 10, the task is already done — just report completion.

## Your Process

You manage the loop by delegating sub-workers using the `teams` tool. Sub-workers share your working directory (useWorktree: false is enforced automatically).

### Iteration Loop

For each iteration (max 10):

#### 1. Delegate Implementer

Spawn an implementer sub-worker. Give it the full task description and, if this is not the first iteration, the review feedback from the previous round.

First iteration (omit the model field if no model preference):
teams({ action: 'delegate', tasks: [{
  text: 'You are an implementer. Your working directory is {{WORKING_DIRECTORY}}.\n\n## Task\n\n{{TASK_DESCRIPTION}}\n\n## Additional Context\n\n{{ADDITIONAL_CONTEXT}}\n\n## Your Job\n\n1. Read the codebase to understand existing patterns and conventions\n2. Implement the task fully\n3. Write tests where appropriate\n4. Run tests to verify they pass\n5. Commit your work with a clear commit message\n6. Close your ticket when done\n\nStay focused. Implement exactly what is asked, nothing more.\n\nIMPORTANT: Do NOT self-review. Do NOT create review tickets. Do NOT use the code-review skill. Just implement, test, commit. A separate reviewer agent handles the review.',
  assignee: 'impl-1',
  model: '{{MODEL_IMPLEMENTER}}'
}], useWorktree: false })

Subsequent iterations (with review feedback):
teams({ action: 'delegate', tasks: [{
  text: 'You are an implementer. Your working directory is {{WORKING_DIRECTORY}}.\n\n## Task\n\n{{TASK_DESCRIPTION}}\n\n## Review Feedback From Previous Iteration\n\nThe reviewer found these issues. Fix ALL of them:\n\n<paste changes_requested list here>\n\n## Your Job\n\n1. Read the review feedback carefully\n2. Fix every issue listed\n3. Run tests to verify they pass\n4. Commit your fixes\n5. Close your ticket when done\n\nIMPORTANT: Do NOT self-review. Do NOT create review tickets. Do NOT use the code-review skill. Just fix the issues, test, commit. A separate reviewer agent handles the review.',
  assignee: 'impl-N'
}], useWorktree: false })

Wait for the implementer to complete before proceeding.

#### 2. Delegate Reviewer

After the implementer completes, spawn a reviewer sub-worker. The reviewer must create a review TICKET with the score and changes_requested in YAML frontmatter.

teams({ action: 'delegate', tasks: [{
  text: 'You are a code reviewer. You are EXTREMELY CRITICAL and desire only perfection.\n\nYour working directory is {{WORKING_DIRECTORY}}.\n\n## What Was Requested\n\n{{TASK_DESCRIPTION}}\n\n## Your Job\n\n1. Run `git log --oneline -10` to see recent commits\n2. Run `git diff HEAD~N` (where N covers the implementation commits) to see all changes\n3. Read the changed files fully to understand the implementation\n4. Perform a thorough 6-pass review:\n   - Pass 1: Technical issues (runtime failures, type errors, null handling, async errors)\n   - Pass 2: Code consistency (style, patterns, naming, dead code)\n   - Pass 3: Architecture (duplication, coupling, missing abstractions)\n   - Pass 4: Environment compatibility (platform deps, version issues)\n   - Pass 5: Verification (run build, tests, linting -- actual commands)\n   - Pass 6: Synthesis (overall assessment)\n\n## CRITICAL: Output Format\n\nCreate a review ticket using tk. The ticket MUST have `score` and `changes_requested` in the YAML frontmatter.\n\nStep 1 -- create the ticket:\n  tk create \"Review: iteration N\" -d \"review\" --tags review,4step\n\nStep 2 -- note the ticket ID from the output\n\nStep 3 -- read the ticket file at .tickets/<id>.md\n\nStep 4 -- edit the ticket file to add score and changes_requested to the frontmatter, and write the full review in the body. The file must look like this:\n\n---\nid: <id>\nstatus: open\n... (existing fields)\nscore: <1-10>\nchanges_requested:\n  - \"description of issue 1\"\n  - \"description of issue 2\"\n---\n# Review: iteration N\n\n## Suggest Fixing\n<critical issues with file:line references and fix instructions>\n\n## Possible Simplifications\n<quality improvements>\n\n## What Works Well\n<strengths of the implementation>\n\n## Verification\n<commands run and their results>\n\nScoring rules:\n- 10/10: ZERO items in Suggest Fixing, ZERO items in Possible Simplifications. Everything is clean.\n- 9/10: Minor style nits only, no functional issues\n- 7-8/10: Some real issues that need fixing\n- Below 7: Significant problems\n\nBe brutally honest. Do not inflate the score. An empty changes_requested with score < 10 is contradictory -- if there are no changes requested, the score must be 10.\n\nStep 5 -- close the ticket: tk close <id>\n\nStep 6 -- report the review ticket ID in your completion note:\n  tk add-note <your-assigned-ticket> \"DONE: Review ticket: <review-ticket-id>, score: <score>\"',
  assignee: 'rev-N',
  model: '{{MODEL_REVIEWER}}'
}], useWorktree: false })

Wait for the reviewer to complete.

#### 3. Read the Review Ticket

The reviewer's completion note will mention the review ticket ID. Read the ticket file:

Read the file at .tickets/<review-ticket-id>.md

Look at the YAML frontmatter for:
- score: the numeric score (1-10)
- changes_requested: list of issues to fix

#### 4. Decide

- If score is 10 AND changes_requested is empty --> DONE. Proceed to reporting.
- If score < 10 OR changes_requested has items --> go to step 1 with the changes_requested as review feedback for the next implementer.
- If this was iteration 10 --> stop and report the best result.

### Reporting

When done (either 10/10 achieved or max iterations hit), report via team_comment:

team_comment: "DONE: 4-step loop complete.
- Score: <final score>/10
- Iterations: <N>
- Review ticket: <last review ticket id>
- Result: <brief summary of what was implemented and the outcome>"

Then close your ticket.

## Rules

- NEVER skip the review step. Every implementation gets reviewed.
- NEVER accept a score below 10 as "good enough" before max iterations.
- ALWAYS pass the full changes_requested list to the next implementer -- do not summarize or omit items.
- ALWAYS use useWorktree: false when delegating (this is enforced automatically, but be explicit).
- Delegate implementer and reviewer SEQUENTIALLY, never in parallel. The reviewer needs to see the implementer's commits.

Reviewer Prompt Reference

This is the reviewer prompt used by the loop coordinator. It is embedded in the loop coordinator prompt template. This file exists as a standalone reference for reading and iteration.

---

Reviewer Instructions

The reviewer is spawned as a sub-worker by the loop coordinator. Its job:

1. Examine the implementation (git diff, read changed files) 2. Perform a 6-pass critical review 3. Create a review ticket with structured frontmatter

Review Ticket Format

The reviewer creates a tk ticket with score and changes_requested in YAML frontmatter:

---
id: p-xxxx
status: closed
type: task
tags: [review, 4step]
score: 8
changes_requested:
  - "Missing null check in auth.ts:45 -- loginHandler does not guard against undefined session"
  - "No test for token expiry edge case -- add test that verifies behavior when refresh token is also expired"
---
# Review: iteration 2

## Suggest Fixing

**[Critical]** `src/auth.ts:45` -- `session` can be undefined when the user's cookie is malformed. Add a null check before accessing `session.token`.

**[Medium]** `src/auth.ts:102` -- No test covers the case where both access and refresh tokens are expired simultaneously.

## Possible Simplifications

- `src/auth.ts:70-85` -- The retry logic duplicates the pattern in `src/http.ts:30`. Extract a shared `withRetry()` helper.

## What Works Well

- Clean separation between token validation and session management
- Tests cover the happy path thoroughly
- Error messages are specific and actionable

## Verification

- `bun test` -- 14/14 passing
- `bun run build` -- clean, no warnings
- `bun run lint` -- no issues

Scoring Rules

Consistency rule: An empty changes_requested with score < 10 is contradictory. If there are no changes to request, score must be 10. If score is below 10, there must be items in changes_requested.

The 6 Review Passes

1. Technical Issues -- runtime failures, type errors, null handling, async errors, missing imports 2. Code Consistency -- style, patterns, naming conventions, dead code 3. Architecture -- duplication, hard-coded values, missing abstractions, coupling 4. Environment -- platform dependencies, version compatibility, migration risks 5. Verification -- run build, tests, linting. Report actual command output. 6. Synthesis -- overall assessment, score, changes_requested list