@urielsh/prodify 0.1.0

package/dist/core/flow-state.js

@@ -0,0 +1,262 @@
+import { ProdifyError } from './errors.js';
+import { isRuntimeProfileName } from './paths.js';
+import { RUNTIME_STATUS } from './state.js';
+export const STAGE_ORDER = ['understand', 'diagnose', 'architecture', 'plan', 'refactor', 'validate'];
+const STAGE_TASK_IDS = {
+    understand: '01-understand',
+    diagnose: '02-diagnose',
+    architecture: '03-architecture',
+    plan: '04-plan',
+    refactor: '05-refactor',
+    validate: '06-validate'
+};
+function cloneState(state) {
+    return {
+        ...state,
+        runtime: {
+            ...state.runtime,
+            completed_stages: [...state.runtime.completed_stages],
+            last_validated_contract_versions: {
+                ...state.runtime.last_validated_contract_versions
+            },
+            last_validation: state.runtime.last_validation
+                ? {
+                    ...state.runtime.last_validation,
+                    violated_rules: [...state.runtime.last_validation.violated_rules],
+                    missing_artifacts: [...state.runtime.last_validation.missing_artifacts],
+                    warnings: [...state.runtime.last_validation.warnings],
+                    diagnostics: [...state.runtime.last_validation.diagnostics]
+                }
+                : null,
+            failure_metadata: state.runtime.failure_metadata
+                ? { ...state.runtime.failure_metadata }
+                : null,
+            bootstrap: {
+                ...state.runtime.bootstrap
+            },
+            timestamps: {
+                ...state.runtime.timestamps
+            }
+        }
+    };
+}
+function nextStage(currentStage) {
+    const index = STAGE_ORDER.indexOf(currentStage);
+    if (index === -1) {
+        return null;
+    }
+    return STAGE_ORDER[index + 1] ?? null;
+}
+function pendingState(stage) {
+    return `${stage}_pending`;
+}
+function completeState(stage) {
+    return `${stage}_complete`;
+}
+function assertAgent(agent) {
+    if (!isRuntimeProfileName(agent)) {
+        throw new ProdifyError(`Unknown target agent: ${agent}`, {
+            code: 'UNKNOWN_TARGET'
+        });
+    }
+}
+function assertMode(mode) {
+    if (!['interactive', 'auto'].includes(mode)) {
+        throw new ProdifyError(`Unsupported runtime mode: ${mode}`, {
+            code: 'INVALID_RUNTIME_MODE'
+        });
+    }
+}
+function ensureStageCheckpoint(state) {
+    if (!state.runtime.current_stage) {
+        throw new ProdifyError('Cannot complete a runtime stage when no stage is active.', {
+            code: 'RUNTIME_STAGE_MISSING'
+        });
+    }
+    return state.runtime.current_stage;
+}
+export function stageToTaskId(stage) {
+    return STAGE_TASK_IDS[stage];
+}
+export function bootstrapFlowState(state, { agent, mode = 'interactive', now = null }) {
+    assertAgent(agent);
+    assertMode(mode);
+    const nextState = cloneState(state);
+    nextState.runtime.status = RUNTIME_STATUS.READY;
+    nextState.runtime.current_state = 'bootstrapped';
+    nextState.runtime.mode = mode;
+    nextState.runtime.current_stage = null;
+    nextState.runtime.current_task_id = null;
+    nextState.runtime.pending_stage = STAGE_ORDER[0];
+    nextState.runtime.completed_stages = [];
+    nextState.runtime.awaiting_user_validation = false;
+    nextState.runtime.last_validation_result = 'unknown';
+    nextState.runtime.last_validation = null;
+    nextState.runtime.last_validated_contract_versions = {};
+    nextState.runtime.resumable = true;
+    nextState.runtime.blocked_reason = null;
+    nextState.runtime.failure_metadata = null;
+    nextState.runtime.bootstrap = {
+        bootstrapped: true
+    };
+    nextState.runtime.next_action = mode === 'auto' ? '$prodify-execute --auto' : '$prodify-execute';
+    nextState.runtime.timestamps.bootstrapped_at = nextState.runtime.timestamps.bootstrapped_at ?? now;
+    nextState.runtime.timestamps.last_transition_at = now;
+    nextState.runtime.timestamps.completed_at = null;
+    return nextState;
+}
+export function startFlowExecution(state, { mode = state.runtime.mode ?? 'interactive', now = null } = {}) {
+    assertMode(mode);
+    const nextState = cloneState(state);
+    nextState.runtime.mode = mode;
+    if (nextState.runtime.current_state === 'validate_complete') {
+        nextState.runtime.status = RUNTIME_STATUS.COMPLETE;
+        nextState.runtime.current_state = 'completed';
+        nextState.runtime.current_stage = null;
+        nextState.runtime.current_task_id = null;
+        nextState.runtime.pending_stage = null;
+        nextState.runtime.awaiting_user_validation = false;
+        nextState.runtime.resumable = false;
+        nextState.runtime.next_action = 'none';
+        nextState.runtime.timestamps.completed_at = now;
+        nextState.runtime.timestamps.last_transition_at = now;
+        return nextState;
+    }
+    const stage = nextState.runtime.pending_stage;
+    if (!stage) {
+        throw new ProdifyError('Cannot start flow execution without a pending stage.', {
+            code: 'RUNTIME_STAGE_MISSING'
+        });
+    }
+    nextState.runtime.status = RUNTIME_STATUS.RUNNING;
+    nextState.runtime.current_state = pendingState(stage);
+    nextState.runtime.current_stage = stage;
+    nextState.runtime.current_task_id = stageToTaskId(stage);
+    nextState.runtime.pending_stage = null;
+    nextState.runtime.awaiting_user_validation = false;
+    nextState.runtime.blocked_reason = null;
+    nextState.runtime.failure_metadata = null;
+    nextState.runtime.next_action = '$prodify-resume';
+    nextState.runtime.resumable = true;
+    nextState.runtime.timestamps.last_transition_at = now;
+    return nextState;
+}
+export function completeFlowStage(state, { validation, now = null }) {
+    const currentStage = ensureStageCheckpoint(state);
+    if (validation.stage !== currentStage) {
+        throw new ProdifyError(`Validation result stage ${validation.stage} does not match active stage ${currentStage}.`, {
+            code: 'VALIDATION_STAGE_MISMATCH'
+        });
+    }
+    if (!validation.passed) {
+        return failFlowStage(state, {
+            reason: validation.violated_rules.map((issue) => issue.message).join('; ') || 'stage validation failed',
+            validation,
+            now
+        });
+    }
+    const nextState = cloneState(state);
+    if (!nextState.runtime.completed_stages.includes(currentStage)) {
+        nextState.runtime.completed_stages.push(currentStage);
+    }
+    nextState.runtime.last_validation_result = 'pass';
+    nextState.runtime.last_validation = validation;
+    nextState.runtime.last_validated_contract_versions[currentStage] = validation.contract_version;
+    nextState.runtime.blocked_reason = null;
+    nextState.runtime.failure_metadata = null;
+    nextState.runtime.timestamps.last_transition_at = now;
+    const upcomingStage = nextStage(currentStage);
+    if (!upcomingStage) {
+        nextState.runtime.current_state = 'validate_complete';
+        nextState.runtime.current_stage = currentStage;
+        nextState.runtime.current_task_id = stageToTaskId(currentStage);
+        nextState.runtime.pending_stage = null;
+        if (nextState.runtime.mode === 'interactive') {
+            nextState.runtime.status = RUNTIME_STATUS.AWAITING_VALIDATION;
+            nextState.runtime.awaiting_user_validation = true;
+            nextState.runtime.resumable = true;
+            nextState.runtime.next_action = '$prodify-resume';
+            return nextState;
+        }
+        return startFlowExecution(nextState, {
+            mode: nextState.runtime.mode ?? 'auto',
+            now
+        });
+    }
+    if (nextState.runtime.mode === 'interactive') {
+        nextState.runtime.status = RUNTIME_STATUS.AWAITING_VALIDATION;
+        nextState.runtime.current_state = completeState(currentStage);
+        nextState.runtime.current_stage = currentStage;
+        nextState.runtime.current_task_id = stageToTaskId(currentStage);
+        nextState.runtime.pending_stage = upcomingStage;
+        nextState.runtime.awaiting_user_validation = true;
+        nextState.runtime.resumable = true;
+        nextState.runtime.next_action = '$prodify-resume';
+        return nextState;
+    }
+    nextState.runtime.status = RUNTIME_STATUS.READY;
+    nextState.runtime.current_state = pendingState(upcomingStage);
+    nextState.runtime.current_stage = upcomingStage;
+    nextState.runtime.current_task_id = stageToTaskId(upcomingStage);
+    nextState.runtime.pending_stage = null;
+    nextState.runtime.awaiting_user_validation = false;
+    nextState.runtime.resumable = true;
+    nextState.runtime.next_action = '$prodify-execute --auto';
+    return nextState;
+}
+export function failFlowStage(state, { reason, validation = null, now = null }) {
+    const nextState = cloneState(state);
+    nextState.runtime.status = RUNTIME_STATUS.FAILED;
+    nextState.runtime.current_state = 'failed';
+    nextState.runtime.blocked_reason = reason;
+    nextState.runtime.awaiting_user_validation = false;
+    nextState.runtime.resumable = false;
+    nextState.runtime.next_action = 'repair runtime state';
+    nextState.runtime.last_validation_result = validation ? 'fail' : nextState.runtime.last_validation_result;
+    nextState.runtime.last_validation = validation;
+    nextState.runtime.failure_metadata = {
+        stage: validation?.stage ?? nextState.runtime.current_stage,
+        contract_version: validation?.contract_version ?? null,
+        reason
+    };
+    nextState.runtime.timestamps.last_transition_at = now;
+    return nextState;
+}
+export function getResumeDecision(state) {
+    const runtime = state.runtime;
+    if (runtime.current_state === 'completed' || runtime.status === RUNTIME_STATUS.COMPLETE) {
+        return {
+            resumable: false,
+            command: null,
+            reason: 'flow complete'
+        };
+    }
+    if (runtime.current_state === 'failed' || runtime.current_state === 'blocked') {
+        return {
+            resumable: false,
+            command: null,
+            reason: runtime.blocked_reason ?? 'runtime is blocked'
+        };
+    }
+    if (!runtime.resumable) {
+        return {
+            resumable: false,
+            command: null,
+            reason: runtime.blocked_reason ?? 'runtime not bootstrapped'
+        };
+    }
+    if (runtime.status === RUNTIME_STATUS.READY) {
+        return {
+            resumable: true,
+            command: runtime.mode === 'auto' ? '$prodify-execute --auto' : '$prodify-execute',
+            reason: runtime.pending_stage
+                ? `ready for ${runtime.pending_stage}`
+                : runtime.current_state
+        };
+    }
+    return {
+        resumable: true,
+        command: '$prodify-resume',
+        reason: runtime.current_state
+    };
+}

