uinaf/workspace-kit

Config-driven validation and scaffolding for agent workspaces: the git repositories that give coding/assistant agents a stable operating context. This workspace model is distinct from package-manager workspaces and monorepo tooling.

Supported execution environments are macOS and Linux.

Install

pnpm add --save-dev --save-exact @uinaf/workspace-kit

Use the project-local binary so contributors and CI use the version recorded by the workspace. Requires Node >= 24.18 plus git on PATH for the history-dependent checks. Convention workspaces use pnpm; enable Corepack once so the first command works before init writes the packageManager pin.

For a new workspace, start in an empty directory. The one-shot bootstrap records the resolved release as an exact local development dependency; ongoing commands then use that local pin:

corepack enable
pnpm dlx @uinaf/workspace-kit@latest init --profile personal
pnpm install
pnpm verify

To scaffold repository-scoped Hindsight instructions without the llm-wiki layout:

pnpm dlx @uinaf/workspace-kit@latest init --profile personal \
  --memory hindsight --integration coding-agent \
  --namespace fixture-owner/fixture-workspace

For a repository that already has package.json, follow Adopting an existing workspace so its existing scripts and dependencies remain explicit. init validates a compatible package when re-run and stops before writing around an incompatible one.

Quick usage

pnpm exec workspace-kit verify                    # complete offline gate
pnpm exec workspace-kit doctor                    # configured core checks
pnpm exec workspace-kit wiki backfill --check     # detect catalog drift
pnpm exec workspace-kit registry validate         # validate projects.json
pnpm exec workspace-kit registry status           # inspect registered checkouts
pnpm exec workspace-kit registry clone            # clone missing managed checkouts
pnpm exec workspace-kit registry pull             # fast-forward managed checkouts
pnpm exec workspace-kit hooks install              # enable tracked Git hooks
pnpm exec workspace-kit skills sync               # materialize workspace skills

• verify is the canonical local and CI gate: it validates the config, runs the configured doctor checks, validates a configured project registry, and checks that configured wiki catalogs are current.

• doctor covers structure, wiki-lint, ownership-contract, documentation-link, workspace-skill, package-manager, and soft-limit checks.

• Git-history-based wiki staleness remains an explicit operation.

• contract handoff <paths...> screens candidate paths for human review eligibility.

• Absent config sections disable their checks, unknown files are always tolerated, and all validation runs offline with zero runtime dependencies.

• memory declares either the repository-maintained llm-wiki lifecycle or a repository-scoped Hindsight integration. Workspace-kit validates the contract but never installs or contacts Hindsight.

• workspace-kit --help lists all commands.

• registry validate is an explicit project-registry gate: it validates the entire declared entry shape before inspecting any locally present checkout, then checks project paths against the configured home-relative prefix, allowed Git origin hosts, repository paths, portable case/Unicode aliases, canonical roots, optional catalog pointers, allowed repository owners, required entries, and an optional entry limit.

• The explicit registry.project policy enables this check; originHosts defaults to ["github.com"], and missing checkouts are allowed.

• verify includes it whenever that policy is present. Personal and runtime scaffolds use verify in their generated pre-commit hook.

• The explicit registry clone, registry status, and registry pull commands run the same validation first, then operate on the configured lifecycle modes.

• Clone and pull affect only entries whose mode is managed; status also shows locally present route-only entries.

• Pull is always fast-forward-only and refuses a configured branch mismatch.

• registry path <category/name> resolves one validated checkout for consumer-owned composition without teaching the package about a particular repository.

• hooks install configures the tracked .githooks directory for the current checkout.

For Git-aware wiki freshness, opt in with wiki.revisionStaleness. The check then evaluates the current working tree, including staged and unstaged edits, so source changes are visible before commit and a page edited in the same proposed revision can attest them. For wiki-to-wiki sources, an updated:-only frontmatter change is metadata: it does not make dependent pages stale.

Composition model

workspace-kit owns portable workspace structure, scaffolding, and validation. Consumers own machine-global setup and compose repository-local tools through their workspace policy. The optional skills sync command links authored workspace skills and installs the workspace's declared remote skills. It records those copies in skills/workspace-kit-lock.json so later syncs retire only workspace-kit-managed copies. Machine-global capabilities remain consumer-owned.

Workspace repositories run history-based secret detection in a dedicated CI workflow. Consumers can list that workflow in workspace.json.required when its presence is part of their structural contract. Local workspace-kit commands remain deterministic, credential-free workspace checks.

Docs

• Workspace convention, bootstrap, and check contracts: workspace structure, skill ownership, scaffold follow-through, and exactly what each check enforces
• Parity oracle: the executable spec the checks are held to, byte-for-byte
• Release workflow: automatic, tokenless publishing

Contributing

See CONTRIBUTING.md. Vulnerabilities: SECURITY.md.

License

MIT