@harness-engineering/cli 1.0.1 → 1.1.0

package/dist/agents/agents/skills/gemini-cli/harness-state-management/SKILL.md

@@ -0,0 +1,295 @@
+# Harness State Management
+
+> Manage persistent state across agent sessions so that context, decisions, progress, and learnings survive context resets. Load state at session start, track position and decisions throughout, and save state for the next session.
+
+## When to Use
+
+- At the start of every session that continues previous work (load state)
+- When completing a task, phase, or milestone (update progress)
+- When making a decision that future sessions need to know about (record decision)
+- When discovering something non-obvious that would be lost on context reset (capture learning)
+- When hitting a blocker that cannot be resolved in the current session (log blocker)
+- At the end of every session (save state)
+- NOT for storing code — code belongs in git commits, not state files
+- NOT for storing large outputs or logs — state should be concise and navigable
+- NOT as a replacement for a plan document — plans live in `docs/`, state tracks progress through plans
+
+## Process
+
+### Phase 1: LOAD — Restore Context from Previous Sessions
+
+1. **Read `.harness/state.json`.** This is the primary state file. It contains:
+   - Current position (phase, task, step)
+   - Progress map (which tasks are complete, in progress, or blocked)
+   - Decisions made in previous sessions (date, what, why)
+   - Blockers encountered and their status
+   - Last session summary
+
+2. **Run `harness state show`** to get a formatted view of current state. This is equivalent to reading the JSON but formatted for readability.
+
+3. **Read `.harness/learnings.md`.** This is the append-only knowledge base. Scan for:
+   - Recent learnings (last 2-3 sessions) — these are most likely still relevant
+   - Gotchas and warnings — these prevent repeating mistakes
+   - Decisions with rationale — these explain why things are the way they are
+
+4. **Read `.harness/failures.md` if exists.** Scan for active anti-patterns and dead ends.
+
+5. **Read `.harness/handoff.json` if exists.** Structured context from last skill.
+
+6. **Check `.harness/archive/` for historical failure logs.**
+
+7. **If no state exists,** this is a fresh start. Create `.harness/state.json` with initial structure:
+
+   ```json
+   {
+     "schemaVersion": 1,
+     "position": { "phase": "start", "task": null },
+     "progress": {},
+     "decisions": [],
+     "blockers": [],
+     "lastSession": { "date": null, "summary": null }
+   }
+   ```
+
+8. **Announce the loaded context.** Briefly summarize: "Resuming from [position]. [N] tasks complete. [N] blockers. Key learnings: [summary]." This confirms the state was loaded and gives the human visibility.
+
+### Phase 2: TRACK — Maintain State During the Session
+
+1. **Update position when moving between phases or tasks.** Every time work shifts to a new task or phase, update `position` in state:
+
+   ```json
+   "position": { "phase": "execute", "task": "Task 3", "step": "writing tests" }
+   ```
+
+2. **Record decisions when they are made.** Decisions are choices that affect future work. Record them immediately — do not wait until the end of the session:
+
+   ```json
+   "decisions": [
+     {
+       "date": "2026-03-14",
+       "what": "Use WebSocket instead of SSE for real-time notifications",
+       "why": "SSE does not support bidirectional communication, which Task 5 requires"
+     }
+   ]
+   ```
+
+3. **Log blockers when encountered.** A blocker is anything that prevents the current task from completing:
+
+   ```json
+   "blockers": [
+     {
+       "date": "2026-03-14",
+       "task": "Task 4",
+       "description": "Payment gateway API returns 403 — API key may be expired",
+       "status": "open"
+     }
+   ]
+   ```
+
+4. **Update progress after each completed task:**
+
+   ```json
+   "progress": {
+     "Task 1": "complete",
+     "Task 2": "complete",
+     "Task 3": "in_progress",
+     "Task 4": "blocked"
+   }
+   ```
+
+5. **Keep state concise.** State is not a log. Each field should contain the current status, not a history of all changes. History belongs in `.harness/learnings.md` and git commits.
+
+### Phase 3: LEARN — Capture Knowledge for Future Sessions
+
+1. **Identify learnings as they happen.** A learning is anything that:
+   - Was surprising or non-obvious
+   - Took significant effort to figure out
+   - Would cause repeated wasted time if forgotten
+   - Represents a decision that needs rationale preserved
+
+2. **Capture learnings with `harness state learn`:**
+
+   ```bash
+   harness state learn "Date comparison needs UTC normalization — use Date.now() not new Date()"
+   ```
+
+   This appends to `.harness/learnings.md` with a timestamp.
+
+3. **Or append directly to `.harness/learnings.md`** with structured format:
+
+   ```markdown
+   ## 2026-03-14 — Task 3: Notification Expiry
+
+   - [learning]: PostgreSQL's `now()` returns timestamp with timezone, but our
+     application uses UTC epoch milliseconds. Always convert before comparing.
+   - [gotcha]: The notifications table has a unique constraint on (userId, type).
+     Use upsert (ON CONFLICT DO UPDATE) instead of plain INSERT.
+   - [decision]: Chose to store expiry as epoch milliseconds rather than
+     ISO timestamp for consistency with the rest of the codebase.
+   ```
+
+4. **Learnings are append-only.** Never edit or delete previous learnings. They are a chronological record. Even if a learning turns out to be wrong, append a correction rather than modifying the original.
+
+5. **What belongs in learnings vs. git commits:**
+   - **Learnings:** Context, rationale, gotchas, decisions, warnings — things that explain _why_ and _what to watch out for_
+   - **Git commits:** Code changes, what was done — things that explain _what_ changed
+   - Example: The commit says "feat: add UTC normalization to date comparison." The learning says "Date comparison needs UTC normalization because PostgreSQL returns timezone-aware timestamps but our app uses epoch milliseconds."
+
+### Phase 4: SAVE — Persist State for Next Session
+
+1. **Update `.harness/state.json`** with final position, progress, and session summary:
+
+   ```json
+   {
+     "schemaVersion": 1,
+     "position": { "phase": "execute", "task": "Task 4" },
+     "progress": {
+       "Task 1": "complete",
+       "Task 2": "complete",
+       "Task 3": "complete"
+     },
+     "decisions": [ ... ],
+     "blockers": [ ... ],
+     "lastSession": {
+       "date": "2026-03-14",
+       "summary": "Completed Tasks 2-3. Task 3 required UTC date normalization (see learnings). Starting Task 4 next session."
+     }
+   }
+   ```
+
+2. **Verify learnings were captured.** Review `.harness/learnings.md` — were all non-obvious discoveries recorded? If something was tricky during the session, it should be in learnings.
+
+3. **Decide whether to commit state files.** State files (`.harness/state.json`, `.harness/learnings.md`) should be committed to git so other team members and agents can access them. Commit state updates separately from code changes so they do not clutter code diffs.
+
+### Building Institutional Knowledge Over Time
+
+The `.harness/learnings.md` file grows over the lifetime of the project. It becomes a valuable resource:
+
+- **Week 1:** A few gotchas about the development environment and initial setup decisions.
+- **Month 1:** Patterns emerge — recurring issues, architectural decisions with rationale, team conventions that were established through experience.
+- **Month 6:** New team members read learnings and avoid months of rediscovery. The file captures knowledge that no single person holds.
+- **Year 1:** Learnings are the project's institutional memory. They explain why the architecture looks the way it does, why certain patterns were adopted, and what was tried and abandoned.
+
+Treat learnings as a first-class project artifact. They are as valuable as tests and documentation.
+
+### Archival Workflow
+
+- **Archive failures:** Move `failures.md` to `.harness/archive/` at milestone boundaries.
+- **Do NOT archive learnings** — permanent. Learnings accumulate for the lifetime of the project.
+- **Do NOT archive state** — git handles history. The current `state.json` is always the source of truth.
+- **Handoff is ephemeral** — overwritten by each skill. No archival needed.
+
+## Harness Integration
+
+- **`harness state show`** — Display current state in a formatted, readable view. Use at session start to quickly orient.
+- **`harness state reset`** — Reset state to initial values. Use when starting a completely new effort and old state is no longer relevant. Use with caution — this discards progress tracking.
+- **`harness state learn "<message>"`** — Append a learning to `.harness/learnings.md` with automatic timestamp formatting.
+- **`.harness/state.json`** — Primary state file. Read at session start, updated throughout, saved at session end.
+- **`.harness/learnings.md`** — Append-only knowledge base. Read at session start for context, appended to when discoveries are made.
+- **`.harness/failures.md`** — Active anti-patterns. Read at session start to avoid known dead ends.
+- **`.harness/handoff.json`** — Structured context from last skill. Read at session start for immediate context.
+- **`.harness/trace.md`** — Optional reasoning trace. Useful for debugging agent behavior across sessions.
+- **`.harness/archive/`** — Archived failure logs. Check for historical context when encountering recurring issues.
+
+## Success Criteria
+
+- State is loaded at the start of every session that continues previous work
+- Position is updated whenever the current phase or task changes
+- Decisions are recorded with date, what, and why — immediately when made, not deferred
+- Blockers are logged with task reference, description, and status
+- Progress is updated after each completed task
+- Learnings are captured for every non-obvious discovery during the session
+- `.harness/learnings.md` entries follow the structured format (date, task, tagged items)
+- Learnings are append-only — no edits or deletions of previous entries
+- State is saved before session end with an accurate session summary
+- State files are committed to git separately from code changes
+
+## Examples
+
+### Example: Starting a New Session (Resuming Work)
+
+**LOAD:**
+
+```
+Run: harness state show
+Output:
+  Position: execute / Task 3 (writing tests)
+  Progress: Task 1 complete, Task 2 complete
+  Blockers: none
+  Last session: 2026-03-13 — "Completed Tasks 1-2. Task 2 required
+    adding a new index on notifications.userId for query performance."
+
+Read: .harness/learnings.md
+  Most recent:
+  - [gotcha]: notifications table needs index on userId — queries
+    were timing out without it
+  - [decision]: used partial index (WHERE deleted_at IS NULL) to
+    avoid indexing soft-deleted rows
+
+Summary: "Resuming from Task 3 (writing tests). Tasks 1-2 complete.
+  Note: notifications table has a partial index on userId — see learnings."
+```
+
+### Example: Recording a Decision Mid-Session
+
+```
+Context: Implementing Task 4, need to choose between polling and WebSocket.
+
+Record decision:
+  date: "2026-03-14"
+  what: "Use WebSocket for real-time notification delivery"
+  why: "Polling would require 1-second intervals for acceptable latency,
+    which creates too much load. WebSocket gives instant delivery with
+    one persistent connection per client."
+
+Capture learning:
+  harness state learn "WebSocket chosen over polling for notifications.
+    Polling at 1s intervals = ~86k requests/day per client. WebSocket =
+    1 persistent connection. See Task 4 decision in state."
+```
+
+### Example: Ending a Session
+
+**SAVE:**
+
+```
+Update .harness/state.json:
+{
+  "schemaVersion": 1,
+  "position": { "phase": "execute", "task": "Task 5" },
+  "progress": {
+    "Task 1": "complete",
+    "Task 2": "complete",
+    "Task 3": "complete",
+    "Task 4": "complete"
+  },
+  "decisions": [
+    {
+      "date": "2026-03-14",
+      "what": "Use WebSocket for real-time notification delivery",
+      "why": "Polling creates too much load at acceptable latency intervals"
+    }
+  ],
+  "blockers": [],
+  "lastSession": {
+    "date": "2026-03-14",
+    "summary": "Completed Tasks 3-4. Task 3 added expiry logic with UTC normalization. Task 4 implemented WebSocket delivery (chose over polling — see decisions). Starting Task 5 (UI integration) next session."
+  }
+}
+
+Verify: .harness/learnings.md has entries for UTC normalization and WebSocket decision.
+Commit: git add .harness/ && git commit -m "chore: update harness state after Tasks 3-4"
+```
+
+### Example: What Belongs Where
+
+| Information                                           | Where It Goes                   | Why                                                  |
+| ----------------------------------------------------- | ------------------------------- | ---------------------------------------------------- |
+| "Added WebSocket handler in src/ws/"                  | Git commit message              | Describes what changed in code                       |
+| "Chose WebSocket over polling because..."             | `.harness/state.json` decisions | Records the choice and rationale for future sessions |
+| "WebSocket requires sticky sessions in load balancer" | `.harness/learnings.md`         | Non-obvious operational concern future sessions need |
+| "Task 4 complete"                                     | `.harness/state.json` progress  | Tracks execution position                            |
+| "The WebSocket library auto-reconnects by default"    | `.harness/learnings.md`         | Gotcha that saves future debugging time              |
+| "Tried approach X, failed because Y"                  | `.harness/failures.md`          | Active anti-pattern to avoid repeating               |
+| "Completed Tasks 1-3, Task 4 pending"                 | `.harness/handoff.json`         | Structured context for next skill                    |
+| "[PREPARE 10:30] Loaded 3 failures"                   | `.harness/trace.md`             | Reasoning trace for debugging agent behavior         |

