Stack Pack Contract

Purpose #

Quick-reference excerpt of the StackPack interface, the manifest, the contribution rules, and per-method conformance. Authoritative: .docs/docs/specs/stack-pack-contract.md.

The interface #

import type {
  StackPackManifest, DetectContext, DetectionResult,
  ProjectContext, SkillTemplate, ValidationCommand, ArchitecturePatternHint,
} from '@aidokit/core';

export interface StackPack {
  readonly manifest: StackPackManifest;

  detect(ctx: DetectContext): Promise<DetectionResult>;
  suggestSkills(ctx: ProjectContext): SkillTemplate[];
  suggestMCPs(ctx: ProjectContext): string[];
  suggestValidationCommands(ctx: ProjectContext): ValidationCommand[];

  defaultArchitecturePattern?(ctx: ProjectContext): ArchitecturePatternHint;
}

Stateless const objects. Stack packs MUST NOT emit files directly — they contribute data; the adapter emits (ADR-0006 §2).

The manifest #

export interface StackPackManifest {
  name: string;                                  // kebab-case
  displayName: string;
  languages: string[];                           // ['typescript', 'javascript']
  specVersion: '2.0';
  sdkVersion: string;
  conformance: 'minimum' | 'standard' | 'strict';
  packVersion: string;
  maintainer: { name: string; url?: string; email?: string };
  detectionSignals: { files?: string[]; manifestDeps?: string[]; configFiles?: string[] };
  composesWith?: string[];                       // e.g. ['react', 'next-js', 'vue']
}

At-rest form is stack-pack.md with YAML frontmatter.

Method specifications #

Full per-method MUST/SHOULD/MAY in .docs/docs/specs/stack-pack-contract.md §8.

Supporting types (one-liners) #

• DetectContext — { projectRoot, fileExists, readFile, readManifest, glob, manifestHasDep, os }. No shell, no network.
• DetectionResult — { matched, confidence: 'high' | 'medium' | 'low' | 'none', extras?, reason? }.
• SkillTemplate — same shape as in adapter contract; for packs: source: 'stack-pack', sourcePackId set, required: false unless the stack cannot function without it.
• ValidationCommand — { id, label, command, kind: 'lint' | 'typecheck' | 'test' | 'format-check' | 'build' | 'other', ciSafe, speed: 'fast' | 'medium' | 'slow' }.
• ArchitecturePatternHint — { pattern, rationale, suggestedLayout: string[], strength: 'opinionated' | 'default' }.

Cardinal rules (from ADR-0006) #

1. No file emission. Packs return data; adapters emit.
2. No shell, no network. DetectContext is the only filesystem surface.
3. Reference catalog MCP ids only. No inline MCP definitions.
4. No security-sensitive MCP suggestions. Per mcp-catalog §10.3.
5. <REVIEW REQUIRED> markers for opinionated skill content so users know what to confirm.
6. Determinism. Same context + same filesystem = same output.

Composability #

Multiple packs can match. The CLI:

• Shows matches at medium confidence or higher.
• Default-selects high matches.
• Allows user override.

Conflicts (e.g. two packs proposing different id: 'test' commands) are surfaced to the user; the highest-confidence pack's suggestion wins by default. See .docs/docs/specs/stack-pack-contract.md §10.3.

Worked example #

The node-ts pack is the canonical example. Skim:

• packages/stack-pack-node-ts/src/index.ts — the const-object pattern
• packages/stack-pack-node-ts/src/detect.ts — tsconfig.json + typescript dep combination
• packages/stack-pack-node-ts/src/skills.ts — five <REVIEW REQUIRED>-marked skills
• packages/stack-pack-node-ts/src/validation.ts — package-manager detection from lockfile

Full reference: .docs/docs/specs/stack-pack-contract.md §16.

Related Pages #

• adapter-contract.md
• conformance-reference.md
• ../concepts/adapters-and-stack-packs.md
• .docs/docs/specs/stack-pack-contract.md
• ADR-0006