跳转至

简体中文

Quickstart

This page gives ordinary developers three executable journeys: discovering capabilities and generating a new project, adopting an existing project, and querying one requirement during daily work. Each journey includes exact commands; architecture routing and API details live in the linked references.

Choose the entry point before running a command:

  • If the input is a natural-language requirement and it is unclear whether Foundation already covers it, call the single foundation-adoption-review Skill. Supply an explicit exact Foundation version, a same-version capability-catalog query result, and an adopt-plan result. The Skill diagnoses read-only; it does not install, initialize, run check, or probe qualification.
  • If the target root needs a complete static engineering review, or an existing Foundation proof must be read, call foundation-engineering-check. It reviews selected engineering declarations, public capability adoption, and call boundaries, then projects a shared conclusion with check proof-create. Read an old proof with check proof. Passing the two mechanical version and entry branches is not a full Foundation pass.
  • If the capability ID is known and the target is an empty directory, use scaffold.
  • If an existing project needs an inventory of structure, conflicts, and migration conditions, start with read-only adopt-plan. Decide later whether to authorize projection or let the project modify existing files itself.
  • If declarations must be compared with physical files, use check. It performs static governance checks without running target Skills, business scripts, or hooks.

stable in the capability catalog means that the entry point is stable in the queried release; candidate remains a candidate. A candidate match, migration complete, source present in a local tree, or passing development self-tests does not by itself prove publication, whole-host control, or target-project compliance. Read the current release and candidate boundary only from Current Product Status and the exact-version capability catalog.

Shared Installation Prerequisite

For local candidate validation, build the three current-version tarballs from the Foundation workspace and install them into a temporary consumer. Run these commands from the Foundation workspace root; foundation_version reads the root package.json and supplies the version for all three tarballs:

foundation_version="$(node -p "require('./package.json').version")"
pack_dir="$(mktemp -d)"
(cd packages/skill-family-contracts && pnpm pack --pack-destination "$pack_dir")
(cd packages/skill-family-harness-node && pnpm pack --pack-destination "$pack_dir")
(cd packages/skill-family-engineering-kit && pnpm pack --pack-destination "$pack_dir")
mkdir "$pack_dir/consumer" && (cd "$pack_dir/consumer" && npm init -y)
(cd "$pack_dir/consumer" && npm install "$pack_dir/skill-family-contracts-${foundation_version}.tgz" "$pack_dir/skill-family-harness-node-${foundation_version}.tgz" "$pack_dir/skill-family-engineering-kit-${foundation_version}.tgz")

After publication, install the exact coordinates listed on the Current Product Status page, then run the npm exec commands below.

New Project: Discover Capabilities and Generate a Skeleton

Start by evaluating the project's uses, then select stable capabilities explicitly. --list-capabilities is read-only; the --uses file should contain problems, constraints, retained guarantees, and optional filters, never credentials or private business data.

npm exec -- skill-family-kit adopt-plan --list-capabilities --all --scope all --locale en --uses ./uses.json
npm exec -- skill-family-kit scaffold --root ./my-project --project-id my-project --capability foundation.contracts.object-validation --capability foundation.harness.atomic-write
npm exec -- skill-family-kit check --root ./my-project

supportedMatches is candidate discovery only, and needsDecision means that the project still has to confirm the use. The command does not write a Profile or claim adoption. A successful scaffold means that the skeleton and contract-test wiring were written; the adapter, domain guarantee, and consumer tests remain to be completed.

Existing Project: Adopt and Complete Migration

Run read-only adopt-plan first, then record uses and one of the four decision dispositions in the migration manifest. Only direct-adoption and compatibility-layer may target a Foundation capability; keep-business and foundation-gap stay with the consumer.

npm exec -- skill-family-kit adopt-plan --root ./existing-repo
npm exec -- skill-family-kit adopt-plan --root ./existing-repo --list-capabilities --all --scope all --locale en --uses ./uses.json
npm exec -- skill-family-kit check --root ./existing-repo