package/dist/agents/agents/skills/gemini-cli/harness-state-management/skill.yaml

@@ -0,0 +1,32 @@
+name: harness-state-management
+version: "1.0.0"
+description: Manage persistent session state across harness agent sessions
+cognitive_mode: meticulous-implementer
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+tools:
+  - Bash
+  - Read
+  - Write
+  - Edit
+  - Glob
+cli:
+  command: harness skill run harness-state-management
+  args:
+    - name: path
+      description: Project root path
+      required: false
+mcp:
+  tool: run_skill
+  input:
+    skill: harness-state-management
+    path: string
+type: flexible
+state:
+  persistent: true
+  files:
+    - .harness/state.json
+depends_on: []

package/dist/agents/agents/skills/gemini-cli/harness-tdd/SKILL.md

@@ -0,0 +1,167 @@
+# Harness TDD
+
+> Red-green-refactor cycle integrated with harness validation. No production code exists without a failing test first.
+
+## When to Use
+
+- Implementing any new feature, function, module, or component
+- Fixing any bug (write a test that reproduces the bug first)
+- Adding behavior to existing code
+- When `on_new_feature` or `on_bug_fix` triggers fire
+- NOT when doing pure refactoring with existing test coverage (use harness-refactoring instead)
+- NOT when writing documentation, configuration, or non-behavioral files
+- NOT when spiking/prototyping (but convert spikes to TDD before merging)
+
+## Process
+
+### Iron Law
+
+**No production code may exist without a failing test that demanded its creation.**
+
+If you find yourself writing production code first, STOP. Delete it. Write the test first. This is not a guideline — it is a hard constraint.
+
+### Phase 1: RED — Write a Failing Test
+
+1. **Identify the smallest behavior to test.** One assertion per test. One behavior per cycle. If you are testing two things, split into two cycles.
+
+2. **Write the test file or add to the appropriate test file.** Follow the project's existing test conventions (file naming, framework, location).
+
+3. **Write ONE minimal test** that asserts the expected behavior. The test should:
+   - Have a clear, descriptive name that states what behavior is expected
+   - Set up only the minimal fixtures needed
+   - Make a single assertion about the expected outcome
+   - NOT test implementation details — test observable behavior
+
+4. **Run the test suite.** Use the project's test runner (e.g., `npx vitest run path/to/test`, `npm test`, `pytest`).
+
+5. **MANDATORY: Watch the test FAIL.** Read the failure message. Confirm it fails for the RIGHT reason — the behavior is not yet implemented, not because the test is broken. If the test passes, either the behavior already exists (skip this cycle) or the test is wrong (fix the test).
+
+6. **Record the failure.** Note the test name and failure reason. This is your contract for the GREEN phase.
+
+### Phase 2: GREEN — Write the Simplest Code to Pass
+
+1. **Write the MINIMUM production code** that makes the failing test pass. Do not write code for future tests. Do not add error handling you have not tested. Do not generalize.
+
+2. **Resist the urge to write "good" code.** The GREEN phase is about correctness, not elegance. Hardcoded values are acceptable if they pass the test. Duplication is acceptable. You will clean up in REFACTOR.
+
+3. **Run the FULL test suite** (not just the new test). All tests must pass.
+
+4. **MANDATORY: Watch the test PASS.** Read the output. Confirm all tests are green. If any test fails, fix the production code (not the tests) until all pass.
+
+5. **Do not proceed to REFACTOR if any test is red.** Fix first.
+
+### Phase 3: REFACTOR — Clean Up While Green
+
+1. **With all tests passing,** look for opportunities to improve:
+   - Remove duplication (DRY)
+   - Extract methods or functions for clarity
+   - Rename for better readability
+   - Simplify conditionals
+   - Improve structure without changing behavior
+
+2. **Run the full test suite after EVERY change.** If a test breaks during refactoring, undo the last change immediately. Refactoring must not change behavior.
+
+3. **Keep refactoring steps small.** One rename, one extraction, one simplification at a time. Run tests between each.
+
+4. **If no refactoring is needed, skip this phase.** Not every cycle requires cleanup.
+
+### Phase 4: VALIDATE — Run Harness Checks
+
+1. **Run `harness check-deps`** to verify dependency boundaries are respected. New code must not introduce forbidden imports or layer violations.
+
+2. **Run `harness validate`** to verify the full project health. This catches architectural drift, documentation gaps, and constraint violations.
+
+3. **If either check fails,** fix the issue before committing. The fix may require another RED-GREEN-REFACTOR cycle if it involves behavioral changes.
+
+4. **Commit the cycle.** Each RED-GREEN-REFACTOR-VALIDATE cycle produces one atomic commit. The commit message references what behavior was added (not "add test" — describe the behavior).
+
+### Cycle Rhythm
+
+Repeat the 4 phases for each new behavior. A typical feature requires 3-10 cycles. Each cycle should take 2-15 minutes. If a cycle takes longer than 15 minutes, the step is too large — break it down.
+
+**Ordering within a feature:**
+
+1. Start with the happy path (simplest success case)
+2. Add edge cases one at a time
+3. Add error handling cases
+4. Add integration points last
+
+## Harness Integration
+
+- **`harness check-deps`** — Run in VALIDATE phase after each cycle. Catches forbidden imports and layer boundary violations introduced by new code.
+- **`harness validate`** — Run in VALIDATE phase after each cycle. Full project health check including architecture, documentation, and constraints.
+- **`harness cleanup`** — Run periodically (every 3-5 cycles) to detect entropy accumulation. Address any issues before they compound.
+- **Test runner** — Use the project's configured test runner. Harness does not prescribe a test framework but the test must actually execute and report results.
+
+## Success Criteria
+
+- Every production function/method has at least one corresponding test
+- Every test was observed to fail before the production code was written
+- Every test was observed to pass after the production code was written
+- `harness check-deps` passes after each cycle
+- `harness validate` passes after each cycle
+- Each cycle is an atomic commit with a descriptive message
+- No test tests implementation details (only observable behavior)
+- No production code exists that was not demanded by a failing test
+
+## Examples
+
+### Example: Adding a `calculateTotal` function
+
+**RED:**
+
+```typescript
+// cart.test.ts
+it('calculates total for items with quantity and price', () => {
+  const items = [
+    { name: 'Widget', price: 10, quantity: 2 },
+    { name: 'Gadget', price: 25, quantity: 1 },
+  ];
+  expect(calculateTotal(items)).toBe(45);
+});
+```
+
+Run tests. Observe: `ReferenceError: calculateTotal is not defined`. Correct failure — function does not exist yet.
+
+**GREEN:**
+
+```typescript
+// cart.ts
+export function calculateTotal(items: Array<{ price: number; quantity: number }>): number {
+  return items.reduce((sum, item) => sum + item.price * item.quantity, 0);
+}
+```
+
+Run tests. Observe: all tests pass.
+
+**REFACTOR:** No refactoring needed for this simple function. Skip.
+
+**VALIDATE:**
+
+```bash
+harness check-deps   # Pass
+harness validate     # Pass
+git add cart.ts cart.test.ts
+git commit -m "feat(cart): calculate total from item price and quantity"
+```
+
+**Next cycle (RED):** Write a test for empty array input. Watch it fail (or pass — if it passes, the behavior is already handled). Continue.
+
+## Gates
+
+These are hard stops. Violating any gate means the process has broken down.
+
+- **Code before test = delete it.** If production code is written before a failing test exists, delete the production code and start the cycle correctly.
+- **Must watch fail.** If you did not observe the test fail with the correct failure reason, the RED phase is incomplete. Do not proceed to GREEN.
+- **Must watch pass.** If you did not observe all tests pass after writing production code, the GREEN phase is incomplete. Do not proceed to REFACTOR.
+- **No skipping VALIDATE.** Every cycle must end with `harness check-deps` and `harness validate`. Skipping creates architectural debt that compounds.
+- **No multi-behavior tests.** One test, one assertion, one behavior. Tests that assert multiple unrelated things must be split.
+- **No "I'll write tests later."** There is no later. The test comes first or the code does not get written.
+
+## Escalation
+
+- **After 3 failed attempts to make a test pass:** Stop coding. The design may be wrong. Re-examine the interface, the test assumptions, or the architecture. Consider whether the feature needs a different approach. Consult the plan or spec.
+- **When a test cannot be written without complex mocking:** This is a design smell. The code under test has too many dependencies. Refactor the existing code to be more testable before proceeding, or reconsider the abstraction boundary.
+- **When harness checks repeatedly fail:** The new code may be violating architectural constraints intentionally. Escalate to the human to decide whether to update the constraints or change the approach.
+- **When the cycle is taking more than 15 minutes:** The step is too large. Break the current behavior into smaller sub-behaviors and test each one separately.
+- **When you are unsure what to test next:** Review the spec or plan. If no spec exists, use the harness-brainstorming skill to clarify requirements before writing more tests.

package/dist/agents/agents/skills/gemini-cli/harness-tdd/skill.yaml

@@ -0,0 +1,48 @@
+name: harness-tdd
+version: "1.0.0"
+description: Test-driven development integrated with harness validation
+cognitive_mode: meticulous-implementer
+triggers:
+  - manual
+  - on_new_feature
+  - on_bug_fix
+platforms:
+  - claude-code
+  - gemini-cli
+tools:
+  - Bash
+  - Read
+  - Write
+  - Edit
+  - Glob
+  - Grep
+cli:
+  command: harness skill run harness-tdd
+  args:
+    - name: path
+      description: Project root path
+      required: false
+mcp:
+  tool: run_skill
+  input:
+    skill: harness-tdd
+    path: string
+type: rigid
+phases:
+  - name: red
+    description: Write failing test
+    required: true
+  - name: green
+    description: Implement minimal code to pass
+    required: true
+  - name: refactor
+    description: Clean up while keeping tests green
+    required: false
+  - name: validate
+    description: Run harness checks
+    required: true
+state:
+  persistent: false
+  files: []
+depends_on:
+  - harness-verification