@starlein/paperclip-plugin-company-wizard 0.2.1

package/templates/modules/game-design/docs/engine-threejs.md

@@ -0,0 +1,304 @@
+# Engine Guide: Three.js
+
+Three.js is a 3D rendering library for the web. Use it for: 3D games, first-person/third-person games, voxel worlds, procedural environments, 3D puzzle games, and any game that needs a 3D scene. Runs on WebGL and WebGPU.
+
+Like PixiJS, Three.js is a renderer — you build the game loop, physics, and input yourself (or bring libraries like Rapier, cannon-es, or Ammo.js).
+
+## Project Setup
+
+```bash
+npm init -y && npm install three
+```
+
+For TypeScript: `npm install three @types/three`
+
+## Core Architecture
+
+### Scene, Camera, Renderer
+
+Every Three.js app needs these three things:
+
+```javascript
+import * as THREE from 'three';
+
+// Scene — the container for all 3D objects
+const scene = new THREE.Scene();
+scene.background = new THREE.Color(0x87ceeb);  // sky blue
+scene.fog = new THREE.Fog(0x87ceeb, 50, 200);  // distance fog
+
+// Camera — the viewpoint
+const camera = new THREE.PerspectiveCamera(
+  75,                                    // FOV
+  window.innerWidth / window.innerHeight, // aspect
+  0.1,                                   // near clipping
+  1000                                   // far clipping
+);
+camera.position.set(0, 5, 10);
+camera.lookAt(0, 0, 0);
+
+// Renderer
+const renderer = new THREE.WebGLRenderer({ antialias: true });
+renderer.setSize(window.innerWidth, window.innerHeight);
+renderer.setPixelRatio(window.devicePixelRatio);
+renderer.shadowMap.enabled = true;
+renderer.shadowMap.type = THREE.PCFSoftShadowMap;
+document.body.appendChild(renderer.domElement);
+
+// Animation loop
+const timer = new THREE.Timer();
+timer.connect(document);
+
+renderer.setAnimationLoop(() => {
+  timer.update();
+  const delta = timer.getDelta();
+  update(delta);
+  renderer.render(scene, camera);
+});
+
+// Handle resize
+window.addEventListener('resize', () => {
+  camera.aspect = window.innerWidth / window.innerHeight;
+  camera.updateProjectionMatrix();
+  renderer.setSize(window.innerWidth, window.innerHeight);
+});
+```
+
+### Meshes, Materials, Geometry
+
+```javascript
+// Built-in geometries
+const ground = new THREE.Mesh(
+  new THREE.PlaneGeometry(100, 100),
+  new THREE.MeshStandardMaterial({ color: 0x228b22 })
+);
+ground.rotation.x = -Math.PI / 2;
+ground.receiveShadow = true;
+scene.add(ground);
+
+// Box
+const cube = new THREE.Mesh(
+  new THREE.BoxGeometry(1, 1, 1),
+  new THREE.MeshStandardMaterial({ color: 0xff4444 })
+);
+cube.position.set(0, 0.5, 0);
+cube.castShadow = true;
+scene.add(cube);
+
+// Instanced mesh (for many identical objects — trees, enemies, particles)
+const count = 1000;
+const mesh = new THREE.InstancedMesh(geometry, material, count);
+const dummy = new THREE.Object3D();
+for (let i = 0; i < count; i++) {
+  dummy.position.set(Math.random() * 100 - 50, 0, Math.random() * 100 - 50);
+  dummy.updateMatrix();
+  mesh.setMatrixAt(i, dummy.matrix);
+}
+scene.add(mesh);
+```
+
+### Lighting
+
+```javascript
+// Ambient — baseline illumination
+const ambient = new THREE.AmbientLight(0x404040, 0.5);
+scene.add(ambient);
+
+// Hemisphere — sky/ground gradient
+const hemi = new THREE.HemisphereLight(0x87ceeb, 0x228b22, 0.6);
+scene.add(hemi);
+
+// Directional — sun-like, casts shadows
+const sun = new THREE.DirectionalLight(0xffffff, 1);
+sun.position.set(10, 20, 10);
+sun.castShadow = true;
+sun.shadow.mapSize.width = 2048;
+sun.shadow.mapSize.height = 2048;
+sun.shadow.camera.near = 0.5;
+sun.shadow.camera.far = 50;
+sun.shadow.camera.left = -20;
+sun.shadow.camera.right = 20;
+sun.shadow.camera.top = 20;
+sun.shadow.camera.bottom = -20;
+scene.add(sun);
+
+// Point — omnidirectional (torch, lamp)
+const point = new THREE.PointLight(0xff8800, 1, 20);
+point.position.set(5, 3, 5);
+scene.add(point);
+```
+
+### Loading 3D Models (GLTF)
+
+GLTF/GLB is the standard format for 3D web content.
+
+```javascript
+import { GLTFLoader } from 'three/addons/loaders/GLTFLoader.js';
+
+const loader = new GLTFLoader();
+loader.load('models/character.glb', (gltf) => {
+  const model = gltf.scene;
+  model.traverse((child) => {
+    if (child.isMesh) {
+      child.castShadow = true;
+      child.receiveShadow = true;
+    }
+  });
+  scene.add(model);
+
+  // Animations
+  const mixer = new THREE.AnimationMixer(model);
+  const idleAction = mixer.clipAction(gltf.animations[0]);
+  const walkAction = mixer.clipAction(gltf.animations[1]);
+  idleAction.play();
+
+  // In update loop:
+  // mixer.update(delta);
+
+  // Crossfade between animations
+  // walkAction.reset().fadeIn(0.3).play();
+  // idleAction.fadeOut(0.3);
+});
+```
+
+### Raycasting (Input / Click Detection)
+
+```javascript
+const raycaster = new THREE.Raycaster();
+const pointer = new THREE.Vector2();
+
+window.addEventListener('click', (event) => {
+  pointer.x = (event.clientX / window.innerWidth) * 2 - 1;
+  pointer.y = -(event.clientY / window.innerHeight) * 2 + 1;
+
+  raycaster.setFromCamera(pointer, camera);
+  const intersects = raycaster.intersectObjects(scene.children, true);
+
+  if (intersects.length > 0) {
+    const hit = intersects[0];
+    console.log('Hit:', hit.object.name, 'at', hit.point);
+  }
+});
+```
+
+### Camera Controls
+
+```javascript
+import { OrbitControls } from 'three/addons/controls/OrbitControls.js';
+
+// Orbit camera (debug / strategy games)
+const controls = new OrbitControls(camera, renderer.domElement);
+controls.target.set(0, 1, 0);
+controls.enableDamping = true;
+controls.dampingFactor = 0.05;
+controls.update();  // call in animation loop
+
+// First-person: use PointerLockControls
+import { PointerLockControls } from 'three/addons/controls/PointerLockControls.js';
+const fpControls = new PointerLockControls(camera, renderer.domElement);
+renderer.domElement.addEventListener('click', () => fpControls.lock());
+```
+
+### Third-Person Camera Pattern
+
+```javascript
+function updateCamera(player, camera) {
+  const offset = new THREE.Vector3(0, 5, 10);  // behind and above
+  const targetPos = player.position.clone().add(offset);
+  camera.position.lerp(targetPos, 0.1);  // smooth follow
+  camera.lookAt(player.position);
+}
+```
+
+## Physics Integration
+
+Three.js has no built-in physics. Common choices:
+
+### Rapier (recommended — fast, WASM, Rust-based)
+
+```bash
+npm install @dimforge/rapier3d-compat
+```
+
+```javascript
+import RAPIER from '@dimforge/rapier3d-compat';
+
+await RAPIER.init();
+const world = new RAPIER.World({ x: 0, y: -9.81, z: 0 });
+
+// Ground
+const groundBody = world.createRigidBody(RAPIER.RigidBodyDesc.fixed());
+world.createCollider(
+  RAPIER.ColliderDesc.cuboid(50, 0.1, 50),
+  groundBody
+);
+
+// Dynamic box
+const boxBody = world.createRigidBody(
+  RAPIER.RigidBodyDesc.dynamic().setTranslation(0, 5, 0)
+);
+world.createCollider(RAPIER.ColliderDesc.cuboid(0.5, 0.5, 0.5), boxBody);
+
+// In update loop:
+world.step();
+const pos = boxBody.translation();
+cube.position.set(pos.x, pos.y, pos.z);
+const rot = boxBody.rotation();
+cube.quaternion.set(rot.x, rot.y, rot.z, rot.w);
+```
+
+### Cannon-es (pure JS, simpler API)
+
+```bash
+npm install cannon-es
+```
+
+## Project Structure Convention
+
+```
+src/
+├── scenes/
+│   ├── MenuScene.js
+│   ├── GameScene.js
+│   └── GameOverScene.js
+├── objects/
+│   ├── Player.js          # Mesh + physics body + animation mixer
+│   ├── Enemy.js
+│   └── Terrain.js
+├── systems/
+│   ├── InputManager.js    # Keyboard + pointer state
+│   ├── PhysicsWorld.js    # Rapier/cannon-es wrapper
+│   ├── SceneManager.js    # Scene switching
+│   └── AudioManager.js    # Spatial audio via Web Audio API
+├── config/
+│   └── constants.js       # Tuning parameters
+├── assets/
+│   ├── models/            # .glb files
+│   ├── textures/
+│   └── audio/
+└── main.js                # Renderer, scene, loop setup
+```
+
+## Tuning Parameters Pattern
+
+```javascript
+export const PLAYER = {
+  MOVE_SPEED: 5,
+  SPRINT_MULTIPLIER: 1.8,
+  JUMP_FORCE: 8,
+  MASS: 70,
+  CAMERA_OFFSET: { x: 0, y: 5, z: 10 },
+  CAMERA_LERP: 0.1,
+};
+```
+
+## Performance Notes
+
+- Use `InstancedMesh` for repeated geometry (trees, bullets, particles) — massive perf gain
+- LOD (Level of Detail): `THREE.LOD` swaps geometry based on camera distance
+- Frustum culling is on by default — objects outside camera view skip rendering
+- Texture compression: use KTX2 + Basis Universal for GPU-compressed textures
+- Shadow map resolution: 1024 is fine for most cases, 2048 for hero shadows
+- Object pooling: reuse meshes instead of creating/disposing
+- `renderer.info` shows draw calls, triangles, textures in memory
+- Use `dispose()` on geometries, materials, and textures when removing objects
+- WebGPU renderer (`THREE.WebGPURenderer`) available for modern browsers — same API, better performance

