Back to the blog

 · AXOps · about 14 min read

A project operations system AI agents use directly: connecting VIBE OPS with a CLI and Skills

We built an operations system that manages everything from requirement to release check (VIBE OPS), and connected AI coding agents so they read and write it under the same rules as people. This is how we did it. The integration is not an MCP server but one bash CLI and procedure documents (Skills).

What this piece covers

On an enterprise system build project, AI coding agents (Claude Code) do a large part of the development. An agent that writes good code isn't enough to keep a project moving. It has to read what to build, record what it built, and stop where a person's approval is needed.

This piece explains what the VIBE OPS system that carries that work is, and how we connected agents to VIBE OPS, in three layers: an API that holds the rules, a CLI as a thin integration, and Skills that set the order of work and where to stop.


What VIBE OPS is

VIBE OPS is a project operations platform that manages, in one place, everything from the moment a requirement for the target system comes in until it is confirmed as done. It carries the flow requirement → PRD → work items → stage confirmation → testing, and shows progress, delays and approvals as totals. The input for building the main system comes out of VIBE OPS.

We set out to solve four problems.

The screens are split into requirements (kanban, backlog, sprints, change tracking), development management (development list, status board, weekly results), test management, risks and issues, approvals, and system administration. The front end is Next.js, the back end NestJS, the database Oracle, in a pnpm + Turborepo monorepo.

The path a requirement takes

A requirement passes through these states in order.

StateMeaningWho moves it
DRAFTDraftRegistrant
REVIEWRequirement reviewConsultant
APPROVEDRequirement approved (can go into a sprint)Consultant
IN_PROGRESSIn developmentDeveloper
IN_REVIEWDevelopment review (waiting for the business side to check)Developer
DONEDoneOnly through confirmation by the business process owner (PI)

A requirement is split into several work items, and each work item goes through the stages DESIGN → BUILD → TEST → DEPLOY. Each stage has three states, WAIT → DOING → APPROVE. When implementation is finished, the work item goes separately through two confirmations: consultant sign-off and business review.

The important rules are enforced by the server, not the screens.

There are six account roles: admin, PM, consultant, developer, PI and requester. For each resource, five actions (read, write, approve, manage, plan) are mapped in a static table. Scope checks such as "only items you are involved in" are done in service logic.

That these rules live on the server is the premise for the agent connection that follows.


How it connects: three layers

People
Web screens
Agent
Skillsprocedure documents
CLIbash wrapper
REST APIpermission table · state rules
DB
People use the web screens and agents use Skills and the CLI, but both go through the same REST API.
LayerWhat it handlesForm
APIWhat is allowedAbout 30 NestJS controllers, a role × resource permission table
CLIHow to call it1 bash script, 43 subcommands
SkillsWhen, in what order, and where to stop16 procedure documents

The counts and line counts in this piece are as of the repository on November 20, 2026.

People and agents go through the same API. There is no back door just for agents, so what an agent can do is what its token owner's role can do.


The CLI: one thin integration

When people think of connecting agents, an MCP server comes to mind first, but VIBE OPS has no MCP server. The integration is one CLI called ops.

Registration puts a one-line wrapper script on the executable path in the home directory. It only hands off to the repository's script with exec, so a git pull keeps the CLI current too.

Command set

Command groupSubcommandsExamples
req (requirements)21req list --status APPROVED --mine, req get <id>, req status <id> <STATUS> [comment], req artifact save <id> prd <file>
dev (work items)8dev list --mine, dev doc save <id> DEV_SPEC <file>, dev stage step <id> BUILD APPROVE [reason]
sprint11sprint active, sprint assign <sprintId> <REQ…>
Othersbacklog, approvals pending, processes, whoami

Authentication and secrets

Automation uses API tokens. There is an interactive login too, but it needs a TTY, so when an agent runs it, it ends with no output.

Exit codes are also split so agents can read them easily: 0 is success, 1 is an error, 3 is missing or expired authentication, and 4 is no permission (403). The procedure says that on 4 the agent doesn't retry but tells the user who needs to do that work.

Output that saves the agent's context

