Skip to main content
skill CX Codex

ns-autonomous — Claude Code skill: autonomous execution engine

ns-autonomous — a skill for Claude Code, Codex, Cursor, Copilot and Gemini CLI that takes a local plan or pasted text and runs it autonomously inside an isolated worktree.

Apache-2.0 152 installs updated 2026-10-24

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add nextstage-brasil/skills --skill ns-autonomous -a claude-code
Open on GitHub

What ns-autonomous does

ns-autonomous runs on Claude Code, Codex, Cursor, GitHub Copilot and Gemini CLI. Both operating modes — standalone and as Phase 2 of ns-execution-gitlab-issue — share the same engine: planning-depth self-decision, doubt resolution, and multi-agent dispatch.

Before touching any application code, the skill creates an isolated worktree at .worktrees/{version_san}/ on branch work/{version_san}. Writing on main or the base branch is off-limits — if worktree creation fails, execution stops entirely. Two or more work units each get a dedicated subagent via ns-coder; parallel dispatch only applies to units with no DAG edge and disjoint file scopes. A single unit runs in the current session.

The review loop goes through ns-reviewer then ns-judge; the code gate requires an explicit Approved status. Destructive doubts in standalone mode pause execution and surface in chat. In Phase 2 mode they return to the calling skill as a structured event. The skill depends on ns-harness, ns-reviewer, and ns-judge at version 1.5.

What it helps with

  • Execute a local plan file autonomously without a GitLab issue
  • Split a multi-step task across parallel subagents
  • Keep all changes inside an isolated worktree away from main
  • Run the full review and judge-closure cycle inside one session
  • Act as the Phase 2 engine for ns-execution-gitlab-issue

Example prompts for the agent

  • Run ns-autonomous against plan.md and execute everything autonomously
  • Take this task description and implement it via ns-autonomous in an isolated branch
  • Use ns-autonomous as the Phase 2 engine for the current issue

How to install ns-autonomous

1Skills CLI (Vercel)

npx skills add nextstage-brasil/skills --skill ns-autonomous -a claude-code

2Manually: put the files in place

~/.claude/skills/ns-autonomous/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/ns-autonomous/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about ns-autonomous

How do I install ns-autonomous in Claude Code?

Run npx skills add nextstage-brasil/skills --skill ns-autonomous -a claude-code. The skill will then be available at ~/.claude/skills/ns-autonomous/SKILL.md.

What does ns-autonomous do?

It takes a local plan or pasted text and executes it autonomously: creates an isolated worktree, dispatches subagents when there are multiple work units, and runs ns-reviewer then ns-judge before closing the session.

When should ns-autonomous not be run directly?

When the task originates from a GitLab issue, do not invoke ns-autonomous standalone — it should only run as Phase 2 of ns-execution-gitlab-issue. Running it directly in that case bypasses the caller's state management.

Source text

SKILL.md · Apache-2.0
---
name: ns-autonomous
description: (NS) Autonomous execution engine — plans depth, resolves doubts from docs/specs, multi-agent work in an isolated worktree. Use for a local/pasted plan or "run this autonomously" without GitLab. Also Phase 2 under ns-execution-gitlab-issue (do not run standalone then). Not for single-step edits (ns-coder) or GitLab issues directly (ns-execution-gitlab-issue).
license: Apache-2.0
metadata:
  author: nextstage-brasil
  version: "1.5"
depends:
  - ns-harness
  - ns-reviewer
  - ns-judge
---

# Code Autonomous

Harness-aware execution engine: planning depth, doubt resolution, multi-agent dispatch, review gate — standalone pipeline or caller's Phase 2 engine.

## Workflow mode (mandatory)

Fixed workflow — named skill handoffs or harness bridges (`../../ns-harness/references/subagent-dispatch.md` spawn gate). Review gate: `../ns-reviewer/references/review-gate-workflow.md`. **MUST** `reviewer-agent` when available (else `ns-reviewer`); then `ns-judge` in-session only if `Code Review: Approved`. No Task persona substitutes. **≥2** units → **MUST** `coder-agent` per unit (`ns-coder`); **1** unit → follow `ns-coder` in A (worktree) — **MUST NOT** extra spawn. C2 / single-unit workers = implement only; **no** per-unit review — parent owns REV at closure.

## Isolation invariant (non-negotiable)

Skill **never** writes application code on main product checkout; **never** commits `main`/`master`/base/`SOURCE_BRANCH` unless human explicitly said work in place this run.

- Standalone + Engine: isolated `WORK_BRANCH` + `WORKTREE_ROOT` before any implementation edit.
- Worktree creation fails, or CWD/branch still main checkout / base → **stop**. No "continue on main to unlock plan".
- Sandbox restrictions (`Operation not permitted`, `.cursor/` paths) **not** permission to violate invariant.

