WallCraft-AI/agents.md

WallCraft AI Agents Collaboration Guide for WallCraft AI

Overview
- Purpose: Define how automated agents will plan, explore, and assist in building a cloud-driven AI workflow for FoundryVTT scene prep (walls, doors, windows), with a safe preview-first workflow.
- Scope: Plan, explore, and coordinate tasks across agent types; no direct code edits by agents, only plan and guidance unless explicitly executed by humans.

Agent Roles and Responsibilities
- General Planner (PlanAgent)
  - Create high-level task plans, decompose features into concrete steps, and assign ownership.
- Explorer (ExploreAgent)
  - Inspect repository structure, FoundryVTT APIs, and proposed module architecture.
- Code Searcher (CodesearchAgent)
  - Look up API docs, FoundryVTT wall/scene data models, and related examples.
- Web Scout (WebSearchAgent)
  - Retrieve current best practices, security considerations, and external docs relevant to cloud AI integration and similar Foundry workflows.

Interaction Protocol
- Requests and responses are exchanged as structured JSON envelopes.
- Each task has: task_id, objective, inputs, constraints, and expected outputs.
- All agents should statically log their actions to an in-app log or a dedicated journal entry for traceability.

Example envelope (high-level)
- Plan request
  {
    "task_id": "plan-001",
    "role": "Planner",
    "objective": "Define MVP milestones for AI Prep pipeline",
    "inputs": { "scope": "FoundryVTT 13.0.351 MVP" },
    "constraints": { "no destructive edits during planning": true }
  }
- Plan response
  {
    "status": "ok",
    "task_id": "plan-001",
    "plan": [
      "Create module scaffold with manifest.json",
      "Implement Settings for cloud endpoint and provider",
      "Add AI Prep UI (Scene toolbar) and preview layer",
      "Define payload schema and fixed prompt template",
      "Implement preview → manual adjust → apply workflow",
      "Add logging and minimal docs"
    ],
    "notes": "Keep MVP strictly non-destructive during preview; apply only after explicit confirmation."
  }

Task Lifecycle and Phases
- Phase 0: Planning and scoping
- Phase 1: MVP scaffolding (module skeleton, settings, UI hooks)
- Phase 2: Cloud integration and preview rendering
- Phase 3: Apply flow (convert AI walls to Foundry walls)
- Phase 4: Safety, validation, and docs
- Phase 5: Optional enhancements (Doors/Windows refine, per-scene prompts, etc.)

Data Exchange and Contracts (see data-contracts.md)
- Use a fixed, provider-agnostic payload to cloud AI endpoint
- Validate AI responses against Foundry grid constraints before enabling apply

Quality and Safety
- Preview is mandatory before applying changes
- All actions should be auditable (chat log or journal entry)
- Validate that walls align to grid and do not collide with tokens
- Optional data redaction in settings for privacy-sensitive scenes

Documentation and Handoff
- Produce a short design doc, an API contract summary, and a quick-start guide
- Maintain change logs for major iterations and provider changes

4) data-contracts.md
AI Prep Data Contracts (Input to AI, and AI Output)

Input payload to cloud AI
- Schema (JSON)
  {
    "scene": { "id": "scene123", "name": "Test Scene" },
    "gridSize": 32,
    "walls": [
      { "c": [1,1,5,1], "type": "wall", "notes": "outer boundary" },
      { "c": [5,1,5,5], "type": "door", "notes": "entry" }
    ],
    "tokens": [
      { "id": "tok1", "x": 3, "y": 3, "w": 1, "h": 1 }
    ],
    "promptTemplate": "Fixed MVP prompt template string",
    "providerMetadata": { "providerName": "OpenCodeCloud", "version": "v1" },
    "previewOnly": true
  }

AI output payload
- Schema (JSON)
  {
    "walls": [
      { "c": [1,1,6,1], "type": "wall", "notes": "perimeter suggestion" },
      { "c": [6,1,6,6], "type": "door", "notes": "future entry" }
    ],
    "notes": [ "Preview generated" ],
    "validationHints": [ "Walls may cross token area; adjust endpoints" ],
    "previewOnly": true
  }

Notes
- All coordinates are grid-aligned integers.
- Unknown fields from provider can be ignored by the client.
- If previewOnly is true, apply is disabled until user explicitly enables it.

5) api-contract.md
Cloud AI Endpoint Contract (example)

Endpoint
- POST https://api.youraihost.com/ai/map-prep

Headers
- Authorization: Bearer <apiToken>
- Content-Type: application/json

