This is the first part of a series about why even the most powerful AI agents today need more than just access to your codebase.
They need access to the living state of the project: tasks, rules, decisions, notes, and workflow context.

In this article, I focus on the core problem. I won’t dive into architecture, Freeform boards, Git integration, or Vibeocus Lens yet — those will come in later parts.

AI is good at writing code, but weak at seeing the project

Modern AI coding assistants have become very good at writing code. Give them a prompt like this:

Fix coupon validation in the cart and add tests.

…and you’ll often get working code, tests, and a decent explanation. This has become normal.

However, in real development, a feature is almost never just one chat message. It comes with rich context:

• the task and its status
• priority and deadlines
• project rules
• previous architectural decisions
• release constraints
• related notes
• Definition of Done

AI handles the code part well, but it often fails to understand the surrounding workflow. This is where the main problem begins.

The developer becomes the integration layer

A typical flow looks like this: the developer copies information from a task into an AI chat, gets the result, then manually updates the task status, writes notes, creates follow-up tasks, and adds release comments.

The AI session and the project management system live in parallel universes. The developer is forced to act as a constant translator between them.

This is manageable when AI is used occasionally. When it becomes a daily tool, the constant manual bridging starts to hurt productivity.

A board shows the task, but not the full context

A Kanban board is great at visualizing workflow for humans. But an AI agent doesn’t live inside your head.

It doesn’t automatically know why a task is important, which rules apply, which decisions are still valid, or what “done” actually means.

Here’s what a task might look like as structured data:

{
  "id": 108,
  "title": "Fix coupon validation in the cart",
  "status": "in-progress",
  "priority": "high",
  "description": "Coupons must not apply to discounted products. Update the server-side validation and add unit tests.",
  "start_date": "2026-05-23",
  "due_date": "2026-05-27"
}

This is already much better than a plain prompt. But for high-quality work, the agent often also needs project rules, active decisions, related documents, and notes.

That’s why I’m not talking about just a better task tracker — I’m talking about a project layer.

The board remains a useful interface for the human. The project layer makes the working context available to the AI agent in a structured way.

Why Markdown and Obsidian did not fully solve this for me

Many developers have already tried to solve this problem with Markdown files, Obsidian, Logseq, or similar local knowledge bases.

I did that too.

This approach has real strengths:

• Markdown is easy to read;
• files are local;
• notes can be stored in Git;
• documents can be linked together;
• an AI agent can be given access to a folder with project context.

But over time, I ran into a limitation.

A folder of Markdown files is good at storing text, but it is not very good at expressing workflow state.

For example, it is hard for an agent to reliably understand:

• which task is active right now;
• which project rules are mandatory;
• which decisions are still active;
• which notes are drafts and which are part of project memory;
• where progress should be written;
• which actions can be performed and which should only be suggested;
• how a task, document, note, and code change are connected.

Markdown is still useful. But by itself, it is not a project layer for an AI agent.

An AI can read a file. That is not the same as receiving a structured answer: here is the project, here are the active tasks, here are the rules, here are the related decisions, here are the allowed tools, and here is where notes live.

I needed more than a set of files. I needed a layer that turns project context into data and actions an agent can understand.

What I mean by a project layer

A project layer is an intermediate layer between an AI session and the real state of the project.

It should not replace the code editor.
It should not replace Git.
It should not be another abstract board for the sake of having another board.
Its job is simpler: give the AI agent access to the project context that the developer usually keeps in their head.

For example:

• which projects exist;
• where the project code lives;
• where project notes live;
• which tasks are in progress;
• which rules must be followed;
• which decisions have already been made;
• which documents belong to the project;
• which tasks can be created after a session;
• which status update can be suggested after implementation.

In other words, the project layer does not answer only "how should this code be written?"

It also answers: "inside which project context should this code be written?"

That distinction matters.

Where MCP fits in

MCP, the Model Context Protocol, becomes interesting exactly here.

It gives AI clients a structured way to connect to external data and tools.

Instead of manually pasting task descriptions, project rules, and notes into a chat every time, an AI agent can ask a local MCP server for that context.

For example, before starting work, an agent could run something like this:

vibeocus_list_projects
vibeocus_list_tasks({ "project_id": 42, "status": "in-progress" })
vibeocus_get_project_rules({ "project_id": 42 })
vibeocus_list_project_decisions({ "project_id": 42, "status": "active" })

In a simplified way, this turns project state into an API for the AI agent.

Not a wall of text.
Not a random folder of files.
A set of clear requests and responses.

For example, a project rule might look like this:

- Validate input data with Zod.
- Cart business logic lives in `src/server/services/cart`.
- Route handlers must not contain business logic directly.
- Do not add new dependencies without approval.
- After TypeScript changes, run the linter and tests.

If the agent sees this rule before changing the code, it is less likely to put business logic in the wrong place or add an unnecessary dependency.

This does not make AI perfect.
But it gives it a much better starting context.

How this is implemented in Vibeocus

Vibeocus is my implementation of this kind of project layer. You can see it here →

It keeps the project state local and exposes it to AI tools through a dedicated MCP helper (vibeocus-mcp).

Inside Vibeocus, there are tasks, rules, decisions, notes, documents, relations between projects, and other parts of project memory.

For an AI agent, this is not just a UI. Through MCP, it can receive structured context and treat it as part of the development process.

For the human, it remains a normal workspace: you can view tasks on a board, in a list, or in a calendar, read notes, and control changes.

I do not want the agent to "take over" the project.

A good workflow looks different:

1. The developer selects or defines a task.
2. The agent reads project context through MCP.
3. The agent helps with implementation.
4. The agent suggests a task update or a new follow-up task.
5. The developer reviews the result.
6. The project state stays aligned with the actual work.

AI should not be a chaotic owner of the board.

It should be a participant in the workflow: one that sees the right context and works inside clear boundaries.

Why this will matter more

AI accelerates execution.

But the faster execution becomes, the more visible coordination problems become.

One AI session can include several things at once:

• implementing a feature;
• fixing a bug;
• refactoring shared code;
• adding tests;
• discovering a new edge case;
• creating a follow-up task;
• updating notes;
• preparing for a release.

From a coding perspective, that can be productive.

From a project management perspective, it can quickly become noise if the result only stays inside a chat.

That is why I believe the next important part of AI-assisted development is not only better code generation.

The next important part is connecting AI sessions to project state.

What is next in the series

This first article is about the general pain, the idea of a project layer, and MCP as a way to connect an AI agent with project state.

Next, I want to break Vibeocus down by layers so each part focuses on one concrete workflow instead of trying to describe the whole product at once:

• Part 2: tasks, rules, and decisions — how tasks, rules, and decisions give the agent working context before code changes.
• Part 3: architecture, Freeform boards, Git, and visual project context — how diagrams, relations, commits, and visual maps help reason about complex features and plan work.
• Part 4: documents and client requirements — how to upload a technical specification, connect it to a project, and use it as context for tasks and AI sessions.
• Part 5: Vibeocus Lens — how visual website annotations, selected elements, and screenshots become project context for an agent.

Final thought

AI coding does not end with code generation.
Real software work needs tasks, rules, decisions, memory, statuses, and coordination.
If an AI agent helps write code, it should see at least part of that context in a structured way.
That is what I call a project layer.
Vibeocus is one implementation of that layer: a local workspace that connects project state with AI tools through MCP.
I am curious how other developers are solving this problem.

How do you connect AI coding sessions with the real tasks, rules, and decisions of your project?
And does MCP feel like the right interface for this kind of project layer?