frontend-harness

frontend-harness is an Execution Policy Layer for frontend teams using Codex or Claude Code.

It does not replace the agent runtime. Codex and Claude Code already provide the loop, tool execution, context handling, permissions, retries, subagents, and skill loading. frontend-harness adds the project-level rules those agents should follow inside a frontend repository.

The product goal is simple:

install once -> inject AGENTS.md / CLAUDE.md -> work normally with AI

After initialization, team members should not need to manually run the harness loop. They keep asking Codex or Claude Code for frontend work in plain language. The injected project protocol and built-in project skills tell the agent how to plan, edit, verify, and repair.

What It Does

frontend-harness gives a project a deterministic execution contract:

context -> plan -> implement -> record changes -> verify -> repair -> done

The CLI exists mainly as a protocol API for AI agents. Humans use it to install, initialize, and occasionally check health.

What It Is Not

frontend-harness is not another agent platform.

It should not rebuild:

• agent loops
• generic tool execution
• permission systems
• subagent orchestration
• long-running runtime launchers or supervised agent wrappers
• replacement workflows for Codex or Claude Code

Those belong to the official agent runtimes. This package owns only the frontend project policy around them.

Install

npm install frontend-harness --save-dev

Add the project-local harness scripts to package.json:

{
  "scripts": {
    "harness": "frontend-harness",
    "harness:init": "frontend-harness init",
    "harness:check": "frontend-harness protocol check",
    "harness:clean": "frontend-harness clean --json"
  }
}

Use the project scripts from package.json to run harness commands. Initialize the harness protocol after the scripts are in place:

npm run harness:init

In this source checkout, use npm run harness -- ... unless the package has intentionally been installed or linked.

Create a New Vue Project

From any directory with Node.js/npm available, run:

npx frontend-harness scaffold --preset vue --target my-vue-app
cd my-vue-app
npm install
npm run harness:init

The scaffold command creates the Vue project with frontend-harness in devDependencies and project-local harness scripts in package.json. After dependencies are installed, npm run harness:init injects the agent protocol into the generated project.

Use these project scripts in the generated project:

npm run harness:init
npm run harness:check
npm run harness:clean
npm run harness -- context --json
npm run harness -- verify --json

init injects managed protocol blocks into:

• AGENTS.md
• CLAUDE.md

It also scaffolds built-in project skills under .frontend-harness/skills/:

• frontend-discovery.md
• architecture-boundary.md
• ui-implementation.md
• prd-knowledge.md
• api-integration.md
• form-workflow.md
• frontend-test.md
• bug-fix.md
• requirement-change.md
• frontend-change-review.md
• git-commit.md

Existing project skill files are preserved. Rerun init after package upgrades to add newly introduced built-in skills. The built-in git commit skill uses <type>(<scope>): <short description> with feat, fix, docs, style, refactor, perf, test, or chore.

Once those files are present, the normal team workflow is:

Open Codex or Claude Code.
Ask for the frontend change.
Let the injected protocol drive planning, verification, and repair.

Human Commands

Most team members only need these commands.

npm run harness:init
npm run harness -- init --json
npm run harness -- init --dry-run --json
npm run harness -- init --check --json
npm run harness:check
npm run harness -- protocol check --json
npx frontend-harness scaffold --preset vue --target my-vue-app
npx frontend-harness scaffold --preset vue --target my-vue-app --dry-run --json
npm run harness:clean

Use init after installation or package upgrades. Use protocol check when you want to verify that AGENTS.md and CLAUDE.md are current. Use clean to remove ignored runtime artifacts while preserving durable project skills, knowledge, and config.

scaffold --preset vue creates a Vue 3 + Vite + TypeScript engineering baseline inspired by the company freight-admin stack. It includes Vite config, ESLint/Prettier, Element Plus auto imports, and small utils, storage, and service layers. It intentionally does not create admin pages, routes, dashboards, permissions, or business components.

