# Coder Nexus

**Agent roles, skills and MCP tools that help an AI coding agent deliver software the way a team does: requirements → design → plan → code → review → verification.**

Coder Nexus has three parts:

- **VS Code / Antigravity extension**: copies agent roles, skills and rules into your project and gives you one-click commands to manage them.
- **`coder-nexus` CLI (Python Hub)**: the MCP server your agent talks to, plus terminal commands for Huly task intake, two-layer Figma extraction (`tokens.json` + `<node>.spec.json` + per-screen `.png`/`.jpg`), and environment checks.
- **`skill-factory` CLI** *(new in 3.0)*: generators that write skills tailored to *your* workspace (architecture, clean code, tests, review, security, QA…). Installed together with `coder-nexus`.

Installing it does not start anything on its own. Your host agent (for example Antigravity) reads the installed roles and skills and uses them when you ask it to work.

## How it works

Coder Nexus organizes 7 specialized agent roles into **2 departments** (`dev-team`, `bug-squad`) plus 2 read-only companion workflows (`debug-investigation`, `feature-testing`):

```
Your request / task ticket
         │
         ├──► dev-team (Feature Delivery)         ──► Spec Writer (Huly + Figma Intake: S-NN, W-NN) ──► [Gate 1 Approval]
         │                                                                                                     │ (Zero-Re-Ask Handoff)
         │                                                                                                     ▼
         │                                                                             Planning [Gate 2 & 3] ──► Code Writer ──► Code Reviewer ──► Test Runner ──► Docs Writer (once after ACCEPTED)
         │
         └──► bug-squad (4-Gate Bug Resolution)   ──► Bug Fixer (Reproduce ──► Root Cause & Impact ──► [S1-S4 & L1/L2/L3 Confirmation])
                                                             ├── L1: Bug Fixer ──► Test Runner
                                                             ├── L2: Bug Fixer ──► Code Reviewer ──► Test Runner
                                                             └── L3: Escalation Report ──► dev-team (Zero-Re-Ask Handoff)
```

| Concept | What it means |
|---|---|
| **2 Departments & 7 Roles** | **`dev-team`** (`Spec Writer`, `Planning`, `Code Writer`, `Code Reviewer`, `Test Runner`, `Docs Writer`) and **`bug-squad`** (`Bug Fixer`, `Code Reviewer` L2, `Test Runner`). |
| **Approval gates** | You approve requirements, screens (`S-NN`) & workflows (`W-NN`) (`Gate 1`), technical design & UI Kit mapping (`Gate 2`), and the implementation plan (`Gate 3`) — or the bug triage level (`S1–S4`, `L1/L2/L3`) — before production code is written. Agents never approve for you. |
| **Zero-Re-Ask Handoffs** | When `Spec Writer` completes Gate 1, `Planning` starts directly at `Gate 2` without re-asking business requirements. Likewise, `debug-investigation` and `feature-testing` hand off directly to `bug-squad`, and L3 bugs hand off to `dev-team`. |
| **Skills & Always-On rules** | Constitutional guardrails in `.agents/rules/` stay active on every turn; step-by-step skills in `.agents/plugins/coder-nexus/skills/` load on demand for discovery, design, coding, review, debugging, and evidence. |
| **Stack packs & profiles** | Rules and skills for a specific stack (Flutter, Backend). Profile-specific guidance (`external-standard`, `external-structured`, `imespro`) is injected automatically into the installed skills. |
| **Workspace skills** | Skills generated by the Skill Factory into `.agents/skills/`. They belong to your project and take priority over pack skills on the same topic. |
| **MCP tools** | Task intake, architecture guidance, UX patterns, and validators the agent can call. |
| **Work & debug items** | Feature artifacts live under `.superpowers/work-items/<slug>/vN/`, bug/investigation artifacts under `.superpowers/debug/<slug>/`, and scenario runs under `.superpowers/test-runs/<slug>/`. |

## Install

### 1. Install the extension
In VS Code / Antigravity open **Extensions** (`Cmd+Shift+X` / `Ctrl+Shift+X`), search **Coder Nexus** and click **Install**.
Or download a `.vsix` from [Releases](https://github.com/pzakhim/coder-nexus/releases) and use **Extensions → … → Install from VSIX...**.

### 2. Install the CLI
Click **Coder Nexus** in the status bar → **Install / Update CLI**. It installs [`uv`](https://docs.astral.sh/uv/) if needed, then the CLI matching the extension version.

Manual install:

```sh
curl -LsSf https://astral.sh/uv/install.sh | sh
```

```sh
uv tool install --force git+https://github.com/pzakhim/coder-nexus.git@vX.Y.Z
```

```sh
coder-nexus --help
```

On Windows, install `uv` with `powershell -c "irm https://astral.sh/uv/install.ps1 | iex"`. Replace `X.Y.Z` with your extension version. Run **Install / Update CLI** again after each extension update.

### 3. Add agents to your project
Open your project. If the extension detects a supported stack it offers **Sync Now**. Otherwise open the Command Palette (`Cmd+Shift+P` / `Ctrl+Shift+P`) and run **Coder Nexus: Sync Stack to Workspace (Auto-Detect)**, then pick your stack.

The sync writes:

| Path | Content |
|---|---|
| `.agents/agents/` | The 7 agent roles, combined with the rules of the selected pack |
| `.agents/rules/` | Always-On constitutional guardrails for the installed pack (`clean_architecture_rules.md` or `backend_clean_architecture_rules.md`) |
| `.agents/plugins/coder-nexus/` | Shared skills, stack skills (with active profile references injected), and `mcp_config.json`; `GUIDELINE.md` there is a user guide for the stack (Flutter) |
| `.agents/stack.json` | Which pack owns which folders (edit it if detection guessed wrong) |

Re-run the sync after installing or updating the CLI so the MCP config points to it.

### 4. Check your setup

```sh
coder-nexus doctor
```

## Using it

Once synced, talk to your agent in natural language or name a workflow directly:

| Workflow / Skill | When to use | Example prompt |
|---|---|---|
| **`dev-team`** | End-to-end feature delivery: Huly + Figma intake (`S-NN`, `W-NN`) at `Gate 1`, UI Kit & Clean Architecture design (`## UI/UX mapping`) at `Gate 2`, implementation plan at `Gate 3`, phase-by-phase coding/review, final QA (`Test Runner`), and a single visual `as-built.md` (`Docs Writer`). | *"Implement task ABC-12"* or *"Build the order screen from this Figma link"* |
| **`bug-squad`** | Reproduce a bug, prove root cause & blast-radius impact, confirm severity (`S1–S4`) + fix level (`L1/L2/L3`), then fix and verify | *"Fix bug: the order list crashes when empty"* or *"Sửa lỗi task ABC-45"* |
| **`debug-investigation`** | Read-only investigation or runtime flow tracing with temporary `[DBG-<slug>]` logs (automatically cleaned up) into `diagnosis.md` | *"Debug: why does the order list show yesterday's data?"* or *"Trace luồng từ màn B sang C"* |
| **`feature-testing`** | Read-only scenario testing by `Test Runner` on the real app/browser/API into `test-run-report.md` | *"Test function A going from page B to C to D"* |

### Fixing a bug (`bug-squad`)
Report it, for example *"Fix bug: the order list crashes when empty"*. The `bug-squad` skill enforces a strict **4-Gate Anti-Rush Sequence** in `.superpowers/debug/<bug-slug>/` so the agent never jumps straight to editing code:
1. **Reproduce first**: `Bug Fixer` reproduces the failure via an uncommitted failing test or live runtime run (`NOT_REPRODUCED` stops immediately).
2. **Root cause & call-graph impact**: Pinpoints the exact `file:line` cause using git forensics / runtime traces and maps affected callers (`gitnexus` + `rg`).
3. **Classify & confirm**: Proposes severity (`S1–S4`) and fix level for your confirmation before touching production code:
   - **L1 (Quick patch)**: Fixed by `Bug Fixer` (starting with a failing regression test) and verified by `Test Runner` without code review.
   - **L2 (Local fix)**: Follows `fixing-plan.md`, goes through `Code Reviewer`, and is verified by `Test Runner`.
   - **L3 (Escalate)**: Contract, schema, shared-code, or business-rule changes write `escalation-report.md` (with zero code edits) and hand off to `dev-team`.

### Debugging without fixing (`debug-investigation`)
Ask, for example *"Debug: why does the order list show yesterday's data?"* or *"Trace what happens from page B to C"*. The `debug-investigation` skill has `Bug Fixer` reproduce the bug or run the scenario, add tagged temporary logs (`[DBG-<slug>]`) when needed, and write `diagnosis.md` in `.superpowers/debug/<slug>/`. Every temporary log is removed and verified clean before it reports `DIAGNOSED`; no code change is kept. If you then want the bug fixed, it hands `diagnosis.md` directly to `bug-squad` without repeating the investigation.

### Testing a scenario (`feature-testing`)
Give a scenario in your own words or as a file, for example *"Test function A going from page B to C to D"*. The `feature-testing` skill has `Test Runner` turn it into cases, use default checks where you gave no expected result, run them on the app or API, and report `PASS`/`FAIL` per case with evidence in `.superpowers/test-runs/<slug>/`. It never writes tests or fixes code; any `FAIL` case can be handed directly to `bug-squad` on your confirmation.

### Task intake (optional)
Connect a task tracker so agents can read tickets. Credentials go into the project's local `.env`. **Make sure `.env` is in `.gitignore`.**

| Command | What it does |
|---|---|
| `coder-nexus setup huly` | Guided setup: workspace URL, then login |
| `coder-nexus setup huly --check` | Check that the configuration is complete (read-only) |
| `coder-nexus setup huly --reset` | Start setup again (e.g. expired session) |
| `coder-nexus my-tasks` | List your open tasks (`--all` for the whole workspace) |
| `coder-nexus task-detail <ID>` | Show a task with its acceptance criteria |
| `coder-nexus task-detail <ID> --download` | Also save attachments and linked designs under `.superpowers/sources/<ID>/` |

You can also just ask the agent to *"set up Huly"*.

### Figma two-layer extraction (optional, read-only)
Add `FIGMA_TOKEN=…` to `.env`. Linked frames are downloaded with `task-detail --download`, or fetch one directly:

```sh
coder-nexus figma fetch "https://www.figma.com/design/<key>/<name>?node-id=<id>"
```

Each fetch writes per-screen renders (`<stem>-SNN.png` or `--format jpg`), a file-level W3C DTCG `tokens.json` (extracted from Figma styles, bound variables, and component sets), a Framelink-inspired normalized `<stem>.spec.json` (`screens`, `workflows_inferred`, and normalized node `tree` referencing `tokens.json`), and the raw `<stem>.json` ground truth.

### Stack setup

```sh
coder-nexus setup flutter --check
```

```sh
coder-nexus setup flutter --profile external-standard
```

Profiles tell the agent where a Flutter project's shared building blocks come from:

| Profile | Use when the project… |
|---|---|
| `external-standard` | has no shared component library; use standard framework widgets |
| `external-structured` | has its own design system or shared components (`lib/core/`, `lib/shared/`); reuse them |
| `imespro` | resolves the internal sibling packages (`../app-core`, `../app-util`, `../app-ui-kit`) |

When a profile is selected (saved in `.superpowers/setup.json`), syncing or running `setup flutter` automatically injects that profile's reference guides into the installed Flutter skills under `.agents/plugins/coder-nexus/skills/`. `coder-nexus setup flutter` also runs step `[4/6] Developer tools`, the same as `setup tools --pack flutter` below. Missing tools never make the setup gate fail.

### Developer tools
The skills check code with real tools (linters, type checkers, test helpers) instead of relying on the agent's reading alone. Set them up per pack:

| Command | What it does |
|---|---|
| `coder-nexus setup flutter` | Flutter project setup **and** the Flutter tools |
| `coder-nexus setup tools --pack flutter` | Only the Flutter tools |
| `coder-nexus setup tools --pack backend` | Only the backend tools |
| `coder-nexus setup tools --pack <pack> --only <a,b>` | Only the named tools, optional ones included (e.g. `--only mocktail,dart_code_linter`) |
| `coder-nexus setup tools --pack <pack> --check` | Read-only: what is installed and what is missing |

It lists the planned changes and asks once before applying them (`--yes` skips the question). Dev dependencies go through the stack's own package manager, missing lint or type config is added without rewriting yours, and tools it cannot install get an install hint. Results are recorded in `.agents/coder-nexus.setup.json`. Syncing the plugin never runs it and never edits your project files.

| Kind | Backend | Flutter |
|---|---|---|
| Dev dependencies (default) | `pytest`, `pytest-asyncio`, `ruff`, `mypy` (`uv add --dev`) | `flutter_lints`, `mocktail`, `bloc_test` (`flutter pub add --dev`) |
| Dev dependencies (optional, with `--only`) | `pytest-cov`, `import-linter`, `pytest-alembic`, `pytest-randomly` | `very_good_analysis`, `dart_code_linter` |
| Config (added only when missing) | `[tool.ruff.lint]`, `[tool.mypy]` in `pyproject.toml` (`ruff-config`, `mypy-config`) | lint include and rules in `analysis_options.yaml` (`analysis_options`) |
| Installed for your user | `ripgrep`; `mockoon-cli` (optional) | `ripgrep`, `mockoon-cli` |
| Run through `uvx` | `pip-audit` | — |
| Checked only (install hint) | `git`, `uv`, `docker`; `psql` (optional) | `git`, `flutter`, `dart`; `adb`, `xcrun` (optional) |

### Skill Factory (new in 3.0)
Fixed packs give every project the same rules. The Skill Factory instead gives you **generators**: each one studies your workspace, asks you to confirm the key decisions, and writes a skill that fits your code, stack and conventions. The generated skill lives in `.agents/skills/` and is yours to edit. When it covers the same topic as a pack skill, the Code Writer and Code Reviewer follow **your** skill.

```sh
skill-factory list
```

```sh
skill-factory get -p coder
```

Then ask your agent to run a generator, e.g. `/create-clean-code-skill` in Claude Code. It writes the real skill (for example `.agents/skills/clean-code/`) and trial-runs it on your code.

| Package | Generators (`create-…-skill`) |
|---|---|
| `coder` | clean-architecture · incremental-implementation · clean-code · unit-testing · code-simplification · bug-hunt · root-cause-debugging · secure-coding-standards · database-migrations · git-workflow · api-contract-design |
| `reviewer` | code-review · bug-hunt · clean-architecture · clean-code · unit-testing · secure-coding-standards · database-migrations · security-review · git-workflow · api-contract-design |
| `security` | secure-coding-standards · security-review |
| `quality` | quality-planning · quality-environment · quality-acceptance · quality-reporting · visual-quality · domain-knowledge |
| `planning` | domain-knowledge · requirements-specification · change-impact-analysis · implementation-planning · api-contract-design |

| Command | What it does |
|---|---|
| `skill-factory list [-p <package>] [--json]` | List generators with version, package and scope |
| `skill-factory get <name> [<name>…]` | Copy one or more generators (`clean-code` or `create-clean-code-skill`) |
| `skill-factory get -p <package>` | Copy a whole package |
| `skill-factory get .` | Copy everything |

`get` writes the generator to `.agents/skills/create-*-skill/`, a shared core to `.agents/skill-factory-core/`, and a link under `.claude/skills/` so Claude Code can run it. Use `--force` to refresh existing copies and `--workspace PATH` to target another folder. Copies you already have are never overwritten without `--force`; compare them with a newer generator and keep what you want. Details: [Skill Factory guide](docs/guides/skill-factory.md).

### Inspect the MCP tools

```sh
npx @modelcontextprotocol/inspector coder-nexus serve
```

## Working on Coder Nexus

Requirements: Python 3.12+, [`uv`](https://docs.astral.sh/uv/), Node.js (for packaging).

```sh
uv sync
```

```sh
uv run pytest -q
```

```sh
uv run coder-nexus install-plugin --pack flutter --workspace /path/to/project
```

```sh
npx @vscode/vsce package --no-dependencies --readme-path README.extension.md
```

| Path | Content |
|---|---|
| `src/coder_nexus/` | CLI and MCP server |
| `src/skill_factory/` | `skill-factory` CLI and the generator library |
| `plugins/` | Agent roles, skills and stack packs (built by `python -m coder_nexus.plugin_build`) |
| `extension.js` | VS Code extension |
| `docs/guides/` | Detailed guides |
| `README.extension.md` | Page shown on the extension marketplace |

Releases are published by pushing a `vX.Y.Z` tag.

## Ground rules for agents

- Agents cannot approve their own gates.
- Task tracker and Figma access is read-only.
- A result is reported as `PASS` only with evidence. Otherwise it stays `BLOCKED`, `NOT_RUN` or `UNVERIFIED`.

## More

- [Installation guide](docs/guides/installation.md)
- [Flutter guide](docs/guides/flutter.md)
- [Skill Factory guide](docs/guides/skill-factory.md)
- [Release notes](https://github.com/pzakhim/coder-nexus/releases)

License: MIT