Choosing your setup
Before creating or adopting a project, two choices shape how Effortless works with you: how the agent moves forward (the work mode) and where the code lives (the module layout). Both can change later, but setting them right at the start saves detours.
A third point matters just as much: where you start your agent. The best experience comes from a command-line agent opened at the project root — see Working at your best.
The work mode
| Mode | The agent | The engine | For whom |
|---|---|---|---|
| Full | moves on its own, with no intermediate validation | blocks nothing | you know Effortless and trust your agent |
| Semi-auto | proposes; you validate the key milestones | disables its execution tools: delivery, code regrouping, autonomous loop, team loop | you want to stay in control of what runs |
| Tutored | moves step by step, explains and confirms each step | blocks nothing: it is an instruction for the agent | you are discovering Effortless or the OPALE method |
A created or adopted project starts in Full. Change the mode at any time in the project settings, or through the agent with effortless_mode_set.
Semi-auto and adoption
In semi-auto, the Group code step of adopting an existing project is refused: it moves files. Adopt the project in Full or Tutored, then switch to semi-auto.
The code layout
Effortless separates steering from code. Steering (effortless.json, .effortless/, blueprints/) always lives at the project root. Code is declared as modules ("stacks"): each has an id, a location, its languages and its development standards. The Modules screen shows them all.
One repository, code at the root
The simplest case. With no declaration, the project has one implicit module, default, covering the root. Nothing to do.
Several modules inside the project
A single repository with several parts — an app, an API, documentation. Each module lives in codebase/<module>/. Declare it from the creation assistant (Stack step), from Preferences › Stack model, or through the agent with effortless_stack_add. Adopting an existing project moves the root code into codebase/<module>/.
An external module, with its own repository
A module's code lives outside the project, in another git repository you also develop. Declare it with its path and git: true:
« Declare the api module, whose code is in ../billing-api, with its own git repository. »
Effortless then follows that repository like the project's own: drift is read there, and the anti-drift hook is installed there too when you install it.
Shared sources, on the side
A module's code lives in a repository you share — a library common to several of your projects, a third-party repository — that you do not want to instrument. Declare it with its path, without git: true:
« Declare the core module, whose shared code is in ../common-core, without tracking it. »
Effortless then works alongside those sources: it installs no hook there and commits nothing there. In return, drift is not watched there. effortless_stack_list marks this module NON SUIVIE (not tracked): that is intended, the label simply reminds you of the choice.
The anti-drift hook: when, and where
The anti-drift pre-commit hook refuses a code commit when no task is in progress. It is never installed by default: neither at creation nor at adoption.
- You install it from the Drift screen (Install the pre-commit hook) or through the agent with
effortless_drift_hook_install. - It goes on the project repository, and on every module declared with
git: true. - It never goes on shared sources (an external module without
git: true). - It never replaces a pre-commit hook that is not Effortless's: the installation is refused, and the refusal names the file.
Which choice for which case
| Your situation | Mode | Layout |
|---|---|---|
| You are discovering Effortless on a small project | Tutored | one repository |
| You want to validate what runs | Semi-auto | depending on the project |
| One repository with an app, an API, documentation | Full or Semi-auto | modules in codebase/ |
| The code is spread over several repositories you develop | Full or Semi-auto | external modules with git: true |
| You rely on a common library you must neither modify nor instrument | your call | shared sources (without git: true) |
| An existing repository whose structure must stay as it is | your call | create the project without adoption, then declare the modules where they are, with path |