Code and stacks

A stack (a module) is a part of your code: its folder under codebase/, its model, its languages. You come to this path to declare a module, choose a model, scaffold the starting code, build, run the tests, tidy up, or bring the work of a worktree back into the repository.

What you ask the agent

💬 You ask your agent

« Which stack models exist, and what does the rust model contain? »

→ The agent callseffortless_stack_model_list

💬 You ask your agent

« Add an api module with the node model. »

→ The agent callseffortless_stack_add

• id = api
• scaffold_template = node

💬 You ask your agent

« Which stacks are declared in this project? »

→ The agent callseffortless_stack_list

💬 You ask your agent

« The api module is in Rust and TypeScript: declare it. »

→ The agent callseffortless_stack_declare_languages

• stack_id = api
• languages = [{"id":"rust"},{"id":"typescript"}]

💬 You ask your agent

« Which command runs the tests of the api module? And the lint? »

→ The agent callseffortless_stack_cycle

• stack_id = api
• kind = test

💬 You ask your agent

« Build the desktop module. »

→ The agent callseffortless_stack_build

• stack_id = desktop

💬 You ask your agent

« Show me what the housekeeping would do on desktop, without deleting anything. »

→ The agent callseffortless_stack_housekeeping

• stack_id = desktop
• apply = false

💬 You ask your agent

« How much do the desktop module's build folders weigh? Measure them. »

→ The agent callseffortless_build_volume

• stack_id = desktop
• measure = true

💬 You ask your agent

« What would resetting desktop's builds do? Don't run anything. »

→ The agent callseffortless_build_reset

• stack_id = desktop
• confirm = false

💬 You ask your agent

« Switch the desktop module to full debug info for its own code. »

→ The agent callseffortless_build_debug

• stack_id = desktop
• project = full

💬 You ask your agent

« Move the code lying at the root under codebase/. »

→ The agent callseffortless_codebase_relocate

• dry_run = false

💬 You ask your agent

« Bring the work of the ../wt-api worktree back into the repository, with pnpm test as the bar. »

→ The agent callseffortless_worktree_reintegrate

• worktree_path = ../wt-api
• bar = {"test":"pnpm test"}

What the agent does

Choose a stack model

1. effortless_stack_model_list lists the models: those shipped with Effortless (rust, node, python, generic, tauri, react, tauri-react, tauri-react-tailwind) and those in the project store. It works before any project exists; the "Get started" path uses it too.
2. effortless_stack_model_show with model_id details a model: its variables, its build strategy and its cycle commands (test, lint, run).

Declare a module and its languages

1. effortless_stack_add with id. It declares the stack (default path codebase/<id>/), scaffolds the folder and applies the model given by scaffold_template, with the variables from vars. A path outside the project makes it an external module: git: true if that module has its own repository, to be tracked like the project's (drift, hook); without git: true, these are shared sources, left on the side — see Choosing your setup.
2. The languages are pre-filled by the model; languages passed in the call replaces them. The standards of the declared languages are written to .ai/ndd/; those that are missing are named in the response.
3. effortless_stack_declare_languages then corrects the languages: the new declaration replaces the previous one, it does not merge. An empty list says "no standard".
4. effortless_stack_list reads the declared stacks back.

Scaffold

1. effortless_scaffold_list lists the templates available in the project store.
2. effortless_scaffold_apply with template_id and target_dir writes the template's files into a folder. Files already present are left intact and reported as skipped. effortless_scaffold_apply_project does the same at the project root.
3. To bring your own template: effortless_scaffold_format returns the schema of a scaffold manifest, then effortless_scaffold_import with path imports it into the project store after validation.

Build and run the cycle

1. effortless_stack_build with stack_id runs the model's build command, from the stack's folder, and returns the status, the artifacts and the logs.
2. effortless_stack_cycle with stack_id and kind (test, lint or run) returns the resolved command. It does not run it: the agent runs it afterwards.