adopt-plan writes no files and does not migrate automatically. Migration state complete means that the Profile, managed files, legacy exit, checks, and four evidence classes are all satisfied; it does not mean contract integration is complete. The consumer's adapter tests and domain gate must state that conclusion.

Reference-skeleton comparison reports structural differences; it does not turn the reference layout into a mandatory standard for every language, release shape, or host. Published checks still carry existing Foundation engineering-policy assumptions, including version-source and entry-shape conventions. A single package, an independently versioned package, a Python project, or another non-npm version source should first use adoption diagnosis to establish policy fit. Do not reshape it into this repository's private parent-workspace topology merely because a legacy-policy check reports findings.

Daily Work: Query One Requirement

When the capability ID is unknown, use a deterministic substring query in the intended language. An empty result is no-text-match; a result containing only unsupported capabilities is boundary-found. Neither result creates a foundation-gap decision.

npm exec -- skill-family-kit adopt-plan --list-capabilities --locale en --filter "must not leave a partial file when a write fails"

To establish real-host qualification, provide a complete request, bindings, and --native to the explicit qualification sub-action:

npm exec -- skill-family-kit check qualification \
  --root <consumer-repo> \
  --capability foundation.kit.plugin-verification \
  --request <request-json> \
  --bindings <private-bindings-json> \
  --native

The real qualification claim comes only from one explicit, bounded host execution. Candidate discovery, migration complete, and contract integration do not replace it.

Legacy Short Path: Generate a Skeleton

If the project has already confirmed that a uses assessment is unnecessary, it can still generate a compliant skeleton directly.

npm exec -- skill-family-kit scaffold --root ./my-project --project-id my-project
npm exec -- skill-family-kit check --root ./my-project

The commands above first generate a skeleton, then run engineering diagnostics on the generated result. scaffold writes only to an empty target directory; a non-empty or conflicting target is refused and not touched; check diagnoses only, it does not fix. Verification passes when check exits with code 0.

Existing Project: Read-Only Inventory (Compatibility Entry)

The goal is to first see whether the existing repository can be adopted, without changing any bytes.

npm exec -- skill-family-kit adopt-plan --root ./existing-repo
npm exec -- skill-family-kit check --root ./existing-repo

adopt-plan outputs the current state, target Profile, exact write set, conflicts, and the legacy-implementation exit list, with zero change to the input repository's bytes. check performs read-only diagnostics only. Decide whether to perform a write after confirming the inventory results.

Architecture Designer: Decide Ownership

The goal is to determine which Foundation layer an architecture requirement should land in, or whether it should stay with the consumer.

  1. Read the eight-step decision order in docs/agents/architecture-routing.md.
  2. In docs/agents/capability-catalog.json, find the capability by layer and intent, and read its entrypoints, sideEffects, failureSemantics, ownedByCaller.
  3. When publishing, task lifecycle, or artifact relationships are involved, route to release-skill, loop-agent, and artifact-graph respectively.

The hard boundary of routing: Foundation does not own remote writes, business state machines, model orchestration, or domain-audit semantics. Capabilities that fall into keep-business or foundation-gap do not forcibly expand Foundation.

Path containment, usage estimation, and upper-bound guards cover only the calls routed through them. The caller still routes all relevant reads through the entry point, defines usage events and limits, and decides what to do after a limit is exceeded. Foundation does not turn those mechanisms into a claim of comprehensive cross-language governance, cross-host permission intersection, or a security sandbox.

Authoritative Facts and Specifications

  • Current product status (versions, package set, mirror coordinates, gates): Current Product Status (the single status page; not duplicated here).
  • Development and commit specifications: Git Lifecycle Guide.

Path Reference

Reader Starting point Next step
New project scaffold check → integrate Profile
Existing project adopt-plan classify (direct-adoption / compatibility-layer / keep-business / foundation-gap) → adopt
Architecture designer routing decision capability catalog → real exports and tests

Windows support and prerequisites

Set up a native Windows 11 x64 environment using local NTFS and a standard user account. Use the exact native runtime and package-manager versions in the compatibility matrix, with exact version alignment across all leaf packages. Prebuilt binaries are loaded without compilation. Do not use WSL as a substitute for native Windows qualification.