Fantasy-Map-Generator/.github/copilot-instructions.md

BMAD Method — Project Instructions

Project Configuration

• Project: Fantasy-Map-Generator
• User: Azgaar
• Communication Language: English
• Document Output Language: English
• User Skill Level: intermediate
• Output Folder: {project-root}/_bmad-output
• Planning Artifacts: {project-root}/_bmad-output/planning-artifacts
• Implementation Artifacts: {project-root}/_bmad-output/implementation-artifacts
• Project Knowledge: {project-root}/docs

BMAD Runtime Structure

• Agent definitions: _bmad/bmm/agents/ (BMM module) and _bmad/core/agents/ (core)
• Workflow definitions: _bmad/bmm/workflows/ (organized by phase)
• Core tasks: _bmad/core/tasks/ (help, editorial review, indexing, sharding, adversarial review)
• Core workflows: _bmad/core/workflows/ (brainstorming, party-mode, advanced-elicitation)
• Workflow engine: _bmad/core/tasks/workflow.xml (executes YAML-based workflows)
• Module configuration: _bmad/bmm/config.yaml
• Core configuration: _bmad/core/config.yaml
• Agent manifest: _bmad/_config/agent-manifest.csv
• Workflow manifest: _bmad/_config/workflow-manifest.csv
• Help manifest: _bmad/_config/bmad-help.csv
• Agent memory: _bmad/_memory/

Key Conventions

• Always load _bmad/bmm/config.yaml before any agent activation or workflow execution
• Store all config fields as session variables: {user_name}, {communication_language}, {output_folder}, {planning_artifacts}, {implementation_artifacts}, {project_knowledge}
• MD-based workflows execute directly — load and follow the .md file
• YAML-based workflows require the workflow engine — load workflow.xml first, then pass the .yaml config
• Follow step-based workflow execution: load steps JIT, never multiple at once
• Save outputs after EACH step when using the workflow engine
• The {project-root} variable resolves to the workspace root at runtime

Available Agents

Agent	Persona	Title	Capabilities
bmad-master	BMad Master	BMad Master Executor, Knowledge Custodian, and Workflow Orchestrator	runtime resource management, workflow orchestration, task execution, knowledge custodian
analyst	Mary	Business Analyst	market research, competitive analysis, requirements elicitation, domain expertise
architect	Winston	Architect	distributed systems, cloud infrastructure, API design, scalable patterns
dev	Amelia	Developer Agent	story execution, test-driven development, code implementation
pm	John	Product Manager	PRD creation, requirements discovery, stakeholder alignment, user interviews
qa	Quinn	QA Engineer	test automation, API testing, E2E testing, coverage analysis
quick-flow-solo-dev	Barry	Quick Flow Solo Dev	rapid spec creation, lean implementation, minimum ceremony
sm	Bob	Scrum Master	sprint planning, story preparation, agile ceremonies, backlog management
tech-writer	Paige	Technical Writer	documentation, Mermaid diagrams, standards compliance, concept explanation
ux-designer	Sally	UX Designer	user research, interaction design, UI patterns, experience strategy

Slash Commands

Type /bmad- in Copilot Chat to see all available BMAD workflows and agent activators. Agents are also available in the agents dropdown.

Project Architecture: Critical Rules for All Agents

main.js globals — NEVER use globalThis

public/main.js and all public/modules/**/*.js files are plain <script defer> tags — NOT ES modules. Every top-level declaration is a window property automatically.

Key globals always available on window at runtime: scale, viewX, viewY, graphWidth, graphHeight, svgWidth, svgHeight, pack, grid, viewbox, svg, zoom, seed, options, byId, rn, tip, layerIsOn and many more.

**Rule: In src/**/\*.ts(ES modules), just use the globals directly — they are declared as ambient globals insrc/types/global.ts:**

// ✅ CORRECT — declared in src/types/global.ts, use as bare identifiers
buildCameraBounds(viewX, viewY, scale, graphWidth, graphHeight);
viewbox.on("zoom.webgl", handler);

// ❌ WRONG — never do these
(window as any).scale(globalThis as any).scale;

Full reference: see docs/architecture-globals.md.

Code Style — Non-Negotiable Rules for All Agents

• No unnecessary comments. Code is self-documenting. Add a comment only when the why is non-obvious from reading the code itself. Never describe what the code does.
• Clean abstractions that don't leak. Each abstraction fully owns its concern. Callers must not need to know implementation details. If a caller must pass a flag to alter internal behavior, the abstraction is wrong — split it.
• No academic over-engineering. No design patterns, extra layers, or wrapper objects unless the problem concretely requires them. Solve the current requirement; do not design for hypothetical future variants.
• Minimal artifacts. Only create files mandated by acceptance criteria. No speculative utils stubs, barrel re-exports, or helper files without multiple concrete callers.