ces-harness-creator

A Claude Code plugin that scaffolds a complete, production-grade harness around any software project — so coding agents can start, stay in scope, verify work, document decisions, and resume across sessions reliably.

Built by Code Engine Studio (CES). An evolution of walkinglabs/harness-creator, extended with architecture docs, enforcement workflows, a rules library.

What it builds

One command turns any repo into a harness-equipped project:

your-project/
├── CLAUDE.md                         ← agent instruction file (links to docs/)
├── feature_list.json                 ← feature tracker with acceptance criteria + ADR refs
├── progress.md                       ← session restart state
├── session-handoff.md                ← context for the next session / agent
├── init.sh                           ← single verification entrypoint
├── docs/
│   ├── adr/                          ← Architecture Decision Records
│   └── architecture/                 ← C4 model in LikeC4 DSL
├── lefthook.yml                      ← git hooks: lint / typecheck / tests
├── .claude/
│   ├── settings.json                 ← Claude Code hooks (Tier 2)
│   ├── hooks/                        ← Tier 1 scripts + Tier 3 nudge scripts
│   ├── workflows/                    ← on-demand verification workflows (Tier 3)
│   ├── rules/                        ← curated guardrails (.md files)
│   └── skills/                       ← project-specific agent workflows

Install

Requires an SSH key configured for GitHub (Code Engine Studio org members only).

npx @codeenginestudio/harness-creator@latest

The wizard will:

1. Check for claude CLI (install Claude Code if missing)
2. Require superpowers — if missing, print claude plugin install superpowers@obra and exit so you can install it first
3. Install ces-harness-creator at user scope (~/.claude) from the private GitHub repo via SSH — it's a generator usable in every project; the harness it emits lives per target project
4. Print a Dependencies summary: superpowers (required) and skill-creator (optional) with their install status and commands

Updating

Pull the latest plugin release with one command:

npx @codeenginestudio/harness-creator@latest update

This updates the plugin only — it does not touch harness files already in your project. Restart Claude Code afterward, then follow the on-screen post-update guidance to refresh a project's assets.

Usage

Invoke the main skill in any project:

/ces-harness-creator

Eight phases run in sequence with a human-approval checkpoint after each.

Feature workflow

Four slash commands cover the whole development loop:

| Command | When | What it does | | ---------------------- | ----------- | ------------------------------------------------------------------------- | | /ces-harness-creator | once | Builds the harness, including feature_list.json (your feature backlog). | | /next-feature | per feature | Picks the next unblocked feature and helps you design it (spec + plan). | | /harness-doctor | on demand | Diagnoses and heals harness drift (examine → prescribe → apply). | | /portal-ui | any time | Launches the harness portal UI to browse specs, plans, and progress. |

Everything else is automatic: a commit hook links each feature to its spec, plan, and release — you never run a linkage command by hand. When a release's features are all done, the flow prompts you to seal it (scripts/seal-release.mjs).

The 8 Phases

flowchart TD
    P1["Phase 1\nPrerequisites\nSuperpowers check\nDetect new/existing/harness"]
    P2["Phase 2\nDiscovery\nNew → brainstorming\nExisting → scan report"]
    P3["Phase 3\nArchitecture\nADRs + C4 model\nnpx likec4 serve"]
    P4["Phase 4\nHarness Files\nCLAUDE.md · feature_list.json\nprogress.md · init.sh"]
    P5["Phase 5\nWorkflows ✦\nPropose 4 dynamic-workflow\nenforcement scripts"]
    P6["Phase 6\nHooks ✦\nlefthook + Claude Code hooks\n3-tier enforcement wired"]
    P7["Phase 7\nRules ○\n27 curated templates\n+ scan-generated + interview"]
    P8["Phase 8\nSkills ○\nStack-matched templates\n+ custom workflow interview"]

    P1 --> P2 --> P3 --> P4 --> P5 --> P6 --> P7 --> P8

    style P7 stroke-dasharray:5,5
    style P8 stroke-dasharray:5,5

✦ required   ○ optional (user-gated)

What each phase produces

| Phase | Key outputs | | ----------------- | ------------------------------------------------------------------------------------------- | | 1 — Prerequisites | Mode: new / existing / existing-with-harness | | 2 — Discovery | Scan report (stack, tooling, missing artifacts). New projects → superpowers:brainstorming | | 3 — Architecture | docs/adr/ (3 seed ADRs) · docs/architecture/*.c4 (LikeC4 C4 model, localhost preview) | | 4 — Harness Files | CLAUDE.md · feature_list.json · progress.md · session-handoff.md · init.sh | | 5 — Workflows | .claude/workflows/*.js — adapted from 4 generic templates | | 6 — Hooks | lefthook.yml · .claude/settings.json · .claude/hooks/*.sh | | 7 — Rules | .claude/rules/*.md — 27-template library, propose-and-select | | 8 — Skills | .claude/skills/*/SKILL.md — per-stack templates, tailored to real conventions |

