An agnostic, AI-driven project-management framework — an MCP server + Skills that let any LLM agent (or human) run a project through a rigorous, phase-gated workflow.
The sloth hangs, eyes closed, and the work still gets done.
Effortless turns a vague intention ("build X", "migrate Y") into a disciplined, auditable engineering process. It is language- and stack-agnostic — it manages how a project advances, not what it's built with.
Four ideas, one framework:
- OPALE phases — work flows through Observe → Position → Articulate → Launch → Execute, with a hard barrier between phases: you can't advance until the required documents exist and every blocking question is resolved.
- A fractal backlog — Epics → Stories → tasks, each level first-class, each Story carrying its own framing docs, decisions, questions and tasks.
- A git-friendly database — every entity is one JSON file under
.effortless/, with Markdown views rendered for humans and browsable as an Obsidian vault. Diff-able, merge-friendly, team-ready. - An MCP control surface — 76 tools an agent calls to drive the project: lifecycle, decisions, questions, tasks, an autonomous execution loop, anti-drift guardrails, a mediated Jira/Xray sync, a release pipeline and a live web dashboard.
Built on the storage/adapter philosophy of SecondBrain — and it integrates back into a SecondBrain memory vault.
- 🚦 Phase gates that actually block — no "we'll document it later"; the barrier is enforced before each transition, per Story.
- 🧩 Decisions, questions and tasks as versioned files — every ADR, open question and task is reviewable in a PR.
- 🤖 Autonomous loop with systematic delegation — the orchestrator handles the hard work and delegates mechanical tasks to fresh sub-agents, cutting tokens and wall-clock.
- 🛡️ Anti-drift guardrail — a pre-commit hook refuses commits that touch code with no active task.
- 🔄 Mediated Jira/Xray sync — Effortless plans the tracker ops; your agent executes them through its own Atlassian access; no credentials ever stored.
- 🚀 Release pipeline — a consent-gated pipe that bumps version, updates the README, commits/pushes, tags and publishes a GitHub/GitLab release.
- 🔌 One install, every CLI agent — auto-deploys to Claude Code, Codex, Mistral Vibe, GitHub Copilot CLI and Antigravity.
- 📊 Living cockpit dashboard — an animated React SPA (burn-up, OPALE track, drift ECG, Epic→Story drill-down, timeline, stats) backed by a JSON API.
┌───────────────────────────────┐
LLM agent ──▶│ Effortless MCP server │──▶ .effortless/ (JSON source of truth)
(Claude, │ 76 tools • OPALE state mach. │──▶ blueprints/ (Markdown views = Obsidian vault)
Codex, …) │ validation • anti-drift │──▶ SecondBrain (vault symbiosis)
└──────────────┬────────────────┘──▶ Jira / Xray (mediated, via the agent)
│
└──▶ /api/* ──▶ React dashboard
- Source of truth = the JSON DB in
.effortless/. Markdown underblueprints/is a generated, read-only rendering (carries a "do not edit" banner) that doubles as an Obsidian vault. - The server resolves the current project from its working directory and its own install location separately — so it works deployed onto any repo.
Requirements: Python 3.12+, git, and (optional, for the dashboard) Node.js.
git clone https://github.com/ArboRithmDev/Effortless.git
cd Effortless
./setup.sh # Windows: .\setup.ps1The setup script creates the Python venv and installs the MCP server (via uv), builds the dashboard (if npm is present), auto-deploys to every detected CLI agent, and installs the anti-drift hook.
Then reconnect the MCP server (e.g. /mcp → reconnect effortless in Claude Code) and start:
"Initialise Effortless in this repo and show me the status."
The agent calls effortless_init then effortless_status. You're in the Observe phase.
effortless_init deploys blueprints/ as a ready-to-use Obsidian vault — config, dashboards, a status-colorised document graph, three bundled plugins.
- Obsidian → Open folder as vault → select
blueprints/. - At the prompt, choose "Trust author and enable plugins".
- Install Dataview to render the dashboard tables (optionally Extended Graph for node colouring).
Full walkthrough: blueprints/9-Guide-Obsidian.md.
Each phase requires documents under the active Story's blueprints/ folder. The barrier checks that every required doc exists, has valid frontmatter for the phase, contains its mandatory sections, and has no unfilled placeholders — and that no blocking question is still open.
| Phase | Name | Produces |
|---|---|---|
| O | Observe | glossary, analysis of the existing, open-questions log (BQO) |
| P | Position | target architecture, decision register (ADR) |
| A | Articulate | functional & technical specs, API contract |
| L | Launch | action plan, task breakdown, acceptance/recette scenarios |
| E | Execute | implementation (driven by the autonomous loop) |
effortless_status tells you what's missing and whether you may advance. effortless_phase_next transitions only if the barrier is clear.
A project is a tree, and every level is first-class:
Project
├── questions (project-level BQO) effortless_bqo_ask / bqo_list
├── evolutions (recorded change requests) effortless_evolution_add
└── Epics effortless_epic_start / epic_complete
└── Stories effortless_story_start / story_complete
├── framing docs (00→07) effortless_cadrage_docs_scaffold
├── decisions (DEC-NN) effortless_decision_add
├── questions (Q-NN) effortless_question_ask / resolve
├── proposal gate effortless_proposal_add / validate / reject
└── tasks (TSK-NN) effortless_task_add / update / classify
Closure is bottom-up and enforced: a Story won't close while tasks are open or its framing is unwritten; an Epic won't close while Stories are open. Two graduation paths keep the backlog honest — a structural project question graduates into an Epic BQO; an evolution worth real work graduates into a fresh Epic.
All 76 capabilities are MCP tools. The full tool reference → docs/tool-reference.md groups them by functional flow, with example agent requests. In brief:
| Area | What it covers |
|---|---|
| Lifecycle & phase gates | init, status, phase transitions with the OPALE barrier |
| Epics & Stories | create/activate/close the fractal backlog, framing gate (opale/fix) |
| Decisions & questions | ADRs, Story- and project-level BQO, graduation |
| Evolutions & proposals | change requests, the proposal gate, draft Story decomposition |
| Tasks | create/move/classify + two-axis model routing (tier × effort) |
| Autonomous loop | task-picking state machine with a delegate / decompose / triage doctrine |
| Anti-drift | detect code changed with no active task; blocking pre-commit hook |
| Tracker sync | mediated Jira/Xray plan-and-ack, idempotent outbox, Jira-as-truth import |
| Release pipeline | consent-gated bump · README · commit/push · tag+release · delivery · retention |
| SecondBrain | non-destructive phase mirroring into your memory vault |
| Migration | bootstrap an existing repo; versioned schema upgrades with dry-run + .bak |
| Deployment & dashboard | multi-CLI deploy, launch the live web cockpit |
| Scaffolds & stacks | scaffold store, multi-stack declaration, feature registry |
effortless_web_ui_launch serves an animated React SPA (light/dark, sloth mascot) backed by JSON endpoints. A fixed header carries the project vitals; a left spine navigates eight auto-refreshing views, each scrolling in its own pane:
Cockpit (burn-up · OPALE track · momentum · drift ECG · what-needs-attention) · Parcours (Epic strip → Story detail board) · Cadrage (blueprints explorer + Markdown reader) · Decisions (ADR cards) · Timeline (git-wired milestones) · Stacks (per-stack git vitals & drift) · Stats (throughput, effort, cadence) · Help.
A ⌘/Ctrl-K command palette jumps to any view. The dashboard is read-only and degrades gracefully when the project is uninitialised or the API is unreachable.
your-project/
├── effortless.json # project config + OPALE workflow + tracker coupling
├── .effortless/ # git-friendly database (source of truth)
│ ├── state.json # current phase, active Epic/Story
│ ├── backlog.json # Epic/Story index
│ ├── tracker_outbox/NNNNNN.json # mediated tracker operations (played/pending)
│ └── epics/NNN-Epic-<Scope>/
│ ├── epic.json
│ └── stories/NNN-Story-<Scope>/
│ ├── story.json
│ ├── decisions/DEC-*.json
│ ├── questions/Q-*.json
│ └── tasks/TSK-*.json
├── blueprints/ # generated Markdown views — also an Obsidian vault
│ ├── .obsidian/ # deployed vault config (graph colours, plugins)
│ └── NNN-Epic-<Scope>/NNN-Story-<Scope>/00..07-*.md
└── codebase/ # application code, one container per stack
└── default/ # mono-stack default — e.g. codebase/api/, codebase/web-ui/ appear as stacks are added
- One file per entity → minimal merge conflicts in team mode.
- Markdown is generated from JSON on every mutation (with a "do not edit" banner) — the docs never drift from the data.
- Install vs. project are cleanly separated: framework code/venv/dashboard live in the install; project data is addressed by the agent's working directory — which is what makes Effortless deployable onto any repo.
codebase/<stack>/is scaffolded incrementally (empty containers with.gitkeep, ateffortless_initand at eacheffortless_stack_add) — never for an external stack (apathoutside the project). Effortless never moves or rewrites existing source code on its own; relocating code intocodebase/<stack>/is always an opt-in action (effortless_codebase_relocate). The container's name is configurable viasettings.codebase.dir_nameineffortless.json(default"codebase"; seetool-reference.mdfor the v1 limits on renaming it after the fact).
A single effortless_deploy (run by setup) registers the MCP server with every project-aware CLI agent it finds:
Claude Code · Codex · Mistral Vibe · GitHub Copilot CLI · Antigravity (Gemini).
GUI clients without a project working directory (e.g. Claude Desktop) are intentionally excluded — Effortless is project-scoped.
cd src/mcp-server
source .venv/bin/activate
pytest -q # run the test suite
effortless-mcp # run the MCP server directly (stdio)The repository dogfoods itself: it's managed by Effortless (see .effortless/), tracked in Jira through its own mediated sync, released through its own release pipeline, and protected by its own anti-drift hook.
Licensed under the Apache License 2.0 — see LICENSE. Copyright 2026 ArboRithmDev.