codex-harness-kit 0.1.0

package/dist/src/templates.js

@@ -0,0 +1,208 @@
+export const DEFAULT_CONFIG_PATH = "docs/harness-config.json";
+export const HARNESS_MARKER_START = "<!-- codex-harness-kit:start -->";
+export const HARNESS_MARKER_END = "<!-- codex-harness-kit:end -->";
+export const HARNESS_BRIDGE_MARKER_START = "<!-- codex-harness-kit:bridge:start -->";
+export const HARNESS_BRIDGE_MARKER_END = "<!-- codex-harness-kit:bridge:end -->";
+export function createDefaultConfig() {
+    return {
+        version: 1,
+        paths: {
+            stateFile: "docs/harness-state.json",
+            memoryFile: "docs/project-memory.md",
+            decisionsFile: "docs/decisions.md",
+            contractsDir: "docs/contracts"
+        },
+        commands: {
+            verifyQuick: "",
+            verifyFull: "",
+            docsGenerate: ""
+        },
+        rules: {
+            maxRepeatedFailures: 2
+        }
+    };
+}
+export function createDefaultState(now = new Date()) {
+    return {
+        currentGoal: "",
+        status: "idle",
+        currentContract: "docs/contracts/example-contract.md",
+        blockers: [],
+        nextStep: "Update the current goal and contract before making code changes.",
+        lastUpdated: now.toISOString(),
+        verification: {
+            lastCommand: "",
+            lastResult: "unknown",
+            notes: "No verification has been recorded yet."
+        }
+    };
+}
+export function renderJsonFile(value) {
+    return `${JSON.stringify(value, null, 2)}\n`;
+}
+export function renderAgentsTemplate(configPath = DEFAULT_CONFIG_PATH) {
+    return `${HARNESS_MARKER_START}
+# AGENTS
+
+## Codex Harness Workflow
+
+1. Before changing code, read \`${configPath}\` first.
+2. Then use the configured paths from that file instead of assuming fixed \`docs/...\` locations:
+   - read \`paths.stateFile\`
+   - read the active contract referenced by \`currentContract\` inside the state file
+   - read \`paths.decisionsFile\`
+   - read \`paths.memoryFile\`
+   - use \`paths.contractsDir\` for contract discovery
+3. Use the configured validation commands from \`commands.verifyQuick\` and \`commands.verifyFull\` when they are set.
+4. Restore state before editing. Do not jump straight into implementation.
+5. Keep the contract current. If scope or acceptance changes, update the contract before more code changes.
+6. After edits, run the smallest meaningful verification command and record the result in the file pointed to by \`paths.stateFile\`.
+7. If the same class of failure reaches the configured repeated-failure limit in \`rules.maxRepeatedFailures\`, stop trial-and-error and write a short diagnosis with evidence, suspected root cause, and the safest next move.
+8. Capture durable context:
+   - long-lived preferences and quirks go in \`paths.memoryFile\`
+   - explicit trade-offs and architectural choices go in \`paths.decisionsFile\`
+9. Final responses must always say:
+   - what changed
+   - what verification ran
+   - what verification did not run
+
+## Restore Prompt
+
+When a new Codex thread starts, begin by reading the harness files above. A good prompt is:
+
+> Restore state and continue from the harness files before making changes.
+
+## Guardrails
+
+- Prefer the existing repo layout over inventing a new framework.
+- Keep this harness lightweight; do not turn it into a platform.
+- If validation is not configured yet, say so explicitly instead of claiming full verification.
+${HARNESS_MARKER_END}
+`;
+}
+export function renderAgentsHarnessSupplement(configPath = DEFAULT_CONFIG_PATH) {
+    return `${HARNESS_MARKER_START}
+# AGENTS Harness Supplement
+
+This file is active only when \`AGENTS.md\` contains the codex-harness-kit bridge block.
+
+## Harness Rules
+
+1. Read \`${configPath}\` first.
+2. Resolve the working files from \`paths.stateFile\`, \`paths.memoryFile\`, \`paths.decisionsFile\`, and \`paths.contractsDir\`.
+3. Open the active contract from \`currentContract\` in the state file before writing code.
+4. Restore state before editing, then keep the contract current as scope changes.
+5. After edits, run the smallest meaningful verification command from the config and record the result back into the configured state file.
+6. If repeated failures hit the configured limit in \`rules.maxRepeatedFailures\`, stop guessing and produce a diagnosis instead of trying random fixes.
+7. Write durable preferences to the memory file and explicit trade-offs to the decisions file.
+8. Final responses must say what changed, what verification ran, and what verification did not run.
+${HARNESS_MARKER_END}
+`;
+}
+export function renderAgentsActivationBridge(configPath = DEFAULT_CONFIG_PATH) {
+    return `${HARNESS_BRIDGE_MARKER_START}
+## Codex Harness Activation
+
+This repository uses \`codex-harness-kit\`.
+
+Keep the existing instructions in this file, and additionally treat \`AGENTS.harness.md\` as active instructions.
+
+Before making code changes:
+
+1. Read \`${configPath}\` first.
+2. Use the file paths from the config \`paths\` object instead of assuming fixed \`docs/...\` paths.
+3. Follow the harness workflow in \`AGENTS.harness.md\` together with the rest of this file.
+${HARNESS_BRIDGE_MARKER_END}
+`;
+}
+export function renderProjectMemoryTemplate() {
+    return `# Project Memory
+
+Use this file for durable context that should survive across threads.
+
+## Product and Repo Context
+
+- What this repository is for.
+- Constraints that matter every time.
+
+## Working Preferences
+
+- Coding style choices that are stable over time.
+- Review preferences or release expectations.
+
+## Known Pitfalls
+
+- Repeated mistakes, flaky areas, or environment traps.
+
+## Open Questions Worth Tracking
+
+- Questions that are not blockers today but should not disappear.
+`;
+}
+export function renderDecisionsTemplate() {
+    return `# Decisions
+
+Record notable technical or product decisions here so they do not live only in chat history.
+
+## Entry Template
+
+### YYYY-MM-DD - Short Decision Title
+
+- Context:
+- Decision:
+- Consequences:
+- Follow-up:
+`;
+}
+export function renderContractsReadmeTemplate() {
+    return `# Contracts
+
+Contracts define the current unit of work before code changes begin.
+
+Each contract should answer:
+
+1. What is being changed right now?
+2. What is explicitly out of scope?
+3. How will we know it is done?
+4. What is the smallest verification that proves progress?
+
+Suggested flow:
+
+1. Update or create a contract.
+2. Point \`currentContract\` in your configured state file at that contract.
+3. Implement against the contract.
+4. Run verification.
+5. Update state and decisions.
+`;
+}
+export function renderExampleContractTemplate() {
+    return `# Example Contract
+
+## Goal
+
+Describe the current objective in one or two sentences.
+
+## In Scope
+
+- The smallest changes that count as success.
+
+## Out of Scope
+
+- Anything intentionally deferred.
+
+## Acceptance Criteria
+
+- A reader can tell whether the task is done.
+- Validation steps are explicit.
+
+## Verification Plan
+
+- Quick check:
+- Full check:
+
+## Notes
+
+- Risks, assumptions, or sequencing notes.
+`;
+}
+//# sourceMappingURL=templates.js.map

