@starlein/paperclip-plugin-company-wizard 0.2.1

package/templates/modules/ci-cd/agents/engineer/skills/ci-cd.fallback.md

@@ -0,0 +1,18 @@
+# Skill: CI/CD Pipeline (Fallback)
+
+The DevOps engineer primarily owns CI/CD pipelines. You are the fallback — step in only if DevOps is absent or hasn't set up the pipeline.
+
+## CI/CD (Fallback)
+
+1. If no CI workflow exists and DevOps hasn't started:
+   - Create a basic CI workflow: lint + test on PRs, build on push to main
+   - Use standard caching and pinned action versions
+   - Document the setup in `docs/CI-CD.md`
+   - Mark the pipeline as **provisional** — it needs DevOps review for CD, caching optimization, and security hardening
+2. If DevOps is active, skip this entirely.
+
+## Rules
+
+- This is a safety net. Set up the basics — lint, test, build.
+- Skip CD (deployment) — that requires infrastructure knowledge best left to DevOps.
+- Let DevOps own pipeline optimization, deployment, and ongoing maintenance.

package/templates/modules/ci-cd/docs/ci-cd-template.md

@@ -0,0 +1,42 @@
+# CI/CD Pipeline
+
+## Pipeline Overview
+
+_Describe the CI/CD setup, tooling (e.g., GitHub Actions), and overall strategy._
+
+## CI Workflow
+
+Runs on: _PRs and pushes to main_
+
+| Stage      | Trigger             | What it does                        |
+|------------|---------------------|-------------------------------------|
+| Lint       | _PR, push to main_  | _Run linter (e.g., ESLint)_        |
+| Test       | _PR, push to main_  | _Run test suite_                    |
+| Build      | _PR, push to main_  | _Compile/typecheck the project_     |
+
+## CD Workflow
+
+Runs on: _merge to main_
+
+| Stage      | Trigger             | What it does                        |
+|------------|---------------------|-------------------------------------|
+| Deploy     | _merge to main_     | _Deploy to target environment_      |
+| Smoke Test | _after deploy_      | _Verify deployment is healthy_      |
+
+## Environment Variables
+
+| Variable   | Where set           | Purpose                             |
+|------------|---------------------|-------------------------------------|
+| _VAR_NAME_ | _GitHub Secrets_    | _Description_                       |
+
+## Deployment Targets
+
+- **Production**: _URL or environment description_
+- **Staging**: _URL or environment description (if applicable)_
+
+## Rollback Procedure
+
+1. _Identify the failing deployment_
+2. _Revert the merge commit or re-deploy the previous known-good commit_
+3. _Verify rollback via smoke tests_
+4. _Investigate root cause before re-deploying the fix_

package/templates/modules/ci-cd/module.meta.json

