agentic-team 0.0.0-stage → 6.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sulhadin Öney
+
+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

@@ -1,3 +1,185 @@
-# Temporary Holding Version
+# Orchestra
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+AI team orchestration for [Claude Code](https://docs.anthropic.com/en/docs/claude-code).
+One terminal plans, another builds. You design and decide; the system
+scaffolds, builds, verifies, reviews and delivers.
+
+Orchestra is an attempt to clone an engineer into a team of agents. The
+decisions a senior engineer would make — stack, structure, testing shape,
+what a commit looks like, what "done" means — are already encoded, so the
+work comes out the way they would have built it, without them in the loop.
+
+No infrastructure. No API keys. Markdown files and Claude Code.
+
+## Install
+
+In the project:
+
+```bash
+npx agentic-team
+```
+
+That copies `.orchestra/` and `.claude/` in and adds the Orchestra section to
+`CLAUDE.md`. Node 22 or newer. Re-running it upgrades in place — milestones,
+blueprints, your own roles, skills and rules are preserved, and `config.yml`
+is merged rather than overwritten.
+
+## How it works
+
+Once, in a freshly cloned empty repo:
+
+```
+/orchestra:setup
+```
+
+It asks what you are building and scaffolds each app from a stack — every
+version resolved from the registry, CI, Dependabot, the PR template, the
+commit hook and the verification gate already in place. Nothing is written
+from memory.
+
+Then, for every feature, two terminals:
+
+```
+Terminal 1 — PM                          Terminal 2 — Lead
+  /orchestra:pm                            /orchestra:start
+  talk the idea through                    reads the board
+  milestones → phases → review             design → RFC
+  "export"  → the board                    one task → one PR
+  /orchestra:sync  on your comments        reviewer on the PR
+                                           /orchestra:sync  on your comments
+```
+
+The PM writes the plan and gets it reviewed. When you say "export", every
+approved milestone goes to the board in one burst — an epic per milestone, a
+task per phase, all in `backlog`. You move a task to `ready`; lead takes it
+from there and nowhere else.
+
+### One task, end to end
+
+![One task, end to end](docs/img/task-lifecycle.svg#gh-light-mode-only)
+![One task, end to end](docs/img/task-lifecycle-dark.svg#gh-dark-mode-only)
+
+### The statuses it moves through
+
+![Task status lifecycle](docs/img/task-status-lifecycle.svg#gh-light-mode-only)
+![Task status lifecycle](docs/img/task-status-lifecycle-dark.svg#gh-dark-mode-only)
+
+Two moves are yours: `backlog → ready` and `blocked → ready`. Lead sets the
+rest, and never moves a task to `ready` itself. A re-export updates a task's
+text and never its status.
+
+A comment on a task is how you change things. About the plan — scope,
+acceptance criteria, a phase to split — the PM answers it: revises the
+phase, re-exports, replies. About the build — a bug, a design mismatch —
+lead answers it with a pull request. Each surfaces the other's kind and
+stops. Never edit a requirement by hand on the board; the next export
+overwrites it.
+
+With `tracker.provider: none` there is no board. The markdown under
+`.orchestra/milestones/` is the source of truth and lead reads it from disk.
+
+## Commands
+
+| Command | Who | What |
+|---|---|---|
+| `/orchestra:setup` | you, once | Scaffold the repo from stacks |
+| `/orchestra:pm` | you | Open the PM terminal |
+| `/orchestra:start` | you | Open the lead terminal; `--auto` runs unattended and merges its own PRs |
+| `/orchestra:export [id]` | PM, when you ask | Push approved milestones to the board |
+| `/orchestra:sync [id]` | PM or lead | Act on what changed on the board |
+| `/orchestra:status` | PM | Milestone status report |
+| `/orchestra:verifier [N]` | PM | Check built milestones against their requirements |
+| `/orchestra:rewind [N]` | PM | Execution history: decisions, metrics, retries |
+| `/orchestra:hotfix {desc}` | you | Implement → verify → commit → push, fast |
+| `/orchestra:blueprint {name}` | PM | Milestones from a template; `add` saves one |
+| `/orchestra:orchestrator` | you | Maintain the system itself |
+| `/orchestra:create-role` | Orchestrator | A new role, interactively |
+| `/orchestra:help` | anyone | All of the above |
+
+## What is inside
+
+```
+.orchestra/
+├── config.yml          pipeline, verification, testing, delivery, tracker, observability
+├── roles/              product-manager, orchestrator — identity and what each may write
+├── stacks/             how each kind of app is scaffolded and built afterwards
+├── trackers/           the GitHub adapter; ClickUp goes through its MCP connector
+├── blueprints/         milestone templates
+└── milestones/         your work — prd, milestone, phases, tracker.yml, context.md
+
+.claude/
+├── agents/             architect, scaffolder, lead, reviewer, tracker
+├── rules/*.orchestra.md   discipline, loaded into every session
+├── skills/*/SKILL.md   depth on one topic, loaded per phase
+└── commands/orchestra/ the commands above
+```
+
+**Stacks:** `web-nextjs`, `web-vite-react`, `backend-hono`, `mobile-expo`,
+`mobile-ios-native`, `mobile-android-native`. A defect found while building a
+real project is fixed in the stack, so the next project never meets it.
+
+**Rules** are the discipline that applies everywhere: verification gate,
+testing shape, security, performance, observability, commit format, pull
+requests, tracker authority, comments. What a rule can decide mechanically
+is enforced by `scripts/policy-check.mjs` in the gate; the rest is a review
+item, and the reviewer is told which is which.
+
+**Roles** write only inside their ownership. PM writes milestones. Lead
+writes `context.md`. Sub-agents write what a phase's scope names. A
+`PreToolUse` hook blocks everything else.
+
+## Principles
+
+Each one exists because ignoring it produced a real failure.
+
+- **Verified, never recalled.** Versions come from the registry, flags from
+  `--help`, OWASP settings from the page — at run time.
+- **Determinism over improvisation.** Scaffolding is a script. It runs the
+  same way every time and lands in a diff.
+- **Enforcement over advice.** A rule nothing checks is prose. Conventions
+  are backed by CI, hooks, coverage gates and a policy script.
+- **A green suite is the merge signal.** Everything wrapping a third-party
+  library has a test, so a dependency bump that changes behaviour turns red.
+- **One source of truth.** `tracker.provider` names it. Never both.
+- **Measure before building.** A milestone states its metric, baseline,
+  target and how it is read — or it is not ready.
+- **Report honestly.** Say what was verified and what was assumed. Unverified
+  is a word.
+
+## Upgrading
+
+```bash
+npx agentic-team@latest
+```
+
+| What | On upgrade |
+|---|---|
+| Roles, rules, agents, commands, stacks, shipped skills | Updated |
+| Your own roles, skills, rules | Preserved |
+| Blueprints (shipped / yours) | Updated / preserved |
+| `milestones/` | Untouched |
+| `config.yml` | Merged — your values kept, new keys added |
+
+## Documentation
+
+- [Getting started](docs/getting-started.md)
+- [Commands](docs/commands.md)
+- [Roles](docs/roles.md)
+- [Features](docs/features.md)
+- [Stacks](docs/stacks.md)
+- [Skills](docs/skills.md)
+- [Blueprints](docs/blueprints.md)
+
+## Development
+
+```bash
+yarn test
+```
+
+`bin/index.js` is the installer. `template/` is built from `.orchestra/` and
+`.claude/` by `yarn template`, is gitignored, and is regenerated on every
+publish. Pre-commit runs the template build and the suite.
+
+## License
+
+MIT

package/bin/build-template.js

@@ -0,0 +1,208 @@
+#!/usr/bin/env node
+
+const fs = require("node:fs");
+const path = require("node:path");
+
+const rootDir = process.cwd();
+
+// Output directory, `template/` unless told otherwise.
+//
+// The suite reads template/ from several files while build-template.test.js
+// rebuilds it, and copyFileSync truncates before it writes — so a reader could
+// catch a file mid-write and fail for a reason that had nothing to do with it.
+// The test builds into a directory of its own instead of racing on the shared
+// one.
+const outFlag = process.argv.indexOf("--out");
+const templateDir =
+  outFlag !== -1 && process.argv[outFlag + 1]
+    ? path.resolve(process.argv[outFlag + 1])
+    : path.join(rootDir, "template");
+
+// Dev-only agents that should NOT be published to users
+const DEV_ONLY_AGENTS = new Set([
+  "codebase-deep-analyzer.md",
+  "orchestra-analyzer.md",
+  "orchestra-reviewer.md",
+  "repo-deep-analyzer.md",
+]);
+
+// Dev-only skills that should NOT be published to users
+const DEV_ONLY_SKILLS = new Set(["ship"]);
+
+// Plugin manifest
+const PLUGIN_MANIFEST = {
+  name: "orchestra",
+  description:
+    "AI Team Orchestration — multi-role coordination with milestones, phases, and quality gates for Claude Code",
+  version: require("../package.json").version,
+  author: { name: "Sulhadin Öney" },
+  repository: "https://github.com/sulhadin/orchestrator",
+  license: "MIT",
+};
+
+// System files to include in the template (plugin-compatible structure)
+// Plugin dirs (agents/, commands/, skills/, rules/) go at root level
+// .orchestra/ and CLAUDE.md also go at root level
+const SYSTEM_PATHS = [
+  { src: ".claude/agents", dest: "agents", filter: (f) => !DEV_ONLY_AGENTS.has(f) },
+  { src: ".claude/commands/orchestra", dest: "commands" },
+  { src: ".claude/rules", dest: "rules", filter: (f) => f.endsWith(".orchestra.md") },
+  {
+    src: ".claude/skills",
+    dest: "skills",
+    filter: (f) => {
+      if (DEV_ONLY_SKILLS.has(f)) return false;
+      const skillDir = path.join(rootDir, ".claude/skills", f);
+      return fs.statSync(skillDir).isDirectory() && fs.existsSync(path.join(skillDir, "SKILL.md"));
+    },
+  },
+  // A hook is only enforcement if it ships and is registered. Without both
+  // it is a script nobody runs, which is the failure mode the rules exist to
+  // avoid.
+  { src: ".claude/hooks", dest: "hooks" },
+  // Same reasoning as the hook above: an adapter that does not ship is a
+  // script nobody runs, and the tracker agent would be back to improvising
+  // GraphQL in a prompt.
+  { src: ".orchestra/trackers", dest: ".orchestra/trackers" },
+  // A rule that names a script the project does not have is prose nobody can
+  // follow. pull-request.orchestra.md points reviewers at this directory.
+  // The repo's own scripts/ stays home: compact-test-output.awk parses
+  // `node --test`, and scaffolded apps run vitest or jest.
+  { src: ".orchestra/scripts", dest: ".orchestra/scripts" },
+  { src: ".orchestra/roles", dest: ".orchestra/roles" },
+  { src: ".orchestra/blueprints", dest: ".orchestra/blueprints" },
+  { src: ".orchestra/stacks", dest: ".orchestra/stacks" },
+  { src: ".orchestra/config.yml", dest: ".orchestra/config.yml" },
+  { src: ".orchestra/README.md", dest: ".orchestra/README.md" },
+  // CLAUDE.md is handled separately — only the marked section may ship.
+];
+
+// The repo's CLAUDE.md carries a "## Development" section about THIS package.
+// Copying it wholesale means every scaffolded project tells its own agents it
+// is the orchestrator npm package. Ship only what is between the markers.
+function packClaudeMd() {
+  const src = fs.readFileSync(path.join(rootDir, "CLAUDE.md"), "utf-8");
+  const start = src.indexOf("<!-- orchestra -->");
+  const end = src.indexOf("<!-- /orchestra -->");
+  if (start === -1 || end === -1) {
+    throw new Error("CLAUDE.md is missing the <!-- orchestra --> markers");
+  }
+  const section = src.slice(start, end + "<!-- /orchestra -->".length);
+  const header =
+    "# CLAUDE.md\n\n" +
+    "This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.\n\n";
+  const claudeMd = path.join(templateDir, "CLAUDE.md");
+  fs.writeFileSync(claudeMd, `${header + section}\n`);
+  record(claudeMd);
+}
+
+/**
+ * Every path this run wrote. What is not in here at the end is retired.
+ *
+ * The builder only ever copied, so a file this project stopped shipping
+ * survived in template/ forever and went out in the package — jira.sh
+ * outlived its own deletion by a whole release.
+ *
+ * Pruning afterwards rather than wiping first, because template/ is read by
+ * the suite: deleting it up front leaves a window where a parallel test file
+ * finds no template at all, which is a flake that looks like a real failure.
+ */
+const written = new Set();
+function record(fullPath) {
+  written.add(path.resolve(fullPath));
+}
+
+function ensureDir(dir) {
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+}
+
+function copyRecursive(src, dest, filter = null) {
+  const fullSrc = path.join(rootDir, src);
+  const fullDest = path.join(templateDir, dest);
+
+  if (!fs.existsSync(fullSrc)) {
+    console.warn(`  [!] Source not found, skipping: ${src}`);
+    return;
+  }
+
+  const stat = fs.statSync(fullSrc);
+
+  if (stat.isDirectory()) {
+    ensureDir(fullDest);
+    const entries = fs.readdirSync(fullSrc, { withFileTypes: true });
+
+    for (const entry of entries) {
+      if (filter && !filter(entry.name)) continue;
+
+      const entrySrc = path.join(src, entry.name);
+      const entryDest = path.join(dest, entry.name);
+
+      const fullEntrySrc = path.join(rootDir, entrySrc);
+      const fullEntryDest = path.join(templateDir, entryDest);
+
+      if (entry.isSymbolicLink()) {
+        // Dereference. The source repo uses symlinks to keep one source of
+        // truth, but npm pack silently DROPS symlinks from the tarball —
+        // shipping them means the agent simply does not exist for users.
+        const resolved = fs.realpathSync(fullEntrySrc);
+        if (fs.existsSync(fullEntryDest)) fs.unlinkSync(fullEntryDest);
+        fs.copyFileSync(resolved, fullEntryDest);
+        record(fullEntryDest);
+      } else if (entry.isDirectory()) {
+        copyRecursive(entrySrc, entryDest);
+      } else {
+        fs.copyFileSync(fullEntrySrc, fullEntryDest);
+        record(fullEntryDest);
+      }
+    }
+  } else {
+    ensureDir(path.dirname(fullDest));
+    fs.copyFileSync(fullSrc, fullDest);
+    record(fullDest);
+  }
+}
+
+console.log("\n  Orchestra — Template Builder");
+console.log("  Packing root system files into template/...\n");
+
+for (const item of SYSTEM_PATHS) {
+  copyRecursive(item.src, item.dest, item.filter);
+  console.log(`  [+] Packed: ${item.src}`);
+}
+
+packClaudeMd();
+console.log("  [+] Packed: CLAUDE.md (orchestra section only)");
+
+// Write plugin manifest
+const pluginDir = path.join(templateDir, ".claude-plugin");
+ensureDir(pluginDir);
+const manifestPath = path.join(pluginDir, "plugin.json");
+fs.writeFileSync(manifestPath, `${JSON.stringify(PLUGIN_MANIFEST, null, 2)}\n`);
+record(manifestPath);
+console.log("  [+] Generated .claude-plugin/plugin.json");
+
+// Retire what this run did not write. A file removed from the source is
+// removed from the package in the same commit, rather than shipping until
+// somebody notices.
+let retired = 0;
+function prune(dir) {
+  if (!fs.existsSync(dir)) return;
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      prune(full);
+      if (fs.readdirSync(full).length === 0) fs.rmdirSync(full);
+    } else if (!written.has(path.resolve(full))) {
+      fs.unlinkSync(full);
+      console.log(`  [-] Retired: ${path.relative(templateDir, full)}`);
+      retired++;
+    }
+  }
+}
+prune(templateDir);
+if (retired === 0) console.log("  [=] Nothing to retire");
+
+console.log("\n  Done! Template is updated and ready for release.");
+console.log("  Run 'yarn test' to verify.\n");