## Session boot

See `../../ns-harness/references/session-boot.md`. **Complete Session boot (blocking)** there before any other step in this skill.

### After session boot — Engine and Standalone

**Engine mode:** caller may have already completed Session boot in Phase 0 — re-read `session-boot.md` only if context is missing.
**Standalone:** you own Session boot before step 1 of the standalone pipeline.

## Routing (read first)

Entry priority table: `../../ns-harness/references/code-skill-routing.md`. Standalone triggers: `references/entry-triggers.md`.

1. **Origin is a GitLab issue** (`ISSUE_URL` or issue reference) → entry priority **1** — follow `ns-execution-gitlab-issue` end to end; this skill only runs as its Phase 2 engine (**Engine mode** below). Do not run the standalone pipeline, do not touch GitLab state, do not create a worktree.
2. **Standalone autonomous** (local plan file, pasted text/plan, ad-hoc "implement this autonomously" without an issue) → entry priority **3** — run the **standalone pipeline**: own worktree, own state, own review loop.

See `references/routing.md` for Engine-mode I/O and anti-cycle rules with `ns-execution-gitlab-issue`.

## Engine mode (invoked by `ns-execution-gitlab-issue`)

Inputs (already resolved by the caller — this skill never creates them): issue payload, `WORKTREE_ROOT`, `WORK_BRANCH`, `SOURCE_BRANCH`.

1. **Planning-depth self-decision** — evaluate the issue payload and decide single work unit vs. light `requirements.md` + `tasks/task-NNN-*.md` + `execution-plan.md` under `docs/versions/{version_san}/sdd/`. See `references/planning-decision.md`.
2. **Doubt protocol** — self-ask, docs-first lookup, self-answer non-destructive doubts, escalate destructive ones as a structured event to the caller instead of mutating GitLab state; pause dependent units until resumed. See `references/doubt-resolution.md`.
3. **Multi-agent dispatch** — parse work units. **1 unit:** follow `ns-coder` in this session inside `WORKTREE_ROOT` (defer review to caller / standalone step 5). **≥2 units:** **MUST** dispatch `coder-agent` when available (else `ns-coder`) per unit; parallel only across units with no DAG edge and disjoint file scopes; sequential otherwise. Workers implement only — **no** per-unit `reviewer-agent`. See `references/multi-agent-dispatch.md` and `../../ns-harness/references/subagent-dispatch.md`.
4. **Checkpoint commits** — one commit per completed sequential unit or per completed parallel batch, inside the worktree; the caller squashes at delivery.
5. **Fix-loop entry point** — when re-invoked after `Rejected`, run **one** coder call on the whole map **verbatim** (no unit-count split, no “or units”). Skip units already done.
6. **Return to caller**: unit statuses, files changed, any open destructive doubt, and (first invocation only) a plan-based `estimate_seconds` hint — the caller applies `set_issue_estimate` only when the issue estimate is empty and the value is ≥ 60 (see `../ns-execution-gitlab-issue/references/time-tracking.md`).

## Standalone pipeline (non-GitLab origin)

Same internals as Engine mode, but this skill owns the whole run:

1. Resolve the descriptor — local plan path or pasted text. No MCP calls.
2. Infer `change_kind` (fix/feat), allocate `{version_san}`, create `docs/versions/{version_san}/sdd/` when artifacts needed.
3. **Create its own worktree**: `.worktrees/{version_san}/` + branch `work/{version_san}` from the resolved base branch, following `../../ns-harness/references/worktree-setup.md`. Path is under the **repo root**, never under `.cursor/`. On failure → abort (do not fall back to the main checkout) — see `references/standalone-pipeline.md`.
4. Planning-depth self-decision, doubt protocol (destructive doubt → chat-only gate, no GitLab actions available), multi-agent dispatch — identical logic to Engine mode.
5. **Internal review loop** — `../ns-reviewer/references/review-gate-workflow.md` (exhaustive map → one coder → `delta`; **`Approved` = 10** only): **MUST** `reviewer-agent` when available (else `ns-reviewer`) version-closure **code** mode. **Do not** run `ns-judge` until code `Approved`. Then in-session `../ns-judge/SKILL.md` (`closure`). Product files changed after judge Rejected: code review again then judge again.
6. Report per `review-gate-workflow.md` **Final report** fields plus `{version_san}`, worktree path, commit(s), and follow-ups. No GitLab board, no MR — unless `docs/context/gitlab-sync-config.md` exists and the human explicitly asked for one (out of scope for v1; standalone stays local-only otherwise).

See `references/standalone-pipeline.md` for the full flow.