@@ -0,0 +1,105 @@
+{
+  "name": "ci-cd",
+  "description": "Sets up continuous integration and deployment pipelines. Automates testing, building, and shipping on every push.",
+  "requires": [
+    "github-repo"
+  ],
+  "capabilities": [
+    {
+      "skill": "ci-cd",
+      "owners": [
+        "devops",
+        "engineer"
+      ],
+      "fallbackSkill": "ci-cd.fallback"
+    }
+  ],
+  "issues": [
+    {
+      "title": "Set up CI/CD pipeline",
+      "assignTo": "capability:ci-cd",
+      "description": "Configure continuous integration (lint, test, build) and deployment pipeline. Document the setup in docs/CI-CD.md. Use GitHub Actions or equivalent."
+    },
+    {
+      "title": "Add linter and configure lint rules",
+      "description": "Install and configure a linter (ESLint, Ruff, golangci-lint, etc. depending on the stack). Use sensible defaults — focus on catching bugs, not style wars. Add a `lint` script to the project.",
+      "priority": "high",
+      "assignTo": "engineer"
+    },
+    {
+      "title": "Add lint step to CI workflow",
+      "description": "Add a linting step to the CI pipeline. It should run on every push and PR. Fail the build on lint errors.",
+      "priority": "high",
+      "assignTo": "engineer"
+    },
+    {
+      "title": "Add test runner and initial tests",
+      "description": "Set up a test runner (Jest, Vitest, pytest, go test, etc.). Write at least one meaningful test to verify the setup works. Add a `test` script to the project.",
+      "priority": "high",
+      "assignTo": "engineer"
+    },
+    {
+      "title": "Add test step to CI workflow",
+      "description": "Add a testing step to the CI pipeline that runs the full test suite. Report results clearly — developers should know exactly what failed and why.",
+      "priority": "high",
+      "assignTo": "engineer"
+    },
+    {
+      "title": "Configure build step",
+      "description": "Add a build step that compiles/bundles the application into deployable artifacts. Ensure it runs in CI and outputs are consistent across environments.",
+      "priority": "medium",
+      "assignTo": "engineer"
+    },
+    {
+      "title": "Set up deployment automation",
+      "description": "Configure automated deployment to at least one environment (staging or production). Use the CI pipeline to trigger deploys on successful builds from the main branch. Include a rollback strategy.",
+      "priority": "medium",
+      "assignTo": "engineer"
+    },
+    {
+      "title": "Add deployment smoke tests",
+      "description": "After each deployment, run a basic smoke test to verify the application is healthy. Check key endpoints, verify the correct version is deployed, and alert on failure.",
+      "priority": "medium",
+      "assignTo": "engineer"
+    }
+  ],
+  "goal": {
+    "title": "Set up CI/CD pipeline",
+    "description": "Establish a complete CI/CD pipeline: automated linting, testing, building, and deployment. Every push to main should be verified automatically, and deployments should be reproducible and low-risk.",
+    "project": false,
+    "subgoals": [
+      {
+        "id": "linting",
+        "title": "Automated linting",
+        "level": "team",
+        "description": "Enforce code quality standards automatically on every push. Linter runs in CI and blocks merges on failure."
+      },
+      {
+        "id": "testing",
+        "title": "Automated testing",
+        "level": "team",
+        "description": "Run the test suite automatically and report results. Tests run in CI with pass/fail status reported on commits and PRs."
+      },
+      {
+        "id": "build",
+        "title": "Automated build",
+        "level": "team",
+        "description": "Build artifacts are produced automatically and consistently. Build step runs in CI and produces deployable artifacts."
+      },
+      {
+        "id": "deploy",
+        "title": "Automated deployment",
+        "level": "team",
+        "description": "Deploy to staging or production with minimal manual intervention. Pushes to main trigger automated deployment to at least one environment."
+      }
+    ]
+  },
+  "routines": [
+    {
+      "title": "CI pipeline health check",
+      "description": "Review recent CI runs for failures, flaky tests, and slow builds. Flag regressions and report pipeline health status.",
+      "assignTo": "capability:ci-cd",
+      "schedule": "0 9 * * 1-5"
+    }
+  ]
+}

package/templates/modules/ci-cd/skills/ci-cd.md

@@ -0,0 +1,26 @@
+# Skill: CI/CD Pipeline
+
+You manage continuous integration and deployment pipelines. Follow the conventions in `docs/CI-CD.md` in the project root.
+
+## Setup Steps
+
+1. Review the tech stack to determine build, lint, and test tooling
+2. Create a CI workflow (GitHub Actions or equivalent):
+   - Lint on all PRs and pushes to main
+   - Run tests on all PRs and pushes to main
+   - Build/typecheck to verify compilation
+3. Create a CD workflow:
+   - Trigger on merge to main
+   - Deploy to the target environment
+   - Run smoke tests after deployment
+4. Add status badges to the project README
+5. Document the full pipeline in `docs/CI-CD.md`
+
+## Rules
+
+- Fail fast — put the quickest checks (lint, typecheck) first.
+- Keep pipelines under 5 minutes. If they exceed this, add caching or split stages.
+- Use dependency caching (e.g., `actions/cache`, `setup-node` cache) to speed up installs.
+- Pin action versions to full SHAs, not tags, for security.
+- Never store secrets in workflow files — use GitHub Secrets or equivalent.
+- If CI breaks main, fix it immediately — a red main blocks everyone.

package/templates/modules/codebase-onboarding/agents/ceo/skills/codebase-audit.fallback.md

