@harness-engineering/cli 1.2.0 → 1.2.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (52) hide show
  1. package/dist/bin/harness.js +1 -1
  2. package/dist/{chunk-IXT3KLVN.js → chunk-5RQKSZLA.js} +4 -3
  3. package/dist/index.js +1 -1
  4. package/package.json +6 -4
  5. package/dist/agents/commands/claude-code/harness/add-component.md +0 -34
  6. package/dist/agents/commands/claude-code/harness/align-documentation.md +0 -33
  7. package/dist/agents/commands/claude-code/harness/architecture-advisor.md +0 -41
  8. package/dist/agents/commands/claude-code/harness/brainstorming.md +0 -42
  9. package/dist/agents/commands/claude-code/harness/check-mechanical-constraints.md +0 -32
  10. package/dist/agents/commands/claude-code/harness/cleanup-dead-code.md +0 -33
  11. package/dist/agents/commands/claude-code/harness/code-review.md +0 -33
  12. package/dist/agents/commands/claude-code/harness/debugging.md +0 -43
  13. package/dist/agents/commands/claude-code/harness/detect-doc-drift.md +0 -32
  14. package/dist/agents/commands/claude-code/harness/diagnostics.md +0 -43
  15. package/dist/agents/commands/claude-code/harness/enforce-architecture.md +0 -32
  16. package/dist/agents/commands/claude-code/harness/execution.md +0 -43
  17. package/dist/agents/commands/claude-code/harness/git-workflow.md +0 -32
  18. package/dist/agents/commands/claude-code/harness/initialize-project.md +0 -33
  19. package/dist/agents/commands/claude-code/harness/onboarding.md +0 -32
  20. package/dist/agents/commands/claude-code/harness/parallel-agents.md +0 -35
  21. package/dist/agents/commands/claude-code/harness/planning.md +0 -41
  22. package/dist/agents/commands/claude-code/harness/pre-commit-review.md +0 -38
  23. package/dist/agents/commands/claude-code/harness/refactoring.md +0 -35
  24. package/dist/agents/commands/claude-code/harness/skill-authoring.md +0 -35
  25. package/dist/agents/commands/claude-code/harness/state-management.md +0 -35
  26. package/dist/agents/commands/claude-code/harness/tdd.md +0 -42
  27. package/dist/agents/commands/claude-code/harness/validate-context-engineering.md +0 -32
  28. package/dist/agents/commands/claude-code/harness/verification.md +0 -38
  29. package/dist/agents/commands/gemini-cli/harness/add-component.toml +0 -240
  30. package/dist/agents/commands/gemini-cli/harness/align-documentation.toml +0 -238
  31. package/dist/agents/commands/gemini-cli/harness/architecture-advisor.toml +0 -469
  32. package/dist/agents/commands/gemini-cli/harness/brainstorming.toml +0 -326
  33. package/dist/agents/commands/gemini-cli/harness/check-mechanical-constraints.toml +0 -249
  34. package/dist/agents/commands/gemini-cli/harness/cleanup-dead-code.toml +0 -258
  35. package/dist/agents/commands/gemini-cli/harness/code-review.toml +0 -461
  36. package/dist/agents/commands/gemini-cli/harness/debugging.toml +0 -436
  37. package/dist/agents/commands/gemini-cli/harness/detect-doc-drift.toml +0 -215
  38. package/dist/agents/commands/gemini-cli/harness/diagnostics.toml +0 -401
  39. package/dist/agents/commands/gemini-cli/harness/enforce-architecture.toml +0 -222
  40. package/dist/agents/commands/gemini-cli/harness/execution.toml +0 -381
  41. package/dist/agents/commands/gemini-cli/harness/git-workflow.toml +0 -325
  42. package/dist/agents/commands/gemini-cli/harness/initialize-project.toml +0 -257
  43. package/dist/agents/commands/gemini-cli/harness/onboarding.toml +0 -316
  44. package/dist/agents/commands/gemini-cli/harness/parallel-agents.toml +0 -221
  45. package/dist/agents/commands/gemini-cli/harness/planning.toml +0 -405
  46. package/dist/agents/commands/gemini-cli/harness/pre-commit-review.toml +0 -294
  47. package/dist/agents/commands/gemini-cli/harness/refactoring.toml +0 -209
  48. package/dist/agents/commands/gemini-cli/harness/skill-authoring.toml +0 -350
  49. package/dist/agents/commands/gemini-cli/harness/state-management.toml +0 -354
  50. package/dist/agents/commands/gemini-cli/harness/tdd.toml +0 -247
  51. package/dist/agents/commands/gemini-cli/harness/validate-context-engineering.toml +0 -186
  52. package/dist/agents/commands/gemini-cli/harness/verification.toml +0 -334
