How to Use Lineage

How to Use Lineage

This page explains the simple flow.

1. Create Or Receive A Package

A Lineage package is a normal folder with a lineage.yaml manifest.

package/
├── lineage.yaml
├── skills/
├── workflows/
├── agents/
├── policies/
├── references/
└── adapters/

These folders are plain on purpose. You should be able to inspect what a package contains.

2. Initialize Local Lineage State

lineage init user

For a named workspace:

lineage init workspace <name>

3. Create A Package

lineage package init resume-workflow

Then add the package files, skills, workflows, references, policies, or adapters that belong to that environment.

4. Validate Before Sharing

Before a package leaves your machine, check it's safe and complete:

lineage package validate ./resume-workflow

This runs the same manifest, export-authority, path-safety, and secret-scan checks that export uses, and prints the package's content digest, without enabling or writing anything.

5. Share A Package

lineage package export ./resume-workflow -o resume-workflow.tgz

export refuses to run if validation fails. The archive is deterministic — exporting the same content twice always produces the same bytes and the same digest — so a receiver can confirm they got exactly what you sent.

On the receiving machine:

lineage package import resume-workflow.tgz

import treats the archive as untrusted: it re-runs the full validation pass against the extracted content before keeping it, the same as if you'd run package validate yourself, and refuses to overwrite an already-imported package (use --as to import under a different name).

6. Enable A Package In A Project

From the project where you want to use the package:

lineage enable ./resume-workflow

This records the package in .lineage/config.yaml.

7. Preview The Launch Plan

lineage run claude --dry-run
lineage run codex --dry-run

The dry run shows which provider, project config, and packages Lineage would use, and never writes anything.

8. Run Through A Provider

lineage run claude

The first time this would actually stage files for a provider — skills into its own directory, a generated section into its context file — it shows what it's about to create or change and asks for confirmation. Answer y/yes, or pass --yes/-y to skip the prompt in scripts. Re-running with an unchanged package set doesn't ask again.

Lineage can also install shims so normal provider commands enter Lineage first:

lineage install-shims

Then put the shim directory before existing provider binaries in PATH.

Safety Rule

Do not package secrets, credentials, provider login state, private prompts, .env values, or machine-local cache files.

If a workflow needs receiver-specific values, package a template or setup prompt instead.