DEV Community: Kravtsov

What your wiki needs before an AI assistant can onboard a new hire

Kravtsov — Wed, 07 Oct 2026 20:16:04 +0000

A new salesperson asks the wiki whether she can give 25% off an annual plan. The answer says no, names the person who approves it, and links to the page it came from. Nobody was interrupted.

I'm the CEO of Evergreen, and we build Folio, an open-source wiki where every page is a file in Git. This is how its onboarding setup works, shown on a made-up Sales space: Acme, a new hire called Jamie, a manager called Marcus.

The answer is not the interesting part. What the wiki needs underneath it is.

Pages are files
A document is *.md, a table is *.table.md, a form is *.form.md, all inside a Git repository. PostgreSQL keeps the index and the access rules, not the content. The assistant, an IDE and a human in the browser work with the same files, and every change is a commit with an author.
Ask mode answers from pages, and the sources are a rule
Folio AI is a panel with two modes. Ask is read-only, and that is enforced on the server. Agent can also write.

Ask mode. The Sources: line is a link to the page, and one click opens it.

That last line is not magic. Without a rule the assistant only has to name the space and the page. The Sources: line with links is a page in the space's .agent folder. This is the starter we ship, how-to-answer.md:

How to answer
You help a new teammate in their first weeks. Answer from the pages of this space, not from general knowledge.

Search the space before you answer. Read the page, do not guess from its title.

Keep the answer short: two to five sentences, or a short list when the answer is a sequence of steps.

Always end with a line Sources: followed by links to the pages you used, in the form [Page title](/s/<space>/p/<id>).

Say plainly when the pages do not contain the answer. Do not make up prices, dates, names or rules. Then suggest who to ask, using the page "Escalation". .agent is a folder of ordinary pages that only space administrators can see or edit. Everything in it goes into the context of every run in that space, in Ask and Agent mode, up to about 60,000 characters. For a non-admin those pages simply do not exist: the answer is "page not found". The panel shows ".agent rules (1)" above the input.

A rule is a line of text, and Git remembers it
The manager adds one line to the page:

Before the Sources line, add a line "Next step:" with one concrete action.
Then he asks the same discount question in a new conversation.

The rule applies from the next conversation: an old one keeps its earlier turns in the Cursor SDK. And rules are pages, so they have page history: who added "Next step", when, and a restore button, like any other page.

A form is a table with a front door

At the end of the week the newcomer answers five questions. That is a form page, paired one to one with a table: a form field is a table column.

This is what Folio writes to disk. It is the demo's "Feature requests" table (columns and rows trimmed), serialized by the repository's own codec:


---
folio: table
version: 1
id: 01J00000000000000000000T01
columns:
  - id: title
    name: What do you want?
    type: text
  - id: rating
    name: How much do you need it (1 to 5)
    type: number
  - id: contact
    name: You may contact me
    type: checkbox
views: []
options:
  rowIds: none
---
# Feature requests

<!-- folio:table:begin -->

| What do you want? | How much do you need it (1 to 5) | You may contact me |
| --- | --- | --- |
| Dark theme for the table grid | 3 | [x] |
| PDF export of whiteboards | 4 | [ ] |

<!-- folio:table:end -->
And the form that fronts it:

---
folio: form
version: 1
id: 01J00000000000000000000F01
table: handbook/feature-requests.table.md
title: Request a feature
public: false
submitButton: Send request
fields:
  - columnId: title
    label: What do you want?
    required: true
    kind: text
  - columnId: rating
    label: How much do you need it (1 to 5)
    required: true
    kind: number
---

The table is plain GitHub-renderable Markdown, so a new answer is a diff. The server adds Submitted at and Submitter itself. Anyone with the viewer role or higher can submit while signed in; anonymous answers need the public flag and a share link, both. The answers table can be restricted to the manager: the newcomer's submission still lands, and he cannot read the table.

Views are the manager's inbox

A view is a filter with and/or rules and a sort, stored in the table's front matter. "Needs a follow-up" in the video is an or: the discount ceiling answered is not 10, or the readiness score is 2 or lower. Four rows go in, one stays: the person who wrote 15.

The assistant reports what it could not answer

This is the part I would build first. There are three signals, and none asks anyone to fill in a report: a 👍 or 👎 on each saved answer, a survey ("Did the assistant solve your question?") after every third answer, and a built-in tool the assistant calls itself.

The assistant calls it once per question, and the server enforces that: check and insert run under a per-run advisory lock, questions are compared after normalization, a duplicate inside one run is dropped (it only fills an empty missing), and a run keeps at most three reports. The missing field is rendered as Markdown, and the tool description requires links to the pages the assistant actually opened in this run:

