@linnify/asd-knowledge

Pulls selected Linnify knowledge areas from the private linnify/asd-harness repository into a project's local working copy, so Claude Code can read Linnify's way of working locally.

This package ships from source (plain Node ESM, no build step, no runtime dependencies) to the public npm registry, released from this repo's cli subdirectory by .github/workflows/publish-cli.yml.

Install

pnpm add -Dw @linnify/asd-knowledge

Drop the -w outside a pnpm workspace root; without it at a workspace root pnpm refuses with ERR_PNPM_ADDING_TO_ROOT.

Installing needs no GitHub access — the registry is public, so a laptop and a CI runner resolve it the same way. Read access to the private linnify/asd-harness repository is a runtime requirement of pull, not an install-time one; see Git access and the CI note.

Release

The package is proprietary (UNLICENSED) and public only so that consumers resolve it without credentials — the knowledge itself never leaves the private repository.

Publishing is version-gated: bump version in cli/package.json in the same PR as the change, and merging to main releases it and tags cli-v<version>. Leave the version alone and the workflow is a no-op, so unrelated cli/ edits (tests, README) don't attempt a duplicate publish.

The .asd/ folder

Everything ASD keeps in a project lives under .asd/ at the repository root — one folder holding the project's declaration of what ASD knows about it:

.asd/
  config.json        committed   — which knowledge areas this project pulls
  context.md         committed   — the project's ASD context: Linear team and
                                   project, docs space, environments, test
                                   accounts (written by asd-toolkit's setup skill)
  context.local.md   gitignored  — the same shape, secrets only
  knowledge/         gitignored  — generated: the pulled knowledge areas
  manifest.json      gitignored  — generated: what was pulled, and from where

The folder is not ignored wholesale: config.json and context.md are source and belong in git, so pull maintains one .gitignore line per generated path instead. A project still carrying a blanket .asd/ entry from the earlier layout gets it replaced with those lines on the next pull — it would otherwise hide the committed config.

Configure

Add a .asd/config.json to your project:

{
  "ref": "main",
  "areas": ["web", "tooling"]
}

• areas (required, non-empty array of strings): the knowledge areas to pull, matching folders under harness/knowledge/ in asd-harness.
• ref (optional, default "main"): the branch or tag of asd-harness to pull from.

Usage

pnpm asd-knowledge pull

Running pnpm asd-knowledge with no arguments does the same thing — pull is the default command.

Each run:

1. Sparse-clones the requested areas from linnify/asd-harness at ref.
2. Replaces .asd/knowledge/<area>/ in your project with the pulled folders, for each requested area.
3. Writes .asd/manifest.json with the resolved commit, ref, areas, and sync timestamp.
4. Ensures the generated paths (.asd/knowledge/, .asd/manifest.json) and .asd/context.local.md are listed in your project's .gitignore, replacing a blanket .asd/ entry if it finds one.
5. Regenerates the ## Development Knowledge section in your project's root agent doc (see below).

The knowledge section

pnpm asd-knowledge map

map regenerates the ## Development Knowledge section in your project's root agent doc — AGENTS.md, or CLAUDE.md when that is the only one the project keeps. That section is what makes the agent aware the knowledge exists at all: it says why the knowledge is binding, how an area is shaped, and lists one line per pulled area pointing at its entrypoint.

It scans every directory under .asd/knowledge/, reads that area's root file (KNOWLEDGE.md, falling back to index.md), and renders one entry per area from its name + description frontmatter:

<!-- BEGIN:linnify-knowledge -->
## Development Knowledge

Always follow the development knowledge below. …

- **web** — Use when working on the NextJs app in any way — … → read the [web knowledge](./.asd/knowledge/web/KNOWLEDGE.md)
<!-- END:linnify-knowledge -->

Everything between the two markers is generated — never hand-edit it; anything outside them is yours and is preserved. pull runs map as its last step, so you only need map directly after editing or removing a pulled area by hand. It errors if nothing has been pulled yet.

Git access

pull clones asd-harness over SSH ([email protected]:linnify/asd-harness.git), so the machine running it needs an SSH key registered with GitHub. If yours is authenticated over HTTPS instead — a gh auth login with Git operations protocol: https, and no GitHub SSH key — the clone fails with:

Host key verification failed.

or

[email protected]: Permission denied (publickey).

Installing the package does not touch git, so the failure only shows up on the first pull.

Either add an SSH key to your GitHub account, or route SSH GitHub URLs over HTTPS so they use your existing credential helper:

git config --global url."https://github.com/".insteadOf "[email protected]:"

CI note

pnpm install in CI resolves this package from npm and needs no credentials.

Do not run pull in CI. asd-harness is private and the default GITHUB_TOKEN has no read access to other private repositories, so the clone would fail. It also has nothing to do: .asd/knowledge/ is gitignored and read by agent sessions, never by a build.