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
npx skills add nextstage-brasil/skills --skill ns-autonomous -a claude-codeWhat 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-autonomousagainstplan.mdand execute everything autonomously - Take this task description and implement it via
ns-autonomousin an isolated branch - Use
ns-autonomousas 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-code2Manually: put the files in place
~/.claude/skills/ns-autonomous/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/ns-autonomous/
1Skills CLI (Vercel)
npx skills add nextstage-brasil/skills --skill ns-autonomous -a codex2Manually: put the files in place
.agents/skills/ns-autonomous/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add nextstage-brasil/skills --skill ns-autonomous -a cursor2Manually: put the files in place
.cursor/skills/ns-autonomous/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install nextstage-brasil/skills skills/ns-autonomous2Manually: put the files in place
.github/skills/ns-autonomous/SKILL.md1Skills CLI (Vercel)
npx skills add nextstage-brasil/skills --skill ns-autonomous -a gemini-cli2Platform CLI
gemini skills install https://github.com/nextstage-brasil/skills --path skills/ns-autonomousManually: put the files in place
.devin/skills/ns-autonomous/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add nextstage-brasil/skills --skill ns-autonomous -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
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