package/templates/modules/game-design/docs/gdd-template.md

@@ -0,0 +1,72 @@
+# Game Design Document
+
+## Concept
+
+**Title:** [Working title]
+**Genre:** [e.g., Platformer, Roguelike, Puzzle, Tower Defense]
+**Platform:** [e.g., Web (HTML5), Desktop, Mobile]
+**Target audience:** [e.g., Casual players, Speedrunners, Strategy fans]
+**Pitch:** [One paragraph: what is this game and why is it fun?]
+
+## Core Mechanic
+
+[The one thing the player does most. Describe the full loop: input → action → feedback → consequence.]
+
+## Game Loop
+
+### Moment-to-moment (5 seconds)
+[What does the player do every few seconds?]
+
+### Session loop (15 minutes)
+[What does a single play session look like? How does it start, flow, and end?]
+
+### Meta loop (multi-session)
+[What brings the player back? Progression, unlocks, story, scores?]
+
+## Mechanics
+
+| Mechanic | Description | Introduced | Interacts with |
+| :------- | :---------- | :--------- | :------------- |
+| | | | |
+
+## Progression
+
+[How does difficulty increase? What gates progress? Skill vs content gates. Unlock schedule.]
+
+## Win / Lose
+
+[How does a session end? How does the overall game end? Fail states and recovery.]
+
+## Controls
+
+| Action | Keyboard | Gamepad | Touch |
+| :----- | :------- | :------ | :---- |
+| | | | |
+
+## Art Direction
+
+**Style:** [e.g., Pixel art 16x16, Low-poly, Hand-drawn]
+**Color language:** [What colors mean in gameplay — player, enemy, pickup, hazard, neutral]
+**References:** [Games or art that capture the target aesthetic]
+
+## Audio Direction
+
+**Music:** [Style, mood, adaptive triggers]
+**SFX:** [Key sounds: player actions, feedback, UI]
+
+## Tuning Parameters
+
+### Player
+| Parameter | Default | Range | Affects |
+| :-------- | :------ | :---- | :------ |
+| | | | |
+
+### Enemies
+| Parameter | Default | Range | Affects |
+| :-------- | :------ | :---- | :------ |
+| | | | |
+
+### Economy
+| Parameter | Default | Range | Affects |
+| :-------- | :------ | :---- | :------ |
+| | | | |

