@harness-engineering/cli 1.14.0 → 1.16.0

package/dist/agents/skills/cursor/initialize-harness-project/SKILL.md

@@ -0,0 +1,232 @@
+# 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/cursor/initialize-harness-project/skill.yaml

@@ -0,0 +1,32 @@
+name: initialize-harness-project
+version: "1.0.0"
+description: Scaffold a new harness-compliant project
+cognitive_mode: constructive-architect
+triggers:
+  - manual
+  - on_project_init
+platforms:
+  - claude-code
+  - gemini-cli
+tools:
+  - Bash
+  - Read
+  - Write
+  - Glob
+cli:
+  command: harness skill run initialize-harness-project
+  args:
+    - name: path
+      description: Project root path
+      required: false
+mcp:
+  tool: run_skill
+  input:
+    skill: initialize-harness-project
+    path: string
+type: flexible
+tier: 1
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/cursor/validate-context-engineering/SKILL.md

@@ -0,0 +1,150 @@
+# Validate Context Engineering
+
+> Validate AGENTS.md quality and evolve it as the codebase changes. Good context engineering means AI agents always have accurate, current knowledge about the project.
+
+## When to Use
+
+- After adding new files, modules, or packages to the project
+- After renaming, moving, or deleting significant files
+- After changing public APIs, architectural patterns, or conventions
+- When onboarding a new contributor (human or AI) and want to verify context is current
+- When `on_context_check` or `on_pre_commit` triggers fire
+- Periodically (weekly or per-sprint) as a hygiene check
+- NOT when making trivial changes (typo fixes, comment updates, formatting)
+- NOT during active feature development — run this between features or at cycle boundaries
+
+## Process
+
+### Phase 1: Audit — Run Automated Checks
+
+1. **Run `harness validate`** to check overall project health. Review any context-related warnings or errors in the output.
+
+2. **Run `harness check-docs`** to detect documentation gaps, broken links, and stale references. Capture the full output for analysis.
+
+3. **Review AGENTS.md manually.** Automated tools catch structural issues but miss semantic drift. Read each section and ask: "Is this still true?"
+
+### Graph-Enhanced Context (when available)
+
+When a knowledge graph exists at `.harness/graph/`, use graph queries for faster, more accurate auditing:
+
+- `query_graph` — find all undocumented code nodes (file nodes without `documents` edges), replacing manual cross-referencing
+- `search_similar` — detect stale references in AGENTS.md by matching section text against current code entities
+
+When a graph is available, it IS the source of truth for documentation coverage. Drift = stale or missing edges between code and doc nodes. Fall back to file-based commands if no graph is available.
+
+### Pipeline Context (when orchestrated)
+
+When invoked by `harness-docs-pipeline`, check for a `pipeline` field in `.harness/handoff.json`:
+
+- If `pipeline` field exists: read `DocPipelineContext` from it
+  - Use `pipeline.exclusions` to skip findings that were already addressed in the FIX phase
+  - Write `GapFinding[]` results back to `pipeline.gapFindings` in handoff.json
+  - This enables dedup across FIX and AUDIT phases
+- If `pipeline` field does not exist: behave exactly as today (standalone mode)
+
+No changes to the skill's interface or output format — the pipeline field is purely additive.
+
+### Phase 2: Detect Gaps
+
+Categorize findings into four types:
+
+1. **Undocumented files.** New source files, modules, or packages that are not mentioned in AGENTS.md or any knowledge map section. These are the highest priority — an AI agent encountering these files has no context.
+
+2. **Broken links.** References to files, functions, or URLs that no longer exist. These actively mislead agents.
+
+3. **Stale sections.** Content that was accurate when written but no longer reflects reality. Examples: renamed functions still referenced by old name, removed features still described, changed conventions not updated.
+
+4. **Missing context.** Sections that exist but lack critical information. A module is listed but its purpose, constraints, or relationships are not explained. An AI agent can find the file but does not understand why it exists or how to use it correctly.
+
+### Phase 3: Suggest Updates
+
+For each gap, generate a specific suggestion:
+
+- **Undocumented files:** Draft a new section or entry with the file path, purpose, key exports, and relationship to existing modules. Use the existing AGENTS.md style and structure.
+- **Broken links:** Identify the correct target (renamed file, moved function) or recommend removal if the target was deleted.
+- **Stale sections:** Draft replacement text that reflects current reality. Show the diff between old and new.
+- **Missing context:** Draft additional content that fills the gap. Focus on what an AI agent needs to know: purpose, constraints, relationships, and gotchas.
+
+### Phase 4: Apply with Approval
+
+1. **Present all suggestions as a grouped list.** Organize by section of AGENTS.md for easy review.
+
+2. **Apply approved changes.** Update AGENTS.md with the approved suggestions. Preserve existing formatting and style.
+
+3. **Re-run `harness check-docs`** to verify all fixes are clean. No new issues should be introduced.
+
+4. **Commit the update.** Use a descriptive commit message that summarizes what was updated and why.
+
+## What Makes Good AGENTS.md Content
+
+Good context engineering treats AGENTS.md as a **dynamic knowledge base**, not a static document.
+
+- **Accuracy over completeness.** A small, accurate AGENTS.md is better than a comprehensive but stale one. Every statement must be verifiable against the current codebase.
+- **Purpose-first descriptions.** Do not just list files. Explain WHY each module exists, what problem it solves, and what constraints apply to it.
+- **Relationship mapping.** Show how modules connect. Which modules depend on which? What are the boundaries? An agent reading one section should understand how it fits into the whole.
+- **Gotchas and constraints.** Document the non-obvious. What will break if someone does X? What patterns must be followed? What is forbidden and why?
+- **Change-friendly structure.** Organize so that adding a new module means adding one section, not updating ten places. Use consistent formatting so automated tools can parse it.
+- **Actionable guidance.** Every section should help an agent make correct decisions. "This module handles authentication" is less useful than "This module handles authentication. All auth changes must go through the AuthService class. Direct database access for auth data is forbidden — use the repository layer."
+
+## Harness Integration
+
+- **`harness validate`** — Full project health check. Reports context gaps as part of overall validation.
+- **`harness check-docs`** — Focused documentation audit. Detects broken links, missing references, stale sections, and undocumented files.
+- **`harness fix-drift`** — Auto-fix simple drift issues (broken links, renamed references). Use after manual review confirms the fixes are correct.
+
+## Success Criteria
+
+- `harness check-docs` passes with zero errors and zero warnings
+- Every source file that contains public API or architectural significance is referenced in AGENTS.md
+- All file paths and function names in AGENTS.md match the current codebase
+- All links (internal and external) resolve correctly
+- AGENTS.md sections accurately describe current module purposes, constraints, and relationships
+- A new AI agent reading AGENTS.md can navigate the codebase and make correct decisions without additional guidance
+
+## Examples
+
+### Example: New module added but not documented
+
+**Audit output from `harness check-docs`:**
+
+```
+WARNING: Undocumented file detected: src/services/notification-service.ts
+  - File contains 3 public exports: NotificationService, NotificationType, sendNotification
+  - File is imported by 4 other modules
+  - No AGENTS.md section references this file
+```
+
+**Suggested update:**
+
+```markdown
+### Notification Service (`src/services/notification-service.ts`)
+
+Handles all outbound notifications (email, Slack, webhook). All notification delivery
+must go through `NotificationService` — direct use of transport libraries (nodemailer,
+Slack SDK) outside this module is forbidden.
+
+- `NotificationType` — enum of supported notification channels
+- `sendNotification()` — primary entry point; routes to the correct transport
+- Requires `NOTIFICATION_CONFIG` environment variables to be set
+- Respects rate limits defined in `harness.config.json` under `notifications`
+```
+
+**Apply:** Add the section under the Services heading in AGENTS.md. Re-run `harness check-docs` to confirm the warning is resolved.
+
+### Example: Renamed function still referenced by old name
+
+**Audit output:**
+
+```
+ERROR: Broken reference in AGENTS.md line 47: `calculateShipping()`
+  - Function was renamed to `computeShippingCost()` in commit abc123
+  - Located in src/services/shipping.ts
+```
+
+**Fix:** Replace `calculateShipping()` with `computeShippingCost()` in AGENTS.md. Verify no other references to the old name exist.
+
+## Escalation
+
+- **When AGENTS.md is severely outdated (>20 issues):** Do not attempt to fix everything at once. Prioritize: broken links first, then undocumented public APIs, then stale descriptions. Batch the work across multiple commits.
+- **When you are unsure whether a section is stale:** Check git blame for the section and compare against recent changes to the referenced files. If the section has not been updated since the referenced files changed, it is likely stale.
+- **When the project has no AGENTS.md:** Escalate to the human. Creating an AGENTS.md from scratch is a significant decision about project structure and should be done intentionally, not automatically.

package/dist/agents/skills/cursor/validate-context-engineering/skill.yaml

@@ -0,0 +1,32 @@
+name: validate-context-engineering
+version: "1.0.0"
+description: Validate repository context engineering practices (AGENTS.md, doc coverage, knowledge map)
+cognitive_mode: meticulous-verifier
+triggers:
+  - manual
+  - on_pr
+  - on_commit
+platforms:
+  - claude-code
+  - gemini-cli
+tools:
+  - Bash
+  - Read
+  - Glob
+cli:
+  command: harness skill run validate-context-engineering
+  args:
+    - name: path
+      description: Project root path
+      required: false
+mcp:
+  tool: run_skill
+  input:
+    skill: validate-context-engineering
+    path: string
+type: flexible
+internal: true
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/gemini-cli/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/gemini-cli/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/gemini-cli/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.