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:

• Event-sourced runtime: pipeline state is appended to .boss/<feature>/.meta/events.jsonl and projected into read-only execution state.
• Non-bypassable gates: QA, deployment, and final checks are modeled as runtime stages instead of loose instructions.
• 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.

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.

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? Still Works

Boss detects the boss CLI at runtime. Without it, the workflow can degrade 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.

Quick Start

1. Install

npm install -g @blade-ai/boss-skill
boss-skill

boss-skill auto-detects supported agents and installs the Boss skill bundle where possible.

For Claude Code plugin mode:

claude --plugin-dir "$(boss-skill path)"

2. Run A Lightweight 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.

3. Inspect Results

boss status todo-app --json
boss 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

Installation Details

npm install -g @blade-ai/boss-skill
boss-skill install

Useful install commands:

boss-skill install --dry-run
boss-skill uninstall
boss-skill path
boss-skill --version

Auto-detected targets:

Commands

Common slash commands:

/boss Build a todo app
/boss Add authentication to this existing project --skip-ui
/boss Build an API service --skip-deploy --quick
/boss Continue the previous task --continue-from 3
/boss Lightweight mode --roles core --hitl-level off
/boss:upgrade

Common options:

Boss CLI commands:

boss --help
boss status FEATURE
boss continue FEATURE
boss gate FEATURE
boss qa attack FEATURE
boss project init FEATURE
boss design preview FEATURE
boss packs detect
boss runtime inspect-pipeline FEATURE
boss runtime generate-summary FEATURE

Agent-facing boss commands use these common options where applicable; run --describe on a command for its exact JSON schema:

• --json: structured output; non-TTY stdout defaults to JSON
• --describe: JSON command schema
• --dry-run: structured action plan for writes or risky operations
• --json-input=<json|->: JSON input payload
• --fields=<a,b> and --limit=<n>: bounded output
• --yes: required only for high-risk non-interactive commands that need an extra confirmation

Structured errors are written to stderr as {"error":{...}} and include code, message, input, retryable, and suggestion.

Workflow

Boss follows a four-stage workflow:

User request
  -> requirement clarification
  -> Stage 1: PM, Architect, UI Designer
  -> Stage 2: Tech Lead, Scrum Master
  -> Stage 3: Frontend, Backend, QA, gates
  -> Stage 4: DevOps, deployment checks, summary

The full role set:

Runtime And Quality Gates

Boss has two layers of quality control:

• Hard constraints verified by code and CI: runtime events, protected execution.json, hooks, install matrix tests, harness scenarios, and Vitest coverage.
• Agent protocol constraints guided by the skill bundle: DAG dispatch, progressive reference loading, test evidence, and gate discipline.

Built-in gates:

Hooks are controlled by environment variables:

Runtime state is backed by .boss/<feature>/.meta/workflow-plan.json and .boss/<feature>/.meta/execution.json. The workflow definition records workflowHash, packHash, and artifact DAG hashes. Runtime resume uses boss runtime resume <feature> --from-run <run-id> to reload the plan, compare node inputs, and materialize execution.workflow.nextNodeIds for the next schedulable nodes. GateEvaluated / WaveVerified events update workflow node status when gates and evidence waves complete.

Security-Sensitive Surfaces

Boss intentionally keeps the published plugin manifest small: it declares only bundled skills and omits MCP servers, app manifests, and asset references unless those companion files exist. Codex hooks are installed by the boss-skill install flow, not by the marketplace manifest.

The npm package excludes local development agent settings such as .claude/settings.json and .claude/settings.local.json. Publishable plugin metadata lives under .claude-plugin/, `.codex-p