package/templates/modules/game-design/module.meta.json

@@ -0,0 +1,22 @@
+{
+  "name": "game-design",
+  "description": "Creates the game design document defining core mechanics, game loop, and player experience. Foundation for any game project.",
+  "capabilities": [
+    {
+      "skill": "game-design",
+      "owners": [
+        "game-designer",
+        "engineer",
+        "ceo"
+      ],
+      "fallbackSkill": "game-design.fallback"
+    }
+  ],
+  "issues": [
+    {
+      "title": "Create Game Design Document",
+      "assignTo": "capability:game-design",
+      "description": "Define the game's core design: genre, core mechanic, game loop, progression system, win/lose conditions, control scheme, and target audience. Document everything in docs/GDD.md. This is the single source of truth for what the game is."
+    }
+  ]
+}

package/templates/modules/game-design/skills/game-design.md

@@ -0,0 +1,41 @@
+# Skill: Game Design
+
+You own the Game Design Document (GDD) and the ongoing design of the game's mechanics, systems, and player experience.
+
+## Game Design Document
+
+Create and maintain `docs/GDD.md` as the single source of truth. It must cover:
+
+1. **Concept** — One-paragraph pitch. Genre, theme, target platform, target audience.
+2. **Core mechanic** — The one thing the player does most. Define it precisely: input → action → feedback → consequence.
+3. **Game loop** — Three layers:
+   - **Moment-to-moment** — What happens every few seconds (jump, shoot, match, place)
+   - **Session loop** — What a single play session looks like (level, round, run, match)
+   - **Meta loop** — What keeps players coming back (progression, unlocks, story, leaderboards)
+4. **Progression** — How difficulty and complexity increase. What gates progress. What the player earns.
+5. **Win/lose conditions** — How does a session end? How does the overall game end? Is there permadeath, lives, continues?
+6. **Controls** — Input scheme for each platform. Keep it simple — if it needs a tutorial, simplify.
+7. **Art direction** — Visual style (pixel art, low-poly, hand-drawn, etc.), color palette guidance, reference games/art.
+8. **Audio direction** — Music style, SFX approach, adaptive audio (if any).
+9. **Tuning parameters** — List every value that affects balance as a named parameter with default:
+   - Player speed, jump height, health, damage, cooldowns
+   - Enemy stats, spawn rates, AI behavior thresholds
+   - Economy values: costs, rewards, drop rates
+
+## Ongoing Design Work
+
+On each heartbeat when `docs/GDD.md` exists:
+
+1. Review recent playtesting feedback (if `docs/PLAYTEST-RESULTS.md` exists).
+2. Identify mechanics that aren't working — not fun, confusing, or broken.
+3. Propose design changes with clear rationale: what's wrong, what to try, expected impact.
+4. Update tuning parameters based on playtest data.
+5. Create issues for new mechanics, balancing passes, or design experiments.
+
+## Rules
+
+- The GDD is a living document. Update it as the design evolves — don't let it get stale.
+- Every mechanic must pass the "why is this fun?" test. If you can't answer, cut it.
+- Design for the minimum viable game first. What's the smallest version that's fun?
+- Tuning values must be parameterized, never hardcoded. Document them in the GDD with ranges.
+- When in doubt, prototype and playtest. Don't design in a vacuum.