@@ -0,0 +1,19 @@
+# Skill: Codebase Audit (Fallback)
+
+The Engineer primarily owns codebase auditing and health. You are the fallback — step in only if the Engineer is absent or hasn't started.
+
+## Codebase Audit (Fallback)
+
+1. If no `docs/CODEBASE-AUDIT.md` exists and the Engineer hasn't started:
+   - Read the project structure and key configuration files
+   - Write a high-level architecture overview in `docs/CODEBASE-AUDIT.md`
+   - List obvious tech debt items visible from a surface-level read
+   - Mark the document as **provisional** — it needs a thorough engineering review
+2. If the Engineer is active, skip this entirely.
+
+## Rules
+
+- This is a safety net. Document what you can see from the project's top-level structure.
+- Skip deep code analysis — that requires engineering expertise.
+- Don't create cleanup issues — leave that to the Engineer's thorough audit.
+- Let the Engineer own the ongoing health checks and refactoring work.

package/templates/modules/codebase-onboarding/module.meta.json

@@ -0,0 +1,24 @@
+{
+  "name": "codebase-onboarding",
+  "description": "Audits an existing codebase and maps its architecture. Gets agents up to speed fast on any inherited code.",
+  "requires": [
+    "github-repo"
+  ],
+  "capabilities": [
+    {
+      "skill": "codebase-audit",
+      "owners": [
+        "engineer",
+        "ceo"
+      ],
+      "fallbackSkill": "codebase-audit.fallback"
+    }
+  ],
+  "issues": [
+    {
+      "title": "Audit codebase and document architecture",
+      "assignTo": "capability:codebase-audit",
+      "description": "Read the existing codebase, map the architecture, identify tech debt hotspots and test coverage gaps. Document findings in docs/CODEBASE-AUDIT.md. Create follow-up issues for cleanup opportunities."
+    }
+  ]
+}

package/templates/modules/codebase-onboarding/skills/codebase-audit.md

@@ -0,0 +1,45 @@
+# Skill: Codebase Audit
+
+You are responsible for understanding the existing codebase and maintaining its health over time. This skill has two modes: initial audit (first run) and ongoing health checks (subsequent heartbeats).
+
+## Initial Audit
+
+Run this when `docs/CODEBASE-AUDIT.md` does not yet exist.
+
+1. Map the project structure — identify key directories, entry points, and architectural layers.
+2. Read configuration files (package.json, tsconfig, Dockerfile, CI configs) to understand the tech stack and build pipeline.
+3. Identify the dependency graph — which modules depend on which, where are the coupling hotspots.
+4. Assess test coverage — find untested code paths, missing test files, or weak assertions.
+5. Identify tech debt — dead code, unused exports, overly complex functions, inconsistent patterns, duplicated logic.
+6. Check for code quality issues — long files, deep nesting, functions with too many parameters, missing error handling at boundaries.
+7. Document everything in `docs/CODEBASE-AUDIT.md`:
+   - Architecture overview (layers, key components, data flow)
+   - Tech stack summary
+   - Tech debt inventory (ranked by severity: critical, major, minor)
+   - Test coverage assessment
+   - Recommended cleanup priorities
+8. Create follow-up issues for the top cleanup opportunities (one issue per fix, small and actionable).
+
+## Ongoing Health Checks
+
+Run this on every heartbeat when `docs/CODEBASE-AUDIT.md` already exists.
+
+1. Check recent commits for newly introduced complexity or tech debt.
+2. Look for refactoring opportunities in code you or other agents have touched.
+3. When fewer than 3 open cleanup issues remain, identify the next batch from the audit.
+4. Execute small cleanup tasks directly when the fix is obvious and low-risk:
+   - Remove dead code and unused imports
+   - Fix inconsistent naming or formatting
+   - Simplify overly complex conditionals
+   - Extract duplicated logic into shared utilities
+5. For larger refactors, create issues with clear scope and rationale instead of acting immediately.
+6. Update `docs/CODEBASE-AUDIT.md` when the architecture or tech debt landscape changes significantly.
+
+## Rules
+
+- Read before you write. Understand the intent of existing code before changing it.
+- Small, focused changes. Each cleanup PR should do one thing. Never combine unrelated fixes.
+- Don't refactor code that is actively being worked on by another agent — check issue assignments first.
+- Preserve behavior. Cleanup must not change functionality. Run tests after every change.
+- Prioritize by impact — fix things that slow down the team or cause bugs, not cosmetic issues.
+- If `docs/CODEBASE-AUDIT.md` exists, review it before starting. Don't duplicate findings.

