file-proposal-viewer

Dependency-free CLI for agentic engineering workflows. It lets an LLM propose files before implementation using a durable JSON manifest, then renders that manifest into a self-contained interactive HTML viewer for human review.

The manifest is the source of truth. The viewer is generated output.

Workflow

1. User asks an agent to implement a feature.
2. Agent creates a proposal manifest before writing code.
3. Agent lists proposed files, purposes, dependencies, and flows.
4. Agent renders the manifest into an HTML viewer.
5. Human reviews the proposed structure.
6. Human approves or requests changes.
7. Agent implements only after approval.

Commands

file-proposal-viewer init
file-proposal-viewer validate proposal.manifest.json
file-proposal-viewer render proposal.manifest.json
file-proposal-viewer render proposal.manifest.json --out proposal.viewer.html

One-off use after publishing:

npx file-proposal-viewer@latest init
npx file-proposal-viewer@latest render proposal.manifest.json

Skill Installation

Install the bundled skill with the skills installer:

npx skills@latest add file-proposal-viewer

The package includes .claude-plugin/plugin.json and skills/engineering/file-proposal-viewer/SKILL.md so compatible skill installers can discover the skill entrypoint.

The installed skill uses one-off CLI commands so users do not need a global install:

npx -y file-proposal-viewer@latest init
npx -y file-proposal-viewer@latest validate proposal.manifest.json
npx -y file-proposal-viewer@latest render proposal.manifest.json --out proposal.viewer.html

Local Usage

From this package directory:

node bin/file-proposal-viewer.mjs validate examples/basic.manifest.json
node bin/file-proposal-viewer.mjs render examples/basic.manifest.json

Viewer Features

• File tree grouped by repo-relative file paths.
• Folder-level expand/collapse.
• Adjustable file tree sidebar width.
• Keyboard sidebar resize with ArrowLeft and ArrowRight.
• Status badges for new, modified, and deleted files.
• Dependency graph from manifest dependencies.
• Flow selector.
• Flow highlighting for touched files and dependency edges.
• Details panel for selected files and flows.
• File filtering by path, purpose, or change summary.
• Self-contained HTML output.
• No runtime dependencies.

Validation

The validator checks:

• Required top-level strings and arrays exist.
• File IDs are unique.
• Dependency IDs are unique.
• Dependencies reference existing file IDs.
• Flows reference existing file and dependency IDs.
• Flow steps reference existing file and dependency IDs.

The validator does not check:

• Whether paths exist.
• Whether paths match architecture rules.
• Whether frontend/backend contracts agree.
• Whether purposes are accurate.
• Whether dependencies are complete.
• Whether implementation code exists.

Manifest Contract

See types/proposal-manifest.d.ts for TypeScript types and schema/proposal-manifest.schema.json for JSON Schema.

export type FileProposalManifest = {
  id: string;
  title: string;
  summary: string;
  scope: ProposalScope;
  files: ProposedFile[];
  dependencies: FileDependency[];
  userFlows: UserFlow[];
  validation: ProposalValidation;
};

export type ProposalScope = {
  featureName: string;
  goal: string;
  assumptions: string[];
  nonGoals: string[];
};

export type UserFlowStep = {
  order: number;
  description: string;
  fileIds: string[];
  dependencyIds?: string[];
};

export type ProposalValidation = {
  status: "not-validated" | "valid" | "warning" | "invalid";
  checks: ValidationCheck[];
};

Agent Instructions

Use agents/file-proposal-instructions.md when asking an agent to prepare a proposal before implementation.

For skill installers, use skills/engineering/file-proposal-viewer/SKILL.md as the canonical skill entrypoint.