thachvd-kit 1.0.36 → 1.0.38

package/bin/spec.js

@@ -0,0 +1,859 @@
+const fs = require('fs');
+const path = require('path');
+const { spawnSync } = require('child_process');
+const recipe = require('./spec-recipe');
+const links = require('./spec-link');
+const nativeSkills = require('./native-skills');
+const specState = require('./spec-state');
+const userConfig = require('./config');
+const specDoctor = require('./spec-doctor');
+
+const MANIFEST_RELATIVE_PATH = path.join('.thachvd', 'system.json');
+const DEFAULT_SPEC_ROOT = 'system-specs';
+const CODEBASE_MEMORY_BINARY = 'codebase-memory-mcp';
+const MANIFEST_SCHEMA_VERSION = 1;
+const DEFAULT_SPEC_LANGUAGE = 'en';
+const SUPPORTED_SPEC_LANGUAGES = new Set(['en', 'vi']);
+const DEFAULT_SPEC_PROFILE = 'auto';
+const SUPPORTED_SPEC_PROFILES = new Set(['auto', 'backend', 'frontend', 'fullstack', 'mobile', 'infra']);
+const DISCOVERY_PROMPT_RELATIVE_PATH = path.join('.agent', 'docs', 'system-discovery-prompt.md');
+const SYSTEM_REVERSE_PROMPT_RELATIVE_PATH = path.join('.agent', 'docs', 'system-reverse-prompt.md');
+const SYSTEM_REVIEW_PROMPT_RELATIVE_PATH = path.join('.agent', 'docs', 'system-spec-review-prompt.md');
+const WORKSPACE_SCAN_IGNORES = new Set([
+    '.git', '.thachvd', '.agent', '.agents', '.claude', 'node_modules',
+    'vendor', 'dist', 'build', 'coverage', 'system-specs'
+]);
+
+function toPortablePath(value) {
+    return value.split(path.sep).join('/');
+}
+
+function parseOptionValues(args, name) {
+    const values = [];
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (arg === name) {
+            if (i + 1 >= args.length || args[i + 1].startsWith('--')) {
+                throw new Error(`${name} requires a value`);
+            }
+            values.push(args[++i]);
+        } else if (arg.startsWith(`${name}=`)) {
+            values.push(arg.slice(name.length + 1));
+        }
+    }
+    return values;
+}
+
+function parseSingleOption(args, name, fallback = null) {
+    const values = parseOptionValues(args, name);
+    if (values.length > 1) throw new Error(`${name} may only be provided once`);
+    return values[0] ?? fallback;
+}
+
+function hasFlag(args, name) {
+    return args.includes(name);
+}
+
+function commandExists(command) {
+    const checker = process.platform === 'win32' ? 'where' : 'command';
+    const checkerArgs = process.platform === 'win32' ? [command] : ['-v', command];
+    const result = spawnSync(checker, checkerArgs, {
+        encoding: 'utf8',
+        shell: process.platform !== 'win32'
+    });
+    return result.status === 0;
+}
+
+function assertDirectory(directory, label) {
+    let stat;
+    try {
+        stat = fs.statSync(directory);
+    } catch {
+        throw new Error(`${label} does not exist: ${directory}`);
+    }
+    if (!stat.isDirectory()) throw new Error(`${label} is not a directory: ${directory}`);
+}
+
+function normalizeSpecLanguage(value) {
+    const language = (value || DEFAULT_SPEC_LANGUAGE).trim().toLowerCase();
+    if (!SUPPORTED_SPEC_LANGUAGES.has(language)) {
+        throw new Error(`Unsupported spec language: ${value}. Supported values: en, vi`);
+    }
+    return language;
+}
+
+function normalizeSpecProfile(value) {
+    const profile = (value || DEFAULT_SPEC_PROFILE).trim().toLowerCase();
+    if (!SUPPORTED_SPEC_PROFILES.has(profile)) {
+        throw new Error(`Unsupported spec profile: ${value}. Supported values: auto, backend, frontend, fullstack, mobile, infra`);
+    }
+    return profile;
+}
+
+function profileInstruction(profile) {
+    const common = [
+        'Profile guidance is a review checklist, not a source of truth. Do not omit behavior that does not fit the selected profile.',
+        'Use implementation/tests as the source of truth and mark unclear behavior explicitly.'
+    ];
+    const specific = {
+        auto: [
+            'Infer a practical profile for each repository from code/config evidence; a multi-repo system may contain different repo profiles.',
+            'Record the inferred repo profile(s) in system-overview/repo-map with supporting evidence.',
+            'Apply the relevant specialized checklist below only after inferring it.'
+        ],
+        backend: [
+            'Pay special attention to HTTP/RPC routes, middleware, authentication/authorization, services/domain logic, persistence/migrations/transactions, caches, queues/events/jobs/schedulers, external clients, feature flags, retries/idempotency, concurrency and failure/rollback behavior.'
+        ],
+        frontend: [
+            'Pay special attention to routes/navigation, page/component composition, state management, API/data clients, forms/validation, auth/session handling, feature flags, analytics, accessibility, loading/error/empty states, browser storage and build/runtime configuration.'
+        ],
+        fullstack: [
+            'Apply both backend and frontend checklists, and explicitly trace client/server boundaries, shared schemas/types, authentication/session propagation, BFF/SSR/server actions where present, and end-to-end failure handling.'
+        ],
+        mobile: [
+            'Pay special attention to navigation, app lifecycle/background work, local storage/cache, offline/sync behavior, permissions, push notifications, deep links, networking/auth refresh, platform-specific code, device integrations and release/runtime configuration.'
+        ],
+        infra: [
+            'Pay special attention to IaC modules/stacks, environments/workspaces, CI/CD, secrets, IAM, networking, state backends, observability, autoscaling/capacity, deployment ordering, rollback/recovery and destructive-change safeguards.'
+        ]
+    };
+    return [...common, ...(specific[profile] || specific.auto)].join('\n- ');
+}
+
+function languageInstruction(language) {
+    if (language === 'vi') {
+        return [
+            'Write documentation prose, headings, explanations, and summaries in natural Vietnamese.',
+            'Keep code identifiers, class/function names, API routes, event/queue names, database/schema names, file paths, commands, and source anchors exactly as they appear in code.',
+            'Prefer established Vietnamese technical wording; retain the original English term in parentheses when translating it would make the concept less precise.'
+        ].join('\n- ');
+    }
+    return [
+        'Write documentation prose, headings, explanations, and summaries in English.',
+        'Keep code identifiers, class/function names, API routes, event/queue names, database/schema names, file paths, commands, and source anchors exactly as they appear in code.'
+    ].join('\n- ');
+}
+
+function resolveSpecRoot(workspaceRoot, specRoot) {
+    if (!specRoot || typeof specRoot !== 'string') throw new Error('spec_root must be a non-empty string');
+    if (path.isAbsolute(specRoot)) throw new Error('spec_root must be relative to the workspace root');
+    const resolved = path.resolve(workspaceRoot, specRoot);
+    const relative = path.relative(workspaceRoot, resolved);
+    if (relative.startsWith('..') || path.isAbsolute(relative)) {
+        throw new Error('spec_root must stay inside the workspace root');
+    }
+    return { resolved, relative: toPortablePath(relative || '.') };
+}
+
+function isGitRepositoryRoot(directory) {
+    return fs.existsSync(path.join(directory, '.git'));
+}
+
+function discoverRepoPaths(workspaceRoot, options = {}) {
+    const root = path.resolve(workspaceRoot);
+    if (isGitRepositoryRoot(root)) return ['.'];
+    const excluded = new Set((options.excludePaths || []).map(value => path.resolve(root, value)));
+
+    let entries = [];
+    try {
+        entries = fs.readdirSync(root, { withFileTypes: true });
+    } catch {
+        return ['.'];
+    }
+
+    const children = entries
+        .filter(entry => entry.isDirectory() && !WORKSPACE_SCAN_IGNORES.has(entry.name))
+        .map(entry => path.join(root, entry.name))
+        .filter(directory => !excluded.has(path.resolve(directory)))
+        .filter(isGitRepositoryRoot)
+        .sort((a, b) => a.localeCompare(b));
+
+    if (children.length === 0) return ['.'];
+    return children.map(directory => toPortablePath(path.relative(root, directory)));
+}
+
+function normalizeRepo(workspaceRoot, repoPath, usedNames) {
+    const absolutePath = path.resolve(workspaceRoot, repoPath);
+    assertDirectory(absolutePath, 'Repository path');
+    const baseName = path.basename(absolutePath) || 'repo';
+    let name = baseName;
+    let suffix = 2;
+    while (usedNames.has(name)) name = `${baseName}-${suffix++}`;
+    usedNames.add(name);
+    return {
+        name,
+        path: toPortablePath(path.relative(workspaceRoot, absolutePath) || '.')
+    };
+}
+
+function createManifest(workspaceRoot, options = {}) {
+    const name = options.name || path.basename(path.resolve(workspaceRoot));
+    const specRoot = resolveSpecRoot(workspaceRoot, options.specRoot || DEFAULT_SPEC_ROOT);
+    const repoPaths = options.repos && options.repos.length > 0
+        ? options.repos
+        : discoverRepoPaths(workspaceRoot, { excludePaths: [specRoot.resolved] });
+    const language = normalizeSpecLanguage(options.language);
+    const profile = normalizeSpecProfile(options.profile);
+    const usedNames = new Set();
+    const repos = repoPaths.map(repoPath => normalizeRepo(workspaceRoot, repoPath, usedNames));
+    const seenPaths = new Set();
+    for (const repo of repos) {
+        if (seenPaths.has(repo.path)) throw new Error(`Duplicate repository path: ${repo.path}`);
+        seenPaths.add(repo.path);
+    }
+    return {
+        schema_version: MANIFEST_SCHEMA_VERSION,
+        name,
+        spec_root: specRoot.relative,
+        language,
+        profile,
+        repos
+    };
+}
+
+function validateManifest(workspaceRoot, manifest) {
+    if (!manifest || typeof manifest !== 'object') throw new Error('System manifest must be a JSON object');
+    if (manifest.schema_version !== MANIFEST_SCHEMA_VERSION) {
+        throw new Error(`Unsupported system manifest schema_version: ${manifest.schema_version}`);
+    }
+    if (!manifest.name || typeof manifest.name !== 'string') throw new Error('System manifest requires name');
+    manifest.language = normalizeSpecLanguage(manifest.language || DEFAULT_SPEC_LANGUAGE);
+    manifest.profile = normalizeSpecProfile(manifest.profile || DEFAULT_SPEC_PROFILE);
+    resolveSpecRoot(workspaceRoot, manifest.spec_root);
+    if (!Array.isArray(manifest.repos) || manifest.repos.length === 0) {
+        throw new Error('System manifest requires at least one repository');
+    }
+    const names = new Set();
+    const paths = new Set();
+    for (const repo of manifest.repos) {
+        if (!repo || typeof repo.name !== 'string' || !repo.name.trim()) throw new Error('Each repository requires a name');
+        if (!repo.path || typeof repo.path !== 'string') throw new Error(`Repository ${repo.name || '(unknown)'} requires a path`);
+        if (names.has(repo.name)) throw new Error(`Duplicate repository name: ${repo.name}`);
+        if (paths.has(repo.path)) throw new Error(`Duplicate repository path: ${repo.path}`);
+        names.add(repo.name);
+        paths.add(repo.path);
+    }
+    return manifest;
+}
+
+function manifestPath(workspaceRoot) {
+    return path.join(workspaceRoot, MANIFEST_RELATIVE_PATH);
+}
+
+function readManifest(workspaceRoot) {
+    const filePath = manifestPath(workspaceRoot);
+    if (!fs.existsSync(filePath)) {
+        throw new Error(`System manifest not found at ${MANIFEST_RELATIVE_PATH}. Run: thachvd-kit spec init`);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(fs.readFileSync(filePath, 'utf8'));
+    } catch (error) {
+        throw new Error(`Cannot parse ${MANIFEST_RELATIVE_PATH}: ${error.message}`);
+    }
+    return validateManifest(workspaceRoot, parsed);
+}
+
+function initialReadme(manifest) {
+    const tick = '`';
+    const repoLines = manifest.repos.map(repo => `- ${tick}${repo.name}${tick}: ${tick}${repo.path}${tick}`).join('\n');
+    if (manifest.language === 'vi') {
+        return `# Đặc tả hệ thống ${manifest.name}
+
+Thư mục này chứa bộ đặc tả AS-IS đã được review cho hệ thống brownfield hiện tại.
+
+## Repository
+
+${repoLines}
+
+## Luồng thực hiện
+
+1. Index các repository bằng ${tick}thachvd-kit spec index${tick}.
+2. Chạy ${tick}thachvd-kit spec discover${tick}, sau đó chạy ${tick}/system-discovery${tick}.
+3. Review thủ công repo map, capability map và integration map.
+4. Chạy ${tick}thachvd-kit spec reverse${tick}, sau đó chạy ${tick}/system-reverse-engineer${tick} để tạo tài liệu cho toàn bộ hệ thống đã được duyệt.
+5. Chạy ${tick}thachvd-kit spec verify${tick}, sau đó chạy ${tick}/system-spec-review${tick} để kiểm chứng độc lập với code/tests.
+6. Chạy ${tick}thachvd-kit spec check${tick} để phát hiện spec có thể stale so với code.
+7. Chạy ${tick}thachvd-kit spec link${tick} để các agent sau này tự tìm thấy bộ spec.
+8. Luôn tách biệt hành vi quan sát được từ code/tests với business rationale chưa được xác nhận.
+
+Ngôn ngữ tài liệu: Tiếng Việt. Tên code/API/event/schema/file path giữ nguyên như trong source.
+Profile phân tích: ${manifest.profile}.
+`;
+    }
+    return `# ${manifest.name} System Specs
+
+This directory is the durable, reviewed specification layer for the current brownfield system.
+
+## Repositories
+
+${repoLines}
+
+## Workflow
+
+1. Index repositories with ${tick}thachvd-kit spec index${tick}.
+2. Run ${tick}thachvd-kit spec discover${tick}, then ${tick}/system-discovery${tick}.
+3. Human-review the repo/capability/integration maps.
+4. Run ${tick}thachvd-kit spec reverse${tick}, then ${tick}/system-reverse-engineer${tick} to document the whole approved system.
+5. Run ${tick}thachvd-kit spec verify${tick}, then ${tick}/system-spec-review${tick} for independent evidence and coverage verification.
+6. Run ${tick}thachvd-kit spec check${tick} to detect potential drift from verified commits.
+7. Run ${tick}thachvd-kit spec link${tick} so future agents discover these specs.
+8. Keep observed behavior distinct from business rationale that requires owner confirmation.
+
+Documentation language: English. Code/API/event/schema/file-path identifiers stay unchanged.
+Analysis profile: ${manifest.profile}.
+`;
+}
+
+function initializeWorkspace(workspaceRoot, options = {}) {
+    const filePath = manifestPath(workspaceRoot);
+    if (fs.existsSync(filePath) && !options.force) {
+        throw new Error(`${MANIFEST_RELATIVE_PATH} already exists. Re-run with --yes to replace it.`);
+    }
+    const manifest = createManifest(workspaceRoot, options);
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    fs.writeFileSync(filePath, JSON.stringify(manifest, null, 2) + '\n', 'utf8');
+
+    const { resolved: specRoot } = resolveSpecRoot(workspaceRoot, manifest.spec_root);
+    for (const directory of ['architecture', 'capabilities', 'flows', 'contracts', '_meta']) {
+        fs.mkdirSync(path.join(specRoot, directory), { recursive: true });
+    }
+    fs.writeFileSync(
+        path.join(specRoot, '_meta', 'workspace.json'),
+        JSON.stringify(manifest, null, 2) + '\n',
+        'utf8'
+    );
+    const readmePath = path.join(specRoot, 'README.md');
+    if (!fs.existsSync(readmePath)) {
+        fs.writeFileSync(readmePath, initialReadme(manifest), 'utf8');
+    }
+
+    nativeSkills.installSystemSpecSkills(workspaceRoot);
+    return manifest;
+}
+
+function selectRepos(manifest, requestedNames) {
+    if (!requestedNames || requestedNames.length === 0) return manifest.repos;
+    const requested = new Set(requestedNames);
+    const selected = manifest.repos.filter(repo => requested.has(repo.name));
+    const missing = [...requested].filter(name => !manifest.repos.some(repo => repo.name === name));
+    if (missing.length > 0) throw new Error(`Unknown repository name(s): ${missing.join(', ')}`);
+    return selected;
+}
+
+function indexWorkspace(workspaceRoot, manifest, options = {}) {
+    const binary = options.binary || CODEBASE_MEMORY_BINARY;
+    const spawn = options.spawn || spawnSync;
+    const dryRun = options.dryRun === true;
+    const repos = selectRepos(manifest, options.repoNames || []);
+    if (!dryRun && options.skipBinaryCheck !== true && !commandExists(binary)) {
+        throw new Error(`${binary} is not installed. Run thachvd-kit setup or install codebase-memory-mcp first.`);
+    }
+
+    const results = [];
+    for (const repo of repos) {
+        const absolutePath = path.resolve(workspaceRoot, repo.path);
+        try {
+            assertDirectory(absolutePath, `Repository ${repo.name}`);
+        } catch (error) {
+            results.push({ name: repo.name, path: repo.path, ok: false, error: error.message });
+            continue;
+        }
+        const args = ['cli', 'index_repository', '--repo-path', absolutePath];
+        if (dryRun) {
+            results.push({ name: repo.name, path: repo.path, ok: true, dryRun: true, command: [binary, ...args] });
+            continue;
+        }
+        const result = spawn(binary, args, {
+            cwd: workspaceRoot,
+            encoding: 'utf8',
+            stdio: 'inherit',
+            shell: process.platform === 'win32'
+        });
+        results.push({
+            name: repo.name,
+            path: repo.path,
+            ok: result.status === 0,
+            status: result.status
+        });
+    }
+    return results;
+}
+
+function generateDiscoveryPrompt(manifest) {
+    const repos = manifest.repos.map(repo => `- ${repo.name}: ${repo.path}`).join('\n');
+    return `# System Discovery Prompt
+
+Use the installed /system-discovery skill.
+
+System: ${manifest.name}
+Spec root: ${manifest.spec_root}
+Documentation language: ${manifest.language}
+Analysis profile: ${manifest.profile}
+
+Language rules:
+- ${languageInstruction(manifest.language)}
+
+Profile rules:
+- ${profileInstruction(manifest.profile)}
+
+Repositories:
+${repos}
+
+Requirements:
+- Treat code and tests as the source of truth.
+- Use Codebase Memory MCP as the primary structural discovery source.
+- Inspect every configured repository and cross-repository flow.
+- Write AS-IS system docs only; do not modify product code.
+- Produce system-overview, repo-map, capability-map, integrations, and glossary under the configured spec root.
+- Attach repository/file/symbol evidence to important claims.
+- Mark inferred or unknown behavior explicitly; never invent business rationale.
+- Stop after the capability map and related system docs are written.
+- Require human review of capability boundaries before detailed reverse-engineering work.
+`;
+}
+
+function writeDiscoveryPrompt(workspaceRoot, manifest) {
+    const outputPath = path.join(workspaceRoot, DISCOVERY_PROMPT_RELATIVE_PATH);
+    fs.mkdirSync(path.dirname(outputPath), { recursive: true });
+    fs.writeFileSync(outputPath, generateDiscoveryPrompt(manifest), 'utf8');
+    return outputPath;
+}
+
+function generateSystemReversePrompt(manifest, capability = null) {
+    const repos = manifest.repos.map(repo => `- ${repo.name}: ${repo.path}`).join('\n');
+    const target = capability
+        ? `Only refresh the approved capability: ${capability}`
+        : 'Process every approved capability in the reviewed capability map.';
+    const progressRef = `${manifest.spec_root}/_meta/${specState.progressFileName(capability)}`;
+    return `# System Reverse Engineering Prompt
+
+Use the installed /system-reverse-engineer skill.
+
+System: ${manifest.name}
+Spec root: ${manifest.spec_root}
+Documentation language: ${manifest.language}
+Analysis profile: ${manifest.profile}
+
+Language rules:
+- ${languageInstruction(manifest.language)}
+
+Profile rules:
+- ${profileInstruction(manifest.profile)}
+
+Repositories:
+${repos}
+
+Scope:
+- ${target}
+
+Requirements:
+- Read the human-reviewed system discovery documents first.
+- Use Codebase Memory MCP as the primary structural source and verify important claims against code/tests.
+- Reverse-engineer AS-IS behavior only; do not modify product code.
+- For each approved capability, produce PRD + design documentation under the configured spec root.
+- Update real cross-repository flows and contracts as evidence is confirmed.
+- Distinguish implementation facts, test-confirmed behavior, inference, and unknown business rationale.
+- One invocation should cover the full approved system unless a capability was explicitly supplied for a targeted refresh.
+- Use ${progressRef} as the durable checkpoint. Create/populate the approved capability worklist if needed, mark a capability in_progress before working on it, completed only after both PRD/design are written and checked, and blocked with a reason when necessary.
+- Resume unfinished work from that checkpoint on later invocations; do not restart completed capabilities unless this is a targeted refresh.
+- Finish with a coverage summary and unresolved ambiguities.
+`;
+}
+
+function generateSystemReviewPrompt(manifest, repoHeads, capability = null) {
+    const repos = manifest.repos.map(repo => {
+        const head = repoHeads[repo.name];
+        return `- ${repo.name}: ${repo.path} @ ${head && head.ok ? head.commit : 'UNAVAILABLE'}`;
+    }).join('\n');
+    const scope = capability
+        ? `Targeted re-review: only capability "${capability}". Preserve unrelated verification entries and their per-capability commit baselines.`
+        : 'Full-system independent review: verify every approved capability.';
+    return `# Independent System Spec Review Prompt
+
+Use the installed /system-spec-review skill.
+
+System: ${manifest.name}
+Spec root: ${manifest.spec_root}
+Documentation language: ${manifest.language}
+Analysis profile: ${manifest.profile}
+Review scope: ${scope}
+
+Language rules:
+- ${languageInstruction(manifest.language)}
+
+Profile rules:
+- ${profileInstruction(manifest.profile)}
+
+Repositories at review handoff:
+${repos}
+
+Requirements:
+- Independently reconstruct implementation coverage instead of trusting the generated specs.
+- Verify important claims and a risk-weighted sample of source anchors against code/tests.
+- Check omitted entry points, jobs, schedulers, listeners, observers/hooks, policies, integrations, state transitions, failure paths, and tests.
+- Check PRD/design consistency and both sides of cross-repository contracts.
+- Do not silently rewrite source specs during the first review pass.
+- Write/update ${manifest.spec_root}/_meta/review.md.
+- Write valid ${manifest.spec_root}/_meta/verification.json with source_paths and capability-specific verified_commits.
+- For a full review, record current top-level repo commit SHAs and every approved capability status.
+- For a targeted re-review, update only the requested capability entry and its verified_commits; preserve all unrelated capability baselines.
+- Mark material gaps as needs_review or blocked; do not call them verified.
+`;
+}
+
+function writeSystemReviewPrompt(workspaceRoot, manifest, repoHeads, capability = null) {
+    const relativePath = capability
+        ? path.join('.agent', 'docs', `system-spec-review-${recipe.normalizeCapability(capability)}-prompt.md`)
+        : SYSTEM_REVIEW_PROMPT_RELATIVE_PATH;
+    const outputPath = path.join(workspaceRoot, relativePath);
+    fs.mkdirSync(path.dirname(outputPath), { recursive: true });
+    fs.writeFileSync(outputPath, generateSystemReviewPrompt(manifest, repoHeads, capability), 'utf8');
+    return outputPath;
+}
+
+function writeSystemReversePrompt(workspaceRoot, manifest, capability = null) {
+    const relativePath = capability
+        ? path.join('.agent', 'docs', `reverse-${recipe.normalizeCapability(capability)}-prompt.md`)
+        : SYSTEM_REVERSE_PROMPT_RELATIVE_PATH;
+    const outputPath = path.join(workspaceRoot, relativePath);
+    fs.mkdirSync(path.dirname(outputPath), { recursive: true });
+    fs.writeFileSync(outputPath, generateSystemReversePrompt(manifest, capability), 'utf8');
+    return outputPath;
+}
+
+function printHelp() {
+    console.log(`thachvd-kit spec
+
+Document an existing brownfield codebase as reviewed AS-IS system specs.
+The workflow is opt-in and does not change normal thachvd-kit development unless you run spec init.
+
+Quick start (same commands for one repo or many):
+  cd your-repo-or-workspace
+  thachvd-kit spec init
+  thachvd-kit spec index
+  thachvd-kit spec discover
+  # In your AI client: run /system-discovery
+  # Human-review system-specs/architecture/capability-map.md
+  thachvd-kit spec reverse
+  # In your AI client: run /system-reverse-engineer
+  thachvd-kit spec verify
+  # In your AI client: run /system-spec-review
+  thachvd-kit spec check
+  thachvd-kit spec link
+
+Documentation language:
+  thachvd-kit spec init --language vi
+  # Prose/headings are Vietnamese; code/API/event/schema/file identifiers remain unchanged.
+
+Analysis profile:
+  thachvd-kit spec init --profile backend
+  # Default is auto. Profiles adjust the discovery/review checklist, not the source of truth.
+
+Repository auto-detection:
+  - If the current directory is a Git repository, it is treated as a single-repo system.
+  - Otherwise, direct child Git repositories are detected as a multi-repo system.
+  - --repo remains available only as an override for unusual layouts.
+
+Usage:
+  thachvd-kit spec init [--name NAME] [--language en|vi] [--profile auto|backend|frontend|fullstack|mobile|infra] [--repo PATH ...] [--spec-root PATH] [--yes]
+  thachvd-kit spec index [--repo NAME ...] [--dry-run]
+  thachvd-kit spec discover
+  thachvd-kit spec reverse [CAPABILITY] [--reset]
+  thachvd-kit spec verify [CAPABILITY]
+  thachvd-kit spec check [--strict]
+  thachvd-kit spec doctor [--strict]
+  thachvd-kit spec link [--dry-run] [--allow-unverified]
+  thachvd-kit spec status
+
+Advanced optional integration (Claude Code):
+  thachvd-kit spec recipe-setup [--fullstack] [--dry-run]
+  # Installs Shinpr's /recipe-reverse-engineer helper. The primary workflow
+  # does not require this plugin.
+
+Commands:
+  init          Auto-detect one or many repositories and create the system manifest/spec skeleton.
+  index         Index every configured repository with codebase-memory-mcp.
+  discover      Write the handoff for /system-discovery.
+  reverse       Write the handoff for /system-reverse-engineer and create/resume its checkpoint.
+                No argument = whole approved system; a capability is a targeted refresh.
+  verify        Write the handoff for independent /system-spec-review.
+                A capability argument re-verifies only that refreshed capability and preserves other baselines.
+  check         Deterministically compare verified commits/source paths with current Git changes.
+                --strict exits non-zero when stale/unknown capabilities exist.
+  doctor        Read-only health report for repos, tools, skills, progress, verification, drift, and links.
+                --strict exits non-zero when any WARN/ERROR remains.
+  link          Add/update the managed system-spec block in each repository's AGENTS.md.
+                Requires all capabilities independently verified unless --allow-unverified is explicit.
+  status        Show configured repositories, reverse progress, and verification state.
+  recipe-setup  Optional: install Shinpr's reverse-engineering helper in each configured repo.
+
+Recommended order:
+  init -> index -> discover -> /system-discovery -> human review
+  -> reverse -> /system-reverse-engineer -> verify -> /system-spec-review
+  -> check -> link
+`);
+}
+
+function printStatus(workspaceRoot, manifest) {
+    console.log(`System: ${manifest.name}`);
+    console.log(`Manifest: ${MANIFEST_RELATIVE_PATH}`);
+    console.log(`Spec root: ${manifest.spec_root}`);
+    console.log(`Documentation language: ${manifest.language}`);
+    console.log(`Analysis profile: ${manifest.profile}`);
+    console.log('Repositories:');
+    for (const repo of manifest.repos) {
+        const exists = fs.existsSync(path.resolve(workspaceRoot, repo.path));
+        console.log(`  ${exists ? 'OK' : 'MISSING'} ${repo.name} -> ${repo.path}`);
+    }
+}
+
+function runSpecCommand(args, options = {}) {
+    const workspaceRoot = options.workspaceRoot || process.cwd();
+    const command = args[0];
+    if (!command || command === '--help' || command === '-h' || command === 'help') {
+        printHelp();
+        return 0;
+    }
+
+    try {
+        if (command === 'init') {
+            const commandArgs = args.slice(1);
+            const explicitLanguage = parseSingleOption(commandArgs, '--language');
+            const explicitProfile = parseSingleOption(commandArgs, '--profile');
+            const manifest = initializeWorkspace(workspaceRoot, {
+                name: parseSingleOption(commandArgs, '--name'),
+                language: explicitLanguage || userConfig.getDefaultSpecLanguage() || DEFAULT_SPEC_LANGUAGE,
+                profile: explicitProfile || userConfig.getDefaultSpecProfile() || DEFAULT_SPEC_PROFILE,
+                repos: parseOptionValues(commandArgs, '--repo'),
+                specRoot: parseSingleOption(commandArgs, '--spec-root', DEFAULT_SPEC_ROOT),
+                force: hasFlag(commandArgs, '--yes') || hasFlag(commandArgs, '-y')
+            });
+            console.log(`Created ${MANIFEST_RELATIVE_PATH} for ${manifest.name}`);
+            console.log(`Configured ${manifest.repos.length} repository(s); specs live in ${manifest.spec_root}`);
+            console.log(`Documentation language: ${manifest.language}`);
+            console.log(`Analysis profile: ${manifest.profile}`);
+            for (const repo of manifest.repos) console.log(`  - ${repo.name}: ${repo.path}`);
+            console.log('Installed /system-discovery, /system-reverse-engineer, and /system-spec-review in the workspace.');
+            console.log('Next: run thachvd-kit spec index');
+            return 0;
+        }
+
+        if (command === 'index') {
+            const commandArgs = args.slice(1);
+            const manifest = readManifest(workspaceRoot);
+            const results = indexWorkspace(workspaceRoot, manifest, {
+                repoNames: parseOptionValues(commandArgs, '--repo'),
+                dryRun: hasFlag(commandArgs, '--dry-run')
+            });
+            for (const result of results) {
+                if (result.dryRun) console.log(`WOULD INDEX ${result.name}: ${result.command.join(' ')}`);
+                else console.log(`${result.ok ? 'OK' : 'FAIL'} ${result.name} -> ${result.path}`);
+            }
+            const failures = results.filter(result => !result.ok);
+            if (failures.length > 0) {
+                process.exitCode = 1;
+                return 1;
+            }
+            return 0;
+        }
+
+        if (command === 'discover') {
+            const manifest = readManifest(workspaceRoot);
+            const outputPath = writeDiscoveryPrompt(workspaceRoot, manifest);
+            console.log(`Wrote ${toPortablePath(path.relative(workspaceRoot, outputPath))}`);
+            console.log('Next: run /system-discovery in your AI client, then review the generated capability map before continuing.');
+            return 0;
+        }
+
+        if (command === 'recipe-setup') {
+            const commandArgs = args.slice(1);
+            const manifest = readManifest(workspaceRoot);
+            const result = recipe.setupRecipePlugin(workspaceRoot, manifest, {
+                fullstack: hasFlag(commandArgs, '--fullstack'),
+                dryRun: hasFlag(commandArgs, '--dry-run')
+            });
+            for (const repoResult of result.results || []) {
+                const status = repoResult.dryRun ? 'WOULD INSTALL' : (repoResult.ok ? 'OK' : 'FAIL');
+                console.log(`${status} ${repoResult.name}`);
+            }
+            if (!result.ok) {
+                throw new Error(result.error || 'recipe plugin setup failed in one or more repositories');
+            }
+            console.log(`${result.dryRun ? 'Would install' : 'Installed'} ${result.plugin}@claude-code-workflows at project scope for all configured repositories`);
+            return 0;
+        }
+
+        if (command === 'reverse') {
+            const commandArgs = args.slice(1);
+            const capability = commandArgs.find(arg => !arg.startsWith('--')) || null;
+            const manifest = readManifest(workspaceRoot);
+            const progress = specState.ensureProgress(workspaceRoot, manifest, capability, {
+                reset: hasFlag(commandArgs, '--reset')
+            });
+            const outputPath = writeSystemReversePrompt(workspaceRoot, manifest, capability);
+            console.log(`Wrote ${toPortablePath(path.relative(workspaceRoot, outputPath))}`);
+            console.log(`${progress.resumed ? 'Resuming' : (progress.completed ? 'Existing completed' : 'Initialized')} checkpoint: ${toPortablePath(path.relative(workspaceRoot, progress.path))}`);
+            console.log(capability
+                ? `Next: run /system-reverse-engineer to refresh only ${capability}.`
+                : 'Next: run /system-reverse-engineer to document/resume every approved capability in the system.');
+            if (progress.completed && !hasFlag(commandArgs, '--reset')) {
+                console.log('Use --reset if you intentionally want to rerun this completed reverse scope.');
+            }
+            return 0;
+        }
+
+        if (command === 'verify') {
+            const commandArgs = args.slice(1);
+            const capability = commandArgs.find(arg => !arg.startsWith('--')) || null;
+            const manifest = readManifest(workspaceRoot);
+            const progress = specState.readProgress(workspaceRoot, manifest, capability);
+            if (!progress || progress.status !== 'completed') {
+                throw new Error(capability
+                    ? `Targeted reverse engineering for ${capability} is not completed. Finish /system-reverse-engineer first.`
+                    : 'Full-system reverse engineering is not completed. Finish /system-reverse-engineer first.');
+            }
+            if (capability) {
+                const existingVerification = specState.readVerification(workspaceRoot, manifest);
+                if (!existingVerification) {
+                    throw new Error('Targeted verification requires an existing full-system verification baseline.');
+                }
+                specState.validateVerification(manifest, existingVerification);
+                const slug = recipe.normalizeCapability(capability);
+                if (!existingVerification.capabilities[slug]) {
+                    throw new Error(`Targeted verification capability is not in the existing baseline: ${slug}. Run a full-system review instead.`);
+                }
+            }
+            const repoHeads = specState.captureRepoHeads(workspaceRoot, manifest);
+            const unavailable = Object.entries(repoHeads).filter(([, value]) => !value.ok);
+            if (unavailable.length > 0) {
+                throw new Error(`Cannot capture Git HEAD for: ${unavailable.map(([name]) => name).join(', ')}`);
+            }
+            const outputPath = writeSystemReviewPrompt(workspaceRoot, manifest, repoHeads, capability);
+            console.log(`Wrote ${toPortablePath(path.relative(workspaceRoot, outputPath))}`);
+            for (const [name, head] of Object.entries(repoHeads)) console.log(`  ${name}: ${head.commit}`);
+            console.log(capability
+                ? `Next: run /system-spec-review to re-verify only ${capability} and preserve unrelated baselines.`
+                : 'Next: run /system-spec-review for the full system. It must write _meta/review.md and _meta/verification.json.');
+            return 0;
+        }
+
+        if (command === 'check') {
+            const commandArgs = args.slice(1);
+            const manifest = readManifest(workspaceRoot);
+            const verification = specState.readVerification(workspaceRoot, manifest);
+            if (!verification) {
+                throw new Error('No verification metadata found. Run thachvd-kit spec verify, then /system-spec-review first.');
+            }
+            const report = specState.checkSpecDrift(workspaceRoot, manifest, verification);
+            console.log(specState.formatDriftReport(report));
+            if (hasFlag(commandArgs, '--strict') && report.stale_count > 0) {
+                process.exitCode = 1;
+                return 1;
+            }
+            return 0;
+        }
+
+        if (command === 'doctor') {
+            const commandArgs = args.slice(1);
+            const manifest = readManifest(workspaceRoot);
+            const report = specDoctor.runDoctor(workspaceRoot, manifest);
+            console.log(specDoctor.formatDoctorReport(report));
+            if (hasFlag(commandArgs, '--strict') && (report.counts.warn > 0 || report.counts.error > 0)) {
+                process.exitCode = 1;
+                return 1;
+            }
+            return 0;
+        }
+
+        if (command === 'link') {
+            const commandArgs = args.slice(1);
+            const manifest = readManifest(workspaceRoot);
+            if (!hasFlag(commandArgs, '--allow-unverified')) {
+                const verification = specState.readVerification(workspaceRoot, manifest);
+                if (!verification) {
+                    throw new Error('Specs are not independently verified. Run thachvd-kit spec verify, then /system-spec-review first.');
+                }
+                specState.validateVerification(manifest, verification);
+                if (!fs.existsSync(specState.reviewPath(workspaceRoot, manifest))) {
+                    throw new Error('Independent review report is missing: system-specs/_meta/review.md');
+                }
+                const unresolved = Object.entries(verification.capabilities)
+                    .filter(([, value]) => value.status !== 'verified')
+                    .map(([slug]) => slug);
+                if (unresolved.length > 0) {
+                    throw new Error(`Cannot link unverified capabilities: ${unresolved.join(', ')}. Re-review them or use --allow-unverified explicitly.`);
+                }
+                const drift = specState.checkSpecDrift(workspaceRoot, manifest, verification);
+                const stale = Object.entries(drift.capabilities)
+                    .filter(([, value]) => value.stale)
+                    .map(([slug]) => slug);
+                if (stale.length > 0) {
+                    throw new Error(`Cannot link stale/unknown capabilities: ${stale.join(', ')}. Refresh/re-verify them or use --allow-unverified explicitly.`);
+                }
+            }
+            const results = links.linkRepositories(workspaceRoot, manifest, {
+                dryRun: hasFlag(commandArgs, '--dry-run')
+            });
+            for (const result of results) {
+                const verb = result.dryRun ? (result.changed ? 'WOULD UPDATE' : 'OK') : (result.changed ? 'UPDATED' : 'OK');
+                console.log(`${result.ok ? verb : 'FAIL'} ${result.name} -> ${result.path || result.error}`);
+            }
+            if (results.some(result => !result.ok)) {
+                process.exitCode = 1;
+                return 1;
+            }
+            return 0;
+        }
+
+        if (command === 'status') {
+            const manifest = readManifest(workspaceRoot);
+            printStatus(workspaceRoot, manifest);
+            const progress = specState.readProgress(workspaceRoot, manifest);
+            const verification = specState.readVerification(workspaceRoot, manifest);
+            console.log(`Reverse progress: ${progress ? progress.status : 'not started'}`);
+            console.log(`Spec verification: ${verification ? (verification.verified_at || 'present') : 'not verified'}`);
+            return 0;
+        }
+
+        console.error(`Unknown spec subcommand: ${command}`);
+        printHelp();
+        process.exitCode = 1;
+        return 1;
+    } catch (error) {
+        console.error(`spec ${command} failed: ${error.message}`);
+        process.exitCode = 1;
+        return 1;
+    }
+}
+
+module.exports = {
+    MANIFEST_RELATIVE_PATH,
+    DEFAULT_SPEC_ROOT,
+    DEFAULT_SPEC_LANGUAGE,
+    SUPPORTED_SPEC_LANGUAGES,
+    DEFAULT_SPEC_PROFILE,
+    SUPPORTED_SPEC_PROFILES,
+    MANIFEST_SCHEMA_VERSION,
+    DISCOVERY_PROMPT_RELATIVE_PATH,
+    SYSTEM_REVERSE_PROMPT_RELATIVE_PATH,
+    SYSTEM_REVIEW_PROMPT_RELATIVE_PATH,
+    normalizeSpecLanguage,
+    normalizeSpecProfile,
+    languageInstruction,
+    profileInstruction,
+    discoverRepoPaths,
+    createManifest,
+    validateManifest,
+    readManifest,
+    initializeWorkspace,
+    indexWorkspace,
+    selectRepos,
+    generateDiscoveryPrompt,
+    writeDiscoveryPrompt,
+    generateSystemReversePrompt,
+    writeSystemReversePrompt,
+    generateSystemReviewPrompt,
+    writeSystemReviewPrompt,
+    runSpecCommand
+};