@ryuenn3123/agentic-senior-core 1.9.1 → 1.9.3

package/lib/cli/compiler.mjs

@@ -0,0 +1,204 @@
+/**
+ * Context Compiler — Rulebook compilation and state persistence.
+ * Depends on: constants.mjs, utils.mjs, skill-selector.mjs
+ */
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+import {
+  CLI_VERSION,
+  POLICY_FILE_NAME,
+  SKILL_PLATFORM_INDEX_PATH,
+} from './constants.mjs';
+
+import {
+  pathExists,
+  collectFileNames,
+} from './utils.mjs';
+
+import {
+  inferSkillDomainNamesFromSelection,
+  buildSkillPackSection,
+} from './skill-selector.mjs';
+
+export async function writeSelectedPolicy(targetDirectoryPath, selectedProfileName) {
+  const policyFilePath = path.join(targetDirectoryPath, '.agent-context', 'policies', POLICY_FILE_NAME);
+  const parsedPolicy = JSON.parse(await fs.readFile(policyFilePath, 'utf8'));
+  parsedPolicy.selectedProfile = selectedProfileName;
+  await fs.writeFile(policyFilePath, JSON.stringify(parsedPolicy, null, 2) + '\n', 'utf8');
+}
+
+export async function writeOnboardingReport({
+  targetDirectoryPath,
+  selectedProfileName,
+  selectedProfilePack,
+  selectedPreset,
+  selectedStackFileName,
+  selectedBlueprintFileName,
+  includeCiGuardrails,
+  setupDurationMs,
+  projectDetection,
+  selectedSkillDomains = [],
+  operationMode = 'init',
+}) {
+  const onboardingReportPath = path.join(targetDirectoryPath, '.agent-context', 'state', 'onboarding-report.json');
+  const onboardingReport = {
+    cliVersion: CLI_VERSION,
+    generatedAt: new Date().toISOString(),
+    operationMode,
+    selectedProfile: selectedProfileName,
+    selectedProfilePack: selectedProfilePack
+      ? {
+        name: selectedProfilePack.slug,
+        sourceFile: selectedProfilePack.fileName,
+      }
+      : null,
+    selectedPreset,
+    selectedStack: selectedStackFileName,
+    selectedBlueprint: selectedBlueprintFileName,
+    ciGuardrailsEnabled: includeCiGuardrails,
+    setupDurationMs,
+    selectedSkillDomains,
+    autoDetection: {
+      recommendedStack: projectDetection.recommendedStackFileName,
+      recommendedBlueprint: projectDetection.recommendedBlueprintFileName,
+      confidenceLabel: projectDetection.confidenceLabel,
+      confidenceScore: projectDetection.confidenceScore,
+      confidenceGap: projectDetection.confidenceGap,
+      detectionReasoning: projectDetection.detectionReasoning,
+      rankedCandidates: projectDetection.rankedCandidates,
+      evidence: projectDetection.evidence,
+    },
+  };
+
+  await fs.writeFile(onboardingReportPath, JSON.stringify(onboardingReport, null, 2) + '\n', 'utf8');
+}
+
+export async function loadOnboardingReportIfExists(targetDirectoryPath) {
+  const onboardingReportPath = path.join(targetDirectoryPath, '.agent-context', 'state', 'onboarding-report.json');
+  if (!(await pathExists(onboardingReportPath))) {
+    return null;
+  }
+
+  const onboardingReportContent = await fs.readFile(onboardingReportPath, 'utf8');
+  return JSON.parse(onboardingReportContent);
+}
+
+export async function buildCompiledRulesContent({
+  targetDirectoryPath,
+  selectedProfileName,
+  selectedStackFileName,
+  selectedBlueprintFileName,
+  includeCiGuardrails,
+}) {
+  const resolvedTargetDirectoryPath = path.resolve(targetDirectoryPath);
+  const selectedRulesDirectoryPath = path.join(resolvedTargetDirectoryPath, '.agent-context', 'rules');
+  const selectedStacksDirectoryPath = path.join(resolvedTargetDirectoryPath, '.agent-context', 'stacks');
+  const selectedBlueprintsDirectoryPath = path.join(resolvedTargetDirectoryPath, '.agent-context', 'blueprints');
+  const selectedStateDirectoryPath = path.join(resolvedTargetDirectoryPath, '.agent-context', 'state');
+  const selectedReviewDirectoryPath = path.join(resolvedTargetDirectoryPath, '.agent-context', 'review-checklists');
+  const skillPlatformIndex = JSON.parse(await fs.readFile(SKILL_PLATFORM_INDEX_PATH, 'utf8'));
+  const selectedSkillDomainNames = inferSkillDomainNamesFromSelection(selectedStackFileName, selectedBlueprintFileName);
+
+  const universalRuleFileNames = await collectFileNames(selectedRulesDirectoryPath);
+  const contextBlocks = [];
+
+  for (const universalRuleFileName of universalRuleFileNames) {
+    const universalRuleFilePath = path.join(selectedRulesDirectoryPath, universalRuleFileName);
+    const universalRuleContent = await fs.readFile(universalRuleFilePath, 'utf8');
+
+    contextBlocks.push(
+      `## UNIVERSAL RULE: ${universalRuleFileName}\nSource: .agent-context/rules/${universalRuleFileName}\n\n${universalRuleContent.trim()}`
+    );
+  }
+
+  const stackFilePath = path.join(selectedStacksDirectoryPath, selectedStackFileName);
+  const stackContent = await fs.readFile(stackFilePath, 'utf8');
+  contextBlocks.push(
+    `## STACK PROFILE: ${selectedStackFileName}\nSource: .agent-context/stacks/${selectedStackFileName}\n\n${stackContent.trim()}`
+  );
+
+  const blueprintFilePath = path.join(selectedBlueprintsDirectoryPath, selectedBlueprintFileName);
+  const blueprintContent = await fs.readFile(blueprintFilePath, 'utf8');
+  contextBlocks.push(
+    `## BLUEPRINT PROFILE: ${selectedBlueprintFileName}\nSource: .agent-context/blueprints/${selectedBlueprintFileName}\n\n${blueprintContent.trim()}`
+  );
+
+  if (includeCiGuardrails) {
+    const githubCiBlueprintContent = await fs.readFile(path.join(selectedBlueprintsDirectoryPath, 'ci-github-actions.md'), 'utf8');
+    const gitlabCiBlueprintContent = await fs.readFile(path.join(selectedBlueprintsDirectoryPath, 'ci-gitlab.md'), 'utf8');
+
+    contextBlocks.push(
+      `## CI/CD GUARDRAILS: ci-github-actions.md\nSource: .agent-context/blueprints/ci-github-actions.md\n\n${githubCiBlueprintContent.trim()}`
+    );
+    contextBlocks.push(
+      `## CI/CD GUARDRAILS: ci-gitlab.md\nSource: .agent-context/blueprints/ci-gitlab.md\n\n${gitlabCiBlueprintContent.trim()}`
+    );
+  }
+
+  for (const selectedSkillDomainName of selectedSkillDomainNames) {
+    const skillDomainEntry = skillPlatformIndex.domains?.[selectedSkillDomainName];
+    if (!skillDomainEntry) {
+      continue;
+    }
+
+    contextBlocks.push(await buildSkillPackSection(skillDomainEntry, skillPlatformIndex.defaultTier || 'advance'));
+  }
+
+  const architectureMapContent = await fs.readFile(path.join(selectedStateDirectoryPath, 'architecture-map.md'), 'utf8');
+  const dependencyMapContent = await fs.readFile(path.join(selectedStateDirectoryPath, 'dependency-map.md'), 'utf8');
+  const prChecklistContent = await fs.readFile(path.join(selectedReviewDirectoryPath, 'pr-checklist.md'), 'utf8');
+
+  contextBlocks.push(
+    `## STATE MAP: architecture-map.md\nSource: .agent-context/state/architecture-map.md\n\n${architectureMapContent.trim()}`
+  );
+  contextBlocks.push(
+    `## STATE MAP: dependency-map.md\nSource: .agent-context/state/dependency-map.md\n\n${dependencyMapContent.trim()}`
+  );
+  contextBlocks.push(
+    `## REVIEW CHECKLIST: pr-checklist.md\nSource: .agent-context/review-checklists/pr-checklist.md\n\n${prChecklistContent.trim()}`
+  );
+
+  return [
+    '# AGENTIC-SENIOR-CORE DYNAMIC GOVERNANCE RULESET',
+    '',
+    `Generated by Agentic-Senior-Core CLI v${CLI_VERSION}`,
+    `Timestamp: ${new Date().toISOString()}`,
+    `Selected profile: ${selectedProfileName}`,
+    `Selected policy file: .agent-context/policies/${POLICY_FILE_NAME}`,
+    '',
+    '## GOVERNANCE PRECEDENCE',
+    '1. Follow this compiled rulebook as the primary source.',
+    '2. Resolve exceptions from .agent-override.md only when explicitly defined.',
+    '3. Use architecture-map.md and dependency-map.md as change safety boundaries.',
+    '4. Enforce pr-checklist.md before declaring completion.',
+    '',
+    '## OVERRIDE PROTOCOL',
+    '- Default: strict compliance with this file.',
+    '- Exception path: .agent-override.md may explicitly allow narrow deviations.',
+    '- Scope policy: every override must include module scope, rationale, and expiry date.',
+    '',
+    ...contextBlocks,
+    '',
+  ].join('\n');
+}
+
+export async function compileDynamicContext({
+  targetDirectoryPath,
+  selectedProfileName,
+  selectedStackFileName,
+  selectedBlueprintFileName,
+  includeCiGuardrails,
+}) {
+  const resolvedTargetDirectoryPath = path.resolve(targetDirectoryPath);
+  const compiledRules = await buildCompiledRulesContent({
+    targetDirectoryPath: resolvedTargetDirectoryPath,
+    selectedProfileName,
+    selectedStackFileName,
+    selectedBlueprintFileName,
+    includeCiGuardrails,
+  });
+
+  await fs.writeFile(path.join(resolvedTargetDirectoryPath, '.cursorrules'), compiledRules, 'utf8');
+  await fs.writeFile(path.join(resolvedTargetDirectoryPath, '.windsurfrules'), compiledRules, 'utf8');
+}

