@urielsh/prodify 0.1.0

package/docs/generated-file-headers.md

@@ -0,0 +1,45 @@
+# Generated File Headers
+
+## Goal
+Define a standard header block for every generated compatibility file.
+
+## Required Header Content
+Every generated file header must state:
+- the file is generated by Prodify
+- the canonical source file or files
+- the agent target
+- the command used to regenerate the file
+- that manual edits may be overwritten
+
+## Standard Markdown Header Template
+
+```md
+<!--
+Generated by Prodify.
+Target agent: <agent>
+Canonical source: <relative path or comma-separated paths>
+Regenerate with: prodify sync --agent <agent>
+Manual edits may be overwritten.
+-->
+```
+
+## Usage Rules
+- The header must be the first content in the generated file.
+- The header must use repository-relative paths.
+- If multiple canonical sources are used, list them in deterministic order.
+- The header must remain stable across repeated sync operations unless the source list or command changes.
+
+## Header Variants
+
+### Direct-Copy Targets
+- Use the standard header.
+- Follow immediately with the canonical markdown body.
+
+### Transformed Targets
+- Use the standard header.
+- Keep the body valid for the destination format.
+- Do not hide source provenance even when content is transformed.
+
+## Compatibility Rule
+- The header format must be valid inside markdown-based instruction files.
+- HTML comment syntax is the default because it is broadly markdown-compatible and minimally intrusive.

package/docs/generation-rules.md

@@ -0,0 +1,94 @@
+# Compatibility File Generation Rules
+
+## Goal
+Describe a possible future compatibility-file generation pipeline without treating it as active default behavior.
+
+## Current Product Behavior
+- The supported lifecycle bootstraps agents directly from `.prodify/AGENTS.md`.
+- `prodify init` and `prodify update` do not generate compatibility files.
+- The rules below are design notes for future or opt-in compatibility surfaces only.
+
+## General Generation Pipeline
+1. Resolve repository root.
+2. Load canonical `.prodify/` sources required for the target.
+3. Apply the target-specific mapping rules.
+4. Prepend the standard generated-file header.
+5. Normalize output formatting.
+6. Write the managed compatibility file to the target path.
+
+## Target Rules
+
+### Codex
+- Agent support status: `supported`
+- Compatibility-file status: not enabled in the default flow
+- Canonical sources:
+  - `.prodify/AGENTS.md`
+- Output path:
+  - `AGENTS.md`
+- Generation mode:
+  - direct copy with generated header
+- Transformations:
+  - prepend standard generated header
+  - preserve markdown body exactly after the header
+- Unsupported feature handling:
+  - do not imply this mode is active until a dedicated opt-in command exists
+
+### Claude
+- Agent support status: bootstrap path supported
+- Compatibility-file status: planned
+- Canonical sources:
+  - `.prodify/AGENTS.md`
+- Output path:
+  - `CLAUDE.md`
+- Generation mode:
+  - direct copy with generated header
+- Transformations:
+  - prepend standard generated header
+  - optionally normalize the top-level title to match the output filename in a future revision
+- Unsupported feature handling:
+  - emit a clear “planned target” note if generation is not yet enabled in the CLI
+
+### Copilot
+- Agent support status: bootstrap path supported
+- Compatibility-file status: planned
+- Canonical sources:
+  - `.prodify/AGENTS.md`
+  - `.prodify/project.md`
+- Output path:
+  - `.github/copilot-instructions.md`
+- Generation mode:
+  - transformed output with generated header
+- Transformations:
+  - merge high-signal repository instructions from `.prodify/AGENTS.md`
+  - inject concise project context from `.prodify/project.md`
+  - omit orchestration details that are not useful in a static instruction file
+- Unsupported feature handling:
+  - if required concise transformation rules are unavailable, stop instead of generating a lossy or ambiguous file
+
+### OpenCode
+- Agent support status: bootstrap path supported
+- Compatibility-file status: experimental
+- Canonical sources:
+  - `.prodify/AGENTS.md`
+- Output path:
+  - `.opencode/AGENTS.md`
+- Generation mode:
+  - direct copy with generated header
+- Transformations:
+  - prepend standard generated header
+  - preserve canonical body by default
+- Unsupported feature handling:
+  - clearly report the experimental status and provisional target path
+
+## Shared Transformation Rules
+- Generated files must keep markdown valid.
+- Generated files must normalize line endings to LF.
+- Generated files must preserve stable section order.
+- Generation must be deterministic for identical inputs.
+
+## Codex Reference Mapping
+If compatibility-file generation is reintroduced, Codex remains the simplest reference mapping because it has:
+- one canonical source file
+- one explicit output path
+- no required semantic transformation beyond the generated header
+- a historically familiar repository-root instruction file pattern

