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 expert-squad 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 enforces hard quality contracts per role, produces replayable artifacts, and chains stages automatically — start anywhere, it runs the rest until you say stop.

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

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

• Hard quality contracts: every role has a non-negotiable requirements table (e.g. PRD must have Given-When-Then scenarios; architecture must compare at least two options; QA must record verified or honestly-unverified evidence). Failed contracts block the next stage unless you explicitly override.
• Artifact-driven: every stage writes a real file under .boss/<feature>/. Progress is judged by artifacts on disk, not by what the agent claims.
• Continuation chain: start at any stage (/boss:pm, /boss:dev, ...) and Boss auto-runs every downstream stage until ship or until you stop it. No manual hand-offs.
• Engineering principles: the squad shares ten principles — prove it works, fix root causes, build the lever, model the domain, boundary discipline, sequence verifiable units, test behavior, minimize reader load, structured experience, autonomous rules. Each agent cites the principle it applies.
• TDD by default: development stages must write a failing test first, watch it go RED, then write the minimum code to make it GREEN.
• 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 for UI prototyping. See PRIVACY.md.
• Deterministic evals: captured transcripts are scored without calling a real LLM.

Boss is not a single monolithic command. Each slash command is an entry point; by default it auto-runs all downstream stages.

The full chain:

pm → architect → ui → review → tasks → dev → qa → ship

Stop the chain by saying "stop", "only do this step", or passing --stop-after <stage>.

Boss is a skill you install into your coding agent. Distribution is marketplace-only: no npm package, no global binary.

Claude Code — plugin marketplace (recommended):

/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

The lowest-cost first run is a read-only review against existing code:

/boss:review

You get tech-review.md (and plan.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 writes qa-report.md.

Inside your coding agent:

/boss Build a local personal todo app --skip-ui

• --skip-ui skips the UI design stage (pure API/CLI projects).
• --quick skips routine clarification prompts.

Artifacts live under .boss/<feature>/:

.boss/todo-app/
├── prd.md
├── architecture.md
├── ui-spec.md
├── ui-design.json
├── tech-review.md
├── plan.md
├── tasks.md
├── qa-report.md
└── deploy-report.md

Each Markdown artifact starts with a ## 摘要 (summary) section so downstream agents can read the conclusion first.

User request
  → requirement clarification (unless --quick)
  → PM: requirement discovery → prd.md
  → Architect: system design → architecture.md
  → UI Designer: UI/UX spec → ui-spec.md + ui-design.json  (skip with --skip-ui)
  → Tech Lead: technical review + implementation plan → tech-review.md + plan.md
  → Scrum Master: task breakdown → tasks.md
  → Frontend / Backend: TDD implementation
  → QA: test execution, bug reports, evidence → qa-report.md
  → DevOps: build, deploy, health checks → deploy-report.md

Boss has two layers of quality control:

• Hard requirements per role: each agent's prompt defines a non-negotiable requirements table. The agent self-checks before handing off; a failed contract blocks the next stage.
• Quality gates: real commands whose verdicts are recorded in the stage artifact.

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.

Boss is local-first and makes no outbound network requests by default. The only network surface is an opt-in, loopback-only (127.0.0.1) HTML prototype server used during the UI design stage.

Release provenance lives in .agents/plugins/provenance.json. It pins the repository HTTPS URL, immutable source commit SHA, publisher identity, and SHA-256 digests for plugin manifests. Verify it with:

npm run provenance:verify

See PRIVACY.md for the full data and network boundary.

.boss/<feature>/
├── prd.md              # PM — product requirements
├── architecture.md     # Architect — system design
├── ui-spec.md          # UI Designer — UI/UX spec (skipped with --skip-ui)
├── ui-design.json      # UI Designer — renderable design JSON
├── tech-review.md      # Tech Lead — technical review
├── plan.md             # Tech Lead — implementation plan
├── tasks.md            # Scrum Master — task breakdown
├── qa-report.md        # QA — test evidence
└── deploy-report.md    # DevOps — deployment record

Boss evals score captured fixtures without starting a real LLM:

npm run evals
npm run evals:release

The release eval includes release-evidence and pipeline-compliance checks — it verifies artifact recording, avoidance of deprecated runtime commands, and expert-squad orchestration behavior.

See test/evals/README.md.

Requirements:

• Node.js >= 22.18

Setup:

git clone https://github.com/echoVic/boss-skill.git
cd boss-skill
npm install
npm run typecheck
npm test

Useful scripts:

npm run typecheck    # tsc --noEmit
npm test             # vitest (unit + skill behavior + evals)
npm run test:skills  # skill behavior tests only
npm run evals        # deterministic transcript evals
npm run lint         # biome ci

boss-skill/
├── skill/                      # Skill bundle installed into coding agents (self-contained)
│   ├── SKILL.md                # Main orchestration entry (invariants + index)
│   ├── agents/                 # Role prompts (boss-pm, boss-architect, ...)
│   ├── commands/               # Slash commands (/boss, /boss:pm, ...)
│   ├── references/             # Shared methodology (principles, quality-gate, ...)
│   ├── skills/                 # Per-domain methodology skills (pm/, qa/, devops/, ...)
│   └── templates/              # Artifact templates (.md.template)
├── test/                       # Vitest, skill behavior, and eval tests
├── scripts/                    # release.js, provenance.js
├── docs/                       # Historical specs, plans, reports
├── examples/                   # Example projects
├── .claude-plugin/             # Claude Code plugin manifest + marketplace
├── .codex-plugin/              # Codex plugin manifest + marketplace
├── .agents/plugins/            # Repo-scoped plugin marketplace + provenance
├── tsconfig.json               # Typecheck-only config (no emit)
└── package.json                # Private dev workspace (never published)

Use the release script so version numbers stay synchronized across package metadata and skill/plugin manifests:

npm run release -- patch
npm run release -- minor
npm run release -- major
npm run release -- 4.1.0
npm run release -- 4.1.0 --dry-run

The release script checks for a clean worktree, runs the full verification chain (typecheck, lint, test), syncs versions across all manifests, verifies consistency, creates a commit and tag, and pushes. Release is the git tag: marketplaces read the repository — there is no npm publish step and no build step.

See CONTRIBUTING.md.

Boss is inspired by BMAD: Breakthrough Method of Agile AI-Driven Development, and by the "write less, higher quality code" philosophy. The expert-squad model keeps the harness lean — no runtime state machine, no event sourcing, no hooks — while preserving hard quality contracts and artifact-driven collaboration.

Read more in DESIGN.md, skill/references/bmad-methodology.md, and skill/references/principles.md.

MIT