Enforcement: 3-Tier Model

Every harness wires three escalating tiers of enforcement:

flowchart LR
    subgraph T1["Tier 1 — Free, automatic"]
        C1["lefthook\ngit hooks\nlint · typecheck · test"]
        C2["precommit-check.sh\n(exit 2 = blocks commit)"]
    end
    subgraph T2["Tier 2 — Low cost, automatic"]
        C3["Claude Code\nPreToolUse agent hook\non every git commit"]
    end
    subgraph T3["Tier 3 — Higher cost, prompted"]
        C4["Dynamic workflows\n.claude/workflows/*.js\nfan-out verifiers\n+ adversarial skeptic"]
    end

    GC["git commit"] --> T1 --> T2
    GP["git push / gh pr create"] -->|"nudge hook\nadditionalContext"| T3
    SE["SessionEnd"] -->|"suggest rule-miner"| T3
    T3 -->|"user approves"| WF["Workflow tool\nlaunches workflow"]

Hooks cannot launch workflows directly. suggest-deep-pass.sh exits 0 and injects additionalContext; Claude — which holds the Workflow tool — offers the relevant workflow and launches it on approval. Tier 3 is prompted, never auto-fired.

The 4 Enforcement Workflows

| Workflow | Pattern | What it checks | | ---------------------------------- | --------------------------------------------------------- | ----------------------------------------- | | pre-commit-verification | Classify-and-act → fan-out verify → synthesize | Staged diff vs init.sh / tests | | rules-adherence-checker | Fan-out (1 agent/rule) → adversarial skeptic | .claude/rules/ + CLAUDE.md | | architecture-consistency-checker | Multi-angle analyzers → adversarial panel | docs/architecture/*.c4 + docs/adr/ | | rule-miner | Mine corrections → cluster → adversarial verify → distill | git history + review comments → new rules |

Workflows are templates, not verbatim scripts. At generation time, Claude adapts each to the project — injecting real rule names, choosing models for the stack, and adding project-specific checks.

Rules Library (27 templates)

Seven rules are enabled by default; the rest are proposed-and-selected:

| Category | Templates (count) | Default-on | | ---------------- | ----------------- | ---------------------------------------- | | Agent Behavior | 6 | verify-before-done, surgical-changes | | Git & Commits | 6 | semantic-commits, no-agent-coauthor, release-linkage | | Harness Design | 4 | — | | Security | 3 | no-secrets-in-code | | Testing | 3 | — | | Documentation | 3 | adr-for-decisions | | PR Workflow | 2 | — |

no-agent-coauthor encodes the CES preference: humans own the commit record; no AI co-author trailers.

Plugin Architecture

flowchart TB
    subgraph Plugin["ces-harness-creator plugin repo"]
        PM[".claude-plugin/plugin.json\n(superpowers = soft dep)"]
        SK["skills/\nOrchestrator SKILL.md\n+ 11 sub-skills"]
        SC["scripts/\nNode.js ES modules\n(no npm deps)"]
        TM["templates/\nhooks/ · adr/ · c4/\nclaude.md · feature-list"]
        RL["rules-library/\n27 × .md templates\n7 categories"]
        SL["skills-library/\n5 × stack skill templates"]
        WL["workflows-library/\n4 × .js workflow templates"]
    end

    subgraph Target["target project (any repo)"]
        HF["Harness files\nCLAUDE.md · init.sh · …"]
        DA["docs/adr/ · docs/architecture/"]
        WF[".claude/workflows/*.js"]
        HK[".claude/hooks/ · lefthook.yml\n.claude/settings.json"]
        RU[".claude/rules/*.md"]
        SP[".claude/skills/*/SKILL.md"]
    end

    SK -->|"phase 1-2: detect + scan"| SC
    SC -->|"planArchitecture()"| DA
    SC -->|"planCoreHarness()"| HF
    SC -->|"planWorkflows()"| WF
    SC -->|"planHooks()"| HK
    SC -->|"planRules()"| RU
    SC -->|"planSkillsGen()"| SP
    TM -.->|fill templates| SC
    RL -.->|readFileSync + substitute| SC
    SL -.->|readFileSync + substitute| SC
    WL -.->|readFileSync + substitute| SC

scripts/lib/ map