Request body (see data-contracts.md)
- {
  "scene": { "id": "...", "name": "..." },
  "gridSize": 32,
  "walls": [...],
  "tokens": [...],
  "promptTemplate": "...",
  "providerMetadata": { "providerName": "...", "version": "..." },
  "previewOnly": true
  }

Response
- 200 OK
  - {
      "walls": [...],
      "notes": ["Preview generated"],
      "validationHints": [...],
      "previewOnly": true
    }
- 4xx/5xx responses
  - { "error": "invalid_payload", "message": "..." }
  - { "error": "auth_failed", "message": "Invalid API token" }

Security and Privacy
- Use HTTPS; support short-lived tokens
- Minimize data; avoid sending unrelated scene data unless required
- Log access on the server side; provide per-request trace IDs

6) onboarding.md
Onboarding for WallCraft AI Contributors

Overview
- This document helps new contributors get up to speed on the WallCraft AI MVP project.

Getting started
- Prerequisites: FoundryVTT v13.0.351, node environment for building modules, access to cloud AI endpoint
- Repository layout: modules/wallcraft-ai/ with module.json and src/
- Key files to know:
  - module.json: module manifest
  - src/AIPrep.js: main module entry
  - src/AIEndpoint.js: HTTP client for cloud AI
  - src/PreviewLayer.js: canvas overlay logic
  - src/SettingsPanel.js: UI to configure endpoint/token/provider
  - src/UIFlow.js: dialog and adjustment UI

Development workflow
- Plan first: use agents.md to outline tasks
- Implement in small, testable increments
- Use non-destructive previews first; require explicit apply
- Write minimal tests or manual checks for payload shaping and wall conversion

Conventions
- Naming: consistent with FoundryVTT APIs (Wall, Door, Window, Scene)
- Data models: grid-aligned coordinates, tokens as bounding boxes
- Logging: messages go to chat or a dedicated journal entry

Testing and validation
- Manual test plan: create a sample scene, run AI Prep, verify preview, adjust, apply, verify persistence
- Edge cases: empty AI response, missing fields, invalid coordinates

Deployment and updates
- Document how to deploy updates to cloud endpoint if users host their own
- Provide migration notes for API changes (backward compatibility guidance)

7) glossary.md
WallCraft AI Glossary

- FoundryVTT: The virtual tabletop platform being extended.
- Scene: A map/workspace in FoundryVTT where walls, tokens, and other elements live.
- Wall: A linear obstacle segment; may be solid, a door, or a window.
- Door/Window: Wall segments with special types; may require swing/hinge data later.
- GridSize: The pixel size of a single tile on the scene grid.
- Preview: A non-destructive overlay showing AI-suggested walls before applying them.
- MVP: Minimum Viable Product.
- API Token: Secret used to authorize requests to the cloud AI endpoint.

8) quick-start.md
WallCraft AI Quick Start (MVP)

What you’ll get
- A cloud-driven FoundryVTT MVP to generate walls (including doors/windows) for the current scene.
- Non-destructive preview with manual adjustments before applying.

Setup
- Install FoundryVTT module (WallCraft AI) for FoundryVTT v13.0.351
- Configure cloud endpoint URL and API token in Settings
- Ensure the cloud AI endpoint is reachable via HTTPS

How to use
- In FoundryVTT, open a scene and click the WallCraft AI Prep button in the Scene toolbar
- The module collects scene data and sends a fixed prompt to the cloud AI
- See a translucent preview of AI-generated walls
- Use the adjustment panel to tweak endpoints or types if needed
- Click Apply to persist walls to the scene
- Review chat/journal log for traceability

Notes
- Batching and multi-scene processing are not part of MVP; plan for future sprints if you want to scale.
- Security: only necessary scene data is sent; token remains with you.

Next steps
- If you’d like, I can generate concrete starter patches (module.json + a minimal AIPrep.js skeleton and the SettingsPanel), plus the exact payload shapes ready to patch into your repo. I can also tailor naming and endpoint paths to your preferred conventions.

9) structure.md
WallCraft AI – Default File Structure

- /modules/wallcraft-ai/
  - module.json
  - /src/
    - AIPrep.js
    - AIEndpoint.js
    - PreviewLayer.js
    - SettingsPanel.js
    - UIFlow.js
  - /agents.md
  - /data-contracts.md
  - /api-contract.md
  - /onboarding.md
  - /glossary.md
  - /quick-start.md

This structure keeps the core module logic separated from the documentation and keeps the docs versioned with the module code.