Jamie/WallCraft-AI
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
WallCraft-AI/agents.md
Jamie Miller 34da1bc90b Add WallCraft AI MVP scaffolding and documentation
2026-02-06 07:48:40 +00:00

8.7 KiB
Raw Permalink Blame History

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
  1. 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.
  1. api-contract.md Cloud AI Endpoint Contract (example)

Endpoint

Headers

  • Authorization: Bearer
  • 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
  1. 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)
  1. 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.
  1. 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.
  1. 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.

Reference in New Issue View Git Blame Copy Permalink