package/docs/idempotency-guarantees.md

@@ -0,0 +1,31 @@
+# Idempotency Guarantees
+
+## Goal
+Define what idempotent Prodify sync behavior means and how it is preserved.
+
+## Idempotency Definition
+For identical:
+- canonical `.prodify/` sources
+- generation rules
+- target set
+
+`prodify sync` must produce byte-identical generated files on repeated runs.
+
+## Stability Constraints
+- Section ordering must be deterministic.
+- Multi-source canonical input order must be deterministic.
+- Header field ordering must be deterministic.
+- Line endings must be normalized to LF.
+- Final newline behavior must be stable.
+- Optional fingerprint metadata must be computed deterministically.
+
+## Diff Prevention Rules
+- Avoid timestamps in generated files.
+- Avoid non-deterministic ordering from filesystem traversal.
+- Avoid unstable whitespace changes.
+- Do not rewrite unchanged managed files.
+
+## Command Behavior
+- A repeated `prodify sync` with unchanged inputs should report targets as unchanged.
+- Meaningless diffs are a bug.
+- `prodify doctor` should be able to confirm that a generated file already matches the expected output exactly.

package/docs/managed-file-detection.md

@@ -0,0 +1,45 @@
+# Managed File Detection
+
+## Goal
+Define how Prodify reliably identifies compatibility files it generated.
+
+## Primary Detection Strategy
+Prodify-managed files are identified by the standard generated-file header at the top of the file.
+
+The header must include:
+- `Generated by Prodify`
+- target agent
+- canonical source path or paths
+- regenerate command
+
+## Required Marker Semantics
+- A file is managed only if all required header fields are present.
+- Header fields must use repository-relative canonical source paths.
+- Partial or malformed headers must not be treated as managed automatically.
+
+## Optional Integrity Metadata
+Prodify may include an additional metadata line in the header:
+
+```text
+Body fingerprint: <stable hash>
+```
+
+If present, the fingerprint is computed from the generated body after the header is excluded.
+
+## Detection Rules
+
+### Managed
+- Valid header present
+- target maps to a known compatibility target
+- canonical source paths are valid
+
+### Unmanaged
+- No Prodify header
+- malformed header
+- unknown target
+- canonical source path cannot be resolved
+
+## Reliability Rules
+- Managed-file detection must be deterministic.
+- Sync and doctor must use the same detection logic.
+- Prodify must never silently “adopt” an unmanaged file based on loose heuristics.

package/docs/manual-edit-conflicts.md

@@ -0,0 +1,37 @@
+# Manual Edit Conflict Behavior
+
+## Goal
+Define what happens when users manually edit generated compatibility files.
+
+## Default Policy
+- Canonical `.prodify/` files remain the source of truth.
+- Manual edits to generated files are treated as drift unless explicitly adopted through canonical changes.
+- `prodify sync` must not silently erase manual edits without first detecting the conflict.
+
+## Conflict Detection
+A manual-edit conflict exists when:
+- a file is recognized as Prodify-managed
+- the current file content does not match the expected generated output
+- the difference cannot be explained only by canonical source changes already being applied in the regenerated output
+
+## Default Sync Behavior
+- Stop and report the conflict.
+- Identify the file path and target agent.
+- Instruct the user to either:
+  - move the change into `.prodify/`
+  - rerun with `--force`
+  - rerun with `--backup`
+
+## Optional Resolution Modes
+
+### `--force`
+- Overwrite the managed generated file with the canonical output.
+- No backup created automatically.
+
+### `--backup`
+- Write a backup copy before overwriting.
+- Backup path should live under `.prodify/backups/` or another deterministic internal backup directory.
+
+## Canonical Rule
+- Conflict resolution must preserve the rule that canonical `.prodify/` content wins.
+- Generated files must not become a shadow source of truth.

