boss-skill

Languages / 语言 / 言語 / 언어 / Idiomas / Langues: English · 中文 · 日本語 · 한국어 · Español · Français · Português

This project is part of the AtomGit G-Star Incubation Program. GitHub is the canonical repository; AtomGit provides an automatically synchronized mirror for faster access in China. Please submit issues and pull requests on GitHub.

GitHub: https://github.com/echoVic/boss-skill · AtomGit mirror: https://atomgit.com/echoVic/boss-skill

Boss is an auditable agent-team workflow for coding agents. It turns one coding agent into a structured engineering team: PM, Architect, UI Designer, Tech Lead, Scrum Master, Frontend, Backend, QA, and DevOps. Unlike prompt-only agent teams, Boss adds runtime state, append-only events, quality gates, deterministic evals, hooks, and replayable artifacts.

Boss works with Claude Code, Codex, OpenClaw, Antigravity, and Hermes.

Why Boss

Prompt-only orchestration can sound organized, but it usually cannot prove that the plan was followed, tests were run, gates passed, or state was not hallucinated. Boss is built around evidence:

• Zero-network by default: no telemetry, no phone-home, no remote LLM proxy. The only network surface is an opt-in loopback preview server bound to 127.0.0.1. A source-level network-boundary test fails CI if anyone reintroduces an outbound client. See PRIVACY.md.
• No shell injection: wave verification runs through structured argv (waves.json), never through a shell. Cloning a malicious repository cannot smuggle commands via tasks.md.
• Event-sourced runtime: pipeline state is appended to .boss/<feature>/.meta/events.jsonl and projected into read-only execution state.
• Verifiable gates: QA, deployment, and final checks run as real commands whose verdicts are recorded as events. boss gate final and boss doctor fail when a completed stage carries a failed gate. Enforcement still relies on the orchestrating agent honoring the protocol; the CLI makes the verdict checkable, not unavoidable.
• Replayable artifacts: PRDs, architecture docs, task lists, QA reports, deploy reports, and summaries live under .boss/<feature>/.
• Deterministic evals: captured transcripts can be scored without calling a real LLM.
• Agent-friendly CLI: commands support JSON output, --describe, dry runs, bounded fields, and structured errors.
• Self-verifiable: run boss doctor to confirm the resolved runtime, install locations, event-stream health, and network boundary — the zero-network claim is auditable, not just asserted.

Use One Role Or The Whole Team

Boss is not a single monolithic command. You can run one role against an existing project, or run the full pipeline from idea to delivery.

Quick Start

1. Install

Boss is a skill you install into your coding agent — not a tool that installs other skills. Distribution is marketplace-only: no npm package, no global binary. The skill ships with its own CLI (skill/cli/), which hooks and the agent invoke through node.

Claude Code — plugin marketplace (recommended; hooks come wired):

/plugin marketplace add echoVic/boss-skill
/plugin install boss@boss-skill

Codex — plugin marketplace:

codex plugin marketplace add echoVic/boss-skill

Then open the plugin browser (/plugins) and install boss.

Any agent — via the skills CLI (vercel-labs/skills, skills.sh):

npx skills add echoVic/boss-skill

It discovers boss from the repo, prompts for target agent / scope (project vs global) / install method, and records a skills-lock.json you can commit. Boss ships a single skill root, so the picker shows just boss — its internal methodologies travel with it.

For Codex and other copy-based installs, wire up the Boss hooks with the bundled CLI:

node <installed-skill>/cli/bin/boss.mts install

2. Try It On A Project You Already Have

The lowest-cost first run is a single role against existing code. It reads, it does not write:

/boss:review

You get tech-review.md under .boss/<feature>/ with risks, findings and severity. Nothing else in your repo is touched.

Want verifiable test evidence instead? /boss:qa runs the tests and the gates, and writes qa-report.md.

3. Run The Full Pipeline

Inside your coding agent:

/boss Build a local personal todo app --roles core --skip-deploy

• --roles core uses PM, Architect, Dev, and QA.
• --skip-deploy stops after implementation and test evidence.

4. Inspect Results

Boss ships its own CLI inside the skill — no npm install, no PATH setup. In the snippets below, <skill> is the directory that contains SKILL.md (for Claude Code plugin installs: <plugin-root>/skill; for copied installs, e.g. ~/.codex/skills/boss).

node <skill>/cli/bin/boss.mts status todo-app --json
node <skill>/cli/bin/boss.mts runtime inspect-pipeline todo-app

Expected artifact layout:

.boss/todo-app/
├── design-brief.md
├── prd.md
├── architecture.md
├── tasks.md
├── qa-report.md
└── .meta/
    ├── events.jsonl
    ├── execution.json
    └── workflow-plan.json

When To Use Boss

Rule of thumb: if you do not need a traceable .boss/ folder, you probably do not need the full /boss pipeline. Use a single role or let your coding agent edit directly.

No CLI Fallback

The CLI ships inside the skill, so a marketplace install always carries it. When node is unavailable or the CLI cannot be located, the workflow degrades to Markdown artifacts under .boss/<feature>/ instead of the event stream. The CLI is the auditability upgrade: event sourcing, replayable resume, deterministic evals, runtime gates, and structured diagnostics.

Boss does not mean "install once and get guaranteed autonomous delivery." It provides a runtime workflow and evidence gates; the active coding agent still has to follow the Boss protocol.

Installation Details

Marketplace installs copy (or link) the whole skill/ directory. The CLI ships as TypeScript source at <skill>/cli/bin/boss.mts and is executed directly by Node.js >=22.18 (native type stripping) — there is no build step, no npm package, and no global boss binary. Hooks reference it by full path.

Useful commands (run through the bundled CLI):

node <skill>/cli/bin/boss.mts install --dry-run
node <skill>/cli/bin/boss.mts uninstall
node <skill>/cli/bin/boss.mts path
node <skill>/cli/bin/boss.mts --version

Auto-detected targets for boss install:

Platform Support

Boss targets Node.js >=22.18 and runs on Linux, macOS, and Windows. The CLI ships inside the skill as TypeScript source that Node executes directly (native type stripping — no build step), shells out only through spawnSync with explicit argument arrays (never shell: true), and resolves npm/npx to their .cmd variants on Windows, so there is no POSIX-only assumption in the core pipeline.

Two capabilities depend on optional external tools and degrade gracefully when they are absent:

• WIP checkpoints (stash/commit/branch) require git and a git work