devilop

Read CONCEPT.md, PROJECT_STATE.md and docs/reference.md before changing behavior. CONCEPT.md records requirements in order; the latest requirement wins. PROJECT_STATE.md is the current handoff. Keep this file concise and update the handoff after substantial work.

Product rules

devilop helps people build their own product with an agent, from an idea and first-user testing toward revenue and the need for a team. The map is the main workspace: product structure and visible user flows. One local app lists projects and stores its own maps next to the program. Four nesting levels: Concept and Mechanics for people who do not program; Technical holds source references, while Code describes each method's detailed behavior in plain language without code syntax or identifiers. Apply this when analysing/building maps; do not rewrite old maps without a request. Double-click dives into a block; a slider selects depth. No in-app conversation: reply to the person in their agent client. Human map edits are handed over only after “Finish edits”; proposal decisions are immediate. Unapproved logic changes use propose, with the person accepting or rejecting. Do not ask again for actions already authorized by the person.

Blocks may carry requirements: the person's freeform wishes, separate from current behavior. Preserve their wording at every depth and omitted values on updates; act after Finish edits. Never erase or mark requests done automatically.

During analysis/building, bind user-visible blocks to their actual local app page, region and prepared state using view; do not invent screens for internal work or rewrite old maps. viewEdits are semantic drafts, held until Finish edits. Work from the immutable submitted package, never from newer unfinished values. The external agent applies it to source and checks the result; broker/runner completion removes only matching id/content versions on the same view and node incarnation. Preserve concurrent drafts and clear drafts explicitly before rebinding. Named states need an app handler. Reading a package is not completion. Native permission questions require a real human answer; lost leases and uncertain source changes require reconciliation before another writer starts. Connect the requesting chat with devilop_connect / current connect; never create a new agent or native session by default. Codex uses its native current-thread queue, Claude Code uses an explicitly enabled channel in the same running CLI session, and Cursor receives only while its bounded MCP receive call is pending. Generic MCP/hooks and a queued notification do not prove idle wakeup or receipt. Check the exact connection and report limitations honestly. Use Codex's native-shell CLI for its queue; Claude channel delivery requires its receiving MCP connection, and Cursor requires its active MCP receive. Merely passing --client claude|cursor to CLI does not enable those transports. An enabled native queue/channel offers every sealed queued package independently of older work; Cursor still needs a pending receive. Receipt is separate from FIFO source execution. If receive returns busy, acknowledge the notice and explain blockedBy; never silently discard it, cancel an older package or renew its writer through notice traffic. Use devilop_receive for the immutable assignment and devilop_result to report or complete it. The private broker owns session credentials, leases and the single source writer; preserve executionId, batchId and payloadHash. Completion needs actual checks and exact applied drafts. Return scoped descriptions/marks in result.blocks so newer human fields survive. Never manually remove submitted drafts. Stop on lost ownership or uncertain source work. The optional separately managed runner owns its own native session; only when the person chooses that mode, its model returns the supplied verified result instead of also invoking lifecycle tools. Onboarding stays in the requesting chat; use CLI now if MCP tools are absent. A separate managed agent is optional, only at the person's explicit choice, never a required final setup step. Keep setup/checks quiet: hidden servers, isolated headless verification, no visible windows or screen navigation in the person's live map. Do not use show for routine progress. Adding bindings or agent focus must not open or switch application screens. Promise automatic delivery only when it is verified for this exact chat; report missing client integration honestly. Keep native approvals with the person. Closed or timed-out receives are not listening; past contact is tooltip history, never a current connection. Do not substitute a scheduled chat automation for client delivery. An MCP connection without a native chat id is a separate, opaque identity. For Codex native-queue work, use the notice's CLI receive/report/complete commands through that chat's native shell consistently; do not switch to an unverified MCP connection. Native Stop hooks cannot identify opaque MCP assignments safely. Immediate fencing requires cancellation of their owned MCP operation or an explicit disconnect; otherwise missing liveness fences the assignment after its five-minute liveness window on the next broker check (normally every ten seconds). Never guess a mapping or reuse another connection's credentials to hide this limitation. Native Codex delivery into the exact chat is verified in this checkout, including receipt while older work blocks execution. Real-client source modification/completion remains unverified; Claude/Cursor native acceptance is also unverified. Controlled demos and isolated integration tests are separate evidence. Keep those claims distinct.