package/templates/modules/github-repo/README.md

@@ -0,0 +1,23 @@
+# Module: github-repo
+
+Enables the Engineer to work in a GitHub repository.
+
+## What it adds
+
+- **Shared docs**: `docs/git-workflow.md` — commit conventions, branch rules
+- **Engineer skill**: Git workflow instructions for working in a repo
+
+## Variants
+
+- **direct-to-main** (default): Engineer commits directly on main. No branches, no PRs. Fast iteration for solo engineer setups.
+- When combined with `pr-review` module: switches to feature-branch workflow automatically.
+
+## Best for
+
+- Solo engineer shipping quickly
+- Prototypes and MVPs
+- Projects where speed > process
+
+## Example
+
+A company building a web app with one engineer. The engineer picks up issues, implements them, commits to main, and marks the issue done. CI runs on push.

package/templates/modules/github-repo/agents/engineer/skills/git-workflow.md

@@ -0,0 +1,23 @@
+# Skill: Git Workflow
+
+You work in a GitHub repository. Follow the conventions in `docs/git-workflow.md` in the project root.
+
+## Direct-to-Main Flow
+
+1. Pull latest: `git pull origin main`
+2. Make your changes
+3. Run available checks (lint, typecheck, tests)
+4. Commit using Conventional Commits: `<type>: <description>`
+5. Push to main: `git push origin main`
+6. If CI fails, fix immediately
+
+## Rules
+
+- Always pull before starting work to avoid conflicts.
+- Keep commits focused — one concern per commit.
+- Never force push to main.
+- If you encounter merge conflicts, resolve them carefully. When in doubt, escalate to the CEO.
+- Reference the issue ID in the commit body (e.g., `Closes YES-5`).
+- Never mark an issue as `done` unless at least one new commit was created for that issue's work and pushed.
+- Before marking `done`, verify there is no uncommitted work (`git status --short` should be clean).
+- If no repository change is required, do not mark `done` silently: leave an issue comment explaining why no code change was needed and escalate to the CEO for decision.

package/templates/modules/github-repo/docs/git-workflow.md