package/lib/cli/constants.mjs

@@ -0,0 +1,136 @@
+/**
+ * CLI Constants — All configuration values extracted from the monolith.
+ * Zero dependencies on other lib modules.
+ */
+import { readFileSync } from 'node:fs';
+import { resolve, join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const currentFilePath = fileURLToPath(import.meta.url);
+const currentDirectoryPath = dirname(currentFilePath);
+
+export const REPO_ROOT = resolve(currentDirectoryPath, '..', '..');
+export const PACKAGE_JSON_PATH = join(REPO_ROOT, 'package.json');
+export const CLI_VERSION = JSON.parse(readFileSync(PACKAGE_JSON_PATH, 'utf8')).version;
+export const AGENT_CONTEXT_DIR = join(REPO_ROOT, '.agent-context');
+export const SKILL_PLATFORM_DIRECTORY = join(AGENT_CONTEXT_DIR, 'skills');
+export const SKILL_PLATFORM_INDEX_PATH = join(SKILL_PLATFORM_DIRECTORY, 'index.json');
+export const POLICY_FILE_NAME = 'llm-judge-threshold.json';
+export const PROFILE_PACKS_DIRECTORY_NAME = 'profiles';
+
+export const PROFILE_PACK_REQUIRED_FIELDS = [
+  'slug',
+  'displayName',
+  'description',
+  'defaultProfile',
+  'defaultStack',
+  'defaultBlueprint',
+  'ciGuardrails',
+  'lockCi',
+  'blockingSeverities',
+];
+
+export const ALLOWED_SEVERITY_LEVELS = new Set(['critical', 'high', 'medium', 'low']);
+
+export const BLUEPRINT_RECOMMENDATIONS = {
+  'typescript.md': 'api-nextjs.md',
+  'python.md': 'fastapi-service.md',
+  'java.md': 'spring-boot-api.md',
+  'php.md': 'laravel-api.md',
+  'go.md': 'go-service.md',
+  'csharp.md': 'aspnet-api.md',
+  'react-native.md': 'mobile-app.md',
+  'flutter.md': 'mobile-app.md',
+};
+
+export const INIT_PRESETS = {
+  'frontend-web': {
+    profile: 'balanced',
+    stack: 'typescript.md',
+    blueprint: 'api-nextjs.md',
+    ci: true,
+    description: 'Frontend-first web app starter',
+  },
+  'backend-api': {
+    profile: 'balanced',
+    stack: 'python.md',
+    blueprint: 'fastapi-service.md',
+    ci: true,
+    description: 'Backend API starter with safe defaults',
+  },
+  'fullstack-product': {
+    profile: 'balanced',
+    stack: 'typescript.md',
+    blueprint: 'api-nextjs.md',
+    ci: true,
+    description: 'Product delivery starter with fullstack governance',
+  },
+  'platform-governance': {
+    profile: 'strict',
+    stack: 'go.md',
+    blueprint: 'go-service.md',
+    ci: true,
+    description: 'Strict release and platform governance starter',
+  },
+  'mobile-react-native': {
+    profile: 'balanced',
+    stack: 'react-native.md',
+    blueprint: 'mobile-app.md',
+    ci: true,
+    description: 'Mobile app starter for React Native',
+  },
+  'mobile-flutter': {
+    profile: 'balanced',
+    stack: 'flutter.md',
+    blueprint: 'mobile-app.md',
+    ci: true,
+    description: 'Mobile app starter for Flutter',
+  },
+  'observability-platform': {
+    profile: 'strict',
+    stack: 'go.md',
+    blueprint: 'observability.md',
+    ci: true,
+    description: 'Observability and platform starter',
+  },
+};
+
+export const PROFILE_PRESETS = {
+  beginner: {
+    displayName: 'Beginner',
+    description: 'Safest path. Minimal decisions, TypeScript defaults, and CI enabled.',
+    defaultStackFileName: 'typescript.md',
+    defaultBlueprintFileName: 'api-nextjs.md',
+    defaultCi: true,
+    lockCi: true,
+    blockingSeverities: ['critical'],
+  },
+  balanced: {
+    displayName: 'Balanced',
+    description: 'Recommended for most teams. Guided choices with strong default guardrails.',
+    defaultStackFileName: null,
+    defaultBlueprintFileName: null,
+    defaultCi: true,
+    lockCi: false,
+    blockingSeverities: ['critical', 'high'],
+  },
+  strict: {
+    displayName: 'Strict',
+    description: 'Tighter governance. CI stays on and medium-risk findings can block merges.',
+    defaultStackFileName: null,
+    defaultBlueprintFileName: null,
+    defaultCi: true,
+    lockCi: true,
+    blockingSeverities: ['critical', 'high', 'medium'],
+  },
+};
+
+export const entryPointFiles = [
+  '.cursorrules',
+  '.windsurfrules',
+  'AGENTS.md',
+  '.agent-override.md',
+  'mcp.json',
+];
+
+export const directoryCopies = ['.agent-context', '.github', '.gemini', '.agents'];

package/lib/cli/detector.mjs

@@ -0,0 +1,211 @@
+/**
+ * Stack Detector — Project context auto-detection.
+ * Depends on: constants.mjs, utils.mjs
+ */
+import fs from 'node:fs/promises';
+
+import { BLUEPRINT_RECOMMENDATIONS } from './constants.mjs';
+import { toTitleCase } from './utils.mjs';
+
+export async function collectProjectMarkers(targetDirectoryPath) {
+  const markerNames = new Set();
+  const directoryEntries = await fs.readdir(targetDirectoryPath, { withFileTypes: true });
+
+  for (const directoryEntry of directoryEntries) {
+    if (directoryEntry.name === '.git' || directoryEntry.name === 'node_modules') {
+      continue;
+    }
+
+    markerNames.add(directoryEntry.name);
+  }
+
+  return markerNames;
+}
+
+export async function detectProjectContext(targetDirectoryPath) {
+  const markerNames = await collectProjectMarkers(targetDirectoryPath);
+  const detectionCandidates = [];
+  const hasExistingProjectFiles = markerNames.size > 0;
+
+  if (markerNames.has('package.json') || markerNames.has('tsconfig.json') || markerNames.has('next.config.js') || markerNames.has('next.config.mjs')) {
+    const evidence = [];
+    let confidenceScore = 0.7;
+
+    if (markerNames.has('package.json')) {
+      evidence.push('package.json');
+      confidenceScore += 0.12;
+    }
+
+    if (markerNames.has('tsconfig.json')) {
+      evidence.push('tsconfig.json');
+      confidenceScore += 0.12;
+    }
+
+    if (markerNames.has('next.config.js') || markerNames.has('next.config.mjs')) {
+      evidence.push('Next.js config');
+      confidenceScore += 0.05;
+    }
+
+    detectionCandidates.push({
+      stackFileName: 'typescript.md',
+      confidenceScore: Math.min(confidenceScore, 0.97),
+      evidence,
+    });
+  }
+
+  if (markerNames.has('pyproject.toml') || markerNames.has('requirements.txt')) {
+    detectionCandidates.push({
+      stackFileName: 'python.md',
+      confidenceScore: markerNames.has('pyproject.toml') ? 0.96 : 0.78,
+      evidence: markerNames.has('pyproject.toml') ? ['pyproject.toml'] : ['requirements.txt'],
+    });
+  }
+
+  if (markerNames.has('pom.xml') || markerNames.has('build.gradle') || markerNames.has('build.gradle.kts')) {
+    const evidence = [];
+    if (markerNames.has('pom.xml')) evidence.push('pom.xml');
+    if (markerNames.has('build.gradle') || markerNames.has('build.gradle.kts')) evidence.push('Gradle build file');
+    detectionCandidates.push({
+      stackFileName: 'java.md',
+      confidenceScore: markerNames.has('pom.xml') ? 0.95 : 0.84,
+      evidence,
+    });
+  }
+
+  if (markerNames.has('composer.json')) {
+    detectionCandidates.push({
+      stackFileName: 'php.md',
+      confidenceScore: 0.95,
+      evidence: ['composer.json'],
+    });
+  }
+
+  if (markerNames.has('go.mod')) {
+    detectionCandidates.push({
+      stackFileName: 'go.md',
+      confidenceScore: 0.96,
+      evidence: ['go.mod'],
+    });
+  }
+
+  if (markerNames.has('Cargo.toml')) {
+    detectionCandidates.push({
+      stackFileName: 'rust.md',
+      confidenceScore: 0.96,
+      evidence: ['Cargo.toml'],
+    });
+  }
+
+  if (markerNames.has('Gemfile')) {
+    detectionCandidates.push({
+      stackFileName: 'ruby.md',
+      confidenceScore: 0.95,
+      evidence: ['Gemfile'],
+    });
+  }
+
+  const hasDotNetMarker = Array.from(markerNames).some((markerName) => markerName.endsWith('.sln') || markerName.endsWith('.csproj'));
+  if (hasDotNetMarker) {
+    detectionCandidates.push({
+      stackFileName: 'csharp.md',
+      confidenceScore: 0.95,
+      evidence: ['.sln or .csproj file'],
+    });
+  }
+
+  if (markerNames.has('package.json') && (markerNames.has('android') || markerNames.has('ios') || markerNames.has('react-native.config.js'))) {
+    detectionCandidates.push({
+      stackFileName: 'react-native.md',
+      confidenceScore: 0.9,
+      evidence: ['package.json', 'mobile runtime markers'],
+    });
+  }
+
+  if (markerNames.has('pubspec.yaml')) {
+    detectionCandidates.push({
+      stackFileName: 'flutter.md',
+      confidenceScore: 0.94,
+      evidence: ['pubspec.yaml'],
+    });
+  }
+
+  if (detectionCandidates.length === 0) {
+    return {
+      hasExistingProjectFiles,
+      recommendedStackFileName: null,
+      recommendedBlueprintFileName: null,
+      confidenceLabel: null,
+      confidenceScore: 0,
+      confidenceGap: 0,
+      detectionReasoning: 'No known project markers were detected.',
+      rankedCandidates: [],
+      evidence: [],
+    };
+  }
+
+  detectionCandidates.sort((leftCandidate, rightCandidate) => rightCandidate.confidenceScore - leftCandidate.confidenceScore);
+  const strongestCandidate = detectionCandidates[0];
+  const secondStrongestCandidate = detectionCandidates[1];
+  const confidenceGap = secondStrongestCandidate
+    ? Number((strongestCandidate.confidenceScore - secondStrongestCandidate.confidenceScore).toFixed(2))
+    : Number(strongestCandidate.confidenceScore.toFixed(2));
+  const isAmbiguous = secondStrongestCandidate
+    && confidenceGap < 0.08;
+  const confidenceLabel = strongestCandidate.confidenceScore >= 0.9
+    ? 'high'
+    : strongestCandidate.confidenceScore >= 0.78
+      ? 'medium'
+      : 'low';
+  const evidence = isAmbiguous
+    ? [...strongestCandidate.evidence, `multiple stack signals detected`]
+    : strongestCandidate.evidence;
+  const rankedCandidates = detectionCandidates.slice(0, 3).map((detectionCandidate) => ({
+    stackFileName: detectionCandidate.stackFileName,
+    confidenceScore: Number(detectionCandidate.confidenceScore.toFixed(2)),
+    evidence: detectionCandidate.evidence,
+  }));
+  const detectionReasoning = isAmbiguous
+    ? `Top signal ${toTitleCase(strongestCandidate.stackFileName)} is close to ${toTitleCase(secondStrongestCandidate.stackFileName)} (confidence gap ${confidenceGap}).`
+    : `Top signal ${toTitleCase(strongestCandidate.stackFileName)} won with confidence ${strongestCandidate.confidenceScore.toFixed(2)} from markers: ${strongestCandidate.evidence.join(', ') || 'none'}.`;
+
+  return {
+    hasExistingProjectFiles,
+    recommendedStackFileName: strongestCandidate.stackFileName,
+    recommendedBlueprintFileName: BLUEPRINT_RECOMMENDATIONS[strongestCandidate.stackFileName] || null,
+    confidenceLabel,
+    confidenceScore: strongestCandidate.confidenceScore,
+    confidenceGap,
+    detectionReasoning,
+    rankedCandidates,
+    evidence,
+  };
+}
+
+export function buildDetectionSummary(projectDetection) {
+  if (!projectDetection.recommendedStackFileName) {
+    return 'I did not find enough stack markers to auto-detect this project confidently.';
+  }
+
+  const readableEvidence = projectDetection.evidence.length > 0
+    ? projectDetection.evidence.join(', ')
+    : 'basic project markers';
+
+  const confidenceGapSummary = typeof projectDetection.confidenceGap === 'number'
+    ? ` Confidence gap: ${projectDetection.confidenceGap}.`
+    : '';
+
+  return `This folder looks like ${toTitleCase(projectDetection.recommendedStackFileName)} with ${projectDetection.confidenceLabel} confidence based on ${readableEvidence}.${confidenceGapSummary}`;
+}
+
+export function formatDetectionCandidates(rankedCandidates) {
+  if (!rankedCandidates?.length) {
+    return 'No ranked candidates available.';
+  }
+
+  return rankedCandidates
+    .map((candidate, candidateIndex) => {
+      const evidenceSummary = candidate.evidence?.length ? candidate.evidence.join(', ') : 'no direct markers';
+      return `${candidateIndex + 1}. ${toTitleCase(candidate.stackFileName)} (score ${candidate.confidenceScore}) via ${evidenceSummary}`;
+    })
+    .join('\n');
+}

package/lib/cli/profile-packs.mjs

@@ -0,0 +1,94 @@
+/**
+ * Profile Pack Parser — Team profile pack loading and matching.
+ * Depends on: constants.mjs, utils.mjs
+ */
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+import {
+  PROFILE_PACK_REQUIRED_FIELDS,
+  PROFILE_PACKS_DIRECTORY_NAME,
+} from './constants.mjs';
+
+import {
+  pathExists,
+  collectFileNames,
+  normalizeChoiceInput,
+  matchProfileNameFromInput,
+  parseBooleanSetting,
+  parseBlockingSeverities,
+} from './utils.mjs';
+
+export function parseProfilePackContent(fileName, profilePackContent) {
+  const parsedFields = {};
+  const profilePackLines = profilePackContent.split(/\r?\n/);
+
+  for (const profilePackLine of profilePackLines) {
+    const lineMatch = profilePackLine.match(/^([A-Za-z][A-Za-z0-9 ]+):\s*(.+)$/);
+    if (!lineMatch) {
+      continue;
+    }
+
+    const fieldName = lineMatch[1].trim();
+    const fieldValue = lineMatch[2].trim();
+    parsedFields[fieldName] = fieldValue;
+  }
+
+  for (const requiredFieldName of PROFILE_PACK_REQUIRED_FIELDS) {
+    if (!parsedFields[requiredFieldName]) {
+      throw new Error(`Profile pack ${fileName} is missing required field: ${requiredFieldName}`);
+    }
+  }
+
+  const defaultProfileName = matchProfileNameFromInput(parsedFields.defaultProfile);
+  if (!defaultProfileName) {
+    throw new Error(`Profile pack ${fileName} has invalid defaultProfile: ${parsedFields.defaultProfile}`);
+  }
+
+  return {
+    fileName,
+    slug: normalizeChoiceInput(parsedFields.slug),
+    displayName: parsedFields.displayName,
+    description: parsedFields.description,
+    defaultProfileName,
+    defaultStackFileName: parsedFields.defaultStack.trim(),
+    defaultBlueprintFileName: parsedFields.defaultBlueprint.trim(),
+    defaultCi: parseBooleanSetting(parsedFields.ciGuardrails, `${fileName} ciGuardrails`),
+    lockCi: parseBooleanSetting(parsedFields.lockCi, `${fileName} lockCi`),
+    blockingSeverities: parseBlockingSeverities(parsedFields.blockingSeverities, fileName),
+    owner: parsedFields.owner || null,
+    lastUpdated: parsedFields.lastUpdated || null,
+  };
+}
+
+export async function collectProfilePacks(targetDirectoryPath) {
+  const profilePackDirectoryPath = path.join(targetDirectoryPath, '.agent-context', PROFILE_PACKS_DIRECTORY_NAME);
+  if (!(await pathExists(profilePackDirectoryPath))) {
+    return [];
+  }
+
+  const profilePackFileNames = await collectFileNames(profilePackDirectoryPath);
+  const profilePackDefinitions = [];
+
+  for (const profilePackFileName of profilePackFileNames) {
+    const profilePackFilePath = path.join(profilePackDirectoryPath, profilePackFileName);
+    const profilePackContent = await fs.readFile(profilePackFilePath, 'utf8');
+    profilePackDefinitions.push(parseProfilePackContent(profilePackFileName, profilePackContent));
+  }
+
+  return profilePackDefinitions;
+}
+
+export function findProfilePackByInput(profilePackInput, profilePackDefinitions) {
+  const normalizedProfilePackInput = normalizeChoiceInput(profilePackInput);
+
+  return profilePackDefinitions.find((profilePackDefinition) => {
+    const normalizedFileName = normalizeChoiceInput(profilePackDefinition.fileName.replace(/\.md$/i, ''));
+    const normalizedSlug = normalizeChoiceInput(profilePackDefinition.slug);
+    const normalizedDisplayName = normalizeChoiceInput(profilePackDefinition.displayName);
+
+    return normalizedProfilePackInput === normalizedFileName
+      || normalizedProfilePackInput === normalizedSlug
+      || normalizedProfilePackInput === normalizedDisplayName;
+  }) || null;
+}