package/templates/modules/competitive-intel/agents/ceo/skills/competitive-tracking.fallback.md

@@ -0,0 +1,17 @@
+# Skill: Competitive Tracking (Fallback)
+
+The Customer Success Manager, CMO, and Product Owner own competitive intelligence above you. You are the last-resort fallback — step in only if all three are absent or haven't delivered the analysis.
+
+## Competitive Tracking (Fallback)
+
+1. If no `docs/COMPETITIVE-LANDSCAPE.md` exists and nobody has started:
+   - Identify the top 2-3 competitors based on the company goal
+   - Write a brief comparison: what they do, how we differ
+   - Document in `docs/COMPETITIVE-LANDSCAPE.md`
+   - Tag the Customer Success Manager, CMO, or Product Owner to expand
+2. If any of the above roles are active, skip this entirely.
+
+## Rules
+
+- This is a safety net. Keep it brief — enough to inform initial positioning.
+- Let the dedicated role own ongoing competitive intelligence.

package/templates/modules/competitive-intel/agents/cmo/skills/competitive-tracking.fallback.md

@@ -0,0 +1,17 @@
+# Skill: Competitive Tracking (Fallback)
+
+The Customer Success Manager owns competitive intelligence above you. You are the fallback — step in if the Customer Success Manager is absent.
+
+## Competitive Tracking (Fallback)
+
+1. If no `docs/COMPETITIVE-LANDSCAPE.md` exists and the Customer Success Manager hasn't started:
+   - Research competitors from a marketing perspective: positioning, messaging, content strategy
+   - Document in `docs/COMPETITIVE-LANDSCAPE.md`
+   - Focus on differentiation opportunities for go-to-market
+   - Tag the Customer Success Manager to expand with customer-facing insights
+2. If the Customer Success Manager is active, skip this entirely.
+
+## Rules
+
+- Focus on marketing and positioning angles — that's your domain.
+- Let the Customer Success Manager own customer-perspective competitive analysis.

package/templates/modules/competitive-intel/agents/customer-success/skills/competitive-tracking.md

@@ -0,0 +1,25 @@
+# Skill: Competitive Tracking
+
+You own competitive intelligence from the customer perspective. You hear what customers say about competitors firsthand.
+
+## Competitive Tracking Process
+
+1. Review the company goal and existing market analysis — if `docs/MARKET-ANALYSIS.md` exists, use it as context.
+2. Research and document in `docs/COMPETITIVE-LANDSCAPE.md`:
+   - **Competitor profiles**: For each key competitor (3-5), document:
+     - Product overview and target audience
+     - What customers say about switching to/from them
+     - Strengths customers mention and weaknesses they complain about
+     - Pricing comparison (if public)
+     - Recent moves (launches, outages, pricing changes)
+   - **Win/loss patterns**: Why customers choose us vs competitors
+   - **Feature gaps**: What customers wish we had that competitors offer
+   - **Retention risks**: Competitor moves that might trigger churn
+3. Create follow-up issues for product improvements informed by competitive gaps
+4. Record summary in your daily notes
+
+## Rules
+
+- Ground analysis in customer evidence: quotes, support tickets, churn reasons.
+- Be opinionated about differentiation — neutral comparisons don't help.
+- Update when customers mention new competitive dynamics.

package/templates/modules/competitive-intel/module.meta.json

@@ -0,0 +1,23 @@
+{
+  "name": "competitive-intel",
+  "description": "Tracks competitors and surfaces market shifts. Keeps the team informed on what others are building.",
+  "capabilities": [
+    {
+      "skill": "competitive-tracking",
+      "owners": [
+        "customer-success",
+        "cmo",
+        "product-owner",
+        "ceo"
+      ],
+      "fallbackSkill": "competitive-tracking.fallback"
+    }
+  ],
+  "issues": [
+    {
+      "title": "Build initial competitive landscape",
+      "assignTo": "capability:competitive-tracking",
+      "description": "Research key competitors: their positioning, strengths, weaknesses, pricing, and recent moves. Document a living competitive landscape in docs/COMPETITIVE-LANDSCAPE.md with actionable differentiation insights."
+    }
+  ]
+}

package/templates/modules/competitive-intel/skills/competitive-tracking.md

