@harness-engineering/cli 1.2.0 → 1.2.2

package/dist/agents/commands/gemini-cli/harness/brainstorming.toml

@@ -1,326 +0,0 @@
-# Generated by harness generate-slash-commands. Do not edit.
-description = "Structured ideation and exploration with harness methodology"
-prompt = """
-<context>
-Cognitive mode: constructive-architect
-Type: rigid
-</context>
-
-<objective>
-Structured ideation and exploration with harness methodology
-
-Phases:
-- explore: Generate ideas and possibilities
-- evaluate: Assess ideas against constraints
-- prioritize: Select and sequence top ideas
-- validate: Run harness checks on selected approach
-</objective>
-
-<execution_context>
---- SKILL.md (agents/skills/claude-code/harness-brainstorming/SKILL.md) ---
-# Harness Brainstorming
-
-> Design exploration to spec to plan. No implementation before design approval. Think first, build second.
-
-## When to Use
-
-- Starting a new feature or project that requires design decisions
-- When the problem space is ambiguous and needs exploration before planning
-- When multiple implementation approaches exist and tradeoffs must be weighed
-- When `on_new_feature` trigger fires and the scope is non-trivial
-- NOT when the implementation path is already clear (go straight to harness-planning)
-- NOT when fixing a bug with an obvious root cause (use harness-debugging or harness-tdd)
-- NOT when the task is a simple refactor with no design decisions (use harness-refactoring)
-
-## Process
-
-### Iron Law
-
-**No implementation may begin before the design is approved by the human.**
-
-If you find yourself writing production code, tests, or scaffolding before the human has signed off on the design, STOP. You are in the wrong skill. Brainstorming produces a spec document, not code.
-
----
-
-### Phase 1: EXPLORE — Gather Context
-
-1. **Read the existing codebase.** Understand the current architecture, constraints, and conventions. Check AGENTS.md, existing specs in `docs/`, and relevant source files.
-
-2. **Identify the problem boundary.** What exactly needs to be solved? What is explicitly out of scope? Write down both.
-
-3. **Check for prior art.** Has this problem been partially solved elsewhere in the codebase? Are there existing patterns that should be followed or deliberately broken?
-
-4. **Assess scope.** If the problem spans more than 3 major subsystems or would take more than 2 weeks to implement, it is too large. Decompose into sub-projects first, then brainstorm each one separately.
-
----
-
-### Phase 2: EVALUATE — Ask Questions and Narrow
-
-1. **Ask ONE question at a time.** Do not dump a list of 10 questions on the human. Ask the most important question first. Wait for the answer. Let the answer inform the next question.
-
-2. **Prefer multiple choice.** Instead of "How should we handle auth?", ask "For auth, should we: (A) use existing JWT middleware, (B) add OAuth2 via provider X, or (C) delegate to an external service?" Give 2-4 concrete options with brief tradeoff notes.
-
-3. **When the human answers, acknowledge and build on it.** Do not re-ask clarified points. Track decisions as they accumulate.
-
-4. **Apply YAGNI ruthlessly.** For every proposed capability, ask: "Do we need this for the stated goal, or is this speculative?" If speculative, cut it. If the human insists, note it as a future consideration, not a requirement.
-
-5. **Continue until you have enough clarity** to propose concrete approaches. Typically 3-7 questions are sufficient. If you need more than 10, the scope is too large — decompose.
-
-### Context Keywords
-
-During Phase 2, extract 5-10 domain keywords that capture the problem space. Include them in the spec frontmatter:
-
-```
-**Keywords:** auth, middleware, session-tokens, refresh-flow, OAuth2
-```
-
-These keywords flow into the `handoff.json` `contextKeywords` field when the spec is handed off to planning. Select keywords that would help a fresh agent — one that has never seen this conversation — understand the domain area quickly.
-
----
-
-### Phase 3: PRIORITIZE — Propose Approaches
-
-1. **Propose 2-3 concrete approaches.** Not 1 (no choice), not 5 (decision paralysis). Each approach must include:
-   - **Summary:** One sentence describing the approach
-   - **How it works:** Key technical decisions (what data structures, what APIs, what patterns)
-   - **Tradeoffs:** What you gain, what you lose, what gets harder later
-   - **Estimated complexity:** Low / Medium / High, with a brief justification
-   - **Risk:** What could go wrong, what assumptions might be wrong
-
-2. **Be honest about tradeoffs.** Do not soft-sell a preferred approach. If approach A is simpler but less extensible, say so plainly.
-
-3. **State your recommendation** and why, but defer to the human's decision.
-
-4. **Wait for the human to choose.** Do not proceed until an approach is selected.
-
----
-
-### Phase 4: VALIDATE — Write the Spec
-
-1. **Present the design section by section.** Do not dump the entire spec at once. Present each major section, get feedback, and incorporate it before moving to the next:
-   - Overview and goals
-   - Decisions made (with rationale from the brainstorming conversation)
-   - Technical design (data structures, APIs, file layout)
-   - Success criteria (observable, testable outcomes)
-   - Implementation order (high-level phases, not detailed tasks — that is harness-planning's job)
-
-2. **After all sections are reviewed, write the spec to `docs/`.** Use the project's existing spec naming convention. If none exists, use `docs/specs/YYYY-MM-DD-<feature-name>.md`.
-
-   When the project has `docs/specs/`, write proposals to `docs/changes/<feature>/proposal.md` instead. This keeps change proposals separate from established specs. Fall back to the existing behavior (`docs/specs/`) when no `docs/specs/` directory exists yet.
-
-3. **Run `harness validate`** to verify the spec file is properly placed and the project remains healthy.
-
-4. **Ask for final sign-off.** Present the complete spec file path and a one-paragraph summary. The human must explicitly approve before this skill is complete.
-
----
-
-### Scope Check
-
-At any point during brainstorming, if the design reveals that the project is larger than initially expected:
-
-1. **Identify natural decomposition boundaries.** Where can the project be split into independently deliverable pieces?
-2. **Propose sub-projects.** Each sub-project should be brainstormable and plannable on its own.
-3. **Get approval for the decomposition** before continuing to brainstorm any individual sub-project.
-
-## Party Mode
-
-When activated with `--party`, add a multi-perspective evaluation step after proposing approaches.
-
-### Perspective Selection
-
-Select 2-3 perspectives based on design topic:
-
-| Topic          | Perspectives                                 |
-| -------------- | -------------------------------------------- |
-| API / backend  | Backend Developer, API Consumer, Operations  |
-| UI / frontend  | Developer, Designer, End User                |
-| Infrastructure | Architect, SRE, Developer                    |
-| Data model     | Backend Developer, Data Consumer, Migration  |
-| Library / SDK  | Library Author, Library Consumer, Maintainer |
-| Cross-cutting  | Architect, Security, Developer               |
-| Default        | Architect, Developer, User/Consumer          |
-
-### Evaluation Process
-
-For each proposed approach, evaluate from each perspective:
-
-```
-### Approach N: [name]
-
-**[Perspective 1] perspective:**
-[Assessment]. Concern: [specific concern or "None"].
-
-**[Perspective 2] perspective:**
-[Assessment]. Concern: [specific concern or "None"].
-
-**[Perspective 3] perspective:**
-[Assessment]. Concern: [specific concern or "None"].
-
-**Synthesis:** [Consensus summary. Address raised concerns. Recommend proceed/revise.]
-```
-
-Converge on a recommendation that addresses all concerns before presenting the design.
-
-## Harness Integration
-
-- **`harness validate`** — Run after writing the spec to `docs/`. Verifies project health and that the new spec file is properly placed.
-- **`harness check-docs`** — Run to verify the spec does not conflict with existing documentation.
-- **Spec location** — Specs go to `docs/` (or `docs/specs/` if the project uses that convention). Follow existing naming patterns.
-- **Handoff to harness-planning** — Once the spec is approved, invoke harness-planning to create the implementation plan from the spec.
-
-#### Requirement Phrasing
-
-When brainstorming produces requirements or acceptance criteria that will feed into planning, prefer EARS sentence patterns for behavioral requirements. See the EARS Requirement Patterns section in harness-planning for the full template reference. Key patterns:
-
-- **Event-driven:** "When [trigger], the system shall [response]."
-- **Unwanted:** "If [condition], then the system shall not [behavior]."
-
-These patterns make requirements testable and unambiguous. Apply them when the output of brainstorming includes specific behavioral expectations.
-
-## Success Criteria
-
-- A spec document exists in `docs/` with all required sections (overview, decisions, technical design, success criteria, implementation order)
-- The human explicitly approved the design before any implementation
-- YAGNI was applied: no speculative features made it into the spec
-- 2-3 approaches were presented with honest tradeoffs before a decision was made
-- Questions were asked one at a time with multiple-choice options where possible
-- `harness validate` passes after the spec is written
-- If scope was too large, it was decomposed into sub-projects with the human's approval
-
-## Examples
-
-### Example: Designing a Notification System
-
-**EXPLORE:**
-
-```
-Read AGENTS.md — project is a TypeScript monorepo with React frontend and Express backend.
-Read existing docs/ — no prior notification specs. Found docs/specs/2026-01-15-user-auth.md as naming example.
-Checked src/services/ — no notification code exists. Found email utility in src/utils/email.ts.
-Scope assessment: single subsystem (notifications), estimated 1 week. Proceed.
-```
-
-**EVALUATE:**
-
-```
-Q1: "For notifications, should we support:
-  (A) Email only (simplest, covers 90% of use cases)
-  (B) Email + in-app (covers real-time needs)
-  (C) Email + in-app + push (full coverage, most complex)?"
-Human: "B — email and in-app."
-
-Q2: "For in-app notifications, should we:
-  (A) Poll from client every 30s (simple, slight delay)
-  (B) WebSocket push (real-time, more infrastructure)?"
-Human: "A — polling is fine for now."
-
-Q3: "Should notifications be stored permanently or expire after 30 days?"
-Human: "Expire after 30 days."
-```
-
-**PRIORITIZE:**
-
-```
-Approach 1: Event-driven with queue
-- Services emit events, notification worker consumes and dispatches
-- Tradeoff: More infrastructure (needs queue), but decoupled and scalable
-- Complexity: Medium
-- Risk: Queue adds operational overhead
-
-Approach 2: Direct service calls
-- Services call NotificationService directly
-- Tradeoff: Simpler, but couples services to notification logic
-- Complexity: Low
-- Risk: Harder to add channels later, synchronous blocking
-
-Recommendation: Approach 2. YAGNI — direct calls are sufficient for email + polling.
-We can migrate to event-driven later if we add push notifications.
-Human: "Agreed, approach 2."
-```
-
-**VALIDATE:**
-
-```
-Wrote docs/specs/2026-03-14-notification-system.md
-Sections: Overview, Decisions, Technical Design, Success Criteria, Implementation Order
-harness validate — passes
-"Spec written to docs/specs/2026-03-14-notification-system.md. Ready for sign-off?"
-Human: "Approved."
-```
-
-## Gates
-
-These are hard stops. Violating any gate means the process has broken down.
-
-- **No implementation before approval.** No production code, no test code, no scaffolding, no "let me just set up the directory structure." The spec must be approved first. If you wrote code, delete it.
-- **No skipping the question phase.** You must ask at least one clarifying question before proposing approaches. If you think you already know the answer, you are making assumptions — validate them.
-- **No single-approach proposals.** Always present at least 2 approaches with tradeoffs. A single approach is a recommendation disguised as a decision — the human has no real choice.
-- **No speculative features.** Every capability in the spec must trace to a stated requirement. "We might need this later" is not a requirement. Cut it.
-- **No section-dump specs.** Present the design section by section with feedback between each. Do not write the entire spec and ask "looks good?"
-
-## Escalation
-
-- **When the human cannot decide between approaches:** Identify the key differentiator. Ask: "The main difference is X. Given your priorities, does X matter more than Y?" If still stuck, suggest building a small spike to compare (but the spike is NOT production code).
-- **When scope keeps growing during brainstorming:** Stop brainstorming. Explicitly say: "The scope has expanded beyond the original problem. Should we (A) decompose into sub-projects, or (B) revisit the original goal to narrow it?" Do not continue accumulating scope.
-- **When the problem domain is unfamiliar:** State what you do not know. Ask the human if they have domain expertise, documentation, or a reference implementation. Do not guess at domain-specific requirements.
-- **When requirements conflict with existing architecture:** Flag the conflict explicitly: "The spec calls for X, but the current architecture assumes Y. Should we (A) change the spec to work within current architecture, or (B) plan an architecture change as a prerequisite?"
-- **When you have asked more than 10 questions without converging:** The problem is too large or too ambiguous. Stop and propose a decomposition or a scoping exercise before continuing.
-
-
---- skill.yaml (agents/skills/claude-code/harness-brainstorming/skill.yaml) ---
-name: harness-brainstorming
-version: "1.0.0"
-description: Structured ideation and exploration with harness methodology
-cognitive_mode: constructive-architect
-triggers:
-  - manual
-  - on_new_feature
-platforms:
-  - claude-code
-  - gemini-cli
-tools:
-  - Bash
-  - Read
-  - Write
-  - Edit
-  - Glob
-  - Grep
-cli:
-  command: harness skill run harness-brainstorming
-  args:
-    - name: path
-      description: Project root path
-      required: false
-mcp:
-  tool: run_skill
-  input:
-    skill: harness-brainstorming
-    path: string
-type: rigid
-phases:
-  - name: explore
-    description: Generate ideas and possibilities
-    required: true
-  - name: evaluate
-    description: Assess ideas against constraints
-    required: true
-  - name: prioritize
-    description: Select and sequence top ideas
-    required: true
-  - name: validate
-    description: Run harness checks on selected approach
-    required: true
-state:
-  persistent: false
-  files: []
-depends_on:
-  - harness-planning
-
-</execution_context>
-
-<process>
-1. Try: invoke mcp__harness__run_skill with skill: "harness-brainstorming"
-2. If MCP unavailable: follow the SKILL.md workflow provided above directly
-3. Pass through any arguments provided by the user
-</process>
-"""

