NomadWorks

Don't just code with AI. Build enterprise-grade software.

NomadWorks is an OpenCode plugin that installs the NomadWorks Collective: an AI-native software development team composed of specialized agents with distinct roles, handoff rules, and verification gates.

Instead of giving you a single generic assistant flow, NomadWorks gives you a small software company inside OpenCode. The collective includes product, architecture, development, QA, review, and design roles that collaborate through explicit artifacts such as SCRs, task files, evidence packets, and documentation updates.

Install

Add the plugin to your OpenCode config:

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["@neuralnomads/nomadworks"]
}

Then restart OpenCode, open the target repository, and start talking to the product_manager agent (PMA).

PMA will guide the repository setup flow and, when needed, initialize NomadWorks inside the repo for you. The user does not need to manually run NomadWorks commands to get started.

Configure

During setup, PMA can initialize the repository and create .nomadworks/nomadworks.yaml. NomadWorks reads this file for repository-local defaults, feature flags, policy extraction settings, and per-agent config overrides.

Repository-local policy overrides live in .nomadworks/policies/. If a policy file is not present there, NomadWorks falls back to the bundled plugin default automatically.

Repository-local full agent definitions can live in .nomadworks/agents/. Use this folder to override a bundled agent's base prompt or define a brand new custom repository agent.

Repository-specific additive agent instructions can live in .nomadworks/agent-additions/.

Repository Customization

• .nomadworks/policies/*.md: shared repository policy overrides used by multiple agents
• .nomadworks/agents/<agent>.md: full repository-local agent definition that overrides a bundled agent or defines a new custom agent
• .nomadworks/agent-additions/<agent>.md: additive repository-specific instructions appended to a bundled or custom agent prompt
• .nomadworks/generated/agents/: generated final prompt dumps for inspection when features.debug_dumps is enabled
• .nomadworks/generated/policies/: generated reference copies of bundled default policies when policies.extract_defaults is set to all

nomadworks_init also creates README placeholders in these folders so repositories can discover what each folder is for without those README files being treated as agents.

The scaffolded README files in .nomadworks/agents/ and .nomadworks/agent-additions/ also list the common available plugin: and policy: includes that custom agents can reuse.

Runtime prompt resolution prefers repository-local policies, agent definitions, and agent additions when present, while keeping the plugin-owned workflow and role model intact by default.

NomadWorks supports two team presets:

• mini: PMA + BA + Tech Lead for simple repositories and tiny / standard tasks
• full: the complete collective, including advanced specialists and workflow_runner

If team_mode is not set in an existing repository, NomadWorks treats it as full by default.

Quick links:

• Installation
• Configuration
• Releasing
• Workflow Agents
• Workflow Model
• Plugin Tools
• Mini Team Mode
• Full Team Mode
• Documentation Structure

Release

NomadWorks ships as the npm package @neuralnomads/nomadworks.

• Local verification: npm run release:check
• Push to dev: auto-publish prerelease (rc)
• Push to main: auto-publish stable release

For the full release setup, required secrets, and branch-based versioning behavior, see Releasing.

Team Modes

Team Mode	Available Agents	Supported Task Complexity	Flow Guide
mini	product_manager, business_analyst, tech_lead	tiny, standard	Mini Team Mode
full	Full NomadWorks Collective, including workflow_runner, technical_architect, developer, qa_engineer, and ui_ux_designer	tiny, standard, complex	Full Team Mode

Workflow Agents

The NomadWorks Collective operates like a role-based software development team:

• product_manager (Product Manager Agent, PMA): Default orchestrator and routing agent.
• workflow_runner (Workflow Runner): Delegated orchestrator for complex implementation tasks.
• business_analyst (Business Analyst, BA): Requirements and product-truth steward.
• technical_architect (Technical Architect): Architecture, interfaces, and impact mapping.
• tech_lead (Tech Lead): Behavioral verification and technical sign-off.
• developer (Developer): Implementation and test authoring.
• qa_engineer (QA Engineer): Verification and test coverage.
• ui_ux_designer (UI/UX Designer): Visual and interaction review.

Together, these agents act as a coordinated delivery team rather than a loose set of tools. PMA manages the work, specialists own their disciplines, and the workflow enforces that major changes are specified, verified, and documented before closure.

Plugin Tools

NomadWorks provides these plugin tools:

• nomadworks_init
• nomadworks_validate
• nomadworks_start_discussion
• nomadworks_stop_discussion
• nomadflow_run_workflow
• nomadflow_prompt_workflow

For arguments, behavior, and team-mode availability, see Plugin Tools.

Task Model

• Complexity: tiny, standard, complex
• Track: implementation, investigation, spec
• Slice: foundation, core, logic, ui, polish, qa, docs

Use complex for work that needs an approved SCR, slice-based decomposition, and workflow_runner. Keep tiny and standard tasks direct and bounded.

Discussion Handoffs

NomadWorks also supports tracked discussion handoffs between product_manager, business_analyst, and tech_lead.

When a direct discussion becomes workflow-relevant:

• create or update a normal task file
• assign it to the next responsible agent
• record the reasoning in the task file's Discussion Record
• track it in tasks/current.md under Active Discussions

This keeps product and technical discussions durable, visible, and easy to hand over between agents instead of losing them in chat history.

What Is An SCR?

SCR stands for Spec Change Request.

An SCR is the workflow artifact used to define and approve a meaningful change before implementation starts. It records:

• the problem being solved
• the proposed specification change
• the intended implementation direction
• acceptance criteria
• review and approval state

NomadWorks uses SCRs so the team does not jump straight from a vague request into code. The SCR gives the Product Manager Agent, Business Analyst, Tech Lead, and other specialists a shared source of truth for what the change is supposed to achieve before delivery work begins.

In practice, SCRs help:

• reduce missed requirements and hidden assumptions
• separate proposed change from implemented truth
• make complex work reviewable before coding starts
• provide a stable anchor for decomposition into tasks

Task Flow

NomadWorks uses different operating flows depending on the configured team mode.

• For the lightweight operating path, see Mini Team Mode
• For the complete collective path, see Full Team Mode

Parallelism

Until dedicated git worktree support lands, NomadWorks supports limited parallelism:

• one shared-worktree implementation task at a time
• parallel investigation and spec tasks when they avoid conflicting edits

For deeper workflow details, use the linked docs above.