| Module | Exports | Used by | | ------------------------- | ----------------------------------------------------------- | ------------------------- | | harness-utils.mjs | barrel re-export | all orchestrators | | fs-utils.mjs | parseArgs, exists, writeText, readJson, listFiles | everything | | detect.mjs | detectProject, detectPackageManager | scan, harness, hooks | | verification.mjs | verificationCommands, initScriptFromCommands | harness, hooks, workflows | | detect-mode.mjs | classifyProjectMode | Phase 1 | | scan-report.mjs | buildScanReport | Phase 2 | | adr.mjs | adrDoc, adrIndex, adrFilename | Phase 3 | | c4.mjs | c4Model, c4Views, c4Workspace, inferContainers | Phase 3 | | score.mjs | scoreHarness, loadHarnessFiles | validate sub-skill | | workflows.mjs | planWorkflows, WORKFLOW_NAMES | Phase 5 | | hooks.mjs | planHooks | Phase 6 | | enforcement-audit.mjs | auditEnforcement | validate | | rules-gen.mjs | planRules, DEFAULT_RULES, ALL_RULE_NAMES | Phase 7 | | skills-gen.mjs | planSkillsGen, opportunitiesForStack | Phase 8 | | customization-audit.mjs | auditCustomization | validate |

Harness Validation

Audit any harness (including the ones this plugin generates):

node scripts/validate.mjs --target /path/to/project

Output: 5-subsystem score (0–100) + enforcement tier audit + customization summary.

Harness validation for /path/to/project
Overall: 95/100   Bottleneck: lifecycle

instructions: 5/5
state:        4/5
verification: 5/5
scope:        5/5
lifecycle:    4/5

Enforcement:
  Tier 1 (git hooks + precommit): present
  Tier 2 (Claude hooks settings): present
  Tier 3 (workflows):             4 installed

Customization:
  Rules: 8 installed (defaults present)
  Skills: 2 installed

Sub-skills

| Sub-skill | Command | Purpose | | -------------------------------- | --------------------------------- | --------------------------------------------- | | ces-harness-creator:scan | /ces-harness-creator:scan | Scan only — stack, tooling, missing artifacts | | ces-harness-creator:arch | /ces-harness-creator:arch | ADR + C4 generation only | | ces-harness-creator:validate | /ces-harness-creator:validate | Audit an existing harness | | ces-harness-creator:workflows | /ces-harness-creator:workflows | Phase 5 only — propose + install workflows | | ces-harness-creator:hooks | /ces-harness-creator:hooks | Phase 6 only — wire enforcement hooks | | ces-harness-creator:rules | /ces-harness-creator:rules | Phase 7 only — propose + install rules | | ces-harness-creator:skills-gen | /ces-harness-creator:skills-gen | Phase 8 only — propose + install skills | | next-feature | /next-feature | Per-feature driver — pick, brainstorm, plan | | harness-doctor | /harness-doctor | Diagnose + heal harness drift (HEAL) | | subproject-claude | /subproject-claude | Monorepo sub-project CLAUDE.md authoring | | portal-ui | /portal-ui | Launch the harness portal UI |

Resumability

Phase state is saved to .claude/harness-state.json. Re-running /ces-harness-creator on a partial harness offers: "Resume from Phase N or start fresh?" Each emitter is non-destructive by default (skips existing files); use --force to overwrite.

Design Principles

Every generated harness propagates these principles into the target project:

1. State assumptions explicitly — ask when uncertain, never silently assume
2. Minimal scope — generate only what was requested; nothing speculative
3. Surgical changes — in existing repos, touch only what serves the goal
4. Verification-first — define "done" as testable criteria before acting
5. Evidence required — no "done" claim without tool output
6. Propose before create — rules, skills, and workflows need human approval first
7. Traceability — every generated artifact traces to a requirement or detected fact

Evaluation

This plugin's own output quality is measured by a standalone PromptFoo eval suite in evals/ — a deterministic script route (real generators run in a tmp dir, file/stdout assertions) and a skill route (SKILL.md guidance judged by llm-rubric).

cd evals && npm install
npm run eval:scripts   # deterministic, no API key — CI-safe
npm run eval:skill     # needs ANTHROPIC_API_KEY (skips cleanly without)

References

• Learn Harness Engineering — 12-lecture course; original harness-creator
• Superpowers — required plugin dependency
• skill-creator — optional; richer custom-skill authoring (skill-creator@claude-plugins-official)
• LikeC4 — C4 architecture DSL and viewer
• Dynamic Workflows — Claude Code workflow API
• Claude Code Hooks — hook schema reference
• "A harness for every task: dynamic workflows in Claude Code" — Thariq Shihipar & Sid Bidasaria (source of canonical workflow patterns)