package/dist/core/fs.js

@@ -0,0 +1,50 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+export async function pathExists(targetPath) {
+    try {
+        await fs.access(targetPath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export async function ensureDir(targetPath) {
+    await fs.mkdir(targetPath, { recursive: true });
+}
+export async function writeFileEnsuringDir(targetPath, content) {
+    await ensureDir(path.dirname(targetPath));
+    await fs.writeFile(targetPath, content, 'utf8');
+}
+export async function copyTree(sourceDir, destinationDir) {
+    const entries = await fs.readdir(sourceDir, { withFileTypes: true });
+    await ensureDir(destinationDir);
+    for (const entry of entries) {
+        const sourcePath = path.join(sourceDir, entry.name);
+        const destinationPath = path.join(destinationDir, entry.name);
+        if (entry.isDirectory()) {
+            await copyTree(sourcePath, destinationPath);
+        }
+        else if (entry.isFile()) {
+            await writeFileEnsuringDir(destinationPath, await fs.readFile(sourcePath, 'utf8'));
+        }
+    }
+}
+export async function listFilesRecursive(rootDir, prefix = '') {
+    const entries = await fs.readdir(rootDir, { withFileTypes: true });
+    const files = [];
+    for (const entry of entries.sort((a, b) => a.name.localeCompare(b.name))) {
+        const nextPrefix = prefix ? path.posix.join(prefix, entry.name) : entry.name;
+        const fullPath = path.join(rootDir, entry.name);
+        if (entry.isDirectory()) {
+            files.push(...(await listFilesRecursive(fullPath, nextPrefix)));
+        }
+        else if (entry.isFile()) {
+            files.push({
+                fullPath,
+                relativePath: nextPrefix
+            });
+        }
+    }
+    return files;
+}

package/dist/core/install.js

@@ -0,0 +1,44 @@
+import fs from 'node:fs/promises';
+import { ProdifyError } from './errors.js';
+import { pathExists, writeFileEnsuringDir } from './fs.js';
+import { detectManagedFileState, parseManagedFileHeader } from './managed-files.js';
+import { resolveRepoPath, resolveTargetPath } from './paths.js';
+import { assertSupportedInstallTarget } from '../legacy/targets.js';
+export async function installTarget(repoRoot, agent, options = {}) {
+    const prodifyDir = resolveRepoPath(repoRoot, '.prodify');
+    if (!(await pathExists(prodifyDir))) {
+        throw new ProdifyError('Canonical .prodify/ directory is missing.', {
+            code: 'PRODIFY_MISSING'
+        });
+    }
+    const targetMetadata = assertSupportedInstallTarget(agent);
+    const targetPath = resolveTargetPath(repoRoot, agent);
+    if (!targetPath) {
+        throw new ProdifyError(`Unknown target agent: ${agent}`, {
+            code: 'UNKNOWN_TARGET'
+        });
+    }
+    const nextContent = await targetMetadata.generator(repoRoot);
+    if (await pathExists(targetPath)) {
+        const existingContent = await fs.readFile(targetPath, 'utf8');
+        const managedHeader = parseManagedFileHeader(existingContent);
+        if (!managedHeader) {
+            throw new ProdifyError(`Target file already exists and is not Prodify-managed: ${targetPath}`, {
+                code: 'UNMANAGED_TARGET_EXISTS'
+            });
+        }
+        const state = detectManagedFileState(existingContent, nextContent);
+        if (state.state === 'conflict' && !options.force) {
+            throw new ProdifyError(`Managed target has manual edits and is blocked: ${targetPath}. Re-run with --force to overwrite.`, {
+                code: 'MANAGED_CONFLICT'
+            });
+        }
+    }
+    await writeFileEnsuringDir(targetPath, nextContent);
+    return {
+        agent: targetMetadata.agent,
+        targetPath,
+        changed: true,
+        status: targetMetadata.status
+    };
+}

package/dist/core/managed-files.js

@@ -0,0 +1,106 @@
+import crypto from 'node:crypto';
+import { isRuntimeProfileName } from './paths.js';
+const HEADER_START = '<!--';
+const HEADER_END = '-->';
+export function renderCanonicalSourceList(sourcePaths) {
+    return [...sourcePaths].sort().join(', ');
+}
+export function parseManagedFileHeader(content) {
+    if (!content.startsWith(HEADER_START)) {
+        return null;
+    }
+    const endIndex = content.indexOf(HEADER_END);
+    if (endIndex === -1) {
+        return null;
+    }
+    const rawHeader = content.slice(HEADER_START.length, endIndex).trim();
+    const lines = rawHeader.split('\n').map((line) => line.trim()).filter(Boolean);
+    const metadata = {};
+    for (const line of lines) {
+        if (line === 'Generated by Prodify.') {
+            metadata.generatedByProdify = true;
+            continue;
+        }
+        const separatorIndex = line.indexOf(':');
+        if (separatorIndex === -1) {
+            if (line === 'Manual edits may be overwritten.') {
+                metadata.manualEditsWarning = true;
+            }
+            continue;
+        }
+        const key = line.slice(0, separatorIndex).trim();
+        const value = line.slice(separatorIndex + 1).trim();
+        metadata[key] = value;
+    }
+    if (metadata.generatedByProdify !== true) {
+        return null;
+    }
+    const targetAgent = metadata['Target agent'];
+    const canonicalSource = metadata['Canonical source'];
+    const regenerateWith = metadata['Regenerate with'];
+    const bodyFingerprint = metadata['Body fingerprint'];
+    if (typeof targetAgent !== 'string'
+        || !isRuntimeProfileName(targetAgent)
+        || typeof canonicalSource !== 'string'
+        || typeof regenerateWith !== 'string') {
+        return null;
+    }
+    return {
+        targetAgent,
+        canonicalSources: canonicalSource.split(',').map((item) => item.trim()).filter(Boolean),
+        regenerateWith,
+        bodyFingerprint: typeof bodyFingerprint === 'string' ? bodyFingerprint : null,
+        manualEditsWarning: metadata.manualEditsWarning === true,
+        headerLength: endIndex + HEADER_END.length
+    };
+}
+export function isManagedFileContent(content) {
+    return parseManagedFileHeader(content) !== null;
+}
+export function extractManagedBody(content, headerLength) {
+    let body = content.slice(headerLength);
+    if (body.startsWith('\r\n\r\n')) {
+        return body.slice(4);
+    }
+    if (body.startsWith('\n\n')) {
+        return body.slice(2);
+    }
+    if (body.startsWith('\r\n')) {
+        return body.slice(2);
+    }
+    if (body.startsWith('\n')) {
+        return body.slice(1);
+    }
+    return body;
+}
+export function computeBodyFingerprint(body) {
+    return crypto.createHash('sha256').update(body, 'utf8').digest('hex');
+}
+export function detectManagedFileState(existingContent, expectedContent) {
+    const existingHeader = parseManagedFileHeader(existingContent);
+    if (!existingHeader) {
+        return {
+            state: 'unmanaged',
+            header: null
+        };
+    }
+    const expectedHeader = parseManagedFileHeader(expectedContent);
+    const currentBody = extractManagedBody(existingContent, existingHeader.headerLength);
+    const currentFingerprint = computeBodyFingerprint(currentBody);
+    if (existingHeader.bodyFingerprint && existingHeader.bodyFingerprint !== currentFingerprint) {
+        return {
+            state: 'conflict',
+            header: existingHeader
+        };
+    }
+    if (existingContent === expectedContent) {
+        return {
+            state: 'unchanged',
+            header: existingHeader
+        };
+    }
+    return {
+        state: 'outdated',
+        header: expectedHeader ?? existingHeader
+    };
+}

package/dist/core/paths.js

@@ -0,0 +1,56 @@
+import path from 'node:path';
+export const RUNTIME_PROFILE_NAMES = ['codex', 'claude', 'copilot', 'opencode'];
+export const USER_OWNED_CANONICAL_PATHS = [
+    '.prodify/AGENTS.md',
+    '.prodify/project.md',
+    '.prodify/planning.md'
+];
+export const USER_OWNED_CANONICAL_PREFIXES = [
+    '.prodify/contracts-src/'
+];
+export const REQUIRED_CANONICAL_PATHS = [
+    '.prodify/AGENTS.md',
+    '.prodify/artifacts/README.md',
+    '.prodify/contracts-src/README.md',
+    '.prodify/contracts-src/architecture.contract.md',
+    '.prodify/contracts-src/diagnose.contract.md',
+    '.prodify/contracts-src/plan.contract.md',
+    '.prodify/contracts-src/refactor.contract.md',
+    '.prodify/contracts-src/understand.contract.md',
+    '.prodify/contracts-src/validate.contract.md',
+    '.prodify/metrics/README.md',
+    '.prodify/project.md',
+    '.prodify/planning.md',
+    '.prodify/runtime-commands.md',
+    '.prodify/skills/README.md',
+    '.prodify/skills/registry.json',
+    '.prodify/skills/domain/react-frontend.skill.json',
+    '.prodify/skills/domain/typescript-backend.skill.json',
+    '.prodify/skills/quality-policy/maintainability-review.skill.json',
+    '.prodify/skills/quality-policy/security-hardening.skill.json',
+    '.prodify/skills/quality-policy/test-hardening.skill.json',
+    '.prodify/skills/stage-method/architecture-method.skill.json',
+    '.prodify/skills/stage-method/codebase-scanning.skill.json',
+    '.prodify/skills/stage-method/diagnosis-method.skill.json',
+    '.prodify/skills/stage-method/planning-method.skill.json',
+    '.prodify/skills/stage-method/refactoring-method.skill.json',
+    '.prodify/skills/stage-method/validation-method.skill.json',
+    '.prodify/state.json',
+    '.prodify/tasks/README.md',
+    '.prodify/rules/README.md',
+    '.prodify/templates/README.md',
+    '.prodify/version.json'
+];
+export function isRuntimeProfileName(value) {
+    return typeof value === 'string' && RUNTIME_PROFILE_NAMES.includes(value);
+}
+export function normalizeRepoRelativePath(relativePath) {
+    const normalized = relativePath.replaceAll('\\', '/');
+    return path.posix.normalize(normalized).replace(/^\/+/, '');
+}
+export function resolveRepoPath(repoRoot, relativePath) {
+    return path.join(repoRoot, ...normalizeRepoRelativePath(relativePath).split('/'));
+}
+export function resolveCanonicalPath(repoRoot, relativePath) {
+    return resolveRepoPath(repoRoot, relativePath);
+}

package/dist/core/preset-validation.js

@@ -0,0 +1,43 @@
+import { ProdifyError } from './errors.js';
+const REQUIRED_PRESET_ENTRIES = [
+    '.prodify/AGENTS.md',
+    '.prodify/artifacts/README.md',
+    '.prodify/contracts-src/README.md',
+    '.prodify/contracts-src/architecture.contract.md',
+    '.prodify/contracts-src/diagnose.contract.md',
+    '.prodify/contracts-src/plan.contract.md',
+    '.prodify/contracts-src/refactor.contract.md',
+    '.prodify/contracts-src/understand.contract.md',
+    '.prodify/contracts-src/validate.contract.md',
+    '.prodify/metrics/README.md',
+    '.prodify/project.md',
+    '.prodify/planning.md',
+    '.prodify/runtime-commands.md',
+    '.prodify/skills/README.md',
+    '.prodify/skills/registry.json',
+    '.prodify/skills/domain/react-frontend.skill.json',
+    '.prodify/skills/domain/typescript-backend.skill.json',
+    '.prodify/skills/quality-policy/maintainability-review.skill.json',
+    '.prodify/skills/quality-policy/security-hardening.skill.json',
+    '.prodify/skills/quality-policy/test-hardening.skill.json',
+    '.prodify/skills/stage-method/architecture-method.skill.json',
+    '.prodify/skills/stage-method/codebase-scanning.skill.json',
+    '.prodify/skills/stage-method/diagnosis-method.skill.json',
+    '.prodify/skills/stage-method/planning-method.skill.json',
+    '.prodify/skills/stage-method/refactoring-method.skill.json',
+    '.prodify/skills/stage-method/validation-method.skill.json',
+    '.prodify/state.json',
+    '.prodify/version.json',
+    '.prodify/tasks/README.md',
+    '.prodify/rules/README.md',
+    '.prodify/templates/README.md'
+];
+export function validatePresetEntries(entries) {
+    const entryPaths = new Set(entries.map((entry) => entry.relativePath));
+    const missing = REQUIRED_PRESET_ENTRIES.filter((requiredPath) => !entryPaths.has(requiredPath));
+    if (missing.length > 0) {
+        throw new ProdifyError(`Default preset is missing required canonical files: ${missing.join(', ')}`, {
+            code: 'PRESET_INVALID'
+        });
+    }
+}

package/dist/core/prompt-builder.js

@@ -0,0 +1,63 @@
+import { STAGE_ORDER, stageToTaskId } from './flow-state.js';
+import { getRuntimeProfile } from './targets.js';
+export function buildBootstrapPrompt(profileName = 'codex') {
+    return (getRuntimeProfile(profileName ?? 'codex') ?? getRuntimeProfile('codex')).bootstrapPrompt;
+}
+export function hasManualBootstrapGuidance(markdown) {
+    return markdown.includes('.prodify/AGENTS.md') && markdown.includes('$prodify-init');
+}
+export function buildRuntimeCommandReference(options = {}) {
+    const concise = options.concise ?? false;
+    const profile = getRuntimeProfile(options.profileName ?? 'codex') ?? getRuntimeProfile('codex');
+    const bootstrapPrompt = profile?.bootstrapPrompt ?? buildBootstrapPrompt('codex');
+    const lines = [
+        '# Runtime Commands',
+        '',
+        'Manual bootstrap:',
+        `- First tell the agent: "${bootstrapPrompt}"`,
+        '- Before using `$prodify-*` in a new agent environment, run `prodify setup-agent <agent>` once outside the repo.',
+        '- Keep the workflow anchored to `.prodify/` files only.',
+        '- Humans edit `.prodify/contracts-src/`; runtime reads only `.prodify/contracts/*.contract.json`.',
+        '- Stage skill definitions live under `.prodify/skills/` and can assist a stage without overriding its contract or validator.',
+        '',
+        'Run these commands inside your coding agent after `prodify init` has created the repo scaffolding.',
+        '',
+        '- `$prodify-init`: inspect `.prodify/`, detect or resolve the active agent runtime, initialize `.prodify/state.json`, and prepare the bootstrapped state without locking the repo to one agent.',
+        '- `$prodify-execute`: run one stage, write stage artifacts, validate them against compiled contracts, then pause in interactive mode.',
+        '- `$prodify-execute --auto`: continue through the full workflow without pausing unless there is a hard failure, policy block, required approval threshold, or invalid state.',
+        '- `$prodify-resume`: continue from `.prodify/state.json` after a pause, interruption, or validation checkpoint.',
+        '',
+        'Stage order:',
+        `- ${STAGE_ORDER.map((stage) => `${stage} (${stageToTaskId(stage)})`).join(' -> ')}`,
+        '',
+        'Resume rules:',
+        '- interactive mode pauses between stages and expects validation before resume',
+        '- auto mode keeps advancing while state remains valid',
+        '- failed or corrupt state must stop with a clear reason'
+    ];
+    if (concise) {
+        return [
+            '# Runtime Commands',
+            '',
+            `- First prompt: "${bootstrapPrompt}"`,
+            '- Run `prodify setup-agent <agent>` once per machine before using agent runtime commands.',
+            '- `$prodify-init`: bootstrap `.prodify/state.json` for the active agent runtime without repo-level locking.',
+            '- `$prodify-execute`: run one stage, then pause.',
+            '- `$prodify-execute --auto`: continue until a hard stop.',
+            '- `$prodify-resume`: continue from saved state.'
+        ].join('\n') + '\n';
+    }
+    return `${lines.join('\n')}\n`;
+}
+export function buildExecutionPrompt(state) {
+    const stage = state.runtime.current_stage ?? state.runtime.pending_stage ?? 'none';
+    const task = state.runtime.current_task_id ?? (state.runtime.pending_stage ? stageToTaskId(state.runtime.pending_stage) : 'none');
+    return [
+        `Current stage: ${stage}`,
+        `Current task: ${task}`,
+        `Current state: ${state.runtime.current_state}`,
+        `Mode: ${state.runtime.mode ?? 'unset'}`,
+        `Status: ${state.runtime.status}`,
+        `Next action: ${state.runtime.next_action}`
+    ].join('\n');
+}