ccteams 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 toffyui
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,227 @@
+# ccteams — Agent-Team Package Manager for Claude Code
+
+Apply a pre-built team of Claude Code subagents to your project with one command, and switch teams whenever the work changes. An **agent team** is a bundle of subagents (with specific roles, expertise, and behaviors) plus orchestration rules that control how they collaborate — managed as a single unit in your project's `.claude/` directory.
+
+## Two ways to use it
+
+Use ccteams from the terminal, from inside Claude Code, or both — whichever fits your flow.
+
+https://github.com/user-attachments/assets/d6c89e7f-3945-484f-95a5-c69eb73cf035
+
+https://github.com/user-attachments/assets/ff71a9cf-a981-440b-8c35-c783dd559ad1
+
+```bash
+ccteams list                 # see the teams
+ccteams use <team>           # apply one (e.g. ccteams use go-api) to the current project
+```
+
+|                           | How you drive it        |                                                                                                                               |
+| ------------------------- | ----------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
+| **CLI** (`ccteams`)       | From your terminal      | `ccteams list`, `ccteams use <team>`, `ccteams current`                                                                       |
+| **Plugin** (`/ccteams:*`) | From inside Claude Code | `/ccteams:list-teams`, `/ccteams:use-team`, and `/ccteams:choose-team` — describe what you need and it picks the team for you |
+
+The CLI is the engine, so it's always installed; the plugin adds the in-Claude-Code slash
+commands (its skills call the CLI under the hood). Install one or both.
+
+## Install
+
+### 1. Install the CLI
+
+```bash
+npm install -g ccteams
+ccteams list
+```
+
+Verify it prints the available teams. You can already use ccteams now — apply a team with
+`ccteams use <team>` and restart Claude Code.
+
+### 2. Add the Claude Code plugin
+
+For slash commands inside Claude Code, add the marketplace and install the plugin:
+
+```
+/plugin marketplace add toffyui/ccteams
+/plugin install ccteams@ccteams
+/reload-plugins
+```
+
+Or restart Claude Code. The slash commands `/ccteams:list-teams`, `/ccteams:use-team`, and `/ccteams:choose-team` will then be available. (The plugin's skills call the `ccteams` CLI under the hood, so the CLI must be installed too.)
+
+## Updating
+
+```bash
+# CLI (new commands, new bundled teams)
+npm install -g ccteams@latest
+
+# Plugin (new or changed slash commands)
+/plugin marketplace update ccteams   # re-pull the latest from the repo
+/reload-plugins                       # or restart Claude Code
+```
+
+A full uninstall/reinstall is **not** needed. New slash commands reach users when the
+plugin's `version` is bumped (the plugin is versioned via `plugin.json`); a marketplace
+update followed by `/reload-plugins` picks them up.
+
+## Usage
+
+### Command Line (CLI)
+
+```bash
+ccteams list                      # All teams (compact, one line each)
+ccteams list --details            # Full descriptions and tags
+ccteams list --json               # Machine-readable JSON
+ccteams use <team>                # Apply a team to the current project
+ccteams use <team> --agent-teams  # Apply it AND enable agent-teams mode (optional)
+ccteams current                   # Show the currently active team
+ccteams --version                 # Print the version
+```
+
+After `ccteams use`, **restart Claude Code** so the team loads (see below).
+
+### Claude Code (slash commands — via the plugin)
+
+```
+/ccteams:list-teams                    # List available teams
+/ccteams:use-team <team-name>          # Apply a team
+/ccteams:choose-team <natural-language> # Find and apply a team by description ("for backend work", "frontend-focused", etc.)
+```
+
+## Available teams
+
+ccteams ships with these teams out of the box. Each is a builder + reviewer pair (except `research`, which is a single read-only researcher).
+
+| Team             | What it's for                                                                                                                                      |
+| ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `generalist`     | Stack-agnostic, end-to-end feature team: scope → design → build → QA → ship. Use when no stack-specific team fits or for general cross-stack work. |
+| `next-ts`        | Next.js (App Router) + TypeScript + Tailwind — RSC, Server Actions, type-safe data fetching, accessible UI.                                        |
+| `frontend`       | Framework-agnostic UI/UX and accessibility — UI work that isn't Next.js-specific, or focused on a11y/responsive/UX quality.                        |
+| `go-api`         | Go HTTP API backend — idiomatic services with `net/http` and `database/sql`.                                                                       |
+| `python-fastapi` | Python FastAPI + Pydantic v2 — async HTTP APIs with full type coverage and validation.                                                             |
+| `rails`          | Ruby on Rails — ActiveRecord, convention-over-configuration, the full Rails stack.                                                                 |
+| `debug`          | Stack-agnostic bug hunting — reproduce → root-cause → minimal fix → regression test.                                                               |
+| `research`       | Stack-agnostic technical research — compare options and produce a written recommendation. Writes no code.                                          |
+
+Run `ccteams list` for the full descriptions and tags, or `/ccteams:choose-team <what you need>` to let Claude pick one for you.
+
+## One team per session (and monorepos)
+
+ccteams applies **one team per project at a time**. `ccteams use <team>` is an exclusive switch: applying a new team cleanly replaces the previous one.
+
+This is partly a Claude Code constraint: subagents in `.claude/agents/` are **global to the project** and cannot be scoped to a subdirectory. You can't, for example, have the `next-ts` team active only in `apps/web/` and `go-api` only in `apps/api/` at the same time with isolation.
+
+**Monorepo workaround:** pick the team that matches the area you're actively working on. Claude Code loads `CLAUDE.md` files along the path to the files you're editing, so launching `claude` from the subdirectory you're working in gives you that subtree's `CLAUDE.md` context — but the applied team's agents themselves remain available repo-wide.
+
+## IMPORTANT: Session restart required
+
+After running `ccteams use`, `/ccteams:use-team`, or `/ccteams:choose-team`, **you must restart Claude Code** for the new agent team to load. The agents are instantiated at session start, not mid-session.
+
+**To restart:** type `/exit` (or close Claude Code) and start a new session.
+
+## How teams are applied to your project
+
+When you apply a team with `ccteams use <team>` or `/ccteams:use-team <team>`:
+
+1. The team's agent definitions are copied into `.claude/agents/`.
+2. A `.claude/active-team.md` file is created, documenting the active team and its purpose.
+3. Your project's `.claude/CLAUDE.md` is updated with an import statement (`@.claude/active-team.md`) to include the team's orchestration rules.
+4. A `.claude/.ccteams-manifest.json` is written to track which team is active and allow clean switching.
+5. If you pass `--agent-teams` (or the team opts in via `"requiresAgentTeams": true`), `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` is set in `.claude/settings.json`. This is optional — without it, the team runs in the normal orchestrated mode.
+
+ccteams includes a **collision guard**: it will refuse to apply a team if any of its agents share a name with agents you've written by hand in `.claude/agents/`. This prevents accidental overwrites.
+
+## Committing `.claude/` — your choice
+
+You have two options:
+
+**Option A (shared teams):** Commit `.claude/agents/`, `.claude/active-team.md`, and `.claude/.ccteams-manifest.json` to git. Teammates pulling the repo will automatically have the same team active.
+
+**Option B (local teams):** Add `.claude/agents/`, `.claude/active-team.md`, and `.claude/.ccteams-manifest.json` to `.gitignore`. Each developer can run `ccteams use` locally to activate their preferred team.
+
+**Recommendation:** If your project benefits from consistent team composition (e.g., a shared code style or mandatory QA agents), commit the team. Otherwise, keep it local.
+
+## Contributing a team
+
+ccteams applies the teams bundled in this repo's `teams/` directory. To add a new team,
+contribute it here (open a PR) — there's no separate user-local team registry. A team lives
+in `teams/<name>/`:
+
+```
+teams/<name>/
+├── team.json               # Metadata: name, description, tags, optional flags
+├── orchestration.md        # The CLAUDE.md rules to import (defines roles, goals, behavior)
+└── agents/
+    ├── agent1.md           # YAML frontmatter + agent system prompt
+    ├── agent2.md
+    └── ...
+```
+
+### `team.json` schema
+
+```json
+{
+  "name": "my-team",
+  "description": "A short pitch of what this team does",
+  "tags": ["backend", "api", "performance"],
+  "requiresAgentTeams": false
+}
+```
+
+Set `"requiresAgentTeams": true` if your team uses agent-to-agent messaging or collaborative member features.
+
+### Agent files (`.md`)
+
+Each agent file is a standard Claude Code subagent: YAML frontmatter (`name`, `description`, and optional `tools`) followed by its system prompt:
+
+```markdown
+---
+name: my-agent
+description: Backend API specialist. Use for building and reviewing REST/GraphQL endpoints, data layers, and integrations.
+tools: Read, Write, Edit, Bash, Glob, Grep
+---
+
+You are a Python backend expert. Your job is to...
+```
+
+The `description` is what Claude uses to decide when to delegate to this agent, so make it specific. Omit `tools` to inherit all available tools.
+
+For examples to copy from, see `teams/next-ts/` (a stack-specific team) and `teams/debug/` (a stack-agnostic team). `next-ts/` is the cleanest reference for the builder + reviewer shape.
+
+### Orchestrated vs. collaborative teams
+
+All teams that ship today are **orchestrated**: one lead delegates to specialized subagents that report back independently. This is the simple, predictable default.
+
+ccteams also supports **collaborative** teams — where subagents message each other directly — via Claude Code's experimental agent-teams feature (`CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1`). ccteams writes that env key into `.claude/settings.json` for you in two cases:
+
+- The team declares `"requiresAgentTeams": true` in its `team.json` — agent-teams mode is enabled automatically whenever you apply it.
+- You pass the `--agent-teams` flag to `ccteams use`, which opts any team into agent-teams mode for that project:
+
+  ```bash
+  ccteams use <team> --agent-teams
+  ```
+
+  The flag is position-agnostic, so `ccteams use --agent-teams <team>` works too.
+
+When ccteams added the env key (either way), it removes it again the next time you switch to a team that doesn't need it. No collaborative team ships by default, but the format supports authoring one.
+
+## Development / local testing
+
+### Test the plugin locally (session-only)
+
+```bash
+claude --plugin-dir ./plugins/ccteams
+```
+
+This loads the plugin for the current session only — no permanent install. Useful for development.
+
+### Test the CLI locally
+
+```bash
+npm install -g .
+ccteams list
+```
+
+Installs the CLI from the repo's current source.
+
+## License
+
+MIT © toffyui. See [LICENSE](./LICENSE) for the full text.

package/bin/ccteams.js

@@ -0,0 +1,174 @@
+#!/usr/bin/env node
+/**
+ * ccteams — Claude Code agent-team package manager
+ *
+ * Commands:
+ *   list [--json]   List available teams
+ *   use <team>      Apply a team to the current project
+ *   current         Show the currently-applied team
+ */
+
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+import { listTeams } from '../lib/teams.js';
+import { readManifest } from '../lib/manifest.js';
+import { useTeam } from '../lib/use.js';
+
+const args = process.argv.slice(2);
+const command = args[0];
+
+// Read the version from package.json (single source of truth), resolved relative
+// to this file so it works regardless of where ccteams is installed.
+function getVersion() {
+  try {
+    const pkgPath = path.join(path.dirname(fileURLToPath(import.meta.url)), '..', 'package.json');
+    return JSON.parse(fs.readFileSync(pkgPath, 'utf8')).version ?? 'unknown';
+  } catch {
+    return 'unknown';
+  }
+}
+
+// ── version ───────────────────────────────────────────────────────────────────
+if (command === '--version' || command === '-V' || command === 'version') {
+  console.log(`ccteams ${getVersion()}`);
+  process.exit(0);
+}
+
+// ── list ────────────────────────────────────────────────────────────────────
+if (command === 'list') {
+  const teams = listTeams();
+  const jsonFlag = args.includes('--json');
+
+  if (jsonFlag) {
+    // Print ONLY valid JSON — no decorative text, nothing else.
+    const output = teams.map(({ name, summary, description, tags, requiresAgentTeams }) => ({
+      name,
+      summary,
+      description,
+      tags,
+      requiresAgentTeams,
+    }));
+    process.stdout.write(JSON.stringify(output, null, 2) + '\n');
+    process.exit(0);
+  }
+
+  if (teams.length === 0) {
+    console.log('No teams found.');
+    process.exit(0);
+  }
+
+  // Color follows the NO_COLOR / FORCE_COLOR conventions, then falls back to TTY
+  // detection (so piped/captured output stays plain).
+  const color = !process.env.NO_COLOR && (process.env.FORCE_COLOR ? true : !!process.stdout.isTTY);
+  const bold = (s) => (color ? `\x1b[1;36m${s}\x1b[0m` : s); // bold cyan (team names)
+  const dim = (s) => (color ? `\x1b[2m${s}\x1b[0m` : s); // dim (secondary text)
+
+  const details = args.includes('--details') || args.includes('-d');
+
+  if (details) {
+    // Full view: name + complete description + tags, one block per team.
+    console.log('Available teams:\n');
+    for (const t of teams) {
+      console.log(`  ${bold(t.name)}`);
+      console.log(`    ${t.description}`);
+      if (t.tags.length > 0) {
+        console.log(`    ${dim('tags:')} ${dim(t.tags.join(', '))}`);
+      }
+      console.log();
+    }
+    console.log(dim('  Apply: ccteams use <team>    Optional: add --agent-teams to run members in parallel.'));
+    process.exit(0);
+  }
+
+  // Compact view (default): name (bold cyan) + a short one-line summary. One row
+  // per team, no wrapping, so the list stays scannable. `--details` shows the full
+  // descriptions and tags.
+  const nameWidth = Math.max(...teams.map((t) => t.name.length));
+
+  console.log('Available teams:\n');
+  for (const t of teams) {
+    console.log(`  ${bold(t.name.padEnd(nameWidth))}  ${t.summary}`);
+  }
+  console.log(dim('\n  Apply: ccteams use <team>    Full details: ccteams list --details'));
+  console.log(dim('  Optional: add --agent-teams to run a team’s members in parallel.'));
+  process.exit(0);
+}
+
+// ── current ──────────────────────────────────────────────────────────────────
+if (command === 'current') {
+  const manifest = readManifest(process.cwd());
+  if (!manifest?.appliedTeam) {
+    console.log('No team currently applied. Run: ccteams use <team>');
+    process.exit(0);
+  }
+  console.log(`Current team: ${manifest.appliedTeam}`);
+  console.log(`Applied at  : ${manifest.appliedAt}`);
+  console.log(`Files placed: ${manifest.placedFiles?.length ?? 0}`);
+  process.exit(0);
+}
+
+// ── use ──────────────────────────────────────────────────────────────────────
+if (command === 'use') {
+  // Parse position-agnostic: strip --agent-teams from the args list, whatever
+  // position it appears in, then take the first remaining non-flag word as the
+  // team name.
+  const agentTeamsFlag = args.includes('--agent-teams');
+  const useArgs = args.slice(1).filter((a) => a !== '--agent-teams');
+  const teamName = useArgs[0];
+
+  if (!teamName) {
+    console.error('Usage: ccteams use [--agent-teams] <team-name>');
+    process.exit(1);
+  }
+
+  const result = useTeam(teamName, process.cwd(), { agentTeams: agentTeamsFlag });
+  if (!result.success) {
+    console.error(`Error: ${result.message}`);
+    process.exit(1);
+  }
+  console.log(result.message);
+  process.exit(0);
+}
+
+// ── no args / unknown command ────────────────────────────────────────────────
+const usageText = `
+ccteams — Claude Code agent-team package manager
+
+Usage:
+  ccteams list                        List all available teams (compact)
+  ccteams list --details              List teams with full descriptions and tags
+  ccteams list --json                 Machine-readable JSON list (for scripts/slash commands)
+  ccteams use <team>                  Apply a team to the current project
+  ccteams use <team> --agent-teams    Apply a team AND enable agent-teams mode
+  ccteams current                     Show the currently-applied team
+  ccteams --version                   Print the ccteams version
+
+Flags:
+  --agent-teams   Enable CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 in .claude/settings.json
+                  for the applied team. Position-agnostic: works before or after <team>.
+                  Teams that declare "requiresAgentTeams" set this automatically.
+
+Agent teams mode:
+  By default a team is orchestrated: one lead delegates to members one at a time,
+  and they report back. With --agent-teams, members become parallel teammates that
+  run at once and message each other directly — better for big, splittable work.
+  It uses Claude Code's experimental agent-teams feature and takes effect after you
+  restart the session.
+
+Examples:
+  ccteams list
+  ccteams use frontend
+  ccteams use go-api --agent-teams
+  ccteams use --agent-teams rails
+  ccteams current
+`.trimStart();
+
+if (command === undefined || command === '--help' || command === '-h') {
+  console.log(usageText);
+  process.exit(0);
+}
+
+console.error(`Unknown command: "${command}"\n`);
+console.error(usageText);
+process.exit(1);

package/lib/manifest.js

@@ -0,0 +1,59 @@
+/**
+ * manifest.js — read/write .claude/.ccteams-manifest.json in the user's project.
+ *
+ * The manifest tracks what ccteams placed so we can clean up on team switches
+ * without touching hand-written agent files.
+ *
+ * Schema:
+ * {
+ *   "version": "1",                    // schema version, bump if format changes
+ *   "appliedTeam": "<team-name>",      // name of the currently-applied team
+ *   "appliedAt": "<ISO-8601>",         // timestamp for diagnostics
+ *   "placedFiles": ["<abs-path>", ...],// every file ccteams wrote, for clean removal
+ *   "agentTeamsFlagSet": <boolean>     // true if ccteams wrote the experimental env key
+ * }
+ */
+
+import fs from 'fs';
+import path from 'path';
+
+const MANIFEST_VERSION = '1';
+
+/**
+ * Resolve the manifest path inside the given project root.
+ */
+export function manifestPath(projectRoot) {
+  return path.join(projectRoot, '.claude', '.ccteams-manifest.json');
+}
+
+/**
+ * Read the manifest from disk. Returns null if it does not exist or is invalid.
+ */
+export function readManifest(projectRoot) {
+  const mPath = manifestPath(projectRoot);
+  if (!fs.existsSync(mPath)) return null;
+  try {
+    return JSON.parse(fs.readFileSync(mPath, 'utf8'));
+  } catch {
+    // Corrupted manifest — treat as absent so we start fresh.
+    return null;
+  }
+}
+
+/**
+ * Write a new manifest to disk.
+ * agentTeamsFlagSet tracks whether ccteams injected the experimental env key so
+ * we can remove it on switch without clobbering a user's pre-existing value.
+ */
+export function writeManifest(projectRoot, { appliedTeam, placedFiles, agentTeamsFlagSet = false }) {
+  const mPath = manifestPath(projectRoot);
+  const data = {
+    version: MANIFEST_VERSION,
+    appliedTeam,
+    appliedAt: new Date().toISOString(),
+    placedFiles,
+    agentTeamsFlagSet,
+  };
+  fs.mkdirSync(path.dirname(mPath), { recursive: true });
+  fs.writeFileSync(mPath, JSON.stringify(data, null, 2) + '\n', 'utf8');
+}

package/lib/teams.js

@@ -0,0 +1,64 @@
+/**
+ * teams.js — discover and read team packages from the ccteams source repo.
+ *
+ * Teams live at <ccteams-repo-root>/teams/<team-name>/ and are resolved relative
+ * to this file's location (import.meta.url), so the path works regardless of
+ * where the user runs ccteams from (process.cwd is the user's project, not ours).
+ */
+
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+// Resolve the ccteams source root from this file's location.
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const TEAMS_DIR = path.resolve(__dirname, '..', 'teams');
+
+/**
+ * Return an array of all available team descriptors.
+ * Each element: { name, description, tags, teamDir }
+ */
+export function listTeams() {
+  if (!fs.existsSync(TEAMS_DIR)) {
+    return [];
+  }
+
+  const entries = fs.readdirSync(TEAMS_DIR, { withFileTypes: true });
+  const teams = [];
+
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    const teamDir = path.join(TEAMS_DIR, entry.name);
+    const jsonPath = path.join(teamDir, 'team.json');
+    if (!fs.existsSync(jsonPath)) continue;
+
+    let meta;
+    try {
+      meta = JSON.parse(fs.readFileSync(jsonPath, 'utf8'));
+    } catch {
+      // Skip malformed team packages silently — user-visible error would be noise.
+      continue;
+    }
+
+    teams.push({
+      name: meta.name ?? entry.name,
+      // Short one-line label for `list`; falls back to the description.
+      summary: meta.summary ?? meta.description ?? '',
+      description: meta.description ?? '',
+      tags: meta.tags ?? [],
+      // Optional: signals that CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS is required.
+      requiresAgentTeams: meta.requiresAgentTeams === true,
+      teamDir,
+    });
+  }
+
+  return teams;
+}
+
+/**
+ * Return a single team descriptor by name, or null if not found.
+ */
+export function findTeam(name) {
+  return listTeams().find((t) => t.name === name) ?? null;
+}