package/docs/opencode-support.md

@@ -0,0 +1,27 @@
+# OpenCode Support
+
+## Goal
+Define the current OpenCode bootstrap path and the experimental compatibility-file surface.
+
+## Current Supported Behavior
+- Bootstrap path: `.prodify/AGENTS.md`
+- Root or `.opencode/` compatibility file: not part of the default lifecycle
+
+## Experimental Compatibility Surface
+- Status: `experimental`
+- Canonical source: `.prodify/AGENTS.md`
+- Future target path if enabled: `.opencode/AGENTS.md`
+- Default design: direct copy with generated header.
+- Read `.prodify/AGENTS.md`.
+- Prepend the standard generated-file header for target `opencode`.
+- Write to `.opencode/AGENTS.md` only when the user explicitly opts into the experimental target.
+
+## Limitations
+- The target path is provisional until a live OpenCode integration confirms the contract.
+- Experimental support should never be enabled implicitly.
+- If the integration contract differs, Prodify must surface that mismatch instead of silently adapting.
+
+## Placeholder Strategy
+- Document the target and generation rule now.
+- Keep CLI support opt-in and clearly labeled experimental.
+- Prefer “not yet validated” over claiming current default support for compatibility-file generation.

package/docs/ownership-rules.md

@@ -0,0 +1,39 @@
+# Source vs Generated Ownership Rules
+
+## Goal
+Define who owns canonical `.prodify/` files and how Prodify treats generated compatibility files.
+
+## Ownership Model
+
+### Canonical Files
+- Users edit canonical files under `.prodify/`.
+- Canonical files are the only durable source of truth for Prodify-managed guidance and workflow content.
+- Prodify commands may create canonical files during `prodify init` or upgrade them during explicit upgrade operations.
+
+### Generated Files
+- Generated compatibility files are future or non-default derived artifacts.
+- They must always be reproducible from canonical `.prodify/` sources.
+- Users should not treat generated files as the place to make lasting changes.
+
+## Overwrite Rules
+- `prodify sync` may overwrite managed generated files.
+- `prodify setup-agent <target>` must not write generated files into repositories.
+- If compatibility-file generation is reintroduced later, it must remain explicit and separate from repo initialization.
+- Prodify must not overwrite unmanaged files silently.
+- If a target path exists but is not recognized as Prodify-managed, Prodify must stop unless an explicit override flag is provided.
+
+## Standard Warning Header Policy
+Every generated compatibility file must begin with a standard warning header that states:
+- the file is generated by Prodify
+- the canonical source file or files
+- the command used to regenerate it
+- that manual edits may be overwritten
+
+## User Editing Rule
+- Users should make durable changes in `.prodify/`.
+- Manual edits to generated files are temporary and subject to conflict policy.
+- If users need custom generated output, they should change canonical sources or supported overlay settings, not patch generated files directly.
+
+## Source Of Truth Rule
+- If canonical and generated content differ, canonical content wins.
+- Generated content must be treated as disposable and reproducible.

package/docs/path-resolution-rules.md

