project-forge

name	project-forge
description	Bootstrap an original game or software project from a concept by producing a product contract, architecture, ownership plan, quality gates, evidence plan, and repository scaffold. Use when starting a new project, turning an idea into an executable build plan, adapting a proven production method to a new product, or recovering a project that lacks explicit contracts and acceptance evidence.
license	MIT
compatibility	Requires Git and Node.js 18+ for bundled scripts. Visual verification benefits from browser and screenshot automation.
metadata	{"author":"moinsen-dev","version":"0.1.0"}

Project Forge

Turn an incomplete concept into a coherent, testable project without coupling the workflow to a particular model, agent product, or delegation API.

Do not treat a generated scaffold, a large implementation, elapsed effort, or subjective confidence as proof that a product works.

Read First

Load only the references needed for the current phase:

• Product and file contracts: references/project-contract.md
• Role scheduling and capability fallbacks: references/orchestration.md
• Required proof and acceptance states: references/quality-gates.md
• Three.js game-specific guidance: references/threejs-game.md

Workflow

1. Inspect Before Creating

Inspect the current directory, Git state, existing instructions, package files, tests, tools, and generated artifacts.

• Never overwrite a non-empty target directory.
• Preserve user changes and existing ownership boundaries.
• Prefer the repository's established stack when adapting an existing project.
• Record conflicts between user intent and repository contracts before coding.

2. Run Product Discovery

Convert the concept into explicit decisions:

• player or user and their primary job,
• product fantasy or value proposition,
• core loop or primary workflow,
• innovation hypothesis,
• non-negotiable rules,
• deliberately excluded scope,
• first complete vertical slice,
• named success, failure, and edge states,
• legal, privacy, safety, and originality boundaries,
• measurable completion evidence.

Infer conservative defaults when information is incomplete and label them as assumptions. Ask only when a missing decision would make implementation unsafe, irreversible, or materially incoherent.

For an innovative game, keep the initial phase as discovery. Prove the core verb and feedback loop before freezing a production architecture around it.

3. Freeze the First Contract

Use references/project-contract.md to define the canonical outputs. For the first supported template, scaffold with:

node scripts/init.mjs \
  --template threejs-game \
  --name "<project name>" \
  --concept-file "<brief path>" \
  --output "<target directory>"

Resolve scripts/init.mjs relative to this skill directory. The command creates a safe initial contract but does not replace product-specific reasoning.

Replace generic defaults with concrete project rules. Keep:

• prompt.md responsible for product scope and quality target,
• ARCHITECTURE.md responsible for technical contracts and boundaries,
• AGENTS.md responsible for ownership, review, and handoff,
• ASSIGNMENTS.md responsible for current work allocation,
• QUALITY_GATES.md responsible for observable acceptance,
• project.yaml and forge-state.json machine-readable.

4. Plan the First Vertical Slice

Define the smallest integrated path that proves the product's central claim. It must exercise real runtime behavior, not an isolated mock or disconnected showcase.

Every slice needs:

• stable identifier,
• one owner,
• exact owned paths,
• accepted dependencies,
• observable acceptance conditions,
• required evidence,
• an independent critic,
• a verifier when the claim is consequential,
• one current status.

Do not fan out coupled state, shared schemas, or files with overlapping ownership.

5. Match Work to Available Capabilities

Follow references/orchestration.md.

• If independent worker contexts are available, execute disjoint slices in parallel.
• Otherwise, execute implementer roles sequentially.
• Run critique in a context that did not author the reviewed implementation.
• If isolated contexts are unavailable, perform a deliberate fresh review pass after clearing implementation assumptions and state that independence is limited.
• If required tools are unavailable, keep the affected gate unverified.

Capability absence changes scheduling and evidence status. It never lowers the acceptance threshold.

6. Implement Through Evidence Loops

For each slice:

1. Contract ownership, acceptance, and evidence.
2. Implement the smallest complete integrated behavior.
3. Run focused deterministic checks.
4. Exercise the real user input or request path.
5. Capture named evidence with build and environment metadata.
6. Obtain independent adversarial criticism.
7. Fix the highest-impact root cause.
8. Repeat until the critic returns PASS or a genuine blocker is recorded.
9. Independently verify the evidence.
10. Integrate and rerun affected cross-system gates.

Use project-forge-review for the independent review phase when it is installed.

7. Validate the Contract

Run:

node scripts/validate.mjs --project "<target directory>" --strict
node scripts/status.mjs --project "<target directory>"

The validator checks structure, machine-readable state, unresolved template tokens, agent-specific control phrases, and required contract sections. It does not prove runtime quality.

8. Report Honestly

The final report must distinguish:

• implemented,
• statically checked,
• runtime tested,
• visually reviewed,
• performance measured,
• independently verified,
• unverified,
• blocked.

List exact commands, evidence paths, observed results, remaining defects, and the next gate. Never convert missing evidence into a pass.

Hard Rules

• Keep core instructions agent- and model-neutral.
• Do not use product-specific slash commands as workflow semantics.
• Do not assume sub-agent, hook, browser, or tool availability.
• Do not let an implementer approve its own user-facing quality.
• Do not accept parallel edits to overlapping files.
• Do not derive acceptance from code inspection alone.
• Do not lower a gate because repeated attempts failed.
• Do not use comparisons as permission to copy names, art, levels, UI, audio, characters, code, or trade dress.
• Do not claim premium quality from a single favorable screenshot.
• Do not start broad production before the central interaction is coherent.