@harness-engineering/cli 1.14.0 → 1.16.0

package/dist/agents/commands/cursor/harness/initialize-harness-project.mdc

@@ -0,0 +1,240 @@
+---
+description: Scaffold a new harness-compliant project
+alwaysApply: false
+---
+
+<!-- Generated by harness generate-slash-commands. Do not edit. -->
+
+# Initialize Harness Project
+
+> Scaffold a new harness-compliant project or migrate an existing project to the next adoption level. Assess current state, configure personas, generate AGENTS.md, and validate the result.
+
+## When to Use
+
+- Starting a brand new project that should be harness-managed from day one
+- Migrating an existing project to harness for the first time
+- Upgrading an existing harness project from one adoption level to the next (basic to intermediate, intermediate to advanced)
+- When `on_project_init` triggers fire
+- NOT when the project is already at the desired adoption level (use harness-onboarding to orient instead)
+- NOT when adding a single component to an existing harness project (use add-harness-component)
+- NOT when the project has no clear owner or maintainer — harness setup requires someone to own the constraints
+
+## Process
+
+### Phase 1: ASSESS — Determine Current State
+
+1. **Check for existing harness configuration.** Look for `.harness/` directory, `AGENTS.md`, `harness.yaml`, and any skill definitions. Their presence determines whether this is a new project or a migration.
+
+2. **For new projects:** Gather project context — language, framework, test runner, build tool. Ask the human if any of these are undecided. Do not assume defaults.
+
+2b. **For existing projects with detectable frameworks:** Run `harness init` without flags first. The command auto-detects frameworks (FastAPI, Django, Gin, Axum, Spring Boot, Next.js, React+Vite, Vue, Express, NestJS) by scanning project files. Present the detection result to the human and ask for confirmation before proceeding. If detection fails, ask the human to specify `--framework` manually.
+
+3. **For existing projects:** Run `harness validate` to see what is already configured and what is missing. Read `AGENTS.md` if it exists. Identify the current adoption level:
+   - **Basic:** Has `AGENTS.md` and `harness.yaml` with project metadata. No layers, no skills, no dependency constraints.
+   - **Intermediate:** Has layers defined, dependency constraints between layers, at least one custom skill. `harness check-deps` runs and passes.
+   - **Advanced:** Has full persona configuration, custom skills for the team's workflows, state management, learnings capture, and CI integration for `harness validate`.
+
+4. **Recommend the target adoption level.** For new projects, start with basic unless the team has harness experience. For existing projects, recommend one level up from current. Present the recommendation and wait for confirmation.
+
+### Phase 2: SCAFFOLD — Generate Project Structure
+
+1. **Run `harness init` with the appropriate flags:**
+   - New basic JS/TS project: `harness init --level basic`
+   - With framework: `harness init --level basic --framework <framework>`
+   - Non-JS language: `harness init --language <python|go|rust|java>`
+   - Non-JS with framework: `harness init --framework <fastapi|django|gin|axum|spring-boot>`
+   - Existing project (auto-detect): `harness init` (no flags -- auto-detection runs)
+   - Migration to intermediate: `harness init --level intermediate --migrate`
+   - Migration to advanced: `harness init --level advanced --migrate`
+
+   **Supported frameworks:** nextjs, react-vite, vue, express, nestjs, fastapi, django, gin, axum, spring-boot
+   **Supported languages:** typescript, python, go, rust, java
+
+2. **Review generated files.** `harness init` creates:
+   - `harness.yaml` — Project configuration (name, stack, adoption level)
+   - `.harness/` directory — State and learnings storage
+   - `AGENTS.md` — Agent instructions (template, needs customization)
+   - Layer definitions (intermediate and above)
+   - Dependency constraints (intermediate and above)
+
+3. **Do not blindly accept generated content.** Read the generated `AGENTS.md` and `harness.yaml`. Flag anything that looks wrong or incomplete. The scaffolded output is a starting point, not a finished product.
+
+### Phase 3: CONFIGURE — Customize for the Project
+
+1. **Configure personas.** Run `harness persona generate` to create persona definitions based on the project's stack and team structure. Personas define how agents should behave in this project — coding style, communication preferences, constraint strictness.
+
+2. **Customize AGENTS.md.** The generated template needs project-specific content:
+   - Project description and purpose
+   - Architecture overview (components, layers, data flow)
+   - Key conventions the team follows
+   - Known constraints and forbidden patterns
+   - Links to relevant documentation
+
+3. **For intermediate and above:** Define layer boundaries. Which modules belong to which layers? What are the allowed import directions? Document these in `harness.yaml` and ensure they match the actual codebase structure.
+
+4. **For advanced:** Configure state management (`.harness/state.json` schema), learnings capture (`.harness/learnings.md` conventions), and CI integration hooks.
+
+5. **Configure i18n (all levels).** Ask: "Will this project support multiple languages?" Based on the answer:
+   - **Yes:** Invoke `harness-i18n-workflow` configure phase to set up i18n config in `harness.config.json` (source locale, target locales, framework, strictness). Then invoke `harness-i18n-workflow` scaffold phase to create translation file structure and extraction config. Set `i18n.enabled: true`.
+   - **No:** Set `i18n.enabled: false` in `harness.config.json`. The `harness-i18n-process` skill will still fire gentle prompts for unconfigured projects when features touch user-facing strings.
+   - **Not sure yet:** Skip i18n configuration entirely. Do not set `i18n.enabled`. The project can enable i18n later by running `harness-i18n-workflow` directly.
+
+### Phase 4: VALIDATE — Confirm Everything Works
+
+1. **Run `harness validate`** to verify the full configuration. This checks:
+   - `harness.yaml` schema validity
+   - `AGENTS.md` presence and required sections
+   - Layer definitions (if intermediate+)
+   - Dependency constraints (if intermediate+)
+   - Persona configuration (if configured)
+
+2. **Fix any validation errors before finishing.** Do not leave the project in a half-configured state.
+
+3. **Run `harness check-deps`** (intermediate and above) to verify dependency constraints match the actual codebase. If there are violations, decide with the human: update the constraints or fix the code.
+
+### Build the Initial Knowledge Graph
+
+If the project will use graph-based queries, build the initial knowledge graph now:
+
+```
+harness scan [path]
+```
+
+This creates the `.harness/graph/` directory and populates it with the project's dependency and relationship data. Subsequent graph queries (impact analysis, dependency health, test advisor) depend on this initial scan.
+
+4. **Mention roadmap.** After validation passes, inform the user: "When you are ready to set up a project roadmap, run `/harness:roadmap --create`. This creates a unified `docs/roadmap.md` that tracks features, milestones, and status across your specs and plans." This is informational only — do not create the roadmap automatically.
+
+5. **Commit the initialization.** All generated and configured files in a single commit.
+
+## Harness Integration
+
+- **`harness init --level <level> [--framework <framework>] [--language <language>]`** — Scaffold a new project. `--framework` infers language automatically. `--language` without `--framework` gives a bare language scaffold. Running without flags on an existing project directory triggers auto-detection.
+- **`harness init --level <level> --migrate`** — Migrate an existing project to the next adoption level, preserving existing configuration.
+- **`harness persona generate`** — Generate persona definitions based on project stack and team structure.
+- **`harness validate`** — Verify the full project configuration is valid and complete.
+- **`harness check-deps`** — Verify dependency constraints match the actual codebase (intermediate and above).
+- **`harness-i18n-workflow configure` + `harness-i18n-workflow scaffold`** — Invoked during Phase 3 if the project will support multiple languages. Sets up i18n configuration and translation file structure.
+- **Roadmap nudge** — After successful initialization, inform the user about `/harness:roadmap --create` for setting up project-level feature tracking. Informational only; does not create the roadmap.
+
+## Success Criteria
+
+- `harness.yaml` exists and passes schema validation
+- `AGENTS.md` exists with project-specific content (not just the template)
+- `.harness/` directory exists with appropriate state files
+- `harness validate` passes with zero errors
+- `harness check-deps` passes (intermediate and above)
+- Personas are configured if the project uses them
+- The adoption level matches what was agreed upon with the human
+- All generated files are committed in a single atomic commit
+- i18n configuration is set if the human chose to enable it during init
+
+## Examples
+
+### Example: New TypeScript Project (Basic Level)
+
+**ASSESS:**
+
+```
+Human: "I'm starting a new TypeScript API project using Express and Vitest."
+Check for .harness/ — not found. This is a new project.
+Recommend: basic level (new project, start simple).
+Human confirms: "Basic is fine for now."
+```
+
+**SCAFFOLD:**
+
+```bash
+harness init --level basic --framework express
+# Creates: harness.yaml, .harness/, AGENTS.md (template)
+```
+
+**CONFIGURE:**
+
+```
+Edit AGENTS.md:
+  - Add project description: "REST API for widget management"
+  - Add stack: TypeScript, Express, Vitest, PostgreSQL
+  - Add conventions: "Use zod for validation, repository pattern for data access"
+  - Add constraints: "No direct SQL queries outside repository layer"
+  - Ask: "Will this project support multiple languages?"
+  - Human: "Yes, Spanish and French."
+  - Run harness-i18n-workflow configure (source: en, targets: es, fr)
+  - Run harness-i18n-workflow scaffold (creates locales/ directory structure)
+```
+
+**VALIDATE:**
+
+```bash
+harness validate  # Pass — basic level checks satisfied
+git add harness.yaml .harness/ AGENTS.md
+git commit -m "feat: initialize harness project at basic level"
+```
+
+### Example: Migrating Existing Project from Basic to Intermediate
+
+**ASSESS:**
+
+```
+Read harness.yaml — level: basic
+Read AGENTS.md — exists, has project-specific content
+Run: harness validate — passes at basic level
+Recommend: intermediate (add layers and dependency constraints)
+Human confirms: "Yes, we're ready for layers."
+```
+
+**SCAFFOLD:**
+
+```bash
+harness init --level intermediate --migrate
+# Preserves existing harness.yaml and AGENTS.md
+# Adds: layer definitions template, dependency constraints template
+```
+
+**CONFIGURE:**
+
+```
+Define layers in harness.yaml:
+  - presentation: src/routes/, src/middleware/
+  - business: src/services/, src/models/
+  - data: src/repositories/, src/db/
+
+Define constraints:
+  - presentation → business (allowed)
+  - business → data (allowed)
+  - data → presentation (forbidden)
+  - presentation → data (forbidden — must go through business)
+
+Update AGENTS.md with layer documentation.
+```
+
+**VALIDATE:**
+
+```bash
+harness validate      # Pass — intermediate level checks satisfied
+harness check-deps    # Pass — no constraint violations in existing code
+git add -A
+git commit -m "feat: migrate harness project to intermediate level with layers"
+```
+
+### Example: Adoption Level Progression
+
+**Basic (start here):**
+
+- `AGENTS.md` with project context
+- `harness.yaml` with metadata
+- `harness validate` runs in development
+
+**Intermediate (add structure):**
+
+- Layer definitions and boundaries
+- Dependency constraints enforced by `harness check-deps`
+- At least one custom skill for team workflows
+
+**Advanced (full integration):**
+
+- Persona configuration for consistent agent behavior
+- State management across sessions
+- `.harness/learnings.md` capturing institutional knowledge
+- `harness validate` runs in CI pipeline
+- Custom skills for all common team workflows
+

