@codeenginestudio/harness-creator 1.0.1

package/README.md

@@ -0,0 +1,287 @@
+# 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](https://github.com/walkinglabs/learn-harness-engineering), 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).
+
+```bash
+npx @codeenginestudio/harness-creator@latest
+```
+
+The wizard will:
+1. Check for `claude` CLI (install [Claude Code](https://claude.ai/code) if missing)
+2. Ask whether to install for **user** scope (all projects) or **project** scope (current directory)
+3. Detect if `superpowers` is missing and offer to install it automatically
+4. Install `ces-harness-creator` from the private GitHub repo via SSH
+
+---
+
+## Usage
+
+Invoke the main skill in any project:
+
+```
+/ces-harness-creator
+```
+
+Eight phases run in sequence with a human-approval checkpoint after each.
+
+---
+
+## The 8 Phases
+
+```mermaid
+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 ○\n42 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` — 42-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:
+
+```mermaid
+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 (42 templates)
+
+Six rules are enabled by default; the rest are proposed-and-selected:
+
+| Category         | Templates (count) | Default-on                               |
+| ---------------- | ----------------- | ---------------------------------------- |
+| Git & Commits    | 5                 | `semantic-commits`, `no-agent-coauthor`  |
+| Agent Behavior   | 5                 | `verify-before-done`, `surgical-changes` |
+| Security         | 4                 | `no-secrets-in-code`                     |
+| Documentation    | 3                 | `adr-for-decisions`                      |
+| Code Quality     | 5                 | —                                        |
+| Testing          | 4                 | —                                        |
+| PR Workflow      | 2                 | —                                        |
+| Harness Design   | 5                 | —                                        |
+| Memory & Context | 9                 | —                                        |
+
+> `no-agent-coauthor` encodes the CES preference: humans own the commit record; no AI co-author trailers.
+
+---
+
+## Plugin Architecture
+
+```mermaid
+flowchart TB
+    subgraph Plugin["ces-harness-creator plugin repo"]
+        PM[".claude-plugin/plugin.json\n(declares superpowers dep)"]
+        SK["skills/\nOrchestrator SKILL.md\n+ 7 sub-skills"]
+        SC["scripts/\nNode.js ES modules\n(no npm deps)"]
+        TM["templates/\nhooks/ · adr/ · c4/\nclaude.md · feature-list"]
+        RL["rules-library/\n42 × .md templates\n9 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):
+
+```bash
+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       |
+
+---
+
+## 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
+
+---
+
+## References
+
+- [Learn Harness Engineering](https://github.com/walkinglabs/learn-harness-engineering) — 12-lecture course; original `harness-creator`
+- [Superpowers](https://github.com/obra/superpowers) — required plugin dependency
+- [LikeC4](https://likec4.dev) — C4 architecture DSL and viewer
+- [Dynamic Workflows](https://code.claude.com/docs/en/workflows) — Claude Code workflow API
+- [Claude Code Hooks](https://code.claude.com/docs/en/hooks) — hook schema reference
+- "A harness for every task: dynamic workflows in Claude Code" — Thariq Shihipar & Sid Bidasaria (source of canonical workflow patterns)

package/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "@codeenginestudio/harness-creator",
+  "version": "1.0.1",
+  "private": false,
+  "type": "module",
+  "description": "CES Harness Creator — install wizard",
+  "bin": {
+    "harness-creator": "scripts/install.mjs"
+  },
+  "files": [
+    "scripts/install.mjs",
+    "scripts/lib/install-utils.mjs"
+  ],
+  "scripts": {
+    "test": "node --test \"scripts/__tests__/**/*.test.mjs\""
+  },
+  "dependencies": {
+    "@clack/prompts": "^0.9.0"
+  }
+}

package/scripts/install.mjs

@@ -0,0 +1,57 @@
+#!/usr/bin/env node
+import * as p from '@clack/prompts';
+import {
+  checkClaude,
+  isPluginInstalled,
+  isSelfRepo,
+  runClaudeCommand,
+  PLUGIN_PATH,
+} from './lib/install-utils.mjs';
+
+async function promptScope() {
+  const scope = await p.select({
+    message: 'Install for:',
+    options: [
+      { value: 'user', label: 'User', hint: '~/.claude — available in all projects' },
+      { value: 'project', label: 'Project', hint: `${process.cwd()} — current directory only` },
+    ],
+  });
+  if (p.isCancel(scope)) { p.cancel('Cancelled.'); process.exit(1); }
+  if (scope === 'project' && isSelfRepo()) {
+    const ok = await p.confirm({ message: 'CWD is the ces-harness-creator repo itself. Continue?', initialValue: false });
+    if (p.isCancel(ok) || !ok) { p.cancel('Aborted. cd to your target project and re-run.'); process.exit(1); }
+  }
+  return scope;
+}
+
+async function ensureSuperpowers() {
+  if (isPluginInstalled('superpowers')) return;
+  const install = await p.confirm({ message: 'superpowers is required. Install it?' });
+  if (p.isCancel(install) || !install) { p.cancel('Cannot continue without superpowers.'); process.exit(1); }
+  const s = p.spinner();
+  s.start('Installing superpowers...');
+  try {
+    runClaudeCommand('plugin marketplace add obra/superpowers');
+    s.stop('superpowers installed');
+  } catch (err) { s.stop('superpowers install failed'); throw err; }
+}
+
+async function installPlugin() {
+  const s = p.spinner();
+  s.start('Installing ces-harness-creator...');
+  try {
+    runClaudeCommand(`plugin marketplace add ${PLUGIN_PATH}`);
+    s.stop('ces-harness-creator installed');
+  } catch (err) { s.stop('ces-harness-creator install failed'); throw err; }
+}
+
+async function main() {
+  p.intro('CES Harness Creator — Install Wizard');
+  if (!checkClaude()) { p.cancel('Claude Code not found. Install from: https://claude.ai/code'); process.exit(1); }
+  await promptScope();
+  await ensureSuperpowers();
+  await installPlugin();
+  p.outro('Done. Open Claude Code and run /ces-harness-creator');
+}
+
+main().catch((err) => { console.error(err.message); process.exit(1); });

package/scripts/lib/install-utils.mjs

@@ -0,0 +1,30 @@
+import { execSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { join, resolve, dirname } from 'node:path';
+import { homedir } from 'node:os';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const _packageRoot = resolve(__dirname, '../..');
+export const PLUGIN_PATH = existsSync(join(_packageRoot, '.claude-plugin', 'plugin.json'))
+  ? _packageRoot
+  : 'Code-Engine-Studio/ces-harness-creator';
+
+export function checkClaude(exec = (cmd) => execSync(cmd, { stdio: 'ignore' })) {
+  try { exec('claude --version'); return true; } catch { return false; }
+}
+
+export function isPluginInstalled(name, exec = (cmd) => execSync(cmd, { encoding: 'utf8', stdio: 'pipe' })) {
+  try {
+    const cacheDir = join(homedir(), '.claude', 'plugins', 'cache');
+    return exec(`find "${cacheDir}" -maxdepth 4 -type d -name "${name}"`).trim().length > 0;
+  } catch { return false; }
+}
+
+export function isSelfRepo(exists = (p) => existsSync(p)) {
+  return exists(join(process.cwd(), '.claude-plugin', 'plugin.json'));
+}
+
+export function runClaudeCommand(args, exec = (cmd) => execSync(cmd, { stdio: 'inherit' })) {
+  exec(`claude ${args}`);
+}