@@ -0,0 +1,27 @@
+# Skill: Competitive Tracking
+
+You own competitive intelligence. This is a living analysis — profiles evolve over time as the competitive landscape shifts.
+
+## Competitive Tracking Process
+
+1. Review the company goal and existing market analysis — if `docs/MARKET-ANALYSIS.md` exists, use it as context. Otherwise, start from the project description.
+2. Research and document in `docs/COMPETITIVE-LANDSCAPE.md`:
+   - **Competitor profiles**: For each key competitor (3-5), document:
+     - Product overview and target audience
+     - Positioning and messaging
+     - Strengths and weaknesses
+     - Pricing model (if public)
+     - Recent changes (launches, pivots, funding)
+   - **Differentiation map**: How we compare on key dimensions
+   - **Gaps and opportunities**: Where competitors are weak and we can win
+   - **Threats**: Where competitors are strong and we need to defend
+3. Create follow-up issues for strategic decisions informed by competitive insights:
+   - `POST /api/companies/{companyId}/issues` with specific recommendations. Include the active `projectId` (and `goalId` / `parentId` when applicable).
+4. Record summary in your daily notes
+
+## Rules
+
+- Be factual. Base analysis on observable evidence, not speculation.
+- Be opinionated. "Competitor X is strong at Y" is more useful than neutral feature lists.
+- Keep profiles current. Update when significant competitor moves happen.
+- Focus on actionable differentiation, not exhaustive feature comparison.

package/templates/modules/dependency-management/agents/engineer/skills/dependency-audit.fallback.md

@@ -0,0 +1,18 @@
+# Skill: Dependency Audit (Fallback)
+
+DevOps or Security Engineer primarily owns dependency management. You are the fallback — step in only if they are absent.
+
+## Dependency Audit (Fallback)
+
+1. If no `docs/DEPENDENCY-AUDIT.md` exists and no one else has started:
+   - Run the package manager's built-in audit command (`npm audit`, `pip-audit`, etc.)
+   - Apply safe patch-level updates that don't break tests
+   - Document current dependency state in `docs/DEPENDENCY-AUDIT.md`
+   - Mark the document as **provisional** — it needs a security/ops review for CVE prioritization
+2. If DevOps or Security Engineer is active, skip this entirely.
+
+## Rules
+
+- This is a safety net. Run the audit and apply safe patches only.
+- Skip major version upgrades — those need dedicated planning.
+- Don't make migration decisions — leave those to the primary owner.

package/templates/modules/dependency-management/module.meta.json

@@ -0,0 +1,25 @@
+{
+  "name": "dependency-management",
+  "description": "Audits and maintains project dependencies. Flags outdated packages, security issues, and license risks.",
+  "requires": [
+    "github-repo"
+  ],
+  "capabilities": [
+    {
+      "skill": "dependency-audit",
+      "owners": [
+        "devops",
+        "security-engineer",
+        "engineer"
+      ],
+      "fallbackSkill": "dependency-audit.fallback"
+    }
+  ],
+  "issues": [
+    {
+      "title": "Audit dependencies and create upgrade plan",
+      "assignTo": "capability:dependency-audit",
+      "description": "Audit all project dependencies for outdated versions, known vulnerabilities, and deprecated packages. Document findings and create a prioritized upgrade plan."
+    }
+  ]
+}

package/templates/modules/dependency-management/skills/dependency-audit.md

