@harness-engineering/cli 1.0.1 → 1.1.0

package/dist/agents/agents/skills/gemini-cli/enforce-architecture/SKILL.md

@@ -0,0 +1,165 @@
+# Enforce Architecture
+
+> Validate architectural layer boundaries and detect dependency violations. No code may violate layer constraints — this is a hard gate, not a suggestion.
+
+## When to Use
+
+- Before approving any pull request or merge
+- After writing new imports or module references
+- When adding a new module or package to the project
+- When `on_pre_commit` or `on_architecture_check` triggers fire
+- After refactoring that moves code between layers or modules
+- NOT when editing documentation, configuration, or non-code files
+- NOT when the violation is intentional and requires a constraint update (escalate instead)
+
+## Process
+
+### Phase 1: Load Constraints
+
+1. **Read `harness.config.json`** to understand the project's architectural constraints. The config defines:
+   - **Layers** — ordered list of architectural layers (e.g., `ui -> service -> repository -> domain`)
+   - **Dependency rules** — which layers may import from which (typically: layers may only import from layers below them)
+   - **Forbidden imports** — specific import paths that are never allowed in certain contexts
+   - **Boundary definitions** — which directories/packages belong to which layer
+
+2. **Understand the layer model.** In a typical layered architecture:
+   - Higher layers depend on lower layers (UI depends on Service, Service depends on Repository)
+   - Lower layers NEVER depend on higher layers (Repository must not import from UI)
+   - Same-layer imports may or may not be allowed depending on project config
+   - Cross-cutting concerns (logging, config) have their own rules
+
+### Phase 2: Run Dependency Checks
+
+1. **Run `harness check-deps`** to analyze all import statements against the constraint model. Capture the full JSON output.
+
+2. **Parse the results.** Each violation includes:
+   - The violating file and line number
+   - The forbidden import target
+   - The source layer and target layer
+   - The specific rule being violated
+
+### Phase 3: Analyze Violations
+
+For each violation, determine:
+
+1. **Which layers are involved.** Identify the source file's layer and the imported module's layer. Map them to the constraint model.
+
+2. **What rule is violated.** Common violation types:
+   - **Upward dependency** — a lower layer imports from a higher layer (e.g., repository importing from UI). This is the most serious type. It creates coupling that makes the lower layer untestable in isolation.
+   - **Skip-layer dependency** — a layer reaches past its immediate neighbor (e.g., UI importing directly from Repository, bypassing Service). This breaks encapsulation and makes the middle layer pointless.
+   - **Circular dependency** — two modules or layers depend on each other. This creates fragile coupling where changing either module risks breaking the other.
+   - **Forbidden import** — a specific import that is explicitly banned (e.g., importing a database driver outside the repository layer). This prevents implementation details from leaking.
+
+3. **Explain the impact.** For each violation, state:
+   - WHY the constraint exists (what architectural property it protects)
+   - WHAT would happen if the violation were allowed to persist
+   - HOW it affects testability, maintainability, and changeability
+
+### Phase 4: Guide Resolution
+
+For each violation, provide a specific fix:
+
+- **Upward dependency:** Introduce an interface or abstraction in the lower layer. The higher layer implements it; the lower layer depends only on the abstraction. Alternatively, use dependency injection.
+- **Skip-layer dependency:** Route the call through the intermediate layer. Add a method to the Service layer that delegates to the Repository, then have the UI call the Service.
+- **Circular dependency:** Break the cycle by extracting shared types into a common module that both can depend on, or restructure so the dependency flows in one direction only.
+- **Forbidden import:** Replace the forbidden import with the approved alternative. If no alternative exists, the feature may need to live in a different layer.
+
+## Common Violation Patterns
+
+### Pattern: "I just need one thing from that layer"
+
+A UI component imports a repository function directly because "it is just one query." Fix: add the query to the Service layer. The extra indirection is the architecture working correctly.
+
+### Pattern: "Shared types across layers"
+
+Two layers both need the same type definition. Fix: place shared types in the lowest layer that both depend on, or create a dedicated `types` or `shared` module at the bottom of the layer stack.
+
+### Pattern: "Test utilities importing production code from wrong layer"
+
+Test helpers import across layer boundaries for convenience. Fix: each layer's tests should only import from that layer and below. Test utilities should follow the same constraints as production code.
+
+### Pattern: "Circular dependency through re-exports"
+
+Module A re-exports from Module B, and Module B imports from Module A. The circular dependency is hidden by the re-export. Fix: identify the true dependency direction and remove the reverse path.
+
+## Harness Integration
+
+- **`harness check-deps`** — Primary tool. Analyzes all imports against the layer model defined in `harness.config.json`. Returns structured violation data including file, line, source layer, target layer, and rule violated.
+- **`harness check-deps --json`** — Machine-readable output for automated pipelines. Use this when parsing results programmatically.
+- **`harness validate`** — Includes dependency checking as part of full project validation. Use when you want a complete health check, not just architecture.
+
+## Success Criteria
+
+- `harness check-deps` reports zero violations
+- All imports flow downward through the layer stack (or follow explicitly configured exceptions)
+- No circular dependencies exist between modules or layers
+- No forbidden imports are present anywhere in the codebase
+- Every new module is assigned to the correct layer in the config
+- The layer model in `harness.config.json` accurately reflects the intended architecture
+
+## Examples
+
+### Example: Service layer importing from UI layer
+
+**Violation from `harness check-deps`:**
+
+```
+VIOLATION: Upward dependency
+  File: src/services/user-service.ts:12
+  Import: import { UserForm } from '../components/UserForm'
+  Source layer: service (level 2)
+  Target layer: ui (level 3)
+  Rule: service layer must not depend on ui layer
+```
+
+**Impact:** The UserService now depends on a React component. It cannot be used in a CLI tool, a background job, or tested without a DOM. The service layer should be framework-agnostic.
+
+**Resolution:**
+
+```typescript
+// BEFORE (violating)
+import { UserForm } from '../components/UserForm';
+const data = UserForm.defaultValues; // using UI defaults in service
+
+// AFTER (fixed)
+// Define the defaults where they belong — in the service layer
+const DEFAULT_USER_DATA: UserInput = { name: '', email: '' };
+```
+
+### Example: Circular dependency between modules
+
+**Violation from `harness check-deps`:**
+
+```
+VIOLATION: Circular dependency detected
+  Cycle: src/services/order-service.ts -> src/services/inventory-service.ts -> src/services/order-service.ts
+  order-service imports checkStock from inventory-service
+  inventory-service imports getOrderQuantity from order-service
+```
+
+**Resolution:** Extract the shared concern into a new module:
+
+```typescript
+// src/services/stock-calculator.ts (new, shared module)
+export function calculateRequiredStock(quantity: number, reserved: number): number {
+  return quantity - reserved;
+}
+```
+
+Both services import from `stock-calculator` instead of from each other. The cycle is broken.
+
+## Gates
+
+These are hard stops. Architecture violations are not warnings — they are errors.
+
+- **No code with layer violations may be approved or merged.** If `harness check-deps` reports violations, the code must be fixed before it proceeds.
+- **No new modules without layer assignment.** Every new directory or package must be mapped to a layer in `harness.config.json` before code is written in it.
+- **No "temporary" violations.** There is no TODO for architecture. Either the code respects the constraints or it does not ship.
+- **No suppressing violations without team approval.** If a violation needs to be allowed, the constraint in `harness.config.json` must be explicitly updated with a comment explaining why.
+
+## Escalation
+
+- **When a violation seems impossible to fix within the current architecture:** The architecture may need to evolve. Escalate to the human with a clear explanation of the constraint, the use case, and why they conflict. Propose options: update the constraint, restructure the code, or add a new layer.
+- **When `harness check-deps` reports false positives:** Verify the layer assignments in `harness.config.json` are correct. If a file is assigned to the wrong layer, fix the config. If the tool is genuinely wrong, report the issue.
+- **When fixing one violation creates another:** This usually indicates a deeper structural issue. Step back and look at the dependency graph as a whole rather than fixing violations one at a time.
+- **When the team wants to change the layer model:** This is a significant architectural decision. All existing code must be migrated to the new model. Plan this as a dedicated refactoring effort, not a side task.