@@ -0,0 +1,40 @@
+# Path Resolution Rules
+
+## Goal
+Define deterministic repository-root detection and output-path behavior for Prodify commands.
+
+## Repository Root Detection
+Prodify must resolve the repository root using this order:
+1. Explicit `--repo` argument, if provided.
+2. Current working directory, if it contains `.prodify/`.
+3. Nearest parent directory containing `.prodify/`.
+4. Nearest parent directory containing `.git/`, if `.prodify/` has not yet been created and the command supports bootstrap behavior.
+
+If no repository root can be resolved, the command must stop.
+
+## Path Normalization Rules
+- All stored paths must be repository-relative.
+- Absolute input paths may be accepted, but they must be normalized back to repository-relative paths before being written into managed files or reports.
+- Path comparison must use normalized separators and remove redundant `.` segments.
+- Prodify must not write outside the resolved repository root.
+
+## Target Output Rules
+- Every compatibility target path must resolve relative to the repository root.
+- Parent directories may be created automatically when the target path is managed by Prodify.
+- Commands must verify whether the target path already exists before writing.
+
+## Existing File Behavior
+
+### Managed Existing File
+- If the file has a valid Prodify managed-file header, Prodify may update it.
+- Drift handling must follow the managed-file conflict policy.
+
+### Unmanaged Existing File
+- If the file exists without a valid managed-file header, Prodify must stop by default.
+- An explicit override flag is required to replace or adopt the file.
+- This is the unmanaged-file path and it must never be resolved implicitly.
+
+## Conflict Behavior
+- Managed files with detected manual edits should trigger the manual-edit conflict flow.
+- Unmanaged files at agent target paths should block generation by default.
+- Resolution must be explicit and deterministic; no silent adoption is allowed.

package/docs/preset-structure.md

@@ -0,0 +1,49 @@
+# Preset Structure
+
+## Goal
+Define how Prodify ships reusable preset packs that populate canonical `.prodify/` contents.
+
+## Preset Directory Layout
+
+```text
+presets/
+  <preset-name>/
+    preset.json
+    canonical/
+      AGENTS.md
+      project.md
+      planning.md
+      tasks/
+      rules/
+      templates/
+    overlays/
+      codex/
+      claude/
+      copilot/
+      opencode/
+```
+
+## Layout Semantics
+
+### `preset.json`
+- preset name
+- preset version
+- schema version
+- description
+
+### `canonical/`
+- base files copied into `.prodify/` by `prodify init`
+- agent-neutral source-of-truth content
+
+### `overlays/`
+- optional agent-specific additions or transformations applied on top of the base canonical content
+- may define target-specific snippets, not compatibility outputs themselves
+
+## Default vs Agent-Specific Content
+- The default preset provides a coherent base `.prodify/` installation.
+- Agent overlays adjust the canonical starter content when a user explicitly chooses them.
+- Overlays must never replace the principle that `.prodify/` remains canonical.
+
+## Mapping Rule
+- Presets populate canonical `.prodify/` files and folders.
+- Compatibility files are still generated later by install or sync commands.

package/docs/skill-system.md

@@ -0,0 +1,67 @@
+# Contract-Bounded Skill System
+
+## Purpose
+
+Prodify stages can use bounded skills to improve execution quality without weakening deterministic contracts.
+
+The governing model is:
+
+- contract defines required inputs, outputs, write boundaries, and success criteria
+- validator decides pass or fail
+- skill routing determines which stage-compatible skills may assist execution
+
+## Ownership
+
+- Stage routing lives in contract source frontmatter as `skill_routing`.
+- Concrete skill definitions live in `.prodify/skills/`.
+- `registry.json` is the discoverable manifest for product-owned skills.
+
+## Skill Model
+
+Every skill definition includes:
+
+- `id`
+- `name`
+- `version`
+- `category`
+- `description`
+- `intended_use`
+- `stage_compatibility`
+- optional `activation_conditions`
+- `execution_guidance`
+- optional `caution_guidance`
+
+Supported categories:
+
+- `stage-method`
+- `domain`
+- `quality-policy`
+
+## Routing Model
+
+Each compiled stage contract may include:
+
+- `default_skills`
+- `allowed_skills`
+- `conditional_skills`
+
+Conditional activation is explicit and deterministic. Current predicates can match:
+
+- `language`
+- `framework`
+- `project_type`
+- `architecture_pattern`
+- `risk_signal`
+
+## Determinism Rules
+
+- Skills never override contract-required artifacts, allowed write paths, or validation.
+- Stage-incompatible or unknown skills are rejected.
+- Skill resolution is based on explicit repo context detection plus contract routing.
+- Status reporting can show the stage, considered skills, active skills, and activation reasons.
+
+## Current Examples
+
+- `codebase-scanning` as a stage-method skill for `understand`
+- `typescript-backend` as a domain skill activated when the repo language includes TypeScript
+- `test-hardening` as a quality-policy skill for `refactor` and `validate`