package/dist/src/templates.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"templates.js","sourceRoot":"","sources":["../../src/templates.ts"],"names":[],"mappings":"AAEA,MAAM,CAAC,MAAM,mBAAmB,GAAG,0BAA0B,CAAC;AAC9D,MAAM,CAAC,MAAM,oBAAoB,GAAG,kCAAkC,CAAC;AACvE,MAAM,CAAC,MAAM,kBAAkB,GAAG,gCAAgC,CAAC;AACnE,MAAM,CAAC,MAAM,2BAA2B,GAAG,yCAAyC,CAAC;AACrF,MAAM,CAAC,MAAM,yBAAyB,GAAG,uCAAuC,CAAC;AAEjF,MAAM,UAAU,mBAAmB;IACjC,OAAO;QACL,OAAO,EAAE,CAAC;QACV,KAAK,EAAE;YACL,SAAS,EAAE,yBAAyB;YACpC,UAAU,EAAE,wBAAwB;YACpC,aAAa,EAAE,mBAAmB;YAClC,YAAY,EAAE,gBAAgB;SAC/B;QACD,QAAQ,EAAE;YACR,WAAW,EAAE,EAAE;YACf,UAAU,EAAE,EAAE;YACd,YAAY,EAAE,EAAE;SACjB;QACD,KAAK,EAAE;YACL,mBAAmB,EAAE,CAAC;SACvB;KACF,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,kBAAkB,CAAC,GAAG,GAAG,IAAI,IAAI,EAAE;IACjD,OAAO;QACL,WAAW,EAAE,EAAE;QACf,MAAM,EAAE,MAAM;QACd,eAAe,EAAE,oCAAoC;QACrD,QAAQ,EAAE,EAAE;QACZ,QAAQ,EAAE,kEAAkE;QAC5E,WAAW,EAAE,GAAG,CAAC,WAAW,EAAE;QAC9B,YAAY,EAAE;YACZ,WAAW,EAAE,EAAE;YACf,UAAU,EAAE,SAAS;YACrB,KAAK,EAAE,wCAAwC;SAChD;KACF,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,cAAc,CAAC,KAAc;IAC3C,OAAO,GAAG,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC;AAC/C,CAAC;AAED,MAAM,UAAU,oBAAoB,CAAC,UAAU,GAAG,mBAAmB;IACnE,OAAO,GAAG,oBAAoB;;;;;kCAKE,UAAU;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA+B1C,kBAAkB;CACnB,CAAC;AACF,CAAC;AAED,MAAM,UAAU,6BAA6B,CAAC,UAAU,GAAG,mBAAmB;IAC5E,OAAO,GAAG,oBAAoB;;;;;;;YAOpB,UAAU;;;;;;;;EAQpB,kBAAkB;CACnB,CAAC;AACF,CAAC;AAED,MAAM,UAAU,4BAA4B,CAAC,UAAU,GAAG,mBAAmB;IAC3E,OAAO,GAAG,2BAA2B;;;;;;;;;YAS3B,UAAU;;;EAGpB,yBAAyB;CAC1B,CAAC;AACF,CAAC;AAED,MAAM,UAAU,2BAA2B;IACzC,OAAO;;;;;;;;;;;;;;;;;;;;;CAqBR,CAAC;AACF,CAAC;AAED,MAAM,UAAU,uBAAuB;IACrC,OAAO;;;;;;;;;;;;CAYR,CAAC;AACF,CAAC;AAED,MAAM,UAAU,6BAA6B;IAC3C,OAAO;;;;;;;;;;;;;;;;;;CAkBR,CAAC;AACF,CAAC;AAED,MAAM,UAAU,6BAA6B;IAC3C,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;CA2BR,CAAC;AACF,CAAC"}

