@linnify/software-factory
v0.3.1
Published
Pull selected Linnify knowledge areas from the Software Factory harness into a project's local working copy.
Keywords
Readme
@linnify/software-factory
Pulls selected Linnify knowledge areas from the Software Factory harness — the
harness/organization/knowledge/ tree of the private
linnify/software-factory
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 packages/cli by
.github/workflows/publish-cli.yml.
Install
pnpm add -Dw @linnify/software-factoryDrop 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/software-factory 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 packages/cli/package.json in
the same PR as the change, and merging to develop releases it and tags
cli-v<version>. Leave the version alone and the workflow is a no-op, so
unrelated packages/cli/ edits (tests, README) don't attempt a duplicate
publish. Auth is npm trusted publishing (OIDC) — there is no token to rotate.
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
AGENTS.md gitignored — generated: the organization instructions and
the knowledge section (see below)
manifest.json gitignored — generated: what was pulled, and from whereThe 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": "develop",
"areas": ["web", "tooling"]
}areas(required, non-empty array of strings): the knowledge areas to pull, matching folders underharness/organization/knowledge/in software-factory.ref(optional, default"develop"): the branch or tag of software-factory to pull from.developis the branch the live harness ships from.
Usage
pnpm software-factory pullRunning pnpm software-factory with no arguments does the same thing —
pull is the default command.
Each run:
- Sparse-clones the requested areas and the organization instructions
(
harness/organization/instructions.md) fromlinnify/software-factoryatref. - Replaces
.asd/knowledge/<area>/in your project with the pulled folders, for each requested area. - Writes
.asd/manifest.jsonwith the resolved commit, ref, areas, and sync timestamp. - Ensures the generated paths (
.asd/knowledge/,.asd/AGENTS.md,.asd/manifest.json) and.asd/context.local.mdare listed in your project's.gitignore, replacing a blanket.asd/entry if it finds one. - Writes
.asd/AGENTS.md— the organization instructions followed by the## Development Knowledgesection — and makes sure your project's root agent doc includes it (see below).
The generated agent doc
.asd/AGENTS.md is what makes the agent build the Linnify way: the
organization instructions every Software Factory session carries, followed by
the ## Development Knowledge section — why the knowledge is binding, how an
area is shaped, and one line per pulled area pointing at its entrypoint. Links
are relative to .asd/, so the file reads the same wherever the agent loads
it from.
Your project's root agent doc — AGENTS.md, or CLAUDE.md when that is the
only one the project keeps — includes it with one line, which pull adds if
it is missing (replacing a ## Development Knowledge section an older
release generated there):
@.asd/AGENTS.mdpnpm software-factory mapmap regenerates only the knowledge section of .asd/AGENTS.md. 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](./knowledge/web/KNOWLEDGE.md)
<!-- END:linnify-knowledge -->The whole of .asd/AGENTS.md is generated — never hand-edit it; pull
rewrites it from the harness every run. 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 software-factory over SSH
([email protected]:linnify/software-factory.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. software-factory 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.
