Agent Jump Start
A single canonical spec for project instructions, review guidance, and reusable skills.
Agent Jump Start renders the right files for twelve coding-agent ecosystems from one source of truth, keeps them synchronized with one maintenance command, and protects pre-existing operator-authored files from accidental overwrite.
It runs on Node.js built-ins only. No runtime dependencies are required.
Runtime support for this repository now starts at Node.js 22. Older lines such
as Node.js 18 and 20 are EOL and are no longer supported here.
Quick Navigation
What It Solves
Teams usually hit one of these problems:
- the same repository has different instructions for different agents
- generated files drift and stop being trusted
- existing repositories already contain hand-written agent files, so first-run adoption is risky
- shared skills exist in different folders with no clear canonical owner
Agent Jump Start gives the repository one explicit memory model:
- one canonical spec
- one canonical skill tree
- one
sync command for maintenance
- one
check command for CI drift detection
- one clear overwrite policy for existing repos
Start Here
Install globally:
npm install -g @marcogoldin/agent-jump-start
Upgrade an existing global install:
npm install -g @marcogoldin/agent-jump-start@latest
Use the scoped package name exactly as shown above. The unscoped agent-jump-start
package is not published on npm.
Initialize a repository:
agent-jump-start init --target .
Review the generated canonical spec, then synchronize managed files:
agent-jump-start sync --spec docs/agent-jump-start/canonical-spec.yaml --target .
Use check in CI:
agent-jump-start check --spec docs/agent-jump-start/canonical-spec.yaml --target .
That is the core operating model:
init creates the framework and drafts the canonical spec
sync renders managed outputs, cleans stale files, and verifies convergence
check fails when generated files drift from the canonical spec
doctor helps when a first draft is still too generic
First-Run Experience
init starts guided onboarding by default.
agent-jump-start init --target .
For automation and CI-friendly bootstrap:
agent-jump-start init --non-interactive --target .
Guided onboarding can inspect repository signals such as:
- package manifests and lockfiles
- scripts and Makefiles
- CI workflows
- Docker files
- Python tooling
- lint and formatting configs
- local conventions in repository docs
When no dominant stack is detected, the guided flow also supports three
first-run paths directly from the prompt:
- choose a starter category or preset
- type a raw stack name such as
python
- type
skip for a generic draft when the repo is still script-based or mixed
The guided flow reviews:
- project name and summary
- detected repository components
- package manager and runtime rules
- suggested validation commands
- suggested workspace sections
- review checklist inclusion and enhancements
- agent rollout choice
Every suggestion carries provenance so the operator can see whether it was detected or inferred.
In interactive TTY sessions, choice prompts now support:
- arrow-key navigation
j / k navigation
- typed shortcuts and aliases such as
y, n, edit, or review
When stdin is not a TTY, or when NO_COLOR is set, prompts fall back to the
plain line-based behavior so CI, piping, and low-capability terminals remain
deterministic.
Selective Agent Support
Agent Jump Start can manage all supported agents or a chosen subset.
The operator model is simple:
- the canonical spec is the source of truth
sync, render, and check read only from the spec
init can set the initial agent rollout
update-agents can add, remove, inspect, or reset support later
Default behavior
If agentSupport is missing from the canonical spec, Agent Jump Start supports all agents.
Initialize with all, detected, or explicit agents
agent-jump-start init --target . --agents all
agent-jump-start init --target . --agents detected
agent-jump-start init --target . --agents claude-code,cursor,github-copilot
Guided onboarding offers the same choices interactively.
Add more agents later
agent-jump-start update-agents \
--spec docs/agent-jump-start/canonical-spec.yaml \
--include github-copilot,aider
agent-jump-start update-agents \
--spec docs/agent-jump-start/canonical-spec.yaml \
--remove windsurf,aider
agent-jump-start update-agents \
--spec docs/agent-jump-start/canonical-spec.yaml \
--all-missing
What always stays canonical
These paths are infrastructure and remain managed even when you support only a subset of agents:
.agents/AGENTS.md
.agents/skills/<slug>/
docs/agent-review-checklist.md
docs/agent-jump-start/generated-manifest.json
How the spec stores the choice
{
"agentSupport": {
"mode": "selected",
"selected": ["claude-code", "cursor", "github-copilot"]
}
}
If all agents are enabled, agentSupport is omitted for a cleaner spec.
Existing Repository Adoption
Existing repositories are the main real-world case. Agent Jump Start is designed to adopt them safely.
If the repo already contains hand-written files such as CLAUDE.md, AGENTS.md, .github/copilot-instructions.md, Cursor rules, Windsurf rules, Cline rules, Roo rules, Continue rules, Amazon Q rules, Junie files, or CONVENTIONS.md, the CLI will not silently overwrite them.
A file is treated as Agent Jump Start-managed only when it carries the provenance marker embedded in generated outputs.
Conflict handling
When unmanaged pre-existing files are found:
- interactive TTY sessions prompt per conflict group, not per file
- mirrored skill-package collisions are grouped by skill slug
- other conflicts are grouped by root such as
.github, .claude, .agents, or workspace root
- non-interactive sessions fail closed unless you choose a policy
Supported policies on init, sync, and render:
--force | overwrite pre-existing operator-authored files |
--backup | create <file>.ajs-backup-<timestamp> before overwrite |
--keep-existing | preserve existing files, skip the rendered version, and exclude it from the manifest |
sync --keep-existing has had a distinct exit contract since 2.0.0:
- exit
0: fully converged
- exit
1: failure or blocked write
- exit
2: safe but non-converged because preserved files still need absorb or overwrite
When exit 2 happens, there are two intentional paths:
- discard the hand-edit and rewrite from the current spec with
sync --force
or sync --backup
- keep the intent and promote supported preserved guidance back into the spec
with
promote-preserved
Day-2 preserved recovery flow:
agent-jump-start promote-preserved \
--spec docs/agent-jump-start/canonical-spec.yaml \
--target . \
--dry-run
agent-jump-start promote-preserved \
--spec docs/agent-jump-start/canonical-spec.yaml \
--target . \
--apply \
--selection path/to/proposal.json
agent-jump-start sync \
--spec docs/agent-jump-start/canonical-spec.yaml \
--target .
agent-jump-start check \
--spec docs/agent-jump-start/canonical-spec.yaml \
--target .
Recommended adoption flow
agent-jump-start init --target . --non-interactive --keep-existing
agent-jump-start absorb --spec docs/agent-jump-start/canonical-spec.yaml --target .
agent-jump-start sync --spec docs/agent-jump-start/canonical-spec.yaml --target . --force
Selective adoption in existing repositories
Selective agent support works well with adoption flows:
agent-jump-start init \
--target . \
--non-interactive \
--agents detected \
--keep-existing
If --keep-existing would make one of the selected agents non-convergent, Agent Jump Start removes that agent from the managed selection before writing the spec, so the repository still converges on the first check.
Interactive agent selection (checkbox UX)
During interactive init, after the rollout question answers Choose specific agents, Agent Jump Start opens a zero-dependency checkbox selector that lists every supported agent by human-readable name, canonical id, and short file-layout hint:
? Select agents to support
> [x] Claude Code claude-code CLAUDE.md, .claude/skills/*/SKILL.md
[ ] GitHub Copilot github-copilot .github/copilot-instructions.md, .github/instructions/*.instructions.md
[ ] OpenAI Codex openai-codex AGENTS.md
[ ] Gemini CLI gemini-cli GEMINI.md
...
Use ↑/↓, Space to toggle, Enter to confirm (a=all, n=none)
Keyboard controls:
↑/↓ (or j/k) move the focus
Space toggles the focused agent
a selects all, n clears all
Enter confirms; an empty selection is refused with an actionable hint
Ctrl+C aborts without writing
Fallbacks and compatibility:
--agents all, --agents detected, --agents <id,...>, and --non-interactive are unchanged
- when stdin is not a TTY,
init keeps the existing line-based behavior
- when raw-mode is unavailable (for example when
NO_COLOR is set), init falls back to one-by-one yes/no prompts that explicitly enumerate all 12 agent names with their file hints
Note on the claude-code label: it means Agent Jump Start writes Claude-compatible local files (CLAUDE.md and .claude/skills/). The Anthropic API does not automatically read those files; teams using the API directly can still reuse that file layout if their own integration loads the content into prompts or tool context.
Note on the openai-codex label: it is the official Codex target for repository instructions read from AGENTS.md. The older github-agents id is still accepted as a deprecated alias for existing specs and scripts.
Daily Maintenance
sync is the main maintenance command.
agent-jump-start sync --spec docs/agent-jump-start/canonical-spec.yaml --target .
What it does:
- validates the canonical spec
- renders the current managed output set
- removes stale generated files that are no longer owned
- writes the current output set with overwrite protection
- verifies the final state with the same ground truth that was written
If preserved operator-authored files remain after --keep-existing, sync now exits 2 and prints the exact next-step commands needed to converge.
If you intentionally deselect one or more agents and want their footprints gone
completely, run sync --purge-disabled. This is the explicit full-cleanup path
for disabled agent roots such as .roo/, .continue/, legacy flat files such
as .roorules, and other residual agent-only content that the default safe
cleanup intentionally leaves in place.
check is the read-only CI equivalent:
agent-jump-start check --spec docs/agent-jump-start/canonical-spec.yaml --target .
render is available when you want direct render semantics without the full sync maintenance path:
agent-jump-start render --spec docs/agent-jump-start/canonical-spec.yaml --target . --clean
After upgrading Agent Jump Start
A new Agent Jump Start release updates the generator. Your repository updates only when you run the maintenance commands again.
That is the model:
- upgrading the CLI gives you the new engine
- running
sync applies that engine to the repository
- running
check proves the repository is aligned with the canonical spec
Use this flow after installing a newer release:
agent-jump-start update-skills \
--spec docs/agent-jump-start/canonical-spec.yaml
agent-jump-start sync \
--spec docs/agent-jump-start/canonical-spec.yaml \
--target .
agent-jump-start check \
--spec docs/agent-jump-start/canonical-spec.yaml \
--target .
If you only upgrade the global package or switch to npx @latest, the repository will still contain the previously generated files until you run this flow.
Full cleanup after deselecting agents:
agent-jump-start update-agents \
--spec docs/agent-jump-start/canonical-spec.yaml \
--remove roo-code,continue-dev
agent-jump-start sync \
--spec docs/agent-jump-start/canonical-spec.yaml \
--target . \
--purge-disabled
Common Commands
| Initialize a repo with guided onboarding | agent-jump-start init --target . |
| Initialize non-interactively | agent-jump-start init --non-interactive --target . |
| Start from detected agents in an existing repo | agent-jump-start init --target . --agents detected |
| Re-render and converge managed outputs | agent-jump-start sync --spec docs/agent-jump-start/canonical-spec.yaml --target . |
| Fully remove files for disabled agents | agent-jump-start sync --spec docs/agent-jump-start/canonical-spec.yaml --target . --purge-disabled |
| Fail CI on drift | agent-jump-start check --spec docs/agent-jump-start/canonical-spec.yaml --target . |
| Promote supported preserved intent back into the spec | agent-jump-start promote-preserved --spec docs/agent-jump-start/canonical-spec.yaml --target . --dry-run |
| Diagnose a weak or generic spec | agent-jump-start doctor --spec docs/agent-jump-start/canonical-spec.yaml |
| Review repository evidence | agent-jump-start infer --target . |
| Generate a schema-shaped overlay | agent-jump-start infer-overlay --target . --base canonical-spec.yaml --output overlay.yaml |
| Absorb existing agent files into canonical memory | agent-jump-start absorb --spec docs/agent-jump-start/canonical-spec.yaml --target . |
| Review or import local skill packages | agent-jump-start intake --spec docs/agent-jump-start/canonical-spec.yaml |
| Import one explicit skill package | agent-jump-start import-skill --spec docs/agent-jump-start/canonical-spec.yaml --skill path/to/skill-directory |
| Add more managed agents later | agent-jump-start update-agents --spec docs/agent-jump-start/canonical-spec.yaml --include github-copilot,aider |
| Remove managed agents from an existing setup | agent-jump-start update-agents --spec docs/agent-jump-start/canonical-spec.yaml --remove windsurf,aider |
| Inspect valid canonical agent IDs | agent-jump-start list-agents |
| Inspect canonical agent IDs with current project state | agent-jump-start list-agents --spec docs/agent-jump-start/canonical-spec.yaml |
Supported Agents
| Claude Code | CLAUDE.md, .claude/skills/*/SKILL.md |
| GitHub Copilot | .github/copilot-instructions.md, .github/instructions/general.instructions.md, .github/skills/*/SKILL.md |
| Gemini CLI | GEMINI.md |
| Amazon Q Developer | .amazonq/rules/general.md |
| JetBrains Junie | .junie/AGENTS.md, .junie/guidelines.md |
| OpenAI Codex | AGENTS.md (AGENT.md is kept only as legacy Agent Jump Start compatibility output) |
| Cursor | .cursor/rules/agent-instructions.mdc, .cursor/rules/*.mdc, canonical .agents/skills/*/SKILL.md |
| Windsurf | .windsurf/rules/general.md, .windsurfrules |
| Cline | .clinerules/general.md, .clinerules when legacy fallback is required |
| Roo Code | .roo/rules/agent-instructions.md, .roorules |
| Continue.dev | .continue/rules/agent-instructions.md |
| Aider | CONVENTIONS.md |
Notes:
.agents/AGENTS.md is the canonical workspace instruction file
.agents/skills/ is the canonical skill package tree and is also an official Cursor skill location
.claude/skills/ and .github/skills/ are mirrors of the canonical packages
- for GitHub Copilot,
.github/copilot-instructions.md is the official repository-wide instruction file; .github/instructions/general.instructions.md and .github/skills/ are extended generated projections kept for compatibility
- agents without native skill-package support receive workspace guidance plus inline skill summaries
Skill Packages
Agent Jump Start supports portable skill packages with a SKILL.md entrypoint and optional references/, scripts/, and assets/ folders.
Plain-language rule:
- normal path: use
add-skill or import-skill, then run sync
- recovery path: use
intake only when a skill was copied into local agent folders by hand or by another tool
- migration path: use
absorb when existing hand-written agent instruction files need to become canonical workspace instructions
- day-2 promotion path: after
sync --keep-existing, use promote-preserved to promote supported preserved guidance back into the canonical spec
In normal day-to-day use, sync is the command that propagates canonically managed skills to the supported agents. absorb and intake are adoption helpers, not required steps after a successful add-skill or import-skill.
Import one skill
agent-jump-start import-skill \
--spec docs/agent-jump-start/canonical-spec.yaml \
--skill path/to/skill-directory
agent-jump-start import-skill \
--spec docs/agent-jump-start/canonical-spec.yaml \
--skill path/to/skill-directory \
--replace
Supported import sources:
- a skill directory
- a standalone
SKILL.md file
- an installed local skill package
- a legacy JSON skill file
During import, display-style skill names in SKILL.md frontmatter are normalized
to canonical slugs automatically. For example, name: Python Pro becomes
python-pro in canonical memory while the human-readable title remains
Python Pro.
Each successful import updates agent-jump-start.lock.json next to the spec. The lockfile records slug, version, checksum, source, and resolved path.
Validate a skill before import
Use validate-skill to check whether a skill is structurally valid and
canonically import-compatible before writing it into the spec.
agent-jump-start validate-skill path/to/skill-directory
agent-jump-start validate-skill path/to/SKILL.md
agent-jump-start validate-skill path/to/SKILL.md --frontmatter-only
Default behavior:
- checks the same canonical import-compatibility path used by
import-skill
- works for both skill directories and standalone
SKILL.md files
- exits
0 only when canonical import would accept the skill
- rejects Agent Jump Start generated mirrors with an explicit recovery hint to import the raw upstream skill instead
--frontmatter-only is the opt-in legacy path when you want only the old
frontmatter shape check in CI.
Adopt locally installed skills
Use intake when another tool already wrote skills into local agent folders and you want Agent Jump Start to make them canonical.
agent-jump-start intake \
--spec docs/agent-jump-start/canonical-spec.yaml
agent-jump-start intake \
--spec docs/agent-jump-start/canonical-spec.yaml \
--import
agent-jump-start intake \
--spec docs/agent-jump-start/canonical-spec.yaml \
--import --replace
Important distinction:
- installed locally means a skill exists on disk under
.agents/skills/, .cursor/skills/, .claude/skills/, or .github/skills/
- managed canonically means the skill is present in the canonical spec and tracked in the lockfile
sync propagates only canonically managed skills
intake reports invalid local skills with explicit reasons instead of importing them blindly
- local mirrors previously generated by Agent Jump Start are treated as invalid import sources and must be replaced with the raw upstream skill package
Add a skill from a higher-level source
add-skill resolves a higher-level source into a local package, then imports it into the canonical spec.
agent-jump-start add-skill \
./external-skills/python-pro \
--spec docs/agent-jump-start/canonical-spec.yaml
agent-jump-start add-skill \
https://github.com/Jeffallan/claude-skills/tree/main/skills/python-pro \
--spec docs/agent-jump-start/canonical-spec.yaml
agent-jump-start add-skill \
github:vercel-labs/agent-skills \
--skill web-design-guidelines \
--spec docs/agent-jump-start/canonical-spec.yaml
agent-jump-start add-skill \
skills:vercel-labs/agent-skills \
--skill web-design-guidelines \
--spec docs/agent-jump-start/canonical-spec.yaml
agent-jump-start add-skill \
skillfish:nguyenthienthanh/aura-frog \
--skill nodejs-expert \
--spec docs/agent-jump-start/canonical-spec.yaml
Supported add-skill sources:
- local filesystem paths
- GitHub URLs and
github:<owner>/<repo> shorthand
skills:<package> providers resolved with the skills CLI
skillfish:<package> providers resolved with Skillfish
Notes:
skills: and skillfish: adapters require npx on PATH
- GitHub sources require
git on PATH
- successful
add-skill imports also update the lockfile with provenance metadata
- local paths that point at
.claude/skills/<slug>, .agents/skills/<slug>, or other Agent Jump Start generated mirrors are rejected; import the raw upstream skill source instead
Refresh imported skills
agent-jump-start update-skills \
--spec docs/agent-jump-start/canonical-spec.yaml \
--dry-run
agent-jump-start update-skills \
--spec docs/agent-jump-start/canonical-spec.yaml
agent-jump-start update-skills \
--spec docs/agent-jump-start/canonical-spec.yaml \
--skill python-pro
update-skills uses the lockfile as the provenance source of truth and updates the spec only when the source actually changed.
If a tracked source resolves to an Agent Jump Start generated mirror instead of the raw upstream package, the refresh is refused rather than risking canonical-spec corruption.
Export a skill
agent-jump-start export-skill \
--spec docs/agent-jump-start/canonical-spec.yaml \
--slug python-pro \
--output ./exported-skills/python-pro
Layered Specs
Layered specs are useful for monorepos or shared-base setups.
The model is simple:
- the base owns shared rules
- each leaf owns what is specific to that package or app
- mutating commands write back only to the leaf
- validation errors identify the layer that owns the failing field
This now also applies to agent selection state. A leaf can narrow, expand, or reset inherited agentSupport safely.
References:
Architecture At A Glance
docs/agent-jump-start/canonical-spec.yaml | canonical project memory |
.agents/AGENTS.md | canonical workspace instruction file |
.agents/skills/<slug>/ | canonical skill packages |
| agent-specific mirrors | projections for each supported ecosystem |
docs/agent-jump-start/generated-manifest.json | current managed file set for cleanup and drift detection |
docs/agent-jump-start/agent-jump-start.lock.json | imported skill provenance and refreshable sources |
Minimal Spec Example
{
"schemaVersion": 1,
"project": {
"name": "Example Repo",
"summary": "Example project using Agent Jump Start.",
"components": [
"api: Python 3.11 service",
"web: React frontend"
]
},
"workspaceInstructions": {
"packageManagerRule": "Use the package manager already chosen by the repository.",
"runtimeRule": "Keep local development and CI on the same runtime versions.",
"sections": [
{
"title": "General rules",
"rules": [
"Prefer small, reviewable changes.",
"Update docs when setup or runtime behavior changes."
]
}
],
"validation": [
"npm test"
]
},
"reviewChecklist": {
"intro": "Review generated changes against repository-specific constraints.",
"failureThreshold": 2,
"items": [
{
"title": "Uses repository constraints",
"details": [
"The change should follow the real stack and validation commands."
]
}
],
"quickSignals": [
"Generated files remain in sync."
],
"redFlags": [
"Hand-edited generated instruction files."
]
},
"skills": []
}
CLI Reference
Global commands
agent-jump-start --help | Show the full command reference |
agent-jump-start --version | Show the CLI version |
agent-jump-start list-agents | Show canonical agent ids and display names |
agent-jump-start list-agents --spec <path> | Show enabled/disabled status for a specific canonical spec |
agent-jump-start list-profiles | List bundled starter profiles |
Bootstrap and maintenance
| `agent-jump-start init [--profile ] [--target ] [--non-interactive] [--agents all | detected |
agent-jump-start bootstrap --base <path> [--profile <path>] [--output <path>] | Create a spec from a base/profile pair without running guided init |
| `agent-jump-start sync --spec [--target ] [--purge-disabled] [--force | --backup |
| `agent-jump-start render --spec [--target ] [--clean] [--purge-disabled] [--force | --backup |
agent-jump-start check --spec <path> [--target <path>] | Validate that generated files still match the canonical spec |
agent-jump-start validate --spec <path> | Validate canonical spec structure without writing files |
agent-jump-start doctor --spec <path> [--suggest --target <path>] | Diagnose weak or overly generic specs |
Adoption, recovery, and lifecycle
agent-jump-start absorb --spec <path> [--target <path>] [--preserved-only] [--dry-run] [--output <path>] [--apply --selection <path>] | Absorb existing agent guidance into canonical memory |
agent-jump-start promote-preserved --spec <path> [--target <path>] [--dry-run] [--output <path>] [--apply --selection <path>] | Promote supported preserved guidance back into the spec |
agent-jump-start update-agents --spec <path> [--include <id,...>] [--remove <id,...>] [--all-missing] [--mode all] | Add, remove, or reset supported agents over time |
agent-jump-start sync --spec <path> [--target <path>] --purge-disabled | Fully remove files for disabled agents, including residual agent-only directories |
Inference and overlays
| `agent-jump-start infer --target [--output ] [--section ] [--format json | text]` |
agent-jump-start infer-overlay --target <path> [--output <path>] [--base <path>] [--section <name>] | Generate a schema-shaped overlay from repository evidence |
Skills and schema
agent-jump-start validate-skill <path> [--frontmatter-only] | Validate a skill package or standalone SKILL.md |
agent-jump-start intake --spec <path> [--target <path>] [--import] [--replace] | Review and optionally import locally discovered skill packages |
agent-jump-start import-skill --spec <path> --skill <path> [--replace] | Import one explicit local skill package |
agent-jump-start add-skill <source> --spec <path> [--skill <name>] [--replace] [--provider <name>] | Import a skill from a higher-level source such as GitHub or a registry |
agent-jump-start export-skill --spec <path> --slug <name> --output <path> | Export a canonical skill into a standalone package |
agent-jump-start update-skills --spec <path> [--skill <slug>] [--dry-run] | Refresh upstream-tracked imported skills |
agent-jump-start export-schema [--output <path>] | Export the canonical JSON Schema |
Demo utilities
agent-jump-start demo-clean --target <path> | Remove a generated demo tree |
agent-jump-start demo-tree --target <path> | Create a demo tree for inspection |
Requirements
- Node.js >= 22
- npm for installation and distribution
- no runtime dependencies required
- interactive TTY menus stay zero-dependency and use the native Node.js terminal APIs
Production note:
- use a currently supported Node.js line only; this repository now targets Node.js 22+ because earlier lines used here are already beyond maintenance
Installation Options
| Global install | daily use on one machine | npm install -g @marcogoldin/agent-jump-start |
npx | one-off execution | npx @marcogoldin/agent-jump-start@latest <command> |
| Vendored in-repo copy | teams that want the toolkit committed inside the repo | git clone https://github.com/marcogoldin/agent-jump-start.git docs/agent-jump-start |
The most reliable execution paths are the global agent-jump-start binary and vendored usage via node docs/agent-jump-start/scripts/agent-jump-start.mjs.
Installing a newer Agent Jump Start version updates the generator on your machine. It does not rewrite files that were already generated inside a repository. After upgrading, run the repository maintenance flow in that repo so the generated outputs, manifest, and managed skills all move to the new release together.
Use npm install -g @marcogoldin/agent-jump-start@latest for upgrades; agent-jump-start without the @marcogoldin/ scope is not an npm package.
Current Limitations
sync, render, and check do not accept transient --agents overrides. Agent selection belongs to canonical spec state.
sync --keep-existing is now explicit about non-convergence: when preserved operator-authored files remain, the command exits 2 and expects a follow-up promote-preserved, sync --force, or sync --backup.
sync --purge-disabled is the explicit destructive cleanup path for deselected agents. Without it, residual agent-specific unmanaged content is intentionally left in place and reported instead of being deleted silently.
promote-preserved is the supported day-2 recovery path for preserved files and intentionally stays limited to workspaceInstructions.sections and workspaceInstructions.validation.
absorb --preserved-only remains available as the lower-level equivalent of promote-preserved.
intake --import --replace is provenance-safe. Upstream-tracked skills are not downgraded to local-only provenance.
validate-skill --frontmatter-only is intentionally weaker than the default canonical import check and exists only for legacy CI workflows that still want the old frontmatter-only contract.
- generated Agent Jump Start skill mirrors are intentionally rejected by
validate-skill, import-skill, add-skill, intake --import, and update-skills; the raw upstream skill remains the only supported source of truth for import and refresh
- Gemini, Amazon Q, Junie, Continue, Aider, Windsurf, Cline, and Roo Code do not receive native skill packages; they receive workspace guidance plus inline skill summaries.
absorb v1 intentionally targets workspaceInstructions.sections and workspaceInstructions.validation only.
- direct
npx @marcogoldin/agent-jump-start@latest ... execution may vary across npm environments; global install and vendored usage are the most reliable paths.
Portability
The content model is stack-agnostic. Node.js is only the generator runtime.
If a team wants a different implementation language, it can preserve:
- the canonical spec format
- the generated file layout
- the synchronization model
Testing
npm test
The automated suite covers core workflows, sync convergence, overwrite protection, guided onboarding, inference, layered specs, leaf-only writeback, skill import and export, provenance lockfiles, absorb flows, grouped conflict prompts, selective agent support, full agent lifecycle management, disabled-agent purge cleanup, generated-skill re-import rejection, and regression cases from real existing-repository adoption.
Contributing
- Create a branch.
- Make the smallest coherent change that solves one problem.
- Run
npm test.
- Update
README.md when user-visible behavior changes.
- Open a pull request.
License
Mozilla Public License 2.0