package/docs/versioning-and-upgrade-strategy.md

@@ -0,0 +1,40 @@
+# Versioning And Upgrade Strategy
+
+## Goal
+Define how Prodify versions canonical preset content and upgrades repositories over time.
+
+## Version Storage
+- Store Prodify metadata in `.prodify/version.json`.
+- Minimum fields:
+  - `schema_version`
+  - `preset_name`
+  - `preset_version`
+
+## Upgrade Model
+- Upgrades operate on canonical `.prodify/` content first.
+- Generated compatibility files are regenerated after canonical upgrades are complete.
+- Upgrade logic must know the current preset version before attempting changes.
+
+## Compatibility Checks
+Before an upgrade, Prodify should verify:
+- current `.prodify/version.json` is readable
+- current preset version is known
+- schema version is supported
+- local canonical structure still matches expected upgrade preconditions
+
+## Migration Surfacing
+- If an upgrade needs a structural migration, Prodify must report it explicitly.
+- The tool should tell the user:
+  - current version
+  - target version
+  - files to be changed
+  - whether manual review is required
+
+## Generated File Behavior During Upgrade
+- Generated compatibility files should not be hand-patched during upgrade.
+- After canonical upgrade succeeds, `prodify sync` should regenerate managed targets deterministically.
+
+## Safety Rules
+- Do not rely on guesswork when a version is unknown.
+- Stop if the repository has unsupported schema or missing required version metadata.
+- Prefer explicit migration steps over implicit silent rewrites.

package/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "@urielsh/prodify",
+  "version": "0.1.0",
+  "license": "Apache-2.0",
+  "private": false,
+  "type": "module",
+  "bin": {
+    "prodify": "./dist/index.js"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "prodify": "npm run build && node ./dist/index.js",
+    "test": "npm run build && node --test tests/unit/*.test.js tests/integration/*.test.js",
+    "test:unit": "npm run build && node --test tests/unit/*.test.js",
+    "test:integration": "npm run build && node --test tests/integration/*.test.js"
+  },
+  "devDependencies": {
+    "@types/node": "^22.15.30",
+    "ts-node": "^10.9.2",
+    "typescript": "^5.8.3"
+  }
+}

package/src/README.md

@@ -0,0 +1,11 @@
+# Source Layout
+
+The `src/` tree is organized by subsystem ownership.
+
+- `commands/`: thin CLI orchestration entrypoints only
+- `contracts/`: source parsing, schema ownership, compilation, and freshness
+- `core/`: runtime state, workspace health, status/doctor/update orchestration, and stage validation
+- `presets/`: canonical preset loading and version metadata
+- `scoring/`: local repository scoring after validated execution
+
+If a behavior changes the product model, its owning subsystem should be obvious from this layout before you read implementation details.

package/src/cli.ts