missing: {
  type: 'string',
  description:
    'What is missing or unclear in the documentation, in one or two short sentences. It is rendered as Markdown for the documentation owners: ' +
    'link each Folio page you actually opened in this run that is related to the gap, as [<title>](/s/<space>/p/<id>) ' +
    '... Never invent a link and never link a page you did not read in this run.',
},

"Questions without an answer". The person's own words come first, the assistant's restated question under them, and then what was missing. This frame is from the recording made before the links fix.

An instance administrator sees every conversation. A space administrator sees the same page limited to the spaces they administer. A personal access token is refused there. Opening a conversation is written to the audit log, and the conversation shows a "Who opened this conversation" block with the name and the time.

The space admin writes the missing section, Jamie asks again in a new conversation, and the answer names the finance lead and links to "Refund policy".

That description is the second version. The first one only said what to put in missing, and in the 19 runs we recorded for video the model wrote plain text and linked a page once. So the recording above has no links in the column. We fixed it in the tool description, not in the UI, and a live check afterwards gave links in all 5 of 5 unanswered questions, each to a page the assistant had read in that run.

The same pages for outside agents

/mcp gives any MCP client 23 tools with a personal token or OAuth, including search and fetch for ChatGPT deep research. The client works with your rights and nothing more:

claude mcp add folio --transport http https://<host>/mcp \
  --header "Authorization: Bearer folio_pat_…"

Two things do not carry over: outside agents do not see .agent, and only the built-in assistant records unanswered questions. For outside agents the package has agent-playbook.md, the same rules as an ordinary page.

What it does not do

Folio AI needs a Cursor subscription, and the pages it works with go to Cursor. There is no other provider yet.

Want to take a look?

Folio is open source (MIT): https://github.com/evergreen-it-dev/folio. The demo is at https://demo.foliowiki.online (pick Sam on the sign-in screen; data resets daily), and there is a short tour at https://foliowiki.online.

I'd be glad if it helps you. And I'm glad to talk about AI SDLC and how you can do the same in your own company.

I Gave AI Agents Actual Job Descriptions. My Team's Delivery Speed Went Up 300%. Here's the Setup

Kravtsov — Tue, 07 Jul 2026 14:06:05 +0000

Hey — I'm Sergii, I run ConnectiveOne (an AI-powered comms platform) and co-founded Evergreen, a dev shop out of Kyiv. I want to walk through, in actual technical detail, how we rebuilt our SDLC around AI agents — not the "we added Copilot" version of this story, the version where it took us over a year, we broke things, and we ended up with a setup that other engineers might actually find useful to steal from.

TL;DR: giving a coding assistant unlimited scope and just chatting with it doesn't scale past a certain point. Giving it a narrow role, a written spec of its boundaries, and a quality gate before a human ever sees the diff — that scales. This post is the "how," with the actual structure we use.

The problem, concretely

If you've used Claude Code or Cursor for more than a few weeks, you've probably hit this: you git clone, you start asking it things — "why is this erroring," "can you refactor this," "how do I wire this up" — and for the first few sessions it's magic. Then context starts leaking. It re-derives your architecture every session. It doesn't remember the convention you told it about three days ago. Token costs climb. And the output quality becomes a function of how well you phrased the prompt that particular morning, not a property of your codebase or your process.

That's not a model problem. It's an architecture problem — you're running a chat, not a system.

What we built instead: agents with job descriptions

Here's the mental model shift that actually mattered: stop treating the agent like a chatbot you're negotiating with, and start treating it like a new hire you're onboarding. A new hire doesn't get "here's the whole codebase, go wild." They get a role, a scope, a set of docs to read, and boundaries on what they're allowed to touch.

We formalize this as a rules layer that lives in the repo, versioned like everything else. If you're on Cursor this is literally .cursor/rules and .cursor/agents; if you're on Claude Code or something else, the mechanism differs but the principle doesn't: if a convention isn't written down somewhere the agent can read it, it doesn't exist as far as the agent is concerned. Don't rely on the model "just knowing" your team's patterns from the code alone.

A simplified version of what one of our role files looks like:

role: backend-development-agent
scope:
  - services/orders/**
  - services/payments/** (read-only, no writes)
forbidden:
  - infra/**
  - CI/CD config
  - anything touching auth middleware
inputs:
  - architecture spec (docs/specs/orders-service.md)
  - existing test suite
outputs:
  - implementation + updated unit tests
  - updated README section for the touched module
must_pass_before_handoff:
  - lint
  - full test suite (local)
  - self-review checklist (see docs/agent-checklist.md)

Nothing exotic here. The value isn't in any single line — it's that this document exists at all, is checked into version control, and is the actual contract the agent operates under, instead of whatever context happened to survive to the end of a long chat session.

Three pillars, in practice

Rules as source of truth. Already covered above — the point is it's a versioned artifact, not tribal knowledge in a senior dev's head.
Role-based agents, not general-purpose ones. We run separate agents for backend, UI/UX, QA, architecture review, and documentation — each with its own scope file like the one above. This sounds like overhead until you compare it to the alternative: one assistant that touches everything, with quality that degrades the more creative latitude you give it. LLMs behave better with a tight job description than with "help me with anything," the same way a contractor does better with a scope of work than with "make the house nicer."
AI transforms the SDLC, it doesn't replace it. Our actual pipeline: requirements → design → dev → test → deploy, with an agent (or agent pair) per phase and an explicit handoff artifact between phases — a markdown spec, not a copy-pasted Slack message. If your team's process for sharing a good prompt is "I pasted it in our dev channel," that's not a system, that's folklore, and it doesn't survive the person who wrote the prompt going on vacation.

The rollout order that actually worked (and the one that didn't)

We tried going straight to "multiple agents running in parallel across the codebase" early on. It went about how you'd expect: fast, confident-sounding output, and a nontrivial chunk of it subtly wrong in ways that were expensive to catch after the fact.

What worked instead — and what I'd tell any team starting this today:

Pick one narrow, boring process. PR review, doc generation, one specific QA pass. Not "the whole SDLC." One thing.
Build one role-scoped agent for it. Validate on real tickets, not toy examples, before it touches anything else.
Add roles one at a time. Each new agent gets its own scope file, gets proven on real work, then becomes permanent.
Only once gates are stable, add parallelism. Multiple agents running concurrently and handing off context to each other — what we internally call an agent swarm — only makes sense once you already have stable rules and an automated quality gate in front of merge. Skipping to this step is the single most common mistake I see teams make.

Where the human actually sits

This is the part people get anxious about, so let me be specific instead of hand-wavy.

We run automated review (CodeRabbit, in our case) as a first-pass filter — style, obvious issues, convention violations, basic security smells. That's it. That's what it catches. It does not catch intent drift — an agent producing code that's clean, passes tests, lints fine, and still solves a subtly different problem than what was actually asked, because context drifted over a long session or an upstream agent handed off a stale spec. That class of failure needs a human, every time, no exceptions. Architecture decisions and business-logic correctness stay human. Final merge sign-off stays human.

What changes isn't whether a human is in the loop — it's what the human is actually reviewing. Less "does this line of code look right," more "does this diff match the intent, and did the agent stay inside its scope file." That's a different skill than traditional code review, and it's worth explicitly training your team on it rather than assuming it transfers automatically.

The tooling gap nobody tells you about: provenance

Here's the thing that bit us hardest and that I don't see written about much: when an agent-generated change causes a problem three weeks later, "why did it do this" is not something you can just ask the engineer who reviewed the PR, because they reviewed a diff, not a decision process. And re-running the same agent against old context and hoping it explains itself consistently is not a reliable debugging method.

We ended up building an internal orchestration layer (we call it C1Cursor) specifically to solve this — every agent-generated diff gets tagged at execution time with: which agent, which role/scope, what context it actually had access to (which docs, which code, which upstream agent's output), and which gates it passed or failed. This turns "why did this happen" from an archaeology project into a lookup. If you're rolling this out yourself and don't have budget for custom tooling, at minimum log this metadata somewhere queryable — even a structured commit message convention is better than nothing.

The number, and why I wouldn't lead with it

Doing all of this got ConnectiveOne to roughly +300% development velocity year over year, against our own prior baseline. I mention it because people ask, but I wouldn't lead a technical conversation with it, because velocity without the gating and provenance layer above is exactly how teams end up shipping fast and debugging blind. The metric that actually told us this was sustainable wasn't velocity — it was our quality-gate pass rate holding steady as we added more agents and more parallelism. Velocity was downstream of that staying true, not a separate win to brag about.

If you're starting this next week

Don't start by picking a model. That's the wrong first decision. Start by writing down, in a file your agent can actually read, what one narrow process is allowed to touch and what it isn't. Prove that one thing works on real tickets. Then add the next role. Resist the urge to parallelize before your gates are boring and reliable — boring is the goal, not a consolation prize.

Happy to go deeper on any piece of this in the comments — the role-file format, the provenance tooling, or the QA agent setup specifically. This is still an evolving system for us, and I'd rather compare notes with people building the same thing than pretend we have it fully solved.