UI restoration work treats design exports, screenshots, and generated code as source evidence for implementation and loop repair, not as paperwork to backfill after coding. For design-backed restoration, visual equivalence is the highest priority for the first project implementation: source material does not mean the agent may redesign the screen. When design_to_code or generated design markup is available, preserve it, localize temporary assets, and classify whether it is usable_as_source, usable_as_visual_baseline, usable_for_patch_reference, or unusable before deciding whether it can seed implementation or only guide repair; verify enforces that classification through visual-baseline metadata for design_to_code sources. Project-native rewrites may change file placement, framework integration, semantic markup, asset localization, naming, state wiring, and component boundaries only when the rendered result preserves the design's primary layout, spacing, typography, color, density, hierarchy, and visible states. When a design contains images, classify each one as required content, functional UI element, brand/product asset, decorative sample, or replaceable placeholder before implementation. Required images should become durable assets; decorative samples and placeholders should be replaced or documented in design evidence. Final handoff evidence should include a restoration verdict with score or pass/fail judgement, key visual differences, accepted gaps, and links to evidence artifacts. Component splits should follow semantic responsibility, reuse, and interaction boundaries rather than mirroring every design layer as a component.

Agent Protocol Commands

These commands are intended for Codex / Claude Code through the injected protocol:

npm run harness -- context --json
npm run harness -- proposal check --json --file <agent-proposal.json>
npm run harness -- plan --json "<task>"
npm run harness -- plan --json "<task>" --prd <prd-file> --ui-source <ui-artifact-or-design-url>
npm run harness -- plan --json "<task>" --agent-proposal <agent-proposal.json>
npm run harness -- state record-change <file>
npm run harness -- state record-change --from-git
npm run harness -- state check --json
npm run harness -- verify --json
npm run harness -- repair packet --json
npm run harness -- state next --json
npm run harness -- state explain --json

The agent should call them automatically while doing work. They persist state under .frontend-harness/ and provide deterministic evidence for each step.

state check --json verifies that recorded changed files cover the current plan's execution-unit files before verification. verify --json runs that contract check first, enforces PRD knowledge coverage when the plan has PRD input, and then discovers the default typecheck, test, and build scripts when present. Projects can also declare custom verification commands in .frontend-harness/config.json:

{
  "verification": {
    "commands": [
      { "name": "lint", "command": "npm run lint" },
      { "name": "e2e", "command": "npm run test:e2e" }
    ]
  }
}

plan --json also classifies the frontend workflow and emits policy guidance for the agent. The current workflow classes are:

• ui_implementation
• prd_knowledge
• api_integration
• frontend_test
• bug_fix
• requirement_change
• documentation
• maintenance

Each plan includes required knowledge actions, implementation constraints, and verification focus. This keeps generated UI imports, PRD digestion, Swagger/API work, tests, bug fixes, and requirement changes inside the same controlled policy loop without turning skills into executable runtime commands.

Agent Plan Proposals

The plan is system-owned. An agent may provide bounded planning evidence before planning; the system resolver validates and consumes safe workflow, target, verification, ambiguity, and component evidence, then records the decision trace and warnings in the final plan.

Valid proposal input:

{
  "contractVersion": 1,
  "proposal": {
    "constraintHints": ["Handle loading, empty, and error states."],
    "planningEvidence": {
      "workflowCandidates": [
        {
          "kind": "documentation",
          "confidence": 0.86,
          "reasons": ["The task names README as the documentation target."]
        }
      ],
      "targetCandidates": [
        {
          "path": "README.md",
          "role": "documentation_target",
          "confidence": 0.9
        }
      ],
      "verificationCandidates": [
        {
          "kind": "documentation_review",
          "reason": "The change is documentation-only."
        }
      ],
      "ambiguities": []
    },
    "componentHints": [
      {
        "name": "OrderSearchForm",
        "responsibility": "query filters and submit behavior"
      }
    ]
  }
}

Validate the proposal file before planning:

npm run harness -- proposal check --json --file agent-proposal.json
npm run harness -- plan --json "<task>" --agent-proposal agent-proposal.json

The final plan still owns execution units, concrete file paths, dependency graph, execution order, and verification requirements. Component hints only influence UI workflows; documentation and maintenance work use project or document boundaries instead of invented frontend component files.

Advisory Commands