Some things are trivial for people but cost an agent.

Commands we left out on purpose

The CLI has no delete and no undo of done. Destructive or hard-to-reverse work is done by a person on the web screens. Instead of telling the agent in a prompt not to use them, we left those commands out of the integration itself.


Connecting it to an AI coding agent

Connecting is done once, in six steps. A person does the two steps where secrets change hands; the agent does installation and checking. The team links the procedure documents in the repository once.

StepWhoWhat they do
1. Check the environmentAgentDetects the operating system and shell, and checks for curl and jq.
2. Register the CLIAgentPuts a one-line wrapper script on the executable path. It doesn't use alias. The non-interactive shell that agents run in doesn't pick aliases up.
3. Issue a tokenPersonCreates an API token on the VIBE OPS web settings screen. The token itself is shown only once, right after issuing.
4. Store the tokenPersonIn their own terminal, with input that isn't shown on screen, writes it to a file only they can read. Never pastes it into the chat.
5. CheckAgentOne ops whoami checks the server connection and authentication together. If a name and role come back, it's done. If there's no authentication, it points to steps 3 and 4 and stops.
6. Link the procedure documentsTeamPuts a table of "for this kind of request, this procedure document" in the repository's agent instructions file, and keeps the procedure documents (Skills) in the same repository. The agent reads this table when it starts work.
# (agent) from the repository root: register the wrapper on the executable path
mkdir -p ~/bin
printf '#!/usr/bin/env bash\nexec "%s/scripts/ops-cli.sh" "$@"\n' "$(pwd)" > ~/bin/ops
chmod +x ~/bin/ops

# (person) in your own terminal: the token is typed without being shown
mkdir -p ~/.ops
read -rs -p 'Paste API token: ' T && printf %s "$T" > ~/.ops/token && unset T; echo
chmod 600 ~/.ops/token

# (agent) check
ops whoami        # example output: { "name": "Jane Doe", "role": "developer", … }

A token's permissions follow the role of the person who issued it. So once connected, the agent can do what that person can do on the web screens.


Skills: documents that set the order and where to stop

If the CLI is "how to call it", Skills are "when to call what, and where to stop". A skill is one SKILL.md document.

There are 16 skills in four groups.

GroupSkills
Git flowStart work, pre-check, create merge request (MR), merge, clean up, status, release
EnvironmentStart and stop servers, pick up work, schema changes, deploy queue
Planning documentsPRD draft, development spec draft
VIBE OPS integrationCLI reference (work-ops), one requirement start to finish (work-req), one work item start to finish (work-dev)

One requirement, start to finish: work-req

A single line, "Work on REQ-101", unfolds into the procedure below. The requirement numbers and comment texts in this piece are examples.

StepWhat it doesCLI
① UnderstandReads the requirement, artifacts, work items, comments and history, and reports the entry point and sizereq get, req artifact list, req dev-items, req timeline
② PRDOnly if there is no PRD: draft → user review → savereq artifact save <id> prd
③ Spec and scenariosWrites each only if missingreq artifact save <id> devSpec
④ Break downPresents a work-item breakdown as a table → registers it after confirmationreq dev-add
⑤ DevelopChecks sprint membership and runs work-dev for each itemsprint active, req status <id> IN_PROGRESS
⑥ Wrap upWhen every item is done, moves it to development review and stopsreq status <id> IN_REVIEW

Here are ① and ② as commands.

RID=$(ops req get REQ-101 | jq -r .id)          # number → ID, once only
ops req get "$RID" | jq 'del(.generatedDocs)'   # body only (about 33,800 → 2,700 characters)
ops req artifact list "$RID"                    # are there artifacts already?
ops req dev-items "$RID"

# no PRD → draft → user review → save and comment in one go
ops req artifact save "$RID" prd ./prd.md \
  && ops req comment "$RID" "PRD saved — 4 functional requirements"

The procedure is idempotent. It decides where to enter by checking which artifacts already exist, so if another session picks up work that was cut off midway, it doesn't do the same thing twice.

One work item: work-dev

A work item records its progress with stage stamps.

