@projectplaceholders/cli — pkit

The command an agent runs before it says it is done.

pkit check          # types, lint, architecture boundaries, context docs — one gate
pkit check --json   # the same result, shaped for a program to read

Why one command

Running tsc and eslint separately is not the hard part. The hard part is that both tools describe the symptom precisely and the remedy not at all. Type 'string | undefined' is not assignable to type 'string' tells an agent something is wrong; it does not say whether to narrow, to widen, or to change the caller. Left to guess, the cheapest move is usually the wrong one — a cast, a !, an any.

So pkit check merges both into one result where every finding carries a fix written for whoever has to act on it:

{
  "ok": false,
  "violations": [
    {
      "source": "eslint",
      "rule": "boundaries/dependencies",
      "file": "src/features/orders/application/place.ts",
      "line": 1,
      "column": 22,
      "message": "'application' may not import 'infrastructure'. ...",
      "fix": "... export it from that feature's index.ts; if the logic belongs to neither feature, move it to src/shared.",
      "severity": "error"
    }
  ],
  "summary": { "errors": 1, "warnings": 0, "ran": ["typescript", "eslint", "context-docs"], "skipped": [], "failed": [] }
}

No guidance ever suggests eslint-disable, @ts-ignore, or @ts-expect-error. The test suite asserts that.

The three checkers

typescript and eslint prove things about code. context-docs checks the thing neither of them can see: whether each module still has a CONTEXT.md, with the sections it needs, that somebody has looked at recently. See @projectplaceholders/context-docs — it is the one checker whose findings can be warnings, because doc drift is an inference rather than a fact.

Exit codes

| | | |---|---| | 0 | passed | | 1 | violations found | | 2 | misconfigured — bad arguments, or a checker that should have run and could not | | 3 | the command is not included in this licence |

ran, skipped, failed

A checker that does not apply — no tsconfig.json, no ESLint config — is listed under skipped and does not fail the run. A checker that should have run and threw is listed under failed, and ok is false: an incomplete check reported as a pass is the worst possible answer.

Pro commands

add, upgrade, and skills live in Project Placeholders Pro. This package is MIT and contains none of their implementations — it looks for the Pro package at runtime and registers whatever it finds. Without it, the commands still appear in --help and still explain themselves; they exit 3 instead of doing the work, because an agent that cannot see why a documented command is missing will waste a turn looking for it.

pkit init and pkit doctor

pkit init                     # add the Kit to a project that already exists
pkit init --stack node        # override the detected stack
pkit init --force             # replace configs the project already had
pkit doctor                   # what `pkit check` covers here, and why not the rest

init writes what is missing and never replaces a config the project already decided on — it reports it and exits 1. doctor exits 2 while the setup is incomplete.

doctor leads with coverage rather than with problems, because a checker that never ran leaves no trace in a clean result: a project with no tsconfig.json passes every type check it has. See @projectplaceholders/setup.

pkit map and pkit explain

pkit map                # the architecture, as one read instead of a repo-wide grep
pkit explain orders     # one module: purpose, public API, who depends on it

explain on an unknown module exits 2 and lists the real ones. A bare "not found" would send the caller back to listing directories, which is the cost the command exists to remove. See @projectplaceholders/map for what it costs and why it is parse-only.

pkit context

pkit context sync                         # AGENTS.md, then a copy for every agent tool
pkit context sync --force                 # overwrite copies that were edited by hand
pkit context stale                        # drift per module, ranked
pkit context template root|module|adr     # a starting document, printed to stdout

sync writes AGENTS.md and mirrors it into CLAUDE.md, .cursor/rules/ and .github/copilot-instructions.md. It never overwrites a generated file somebody edited — it reports it and exits 1, because a fixer that quietly discards work is one people stop running. See @projectplaceholders/agent-rules for how the two cases are told apart.

stale exits 2 outside a git repository. You asked a question about history; answering "looks fine" without any would be a lie of omission.

Scope

pkit check checks one project directory — the working directory, or --cwd <dir>. In a monorepo, run it per package or through your task runner. Walking a workspace is a later release.