@@ -0,0 +1,50 @@
+# Git Workflow
+
+## Commit Conventions
+
+Use Conventional Commits format for all commit messages:
+
+```
+<type>: <short description>
+```
+
+Types: `feat`, `fix`, `docs`, `chore`, `refactor`, `test`, `perf`
+
+Examples:
+- `feat: add user authentication endpoint`
+- `fix: resolve null pointer in game loop`
+- `docs: update README with setup instructions`
+
+Rules:
+- Lowercase after colon
+- No period at end
+- Under 72 characters
+- Reference issue ID in commit body when applicable
+
+## Direct-to-Main Workflow
+
+1. Pull latest from main
+2. Make changes
+3. Run tests/linting locally if available
+4. Commit with conventional commit message
+5. Push to main
+6. Verify CI passes (if configured)
+
+## What Requires a Commit
+
+- Code logic changes
+- Configuration changes
+- Feature additions
+- Bug fixes
+- Documentation updates
+- Infrastructure changes
+
+## Issue Completion Guardrails
+
+- Never mark an issue as `done` unless at least one new commit exists for that issue's work and has been pushed.
+- Before marking `done`, ensure the working tree is clean (`git status --short` shows no pending changes).
+- If no repository change is required, do not silently close as `done`: add an issue comment explaining why no code change was needed and escalate to the CEO for explicit decision.
+
+## CI
+
+If the project has CI configured (e.g., GitHub Actions), always verify your push passes CI. If CI fails, fix it immediately — a broken main blocks everyone.

package/templates/modules/github-repo/module.meta.json

@@ -0,0 +1,12 @@
+{
+  "name": "github-repo",
+  "description": "Connects the team to a GitHub repository. Required by most engineering workflow modules.",
+  "capabilities": [],
+  "issues": [
+    {
+      "title": "Initialize GitHub repository",
+      "assignTo": "engineer",
+      "description": "Create the GitHub repository, initialize with README, push initial commit to main, and set up branch protection if using PR workflow."
+    }
+  ]
+}

package/templates/modules/hiring-review/agents/ceo/skills/hiring-review.fallback.md

@@ -0,0 +1,17 @@
+# Skill: Hiring Review (Fallback)
+
+The Product Owner primarily manages team composition analysis. You are the fallback — step in only if the PO is absent or hasn't addressed critical team gaps.
+
+## Hiring Review (Fallback)
+
+1. Query current agents: `GET /api/companies/{companyId}/agents`
+2. If a critical capability gap is blocking progress and the PO hasn't acted:
+   - Create a board approval request for the most urgent hire
+   - Keep it to one proposal at a time
+   - Tag the PO to take over broader team planning
+
+## Rules
+
+- This is a safety net, not your primary job. Let the PO own it.
+- Only propose hires when progress is visibly blocked by missing expertise.
+- One hire at a time. Don't over-expand.

package/templates/modules/hiring-review/module.meta.json

@@ -0,0 +1,21 @@
+{
+  "name": "hiring-review",
+  "description": "Adds a review step before new agents are hired. Gives the board visibility into team composition changes.",
+  "capabilities": [
+    {
+      "skill": "hiring-review",
+      "owners": [
+        "product-owner",
+        "ceo"
+      ],
+      "fallbackSkill": "hiring-review.fallback"
+    }
+  ],
+  "issues": [
+    {
+      "title": "Evaluate team composition and propose new hires",
+      "assignTo": "capability:hiring-review",
+      "description": "Review the current team against the company goal and project requirements. Identify missing expertise or capacity gaps. For each proposed hire, create a board approval request with the role, justification, and suggested adapter configuration."
+    }
+  ]
+}

package/templates/modules/hiring-review/skills/hiring-review.md

@@ -0,0 +1,24 @@
+# Skill: Hiring Review
+
+You own team composition analysis. Evaluate whether the current team can deliver on the company goal, and propose hires when gaps exist.
+
+## Hiring Review Process
+
+1. Query current agents: `GET /api/companies/{companyId}/agents`
+2. Review the company goal and project scope
+3. For each identified gap:
+   - Define the role (use Paperclip role enum: engineer, pm, qa, designer, researcher, devops, general)
+   - Write a justification: what capability is missing and why it matters
+   - Suggest adapter configuration (model, effort level)
+   - Create a board approval request via `POST /api/companies/{companyId}/approvals` with:
+     - `type: "hire"`
+     - `title`: role name and purpose
+     - `description`: justification and config suggestion
+4. Document the team assessment in your daily notes
+
+## Rules
+
+- Don't propose hires for capabilities already covered by existing roles.
+- Consider whether an existing agent could take on additional responsibilities before hiring.
+- Prioritize roles that unblock the most work.
+- Each hire proposal must go through board approval — never create agents directly.