ops dev doc save "$DID" PRD ./prd.md \
  && ops dev stage step "$DID" DESIGN DOING "Design started"

# … implementation, local checks …

ops dev comment "$DID" "Local E2E 4/4 · pre-check passed"
ops dev stage step "$DID" BUILD APPROVE "Build done — MR merged and deployed"

This is where "progress is not entered", from earlier, closes the loop. The stage stamps the agent records become the numbers on the status board. Check results are written as numbers, like "4/4", not as "passed".

Splitting the seats

Within a procedure, the agent seats are also split by the kind of work. Design and planning go to a read-only seat on a higher model; finding code locations goes to a search seat on a lighter model, which returns only its conclusion and path:line; implementation goes to an implementation seat in an isolated working folder (a worktree).


Running it in natural language

Once connected, nobody needs to memorize commands, because the front matter of each procedure document holds natural-language conditions. The front matter of the work-item procedure lists example requests and then ends like this (our translation of the Korean original).

…as in these, apply this skill also when someone asks to move a development-list item forward without naming the skill.

Here is how a single line becomes commands, in four cases (the numbers are examples).

What the user saysProcedure the agent picksCommands it runsResult, or where it stops
"What requirements do I have?"work-opsops req list --mineSummarizes the list and reports. No writes.
"Work on REQ-101"work-reqops req get REQ-101 → ops req artifact list <id> → ops req dev-items <id>First reports how far it has got and how big it is. The PRD draft goes up with ops req artifact save <id> prd <file> only after the user has reviewed it.
"Design for DEV-201 is done, record it"work-devops dev stage list <id> → ops dev stage step <id> DESIGN APPROVE "Design done"If it can't take that step (not the assignee, or the previous stage isn't finished), it doesn't record it and says why.
"Mark REQ-101 as done"work-opsRuns nothingExplains that done is set only through confirmation by the business side, and stops.

As a conversation, it looks like this (the replies are examples).

User
What requirements do I have?
Agent
You have 3 requirements that you own or requested: 1 in development (REQ-101) and 2 in requirement review (REQ-102, REQ-103).
User
Mark REQ-101 as done.
Agent
I can't set REQ-101 to done. Done is set only through confirmation by the business process owner, and the server rejects requests that change the state directly. Its 2 work items are both finished, so if you like, I'll move it to "development review" to wait for confirmation.

In the second conversation, the agent doesn't try the command and fail; it reads the rule in the procedure document first and stops. The server enforces the same rule, so even if the agent misreads the document, the requirement isn't marked done.


Where the agent stops

The part of the connection we worked hardest on is what the agent doesn't do. We put the stopping points both in code and in documents.

Where it stopsServer (code)Procedure (document)
Marking doneDONE only through confirmation; a direct change gets 400Moves it up to development review and stops
Approving sprints and requirementsRole permission tableOnly when the user explicitly asks
Requirements not in a sprintSwitch to in development is rejectedDoesn't add it to a sprint itself; reports that the user should ask the person in charge
Delete and undoNo command in the CLIDone by a person on the web screens
Permission errors403 (exit code 4)No retry; says who needs to do it
Saving planning documents—Drafts go up only after the user reviews them
Production release—The deploy button and merges to the production branch are for people

If you block only in documents, it breaks the moment the agent misreads a procedure. If you block only in code, the agent spends time looking for a way around after it is rejected. The most stable combination was the server blocking and the document telling the agent "don't try here; report like this instead".


What we learned running it


To close

In short, three things.

  1. Keep the rules on the server. People and agents go through the same API and the same permission table.
  2. Keep the integration thin. The CLI maps the API as it is, and changes with it in the same repository.
  3. Keep the order of work and where to stop in documents. Write into the procedure how far the agent goes and where it hands over to a person.

Takeaway

To hand agents more work, what we needed first was not a smarter prompt but an operations system for the agent to read and write, and the rules that system enforces.

Would this work for us? Find out with a free two-week on-site diagnosis

Pick one workflow and we'll diagnose it on site for two weeks, then hand you a report and a build proposal. No obligation to go further.

Explore consulting