frontend-harness

frontend-harness is a context and evidence 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 a heavy harness workflow for every task. They keep asking Codex or Claude Code for frontend work in plain language. The injected project protocol tells the agent when to use the full context, planning, evidence, and repair loop, and when ordinary task guidance is enough.

What It Does

frontend-harness gives complex frontend tasks a deterministic execution contract:

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

The full loop is intended for work where source material, evidence, or durable verification matters: design-backed UI restoration, PRD-derived product knowledge, multi-source frontend changes, and handoffs that need validated artifacts. Simple bug fixes, tests, docs, maintenance, and small requirement edits should stay lightweight unless the task includes explicit PRD, API, UI, or audit evidence.

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 context, policy, and evidence around them. It should not wrap ordinary agent conversation in process for its own sake.

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 decide whether the task needs the full harness loop or lightweight project guidance.

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 general Vue 3 + Vite + TypeScript engineering baseline. It includes Vite config, ESLint/Prettier, Element Plus auto imports, product-neutral style layers, and small utils, storage, and service layers. Mature internal Vue applications can inform the baseline, but the default scaffold is not an admin template and does not create dashboards, sidebars, permission systems, business pages, or domain components. Admin-style shells, table pages, route permissions, and menu trees belong in optional recipes rather than the default preset.

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 and classify whether it is usable_as_visual_baseline, usable_for_patch_reference, usable_as_source, 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, and temporary asset localization is required only when the generated artifact is used as project source. 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 -- context task --json "<task>" --prd <prd-file> --api-source <openapi-file-or-url> --ui-source <ui-artifact-or-design-url>
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> --api-source <openapi-file-or-url> --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 -- evidence template --json
npm run harness -- evidence record --json --file <evidence-input.json>
npm run harness -- visual compare --json --design <design.png> --actual <actual.png> --diff <diff.png>
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 when the task needs harness-managed context, planning, or evidence. They persist local state under .frontend-harness/ and provide deterministic evidence for each step. context task --json emits a compact task packet from workflow policy, selected knowledge cards, explicit PRD/API/UI inputs, candidate project files, and ingest provenance so agents can use PRD/UI/API context without loading entire source materials into the prompt. evidence template --json prints the machine-readable evidence entry shape for the current plan; it is a schema aid, not proof. Put real captures, checks, comparisons, and hashes in a project-local evidence input JSON, then use evidence record --json --file <evidence-input.json> so the harness validates and writes .frontend-harness/verification/evidence.json. Captured evidence and visual comparison files are local intermediate artifacts by default; scaffolded projects ignore them and clean may remove them.

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, checks PRD knowledge quality 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
• frontend_review
• requirement_change
• documentation
• maintenance

Each plan includes required knowledge actions, implementation constraints, and verification focus. UI restoration, PRD knowledge, explicit source-backed API work, and evidence-heavy changes use the full controlled loop. Ordinary tests, bug fixes, docs, maintenance, and requirement edits are intentionally lightweight policy guidance unless the task supplies PRD/API/UI source material or asks for auditable evidence. Project skills remain guidance, not 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 -- ingest record --json --kind prd|openapi|ui-package --id <source-id> --source <file-or-url> --summary "<summary>"
npm run harness -- ingest list --json
npm run harness -- ingest show --json --ref ingest://<kind>/<source-id>
npm run harness -- knowledge add --json --kind rule --subject "<subject>" --rule "<rule>"
npm run harness -- knowledge outline --json --ref ingest://<kind>/<source-id>
npm run harness -- knowledge draft --json --ref ingest://<kind>/<source-id>
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 that must remain useful after source PRDs are deleted. Use ingest record only as a temporary input handle when PRD, OpenAPI, or UI package material needs to be referenced during extraction; source refs and coverage labels are optional retrieval aids, not quality gates. Use knowledge outline for project-file PRD Markdown to turn the source heading structure into a deterministic checklist with suggested knowledge kinds and extraction-required hints. Use knowledge draft to turn an ingest record into reviewed knowledge add / knowledge module scaffolds; for PRD Markdown, extractionItems is the source checklist and each required block should be added, updated, or explicitly skipped with a reason. Do not add scaffolds unchanged. When existing cards already point at the same ingest record, produced card IDs, or source file, draft output includes knowledge update candidates so agents can merge before adding duplicates. 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 checks that active PRD semantics are self-contained and not thin placeholders. knowledge promote remains available for authored non-PRD Markdown cards or hand-written cards, but it is not the PRD digestion path; raw PRD prose should stay in source documents or temporary ingest inputs 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. For simple tasks, they should be enough on their own; the harness should not force a full stateful loop when direct agent conversation plus local verification is cheaper.

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/
  design-sources/
  evidence/
  visual/
  logs/
  repair/
  repair-decision/
  state-explain/
  protocol/
  knowledge/
  skills/
  config.json

Runtime artifacts such as context/, plans/, state.json, verification/, design-sources/, evidence/, visual/, logs/, repair/, state-explain/, execution-units/, component-graph/, and stale runtime directories are generated local continuity and evidence. They are ignored by scaffolded project 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. Do not add agent * or run --agent surfaces 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.