@@ -0,0 +1,43 @@
+# Skill: Dependency Audit
+
+You are responsible for keeping the project's dependencies healthy, secure, and up to date.
+
+## Steps
+
+1. **Inventory** — List all direct and transitive dependencies with current versions.
+   - For Node.js: `npm outdated`, `npm ls --all`
+   - For Python: `pip list --outdated`, `pip-audit`
+   - For Go: `go list -m -u all`
+   - Adapt to the project's package manager.
+2. **Vulnerability scan** — Check for known CVEs.
+   - `npm audit`, `pip-audit`, `go vuln check`, or equivalent
+   - Cross-reference with GitHub Security Advisories if available
+3. **Classify findings** by severity:
+   - **Critical** — Active CVE with known exploit, or dependency is abandoned/unmaintained
+   - **Major** — Outdated by 2+ major versions, or has high-severity CVE without known exploit
+   - **Minor** — Outdated by 1 major version or multiple minor versions, no security impact
+4. **Create upgrade plan** — For each finding, determine:
+   - Can it be updated in-place (patch/minor bump)?
+   - Does it require migration work (major version, breaking changes)?
+   - Are there alternatives if the dependency is abandoned?
+5. **Document** findings in `docs/DEPENDENCY-AUDIT.md`:
+   - Summary table of dependencies by status (current, outdated, vulnerable, deprecated)
+   - Prioritized upgrade plan with estimated effort
+   - Lock file hygiene notes
+6. **Execute safe upgrades** — Apply patch and minor updates directly when tests pass.
+7. **Create issues** for major version upgrades or migrations that require dedicated work.
+
+## Ongoing
+
+On each heartbeat when `docs/DEPENDENCY-AUDIT.md` exists:
+1. Run vulnerability scan — if new CVEs appear, create issues immediately.
+2. Check for newly outdated dependencies — update the audit doc.
+3. Apply safe patch updates and verify tests pass.
+
+## Rules
+
+- Never upgrade a major version without creating an issue first — breaking changes need review.
+- Always run the full test suite after any dependency update.
+- Keep the lock file committed. Never delete or regenerate it without reason.
+- If a dependency is abandoned, research alternatives and create an issue with a migration proposal.
+- Document why a dependency is pinned if you intentionally skip an upgrade.

package/templates/modules/documentation/agents/ceo/skills/project-docs.fallback.md

@@ -0,0 +1,16 @@
+# Skill: Project Documentation (Fallback)
+
+The Technical Writer and Engineer own project documentation above you. You are the last-resort fallback — step in only if both are absent or haven't delivered documentation.
+
+## Project Documentation (Fallback)
+
+1. If no README.md exists and nobody has started:
+   - Write a brief project overview: what it does, who it's for, how to get started
+   - Document in README.md
+   - Tag the Technical Writer or Engineer to expand
+2. If the Technical Writer or Engineer is active, skip this entirely.
+
+## Rules
+
+- This is a safety net. Keep it to the absolute essentials.
+- Let the Technical Writer own ongoing documentation.

package/templates/modules/documentation/agents/engineer/skills/project-docs.fallback.md

@@ -0,0 +1,16 @@
+# Skill: Project Documentation (Fallback)
+
+The Technical Writer owns project documentation above you. You are the fallback — step in only if the Technical Writer is absent or hasn't started.
+
+## Project Documentation (Fallback)
+
+1. If no README.md exists or it's a bare skeleton:
+   - Write a minimal README with project overview, setup instructions, and basic usage
+   - Add inline code comments for complex logic you encounter during regular work
+   - Tag the Technical Writer to expand and maintain documentation
+2. If the Technical Writer is active, skip this entirely.
+
+## Rules
+
+- This is a safety net. Keep it minimal — enough to onboard a new contributor.
+- Let the Technical Writer own comprehensive documentation.

package/templates/modules/documentation/module.meta.json

@@ -0,0 +1,22 @@
+{
+  "name": "documentation",
+  "description": "Maintains project documentation: guides, API references, and architecture notes.",
+  "capabilities": [
+    {
+      "skill": "project-docs",
+      "owners": [
+        "technical-writer",
+        "engineer",
+        "ceo"
+      ],
+      "fallbackSkill": "project-docs.fallback"
+    }
+  ],
+  "issues": [
+    {
+      "title": "Create initial project documentation",
+      "assignTo": "capability:project-docs",
+      "description": "Write the foundational project documentation: README with setup instructions, architecture overview, API reference (if applicable), and contribution guide. Document in the project root and docs/ directory."
+    }
+  ]
+}

package/templates/modules/documentation/skills/project-docs.md

@@ -0,0 +1,25 @@
+# Skill: Project Documentation
+
+You own project documentation. Good docs let new contributors (human or agent) get productive fast.
+
+## Documentation Process
+
+1. Review the project structure, existing code, and any architecture docs.
+2. Create or update the following:
+   - **README.md**: Project overview, setup instructions, usage examples, development workflow
+   - **API reference** (if applicable): Endpoints, parameters, response shapes, authentication
+   - **Architecture overview**: High-level system design, component relationships, data flow
+   - **Contributing guide**: How to set up the dev environment, coding conventions, PR process
+3. Ensure documentation accuracy:
+   - All setup instructions should be tested and working
+   - API docs should match the actual implementation
+   - Architecture docs should reflect the current state, not aspirations
+4. Create follow-up issues for documentation gaps discovered during review
+5. Record summary in your daily notes
+
+## Rules
+
+- Accuracy over completeness. Wrong docs are worse than no docs.
+- One source of truth per topic. Don't duplicate information across files.
+- Keep docs close to code. Reference specific files and paths.
+- Update docs when you notice drift — don't let them go stale.