package/dist/agents/commands/gemini-cli/harness/check-mechanical-constraints.toml

@@ -1,249 +0,0 @@
-# Generated by harness generate-slash-commands. Do not edit.
-description = "Run all mechanical constraint checks (context validation + architecture)"
-prompt = """
-<context>
-Cognitive mode: meticulous-verifier
-Type: rigid
-</context>
-
-<objective>
-Run all mechanical constraint checks (context validation + architecture)
-</objective>
-
-<execution_context>
---- SKILL.md (agents/skills/claude-code/check-mechanical-constraints/SKILL.md) ---
-# Check Mechanical Constraints
-
-> Run all mechanical constraint checks: linter rules, boundary schemas, and forbidden imports. These are automated, enforceable rules — if it can be checked by a machine, it must be.
-
-## When to Use
-
-- Before every commit (ideally via pre-commit hook)
-- Before submitting a pull request for review
-- After any code generation or automated refactoring
-- When `on_pre_commit` or `on_validate` triggers fire
-- After resolving merge conflicts (constraints may have been silently violated)
-- NOT as a substitute for code review — mechanical constraints catch structural issues, not logic errors
-- NOT when only editing non-code files (docs, config) unless those files have their own schema constraints
-
-## Process
-
-### Phase 1: Run All Checks
-
-1. **Run `harness validate`** to check project-wide constraints: file structure, naming conventions, required files, and configuration validity.
-
-2. **Run `harness linter validate`** to check all linter rules: code style, import restrictions, forbidden patterns, and boundary schemas.
-
-3. **Run `harness check-deps`** to check architectural layer boundaries. This is included here because dependency violations are mechanical — they can be detected purely from import statements and the constraint config.
-
-4. **Capture all output.** Combine results from all three commands into a single violation list for triage.
-
-### Phase 2: Categorize Violations by Severity
-
-Organize violations into three tiers:
-
-**Tier 1 — Errors (must fix before commit):**
-
-- Forbidden imports (importing banned modules)
-- Layer boundary violations (importing across architectural boundaries)
-- Schema violations (config files that do not match required schema)
-- Missing required files (every package must have index.ts, etc.)
-
-**Tier 2 — Warnings (must fix before merge):**
-
-- Naming convention violations (wrong casing, wrong prefix)
-- Import ordering issues
-- Unused exports detected by linter
-- Documentation file references that do not resolve
-
-**Tier 3 — Info (fix when convenient):**
-
-- Style suggestions (formatting that does not affect behavior)
-- Complexity warnings (functions exceeding thresholds)
-- Minor inconsistencies with project conventions
-
-### Phase 3: Auto-Fix Where Safe
-
-Some violations can be fixed automatically without risk:
-
-- **Import ordering** — reorder imports to match the configured convention. This never changes behavior.
-- **Formatting** — apply the project's formatter (prettier, etc.). Pure whitespace and style changes.
-- **Simple forbidden imports** — when a forbidden import has a known replacement (e.g., `import lodash` to `import lodash-es`), apply the substitution.
-- **Missing trailing commas, semicolons** — mechanical formatting fixes.
-
-**Rules for auto-fix:**
-
-- ONLY auto-fix violations that cannot change runtime behavior
-- Run the test suite after auto-fixing to confirm nothing broke
-- Present the auto-fix diff to the user for awareness (do not silently change code)
-- If unsure whether a fix is safe, do NOT auto-fix — report it for manual resolution
-
-### Phase 4: Report Remaining Violations
-
-For each violation that was not auto-fixed, report:
-
-1. **File and line number** — exact location of the violation
-2. **Rule name** — which constraint was violated
-3. **What it protects against** — why this rule exists (see reference below)
-4. **How to fix** — specific guidance for resolving this type of violation
-5. **Severity tier** — whether it blocks commit, merge, or is informational
-
-## What Each Constraint Type Protects Against
-
-### Forbidden Imports
-
-**Protects against:** Implementation detail leakage and unwanted coupling. When a library is forbidden in a layer, it is because using it there would create a dependency that makes the layer harder to test, replace, or maintain. Example: forbidding `fs` in the UI layer ensures UI code never directly accesses the filesystem.
-
-### Layer Boundaries
-
-**Protects against:** Architectural erosion. Without enforced boundaries, codebases gradually become a tangle where everything depends on everything. Layer boundaries ensure changes in one area do not ripple unpredictably through the whole system.
-
-### Boundary Schemas
-
-**Protects against:** Configuration drift and invalid state. When config files must match a schema, you catch invalid configurations at lint time rather than at runtime. This prevents deployment failures and hard-to-debug runtime errors.
-
-### Naming Conventions
-
-**Protects against:** Cognitive overhead and inconsistency. Consistent naming means developers (human and AI) can predict file locations, function names, and module structure without searching. It also ensures automated tools that rely on naming patterns continue to work.
-
-### Required File Rules
-
-**Protects against:** Incomplete modules. When every package must have an `index.ts` or every component must have a test file, you ensure that the project structure remains complete and navigable.
-
-### Import Ordering
-
-**Protects against:** Merge conflicts and readability issues. Consistent import ordering reduces git conflicts when multiple developers add imports to the same file. It also makes imports scannable at a glance.
-
-## Harness Integration
-
-- **`harness validate`** — Project-wide structural validation. Checks file structure, naming conventions, required files, and configuration schemas.
-- **`harness validate --json`** — Machine-readable output for parsing and categorization.
-- **`harness linter validate`** — Runs all configured linter rules. Checks code patterns, import restrictions, and style conventions.
-- **`harness check-deps`** — Architectural boundary enforcement. Checks all imports against the layer model.
-- **`harness check-deps --json`** — Machine-readable dependency check output.
-
-## Success Criteria
-
-- All three commands (`harness validate`, `harness linter validate`, `harness check-deps`) pass with zero errors
-- All Tier 1 violations are resolved before any commit
-- All Tier 2 violations are resolved before any merge to main
-- Auto-fixed changes are verified by running the test suite
-- No violations are suppressed without explicit team approval and a documented reason
-
-## Examples
-
-### Example: Forbidden import detected
-
-**Violation:**
-
-```
-ERROR [forbidden-import] src/components/Dashboard.tsx:3
-  Import 'pg' is forbidden in layer 'ui'
-  Rule: ui layer must not import database drivers
-```
-
-**What it protects against:** The UI layer importing a PostgreSQL driver means UI code could execute raw SQL queries, bypassing the service and repository layers entirely. This breaks testability (tests need a real database) and security (SQL injection risk from UI layer).
-
-**Fix:** Remove the direct database call. Add the needed query to the appropriate repository, expose it through the service layer, and call the service from the UI component.
-
-### Example: Auto-fixable import ordering
-
-**Violation:**
-
-```
-WARNING [import-order] src/services/auth-service.ts:1-8
-  Imports are not in the configured order
-  Expected: builtin -> external -> internal -> relative
-  Found: relative -> external -> builtin
-```
-
-**Auto-fix applied:**
-
-```typescript
-// BEFORE
-import { hashPassword } from './utils';
-import bcrypt from 'bcrypt';
-import { createHash } from 'crypto';
-
-// AFTER (auto-fixed)
-import { createHash } from 'crypto';
-import bcrypt from 'bcrypt';
-import { hashPassword } from './utils';
-```
-
-Tests re-run: all passing. No behavioral change.
-
-### Example: Schema violation in config
-
-**Violation:**
-
-```
-ERROR [schema-violation] harness.config.json:24
-  Property 'layers[2].allowedImports' must be an array of strings
-  Found: number (42)
-  Schema: harness-config-schema.json#/properties/layers/items/properties/allowedImports
-```
-
-**What it protects against:** An invalid config means `harness check-deps` will either crash or silently skip validation. The layer constraints would not be enforced, allowing violations to slip through undetected.
-
-**Fix:** Correct the config value to be a valid string array: `"allowedImports": ["@shared/types", "@shared/utils"]`.
-
-## Gates
-
-These are hard stops. Mechanical constraints are non-negotiable.
-
-- **No commits with Tier 1 violations.** Errors must be resolved before the code is committed. No exceptions.
-- **No merges with Tier 2 violations.** Warnings must be resolved before merging to the main branch.
-- **No suppressing rules without documentation.** If a rule must be disabled for a specific line or file, the suppression comment must explain WHY (not just disable the rule).
-- **No auto-fix without test verification.** Every auto-fix must be followed by a test run to confirm no behavioral change.
-
-## Escalation
-
-- **When a rule seems wrong for the project:** Rules are configured in `harness.config.json` and linter configs. If a rule does not fit, propose a config change with justification. Do not disable the rule inline.
-- **When a violation cannot be fixed without a larger refactor:** Document the violation, create a task for the refactor, and get team approval for a temporary inline suppression with a TODO linking to the task.
-- **When auto-fix produces unexpected changes:** Undo the auto-fix, report the issue, and fix manually. Auto-fix tools are not infallible.
-- **When multiple constraints conflict:** The stricter constraint wins. If `harness validate` says a file is required but `harness linter validate` says its contents violate a rule, fix the contents to satisfy both. Escalate if truly irreconcilable.
-
-
---- skill.yaml (agents/skills/claude-code/check-mechanical-constraints/skill.yaml) ---
-name: check-mechanical-constraints
-version: "1.0.0"
-description: Run all mechanical constraint checks (context validation + architecture)
-cognitive_mode: meticulous-verifier
-triggers:
-  - manual
-  - on_pr
-platforms:
-  - claude-code
-  - gemini-cli
-tools:
-  - Bash
-  - Read
-  - Glob
-cli:
-  command: harness skill run check-mechanical-constraints
-  args:
-    - name: path
-      description: Project root path
-      required: false
-mcp:
-  tool: run_skill
-  input:
-    skill: check-mechanical-constraints
-    path: string
-type: rigid
-state:
-  persistent: false
-  files: []
-depends_on:
-  - validate-context-engineering
-  - enforce-architecture
-
-</execution_context>
-
-<process>
-1. Try: invoke mcp__harness__run_skill with skill: "check-mechanical-constraints"
-2. If MCP unavailable: follow the SKILL.md workflow provided above directly
-3. Pass through any arguments provided by the user
-</process>
-"""