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
• Start Here
• First-Run Experience
• Selective Agent Support
• Existing Repository Adoption
• Daily Maintenance
• Common Commands
• Skill Packages
• Layered Specs
• Architecture At A Glance
• CLI Reference
• Requirements
• Installation Options
• Current Limitations
• Testing
• Contributing

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

# Support every agent target
agent-jump-start init --target . --agents all

# In an existing repo, detect current agent usage and start there
agent-jump-start init --target . --agents detected

# Start with an explicit subset
agent-jump-start init --target . --agents claude-code,cursor,github-copilot

Guided onboarding offers the same choices interactively.

Add more agents later

# Add one or more missing agents
agent-jump-start update-agents \
  --spec docs/agent-jump-start/canonical-spec.yaml \
  --include github-copilot,aider

# Remove one or more enabled agents
agent-jump-start update-agents \
  --spec docs/agent-jump-start/canonical-spec.yaml \
  --remove windsurf,aider

# Reset to full coverage
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:

| Flag | Effect | |---|---| | --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:

# Start from agents already present in the repository
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:

1. validates the canonical spec
2. renders the current managed output set
3. removes stale generated files that are no longer owned
4. writes the current output set with overwrite protection
5. 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:

# Optional: refresh upstream-tracked skills first
agent-jump-start update-skills \
  --spec docs/agent-jump-start/canonical-spec.yaml

# Rewrite the managed output set with the new generator version
agent-jump-start sync \
  --spec docs/agent-jump-start/canonical-spec.yaml \
  --target .

# Confirm the repository is fully aligned
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

| If you want to... | Command | |---|---| | 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

| Agent | Generated output | |---|---| | 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.

# Review local skill packages
agent-jump-start intake \
  --spec docs/agent-jump-start/canonical-spec.yaml

# Import all valid unmanaged skills
agent-jump-start intake \
  --spec docs/agent-jump-start/canonical-spec.yaml \
  --import

# Replace canonically managed local skills when appropriate
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.

# Local path
agent-jump-start add-skill \
  ./external-skills/python-pro \
  --spec docs/agent-jump-start/canonical-spec.yaml

# GitHub tree URL
agent-jump-start add-skill \
  https://github.com/Jeffallan/claude-skills/tree/main/skills/python-pro \
  --spec docs/agent-jump-start/canonical-spec.yaml

# Repository shorthand plus explicit skill name
agent-jump-start add-skill \
  github:vercel-labs/agent-skills \
  --skill web-design-guidelines \
  --spec docs/agent-jump-start/canonical-spec.yaml

# Through the open skills CLI
agent-jump-start add-skill \
  skills:vercel-labs/agent-skills \
  --skill web-design-guidelines \
  --spec docs/agent-jump-start/canonical-spec.yaml

# Through Skillfish
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

# Preview
agent-jump-start update-skills \
  --spec docs/agent-jump-start/canonical-spec.yaml \
  --dry-run

# Refresh every tracked skill
agent-jump-start update-skills \
  --spec docs/agent-jump-start/canonical-spec.yaml

# Refresh one tracked skill
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:

• operator guide: docs/layered-specs.md
• copyable example: specs/examples/monorepo/

Architecture At A Glance

| Source of truth | Purpose | |---|---| | 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

| Command | Purpose | |---|---| | 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

| Command | Purpose | |---|---| | agent-jump-start init [--profile <path>] [--target <path>] [--non-interactive] [--agents all|detected|<id,...>] | Bootstrap a repository and draft a canonical spec | | 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 <path> [--target <path>] [--purge-disabled] [--force | --backup | --keep-existing] | Render, clean, and verify the managed output set | | agent-jump-start render --spec <path> [--target <path>] [--clean] [--purge-disabled] [--force | --backup | --keep-existing] | Render directly without the full sync maintenance path | | 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

| Command | Purpose | |---|---| | 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

| Command | Purpose | |---|---| | agent-jump-start infer --target <path> [--output <path>] [--section <name>] [--format json|text] | Inspect repository evidence and suggest validation or guidance | | agent-jump-start infer-overlay --target <path> [--output <path>] [--base <path>] [--section <name>] | Generate a schema-shaped overlay from repository evidence |

Skills and schema

| Command | Purpose | |---|---| | 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

| Command | Purpose | |---|---| | 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

| Install path | Best for | Command | |---|---|---| | 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

1. Create a branch.
2. Make the smallest coherent change that solves one problem.
3. Run npm test.
4. Update README.md when user-visible behavior changes.
5. Open a pull request.

License

Mozilla Public License 2.0