Skip to content

Update README, LLM setup guide, and bundled wt skill for orchestration workflows #16

Description

@pkudinov

Parent: #11

Implementation dependencies:

Goal

Update all user-facing and agent-facing guidance together after the underlying
contracts land. This is intentionally one documentation issue so configuration,
CLI examples, automation guidance, and the bundled /wt skill cannot drift
apart.

README updates

Product positioning and requirements

  • Describe databases as an optional isolation capability rather than a global
    prerequisite.
  • Make the PostgreSQL requirement conditional on managed template-cloning mode.
  • Explain the three database states represented by an allocation: managed,
    logical-name-only, and absent.
  • State what new, setup, remove, prune, and doctor do in each state.

Configuration examples

  • Preserve and verify the existing local Postgres template-cloning example.
  • Add a ports + env-only example that has no local database or DATABASE_URL.
  • Add a cloud/pre-provisioned database example that disables provisioning but
    derives a per-slot logical DB name for the database env patch.
  • Document validation behavior for {{dbName}} and database patches when no
    logical name is configured.

Multi-service cross-wiring

  • Add one complete example with at least a frontend and API service.
  • Show the API's PORT using a port patch.
  • Show the frontend's API_BASE_URL using a url patch targeting the API
    service, proving both values resolve to the same allocated port.
  • Include the resulting env values for a concrete slot.

Concurrent orchestration

JSON contract

  • Document the schema version and compatibility policy from Define a stable, versioned JSON contract for orchestration #15.
  • Provide complete success and error examples for new --json.
  • Provide a complete list --json example with resolved ports.
  • State that stdout contains the JSON document and diagnostics go to stderr.

Setup Guide for LLM Agents

  • Make database discovery conditional instead of assuming every project has a
    Postgres DATABASE_URL.
  • Add an explicit decision step: managed local Postgres, externally managed
    database with logical per-slot naming, or no database integration.
  • Teach agents to generate the implemented configuration shape for each mode.
  • Keep port and URL discovery service-aware so cross-service URLs remain
    self-consistent.
  • Add mode-appropriate smoke tests that do not create or drop a database in
    unmanaged mode.
  • Teach agents to use the versioned JSON fields rather than scraping terminal
    output.

Bundled skills/wt/SKILL.md

Acceptance criteria

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentation

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions