Effortless

Effortless

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.

[](LICENSE) [](https://www.python.org/) [](https://modelcontextprotocol.io/) [](docs/tool-reference.md) [](https://github.com/ArboRithmDev/Effortless/releases)

The sloth hangs, eyes closed, and the work still gets done.

---

What is Effortless?

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.

---

Why use it?

• 🚦 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.

---

How it works

                ┌───────────────────────────────┐
   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 under blueprints/ 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.

---

Quick start

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.ps1

The 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.

Open the framing vault in Obsidian (recommended)

effortless_init deploys blueprints/ as a ready-to-use Obsidian vault — config, dashboards, a status-colorised document graph, three bundled plugins.

1. Obsidian → Open folder as vault → select blueprints/.
2. At the prompt, choose "Trust author and enable plugins".
3. Install Dataview to render the dashboard tables (optionally Extended Graph for node colouring).

Full walkthrough: [blueprints/9-Guide-Obsidian.md](blueprints/9-Guide-Obsidian.md).

---

The workflow (OPALE)

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.

---

The fractal model (Epics → Stories → tasks)

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.

---

What you can do

All 76 capabilities are MCP tools. The [full tool reference → docs/tool-reference.md](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 |

---

The dashboard

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.

---

Architecture & storage

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-/
│       ├── epic.json
│       └── stories/NNN-Story-/
│           ├── 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-/NNN-Story-/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// is scaffolded incrementally (empty containers with .gitkeep, at effortless_init and at each effortless_stack_add) — never for an external stack (a path outside the project). Effortless never moves or rewrites existing source code on its own; relocating code into codebase// is always an opt-in action (effortless_codebase_relocate). The container's name is configurable via settings.codebase.dir_name in effortless.json (default "codebase"; see [tool-reference.md](docs/tool-reference.md) for the v1 limits on renaming it after the fact).

---

Multi-client support

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.

---

Development

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.

---

License

Licensed under the Apache License 2.0 — see [LICENSE](LICENSE). Copyright 2026 ArboRithmDev.

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: ArboRithmDev
• Source: ArboRithmDev/Effortless
• License: Apache-2.0

Install and usage instructions live in the source repository linked above.