@jarl_okbe/tk

@jarl_okbe/tk

Technical Knockout makes supported coding agents research a maintainer-curated set of open-source projects for architecture, selection, build-vs-buy decisions, and capability replication.

TK is now plan-first: it produces machine-readable replication contracts and run artifacts before or alongside the human-readable brief.

Start

Install TK for your agent host and check that it is ready:

npx @jarl_okbe/tk codex install && npx @jarl_okbe/tk codex status
npx @jarl_okbe/tk claude install && npx @jarl_okbe/tk claude status
npx @jarl_okbe/tk opencode install && npx @jarl_okbe/tk opencode status
npx @jarl_okbe/tk hermes install && npx @jarl_okbe/tk hermes status

Restart the host or start a new session after installation. In an existing Claude Code session, run /reload-plugins to load the plugin and reconnect MCP.

Then describe the technical decision from your project without naming TK:

We need an internet capability layer for our agent. Research existing open-source approaches and dependencies, then decide what to reuse, adopt, or build.

The configured agent should inspect the current project, then query TK reports, comparisons, and dependency evidence. Inclusion in TK is the project-selection signal. If the curated set has no relevant coverage, the agent should report that gap instead of discovering replacement projects externally. If implementation evidence is needed, ask the agent to inspect the relevant TK source cache.

For a reference-only brief:

npx @jarl_okbe/tk replicate "agent internet capability layer" --from agent-reach

For the structured replication workflow:

npx @jarl_okbe/tk plan "agent internet capability layer" --from agent-reach --json
npx @jarl_okbe/tk verify "agent internet capability layer" --from agent-reach --json
npx @jarl_okbe/tk run list --json
npx @jarl_okbe/tk run show <run-id> --json

TK should help the agent answer what to keep, what to adapt, what not to copy, the first implementation boundary, and how to verify it.

CLI

Command	What it does
tk doctor	Aggregate repo + runtime health checks
tk doctor repo	Check reports/comparisons, catalog validity, and replication schemas
tk doctor runtime	Check source-cache state and runtime artifact roots
tk plan "<capability>"	Build a structured replication plan and persist run artifacts
tk replicate "<capability>"	Render the human-readable brief view over the structured plan
tk verify "<capability-or-run-id>"	Verify the replication contract and update the run trace
tk run list	List recent persisted runs
tk run show <run-id>	Read one persisted run with plan, trace, references, and verification
tk report audit	Audit report structure against TK Report Contract v1
tk report lint	Fail when reports fall outside the hard-gate contract
tk report fix-headings --write	Normalize low-risk heading aliases across reports/
tk search "<query>"	Search TK catalog metadata
tk deps <project>	Inspect dependency / SDK evidence for one project
tk source status	Inspect local source-cache state
tk source sync --missing	Create a clone/fetch plan for missing source caches
`tk codex <install	status
`tk claude <install	status
`tk opencode <install	status
`tk hermes <install	status

Machine index invariant: tk catalog validate requires every catalog project to have a packaged data/reports/*.md snapshot, and tk doctor repo validates the packaged data/tk.lock.json against the current catalog. After pruning a report, refresh with tk catalog build and tk source status --write-lock.

Examples:

• Value proof: https://github.com/okbexx/tech-knockout/blob/main/docs/value-proof.md
• Runtime and contracts: https://github.com/okbexx/tech-knockout/blob/main/docs/tk-replication-runtime.md
• Architecture notes: https://github.com/okbexx/tech-knockout/blob/main/docs/tk-agent-plugin-architecture.md

Runtime Artifacts

When TK runs from a repository checkout, persisted runs live under:

packages/tk/data/runs/<run-id>/

When TK runs from the published npm package, the same artifacts live under the OS-specific user data directory. Set TK_RUNTIME_DATA_ROOT to override the location.

Each run stores:

File	Meaning
input.json	Capability, selected references, and invocation metadata
references.json	Resolved reference project records
plan.json	Structured replication plan validated by replication-plan.schema.json
brief.md	Human-readable brief rendered from the structured plan
verification.json	Verification result validated by verification-result.schema.json
trace.json	Run trace / step log validated by run-trace.schema.json

packages/tk/data/runs/ is runtime output, not source-controlled product content.

Report Structure Contract

TK report governance is now part of the package surface.

• Contract doc: docs/tk-report-structure-contract-v1.md
• Rollout / migration plan: docs/tk-report-structure-rollout-plan.md
• Machine-readable audit schema: packages/tk/schemas/report-structure-audit.schema.json
• Written audit artifact: packages/tk/data/report-structure-audit.json

Hard gate focuses on the decision skeleton (基本信息, dual-scenario core, quality, community, rating, summary). Recommended sections such as 架构解剖, 关键代码走读, and detailed bottom-architecture children stay as warnings so the repository can migrate gradually instead of rewriting every report at once.

MCP

The MCP server exposes the same replication workflow through structured tools:

• tk_plan_replication
• tk_verify_replication
• tk_list_runs
• tk_get_run_trace
• tk_doctor

Use MCP when an agent needs machine-readable results. Use CLI when a human wants direct control of writes, source sync, or local verification.

Development

From the repository root:

npm install
npm run check --workspace @jarl_okbe/tk
npm run report:audit --workspace @jarl_okbe/tk
npm run report:lint --workspace @jarl_okbe/tk
npm run fixtures:regression --workspace @jarl_okbe/tk
npm run benchmark:capabilities --workspace @jarl_okbe/tk
npm run mcp:smoke --workspace @jarl_okbe/tk
npm run verify --workspace @jarl_okbe/tk

Publish by creating a GitHub Release whose tag exactly matches the package version, for example v0.1.7. .github/workflows/publish.yml verifies the release, publishes through npm trusted publishing, and smoke-tests the registry artifact. Before the first automated release, configure the npm package's Trusted Publisher with:

• GitHub owner: okbexx
• Repository: tech-knockout
• Workflow filename: publish.yml
• Allowed action: npm publish

No long-lived NPM_TOKEN is required. The workflow requires GitHub-hosted runners, Node 24, npm 11.5.1 or newer, and id-token: write permission.

The package owns the host-neutral runtime and canonical Skills. Codex and Claude Code use native plugin adapters in plugins/technical-knockout; OpenCode and Hermes load the same package-owned Skills and MCP server through their global configuration.