Keep the current quiet monochrome ASCII interface: short functional labels, system monospace, neutral controls and muted red failure marks, fonts at least 12px, no slogans or repeated explanatory panels. The app and agent-facing material are English; the UI also supports Russian. Write map content and user replies in the person's language. Existing code identifiers stay unchanged when translating prose.

Development

• Node.js 22+, native ES modules, no external runtime dependencies, no build step. Preserve one-click startup: devilop.cmd / devilop.command → node devilop.mjs open; direct node server.mjs must also work.
• Before editing inspect Git status; preserve unfinished user changes. Do not commit or push unless requested.
• Runtime data is .devilop/, never in connected project folders. Do not edit it while a server is running. Keep keys, .env, machine settings and runtime data out of Git. Previous data folder names remain only for migration.
• Read the modules involved. Geometry in public/app.js and src/layout.mjs must agree. Stepwise builds use the local model to compute their final layout; keep it deterministic.
• Graph operations, proposals and marks are pure functions in src/model.mjs. Only server proposal code sets proposed flags. Synchronize mark names in CLI and server context.
• Level names/rules occur in src/levels.mjs, public/app.js, src/agent-guide.md and server context. Update them together. Guide templates use {{url}}, {{command}}, {{readme}} and {{remote}} placeholders.
• Agent tools are defined once in src/tools.mjs and shared by MCP, tools/call and the local-model agent. Commands and the devilop_* tool names must agree. The local-model agent reads project files and maintains maps, not code; its filtered tool set excludes current-chat execution/lifecycle, batch mutation and long waits. Do not restore those tools merely to make every client list identical.
• Mutations require expectedRevision. On 409 reread and merge; do not overwrite blindly. Only proposal decisions and check marks have the existing markNow exception. Keep atomic writes and single-process data locking.
• VM access is restricted to local network interfaces and authenticated machine keys. Never bind to 0.0.0.0. The host token must not go over the network. Only the person approves access in the host UI. Projects on different machines have separate folder namespaces; the host does not inspect VM project paths.
• Hooks must exit quietly with code 0 on errors. The hub never runs arbitrary check commands: the agent runs check. Health reports only locations of possible secrets, never their contents; never open .env, keys or certificates.

Codex workflow

node devilop.mjs setup --install --hooks configures this project's MCP server and hooks. It merges devilop tables in .codex/config.toml and owned entries in .codex/hooks.json; it must preserve other settings. Keep machine-specific files out of version control; the Codex installer does not add ignore rules. A future trusted Codex session loads devilop_* tools. CLI remains available in the current session; use --actor codex when needed. Claude/Cursor use setup --agent claude|cursor --install --hooks and project-local settings too. Claude channel consent is a separate native per-session decision; setup never grants it or launches another session. Channel support is a research preview and may be restricted by organization policy. Optional hooks are printed by setup --agent codex; file tracking also works through watch or touch/fresh.

If devilop is already running, read http://127.0.0.1:4317/agent or node devilop.mjs guide, find this repository's project and read its context before updating its map. Check changes at the start of each step. For interactive waits, use bounded calls (MCP defaults to 30 seconds). Show activity with doing, update blocks whose behavior changed, mark checks, and clear activity when done. For submitted work, return final descriptions/marks through the owning current-chat broker or optional runner instead of writing them ahead of completion; doing --done is not a package receipt. Use devilop_current_exec for long owned checks, under native permissions, to keep the lease live only while the local command actually runs. The hub never executes commands. Do not launch an endless model wait after the requested task is complete; a supported active-receive workflow uses bounded calls and ends as not listening. Stages and their task UI are withdrawn pending redesign. Do not create a stage plan or require stage-based work. Keep existing stage/task data; explicit legacy commands remain for compatibility. Native plans report activity only. Clear activity when stopping and mark checks only after verifying the result.

Verification

Run node --test test/*.test.mjs for model, storage, API, CLI and MCP changes. Tests must use temporary data and ports, never the real .devilop or port 4317. UI changes require a browser check; existing Chrome tests use an isolated profile and skip if Chrome is absent. Do not add tests that only repeat the implementation. Report the checks actually run, unresolved failures and skipped coverage. No package installation is needed for normal work.