Skill: doanbactam/harness-engineering (version 1.0.0)

--- name: harness-engineering description: Evolve an existing repository toward Harness Engineering by making it more legible to agents, moving critical knowledge into repo-local artifacts, adding predictable structure, and replacing policy-only documentation with executable checks. Use when Codex is asked to audit a live codebase against Harness Engineering ideas, strengthen AGENTS.md and docs, add runnable governance and CI checks, or incrementally reduce hidden context and architectural drift without rewriting the project from scratch. --- # Harness Engineering Evolve an existing repository toward Harness Engineering without pretending it must be rebuilt as a blank template. Prefer repo-local knowledge, predictable structure, and executable checks over aspirational documentation and hidden context. ## Workflow ### 1. Audit the current repo - Read `AGENTS.md` and the top-level docs under `docs/`. - Identify missing source-of-truth artifacts, dead references, placeholder CI, and stack-specific assumptions. - Confirm whether the repo is a real app, a governance layer, or a starter template. - Preserve existing product and runtime structure where possible. Do not force a greenfield layout onto a mature codebase. ### 2. Establish the minimum repo-local artifacts - Keep `AGENTS.md` short and map-like. - Add only the missing artifacts that materially improve agent legibility, such as: - `docs/ARCHITECTURE.md` - `docs/core-beliefs.md` - `docs/quality-score.md` - `docs/observability.md` - `docs/worktrees.md` - `docs/skills.md` - `docs/product-specs/index.md` - `docs/product-specs/template.md` - `docs/exec-plans/index.md` - `docs/exec-plans/template.md` - `docs/exec-plans/tech-debt-tracker.md` - `docs/generated/README.md` - Match the artifact set to the repository's maturity. A small service may need fewer documents than a large multi-domain product. - If generated artifacts are referenced but not yet produced, add explicit placeholders rather than leaving silent gaps. ### 3. Replace policy-only claims with enforcement - Use the repo's existing stack where needed, but prefer `bun` for lightweight governance scripts when that does not conflict with the project. - Add executable checks for required files, stale placeholders, broken references, and obvious contract drift. - Wire CI to run the checks for every push and pull request. - Do not leave comments like "run lint later" as the only quality gate. ### 4. Preserve generality - Preserve real project names, domains, and runtime details when the repository is already in active use. - Remove only accidental one-off assumptions, stale tribal knowledge, and undocumented conventions. - Write docs so a future agent can continue work from the repository itself. - Prefer incremental hardening over broad rewrites. ### 5. Make the repo legible to agents - Keep one clear location for each category of knowledge. - Put product intent in `docs/product-specs/`. - Put multi-step delivery work in `docs/exec-plans/`. - Put detailed external library notes in `docs/references/`. - Prefer explicit directory conventions over clever local variation. ### 6. Verify the template - Run `bun run template:check` or the project equivalent. - Fix all hard failures before stopping. - Treat warnings as backlog only if they are genuinely optional. - If the repository is not a git checkout, note that you cannot report git status. ## Editing rules - Use imperative language in docs. - Prefer concise checklists over essays. - Keep examples aligned with `bun`. - Avoid claiming that a metric, score, or automation is "automatic" unless code actually updates it. - Add placeholder files when the template references an artifact that new projects will generate later. ## Reference Read [references/checklist.md](references/checklist.md) when you need a compact audit list while editing or reviewing a template repo. ## Deliverables - Updated repo-local docs - Missing placeholder artifacts filled in - Executable validation or governance checks - CI wired to run real checks - A short summary of what now supports Harness Engineering and what still depends on hidden context

path: README.md
content: # Harness Engineering Skill

`harness-engineering` is a Codex skill for evolving an existing repository toward Harness Engineering.

It is meant for real codebases that already have product code, delivery history, and project-specific constraints. The goal is not to force every repo into the same greenfield template. The goal is to make the repo easier for agents to work in by reducing hidden context, improving repository-local source of truth, and replacing policy-only documentation with executable checks.

## What this skill does

- Audits a repository for agent legibility gaps
- Strengthens `AGENTS.md` and supporting docs
- Adds or repairs repo-local source-of-truth artifacts
- Replaces placeholder governance with runnable validation
- Improves CI so agent workflows are enforced, not just described
- Encourages incremental adoption instead of broad rewrites

## Good fit

Use this skill when you want to:

- assess a repo against Harness Engineering ideas
- improve an existing repository so agents can operate with less chat-only context
- add `AGENTS.md`, architecture docs, execution plans, and quality scorecards
- introduce lightweight governance checks with `bun`
- reduce documentation drift and architectural drift over time

## Not the goal

This skill is not primarily about turning every repository into the same universal template.

It should preserve:

- the existing product structure
- the current stack where it makes sense
- project-specific naming and domain boundaries

It should remove:

- hidden tribal knowledge
- dead references
- fake automation claims
- placeholder CI that never checks anything real

## Files

- `SKILL.md`: the skill instructions and trigger description
- `agents/openai.yaml`: UI metadata for the skill
- `references/checklist.md`: compact review checklist for repo audits

## Suggested usage

Example prompt:

```text
Use $harness-engineering to audit this repository and evolve it toward Harness Engineering without forcing a greenfield rewrite.
```

## Installation

Copy this folder into your Codex skills directory:

```text
$CODEX_HOME/skills/harness-engineering
```

On this machine, that path is:

```text
C:\Users\kisde\.codex\skills\harness-engineering
```

## License

Add a license here if you plan to publish the skill as a standalone GitHub repository.


path: references/checklist.md
content: # Harness Template Checklist

Use this list when evolving an existing repository toward Harness Engineering.

## Core map

- `AGENTS.md` exists and stays short
- `AGENTS.md` points to deeper docs instead of duplicating them
- All referenced docs actually exist

## Source of truth

- Product intent lives in `docs/product-specs/`
- Active implementation work lives in `docs/exec-plans/`
- Tech debt lives in `docs/exec-plans/tech-debt-tracker.md`
- Library-specific notes live in `docs/references/`

## Architecture

- Layer order is explicit
- Boundary rules are written down
- Examples match the declared layer rules

## Enforcement

- Template has a `bun` script for governance checks
- CI runs a real command, not an `echo` placeholder
- Docs do not claim automation that does not exist

## Incremental adoption

- Existing product structure is preserved unless it blocks legibility
- Placeholder artifacts make absence explicit
- New docs explain the current repo, not an imaginary greenfield version

## Verification

- Local validation command runs successfully
- Any residual warnings are documented


path: agents/openai.yaml
content: interface:
  display_name: "Harness Engineering"
  short_description: "Incremental Harness Engineering workflow"
  default_prompt: "Use $harness-engineering to evolve this existing repository toward Harness Engineering with repo-local docs, executable checks, and less hidden context."

policy:
  allow_implicit_invocation: true


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: clean (LOW)