package/dist/agents/agents/skills/gemini-cli/enforce-architecture/skill.yaml

@@ -0,0 +1,31 @@
+name: enforce-architecture
+version: "1.0.0"
+description: Validate architectural layer boundaries and detect circular dependencies
+cognitive_mode: meticulous-verifier
+triggers:
+  - manual
+  - on_pr
+  - on_commit
+platforms:
+  - claude-code
+  - gemini-cli
+tools:
+  - Bash
+  - Read
+  - Glob
+cli:
+  command: harness skill run enforce-architecture
+  args:
+    - name: path
+      description: Project root path
+      required: false
+mcp:
+  tool: run_skill
+  input:
+    skill: enforce-architecture
+    path: string
+type: rigid
+state:
+  persistent: false
+  files: []
+depends_on: []

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

@@ -0,0 +1,388 @@
+# Harness Architecture Advisor
+
+> Cognitive mode: **advisory-guide**. Ask questions, surface trade-offs, present options. Do NOT execute. The human decides; you inform the decision.
+
+## When to Use
+
+- When designing a new feature, module, or system boundary
+- When choosing between architectural approaches (REST vs GraphQL, monolith vs microservice, etc.)
+- When refactoring raises questions about target architecture
+- When `on_new_feature` triggers fire and the feature touches multiple modules
+- When a Design-category error is escalated from harness-diagnostics
+- NOT for implementation (use harness-execution after the decision is made)
+- NOT for bug fixes (use harness-debugging or harness-diagnostics)
+- NOT for code review (use harness-code-review)
+
+## Core Principle
+
+**This skill advises. It does not execute.**
+
+You will research, analyze, and present options with clear trade-offs. You will not write production code, create files, or make architectural choices. The human makes the decision. You document it.
+
+If you find yourself writing implementation code, STOP. You have left advisory mode. Return to presenting options.
+
+## Process
+
+### Phase 1: DISCOVER — Understand the Problem Space
+
+**Gate: This phase requires human answers. Do not proceed to Phase 2 until the human has responded.**
+
+Ask these 5 questions. Wait for answers before proceeding.
+
+1. **What problem are you solving?** Describe the user-facing or system-facing need. Not the technical solution — the problem.
+
+2. **What are your hard constraints?** Things that cannot change: existing database, specific language/framework, compliance requirements, team size, timeline, budget.
+
+3. **What are your soft preferences?** Things you would like but could trade away: specific patterns, technology preferences, performance targets, consistency with other systems.
+
+4. **What have you already considered?** Any approaches you have thought about, tried, or rejected. Include why you rejected them if applicable.
+
+5. **What does success look like in 6 months?** How will you know this decision was correct? What would make you regret it?
+
+Record the answers verbatim. Do not paraphrase or interpret at this stage.
+
+```
+Store answers in: .harness/architecture/<topic>/discovery.md
+```
+
+---
+
+### Phase 2: ANALYZE — Research the Codebase
+
+Read the codebase to understand the current state. Do not propose solutions yet — gather facts.
+
+#### Step 1: Map Existing Patterns
+
+Search for how the codebase currently handles similar concerns:
+
+- What architectural patterns are already in use? (MVC, hexagonal, event-driven, etc.)
+- How are similar features structured?
+- What conventions exist for the relevant layer (API, data, UI, infrastructure)?
+
+#### Step 2: Identify Integration Points
+
+Find where the new feature will touch existing code:
+
+- Which modules will it interact with?
+- What are the current API boundaries?
+- Are there shared data models or services?
+
+#### Step 3: Assess Technical Debt
+
+Look for existing issues that may affect the decision:
+
+- Are there known pain points in the relevant area?
+- Is there existing tech debt that one option would worsen and another would improve?
+- Are there pending migrations or deprecations?
+
+#### Step 4: Summarize Findings
+
+```markdown
+## Codebase Analysis: <topic>
+
+### Current Patterns
+
+- <pattern 1>: used in <locations>
+- <pattern 2>: used in <locations>
+
+### Integration Points
+
+- <module A>: <how it connects>
+- <module B>: <how it connects>
+
+### Technical Debt
+
+- <issue 1>: <impact on this decision>
+- <issue 2>: <impact on this decision>
+
+### Relevant Files
+
+- <path>: <why it matters>
+```
+
+```
+Store analysis in: .harness/architecture/<topic>/analysis.md
+```
+
+---
+
+### Phase 3: PROPOSE — Present Options with Trade-Offs
+
+**Gate: This phase requires human choice at the end. Do not proceed to Phase 4 until the human has selected an option.**
+
+Present 2-3 architectural options. Never present only one option — a single option is not a decision, it is a directive. Never present more than 3 — too many options cause decision paralysis.
+
+#### For Each Option
+
+```markdown
+### Option [A/B/C]: <Name>
+
+**Summary:** One paragraph describing the approach.
+
+**How it works:**
+
+1. <Step 1>
+2. <Step 2>
+3. <Step 3>
+
+**Pros:**
+
+- <Advantage 1> — <why it matters given the constraints>
+- <Advantage 2> — <why it matters given the constraints>
+
+**Cons:**
+
+- <Disadvantage 1> — <severity: low/medium/high> — <mitigation if any>
+- <Disadvantage 2> — <severity: low/medium/high> — <mitigation if any>
+
+**Effort:** <Small / Medium / Large> — <rough description of what is involved>
+
+**Risk:** <Low / Medium / High> — <what could go wrong>
+
+**Best when:** <the scenario where this option is clearly the right choice>
+```
+
+#### Comparison Matrix
+
+After presenting all options, provide a direct comparison:
+
+```markdown
+| Criterion        | Option A | Option B | Option C |
+| ---------------- | -------- | -------- | -------- |
+| Complexity       |          |          |          |
+| Performance      |          |          |          |
+| Maintainability  |          |          |          |
+| Effort to build  |          |          |          |
+| Effort to change |          |          |          |
+| Risk             |          |          |          |
+| Fits constraints |          |          |          |
+```
+
+#### Recommendation
+
+State which option you would lean toward and why, but frame it as a recommendation, not a decision:
+
+```
+Based on the constraints (especially <key constraint>), I would lean toward Option <X> because <reason>.
+However, if <condition>, Option <Y> would be stronger.
+```
+
+Present the options to the human and wait for their choice.
+
+```
+Store proposal in: .harness/architecture/<topic>/proposal.md
+```
+
+---
+
+### Phase 4: DOCUMENT — Write the Architecture Decision Record
+
+After the human selects an option, write a formal ADR.
+
+#### ADR Template
+
+```markdown
+# ADR-<number>: <Title>
+
+**Date:** <date>
+**Status:** Accepted
+**Deciders:** <who was involved>
+
+## Context
+
+<What is the problem or need that prompted this decision? Include relevant
+background, constraints, and the current state of the system. A reader who
+was not part of the discussion should understand why this decision was needed.>
+
+## Decision
+
+<What is the architectural decision? State it clearly and specifically.
+Include enough detail that someone could implement it without further
+discussion.>
+
+## Alternatives Considered
+
+### <Alternative 1 name>
+
+<Brief description and why it was not chosen.>
+
+### <Alternative 2 name>
+
+<Brief description and why it was not chosen.>
+
+## Consequences
+
+### Positive
+
+- <Benefit 1>
+- <Benefit 2>
+
+### Negative
+
+- <Trade-off 1> — <mitigation plan>
+- <Trade-off 2> — <mitigation plan>
+
+### Neutral
+
+- <Side effect that is neither positive nor negative>
+
+## Action Items
+
+- [ ] <Concrete next step 1> — owner: <who> — by: <when>
+- [ ] <Concrete next step 2> — owner: <who> — by: <when>
+- [ ] <Concrete next step 3> — owner: <who> — by: <when>
+```
+
+Save the ADR:
+
+```
+.harness/architecture/<topic>/ADR-<number>.md
+```
+
+Also link from the project's ADR index if one exists.
+
+## Harness Integration
+
+- Extends the human-architect model — the skill is a thinking partner, not a decision maker
+- Respects architectural constraints defined in harness.config.json
+- Outputs structured ADR that other skills can reference
+- Reads prior ADRs from `.harness/architecture/` for consistency
+
+## Success Criteria
+
+- [ ] All 5 discovery questions are asked (or explicitly deferred by human)
+- [ ] At least 2 options are presented with concrete trade-offs
+- [ ] Human makes an explicit choice before documentation proceeds
+- [ ] ADR follows the template structure with all sections filled
+- [ ] ADR references specific files or components (not abstract generalities)
+
+## Gates
+
+- **Phase 1 to Phase 2: Requires human answers.** Do not proceed to codebase analysis until the human has answered the discovery questions. Without understanding constraints, analysis is directionless.
+- **Phase 3 to Phase 4: Requires human choice.** Do not write the ADR until the human has selected an option. The ADR documents a decision, not a recommendation.
+- **Always 2-3 options.** Never present 1 option (that is a directive, not advice). Never present more than 3 (that causes paralysis).
+- **No implementation in this skill.** If you write production code, you have broken the advisory boundary. Stop and return to presenting options.
+- **Trade-offs must be honest.** Every option has downsides. If you cannot articulate the cons of an option, you do not understand it well enough to recommend it.
+
+## Escalation
+
+- **Human cannot choose between options:** Help narrow by asking which constraint matters most. If two options are genuinely equivalent, say so — flip a coin on equivalent options rather than agonizing.
+- **Analysis reveals the problem is already solved:** If the codebase already has a pattern that handles this, say so. No need to architect what already exists.
+- **Constraints are contradictory:** If hard constraints rule out all reasonable options, escalate this back to the human. Something in the constraints must give.
+- **Decision has organization-wide impact:** If the decision affects teams or systems beyond the current codebase, flag this. The decision may need a broader audience.
+
+## Examples
+
+### Example 1: API Design for a New Resource
+
+**Phase 1 — DISCOVER:**
+
+```
+1. Problem: We need to expose order history to mobile clients and third-party integrations.
+2. Hard constraints: Must work with existing PostgreSQL database. REST API already
+   serves other resources. Team of 3 backend engineers. Ship in 6 weeks.
+3. Soft preferences: Would like to use GraphQL eventually. Want pagination.
+   Want to keep response times under 200ms.
+4. Already considered: Adding REST endpoints like the other resources. Wondered
+   about GraphQL but unsure if it is worth the investment for one resource.
+5. Success in 6 months: Mobile app and 2 integrations consuming the API without
+   complaints about performance or missing data.
+```
+
+**Phase 2 — ANALYZE:**
+
+```
+Current patterns: REST with Express, controller-service-repository layers.
+  15 existing resources follow this pattern.
+Integration points: Order model joins with Users and Products.
+  Existing /users and /products endpoints.
+Tech debt: No pagination on existing endpoints — they return all records.
+  This is fine for small datasets but orders could be large.
+```
+
+**Phase 3 — PROPOSE:**
+
+Option A: REST endpoints following existing patterns. Add pagination.
+
+- Pros: Consistent with codebase, team knows how to build it, fast to ship.
+- Cons: Mobile may over-fetch (gets all fields even when it needs few), no subscription support.
+- Effort: Small (2-3 weeks).
+
+Option B: GraphQL for orders only, REST for everything else.
+
+- Pros: Mobile gets exactly the fields it needs, natural pagination with cursors, foundation for future migration.
+- Cons: Two API paradigms to maintain, team learning curve, more infrastructure (Apollo/Yoga server).
+- Effort: Medium (4-5 weeks).
+
+Option C: REST with sparse fieldsets (JSON:API style `?fields=id,total,date`).
+
+- Pros: Stays REST, solves over-fetching for mobile, no new infrastructure.
+- Cons: Custom implementation of field filtering, not a standard the team has used before, still no subscriptions.
+- Effort: Small-Medium (3-4 weeks).
+
+Recommendation: Option A with pagination. It ships fastest, matches the existing codebase, and the team can migrate to GraphQL later as a separate initiative when there are more consumers with diverse needs.
+
+**Phase 4 — DOCUMENT:**
+ADR written after human selects Option A. Action items: implement pagination middleware (reusable for other endpoints), create /orders endpoints, update API documentation.
+
+### Example 2: Component Decomposition for a Dashboard
+
+**Phase 1 — DISCOVER:**
+
+```
+1. Problem: The dashboard page component is 1200 lines and growing. It handles
+   data fetching, state management, filtering, sorting, and rendering for
+   5 different widget types.
+2. Hard constraints: React with TypeScript. Must not break existing widget
+   behavior. Cannot change the API contract — backend team is on a different
+   release cycle.
+3. Soft preferences: Want widgets to be independently testable. Want to add
+   2 new widget types next quarter without touching the main component.
+4. Already considered: Just splitting into smaller files. Worried that without
+   a clear boundary, it will re-tangle.
+5. Success in 6 months: Adding a new widget type requires creating one new
+   file and registering it, not modifying the dashboard component.
+```
+
+**Phase 2 — ANALYZE:**
+
+```
+Current patterns: Dashboard uses a single useEffect for all data fetching.
+  State is a large object with fields for each widget type. Rendering uses
+  a switch statement on widget type.
+Integration points: 3 API endpoints supply data. Shared filter context
+  affects all widgets. URL query params drive initial state.
+Tech debt: Two widget types share copy-pasted filtering logic. The sort
+  function has special cases for each widget type.
+```
+
+**Phase 3 — PROPOSE:**
+
+Option A: Widget plugin architecture with a registry.
+
+- Each widget is a self-contained module (component + hook + types).
+- A registry maps widget type strings to widget modules.
+- Dashboard iterates the registry, renders each widget, passes shared context.
+- Pros: Adding a widget means adding one module and one registry entry. Widgets are independently testable. Clear boundaries.
+- Cons: Requires upfront refactoring of all 5 existing widgets. Shared filter logic needs a common abstraction.
+- Effort: Medium (2-3 weeks to extract, then new widgets are fast).
+
+Option B: Compound component pattern with slots.
+
+- Dashboard defines layout slots. Each widget fills a slot.
+- Shared state via React context. Each widget manages its own data fetching.
+- Pros: Simpler than a registry. Familiar React patterns. Widgets own their data.
+- Cons: Less structured than a registry — no formal contract. Could re-tangle if disciplines slip. Adding a widget still requires modifying the dashboard layout.
+- Effort: Small-Medium (1-2 weeks).
+
+Option C: Micro-frontend approach with module federation.
+
+- Each widget is a separate build artifact loaded at runtime.
+- Pros: Maximum independence. Widgets can use different libraries. Independent deployment.
+- Cons: Massive overkill for 5-7 widgets in one app. Complex build setup. Runtime overhead. Team of 3 does not need this level of isolation.
+- Effort: Large (4-6 weeks).
+
+Recommendation: Option A. The plugin registry provides the clear boundary you need to prevent re-tangling, and the upfront cost pays off immediately when you add the 2 new widget types next quarter. Option C is overengineered for your scale.
+
+**Phase 4 — DOCUMENT:**
+ADR written after human selects Option A. Action items: define widget interface contract, extract existing widgets one at a time (one PR per widget), create registry with type-safe registration, add documentation for "how to add a new widget."

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

@@ -0,0 +1,48 @@
+name: harness-architecture-advisor
+version: "1.0.0"
+description: Interactive architecture advisor that surfaces trade-offs and helps humans choose
+cognitive_mode: advisory-guide
+triggers:
+  - manual
+  - on_new_feature
+platforms:
+  - claude-code
+  - gemini-cli
+tools:
+  - Read
+  - Glob
+  - Grep
+  - Bash
+cli:
+  command: harness skill run harness-architecture-advisor
+  args:
+    - name: path
+      description: Project root path
+      required: false
+    - name: topic
+      description: "Architecture topic (e.g., api-design, data-modeling, decomposition)"
+      required: false
+mcp:
+  tool: run_skill
+  input:
+    skill: harness-architecture-advisor
+    path: string
+type: flexible
+phases:
+  - name: discover
+    description: Ask questions about the problem space and constraints
+    required: true
+  - name: analyze
+    description: Research the codebase and identify relevant patterns
+    required: true
+  - name: propose
+    description: Present 2-3 architectural options with trade-offs
+    required: true
+  - name: document
+    description: Write an Architecture Decision Record for the chosen option
+    required: true
+state:
+  persistent: true
+  files:
+    - .harness/architecture/
+depends_on: []