package/templates/modules/game-design/agents/ceo/skills/game-design.fallback.md

@@ -0,0 +1,17 @@
+# Skill: Game Design (Fallback)
+
+The Game Designer or Engineer primarily owns the game design. You are the fallback — step in only if they are absent or haven't started.
+
+## Game Design (Fallback)
+
+1. If no `docs/GDD.md` exists and no one else has started:
+   - Write a minimal Game Design Document covering: concept pitch, core mechanic, basic game loop, target platform
+   - List obvious design questions that need answers (progression, win conditions, art style)
+   - Mark the document as **provisional** — it needs a thorough design review
+2. If the Game Designer or Engineer is active, skip this entirely.
+
+## Rules
+
+- This is a safety net. Define the basics so the team has direction.
+- Skip detailed mechanics, balancing, and progression — those need dedicated design work.
+- Don't make art direction decisions — leave those to the Game Artist or Game Designer.

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

@@ -0,0 +1,51 @@
+# Skill: Game Design (Game Designer)
+
+You are the primary owner of the game design. This is your core responsibility.
+
+## Game Design Document
+
+Create and maintain `docs/GDD.md` as the single source of truth. Cover every section thoroughly:
+
+1. **Concept** — One-paragraph pitch. Genre, theme, target platform, target audience. What makes this game unique?
+2. **Core mechanic** — The central verb. Define precisely: input → action → feedback → consequence. What makes it feel good?
+3. **Game loop** — Three layers:
+   - **Moment-to-moment** — The 5-second loop. What creates flow state?
+   - **Session loop** — The 15-minute loop. What gives structure and pacing?
+   - **Meta loop** — The multi-session loop. What creates "one more run" compulsion?
+4. **Mechanics catalog** — Every mechanic in the game: name, description, when introduced, interactions with other mechanics.
+5. **Progression** — Difficulty curve design. What gates progress? Skill gates vs content gates. Unlock schedule.
+6. **Economy** (if applicable) — Resources, currencies, costs, rewards, drop rates. The flow of value.
+7. **Win/lose conditions** — Session end conditions. Game end conditions. Fail states and recovery.
+8. **Controls** — Input mapping per platform. Responsiveness targets (input lag, animation cancel windows).
+9. **Game feel** — Coyote time, input buffering, screen shake, hit stop, juice. The invisible design.
+10. **Art direction** — Visual style, reference games, color language (what colors mean in gameplay), silhouette readability.
+11. **Audio direction** — Music style, SFX for feedback loops, adaptive audio triggers.
+12. **Tuning parameters** — Every balance-relevant value as a named parameter:
+    - Format: `parameter_name: default_value (range: min–max) — what it affects`
+    - Group by system: player, enemies, economy, progression
+
+## Balancing
+
+After each playtest round:
+
+1. Read `docs/PLAYTEST-RESULTS.md` (if it exists).
+2. Identify the top 3 balance issues by player impact.
+3. Adjust tuning parameters with clear rationale.
+4. Update the GDD with new values.
+5. Create issues for parameter changes that need engineering implementation.
+
+## Design Experiments
+
+When a mechanic is uncertain:
+
+1. Define two variants with specific parameter differences.
+2. Create a playtest issue specifying what to compare and how to measure.
+3. After results, commit to one direction and document why.
+
+## Rules
+
+- Fun is measurable. "Players quit at level 3" is data. "The game needs to be more fun" is not actionable.
+- Design the minimum viable game first. Scope down ruthlessly. What's the smallest thing that's fun to play?
+- The GDD is alive. Update it every heartbeat if needed. A stale GDD is worse than no GDD.
+- Tuning values are never final. Document your reasoning so future changes have context.
+- Playtest early, playtest often. Paper design only gets you so far.