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.config.json

   does not exist, stop and run initialize-harness-project first.

Phase 2: VALIDATE — Check Against Existing Constraints

1. Read the current configuration. Load

   harness.config.json

   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.config.json

   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.config.json

   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.config.json

   • 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.config.json

• 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

Rationalizations to Reject

Rationalization	Why It Is Wrong
"I will add the component and fix any constraint violations later"	Phase 2 requires running harness check-deps for a clean baseline BEFORE adding. Phase 5 requires it to pass AFTER adding.
"AGENTS.md does not need updating for a small internal component"	Phase 4 explicitly requires updating AGENTS.md for every new component. Without it, AI agents have no context.
"The new layer imports are obvious, so I do not need to check for circularity"	Phase 2 checks whether new dependency relationships create circular imports. Circular dependencies are invisible until they cause runtime failures.
"I will commit the config change and the code separately for cleaner history"	The success criteria require a single atomic commit. Splitting creates a window where config references a nonexistent component.

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.config.json — 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.config.json: allow business → infrastructure imports.
  Update AGENTS.md: document infrastructure layer purpose and boundaries.

VERIFY:
  harness validate    # Pass
  harness check-deps  # Pass
  git add harness.config.json 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.config.json 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.config.json — 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.config.json AGENTS.md src/services/notification-service.*
  git commit -m "feat: add notification service to business layer"