Description

Software Teams

A team of specialist AI agents that plan, build, review, and ship features end-to-end.

  

You:   /st-create-plan "Add password reset flow"
ST:    Plan written. 4 tasks across backend, frontend, qa. Approve?
You:   approved
You:   /st-implement-plan
ST:    Wave 1: backend done (commit 1a2b3c). Wave 2: frontend done (commit 4d5e6f).
       QA pass: 12/12 tests added and passing. Ready to ship?
You:   /st-generate-pr
ST:    PR #42 opened.

That’s the loop. Plan → approve → implement → ship. One Claude Code session.

—

Why use this

Claude Code has built-in subagents. Software Teams sits on top of them and adds the workflow — the specific orchestration patterns that turn “I have a ticket” into “I have a merged PR” without you driving each step.

| You want… | Reach for |
|———–|———–|
| To ask Claude one focused question | Claude Code itself |
| To dispatch one specialist for a clear task | Claude Code’s /agents |
| A repeatable plan-then-build flow with multiple specialists, atomic commits, and a generated PR | Software Teams |
| Autonomous execution from a GitHub issue or PR comment | Software Teams (GitHub Actions mode) |
| To compose specialists visually — one Claude per node, canvas handoff, Slack human-in-the-loop, ClickUp/Datadog triggers | Software Teams (n8n nodes) |

The differentiators:

• Three-tier planning keeps prompt context tight. The planner writes a spec.md (the what), an orchestration.md (the how — task graph, agent pinning, sequencing rules), and one T{n}.md slice per task. When a specialist is spawned for task T3, it loads only T3’s slice and the SPEC sections that slice cites — not the whole plan, not the other tasks. On a 12-task plan this typically saves 60–80% of per-spawn tokens.
• Native Claude Code subagents. No identity-injection preambles. Specialists are real .claude/agents/.md files generated from the canonical specs in packages/cli/agents/.
• Native rules that learn from PR review. When a reviewer says “we always use path aliases here,” the feedback-learner extracts the team convention, dedupes it against CLAUDE.md, native rules, and auto memory, then writes it to path-scoped .claude/rules/{frontend,backend,…}.md. Machine-local discoveries stay in auto memory.
• Four runtimes, one codebase. The same specialists run from inside Claude Code (/st-*), from your terminal (software-teams …), from a GitHub PR comment (Hey software-teams …), or as n8n community nodes on a self-hosted visual canvas.

—

Quickstart (60 seconds)

Pick one of two install paths. Native skills require Claude Code 2.1.218 or
newer (claude --version).

Option A — Claude Code plugin (recommended if you live inside Claude Code):

/plugin marketplace add zottiben/software-teams
/plugin install software-teams@websitelabs

Then in your project: /st-init (the explicit namespaced form is
/software-teams:init).

> Self-contained — the plugin ships with a bundled CLI (dist/index.js, Bun-native). No global install needed; everything runs inside the plugin. Plugin init uses --state-only mode: it scaffolds .software-teams/ plus shared hooks/settings wiring, but generates no project skill or agent copies — the plugin supplies those natively.

Option B — Standalone CLI (recommended if you also want the terminal commands and GitHub Actions runtime):

bun add -g @websitelabs/software-teams
or:
npm i -g @websitelabs/software-teams
cd ~/code/your-project
software-teams init

The plugin path sets up .software-teams/ (state, plans, rules) only — the plugin supplies skills and agents natively. The CLI path sets up .software-teams/, .claude/skills/st-*/, .claude/agents/ (34 specialists), and a CLAUDE.md routing block. Pass --state-only to any init call to skip generated project skill/agent copies while still installing shared hooks and settings wiring.

Now from inside Claude Code in that project:

/st-create-plan "Add a /healthz endpoint with a 200 response and a basic test"

The planner spawns, scans your codebase, and writes a plan. Reply approved to lock it. Then:

/st-implement-plan