package/dist/agents/skills/claude-code/enforce-architecture/SKILL.md

@@ -236,6 +236,58 @@ These are hard stops. Architecture violations are not warnings — they are erro
 - **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.
 
+## Evidence Requirements
+
+When this skill makes claims about existing code, architecture, or behavior,
+it MUST cite evidence using one of:
+
+1. **File reference:** `file:line` format (e.g., `src/auth.ts:42`)
+2. **Code pattern reference:** `file` with description (e.g., `src/utils/hash.ts` —
+   "existing bcrypt wrapper")
+3. **Test/command output:** Inline or referenced output from a test run or CLI command
+4. **Session evidence:** Write to the `evidence` session section via `manage_state`
+
+**Uncited claims:** Technical assertions without citations MUST be prefixed with
+`[UNVERIFIED]`. Example: `[UNVERIFIED] The auth middleware supports refresh tokens`.
+
+## Red Flags
+
+### Universal
+
+These apply to ALL skills. If you catch yourself doing any of these, STOP.
+
+- **"I believe the codebase does X"** — Stop. Read the code and cite a file:line
+  reference. Belief is not evidence.
+- **"Let me recommend [pattern] for this"** without checking existing patterns — Stop.
+  Search the codebase first. The project may already have a convention.
+- **"While we're here, we should also [unrelated improvement]"** — Stop. Flag the idea
+  but do not expand scope beyond the stated task.
+
+### Domain-Specific
+
+- **"Auto-fixing this import to use the correct layer"** without verifying the replacement module exists — Stop. Verify the target exists and exports the needed symbol before rewriting an import.
+- **"This file is in a test directory, skipping violation"** — Stop. Test directories have architectural rules too. Check the constraint definition before assuming tests are exempt.
+- **"Removing this circular dependency by moving the import"** without tracing downstream effects — Stop. Moving imports can break consumers. Trace the dependency chain first.
+- **"This violation is from generated code, ignoring"** — Stop. Generated files can still violate architecture if the generator is misconfigured. Check the source template.
+
+## Rationalizations to Reject
+
+### Universal
+
+These reasoning patterns sound plausible but lead to bad outcomes. Reject them.
+
+- **"It's probably fine"** — "Probably" is not evidence. Verify before asserting.
+- **"This is best practice"** — Best practice in what context? Cite the source and
+  confirm it applies to this codebase.
+- **"We can fix it later"** — If it is worth flagging, it is worth documenting now
+  with a concrete follow-up plan.
+
+### Domain-Specific
+
+- **"The violation is minor — just one import"** — One violation sets a precedent. Enforce the constraint or document an explicit exception with rationale.
+- **"It works, so the architecture must be fine"** — Working code with bad architecture is technical debt with compound interest. Correct function does not excuse structural violations.
+- **"This is a legacy module, different rules apply"** — Legacy does not mean exempt. Either the constraint applies or it needs an explicit documented exception.
+
 ## 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.

