# Effortless > Agnostic, AI-driven project-management framework: an MCP server + Skills with a git-friendly JSON database, OPAL phase workflow, an autonomous sub-agent delegation loop, anti-drift guardrails, and SecondBrain memory symbiosis. - **Type:** MCP server - **Install:** `agentstack add mcp-arborithmdev-effortless` - **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior - **Seller:** [ArboRithmDev](https://agentstack.voostack.com/s/arborithmdev) - **Installs:** 0 - **Category:** [Databases](https://agentstack.voostack.com/c/databases) - **Latest version:** 0.1.0 - **License:** Apache-2.0 - **Upstream author:** [ArboRithmDev](https://github.com/ArboRithmDev) - **Source:** https://github.com/ArboRithmDev/Effortless ## Install ```sh agentstack add mcp-arborithmdev-effortless ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About 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 **O**bserve → **P**osition → **A**rticulate → **L**aunch → **E**xecute, 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](https://github.com/SI-GMT/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. ```bash 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`](https://github.com/astral-sh/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 ```bash 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](https://github.com/ArboRithmDev) - **Source:** [ArboRithmDev/Effortless](https://github.com/ArboRithmDev/Effortless) - **License:** Apache-2.0 Install and usage instructions live in the source repository linked above. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** no - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** no - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: passed — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/mcp-arborithmdev-effortless - Seller: https://agentstack.voostack.com/s/arborithmdev - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.