Solid, opinionated procedural-generation foundation with evidence-driven detail analysis and cost-reduction architecture. Token economics are explicit (docs/TOKEN_COST.md); cost drivers are identified (review cycles).
Convergent signal across 5 personas (CTO, CPO, VPE, CISO, Scrum Master) on the same 5 high-ROI hardening steps: wire validation gates, run schema checks as subprocess (not LLM tokens), embed policy metadata for deterministic review, enforce quality contracts upfront, require detail-inventory completion before spec. These are low-to-medium adoption cost and pay back in first 50 objects via 20, 40% per-object token savings + eliminated rework cycles.
Character likeness and destruction rigging are planned; shipping them requires minimal additional gating (metadata schemas already sketched). Recommend: Beta → Production-ready once gates are wired and CI/CD covers all 4 review stages.
ReadyBase score: Fair, AI for well-tested areas only. Deterministic, no LLM.
How ReadyBase scores this →Convergent across 5 personas (CTO, CPO, VPE, CISO, Scrum Master). Evidence: 20, 40% per-object token savings, reduces LLM inference attack surface, scripts already exist (validate_sculpt_spec.py). Adoption: low, wire into orchestrate_passes.py, make subprocess default path for schema/syntax/completeness checks. Payback: first 50 objects. Generality: transferable (any multi-stage pipeline with structural gates).
Convergent across 4 personas (CTO, CPO, VPE, Scrum Master). Evidence: prevents wasted render cycles on malformed geometry (10x token waste at scale); validate_sculpt_spec.py exists. Adoption: low, one-line gate in orchestrate_passes.py (call validate, skip factory if invalid). Payback: immediate. Generality: transferable.
Convergent across 5 personas (CTO, CPO, VPE, CISO, Scrum Master). Evidence: feature_acceptance_policy.py exists; eliminates subjective review variance; CISO flags prose scoring as prompt-injection risk. Adoption: medium, refactor append_review.py to call policy.check() instead of agent scoring; update self_correction.md. Payback: scales review cost sublinearly. Generality: transferable.
Convergent across 5 personas (CTO, CPO, VPE, CISO, Scrum Master). Evidence: quality_contract.md and new_pre_spec_assessment.py exist; shifts cost from open-ended (80, 180k tokens) to gates (1, 2 review cycles). Adoption: medium, codify contract as executable JSON schema; gate stage2→stage3 on contract completion; validate spec against thresholds. Payback: 60% cycle reduction. Generality: transferable.
Convergent across 5 personas (CTO, CPO, VPE, CISO, Scrum Master). Evidence: build_detail_inventory.py generates zone-based stubs; prevents detail loss and shallow specs; CISO emphasizes input-validation closure. Adoption: medium, gate stage2 entry on completion; validate all zones have classification + component link; enforce in orchestrate_passes.py. Payback: eliminates expensive correction loops. Generality: transferable.
Flagged by CPO and Scrum Master (2 personas). Evidence: build_detail_inventory.py already implemented; ensures systematic coverage without human zone spec. Adoption: low, already exists, document as required intake stage in SKILL.md; enforce in pipeline. Generality: transferable (any single-image analysis task). Note: de-prioritized vs. top 5 because already shipped; high polish value but lower activation energy.
Flagged by VPE and implied by CPO (visual acceptance). Evidence: make_comparison_sheet.py exists but not integrated into review loop (append_review.py). Adoption: low, call make_comparison_sheet.py in append_review.py for each entry; store guttered images in review artifact. Payback: reduces reviewer error, speeds sign-off. Generality: transferable (any visual diff task).
Flagged by CPO (1 persona). Evidence: enables precise routing to right pipeline (character vs. hard-surface); prevents misrouting. Adoption: medium, requires taxonomy training. Payback: medium (routing only; not per-object cost). Generality: transferable (any multi-domain classification). De-prioritized vs. cost-reduction ideas but complements policy metadata (axes inform feature tier routing).
Flagged by CISO and implied by Scrum Master (2 personas). Evidence: CISO emphasizes prevention of social-engineering acceptance of degraded output. Adoption: low, expand quality_contract.md with failure-mode matrix; validate upfront. Payback: prevents silent acceptance. Generality: transferable (any gated acceptance system).
Flagged by CTO and CISO (2 personas). Evidence: zero cost now, unlocks physics at scale (CTO); audit trail prevents unvetted physics injection (CISO). Adoption: low, extend ObjectSculptSpec schema; validate structure in validate_sculpt_spec.py. Payback: future-proofing (Epic 3). Generality: domain-specific (destruction/animation).
img2threejs reconstructs 3D objects and humanoid characters from single reference images as procedural Three.js models. It stages the workflow through image intake (zoned detail inventory), spec authoring (quality contracts defining pass/fail thresholds), code generation (TypeScript factory), and visual review with self-correction loops. Output is animation-ready geometry with hierarchical rigging, parametric materials (PBR channels), and metadata for destruction/physics binding.
Detail-first, evidence-linked pipeline that catches small identity-defining marks (buttons, scratches, labels) via deterministic zoning before code generation. Combined with upfront quality contracts (pass/fail thresholds per complexity tier) and deterministic validation gates (no tokens wasted on malformed specs), this prevents the cost bleed that plagues iterative reconstruction. Procedural Three.js factory output (not baked meshes) enables inspection and adaptation, core transparency promise that alternatives lack.
Docs claim production-ready procedural pipeline; code lacks enforced quality gates, deterministic policy validation, and CI/CD coverage that claims presuppose.
Prevents wasted render cycles on malformed geometry; direct token cost reduction at 10x scale when queuing hundreds of specs.
Cost Deterministic validation scripts already exist (test_pipeline.py); wire into orchestrate_passes.py gating logic.
Decouples vision passes from structural truth; ~80% cost savings on pre-render validation as dataset scales.
Cost Already partially implemented; systematize entry points and make subprocess harness the default path for all schema checks.
Replaces subjective review rounds with deterministic policy evaluation; scales review cost sublinearly with model count.
Cost Policy structure exists in feature_acceptance_policy.py; integrate into orchestrate_passes and append_review as the sole arbiter.
Eliminates vague spec-drift; reduces review cycle count from 3, 5 to 1, 2 per object at scale.
Cost quality_contract.md and new_sculpt_spec.py already encode this; enforce as a required gate before passing to stage3_build.
Forces completeness upfront; catches missed geometry before render, avoiding expensive correction loops.
Cost build_detail_inventory.py and detail_inventory.md exist; make the JSON skeleton a blocker for spec authoring in orchestrate_passes.
Future-proofs the spec format; zero cost now, unlocks physics/destruction features at 5, 10x team scale without re-sculpting.
Cost Extend ObjectSculptSpec schema with optional collider metadata fields; update validate_sculpt_spec.py to accept but not require them.
De-couples material truth from lighting artifacts; enables reuse of materials across projects and faster iteration.
Cost Requires separate neutral-light render pass in generate_threejs_factory.py and render_capture.md review checklist addition.
Eliminates wasted render cycles on underspecified models; cuts token cost by enforcing upfront validation gates instead of iterative refinement
Cost Requires stakeholder buy-in on stricter intake gates; may slow initial user experience but dramatically improves per-object economics
Makes review repeatability and cost predictability explicit; enables cross-project policy inheritance and reduces reviewer variance
Cost Initial policy authoring effort; requires taxonomy agreement across teams before deployment
Shifts cost curve from open-ended review loops (80, 180k tokens per object) to deterministic pass/fail gates; aligns user expectations before work begins
Cost Demands upfront spec discipline; users must commit detail and failure-mode clarity before modeling starts
Enables precise routing to the right pipeline (character vs. hard-surface, stylized vs. photorealistic); prevents misrouting that wastes cycles on wrong reconstruction strategy
Cost Requires training users and internal reviewers on the axis taxonomy; moderate onboarding lift
Cuts per-object token spend by 10, 20% by offloading format validation, collision detection, and rig coherence to cheap subprocess checks
Cost Moderate engineering lift to instrument validation pipelines; pays back in first 50 objects
Prevents detail loss in single-image reconstruction; ensures prosaic objects (buttons, scratches, labels) are captured as evidence-linked artifacts, not guessed
Cost Adds upfront inventory work; improves downstream fidelity without significant token overhead if zoning is deterministic
Pipeline orchestrates 8 stages; shifting structural validation (complexity scoring, spec syntax, completeness gates) to Python validators reduces Claude API call frequency and token waste on repetitive checks.
Cost Add 3-4 validator scripts in forge/stage2_spec/ and stage4_review/, integrate into orchestrate_passes.py; retrofit existing review loops to fail-fast on validation before invoking Claude.
Catalog suggests validate-spec-before-build; repo already has validate_sculpt_spec.py but it's not wired as a blocking gate in generate_threejs_factory.py. Prevents expensive Three.js factory builds from failing due to incomplete specs.
Cost One-line gate in orchestrate_passes.py (call validate, skip factory if spec invalid); update SKILL.md to document gate.
Feature acceptance policy already exists (forge/_shared/feature_acceptance_policy.py), but review scripts (append_review.py, self_correction.md) still rely on agent judgment for pass/fail. Encoding policy as executable rules reduces subjectivity and drift across review cycles.
Cost Refactor append_review.py to call feature_acceptance_policy.check() instead of agent scoring; update grimoire/review/self_correction.md to reference policy logic.
build_detail_inventory.py generates zone-based stubs; these stubs feed into agent detail classification but there's no strict requirement that all zones have linked evidence before spec generation. Enforcing this gate prevents vague specs that fail at render time.
Cost Add validation in new_sculpt_spec.py: check that all detail_inventory zones have classification + component link before accepting spec; gate orchestrate_passes.py stage2->stage3 transition.
make_comparison_sheet.py exists but is not integrated into the review loop; it's not called by append_review.py or referenced in self_correction.md. Wiring it in reduces reviewer error and speeds sign-off.
Cost Call make_comparison_sheet.py in append_review.py for each review entry; update render_capture.md with screenshot requirements and store guttered images in review artifact.
Quality contract structure exists in quality_contract.md and new_pre_spec_assessment.py, but contract is generated as prose metadata, not enforced as executable criteria. Encoding pass/fail rules upfront reduces rework cycles.
Cost Refactor quality_contract payload to include executable thresholds (silhouette_fidelity_min, component_count_max); update self_correction.md to compare rendered output against contract thresholds.
Offloading validation to subprocess prevents LLM inference tokens on structural integrity checks, reducing token-cost attack surface and enabling cost predictability for security gates.
Cost Minimal; scripts already exist (validate_sculpt_spec.py); integrate as pre-render subprocess barrier.
Hardcoded policy dictionaries (feature_acceptance_policy.py) replace subjective LLM judgment, eliminating prompt-injection risk and enabling auditability of what passes quality gates.
Cost Low; policy already exists; refactor gate enforcement to reject specs failing policy in-process before agent submission.
Mandating structured, zoned detail capture (build_detail_inventory.py) with per-zone evidence links closes input-validation gap; prevents vague briefs from driving code generation and reduces prompt-complexity that could mask injection.
Cost Medium; must gate stage2_spec entry on evidence artifact completion and validate inventory structure schema before accept.
Pre-agreed quality contracts (quality_contract.md) eliminate undefined acceptance criteria that could be manipulated mid-loop; explicit failure modes prevent scope creep and token-cost spikes.
Cost Medium; codify contract as mandatory JSON schema; validate spec against contract before passing to build stage.
Metadata-first approach (action_rigging.md) creates audit trail of destruction/rigging intent without runtime coupling; separates concerns so unvetted physics libraries cannot be injected into trusted mesh specs post-generation.
Cost Low; add collider intent schema to ObjectSculptSpec; validate metadata structure in validate_sculpt_spec.py.
Explicit failure-mode documentation prevents silent acceptance of degraded output; reviewers cannot be socially engineered into accepting unvetted renders if criteria are pre-committed.
Cost Low; expand quality_contract.md with failure-mode matrix; add validation rule to reject specs missing failure docs.
Prevents expensive rendering of incomplete/malformed geometry; quality gate system already exists (validate_sculpt_spec.py) and could be extended to block generation.
Cost Low, extend existing validator functions in stage2_spec/ to enforce pre-generation checks.
Replaces subjective visual review thresholds with deterministic acceptance rules; feature_acceptance_policy.py already implements this pattern.
Cost Medium, refactor pass-completion logic in stage4_review/ to consume policy metadata from spec; document all feature tiers (critical, important, detail).
Reduces review cycles by aligning expectations before generation; quality_contract already defined in stage2_spec but not enforced as hard gate.
Cost Medium, formalize contract as required artifact in new_pre_spec_assessment.py and gate subsequent stages on contract completion.
Current system runs all checks via Claude; splitting PNG/JSON validation into pure-Python subprocess saves 20-40 percent of token budget per spec cycle.
Cost Low, migrate structural validations from stage4_review agents to subprocess calls in validate_sculpt_spec.py; document expected format contracts.
Prevents vague detail descriptions; detail_inventory skeleton already generated in stage1_intake but not enforced as gate before stage2 spec authoring.
Cost Medium, add detail inventory completion check to new_sculpt_spec.py entry point; link each spec detail to inventory zone ID.
build_detail_inventory.py already does this; ensures systematic coverage without requiring human zone specification.
Cost Low, already implemented; document as required intake stage in SKILL.md and enforce in pipeline orchestration.
8-stage pipeline (intake → spec → build → review) is coherent and opinionated. Staged sculpting with gating model is sound. Separation of concerns (image processing, spec authoring, code generation, visual review) is clean. Evidence: validate_sculpt_spec.py exists; feature_acceptance_policy.py is structured metadata; detail_inventory zoning is deterministic. However, gates are documented (grimoire/) but not wired as blocking logic in orchestrate_passes.py (VPE finding: 'not wired as blocking gate'). Validation scripts exist but are not subprocess-default (CTO/CPO finding: 'systematize entry points'). Architecture will age well if gates are hardened; currently it is aspirational, the skeleton is there but enforcement is loose.
Stages 1, 2 (intake, spec) are feature-complete with working Python scripts (image probing, detail inventory, spec skeleton generation). Stage 3 (code generation) produces valid TypeScript. Stage 4 (review) has comparison-sheet scaffolding and self-correction structure. However, production gaps are material: validation gates documented in quality_contract.md and new_pre_spec_assessment.py exist as data structures, not enforced as hard gates in code (VPE: 'contract is generated as prose metadata, not enforced as executable criteria'). Feature-acceptance policy (feature_acceptance_policy.py) is stubbed but append_review.py still uses agent judgment instead of calling policy.check() (VPE: 'append_review.py still rely on agent judgment'). No production CI/CD (test_pipeline.py covers intake+spec but not render/review loops; no integration tests for full 4-stage pipeline). Documentation-vs-code gap: grimoire/ reference docs for destruction rigging and neutral-light PBR validation are written but not implemented in code. ReadyBase: no CI detected (0/10); test coverage 6% (3/17). Adoption gap is low (gates ~1, 2 days wiring) but material.
No identified injection vectors in current design: Python subprocess model (validate_sculpt_spec.py, build_detail_inventory.py) keeps structural validation out of LLM inference. Structured quality contracts (feature_acceptance_policy.py) replace prose scoring, closing prompt-injection risk in review (CISO finding: 'hardcoded policy dictionaries replace subjective LLM judgment'). Input validation exists: probe_image.py detects image format/size; validate_sculpt_spec.py checks schema. However, three material gaps: (1) Detail-inventory completeness gate is not enforced, shallow zone coverage could pass spec authoring (CISO: 'evidence-linked capture closes input-validation gap' but 'not a strict requirement'). (2) No documented secret/credential handling for Claude API integration (SKILL.md and orchestrate_passes.py imply agent calls but no env-var or auth-token isolation pattern documented). (3) No supply-chain lockdown: requirements.txt is pure stdlib (15/15 on ReadyBase dependencies), but Python version (3.10+) is not pinned in setup or CI; no lockfile or hash-pinning for reproducible subprocess calls. CISO findings emphasize preventive policy embedding and metadata-first approach (already present); missing are enforcement gates and CI/CD validation (no signed commits, no scan log).
Core IP is highly transferable: (1) Modular image-processing functions (read_png, write_png_rgb, composite_over_white in build_detail_inventory.py and extract_landmarks.py) can be reused in other vision-to-code pipelines. (2) Staged validation model (intake → spec → build → review) is pattern-transferable to any multi-stage procedural generation (e.g., animation rigging, level design from sketches). (3) Feature-acceptance policy (feature_acceptance_policy.py) is domain-agnostic hierarchical policy logic; trivial to adapt to other quality-gate tasks. (4) Zoned detail inventory (build_detail_inventory.py) generalizes to any single-image analysis requiring systematic coverage. (5) Comparison-sheet composition (make_comparison_sheet.py) is reusable for any visual diff task. Evidence: py files are well-factored with reusable utility functions (clamp, srgb_luma, struct-based PNG read/write). However, three reusability gaps: (1) No public API or packaging (no setup.py, no PyPI, no importable module structure). (2) Domain-specific hardcoding in grimoire/ (character templates, human-proportion locks) limits adaptation to non-humanoid domains without rework. (3) Three.js output is specific to JavaScript ecosystem; no porting to GLTF, USD, or other interchange formats documented. ReadyBase: 0 packages (1/5 on structure). Reusability is high in code but blocked by lack of distribution and abstraction.
README.md (0 days old per ReadyBase summary) claims 'quality-gated, animation-ready pipeline' and 'staged sculpting pipeline' with 'self-correction and improvement'. SKILL.md describes gate-based approach with validation stages. ROADMAP.md outlines planned evolution (v1.3.0 destruction rigging, PBR realism, animation rig binding). However, documentation-vs-code gap is material: (1) Quality contracts are described in quality_contract.md and encoded in new_pre_spec_assessment.py, but are not enforced as blocking gates in orchestrate_passes.py or append_review.py (VPE: 'contract is generated as prose metadata, not enforced as executable criteria'). (2) Detail-inventory completeness is documented as required (detail_inventory.md) but not gated in new_sculpt_spec.py (Scrum Master: 'not enforced as gate before stage2 spec authoring'). (3) Feature-acceptance policy is described (feature_acceptance_policy.py) but append_review.py still uses agent judgment (VPE: 'still rely on agent judgment for pass/fail'). (4) Destruction rigging and PBR channels are documented in grimoire/ but not implemented in code (Assessment: 'planned but not shipped'). (5) No runnable examples or end-to-end walk-through in README; TOKEN_COST.md estimates are 'engineering models rather than empirical data' (docs/TOKEN_COST.md summary). (6) CONTRIBUTING.md emphasizes 'no pip dependencies' and 'pure Python 3.10+ standard library' but does not document how to extend for new domains (e.g., vehicle rigging, architectural meshes). Docs are honest about what is planned (ROADMAP) but overstate what is enforced (quality gates) and lack guidance for extension. ReadyBase: Documentation 12/15 (README recent but thin on detail).
test_pipeline.py exists and covers end-to-end stages: image processing (probe), assessment, spec generation, review (Assessment notes 'tests cover various stages'). Test design is sound: uses temp directories, struct-based PNG generation (avoiding PIL dependency), subprocess-based CLI testing. However, coverage is limited: (1) Only intake (stage 1) and spec (stage 2) are tested; render (stage 3) and review (stage 4) loops are not covered (Assessment: 'test_pipeline.py covers intake+spec but not render/review loops'). (2) No integration tests for full 4-stage pipeline or error-path recovery (e.g., how orchestrate_passes handles validation failure → correction → retry). (3) No property-based tests for image format robustness (only struct-based synthetic PNGs, no real-world reference images). (4) Feature-acceptance policy (feature_acceptance_policy.py) and comparison-sheet composition (make_comparison_sheet.py) have no test coverage. (5) No CI/CD (ReadyBase: CI 0/10). (6) test_pipeline.py is not documented in SKILL.md or CONTRIBUTING.md as required pre-commit or validation step. Quality signals: scripts follow stdlib-only discipline (good signal); error handling in probe_image.py and extract_landmarks.py is defensive (PNG signature checks, format detection fallbacks); validate_sculpt_spec.py is systematic (type checking, range validation). However, ReadyBase: test coverage 6% (3/17); test quality 0 (no tests found, likely due to small test count not real coverage). No mutation testing, no fuzz testing on image inputs, no chaos engineering on pipeline stages.
Swap 'structural checks' for 'inventory checks': run existing scripts (validate_sculpt_spec.py, build_detail_inventory.py) to observe actual behavior rather than inferring it from docs, zero token waste on things scripts can answer directly.
No code generation or rendering in this use case; gate pattern doesn't apply to read-only architectural analysis.
Directly transferable: record each extracted pattern as structured metadata (name, location, generality, reuse_mode, evidence_path) not prose notes, so patterns are machine-queryable and comparable.
Directly transferable: define upfront what 'extracted pattern' means (must have file evidence, reuse_mode, one concrete example) before starting the walk-through, preventing open-ended exploration loops.
Core pattern for this use case: zone the repo by subsystem (intake, build, review, orchestration, grimoire docs), generate one stub per zone, then fill with evidence (file + line) before declaring any pattern extracted.
Replace 'image' with 'repo directory tree': same systematic zone-then-stub method prevents missing small but identity-defining patterns (e.g., a single-file policy module) during architecture walk.
Visual diffing tool; no render artifacts in a code architecture task.
Replace '8 3D axes' with repo-relevant axes (coupling, abstraction depth, reuse surface, doc coverage, test coverage, domain-specificity, entry-point clarity, pipeline position); gives precise routing of which subsystems to study first.
Transferable as: document before starting what extraction failure looks like (pattern claimed without file evidence, generality asserted without second use-site, reuse_mode wrong), so reviewers can reject shallow extractions on first pass.
Domain-specific to 3D destruction physics; no analog in repo architecture extraction.
Execute in this order. First, write a one-page quality contract defining what a valid extracted pattern requires (file evidence, reuse_mode, at least one concrete call-site or doc location). Second, zone the repo by directory (intake, build, review, orchestration, shared, grimoire) and generate one stub per zone before filling any detail, this prevents skipping small but critical modules. Third, run existing scripts (validate_sculpt_spec.py, build_detail_inventory.py, feature_acceptance_policy.py) as subprocesses to observe actual behavior, not just read docs about it. Fourth, score each subsystem on adapted independent axes (coupling, reuse surface, doc coverage, domain-specificity) to prioritize which patterns are worth extracting versus which are too domain-locked to transfer. Fifth, record all findings as structured metadata per the schema, not prose. Document failure modes (shallow claims, missing evidence) in the contract so any reviewer can reject on first pass without a second cycle. Biggest risk: the grimoire docs describe intent, not implementation, the code in forge/ may diverge silently, so always cross-reference doc claims against actual file behavior before marking a pattern as 'transferable'.