package/dist/agents/skills/claude-code/harness-api-design/SKILL.md

@@ -296,6 +296,58 @@ enum NotificationType {
 - **Generated specs must be valid.** The OpenAPI spec must pass structural validation. The GraphQL schema must parse without errors. Proto files must compile with `protoc`. An invalid spec is worse than no spec.
 - **Naming conventions must be consistent.** WHERE the project uses a naming convention (detected in phase 1), THEN all new endpoints must follow it. A single inconsistent name pollutes the entire API surface.
 
+## Evidence Requirements
+
+When this skill makes claims about existing code, architecture, or behavior,
+it MUST cite evidence using one of:
+
+1. **File reference:** `file:line` format (e.g., `src/auth.ts:42`)
+2. **Code pattern reference:** `file` with description (e.g., `src/utils/hash.ts` —
+   "existing bcrypt wrapper")
+3. **Test/command output:** Inline or referenced output from a test run or CLI command
+4. **Session evidence:** Write to the `evidence` session section via `manage_state`
+
+**Uncited claims:** Technical assertions without citations MUST be prefixed with
+`[UNVERIFIED]`. Example: `[UNVERIFIED] The auth middleware supports refresh tokens`.
+
+## Red Flags
+
+### Universal
+
+These apply to ALL skills. If you catch yourself doing any of these, STOP.
+
+- **"I believe the codebase does X"** — Stop. Read the code and cite a file:line
+  reference. Belief is not evidence.
+- **"Let me recommend [pattern] for this"** without checking existing patterns — Stop.
+  Search the codebase first. The project may already have a convention.
+- **"While we're here, we should also [unrelated improvement]"** — Stop. Flag the idea
+  but do not expand scope beyond the stated task.
+
+### Domain-Specific
+
+- **"Adding this required field to the existing endpoint"** — Stop. Adding required fields to existing endpoints breaks all current consumers. Make it optional or version the endpoint.
+- **"Changing the response shape to be cleaner"** — Stop. Changing response shape without versioning is a breaking change. Existing consumers depend on the current structure.
+- **"Returning the full object for convenience"** — Stop. Over-fetching exposes unnecessary data and increases payload size. Return only what the consumer needs.
+- **"We don't need pagination for this endpoint"** — Stop. Lists without pagination become production incidents at scale. Add pagination from the start.
+
+## Rationalizations to Reject
+
+### Universal
+
+These reasoning patterns sound plausible but lead to bad outcomes. Reject them.
+
+- **"It's probably fine"** — "Probably" is not evidence. Verify before asserting.
+- **"This is best practice"** — Best practice in what context? Cite the source and
+  confirm it applies to this codebase.
+- **"We can fix it later"** — If it is worth flagging, it is worth documenting now
+  with a concrete follow-up plan.
+
+### Domain-Specific
+
+- **"It's an internal API, breaking changes are fine"** — Internal consumers break too. Version the change or coordinate the migration explicitly.
+- **"The field name is obvious enough"** — API field names are a public contract. Follow existing naming conventions and document the semantics.
+- **"Nobody uses that endpoint anyway"** — Verify with access logs or usage data. Assumptions about usage without evidence lead to silent breakages.
+
 ## Escalation
 
 - **No existing conventions detected:** When the project has no existing API endpoints and no spec file, the skill cannot infer conventions. Report: "No existing API conventions found. Provide a style guide or approve the defaults (plural nouns, kebab-case paths, RFC 7807 errors, cursor pagination) before proceeding."

package/dist/agents/skills/claude-code/harness-architecture-advisor/SKILL.md

@@ -273,6 +273,58 @@ Also link from the project's ADR index if one exists.
 - **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.
 
+## Evidence Requirements
+
+When this skill makes claims about existing code, architecture, or behavior,
+it MUST cite evidence using one of:
+
+1. **File reference:** `file:line` format (e.g., `src/auth.ts:42`)
+2. **Code pattern reference:** `file` with description (e.g., `src/utils/hash.ts` —
+   "existing bcrypt wrapper")
+3. **Test/command output:** Inline or referenced output from a test run or CLI command
+4. **Session evidence:** Write to the `evidence` session section via `manage_state`
+
+**Uncited claims:** Technical assertions without citations MUST be prefixed with
+`[UNVERIFIED]`. Example: `[UNVERIFIED] The auth middleware supports refresh tokens`.
+
+## Red Flags
+
+### Universal
+
+These apply to ALL skills. If you catch yourself doing any of these, STOP.
+
+- **"I believe the codebase does X"** — Stop. Read the code and cite a file:line
+  reference. Belief is not evidence.
+- **"Let me recommend [pattern] for this"** without checking existing patterns — Stop.
+  Search the codebase first. The project may already have a convention.
+- **"While we're here, we should also [unrelated improvement]"** — Stop. Flag the idea
+  but do not expand scope beyond the stated task.
+
+### Domain-Specific
+
+- **"You should introduce an abstraction layer here"** without checking duplication metrics — Stop. Abstractions are justified by measured duplication or coupling, not intuition.
+- **"This module is getting too large"** without checking line counts or complexity scores — Stop. "Too large" needs a number. Query the graph or count lines before asserting.
+- **"Consider migrating to [technology]"** without a cost-benefit analysis — Stop. Migration advice without concrete tradeoffs is harmful.
+- **"The architecture would be cleaner if..."** — Stop. "Cleaner" is subjective. State the specific quality attribute that improves (testability, deployability, coupling) and cite evidence.
+
+## Rationalizations to Reject
+
+### Universal
+
+These reasoning patterns sound plausible but lead to bad outcomes. Reject them.
+
+- **"It's probably fine"** — "Probably" is not evidence. Verify before asserting.
+- **"This is best practice"** — Best practice in what context? Cite the source and
+  confirm it applies to this codebase.
+- **"We can fix it later"** — If it is worth flagging, it is worth documenting now
+  with a concrete follow-up plan.
+
+### Domain-Specific
+
+- **"This will be easier to maintain"** — Easier for whom, and compared to what? Cite the maintenance burden with evidence from the codebase.
+- **"It's the modern approach"** — Modernity is not a design criterion. Fitness for purpose is. State the specific benefit.
+- **"Other teams do it this way"** — Other teams have different constraints. Evaluate the option on this codebase's specific merits.
+
 ## 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.

package/dist/agents/skills/claude-code/harness-auth/SKILL.md

@@ -271,6 +271,58 @@ Phase 4: VALIDATE
 - **No plaintext or weakly hashed passwords.** MD5, SHA-1, or unsalted SHA-256 for password storage is a blocking finding. Passwords must use bcrypt (cost 12+), scrypt, or argon2id.
 - **No authorization checks skipped at the API layer.** UI-only authorization is not authorization. Every API endpoint that serves user-specific or role-restricted data must enforce permissions server-side.
 
+## Evidence Requirements
+
+When this skill makes claims about existing code, architecture, or behavior,
+it MUST cite evidence using one of:
+
+1. **File reference:** `file:line` format (e.g., `src/auth.ts:42`)
+2. **Code pattern reference:** `file` with description (e.g., `src/utils/hash.ts` —
+   "existing bcrypt wrapper")
+3. **Test/command output:** Inline or referenced output from a test run or CLI command
+4. **Session evidence:** Write to the `evidence` session section via `manage_state`
+
+**Uncited claims:** Technical assertions without citations MUST be prefixed with
+`[UNVERIFIED]`. Example: `[UNVERIFIED] The auth middleware supports refresh tokens`.
+
+## Red Flags
+
+### Universal
+
+These apply to ALL skills. If you catch yourself doing any of these, STOP.
+
+- **"I believe the codebase does X"** — Stop. Read the code and cite a file:line
+  reference. Belief is not evidence.
+- **"Let me recommend [pattern] for this"** without checking existing patterns — Stop.
+  Search the codebase first. The project may already have a convention.
+- **"While we're here, we should also [unrelated improvement]"** — Stop. Flag the idea
+  but do not expand scope beyond the stated task.
+
+### Domain-Specific
+
+- **"Let's store the token in localStorage for convenience"** — Stop. localStorage is accessible to XSS. Use httpOnly cookies or secure server-side storage.
+- **"We can use a simple hash for passwords"** — Stop. Passwords require slow hashing (bcrypt, scrypt, argon2id). Fast hashes like MD5/SHA are crackable in seconds.
+- **"Let's implement our own JWT validation"** — Stop. Use a vetted library. Custom crypto is a known source of vulnerabilities.
+- **"The session expiry is just a UX concern"** — Stop. Session management is a security control. Timeout values are security-relevant configuration.
+
+## Rationalizations to Reject
+
+### Universal
+
+These reasoning patterns sound plausible but lead to bad outcomes. Reject them.
+
+- **"It's probably fine"** — "Probably" is not evidence. Verify before asserting.
+- **"This is best practice"** — Best practice in what context? Cite the source and
+  confirm it applies to this codebase.
+- **"We can fix it later"** — If it is worth flagging, it is worth documenting now
+  with a concrete follow-up plan.
+
+### Domain-Specific
+
+- **"No one would guess this token format"** — Security by obscurity. Tokens must be cryptographically secure regardless of format predictability.
+- **"This is an internal service, auth is less critical"** — Internal services are lateral movement targets. Authenticate all service boundaries.
+- **"The frontend validates permissions, so the backend doesn't need to"** — Client-side checks are bypassable. Server-side authorization is the only real enforcement.
+
 ## Escalation
 
 - **When the auth architecture requires a fundamental redesign:** Report: "The current auth implementation has [N] high-severity findings that require architectural changes (e.g., switching from localStorage tokens to httpOnly cookies). This is not a patch — recommend a dedicated auth migration sprint with a rollback plan."