Add WallCraft AI MVP scaffolding and documentation
This commit is contained in:
Jamie Miller
236
agents.md
Normal file
236
agents.md
Normal file
@@ -0,0 +1,236 @@
|
||||
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.
|
||||
Reference in New Issue
Block a user