· 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.
- Progress typed in by hand drifts from reality. When we checked in early August, the progress field of all 185 work items was 0. So progress is not entered; it is calculated from stage confirmation. Starting implementation makes it 50, finishing makes it 100.
- Scope that grew without approval doesn't show in the numbers. Additional requirements stay out of the denominator of the progress calculation until they are approved.
- Approvals are scattered across screens. Approvals for requirements, mockups, additional requirements and development sign-off are gathered in one place, "My approvals".
- Traceability between requirements, business processes and screens breaks. Business processes (L1–L3) are the single axis, and requirements and screens are linked to them.
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.
| State | Meaning | Who moves it |
|---|---|---|
DRAFT | Draft | Registrant |
REVIEW | Requirement review | Consultant |
APPROVED | Requirement approved (can go into a sprint) | Consultant |
IN_PROGRESS | In development | Developer |
IN_REVIEW | Development review (waiting for the business side to check) | Developer |
DONE | Done | Only 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.
- A requirement can't move to in development or beyond without a PRD.
- Only requirements in an active sprint can go into development.
- Done happens only through the confirmation procedure. In projects that use sprints, a request to set the state directly to
DONEis rejected with 400 even from an admin account; an admin has to use the proxy confirmation procedure. (Sub-requirements split from a parent requirement are outside this procedure.) - Development status is derived from the work items, so it can't be written directly.
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
| Layer | What it handles | Form |
|---|---|---|
| API | What is allowed | About 30 NestJS controllers, a role × resource permission table |
| CLI | How to call it | 1 bash script, 43 subcommands |
| Skills | When, in what order, and where to stop | 16 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.
- It is a single bash script. About 1,560 lines, depending only on
curlandjq. No build, no install step. - It is a thin wrapper over the REST API. No decision logic in it; endpoints are mapped to commands.
- It is versioned in the same repository as the API. The rule is that when an endpoint changes, the CLI is fixed in the same PR. The contract between server and client has no chance to go stale separately.
- People use the same commands. Anything an agent did can be reproduced as is in a terminal, which makes problems easy to trace.
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 group | Subcommands | Examples |
|---|---|---|
req (requirements) | 21 | req list --status APPROVED --mine, req get <id>, req status <id> <STATUS> [comment], req artifact save <id> prd <file> |
dev (work items) | 8 | dev list --mine, dev doc save <id> DEV_SPEC <file>, dev stage step <id> BUILD APPROVE [reason] |
sprint | 11 | sprint active, sprint assign <sprintId> <REQ…> |
| Others | backlog, 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.
- A person issues the token on the web settings screen. Expiry is chosen between 30 and 365 days, 90 by default.
- The server doesn't store the token itself, only its SHA-256 hash.
- The CLI reads the token from an environment variable or a file with permission 600. The auth header is passed to
curlon standard input, not as a command argument, so the token doesn't show in the process list. - The agent never receives a password or token value by any route. In the install runbook too, the agent carries environment detection, installation and verification through to the end, and hands only token issuing and admin credential prompts to a person.
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.
- Fetching one requirement as is gave a response of about 33,800 characters (measured on September 4, 2026). 92% of that was the full text of generated documents. So
req getfolds document text into a character count and expands it only with an option. The same fetch comes to about 2,700 characters. - Turning a number like
REQ-101into an internal ID means scanning the list. When we added "capture the ID on the first lookup and call by ID after that" to the procedure document, one lookup went from 3.3 seconds to 0.75 seconds (measured the same day). - Lists support both a table for people and
--jsonoutput.
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.
| Step | Who | What they do |
|---|---|---|
| 1. Check the environment | Agent | Detects the operating system and shell, and checks for curl and jq. |
| 2. Register the CLI | Agent | Puts 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 token | Person | Creates an API token on the VIBE OPS web settings screen. The token itself is shown only once, right after issuing. |
| 4. Store the token | Person | In 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. Check | Agent | One 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 documents | Team | Puts 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.
- The front matter holds a name and a description. The description includes natural-language conditions such as "also applies when someone says ○○ without naming the skill", so the agent reads the intent and pulls out the right procedure without the user memorizing commands.
- The body is numbered steps. Each step has the block of commands it actually runs.
- At the end there is a "pitfalls" table and a "never do" list. The items come from real incidents.
- Rules shared by several skills (database layers, rules for passing content, lookup cost rules) are split into common reference documents and linked.
There are 16 skills in four groups.
| Group | Skills |
|---|---|
| Git flow | Start work, pre-check, create merge request (MR), merge, clean up, status, release |
| Environment | Start and stop servers, pick up work, schema changes, deploy queue |
| Planning documents | PRD draft, development spec draft |
| VIBE OPS integration | CLI 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.
| Step | What it does | CLI |
|---|---|---|
| ① Understand | Reads the requirement, artifacts, work items, comments and history, and reports the entry point and size | req get, req artifact list, req dev-items, req timeline |
| ② PRD | Only if there is no PRD: draft → user review → save | req artifact save <id> prd |
| ③ Spec and scenarios | Writes each only if missing | req artifact save <id> devSpec |
| ④ Break down | Presents a work-item breakdown as a table → registers it after confirmation | req dev-add |
| ⑤ Develop | Checks sprint membership and runs work-dev for each item | sprint active, req status <id> IN_PROGRESS |
| ⑥ Wrap up | When every item is done, moves it to development review and stops | req 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 says | Procedure the agent picks | Commands it runs | Result, or where it stops |
|---|---|---|---|
| "What requirements do I have?" | work-ops | ops req list --mine | Summarizes the list and reports. No writes. |
| "Work on REQ-101" | work-req | ops 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-dev | ops 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-ops | Runs nothing | Explains 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 stops | Server (code) | Procedure (document) |
|---|---|---|
| Marking done | DONE only through confirmation; a direct change gets 400 | Moves it up to development review and stops |
| Approving sprints and requirements | Role permission table | Only when the user explicitly asks |
| Requirements not in a sprint | Switch to in development is rejected | Doesn't add it to a sprint itself; reports that the user should ask the person in charge |
| Delete and undo | No command in the CLI | Done by a person on the web screens |
| Permission errors | 403 (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
aliasisn't picked up in an agent's shell. Non-interactive shells don't read aliases. You need a wrapper script on the executable path.ln -sin Windows Git Bash makes a copy, not a link. The old CLI stays behind even after the repository is updated. Having the wrapper call the repository's script directly avoids the problem.- Korean text isn't passed as an argument. In some environments the encoding breaks, so the text goes through a temporary file.
- Documents go stale before code does. Even after roles grew from five to six, two design documents still say five. We narrowed what the agent treats as the source of truth to the code, the CLI help and the procedure documents, and when a rule changes we fix all three in the same change.
- What matters in a skill is the document, not the packaging. At first we bundled the skills as a plugin and called them with slash commands. Now the bundle is gone and the agent reads and follows the procedure documents directly. The way they are called changed, and the procedures still worked as they were.
To close
In short, three things.
- Keep the rules on the server. People and agents go through the same API and the same permission table.
- Keep the integration thin. The CLI maps the API as it is, and changes with it in the same repository.
- 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.