@@ -0,0 +1,61 @@
+import { runDoctorCommand } from './commands/doctor.js';
+import { runInitCommand } from './commands/init.js';
+import { runSetupAgentCommand } from './commands/setup-agent.js';
+import { runStatusCommand } from './commands/status.js';
+import { runUpdateCommand } from './commands/update.js';
+import { ProdifyError, toErrorMessage } from './core/errors.js';
+import type { CommandContext, CommandHandler } from './types.js';
+
+export const COMMANDS: Record<string, CommandHandler> = {
+  init: runInitCommand,
+  'setup-agent': runSetupAgentCommand,
+  status: runStatusCommand,
+  doctor: runDoctorCommand,
+  update: runUpdateCommand
+};
+
+export const PUBLIC_COMMANDS = ['init', 'setup-agent', 'status', 'doctor', 'update'] as const;
+
+export function renderHelp(): string {
+  return [
+    'Prodify CLI',
+    '',
+    'Usage:',
+    '  prodify setup-agent <codex|claude|copilot|opencode>',
+    '  prodify init',
+    '  prodify status',
+    '  prodify doctor',
+    '  prodify update',
+    '',
+    'Global agent setup is separate from per-repository init.',
+    'The primary flow is .prodify-first and contract-driven.'
+  ].join('\n');
+}
+
+export async function runCli(argv: string[], context: Partial<CommandContext> = {}): Promise<number> {
+  const stdout = context.stdout ?? process.stdout;
+  const stderr = context.stderr ?? process.stderr;
+  const cwd = context.cwd ?? process.cwd();
+
+  if (argv.length === 0 || argv.includes('--help') || argv.includes('-h')) {
+    stdout.write(`${renderHelp()}\n`);
+    return 0;
+  }
+
+  const [commandName, ...rest] = argv;
+  const command = COMMANDS[commandName];
+
+  if (!command) {
+    stderr.write(`Unknown command: ${commandName}\n`);
+    stderr.write(`${renderHelp()}\n`);
+    return 1;
+  }
+
+  try {
+    return await command(rest, { cwd, stdout, stderr });
+  } catch (error) {
+    const message = toErrorMessage(error);
+    stderr.write(`${message}\n`);
+    return error instanceof ProdifyError ? error.exitCode : 1;
+  }
+}

package/src/commands/doctor.ts

@@ -0,0 +1,20 @@
+import { resolveRepoRoot } from '../core/repo-root.js';
+import { runDoctor } from '../core/doctor.js';
+import type { CommandContext } from '../types.js';
+
+export async function runDoctorCommand(args: string[], context: CommandContext): Promise<number> {
+  void args;
+  const repoRoot = await resolveRepoRoot({
+    cwd: context.cwd,
+    allowBootstrap: true
+  });
+  const result = await runDoctor(repoRoot);
+
+  context.stdout.write('Prodify Doctor\n');
+  for (const check of result.checks) {
+    const status = check.skipped ? 'SKIP' : check.ok ? 'PASS' : 'FAIL';
+    context.stdout.write(`${check.label}: ${status}${check.details ? ` - ${check.details}` : ''}\n`);
+  }
+
+  return result.ok ? 0 : 1;
+}

package/src/commands/init.ts

@@ -0,0 +1,37 @@
+import { writeFileEnsuringDir } from '../core/fs.js';
+import { resolveRepoRoot } from '../core/repo-root.js';
+import { resolveRepoPath } from '../core/paths.js';
+import { pathExists } from '../core/fs.js';
+import { ProdifyError } from '../core/errors.js';
+import { loadDefaultPreset } from '../presets/loader.js';
+import { synchronizeRuntimeContracts } from '../contracts/compiler.js';
+import type { CommandContext } from '../types.js';
+
+export async function runInitCommand(args: string[], context: CommandContext): Promise<number> {
+  void args;
+  const repoRoot = await resolveRepoRoot({
+    cwd: context.cwd,
+    allowBootstrap: true
+  });
+  const prodifyDir = resolveRepoPath(repoRoot, '.prodify');
+
+  if (await pathExists(prodifyDir)) {
+    throw new ProdifyError('.prodify/ already exists. init stops rather than merging existing canonical files.', {
+      code: 'PRODIFY_ALREADY_EXISTS'
+    });
+  }
+
+  const preset = await loadDefaultPreset();
+
+  for (const entry of preset.entries) {
+    await writeFileEnsuringDir(resolveRepoPath(repoRoot, entry.relativePath), entry.content);
+  }
+
+  await synchronizeRuntimeContracts(repoRoot);
+
+  context.stdout.write(`Initialized Prodify in ${repoRoot}\n`);
+  context.stdout.write('Global agent setup is separate: run `prodify setup-agent <agent>` once per machine before using `$prodify-*` commands inside that agent\n');
+  context.stdout.write('Manual bootstrap starts by telling your agent to read .prodify/AGENTS.md\n');
+  context.stdout.write('Compiled runtime contracts were generated under .prodify/contracts/\n');
+  return 0;
+}