package/dist/src/types.d.ts

@@ -0,0 +1,54 @@
+export interface HarnessConfig {
+    version: number;
+    paths: {
+        stateFile: string;
+        memoryFile: string;
+        decisionsFile: string;
+        contractsDir: string;
+    };
+    commands: {
+        verifyQuick: string;
+        verifyFull: string;
+        docsGenerate: string;
+    };
+    rules: {
+        maxRepeatedFailures: number;
+    };
+}
+export interface HarnessState {
+    currentGoal: string;
+    status: string;
+    currentContract: string;
+    blockers: string[];
+    nextStep: string;
+    lastUpdated: string;
+    verification: {
+        lastCommand: string;
+        lastResult: string;
+        notes: string;
+    };
+}
+export interface ValidationIssue {
+    level: "error" | "warning";
+    path?: string;
+    message: string;
+    suggestion?: string;
+}
+export interface ValidationReport {
+    ok: boolean;
+    repoRoot: string;
+    agentsFile: string | null;
+    issues: ValidationIssue[];
+    config?: HarnessConfig;
+    state?: HarnessState;
+}
+export interface FileAction {
+    file: string;
+    status: "created" | "updated" | "unchanged" | "skipped";
+    reason?: string;
+}
+export interface InitResult {
+    repoRoot: string;
+    actions: FileAction[];
+    notes: string[];
+}

package/dist/src/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/src/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/types.ts"],"names":[],"mappings":""}

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "codex-harness-kit",
+  "version": "0.1.0",
+  "description": "A lightweight CLI and scaffold for Codex-style harness workflows in any repository.",
+  "type": "module",
+  "main": "./dist/src/index.js",
+  "types": "./dist/src/index.d.ts",
+  "bin": {
+    "codex-harness-kit": "dist/src/cli.js"
+  },
+  "files": [
+    "dist/src",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18.18"
+  },
+  "scripts": {
+    "clean": "rm -rf dist",
+    "build": "npm run clean && tsc -p tsconfig.json",
+    "prepack": "npm run build",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "npm run build && node --test dist/tests/*.test.js",
+    "verify": "npm run typecheck && npm test"
+  },
+  "keywords": [
+    "codex",
+    "harness",
+    "cli",
+    "typescript",
+    "agent"
+  ],
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/lonelyreader/codex-harness-kit.git"
+  },
+  "devDependencies": {
+    "@types/node": "^24.6.0",
+    "typescript": "^5.9.3"
+  }
+}