The orchestrator picks specialists, runs them in dependency order, and posts a summary when each task is done. From there: /st-commit, /st-generate-pr, ship.

—

Three ways to drive it

Inside Claude Code — slash commands trigger the workflow:

/st-create-plan 
/st-implement-plan
/code-review 

From the terminal — same workflows, scriptable:

software-teams plan "add password reset flow"
software-teams implement
software-teams quick "fix the broken login button"
software-teams review 42
software-teams pr

From a GitHub PR/issue comment — autonomous mode, runs in Actions:

Hey software-teams plan add password reset flow
Hey software-teams implement
Hey software-teams review

The action handles plan-then-build, posts progress comments, opens the PR. See GitHub Actions setup for the one-time wiring.

—

What’s actually shipping

The headline workflows are the ones in the Quickstart. Under the hood:

• A planner that produces three-tier plans by default and falls back to single-tier for trivial work.
• A complexity router that decides whether one specialist handles a task or whether to fan out into wave-based parallel execution.
• A QA gate that runs after every task and can halt the orchestrator on critical findings.
• Native project rules under .claude/rules/. Cross-cutting general.md loads at startup; backend, frontend, testing, and DevOps conventions load only when matching files are touched.
• Worktree integration for isolated environments when you want the agent to work on a branch without touching your local checkout.

Full reference: software-teams.md.

—

Slash commands

Both installations accept the common bare /st-* names. Plugin users can also
use the explicit /software-teams:* namespace. Native /verify and
/code-review replace the former Software Teams duplicates. Skills with
operational side effects are direct-user-only and cannot be invoked by Claude.

| Skill | npm CLI prefix | Plugin prefix | What it does |
|—|—|—|—|
| init | /st-init | /software-teams:init | One-time setup in the current project |
| build | /st-build | /software-teams:build | Read-only state-aware guide to the next workflow step |
| create-dev-plan | /st-create-dev-plan | /software-teams:create-dev-plan | Write one human-executed developer guide in an isolated dev-planner fork |
| create-plan | /st-create-plan | /software-teams:create-plan | Plan a feature (three-tier by default) |
| review-plan | /st-review-plan | /software-teams:review-plan | Review a plan for one-shot readiness (consistency, contradictions, quality) via software-teams-quality; defaults to the current plan, [plan-name] [plan-part] to target one. Re-runnable until it passes, then auto-approves. Recommended by create-plan but not required. |
| implement-plan | /st-implement-plan | /software-teams:implement-plan | Execute the current plan (add --workflow for deterministic execution, --isolate to run in a worktree, --team for agent-teams) |
| compile-workflow | /st-compile-workflow | /software-teams:compile-workflow | Compile an approved three-tier plan into a deterministic Claude Code Workflow and optionally run it |
| verify (native) | /verify | /verify | Build/run the app and verify behavior using Claude Code’s recorded project recipe |
| quick | /st-quick | /software-teams:quick | One-shot focused change, no orchestration |
| code-review (native) | /code-review | /code-review | Review changes with Claude Code’s native reviewer and ReportFindings output |
| pr-feedback | /st-pr-feedback | /software-teams:pr-feedback | Address PR review comments and learn rules |
| commit | /st-commit | /software-teams:commit | Conventional commit |
| generate-pr | /st-generate-pr | /software-teams:generate-pr | Open a pull request |
| status | /st-status | /software-teams:status | Show current state and next action |
| statusline | /st-statusline | /software-teams:statusline | Install/remove a statusline showing plan · phase · wave · task (needs python3) |
| routines | /st-routines | /software-teams:routines | Recommended recurring routines via /loop (local) and /schedule (cloud) |
| orchestrator-mode | /st-orchestrator-mode | /software-teams:orchestrator-mode | Toggle Orchestrator-Only Mode (on|off|status) — restricts the main thread to read / plan / delegate code changes while still letting it manage and ship the work (commit, push, install, build, open PRs); Edit, Write, NotebookEdit, and code-mutating Bash (sed -i, tee, >/>> redirects, rm/mv/cp, destructive git) are hard-blocked by a PreToolUse hook (see templates/.claude/hooks/orchestrator-deny-bash.sh for the full deny list). Specialists invoked via Agent are unaffected. Per-project only. |
| ask-questions | /st-ask-questions | /software-teams:ask-questions | Toggle the Ask Clarifying Questions policy (on|off|status) — overrides the Claude Code harness’s hardcoded auto-mode reminder that tells Claude to “work without stopping for clarifying questions.” When on, Claude and sub-agents are told to ask substantive questions about ambiguous architectural/scope decisions even in auto permission mode. No hooks — pure prompt-layer policy. Per-project only. |

