Welcome to NHK: Naive Harness Kit

English | 中文

NHK is a prompt-first starter kit for people who want a usable agent workspace harness without becoming full-time harness engineers first.

It is intentionally a little humble, a little self-aware, and very practical. The point is not to look clever. The point is to help you get the good tools in place, wire them together sanely, and keep a Codex or Claude Code workspace from turning into a vague little document swamp.

What NHK Is

NHK helps with five recurring jobs that show up surprisingly fast once you start using coding agents seriously:

• getting the useful workflow tools in place, especially superpowers and planning-with-files
• lazily but safely initializing the right workspace instruction file for the current agent environment
• keeping coding-agent-guide.md and documentation-governance.md aligned with reality
• deciding whether a workstream should stay active or move to archive
• doing all of that with explicit prompts instead of opaque hooks

In other words, NHK is not trying to be magic. It is trying to be the slightly fussy friend who says: yes, let's make this easier, but let's also write the rules down so future-you is not stuck deciphering agent vibes.

This kit is for beginners, lazy pragmatists, and anyone who would rather ship than hand-roll a custom agent harness from scratch.

What Is Included

NHK ships with four focused skills:

• welcome-to-nhk: the first-stop router
• nhk-bootstrap: first-time workspace setup
• nhk-upkeep: day-to-day harness maintenance
• nhk-archive: human-confirmed archive transition

It also ships with frozen local references:

• AGENTS-template.md
• CLAUDE-template.md
• coding-agent-guide-template.md
• documentation-governance-template.md
• archive-readme-template.md
• dependency-setup.md
• validation-scenarios.md

The instruction templates are generation contracts, not copy-paste snacks. They tell the agent what must survive, what must be adapted, and what should quietly disappear before the final AGENTS.md or CLAUDE.md lands in a real workspace.

Documentation Logic

NHK separates human-facing docs from agent-facing docs on purpose:

• README.md is the default GitHub landing page for humans
• README_CN.md is the Chinese companion for humans
• AGENTS.md is for Codex-style agents maintaining this repository
• CLAUDE.md is for Claude Code and imports the shared repo instructions
• the four skill folders define actual NHK behavior
• references/ stores frozen drafting and validation assets used by the skills

This split matters. README files explain what NHK is, how to install it, and how to use it. AGENTS.md and CLAUDE.md are not tutorials; they tell coding agents how to work on the NHK repository itself without confusing repo maintenance with skill usage.

For an NHK-managed workspace, the expected document system is layered:

NHK is opinionated here on purpose:

• every NHK-managed workspace should have the instruction, routing, governance, and root archive surfaces
• root tracking files are conditional, not automatic
• active docs and archive docs should not be mixed
• archive transitions require human confirmation
• archived workstreams should stay discoverable through a root archive/README.md index

The direct source for the governance layer is references/documentation-governance-template.md. NHK does not treat documentation lifecycle as an implicit side effect. It expects those rules to be written down explicitly in the target workspace.

Dependencies

NHK expects these peer workflow systems:

• superpowers: process discipline, skill-first routing, brainstorm/spec/plan flow
• planning-with-files: persistent task tracking, recovery, and continuity

The pairing matters.

superpowers is useful because it gives agent work an actual shape instead of a vague "just keep going" spiral. It helps the model route work, choose the right workflow, and avoid improvising its own grand theory every twenty minutes.

planning-with-files pairs well with that because Codex and Claude Code are both a bit fuzzy about long-lived working memory in practice. External tracking files are not glamorous, but they are much better than hoping the model remembers which thread is still active, what has already been verified, or whether a half-finished workstream was supposed to stay live.

Together they give NHK a steadier foundation:

• superpowers gives the process shape
• planning-with-files gives the memory somewhere reliable to live outside the model
• NHK uses both to make AGENTS.md / CLAUDE.md setup, daily upkeep, and archive decisions less ad hoc

If one of them is missing, NHK should pause and ask whether you want to install it, enable it, or explicitly adopt its conventions manually for this NHK run. Adopt does not install anything, does not persist into later runs, and should be reported honestly. That decision is described in references/dependency-setup.md.

Installation

NHK is a file-based skill bundle. There is nothing to compile.

Copy the four skill directories and their sibling references/ directory directly under the skills root used by your agent environment:

<skills-root>/
├── welcome-to-nhk/
├── nhk-bootstrap/
├── nhk-upkeep/
├── nhk-archive/
└── references/

From this repository, the equivalent copy command is:

cp -R welcome-to-nhk nhk-bootstrap nhk-upkeep nhk-archive references <skills-root>/

Replace <skills-root> with the real skill collection path for your environment. Do not add an extra nhk/ directory around these five siblings.

The repository's scripts/ and tests/ directories are maintainer-only and are not runtime installation content. Python is not an NHK dependency. If Python 3 is already available, the zero-third-party-dependency validator is an optional file-layout check:

python3 -B scripts/validate_nhk.py --install-root <skills-root>

The validator confirms files and versions; it cannot confirm platform skill discovery. After copying and validating, refresh the agent session and confirm that all four skills are discoverable. Then start in the target workspace with welcome-to-nhk.

If you are installing NHK into a new environment and are not sure whether the dependencies are already present, that is normal. NHK is designed to stop and ask before pretending everything is ready.

How To Use It

The shortest path is:

1. Start with welcome-to-nhk.
2. Let it decide whether the workspace needs nhk-bootstrap, nhk-upkeep, or nhk-archive.
3. Use nhk-bootstrap to create or adapt the workspace instruction file, the two mandatory companion docs, and the root archive surface (archive/ plus archive/README.md).
4. Use nhk-upkeep after normal delivery cycles to repair drift; it asks about archive only when one specific workstream has completion evidence and related materials.
5. Use nhk-archive only after the human clearly confirms that one workstream is done and should move to archive.

If you do not know where to begin, NHK is opinionated on purpose: begin at welcome-to-nhk and let the router be the adult in the room.

Codex And Claude Code

NHK is designed to work with both:

• Codex-oriented workspaces usually center on AGENTS.md
• Claude Code workspaces may use standalone CLAUDE.md, or a thin CLAUDE.md that imports canonical AGENTS.md

NHK does not guess recklessly. When both files exist and CLAUDE has a real import line exactly equal to @AGENTS.md or @./AGENTS.md, AGENTS is canonical and NHK does not ask a needless question. A lone importing CLAUDE is a broken adapter; two independent files are real ambiguity and still require a human choice.

Worker Cost Policy

NHK does not freeze a model catalog that will go stale with the next release. The user's main-thread model and reasoning effort form the default per-worker cost ceiling. A known lower-cost configuration is fine when it is supported and unlikely to create expensive retries; a known increase needs human approval. Exact model pinning remains a project-level, human-approved exception.

Repo Maintenance

This repository itself includes both AGENTS.md and CLAUDE.md.

The intent is:

• AGENTS.md is the shared repo maintenance contract for coding agents
• CLAUDE.md imports AGENTS.md and adds only Claude-specific glue

That keeps the human-facing README separate from the agent-facing working rules, which is the least dramatic arrangement and therefore usually the best one.