@harness-engineering/cli 1.14.0 → 1.16.0

package/dist/agents/commands/codex/harness/initialize-harness-project/SKILL.md

@@ -0,0 +1,235 @@
+<!-- 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/commands/codex/harness/initialize-harness-project/agents/openai.yaml

@@ -0,0 +1,3 @@
+# Reserved for Phase B native integration
+name: initialize-harness-project
+version: "1.0.0"

package/dist/agents/commands/cursor/harness/add-harness-component.mdc

@@ -0,0 +1,200 @@
+---
+description: Add a component to an existing harness project
+alwaysApply: false
+---
+
+<!-- Generated by harness generate-slash-commands. Do not edit. -->
+
+# Add Harness Component
+
+> Add layers, documentation, components, or skills to an existing harness project with proper integration. Validate against existing constraints, wire into architecture, and verify the result.
+
+## When to Use
+
+- Adding a new layer to the project's architecture
+- Adding a new documentation file that harness should track
+- Adding a new component (module, service, package) that must be wired into existing layer boundaries
+- Adding a new skill to the project's skill library
+- When a plan calls for introducing a new architectural boundary or module
+- NOT when initializing a project from scratch (use initialize-harness-project)
+- NOT when modifying an existing component (use standard editing workflows)
+- NOT when removing components (manual process — removing requires careful dependency analysis)
+
+## Process
+
+### Phase 1: DETERMINE — Identify What to Add
+
+1. **Clarify the component type.** Ask if not obvious from context:
+   - **Layer:** A new architectural boundary (e.g., adding an "infrastructure" layer to a project that only has "business" and "data")
+   - **Document:** A documentation file that harness should track for drift detection (e.g., API docs, architecture decision records)
+   - **Component:** A code module, service, or package that lives within an existing layer
+   - **Skill:** A new harness skill definition for the project's workflow
+
+2. **Gather requirements.** For each type:
+   - **Layer:** Name, which directories belong to it, which layers it can import from, which layers can import from it
+   - **Document:** Path, what it documents, which code files it relates to
+   - **Component:** Name, which layer it belongs to, what it depends on, what will depend on it
+   - **Skill:** Name, purpose, type (rigid or flexible), triggers
+
+3. **Check prerequisites.** The project must already be initialized with harness. If `harness.yaml` does not exist, stop and run initialize-harness-project first.
+
+### Phase 2: VALIDATE — Check Against Existing Constraints
+
+1. **Read the current configuration.** Load `harness.yaml` and `AGENTS.md` to understand existing layers, constraints, and architecture.
+
+2. **Verify the new component does not conflict:**
+   - Does the layer name already exist?
+   - Does the component directory already exist?
+   - Would the new dependency relationships create circular imports?
+   - Does the component violate any existing forbidden-import rules?
+
+3. **If conflicts are found,** report them clearly: "Adding layer X would conflict with existing layer Y because [reason]. Options: [A] rename, [B] merge into existing layer, [C] restructure. Which do you prefer?"
+
+4. **Run `harness check-deps`** on the current state to establish a clean baseline. If it already fails, fix existing violations before adding new components.
+
+### Phase 3: ADD — Create the Component
+
+1. **Run `harness add` with appropriate arguments:**
+   - Layer: `harness add layer <name> --dirs <dir1,dir2> --imports <allowed-layers>`
+   - Document: `harness add doc <path> --tracks <related-code-paths>`
+   - Component: `harness add component <name> --layer <layer-name>`
+   - Skill: `harness add skill <name> --type <rigid|flexible>`
+
+2. **Review generated files and configuration changes.** `harness add` modifies `harness.yaml` and may generate template files. Check that the changes look correct.
+
+3. **Create the actual code or content.** `harness add` creates the configuration entry but not necessarily the implementation. Create the directories, files, and initial code as needed.
+
+### Phase 4: WIRE — Integrate into Architecture
+
+1. **Update imports and exports.** If the new component needs to be imported by existing code, add the imports. If existing code needs to be aware of the new layer, update barrel files or index modules.
+
+2. **Update `AGENTS.md`.** Add the new component to the architecture section. Document its purpose, boundaries, and relationships to other components. This keeps agent instructions accurate.
+
+3. **Update layer configuration** if the new component changes dependency relationships. Ensure `harness.yaml` reflects the actual import graph.
+
+4. **For new skills:** Write the `skill.yaml` and `SKILL.md` files following the harness skill format. Use harness-skill-authoring for guidance on writing good skill content.
+
+### Phase 5: VERIFY — Confirm Integration
+
+1. **Run `harness validate`** to verify the full project configuration is still valid after the addition.
+
+2. **Run `harness check-deps`** to verify no dependency violations were introduced. The new component's imports must respect layer boundaries.
+
+### Graph Refresh
+
+If a knowledge graph exists at `.harness/graph/`, refresh it after code changes to keep graph queries accurate:
+
+```
+harness scan [path]
+```
+
+Skipping this step means subsequent graph queries (impact analysis, dependency health, test advisor) may return stale results.
+
+3. **If validation fails,** fix the issues before committing. Common causes:
+   - New layer not properly registered in `harness.yaml`
+   - Component placed in wrong directory for its declared layer
+   - Imports from forbidden layers
+   - `AGENTS.md` references outdated architecture
+
+4. **Commit the addition.** All new and modified files in a single atomic commit.
+
+## Harness Integration
+
+- **`harness add layer <name>`** — Register a new architectural layer with directory mappings and import rules.
+- **`harness add doc <path>`** — Register a documentation file for drift tracking.
+- **`harness add component <name> --layer <layer>`** — Register a new code component within an existing layer.
+- **`harness add skill <name> --type <type>`** — Scaffold a new skill definition.
+- **`harness validate`** — Verify project configuration after the addition.
+- **`harness check-deps`** — Verify dependency constraints are respected after the addition.
+
+## Success Criteria
+
+- The new component is properly registered in `harness.yaml`
+- The component's files exist in the correct directories for its declared layer
+- `AGENTS.md` is updated to reflect the new component
+- `harness validate` passes after the addition
+- `harness check-deps` passes after the addition (no new violations)
+- No circular dependencies were introduced
+- The addition is committed as a single atomic commit
+
+## Examples
+
+### Example: Adding a New Layer
+
+```
+Human: "We need an infrastructure layer for external API clients."
+
+DETERMINE: Adding a layer. Name: infrastructure. Dirs: src/infrastructure/.
+  Imports from: (none — infrastructure is a leaf layer, no internal dependencies).
+  Imported by: business layer (services call external APIs through infrastructure).
+
+VALIDATE:
+  Read harness.yaml — existing layers: presentation, business, data.
+  No conflict with "infrastructure" name.
+  Run: harness check-deps — passes (clean baseline).
+
+ADD:
+  harness add layer infrastructure --dirs src/infrastructure --imports none
+  mkdir -p src/infrastructure
+
+WIRE:
+  Update harness.yaml: allow business → infrastructure imports.
+  Update AGENTS.md: document infrastructure layer purpose and boundaries.
+
+VERIFY:
+  harness validate    # Pass
+  harness check-deps  # Pass
+  git add harness.yaml AGENTS.md src/infrastructure/
+  git commit -m "feat: add infrastructure layer for external API clients"
+```
+
+### Example: Adding a Document for Drift Tracking
+
+```
+Human: "Track our API specification for documentation drift."
+
+DETERMINE: Adding a document. Path: docs/api-spec.md.
+  Tracks: src/routes/, src/models/response.ts.
+
+ADD:
+  harness add doc docs/api-spec.md --tracks src/routes,src/models/response.ts
+
+WIRE:
+  Update AGENTS.md: note that docs/api-spec.md is tracked for drift.
+
+VERIFY:
+  harness validate  # Pass
+  git add harness.yaml AGENTS.md
+  git commit -m "feat: track API spec for documentation drift detection"
+```
+
+### Example: Adding a Component to an Existing Layer
+
+```
+Human: "Add a notification service to the business layer."
+
+DETERMINE: Adding a component. Name: notification-service. Layer: business.
+  Depends on: data layer (notification repository). Depended on by: presentation layer (routes).
+
+VALIDATE:
+  Read harness.yaml — business layer exists, maps to src/services/.
+  No existing notification-service directory.
+  business → data is an allowed import. Presentation → business is allowed.
+  Run: harness check-deps — passes.
+
+ADD:
+  harness add component notification-service --layer business
+  Create src/services/notification-service.ts
+  Create src/services/notification-service.test.ts
+
+WIRE:
+  Add export to src/services/index.ts (if barrel file exists).
+  Update AGENTS.md: add notification service to business layer component list.
+
+VERIFY:
+  harness validate    # Pass
+  harness check-deps  # Pass
+  git add harness.yaml AGENTS.md src/services/notification-service.*
+  git commit -m "feat: add notification service to business layer"
+```
+