Worktrees are Claude Code’s: start a session with claude --worktree , ask
Claude to work in one, or set isolation: worktree on a subagent. List gitignored
files like .env in .worktreeinclude to have them copied in. Software Teams adds
only software-teams provision-worktree, which runs your adapter’s database and
web-server setup inside a worktree the harness already created.

For non-standard applications, run /run-skill-generator once or let /verify
record the working launch recipe in .claude/skills/verify/SKILL.md; commit that
project-specific recipe. Deterministic adapter gates remain available from the
terminal as software-teams verify. /code-review uses Claude Code’s native
review flow and structured ReportFindings result instead of a parallel ST
review prompt.

—

Upgrading from 0.13.x

See MIGRATING.md. software-teams init performs the migration;
it is idempotent and preserves content you wrote.

—

GitHub Actions setup

software-teams setup-action

This drops .github/workflows/software-teams.yml into your repo. Then:

1. Add ANTHROPICAPIKEY to your repo secrets.
2. (Optional) Set SOFTWARETEAMSAUTHENABLED=true and SOFTWARETEAMSALLOWEDUSERS to restrict who can trigger.
3. Comment on any issue/PR:

   Hey software-teams plan 
   Hey software-teams implement
   Hey software-teams quick 
   Hey software-teams review
   Hey software-teams do 
   

The action threads its responses, supports refinement (change task 2…), and respects an explicit approved gate before implementation. Plans live in the cache; rules can be persisted to your repo or pushed to a shared rules repo across projects.

—

Run it as n8n nodes

Software Teams also ships as a set of n8n community nodes — run each specialist as a node on a visual workflow canvas, hand off between them over the wire, and pause for human review in Slack. Published as @websitelabs/n8n-nodes-software-teams.

> Self-hosted n8n only. The nodes execute the claude binary inline on the n8n worker, which n8n Cloud forbids. Each worker needs the claude CLI on PATH and an Anthropic key in the credential.

Install via Settings → Community Nodes → Install in your self-hosted instance:

@websitelabs/n8n-nodes-software-teams

Five nodes appear under the Software Teams palette section. They share one encrypted Software Teams API credential and pass a single typed NodeEnvelope between them:

| Node | What it does |
|——|————–|
| Trigger Ingestion | Fetches PII-scrubbed context from a ClickUp ticket or Datadog issue and emits the initial envelope |
| Agent | Runs one specialist for one turn via claude (Agent tool disabled); chain A→B for multi-agent handoff |
| Orchestrator | Plans an epic and emits one envelope per wave-task in dependency order; run state persists for resumable partial failures |
| Slack HITL | Posts a question to Slack, pauses the workflow, and resumes the agent with the human’s reply folded into context |
| Output | Opens a GitHub PR (or issue) from the final envelope |

Secrets live only in n8n’s encrypted credential store — never in node parameters, output, or execution logs.

Can’t install the package? (n8n Cloud, or a locked-down worker) — the same engine is exposed as CLI verbs (software-teams ingest | agent-turn | orchestrator-turn | output) you can wire into n8n’s built-in Execute Command nodes. See the manual recipe.

