The AI Agent That Refused to Write Code

Applying the AI-Ready Nx Workspace to a production monorepo

We asked our coding agent to start a task, /run-task 12.1. It read the task definition, followed its dependency chain, and stopped:

STOP — 12.1 is blocked. Its gate depends on a spike's live decision-run, which hasn't been executed, and a market-validation gate that hasn't cleared. Building the schema now risks building on a premise the gate may reject.

It produced no code. That refusal is the behavior we most wanted from the AI-Ready Nx Workspace, and a good example of what the framework does: it keeps an agent working inside the architecture and process a team already has, rather than around them.

This post covers what we adopted and what it changed.

The problem

The AI-Ready Nx Workspace is a template monorepo built around one rule:

Agents consume architecture. They do not redefine it.

It addresses three failures that show up when coding agents work in a real repo:

• They duplicate architectural decisions across config files until the configs disagree.
• They invent conventions instead of following the ones already there.
• They skip quality gates that were never written down.

Its structure: an Authority Order (Nx project graph, then /docs, then /.ai, then agent-specific files), five agent roles, a tiered SDLC pipeline, ADRs, and thin adapter files (CLAUDE.md, AGENTS.md, .cursor/) that point each tool at the same shared rules.

We applied it to StoryCraft, an Nx monorepo: a requirement-quality engine that scores user stories against INVEST, plus a hosted MCP server, a tRPC API, a Next.js app, and a Supabase database.

What we adopted

Consume, don't redefine

StoryCraft exposes its MCP engine over local stdio (packages/mcp) and over hosted HTTP. When the hosted endpoint was added, the shared tool definitions in tools.ts stayed untouched; the endpoint is an adapter that registers the existing transport-agnostic tools. An ADR recorded the boundary: if the hosted transport needs to edit tools.ts, the transport is leaking into the handlers. Across the five-task wave, that file never changed.

The tiered pipeline

Tasks are classified by story points into a tier that sets which phases run:

Tier	SP	Phases
Light	1–2	Analyze, Implement, Review, Verify
Standard	3	+ Design, + Test
Complex	5–8	+ Security, + Deploy

A recent Light task, documentation plus a smoke probe for the hosted endpoint, ran all four phases: a Task Brief that paused for human confirmation, implementation behind a gate (nx affected -t lint,test,build had to pass), a review pass, and verification that ran the probe against a live server. The task's output file records the run:

| Metric              | Value |
| Total phases        | 4     |
| Gate failures       | 0     |
| Review cycles       | 0     |
| Human interventions | 1     |

Every task produces the same record, regardless of who or what ran it.

Roles

The agent reads a different role file for each phase: Business Analyst for the brief, Implementer to build, Reviewer to critique the diff, then back to Business Analyst to verify against the acceptance criteria. Because the reviewing instructions are not the building ones, the review phase tends to catch more than an author re-reading their own work.

Gates that stop work

The refusal above came from this pillar. Two examples from one session:

• Task 12.1 was blocked. The agent followed a Depends on column to an unmet spike and an open market gate, and halted instead of building ahead. It separated engineering necessity from market demand as distinct gate conditions and suggested running the missing validation first.
• Wave D2 was demand-gated. The agent drafted the full ~20-point plan, then marked it as not-to-start until real usage showed it was needed, and recorded that trigger alongside the plan.

Corrections that persist

Each task output includes a Human Interventions section: the points where a human corrected the agent, written up as a lesson the next task has to apply. Two from StoryCraft:

• When a roadmap names a specific third-party product, verify it still exists before designing against it. (The suggested rate-limit backend had been discontinued; the agent flagged it during analysis.)
• Task output belongs under .ai/sprints/.../tasks/; the progress file belongs in docs/specs/. Don't co-locate them.

The corrections live in the repo, so the same mistake doesn't recur across tasks.

ADRs

Decisions with trade-offs become ADRs the agent reads while working. The hosted engine's auth boundary became one. When a later account-connected wave needed a different auth model, the agent proposed a separate ADR rather than editing the first, keeping each ADR to a single decision.

What changed

• Conventions stayed consistent across the wave: one adapter pattern, one commit process, one location per artifact.
• The agent blocked its own work twice rather than ship on an unvalidated premise.
• Each task left a brief, a review, a verification, and a metrics table, in the same format.
• Human corrections became durable rules instead of one-off chat messages.
• "Build this later, when X happens" became a normal output, which kept speculative work out of the codebase.

How the wiring works

For anyone adopting it, the model is small:

• /.ai/ is the shared layer: roles/ (the five perspectives), prompts/ (phase guides), standards/ (coding, boundaries, security), workflows/ (tier definitions).
• /docs/ holds ADRs, architecture, and requirements.
• Adapter files (CLAUDE.md, AGENTS.md) stay thin. They point tools at /.ai/ rather than restating rules.
• The Authority Order resolves conflicts: the Nx project graph wins over docs, docs over /.ai, agent folders last.
• /run-task <id> reads the roadmap row, classifies the tier, checks dependencies, and runs the phases, with a human checkpoint at the brief and before each commit. The agent proposes commit plans; a human commits.

Most of the adoption cost is writing down decisions you have already made, boundaries, the review bar, the definition of done, in a place the agent is required to read.

Takeaway

We shipped a guarded hosted MCP engine through this process, and declined to ship two things that weren't ready. The value was not output volume. It was that the agent stayed within the existing architecture, stopped at the gates, and left a record we can audit.

Framework: github.com/codeaiforge/ai-ready-nx-workspace