WTI-AI bridges the gap between a “smart internet agent” and a local, project-aware IDE by turning vague ideas into an explicit, reviewable workflow: clarify intent → produce a plan → create durable artifacts → implement safely → verify.
The core metaphor is a multi-agent symphony: a set of specialized AI “voices” that contribute their parts, while a Conductor orchestrates the work into a coherent chorus of user-approved workflow automation.
Start here:
AGENTS.md— operating rules + approval gatesPURPOSE.md— repo routerdocs/PURPOSE.md— docs taxonomy routerdocs/theia/WTI_IDE_WORKFLOW.md— canonical IDE workflow
- What exists now: a Theia browser IDE workflow under
ide/, env-file secret loading viaWTI_AI_ENV_FILES, and a docs system with explicit trust routing (status: CERTIFIEDis the only authoritative truth). - What’s planned: a Quarkus
conductorcontrol plane, MCP tool services (least-privilege filesystem + ripgrep), and Step Mode (plan → approve → execute) to scale from “careful human oversight” toward “safe automation”.
Using AI effectively requires careful, focused expression of intent. WTI-AI is designed to make that practical inside your real repository:
- You describe a goal (often ambiguous).
- The system helps you refine it into an actionable plan.
- Agents produce and maintain durable artifacts (goals/specs/plans/ADRs/tests) so progress compounds instead of resetting each chat.
- You approve changes at the right level:
- early: more docs/spec changes, fewer code changes
- later: more code diffs, fewer doc diffs
- Over time, as artifacts and behavior become trustworthy, you automate more of the workflow—with less oversight and more design intervention.
- When a feature's requirements change or something breaks, the stored decisions and the reasons for making them become invaluable.
- When a reviewer, human or otherwise, points out a problem, new goals and features can be started, spec's updated and tests entirely automated.
A typical WTI feature matures through stages. The key idea is deliberate progression from intent → clarity → implementation → verification.
Recommended lifecycle (artifacts):
- Triage → capture the intent as a goal (
docs/goals/*) - Spec → define behavior and acceptance criteria (
docs/specs/*) - ADR (if needed) → record architecture decisions (
docs/adr/*) - Plan → sequence work and gates (
docs/plans/*) or a task context - Implement → small, reviewable diffs
- Verify → tests/diagnostics (run only with approval gates)
- Certify docs → promote key docs to
status: CERTIFIEDwhen reviewed
Note: there are triage-level guidance docs (non-authoritative):
docs/0_triage/workflow/feature-lifecycle-and-maturity.md(status: UNREVIEWED)docs/0_triage/workflow/role-based-reading-and-trust.md(status: UNREVIEWED)
In the intended model:
- The Conductor listens to your request, asks specialist agents for help, and proposes a structured plan.
- As you refine your request, agents improve the recorded spec and plan, with explicit approval.
- As the feature matures, your approvals shift from “lots of documentation diffs” toward “mostly code + tests”.
- The end state is repeatable: tests pass, the feature is complete, and docs are upgraded to certified truth.
These are the intended “personalities” in the platform model. Some are already reflected in how work is performed in this repo (especially the rules), even if the full multi-agent runtime is not yet implemented.
- Conductor (planned): orchestrator and state machine; owns dispatch, transitions, and approval gates.
- Scout / Navigator: read-only context retrieval; finds relevant routers/docs/code.
- Planner: produces a plan/task context with acceptance criteria.
- Coder: proposes code/doc changes as small diffs.
- Reviewer / Validator: checks diffs against rules, acceptance criteria, and repo reality.
- Tester: defines and runs verification strategy (tests/diagnostics) when approved.
- Compliance / Safety (optional): enforces trust rules and prevents secret leakage.
- Guru (internet-connected; unable to write repo content):
- Q&A only for general knowledge.
- Never receives repo secrets.
- Never executes tasks.
- Must not be used to process or summarize private repo content.
A Theia browser IDE workspace is built and run from the standalone ide/ pnpm workspace.
- Canonical workflow:
docs/theia/WTI_IDE_WORKFLOW.md - Helper scripts live in
ide/(e.g.build.sh,run.sh,watch.sh,test.sh,clean.sh).
ide/run.sh supports loading secrets from a directory pointed to by WTI_AI_ENV_FILES.
Behavior (as implemented):
- For each file in the directory:
- env var name = file basename
- env var value = file contents
Source of truth: ide/run.sh
This repo treats documentation as a first-class system.
- Authority is determined by frontmatter:
- Only documents with
status: CERTIFIEDare authoritative. - Folder location is not authoritative (including
docs/5_certified/).
- Only documents with
- Taxonomy hubs:
docs/README.md— taxonomy + status header rulesdocs/PURPOSE.md— router for doc areas
- Operating rules and safety gates:
These items are referenced in docs and plans, but are not fully implemented in this repo yet.
A Quarkus service intended to own planning, step mode, and multi-agent orchestration.
- Roadmap context:
MASTER_PLAN.md - Certified term definition:
docs/5_certified/WTI_AI_GLOSSARY.md
Planned MCP services provide tools like rg and filesystem reads with least-privilege boundaries.
- Roadmap context:
MASTER_PLAN.md - Certified term definition:
docs/5_certified/WTI_AI_GLOSSARY.md
Default safety model (planned): the system produces a plan, a human approves it, then the system executes bounded steps.
- Safety/approval gating rules today:
AGENTS.md - Roadmap context:
MASTER_PLAN.md
Planned: curate durable artifacts (plans, decisions, outcomes) and re-use them across loop iterations to prevent low-signal repetition.
- Goal doc:
docs/goals/conductor-lisa-loops.md
Canonical instructions live in docs/theia/WTI_IDE_WORKFLOW.md. This section is the minimum.
- Node.js 20.x (see
ide/.nvmrc) corepackenabled (the scripts handle this best-effort)
cd ide
./build.sh
./run.sh- Default port:
1771 - Override:
WTI_IDE_PORT=1771(or any port)
Create a private directory of secret files:
mkdir -p -m 700 ~/.wti/.secure/envPut secrets in files, one per environment variable.
Example for OPENAI_API_KEY:
printf '%s' "$OPENAI_API_KEY" > ~/.wti/.secure/env/OPENAI_API_KEY
chmod 600 ~/.wti/.secure/env/OPENAI_API_KEYPoint the IDE runner at that directory (e.g., in your shell rc):
export WTI_AI_ENV_FILES=~/.wti/.secure/envWTI’s intended orchestration loop is a deliberate state machine—LiSA loops—to prevent accidental, repetitive, low-signal “Ralph loops”.
Phases:
- Locate — identify the correct sources of truth (routers, certified docs, code).
- Investigate — gather evidence and constraints; confirm repo reality.
- Solve — implement bounded changes with explicit steps and artifacts.
- Assess — verify outcomes (tests/diagnostics), update docs, decide next transition.
Design goal reference:
docs/features/ is a legacy area (see docs/PURPOSE.md). A lightweight, manual approach is to generate a README table by prompting an agent to summarize each doc.
Copy/paste this into your IDE chat (or ChatGPT) to generate a Markdown table:
/features-table
Read: docs/features/* (only the first ~200 lines of each file unless it’s shorter).
Output: a single Markdown table with columns:
- Feature
- Status (from frontmatter status: ...)
- Goal (1 sentence)
- Lifecycle/Maturity (from frontmatter if present; else blank)
- Links (relative links)
Rules:
- Do not invent status/lifecycle/maturity if not present.
- If a doc is missing frontmatter, mark Status as "(missing)".
- Keep Goal factual; if unclear, write "(unclear)".
Planned follow-up: add a small script to generate/refresh this table automatically.
- Certified glossary:
docs/5_certified/WTI_AI_GLOSSARY.md - Infra/product roadmap context:
MASTER_PLAN.md