Full node reference, parameters, the inter-node data contract, and an importable example workflow: packages/n8n/README.md.

—

The specialists

Software Teams ships 33 specialist agents organised by team. You don’t pick them by hand — the planner pins each task to the right specialist via the agent router, and the orchestrator spawns them. Listed here for transparency, not as a UX surface you need to memorise.

Show full roster

| Team | Specialists |
|——|————-|
| Engineering | backend, frontend, architect, programmer, debugger, perf-analyst, security |
| Product & Research | planner, dev-planner, researcher, phase-researcher, product-lead, ux-designer |
| Quality | quality, qa-tester, verifier, plan-checker |
| DevOps | devops |
| Delivery | committer, pr-generator, pr-feedback, feedback-learner |
| Oversight | producer, head-engineering, codebase-mapper |
| Game development | game-designer, game-producer, game-engineer, game-ai-engineer, game-art-pipeline, game-devops, game-qa, game-tech-artist |

Each specialist is a .claude/agents/software-teams-.md file generated by software-teams sync-agents from the canonical sources in packages/cli/agents/. Re-run sync-agents after upgrades to refresh.

—

Configuration

Software Teams runtime state lives under .software-teams/; committed team conventions use Claude Code’s native .claude/rules/:

.software-teams/
├── state.yaml          # current plan, progress, review status
├── config/
│   ├── config.yaml     # workflow + model config
│   └── adapter.yaml    # tech stack + quality gates
├── plans/              # spec.md / orchestration.md / T{n}.md slices
├── persistence/        # codebase index, spawn ledger
└── feedback/           # PR feedback drafts (when --no-comments)

Native rules are written to .claude/rules/{general,backend,frontend,testing,devops}.md; domain files use paths: frontmatter while general.md is startup-loaded.

Project-type adapters (adapters/.yaml) define quality gates per stack — e.g. PHP/Laravel runs composer test and composer cs, TypeScript runs bun test and bun run typecheck. Override via .software-teams/config/adapter.yaml.

Generated .claude/ artefacts & .gitignore

In CLI mode, software-teams init also generates Claude Code artefacts:

.claude/
├── agents/software-teams-*.md   # 34 specialist specs (from packages/cli/agents/)
├── skills/st-/SKILL.md         # native /st- skills
├── hooks/*.sh                   # quality gate, state-context (SessionStart), orchestrator-mode, team gate
├── statusline/                  # the optional statusline renderer
├── settings.json                # tool allowlist + hook wiring
├── AGENTS.md                    # generated agent catalogue
├── rules/                       # native path-scoped conventions + ST doctrine
└── CLAUDE.md                    # routing block

Generated skills, agents, hooks, settings, catalogue, CLAUDE.md, and the framework-owned rules/software-teams.md are gitignored by default. Learned category rules (general.md, backend.md, frontend.md, testing.md, devops.md) are deliberately not ignored: they are team conventions intended for version control. .software-teams/ remains ignored runtime state.

To version-control any artefact (e.g. a shared settings.json, or your project’s CLAUDE.md), remove that line from the managed block. Custom agents you add under .claude/agents/ that aren’t named software-teams-* stay tracked — the ignore is prefix-scoped. (Plugin/--state-only installs generate no project skill or agent specs — the plugin supplies them natively; hook/settings infrastructure is still installed.)

—

Status

• Stable: planning, implementation, commit, PR generation, PR review, GitHub Actions runtime.
• Recent: deterministic Workflow compiler (compile-workflow / --workflow); automatic quality-gate + state-durability hooks; on-demand verify; worktree-isolated runs (--isolate) on Claude Code’s native worktrees; a plan/phase/task statusline; LSP for code-touching agents; recurring routines; and experimental agent-teams specialist-to-specialist collaboration (--team).
• Next: (open an issue to weigh in)

git clone https://github.com/zottiben/software-teams
cd software-teams
bun install
bun run build
bun test