@@ -1,405 +0,0 @@
1
- # Generated by harness generate-slash-commands. Do not edit.
2
- description = "Structured project planning with harness constraints and validation"
3
- prompt = """
4
- <context>
5
- Cognitive mode: constructive-architect
6
- Type: rigid
7
- </context>
8
-
9
- <objective>
10
- Structured project planning with harness constraints and validation
11
-
12
- Phases:
13
- - scope: Define goals and constraints
14
- - decompose: Break work into tasks
15
- - sequence: Order tasks and identify dependencies
16
- - validate: Run harness checks on the plan
17
- </objective>
18
-
19
- <execution_context>
20
- --- SKILL.md (agents/skills/claude-code/harness-planning/SKILL.md) ---
21
- # Harness Planning
22
-
23
- > Implementation planning with atomic tasks, goal-backward must-haves, and complete executable instructions. Every task fits in one context window.
24
-
25
- ## When to Use
26
-
27
- - After a design spec is approved (output of harness-brainstorming) and implementation needs to be planned
28
- - When starting a new feature or project that needs structured task decomposition
29
- - When `on_new_feature` or `on_project_init` triggers fire and the work is non-trivial
30
- - When resuming a stalled project that needs a fresh plan
31
- - NOT when the task is small enough to implement directly (under 15 minutes, single file — just do it)
32
- - NOT when you need to explore the problem space first (use harness-brainstorming)
33
- - NOT when a plan already exists and needs execution (use harness-execution)
34
-
35
- ## Process
36
-
37
- ### Iron Law
38
-
39
- **Every task in the plan must be completable in one context window (2-5 minutes). If a task is larger, split it.**
40
-
41
- A plan with vague tasks like "add validation" or "implement the service" is not a plan — it is a wish list. Every task must contain exact file paths, exact commands, and complete code snippets.
42
-
43
- ---
44
-
45
- ### Phase 1: SCOPE — Derive Must-Haves from Goals
46
-
47
- Work backward from the goal. Do not start with "what should we build?" Start with "what must be true when we are done?"
48
-
49
- 1. **State the goal.** One sentence. What does the system do when this plan is complete?
50
-
51
- 2. **Derive observable truths.** What can be observed (by running a command, opening a browser, reading a file) that proves the goal is met? These are your acceptance criteria. Be specific:
52
- - BAD: "The API handles errors"
53
- - GOOD: "GET /api/users/nonexistent returns 404 with `{ error: 'User not found' }` body"
54
-
55
- 3. **Derive required artifacts.** For each observable truth, what files must exist? What functions must be implemented? What tests must pass? List exact file paths.
56
-
57
- 4. **Identify key links.** How do the artifacts connect? What imports what? What calls what? What data flows where? Draw the dependency graph mentally.
58
-
59
- 5. **Apply YAGNI.** For every artifact, ask: "Is this required for an observable truth?" If not, cut it.
60
-
61
- #### EARS Requirement Patterns
62
-
63
- When writing observable truths and acceptance criteria, use EARS (Easy Approach to Requirements Syntax) sentence patterns. These patterns eliminate ambiguity by forcing a consistent grammatical structure.
64
-
65
- | Pattern | Template | Use When |
66
- | ---------------- | -------------------------------------------------------- | ------------------------------------------------- |
67
- | **Ubiquitous** | The system shall [behavior]. | Behavior that always applies, unconditionally |
68
- | **Event-driven** | When [trigger], the system shall [response]. | Behavior triggered by a specific event |
69
- | **State-driven** | While [state], the system shall [behavior]. | Behavior that applies only during a certain state |
70
- | **Optional** | Where [feature is enabled], the system shall [behavior]. | Behavior gated by a configuration or feature flag |
71
- | **Unwanted** | If [condition], then the system shall not [behavior]. | Explicitly preventing undesirable behavior |
72
-
73
- **Worked Examples:**
74
-
75
- 1. **Ubiquitous:** "The system shall return JSON responses with `Content-Type: application/json` header."
76
- 2. **Event-driven:** "When a user submits an invalid form, the system shall display field-level error messages within 200ms."
77
- 3. **State-driven:** "While the database connection is unavailable, the system shall serve cached responses and log reconnection attempts."
78
- 4. **Optional:** "Where rate limiting is enabled, the system shall reject requests exceeding 100/minute per API key with HTTP 429."
79
- 5. **Unwanted:** "If the request body exceeds 10MB, then the system shall not attempt to parse it — return HTTP 413 immediately."
80
-
81
- **When to use EARS:** Apply these patterns when writing observable truths in Phase 1. Not every criterion needs an EARS pattern — use them when the requirement is behavioral (not structural). File existence checks ("src/types/user.ts exists with User interface") do not need EARS framing.
82
-
83
- ---
84
-
85
- ### Phase 2: DECOMPOSE — Map File Structure and Create Tasks
86
-
87
- 1. **Map the file structure first.** Before writing any tasks, list every file that will be created or modified. This is where decomposition decisions are locked. Example:
88
-
89
- ```
90
- CREATE src/services/notification-service.ts
91
- CREATE src/services/notification-service.test.ts
92
- MODIFY src/services/index.ts (add export)
93
- CREATE src/types/notification.ts
94
- MODIFY src/api/routes/users.ts (add notification trigger)
95
- ```
96
-
97
- 2. **Decompose into atomic tasks.** Each task must:
98
- - Be completable in 2-5 minutes
99
- - Fit in a single context window
100
- - Have a clear, testable outcome
101
- - Follow TDD: write test, fail, implement, pass, commit
102
- - Produce one atomic commit
103
-
104
- 3. **Write complete instructions for each task.** Not summaries — complete executable instructions:
105
- - **Exact file paths** to create or modify
106
- - **Exact code** to write (not "add validation logic" — write the actual validation code)
107
- - **Exact test commands** to run (e.g., `npx vitest run src/services/notification-service.test.ts`)
108
- - **Exact commit message** to use
109
- - **`harness validate`** as the final step
110
-
111
- 4. **Include checkpoints.** Mark tasks that require human verification, decisions, or actions:
112
- - `[checkpoint:human-verify]` — Pause, show result, wait for confirmation
113
- - `[checkpoint:decision]` — Pause, present options, wait for choice
114
- - `[checkpoint:human-action]` — Pause, instruct human on what they need to do
115
-
116
- ---
117
-
118
- ### Phase 3: SEQUENCE — Order Tasks and Identify Dependencies
119
-
120
- 1. **Order by dependency.** Types before implementations. Implementations before integrations. Tests alongside their implementations (same task, TDD style).
121
-
122
- 2. **Identify parallel opportunities.** Tasks that touch different subsystems with no shared state can be marked as parallelizable (for harness-parallel-agents).
123
-
124
- 3. **Number tasks sequentially.** Use `Task 1`, `Task 2`, etc. Dependencies reference task numbers: "Depends on: Task 3."
125
-
126
- 4. **Estimate total time.** Each task is 2-5 minutes. Sum them. If the total exceeds the available time, identify a milestone boundary where the plan can be paused with a working system.
127
-
128
- ---
129
-
130
- ### Phase 4: VALIDATE — Review and Finalize the Plan
131
-
132
- 1. **Verify completeness.** Every observable truth from Phase 1 must be achievable by completing the tasks. Trace each truth to the specific task(s) that deliver it.
133
-
134
- 2. **Verify task sizing.** Read each task. Could an agent complete it in one context window without needing to explore or make decisions? If not, split it.
135
-
136
- 3. **Verify TDD compliance.** Every task that produces code must include a test step. No task should say "write tests later."
137
-
138
- 4. **Run `harness validate`** to verify project health before writing the plan.
139
-
140
- 5. **Check failures log.** Read `.harness/failures.md` before finalizing. If planned approaches match known failures, flag them with warnings.
141
-
142
- 6. **Write the plan to `docs/plans/`.** Use naming convention: `YYYY-MM-DD-<feature-name>-plan.md`. If the directory does not exist, create it.
143
-
144
- 7. **Write handoff.** Save `.harness/handoff.json` with the following structure:
145
-
146
- ```json
147
- {
148
- "fromSkill": "harness-planning",
149
- "phase": "VALIDATE",
150
- "summary": "<one-sentence description of what was planned>",
151
- "completed": [],
152
- "pending": ["<task 1>", "<task 2>", "..."],
153
- "concerns": ["<any concerns or risks identified>"],
154
- "decisions": ["<key decisions made during planning>"],
155
- "contextKeywords": ["<domain-relevant keywords>"]
156
- }
157
- ```
158
-
159
- 8. **Present the plan to the human for review.** Walk through the task list, the estimated timeline, and any checkpoints that require human input.
160
-
161
- ---
162
-
163
- ### Plan Document Structure
164
-
165
- ````markdown
166
- # Plan: <Feature Name>
167
-
168
- **Date:** YYYY-MM-DD
169
- **Spec:** docs/specs/<spec-file>.md (if applicable)
170
- **Estimated tasks:** N
171
- **Estimated time:** N minutes
172
-
173
- ## Goal
174
-
175
- One sentence.
176
-
177
- ## Observable Truths (Acceptance Criteria)
178
-
179
- 1. [observable truth]
180
- 2. [observable truth]
181
-
182
- ## File Map
183
-
184
- - CREATE path/to/file.ts
185
- - MODIFY path/to/other-file.ts
186
-
187
- ## Tasks
188
-
189
- ### Task 1: <descriptive name>
190
-
191
- **Depends on:** none
192
- **Files:** path/to/file.ts, path/to/file.test.ts
193
-
194
- 1. Create test file `path/to/file.test.ts`:
195
- ```typescript
196
- // exact test code
197
- ```
198
- ````
199
-
200
- 2. Run test: `npx vitest run path/to/file.test.ts`
201
- 3. Observe failure: [expected failure message]
202
- 4. Create implementation `path/to/file.ts`:
203
- ```typescript
204
- // exact implementation code
205
- ```
206
- 5. Run test: `npx vitest run path/to/file.test.ts`
207
- 6. Observe: all tests pass
208
- 7. Run: `harness validate`
209
- 8. Commit: `feat(scope): descriptive message`
210
-
211
- ### Task 2: <descriptive name>
212
-
213
- [checkpoint:human-verify]
214
- ...
215
-
216
- ````
217
-
218
- ## Harness Integration
219
-
220
- - **`harness validate`** — Run during Phase 4 (before writing the plan) and included as a step in every task.
221
- - **`harness check-deps`** — Referenced in tasks that add imports or create new modules. Ensures dependency boundaries are respected.
222
- - **Plan location** — Plans go to `docs/plans/`. Follow the naming convention: `YYYY-MM-DD-<feature-name>-plan.md`.
223
- - **Handoff to harness-execution** — Once the plan is approved, invoke harness-execution to begin task-by-task implementation.
224
- - **Task commands** — Every task includes exact harness CLI commands to run (e.g., `harness validate`, `harness check-deps`).
225
-
226
- ## Change Specifications
227
-
228
- When planning changes to existing functionality (not greenfield), express requirements as deltas from the current documented behavior. Use these markers:
229
-
230
- - **[ADDED]** — New behavior that does not exist today
231
- - **[MODIFIED]** — Existing behavior that changes
232
- - **[REMOVED]** — Existing behavior that goes away
233
-
234
- **Example:**
235
- ```markdown
236
- ## Changes to User Authentication
237
-
238
- - [ADDED] Support OAuth2 refresh tokens with 7-day expiry
239
- - [MODIFIED] Login endpoint returns `refreshToken` field alongside existing `accessToken`
240
- - [MODIFIED] Token validation middleware accepts both JWT and OAuth2 tokens
241
- - [REMOVED] Legacy API key authentication (deprecated in v2.1)
242
- ````
243
-
244
- This is not mandatory for greenfield features. Only apply when modifying existing documented behavior.
245
-
246
- When `docs/specs/` exists in the project, produce `docs/changes/<feature>/delta.md` alongside the task plan. This keeps the change intent separate from the full spec and makes review easier.
247
-
248
- ## Success Criteria
249
-
250
- - A plan document exists in `docs/plans/` with all required sections
251
- - Every task is completable in 2-5 minutes (one context window)
252
- - Every task includes exact file paths, exact code, and exact commands
253
- - Every code-producing task follows TDD: test first, fail, implement, pass
254
- - Observable truths trace to specific tasks that deliver them
255
- - File map lists every file to be created or modified
256
- - Checkpoints are marked where human input is required
257
- - `harness validate` passes before the plan is written
258
- - `harness validate` is included as a step in every task
259
- - The human has reviewed and approved the plan
260
-
261
- ## Examples
262
-
263
- ### Example: Planning a User Notification Feature
264
-
265
- **Goal:** Users receive email and in-app notifications when their account is modified.
266
-
267
- **Observable Truths:**
268
-
269
- 1. `POST /api/users/:id` with changed fields triggers a notification record in the database
270
- 2. `GET /api/notifications?userId=:id` returns the notification with type, message, and timestamp
271
- 3. Notification email is sent via the existing email utility (verified by mock in test)
272
- 4. `npx vitest run src/services/notification-service.test.ts` passes with 8+ tests
273
- 5. `harness validate` passes
274
-
275
- **File Map:**
276
-
277
- ```
278
- CREATE src/types/notification.ts
279
- CREATE src/services/notification-service.ts
280
- CREATE src/services/notification-service.test.ts
281
- MODIFY src/services/index.ts
282
- MODIFY src/api/routes/users.ts
283
- MODIFY src/api/routes/users.test.ts
284
- ```
285
-
286
- **Task 1: Define notification types**
287
-
288
- ```
289
- Files: src/types/notification.ts
290
- 1. Create src/types/notification.ts:
291
- export interface Notification {
292
- id: string;
293
- userId: string;
294
- type: 'account_modified';
295
- message: string;
296
- read: boolean;
297
- createdAt: Date;
298
- expiresAt: Date;
299
- }
300
- 2. Run: harness validate
301
- 3. Commit: "feat(notifications): define Notification type"
302
- ```
303
-
304
- **Task 2: Create notification service with create method (TDD)**
305
-
306
- ```
307
- Files: src/services/notification-service.ts, src/services/notification-service.test.ts
308
- 1. Write test: create notification returns Notification object with correct fields
309
- 2. Run test — observe: NotificationService is not defined
310
- 3. Implement: NotificationService.create() stores and returns notification
311
- 4. Run test — observe: pass
312
- 5. Run: harness validate
313
- 6. Commit: "feat(notifications): add NotificationService.create"
314
- ```
315
-
316
- **Task 3: Add list and expiry methods (TDD)**
317
-
318
- ```
319
- [checkpoint:human-verify] — verify Task 2 output before continuing
320
- Files: src/services/notification-service.ts, src/services/notification-service.test.ts
321
- 1. Write tests: list by userId, filter expired
322
- 2. Run tests — observe failures
323
- 3. Implement: list() and isExpired() methods
324
- 4. Run tests — observe: pass
325
- 5. Run: harness validate, harness check-deps
326
- 6. Commit: "feat(notifications): add list and expiry to NotificationService"
327
- ```
328
-
329
- ## Gates
330
-
331
- These are hard stops. Violating any gate means the process has broken down.
332
-
333
- - **No vague tasks.** "Implement the service" is not a task. Every task must have exact file paths, exact code, and exact commands. If you cannot write the code in the plan, you do not understand the task well enough to plan it.
334
- - **No tasks larger than one context window.** If a task requires exploring the codebase, making design decisions, or touching more than 3 files, it is too large. Split it.
335
- - **No skipping TDD in tasks.** Every task that produces code must start with writing a test. "Add tests later" is not allowed in a plan. If tests cannot be written first, the design is unclear — go back to brainstorming.
336
- - **No plan without observable truths.** The plan must start with goal-backward acceptance criteria. If you cannot state what is observable when the plan is complete, you do not understand the goal.
337
- - **No implementation during planning.** The plan is a document, not code. Do not "just start Task 1 while we are here." Write the plan, get approval, then use harness-execution.
338
- - **File map must be complete.** Every file that will be created or modified must appear in the file map. Discovering new files during execution means the plan was incomplete.
339
-
340
- ## Escalation
341
-
342
- - **When you cannot write exact code for a task:** The design is underspecified. Go back to the spec (or brainstorm if no spec exists). Do not write a vague task as a placeholder.
343
- - **When task count exceeds 20:** The project may be too large for a single plan. Consider splitting into multiple plans with clear milestone boundaries.
344
- - **When dependencies form a cycle:** The decomposition is wrong. Re-examine the file map and find a way to break the cycle (usually by extracting a shared type or interface).
345
- - **When you discover the spec is missing information during planning:** Do not fill in the gaps yourself. Escalate: "The spec does not define behavior for [scenario]. This blocks Task N. We need to update the spec before continuing the plan."
346
- - **When estimated time exceeds available time:** Identify a milestone boundary where the plan can be paused with a working system. Propose delivering the plan in phases, each phase producing a usable increment.
347
-
348
-
349
- --- skill.yaml (agents/skills/claude-code/harness-planning/skill.yaml) ---
350
- name: harness-planning
351
- version: "1.0.0"
352
- description: Structured project planning with harness constraints and validation
353
- cognitive_mode: constructive-architect
354
- triggers:
355
- - manual
356
- - on_new_feature
357
- - on_project_init
358
- platforms:
359
- - claude-code
360
- - gemini-cli
361
- tools:
362
- - Bash
363
- - Read
364
- - Write
365
- - Edit
366
- - Glob
367
- cli:
368
- command: harness skill run harness-planning
369
- args:
370
- - name: path
371
- description: Project root path
372
- required: false
373
- mcp:
374
- tool: run_skill
375
- input:
376
- skill: harness-planning
377
- path: string
378
- type: rigid
379
- phases:
380
- - name: scope
381
- description: Define goals and constraints
382
- required: true
383
- - name: decompose
384
- description: Break work into tasks
385
- required: true
386
- - name: sequence
387
- description: Order tasks and identify dependencies
388
- required: true
389
- - name: validate
390
- description: Run harness checks on the plan
391
- required: true
392
- state:
393
- persistent: false
394
- files: []
395
- depends_on:
396
- - harness-verification
397
-
398
- </execution_context>
399
-
400
- <process>
401
- 1. Try: invoke mcp__harness__run_skill with skill: "harness-planning"
402
- 2. If MCP unavailable: follow the SKILL.md workflow provided above directly
403
- 3. Pass through any arguments provided by the user
404
- </process>
405
- """
@@ -1,294 +0,0 @@
1
- # Generated by harness generate-slash-commands. Do not edit.
2
- description = "Lightweight pre-commit quality gate combining mechanical checks and AI review"
3
- prompt = """
4
- <context>
5
- Type: rigid
6
- </context>
7
-
8
- <objective>
9
- Lightweight pre-commit quality gate combining mechanical checks and AI review
10
-
11
- Phases:
12
- - mechanical-checks: Run deterministic checks (lint, typecheck, tests)
13
- - classify-changes: Determine if AI review is needed based on change type
14
- - ai-review: Lightweight AI review of staged changes (skipped for docs/config-only) (optional)
15
- </objective>
16
-
17
- <execution_context>
18
- --- SKILL.md (agents/skills/claude-code/harness-pre-commit-review/SKILL.md) ---
19
- # Harness Pre-Commit Review
20
-
21
- > Lightweight pre-commit quality gate — mechanical checks first, AI review second. Fast feedback before code leaves your machine.
22
-
23
- ## When to Use
24
-
25
- - Before committing code (manual invocation or git pre-commit hook)
26
- - As a quick sanity check before pushing to a branch
27
- - When you want fast feedback without a full code review cycle
28
- - NOT as a replacement for full peer review (use `harness-code-review` for that)
29
- - NOT for commits that only update documentation or configuration (fast path skips AI review)
30
-
31
- ## Principle: Deterministic First
32
-
33
- This skill follows the Deterministic-vs-LLM Responsibility Split principle. Mechanical checks run first and must pass before any AI review occurs. If a linter or type checker can catch the problem, the LLM should not be the one finding it.
34
-
35
- ## Process
36
-
37
- ### Phase 1: Mechanical Checks
38
-
39
- Run all deterministic checks against staged changes. These are binary pass/fail — no judgment required.
40
-
41
- #### 1. Detect Available Check Commands
42
-
43
- ```bash
44
- # Check for project-specific commands
45
- cat package.json 2>/dev/null | grep -E '"(lint|typecheck|test)"'
46
- cat Makefile 2>/dev/null | grep -E '^(lint|typecheck|test):'
47
- ```
48
-
49
- #### 2. Run Checks in Order
50
-
51
- Run whichever of these are available in the project:
52
-
53
- ```bash
54
- # Lint (fastest — run first)
55
- pnpm lint 2>&1 || npm run lint 2>&1 || make lint 2>&1
56
-
57
- # Type check
58
- pnpm typecheck 2>&1 || npx tsc --noEmit 2>&1 || make typecheck 2>&1
59
-
60
- # Tests (slowest — run last)
61
- pnpm test 2>&1 || npm test 2>&1 || make test 2>&1
62
- ```
63
-
64
- #### 3. Gate Decision
65
-
66
- - **Any check fails:** STOP. Report the failure. Do not proceed to AI review. The author must fix mechanical issues first.
67
- - **All checks pass:** Proceed to Phase 2.
68
-
69
- **Output format for failures:**
70
-
71
- ```
72
- Pre-Commit Check: FAIL
73
-
74
- Mechanical Checks:
75
- - Lint: FAIL — 3 errors (see output above)
76
- - Types: PASS
77
- - Tests: NOT RUN (blocked by lint failure)
78
-
79
- Action: Fix lint errors before committing.
80
- ```
81
-
82
- ### Phase 2: Classify Changes
83
-
84
- Determine whether AI review is needed based on what changed.
85
-
86
- ```bash
87
- # Get list of staged files
88
- git diff --cached --name-only
89
-
90
- # Check if only docs/config files changed
91
- git diff --cached --name-only | grep -v -E '\.(md|yml|yaml|json|toml|ini|cfg|conf|env|env\..*)$' | wc -l
92
- ```
93
-
94
- #### Fast Path: Skip AI Review
95
-
96
- If ALL staged files match these patterns, skip AI review and approve:
97
-
98
- - `*.md` (documentation)
99
- - `*.yml`, `*.yaml` (configuration)
100
- - `*.json` (configuration — unless in `src/`)
101
- - `*.toml`, `*.ini`, `*.cfg` (configuration)
102
- - `.env*` (environment — but warn about secrets)
103
- - `LICENSE`, `CODEOWNERS`, `.gitignore`
104
-
105
- **Output for fast path:**
106
-
107
- ```
108
- Pre-Commit Check: PASS (fast path)
109
-
110
- Mechanical Checks:
111
- - Lint: PASS
112
- - Types: PASS
113
- - Tests: PASS (12/12)
114
-
115
- AI Review: SKIPPED (docs/config only)
116
- ```
117
-
118
- #### Standard Path: Proceed to AI Review
119
-
120
- If any staged file contains code changes, proceed to Phase 3.
121
-
122
- ### Phase 3: AI Review (Lightweight)
123
-
124
- Perform a focused, lightweight review of staged changes. This is NOT a full code review — it catches obvious issues only.
125
-
126
- #### 1. Get the Staged Diff
127
-
128
- ```bash
129
- git diff --cached
130
- ```
131
-
132
- #### 2. Quick Review Checklist
133
-
134
- Review the staged diff for these high-signal issues only:
135
-
136
- - **Obvious bugs:** null dereference, infinite loops, off-by-one errors, resource leaks
137
- - **Security issues:** hardcoded secrets, SQL injection, path traversal, unvalidated input
138
- - **Broken imports:** references to files/modules that do not exist
139
- - **Debug artifacts:** console.log, debugger statements, TODO/FIXME without issue reference
140
- - **Type mismatches:** function called with wrong argument types (if visible in diff)
141
-
142
- Do NOT review for:
143
-
144
- - Style (that is the linter's job)
145
- - Architecture (that is the full review's job)
146
- - Test completeness (that is the full review's job)
147
- - Naming preferences (subjective and noisy at this stage)
148
-
149
- #### 3. Report
150
-
151
- **If no issues found:**
152
-
153
- ```
154
- Pre-Commit Check: PASS
155
-
156
- Mechanical Checks:
157
- - Lint: PASS
158
- - Types: PASS
159
- - Tests: PASS (12/12)
160
-
161
- AI Review: PASS (no issues found)
162
- ```
163
-
164
- **If issues found:**
165
-
166
- ```
167
- Pre-Commit Check: WARN
168
-
169
- Mechanical Checks:
170
- - Lint: PASS
171
- - Types: PASS
172
- - Tests: PASS (12/12)
173
-
174
- AI Review: 2 observations
175
- 1. [file:line] Possible null dereference — `user.email` accessed without null check after `findUser()` which can return null.
176
- 2. [file:line] Debug artifact — `console.log('debug:', payload)` appears to be left from debugging.
177
-
178
- Action: Review observations above. Commit anyway if intentional, or fix first.
179
- ```
180
-
181
- ## Git Hook Installation
182
-
183
- To use as an automatic pre-commit hook, add to `.git/hooks/pre-commit` or configure via your git hooks manager (husky, lefthook, etc.):
184
-
185
- ```bash
186
- #!/bin/bash
187
- # .git/hooks/pre-commit
188
- harness skill run harness-pre-commit-review
189
- exit_code=$?
190
- if [ $exit_code -ne 0 ]; then
191
- echo "Pre-commit review failed. Fix issues before committing."
192
- exit 1
193
- fi
194
- ```
195
-
196
- **Note:** AI review observations (WARN) do not block the commit — only mechanical check failures (FAIL) block. The author decides whether to address AI observations.
197
-
198
- ## Gates
199
-
200
- - **Mechanical checks must pass before AI review.** Do not run AI review if lint/typecheck/tests fail.
201
- - **Fast path is mandatory.** If only docs/config changed, skip AI review — do not waste tokens.
202
- - **AI review is advisory only.** Observations do not block the commit. Only mechanical failures block.
203
-
204
- ## Harness Integration
205
-
206
- - Follows Principle 7 (Deterministic-vs-LLM Split) — mechanical checks first, AI review second
207
- - Reads `.harness/review-learnings.md` for calibration (if present)
208
- - Complements harness-code-review (full review) — use pre-commit for quick checks, code-review for thorough analysis
209
-
210
- ## Success Criteria
211
-
212
- - [ ] Mechanical checks ran and produced clear pass/fail results
213
- - [ ] Fast path correctly identified docs/config-only changes
214
- - [ ] AI review focused on high-signal issues only (no style nits)
215
- - [ ] Report follows the structured format exactly
216
-
217
- ## Examples
218
-
219
- ### Example: Clean Commit
220
-
221
- ```
222
- Pre-Commit Check: PASS
223
-
224
- Mechanical Checks:
225
- - Lint: PASS
226
- - Types: PASS
227
- - Tests: PASS (12/12)
228
-
229
- AI Review: PASS (no issues found)
230
- ```
231
-
232
- ### Example: Docs-Only Fast Path
233
-
234
- ```
235
- Pre-Commit Check: PASS (fast path)
236
-
237
- Mechanical Checks:
238
- - Lint: PASS
239
- - Types: PASS
240
- - Tests: PASS (12/12)
241
-
242
- AI Review: SKIPPED (docs/config only)
243
- ```
244
-
245
- ## Escalation
246
-
247
- - **Mechanical checks fail:** Fix the issues. Do not bypass the hook.
248
- - **AI review finds a potential issue you disagree with:** Commit anyway — AI review observations are advisory, not blocking. If the observation is consistently wrong, add it to `.harness/review-learnings.md` under Noise / False Positives.
249
- - **Hook is too slow:** If the full test suite is slow, configure the project to run only affected tests in pre-commit. The full suite runs in CI.
250
-
251
-
252
- --- skill.yaml (agents/skills/claude-code/harness-pre-commit-review/skill.yaml) ---
253
- name: harness-pre-commit-review
254
- version: "1.0.0"
255
- description: Lightweight pre-commit quality gate combining mechanical checks and AI review
256
- triggers: [manual, on_commit]
257
- platforms: [claude-code, gemini-cli]
258
- tools: [Bash, Read, Glob, Grep]
259
- cli:
260
- command: harness skill run harness-pre-commit-review
261
- args:
262
- - name: path
263
- description: Project root path
264
- required: false
265
- mcp:
266
- tool: run_skill
267
- input:
268
- skill: harness-pre-commit-review
269
- path: string
270
- type: rigid
271
- phases:
272
- - name: mechanical-checks
273
- description: Run deterministic checks (lint, typecheck, tests)
274
- required: true
275
- - name: classify-changes
276
- description: Determine if AI review is needed based on change type
277
- required: true
278
- - name: ai-review
279
- description: Lightweight AI review of staged changes (skipped for docs/config-only)
280
- required: false
281
- state:
282
- persistent: false
283
- files: []
284
- depends_on:
285
- - harness-code-review
286
-
287
- </execution_context>
288
-
289
- <process>
290
- 1. Try: invoke mcp__harness__run_skill with skill: "harness-pre-commit-review"
291
- 2. If MCP unavailable: follow the SKILL.md workflow provided above directly
292
- 3. Pass through any arguments provided by the user
293
- </process>
294
- """