## Stop and ask the human

| Condition                                                        | Action                                              |
| ------------------------------------------------------------------ | ---------------------------------------------------- |
| Destructive doubt (Engine mode)                                   | Return escalation event to caller — no chat pause here |
| Destructive doubt (standalone)                                    | Stop in chat, ask, resume with the answer as context |
| Worktree conflict for the same `{run_id}` (standalone)             | Stop unless explicit resume                          |
| `git worktree add` failed (permissions/sandbox/path)               | Abort — report path attempted; never fall back to main checkout or `.cursor/` |
| Still on `main`/`master`/base branch when about to edit code       | Abort — isolation missing; do not implement                                   |
| Human explicitly said "do not create a new branch / work in place" | Only then may edit the current branch; still never invent a `.cursor/` path |
| Base branch for standalone worktree unresolved                    | Stop — ask once                                      |
| Review `Blocked` or 3 rounds exhausted                             | Stop, report as blocked — do not fabricate success   |
| Engine mode invoked with a GitLab origin but no worktree/branch given | Stop — this is a caller contract violation, not a doubt |

## Related skills

| Skill                 | Role                                                       |
| ---------------------- | ------------------------------------------------------------ |
| `ns-execution-gitlab-issue` | GitLab flow owner — calls this skill for Phase 2             |
| `ns-coder`           | Implement via in-session (1 unit) or `coder-agent` (≥2 — **MUST** when available) |
| `ns-reviewer`        | Closure code gate via `reviewer-agent` (**MUST** when available) — not per unit |
| `ns-judge`           | Delivery proof in-session after `Code Review: Approved` |
| `ns-harness`    | Artifact layout, worktree mechanics, discovery               |

## References

| File                                | When                                                                |
| ------------------------------------ | --------------------------------------------------------------------- |
| `references/routing.md`              | Issue vs. standalone; Engine-mode I/O and anti-cycle with `ns-execution-gitlab-issue` |
| `references/entry-triggers.md`       | Priority 3 standalone entry phrases |
| `references/planning-decision.md`    | Self-evaluation heuristic: single unit vs. requirements+tasks+plan  |
| `references/doubt-resolution.md`     | Self-ask, docs-first lookup, destructive criteria, escalation shape |
| `references/multi-agent-dispatch.md` | DAG + disjoint-scope parallel rule, subagent prompt, checkpoint commits |
| `references/standalone-pipeline.md`  | Full non-GitLab flow: version alloc, own worktree, review loop      |

## Forbidden

- Review substitutes (`senior-tech-lead-reviewer`, `bugbot`, `security-review`, or any non-`ns-reviewer` code gate) — harness `reviewer-agent` is allowed; see `../ns-reviewer/references/review-gate-workflow.md`
- `ns-judge` before `Code Review: Approved`
- Reporting success without both `Approved`, or explicit **blocked** state
- Skipping re-review after a `Rejected` fix before closure

© nextstage-brasil · Apache-2.0 · nextstage-brasil/skills

Similar skills

All skills for Agent setup: memory, context, orchestration →

From the same set20

The whole set →
ns-requirements-enricher ns-requirements-enricher turns one GitLab issue or a pasted scope into an implementation brief for a coding agent, grounded in the existing code, with blocking questions kept in chat. CX Codex +1 163installs ns-best-practices ns-best-practices runs security header audits, checks basic accessibility, and reviews UI against Web Interface Guidelines. Generates structured findings with file locations. CX Codex +1 154installs ns-investigator The ns-investigator skill for Claude Code reads stack traces, logs and failing tests, identifies the root cause and proposes a minimal fix without implementing it. CX Codex +1 153installs ns-frontend-design ns-frontend-design — a skill for Claude Code, Codex, Cursor and other agents that builds production UI with deliberate typography, hierarchy and motion. Activates on pages, components, dashboards, forms and analytics views. CX Codex +1 153installs ns-e2e-tests The ns-e2e-tests skill structures Cypress end-to-end work across devices and keeps tests in a separate project. Use it when adding or refactoring specs. CX Codex +1 151installs ns-backend-tests ns-backend-tests — a skill for writing and running PHPUnit unit and integration tests directly in your IDE. Runs only in Docker containers, helping you quickly test a new Laravel project or rewrite existing tests. CX Codex +1 151installs ns-docs-writer ns-docs-writer — a skill for Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, and OpenCode that produces human-facing project docs: README files, docs/ guides, runbooks, and contributor markdown. CX Codex +1 151installs ns-coder ns-coder handles focused code changes such as fixes, small refactors, scripts, and migrations. Use it for ad-hoc work outside a multi-stage SDD handoff. CX Codex +1 151installs

Project sponsors

Companies that keep this analytics open