Tidy up

effortless_stack_housekeeping reports what the housekeeping policy declared in languages[].housekeeping would purge: what, how large, for which language. Without apply, it deletes nothing. The agent passes apply: true only after your agreement. stack_id limits the report to one stack.

Measure and slim down builds

effortless_build_volume measures, module by module, how much the build folders weigh: those the stack declares and those the build tool tagged (CACHEDIR.TAG), never counting the same byte twice. Without measure, it returns the last measurement and its date. When a module goes over the project threshold (settings.build_volume.threshold, 10 GB by default), the resume screen flags it.

effortless_build_reset resets a module's builds by running the command its language declares (for example cargo clean). It always starts with a simulation: command, folders, size. The agent passes confirm: true only after your agreement; the next build will be a full one.

effortless_build_debug reads or sets the amount of debug information in dev builds — none, lines or full — for the module's own code (project) and, when the language allows it, for its dependencies. The level becomes environment variables set on the commands Effortless runs: your files are never rewritten. For Rust, only the module's own code is adjustable; dependencies stay without debug info, as the model sets them.

Move the code under codebase/

effortless_codebase_relocate moves the code left at the root into codebase/<stack>/ (the default stack without stack_id). It starts with a preview (dry_run is true by default); the agent runs it for real (dry_run: false) after your agreement. In Semi-auto mode it is disabled and says so.

Reintegrate a worktree

effortless_worktree_reintegrate with worktree_path (or worktree_paths for a multi-repository project) and bar, the check bar: an object that maps test, lint, typecheck or build to a command. The verb first commits the worktree's pending files, measures the bar in the worktree, and merges only if everything is green. After a successful merge, the worktree and its branch are removed, unless keep_worktree: true. The verb never creates a worktree.

What you get

• Modules declared in effortless.json, folders under codebase/<id>/, language standards in .ai/ndd/.
• The Modules screen shows each stack: languages, model, standards, version, delivery. It is read-only; stacks are declared by the agent or when the workspace is created.
• For a reintegrated worktree: the work is merged into the repository, or nothing changed.

When the agent is refused

Situation	What the refusal says	What to do
Unknown stack (language declaration, housekeeping)	stack:unknown	List the stacks with effortless_stack_list.
Unknown stack (build, cycle)	stacks:stackNotFound	Same action: effortless_stack_list.
Stack id already taken, or empty	"stack id already exists" / "stack id required"	Pick another id.
Malformed languages	stack:languagesMalformed (the faulty entries are named)	Each language is an object { id, version, ndd }.
Standard source neither embedded nor git	stack:nddSourceRefused	Declare the source as embedded or git.
Stack without a model, for a build	"the stack has no model (scaffold_template)"	Declare the stack with a model.
Unknown cycle requested	stacks:cycleInvalid	kind is test, lint or run.
Template not found	create:templateNotFound	List the templates with effortless_scaffold_list.
Invalid imported manifest	"invalid manifest" with the list of errors	Fix the manifest using effortless_scaffold_format.
Imported model that declares a command to run	create:anchorUntrusted	Remove the anchor key from the manifest, or take a shipped model (effortless_stack_model_list).
Folder to reintegrate is not a git worktree	worktree:notAWorktree	Create the worktree first: the verb never creates one.
Worktree on no branch	worktree:detachedHead	Put the worktree back on a branch.
No worktree given	worktree:noWorktree	Pass worktree_path, or worktree_paths.
The bar goes red	worktree:barRed (the failing commands are named)	Fix in the worktree, then retry; nothing was reintegrated.
Untracked symbolic link in the worktree	worktree:untrackedSymlink	Ignore the link in .gitignore (pattern without a trailing slash) or remove it.
Merge conflict	worktree:mergeConflict (files named)	Resolve the conflict in the worktree and retry; the merge was cancelled.
Partial merge across several repositories	worktree:partialMerge	Fix the cause, then retry on the failing worktree only.