From harness-claude
Adds layers, documentation, components, or skills to existing harness projects. Validates against constraints, wires into architecture, and verifies results.
npx claudepluginhub intense-visions/harness-engineering --plugin harness-claudeThis skill uses the workspace's default tool permissions.
> 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.
Scaffolds new harness-compliant projects, migrates existing to higher adoption levels, bootstraps plugin-only installs. Assesses state, configures, validates, instruments baselines/telemetry.
Bootstraps repositories with harness engineering scaffolding: AGENTS.md orientation map, docs/ system of record, boundary tests, linter rules, CI pipeline, GC scripts. Use for new projects, agent-readiness, or architecture boundaries.
Sets up or updates agent-first engineering harness for repositories with AGENTS.md maps, docs structure, architecture boundaries, .harness rules, and quality scoring. Use to make repos AI agent-ready or audit readiness.
Share bugs, ideas, or general feedback.
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.
Clarify the component type. Ask if not obvious from context:
Gather requirements. For each type:
Check prerequisites. The project must already be initialized with harness. If harness.config.json does not exist, stop and run initialize-harness-project first.
Read the current configuration. Load harness.config.json and AGENTS.md to understand existing layers, constraints, and architecture.
Verify the new component does not conflict:
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?"
Run harness check-deps on the current state to establish a clean baseline. If it already fails, fix existing violations before adding new components.
Run harness add with appropriate arguments:
harness add layer <name> --dirs <dir1,dir2> --imports <allowed-layers>harness add doc <path> --tracks <related-code-paths>harness add component <name> --layer <layer-name>harness add skill <name> --type <rigid|flexible>Review generated files and configuration changes. harness add modifies harness.config.json and may generate template files. Check that the changes look correct.
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.
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.
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.
Update layer configuration if the new component changes dependency relationships. Ensure harness.config.json reflects the actual import graph.
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.
Run harness validate to verify the full project configuration is still valid after the addition.
Run harness check-deps to verify no dependency violations were introduced. The new component's imports must respect layer boundaries.
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.
If validation fails, fix the issues before committing. Common causes:
harness.config.jsonAGENTS.md references outdated architectureCommit the addition. All new and modified files in a single atomic commit.
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.harness.config.jsonAGENTS.md is updated to reflect the new componentharness validate passes after the additionharness check-deps passes after the addition (no new violations)| 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. |
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"
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"
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"