These commands expose project-local knowledge and workflow guidance as provenance only. They do not launch agents, execute skills, or turn markdown into commands.

npm run harness -- skills list --json
npm run harness -- skills check --json
npm run harness -- knowledge add --json --kind rule --subject "<subject>" --rule "<rule>"
npm run harness -- knowledge promote --json --title "<title>" --body "<body>"
npm run harness -- knowledge update --json --id <knowledge-id> --source "docs/prd/<file>.md"
npm run harness -- knowledge index --json
npm run harness -- knowledge coverage --json
npm run harness -- knowledge list --json
npm run harness -- knowledge search --json --query "<query>"
npm run harness -- knowledge show --json --id <knowledge-id>
npm run harness -- knowledge check --json

Prefer knowledge add for PRD digestion. It stores small atomic entries such as rules, workflows, permissions, terms, decisions, conventions, and pitfalls with source_paths pointing back to the original PRD. Use knowledge update when a requirement changes so existing cards are merged instead of duplicated. knowledge index writes .frontend-harness/knowledge/index.json, a deterministic manifest grouped by PRD source, card id, scope, and tag. knowledge coverage verifies active PRD semantics remain traceable to source documents. knowledge promote remains available for authored Markdown cards, but raw PRD prose should stay in source documents instead of being copied into knowledge.

Runtime Boundary

The boundary is strict:

• Codex / Claude Code owns execution.
• frontend-harness owns policy.
• The project owns durable state and knowledge.

Project skills under .frontend-harness/skills/ are policy guidance and provenance for planning. They are intentionally separate from Codex or Claude runtime skills installed in the developer environment.

That means frontend-harness should stay small and focused. Its job is to make frontend work repeatable, not to become a second runtime.

Project State

The package writes project-local artifacts under .frontend-harness/:

.frontend-harness/
  context/
  plans/
  execution-units/
  component-graph/
  guidance/
  state.json
  verification/
  logs/
  repair/
  repair-decision/
  state-explain/
  protocol/
  knowledge/
  skills/
  config.json

Runtime artifacts such as context/, plans/, state.json, verification/, logs/, repair/, state-explain/, execution-units/, and component-graph/ are generated continuity and evidence. They are ignored by git and can be removed with frontend-harness clean --json.

Durable project assets such as knowledge/, skills/, config.json, and protocol provenance are intentionally preserved by clean and may be committed when they represent project policy.

New Direction

The project is being recentered around the original idea:

1. Keep AGENTS.md and CLAUDE.md injection as the primary product surface.
2. Treat CLI commands as the agent-facing protocol API, not the daily human UI.
3. Keep the public human workflow to install, initialize, and check protocol health.
4. Preserve deterministic context, plan, verify, repair, and state primitives.
5. Delete launcher/runtime features that duplicate Codex or Claude Code.
6. Keep removed agent * and run --agent surfaces out of the product unless the direction is explicitly revisited.
7. Ship a small built-in set of project skills for common frontend workflows, while preserving project-local overrides.
8. Keep documentation short, current, and product-oriented.

The success criterion is not more commands. The success criterion is that a team member can install the package, initialize the protocol, and then use AI-assisted frontend development normally while the agent follows a controlled engineering loop.

Development

Build:

npm run build

Run the CLI from this source checkout without linking:

npm run harness -- context --json
npm run harness -- plan --json "<task>"
npm run harness -- verify --json
npm run harness -- scaffold --preset vue --target tmp-vue-app --dry-run --json

Use npm run harness -- ... from project scripts for harness commands.

Verify:

npm run verify

Package dry-run:

npm_config_cache=/tmp/frontend-harness-npm-cache npm pack --dry-run

The temporary npm cache avoids local global-cache permission issues on machines where ~/.npm contains root-owned files.

Release checklist:

npm run verify
npm_config_cache=/tmp/frontend-harness-npm-cache npm pack --dry-run
npm_config_cache=/tmp/frontend-harness-npm-cache npm pack --pack-destination /tmp

Update CHANGELOG.md before publishing, then install the generated tarball in a temporary consumer project and run npx frontend-harness --help plus scaffold dry-run. See docs/RELEASE.md for the full npm release process.