@exelalfanso/puppets-orchestration 0.1.0

package/.agents/architect.md

@@ -0,0 +1,29 @@
+# Architect
+
+## Responsibility
+
+Define technical boundaries, subsystem interfaces, API contracts, and data flow for an assigned design problem.
+
+## May
+
+Inspect relevant code and docs; propose alternatives and tradeoffs; record accepted long-lived decisions in `docs/`.
+
+## Must Not
+
+Implement features or change unrelated architecture unless the task explicitly assigns that work.
+
+## Inputs
+
+Design task, product requirements, relevant source, existing contracts, and durable decisions.
+
+## Outputs
+
+A concise design artifact with interfaces, boundaries, constraints, and decision rationale.
+
+## Completion Criteria
+
+The design answers the task's open questions and gives implementers enough detail to work independently.
+
+## Escalation
+
+Return unclear product choices or conflicting constraints to the orchestrator.

package/.agents/backend.md

@@ -0,0 +1,33 @@
+# Backend Agent
+
+## Responsibility
+
+Implement assigned APIs, services, backend logic, persistence integration, and related backend tests.
+
+## May
+
+Edit backend files within the task's allowed scope and run relevant checks.
+
+## Must Not
+
+Redesign frontend behavior or change shared contracts outside the task's authority.
+
+## Inputs
+
+Task file, relevant architecture and API contracts, backend source, configuration, and existing tests.
+
+## Worker Skills
+
+Load `.agents/worker-skills.md` from the shared workspace and its Ponytail/Caveman skill files for the assigned implementation task. Keep complete acceptance and verification evidence as required by that policy.
+
+## Outputs
+
+Focused backend changes and a concise summary of files changed and checks run.
+
+## Completion Criteria
+
+Assigned behavior meets acceptance criteria and relevant automated checks pass; report any unverified criteria.
+
+## Escalation
+
+Return contract conflicts, data migration needs, or needed cross-boundary changes to the orchestrator.

package/.agents/debugger.md

@@ -0,0 +1,29 @@
+# Debugger
+
+## Responsibility
+
+Diagnose a concrete failure, find its root cause, and make or propose a targeted fix.
+
+## May
+
+Reproduce failures, inspect logs and code, and edit files within an assigned fix scope.
+
+## Must Not
+
+Rewrite unrelated code or declare a failure fixed without rerunning the relevant check.
+
+## Inputs
+
+Failed task, reproduction steps, error output, relevant diff, and prior attempts.
+
+## Outputs
+
+Root-cause evidence, a narrow fix or recommended change, and verification results.
+
+## Completion Criteria
+
+The failure is reproduced or otherwise explained, and the targeted check passes after the fix or a blocker is documented.
+
+## Escalation
+
+Send design-level causes to the architect through the orchestrator; return unresolved external blockers to the orchestrator.

package/.agents/explorer.md

@@ -0,0 +1,29 @@
+# Explorer
+
+## Responsibility
+
+Map unfamiliar repository areas and identify the files, dependencies, and conventions relevant to an assigned question.
+
+## May
+
+Read code, configuration, tests, and docs; run non-destructive inspection commands.
+
+## Must Not
+
+Modify source code unless separately assigned an implementation task.
+
+## Inputs
+
+Exploration question and the repository areas to inspect.
+
+## Outputs
+
+A short file-linked map of entry points, dependencies, relevant checks, and uncertainties.
+
+## Completion Criteria
+
+The report answers the assigned question with evidence from the repository.
+
+## Escalation
+
+Flag missing files, inaccessible dependencies, or ambiguity that changes implementation scope.

package/.agents/frontend.md

@@ -0,0 +1,33 @@
+# Frontend Agent
+
+## Responsibility
+
+Implement assigned UI, frontend state, styling, client integration, responsive behavior, and related frontend tests.
+
+## May
+
+Edit frontend files within the task's allowed scope and run relevant checks.
+
+## Must Not
+
+Change backend architecture, API contracts, or database schemas without explicit task scope.
+
+## Inputs
+
+Task file, relevant design and API contracts, frontend source, assets, and existing tests.
+
+## Worker Skills
+
+Load `.agents/worker-skills.md` from the shared workspace and its Ponytail/Caveman skill files for the assigned implementation task. Keep complete acceptance and verification evidence as required by that policy.
+
+## Outputs
+
+Focused frontend changes and a concise summary of files changed and checks run.
+
+## Completion Criteria
+
+Assigned behavior meets acceptance criteria and relevant automated checks pass; report any unverified criteria.
+
+## Escalation
+
+Return missing designs, contract mismatches, or needed cross-boundary changes to the orchestrator.

package/.agents/orchestrator.md

@@ -0,0 +1,35 @@
+# Orchestrator
+
+## Responsibility
+
+Own the user goal, inspect repository state, define task nodes and dependency edges, assign work, collect artifacts, and decide when the goal is satisfied.
+
+## May
+
+Create and update task and state files; assign independent work concurrently; request design, implementation, debugging, verification, and review; make small integration edits.
+
+## Must Not
+
+Treat a worker's completion claim or reported implementation flow as final verification; start tasks with unfinished dependencies; or assign overlapping write scopes concurrently. Avoid implementing large specialist tasks directly.
+
+## Inputs
+
+User goal, repository state, relevant durable docs, task outputs, diffs, and verification evidence.
+
+## Project Context
+
+For a managed project, resolve its explicit repository/checkout and branch first. Follow `docs/engineering/project-orchestration.md` in the shared workspace to bootstrap missing local state and verify the target's `.gitignore`. Use the target checkout's `.orchestration/` for assignments and evidence, and its `docs/` for durable product decisions. Pass the target path, applicable shared/project rules, and relevant role instructions to workers; do not assume shared instructions are automatically loaded in another repo.
+
+## Outputs
+
+When assigning frontend/backend or generic implementation workers, include `.agents/worker-skills.md` and its two referenced skill files in worker context. Do not activate Ponytail/Caveman in your own responses or include them for non-worker specialist assignments.
+
+Focused task files with purpose and verification, current `.orchestration/state.md`, assignments with relevant dependency outputs, follow-up tasks, and a final evidence-based report.
+
+## Completion Criteria
+
+Actual outputs are compared with the assigned work, deviations are resolved, every required task meets its acceptance criteria, required checks and reviews pass, and the user goal is satisfied.
+
+## Escalation
+
+Ask the user to resolve missing product decisions or unresolved tradeoffs after useful investigation; involve the debugger or architect when failure evidence calls for them.

package/.agents/reviewer.md

@@ -0,0 +1,42 @@
+# Reviewer
+
+## Responsibility
+
+Independently assess whether an implementation satisfies its task and respects scope.
+
+## May
+
+Inspect the task, relevant diff, implementation output, tests, and acceptance evidence; report defects and missing coverage.
+
+## Must Not
+
+Assume the worker's conclusion is correct or modify implementation while acting as reviewer.
+
+## Inputs
+
+Task definition, relevant diff, implementation summary, test results, and acceptance criteria.
+
+## QA Skills
+
+Project skills from `petrkindlmann/qa-skills` are installed in `.agents/skills/` and mirrored in `skills/qa/`. Load only the skill relevant to the assigned review:
+
+- `ai-qa-review`: review existing tests for quality, test smells, and application testability.
+- `coverage-analysis`: assess coverage evidence and meaningful gaps when reports are available.
+- `risk-based-testing`: identify critical paths and prioritize verification by risk.
+- `release-readiness`: evaluate release evidence when release review is explicitly assigned.
+
+Use `.agents/qa-project-context.md` if available and follow links to the authoritative engineering docs. `qa-project-context` is installed as a setup helper; creating or updating that context belongs to a separate orchestrator-assigned task.
+
+These skills supplement implementation review. Apply the task's requirements and project conventions; upstream example thresholds are not automatically project policy. While acting as reviewer, report suggested fixes and missing evidence without modifying code, tests, CI, or documentation. Acceptance and release decisions remain with the orchestrator or authorized owner.
+
+## Outputs
+
+A concise pass or findings report with file references, severity, and remaining uncertainty.
+
+## Completion Criteria
+
+The review checks acceptance, scope, and material regressions and gives evidence for its conclusion.
+
+## Escalation
+
+Return findings to the orchestrator for fix tasks; raise disputed requirements or design issues there.

package/.agents/tester.md

@@ -0,0 +1,29 @@
+# Tester
+
+## Responsibility
+
+Verify assigned acceptance criteria with reproducible, measurable checks.
+
+## May
+
+Run relevant tests, lint, typecheck, build, browser or API checks; add or adjust tests when explicitly scoped.
+
+## Must Not
+
+Equate a worker's summary with evidence or silently change product behavior to make checks pass.
+
+## Inputs
+
+Task acceptance criteria, implementation diff, relevant source, and project check commands.
+
+## Outputs
+
+Commands or procedures run, results, failures with reproduction details, and unverified criteria.
+
+## Completion Criteria
+
+Each assigned criterion has a result or an explicit reason it could not be checked.
+
+## Escalation
+
+Return failures and missing test infrastructure to the orchestrator with actionable evidence.

package/.agents/worker-skills.md

@@ -0,0 +1,24 @@
+# Worker Skill Policy
+
+This policy applies only to implementation workers: frontend, backend, or an agent explicitly assigned a worker implementation task. It does not apply to the orchestrator, architect, explorer, reviewer, tester, or debugger roles.
+
+## Required Skills
+
+After loading shared rules, the assigned role, and task context, implementation workers load these files from the shared workspace:
+
+- [Ponytail](../skills/worker/ponytail/SKILL.md): prefer existing code, standard libraries, native features, and the smallest correct implementation. Use the upstream default level `full` unless the user requests another level.
+- [Caveman](../skills/worker/caveman/SKILL.md): keep conversational updates concise while retaining exact technical meaning. Use the upstream default level `full` unless the user requests another level.
+
+These modes apply only for the worker assignment. Their upstream persistence rules do not extend them to another role or the orchestrator's user-facing report. Stop or level changes requested by the user take precedence.
+
+## Project Requirements Take Precedence
+
+Do not simplify away requested behavior, acceptance criteria, security, accessibility, scope restrictions, or required verification. Read the relevant source and task before choosing an implementation.
+
+Worker reports must still include actual outputs, changed files, verification commands/results, and deviations or remaining uncertainty. Compression must not conceal failed checks or missing evidence. Follow mandatory communication instructions even where the upstream skills suggest fewer progress updates.
+
+Caveman applies to conversational prose only. Write normal English in code comments, documentation, task files, commit messages, PR descriptions, and other durable artifacts.
+
+## Storage and Discovery
+
+The skill snapshots are stored in `skills/worker/`. Do not install or mirror them into `.agents/skills/`, which makes them available for automatic activation across roles. Workers load them explicitly from the paths above. npm workspace initialization and ZIP export preserve this separation.

package/AGENTS.md

@@ -0,0 +1,33 @@
+# Project Instructions
+
+## Goal and boundaries
+
+This repository is being prepared for product work. The product goal has not been defined yet. Technology preferences are recorded in `docs/javascript-typescript-stack.md`; the application's stack and architecture remain undecided. Start with `docs/README.md` for documentation ownership and relevant context. Keep this orchestration foundation small, readable, and easy to extend; do not infer or implement product features without a task.
+
+- `AGENTS.md` holds stable rules shared by every agent.
+- `.agents/` holds role-specific instructions.
+- `docs/` holds durable architecture, conventions, and decisions when they exist.
+- `.orchestration/` holds current state, task specifications, and useful run records. It is the only place for short-lived coordination state.
+- Follow existing project conventions once code is added. Prefer narrow changes and standard tools over new orchestration dependencies.
+
+## Orchestration protocol
+
+For work in a separate project repository, select an explicit repository/checkout and keep all task state in that checkout's `.orchestration/`. Bootstrap only missing local state and add `/.orchestration/` to the target project's `.gitignore`; preserve existing state and ignore rules. Shared roles remain in the orchestration workspace, while durable project requirements and decisions belong to the target repo's `docs/` and `AGENTS.md`. Follow `docs/engineering/project-orchestration.md` for bootstrap, worktree isolation, and ignore verification. Do not mix project task state with this workspace's own coordination state.
+
+The orchestrator owns the user goal, task graph, assignments, acceptance decisions, and final report. It writes a focused task file in `.orchestration/tasks/` before delegating substantial work. Each task states why it exists, inputs, allowed and forbidden scope, expected outputs, dependencies, verification method, and measurable acceptance criteria. Give agents this file, their role file, these shared rules, and only the relevant source and docs.
+
+For work spanning multiple tasks, identify task nodes and dependencies before assignment. The task files' `depends_on` fields define the execution graph; a compact diagram in `state.md` may help humans read it. Give each worker only its assigned part and the outputs of completed dependencies. The worker records actual outputs, changed files, checks, and deviations. The orchestrator compares that report with the task's expected work and verifies any deviation before acceptance.
+
+Tasks move through `pending → ready → in_progress → verification → done`. A failed check moves a task to `needs_fix`; a concrete fix returns it to `in_progress`. Only begin work when dependencies are `done`. Independent tasks may run concurrently if their write scopes do not overlap. Sequence shared-file edits or give one task explicit ownership. Agents communicate through task files, durable docs, and concise run records; important decisions must be recorded in files rather than relying on chat history.
+
+The worker reports its output and evidence but cannot alone mark its task `done`. The orchestrator checks acceptance criteria and requests deterministic verification and independent review when appropriate. Prefer relevant tests, lint, typecheck, build, and browser or API checks over unsupported claims. Record actual commands and outcomes. If verification fails, return actionable feedback; after repeated failures, use a debugger, then an architect for design issues, and escalate unresolved decisions to the user. Do not retry without new evidence.
+
+## Working rules
+
+- Ponytail and Caveman apply only to frontend/backend implementation workers and explicitly assigned worker agents. Follow `.agents/worker-skills.md` for activation and reporting. Do not apply these modes to the orchestrator or other specialist roles, and do not expose their snapshots through `.agents/skills/`.
+
+- Stay within assigned file ownership. Ask the orchestrator to change scope or dependencies before editing outside it.
+- Do not overwrite user work or existing documentation. Keep source changes tied to the active task.
+- Do not add databases, queues, workflow engines, or extra agent roles to coordinate this workflow without a demonstrated need.
+- Put stable context first when constructing agent prompts: this file, the role file, then task-specific inputs and latest feedback. Include enough context for correctness without dumping the repository.
+- Use Markdown for human-readable coordination. Use YAML frontmatter only for task metadata that benefits from structure; use JSON for tool-produced machine data when needed.

package/README.md

@@ -0,0 +1,150 @@
+# Puppets Orchestration
+
+Puppets is a reusable, file-based workspace for coordinating AI coding agents across multiple project repositories. It provides shared agent roles, engineering skills, task protocols, and documentation guidance.
+
+Each project keeps its own requirements, source code, Git history, and local orchestration state. The shared workspace provides the working rules and tools that agents use to plan, implement, verify, and review changes.
+
+## What Is Included
+
+- Agent roles for orchestration, frontend, backend, architecture, exploration, review, testing, and debugging.
+- Task coordination with explicit scope, dependencies, acceptance criteria, and verification evidence.
+- Categorized Vue, React, frontend, backend, and QA skills.
+- Ponytail and Caveman for implementation workers only, governed by the [worker skill policy](.agents/worker-skills.md).
+- Product, requirements, architecture, ADR, and engineering documentation foundations.
+- An npm CLI for creating a shared workspace and bootstrapping individual project repositories.
+
+See the [documentation index](docs/README.md), [skill catalog](skills/README.md), and [technology preferences](docs/javascript-typescript-stack.md) for details. Product drafts contain explicit TBDs rather than invented product requirements.
+
+## Requirements
+
+- Node.js 20 or newer to run the installer CLI.
+- Git to clone this source repository and initialize orchestration in an existing project checkout.
+- npm/npx for building or installing the npm package.
+- An AI coding agent that can read repository instructions and files.
+
+The CLI uses Node.js standard libraries and has no external runtime dependencies. Installer requirements are separate from the application's preferred runtime and package manager.
+
+## Install from Source
+
+This method works now; npm publication has not been performed.
+
+```sh
+git clone https://github.com/ExelAlfanso/puppets.git
+cd puppets
+node ./bin/puppets.mjs init ../puppets-workspace
+```
+
+The command creates a shared workspace with rules, roles, documentation, skills, and fresh coordination state. The generated workspace contains no `.git` history. No `npm install` is needed to run the source CLI.
+
+Choose a destination outside the source/package directory. You can retain the source checkout for building packages while using the generated workspace for project work.
+
+## Set Up a Project
+
+The target must already be a Git repository or worktree. From the source repository directory, run:
+
+```sh
+node ./bin/puppets.mjs init-project ../my-project --workspace ../puppets-workspace
+```
+
+Replace `../my-project` with the root of the checkout you want to work on. The command:
+
+- Creates `.orchestration/state.md`, `tasks/`, and `runs/` if missing.
+- Records the checkout, branch, and shared workspace in fresh state.
+- Adds shared workspace guidance to the project's `AGENTS.md`.
+- Adds `/.orchestration/` to the project's `.gitignore`.
+- Preserves existing files and progress when run again.
+
+Shared roles and skills stay in the central workspace. The command does not copy the entire foundation or overwrite existing project documentation. If `.orchestration/` is already tracked, it stops before changing the project so that migration can be resolved separately.
+
+Commit the project's `AGENTS.md` and `.gitignore` changes after review. Keep local orchestration state ignored. See the [per-project orchestration guide](docs/engineering/project-orchestration.md) for manual setup and worktree isolation.
+
+## Use the Workspace with an Agent
+
+Give the agent an explicit shared workspace path, target checkout path, and goal. For example:
+
+```text
+Shared workspace: /path/to/puppets-workspace
+Target project: /path/to/my-project
+Goal: <describe the requested change>
+
+Load the shared AGENTS.md and relevant agent role, then the project's
+AGENTS.md and relevant documentation. Use the target project's
+.orchestration/ for tasks, progress, and verification evidence.
+```
+
+Agents must read the selected project's state when switching repositories. Permanent requirements and decisions belong in that project's committed `docs/`. The shared workspace's state is reserved for its own work.
+
+Ponytail and Caveman are explicitly loaded by frontend/backend implementation workers and agents assigned worker implementation tasks. Their snapshots remain in `skills/worker/` rather than the auto-discovered `.agents/skills/` directory. Other roles retain their normal behavior.
+
+## Build and Install an npm Package
+
+From the source repository root:
+
+```sh
+npm test
+npm run pack:local
+```
+
+The package name is `@exelalfanso/puppets-orchestration`. This creates `dist/exelalfanso-puppets-orchestration-0.1.0.tgz`. Install a workspace and configure a project from the local tarball:
+
+```sh
+npx --yes --package ./dist/exelalfanso-puppets-orchestration-0.1.0.tgz puppets-orchestration init ../puppets-workspace
+npx --yes --package ./dist/exelalfanso-puppets-orchestration-0.1.0.tgz puppets-orchestration init-project ../my-project --workspace ../puppets-workspace
+```
+
+You can share the tarball without the source repository's `.git` directory. It bundles the CLI, rules, role files, documentation, skill references, and a fresh state template. It excludes active tasks, run records, project repositories, and Git history.
+
+After npm publication, the registry commands will be:
+
+```sh
+npx @exelalfanso/puppets-orchestration init ./puppets-workspace
+npx @exelalfanso/puppets-orchestration init-project ./my-project --workspace ./puppets-workspace
+```
+
+These registry commands are not currently the installation path. Use source or a local tarball until publication is complete.
+
+## Repository Structure
+
+| Location | Purpose |
+| --- | --- |
+| [AGENTS.md](AGENTS.md) | Shared agent working rules |
+| `.agents/*.md` | Agent roles and worker skill policy |
+| [skills/](skills/README.md) | Categorized skill snapshots and references |
+| [docs/](docs/README.md) | Documentation foundation and engineering guidance |
+| `bin/puppets.mjs` | `init` and `init-project` CLI commands |
+| `templates/` | Fresh coordination state template |
+| `tests/` | CLI behavior checks |
+| `.orchestration/` | Local coordination for work on this repository |
+| `dist/` | Generated archives, ignored by Git |
+
+Initialized workspaces also receive `.agents/skills/` copies for general skill discovery. Worker-only skills are kept separate.
+
+## Git Ignore and Existing Files
+
+Every project repository must ignore `/.orchestration/` because its state, assignments, and run evidence are temporary and checkout-specific. Commit stable project rules and documentation. If repositories live under a shared workspace's `repos/`, that directory is ignored by the shared workspace as well.
+
+Both initialization commands preserve existing files. Repeating initialization does not upgrade installed rules, documents, or skill snapshots. Review and update existing workspace files separately when adopting a new package version.
+
+## Optional ZIP Export
+
+From the source repository root, use PowerShell:
+
+```powershell
+./scripts/build-package.ps1
+```
+
+Output: `dist/puppets-orchestration.zip`. Extract it to use the shared workspace manually. For another build, choose a new output filename with `-OutputPath`; existing archives are preserved. The exporter is source tooling and is not installed by `init`.
+
+## License and Publication Status
+
+Publication is configured as public under the lowercase npm scope `@exelalfanso`. Log in with an npm account authorized for that scope, confirm the package's distribution license, and publish the verified tarball from the source root:
+
+```sh
+npm login
+npm whoami
+npm publish ./dist/exelalfanso-puppets-orchestration-0.1.0.tgz --access public
+```
+
+The package has not been published to npm. Its original material is temporarily marked `UNLICENSED` until the owner selects a distribution license.
+
+Bundled skills retain their upstream metadata and available license files. Their sources are documented in the [skill catalog](skills/README.md), `skills-lock.json`, and the worker snapshot notes.

package/bin/puppets.mjs

@@ -0,0 +1,152 @@
+#!/usr/bin/env node
+import { existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, realpathSync, writeFileSync } from 'node:fs';
+import { dirname, join, relative, resolve, sep } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { execFileSync } from 'node:child_process';
+
+const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+const roles = ['orchestrator', 'architect', 'backend', 'frontend', 'explorer', 'debugger', 'reviewer', 'tester'];
+const help = `Puppets Orchestration
+
+Usage:
+  puppets-orchestration init [workspace-directory]
+  puppets-orchestration init-project [repo-directory] --workspace <workspace-directory>
+
+init creates the shared workspace without Git history.
+init-project adds local coordination state to an existing Git checkout.
+Existing files are preserved. Project AGENTS.md and .gitignore receive additive guidance.
+`;
+
+function ensureDirectory(root, directory) {
+  const segments = relative(root, directory).split(sep).filter(Boolean);
+  if (segments.includes('..')) throw new Error('Destination must stay inside the selected directory.');
+  let current = root;
+  for (const segment of segments) {
+    current = join(current, segment);
+    if (existsSync(current)) {
+      const stat = lstatSync(current);
+      if (stat.isSymbolicLink() || !stat.isDirectory()) throw new Error(`Expected a normal directory: ${current}`);
+    } else {
+      mkdirSync(current);
+    }
+  }
+}
+
+function writeMissing(root, destination, content) {
+  const path = join(root, destination);
+  ensureDirectory(root, dirname(path));
+  try {
+    writeFileSync(path, content, { flag: 'wx' });
+  } catch (error) {
+    if (error.code !== 'EEXIST') throw error;
+    if (lstatSync(path).isSymbolicLink() || !lstatSync(path).isFile()) throw new Error(`Expected a normal file: ${path}`);
+  }
+}
+
+function copyMissing(root, source, destination) {
+  const stat = lstatSync(source);
+  if (stat.isSymbolicLink()) throw new Error(`Symlink is not a distributable asset: ${source}`);
+  if (stat.isDirectory()) {
+    ensureDirectory(root, join(root, destination));
+    for (const entry of readdirSync(source)) copyMissing(root, join(source, entry), join(destination, entry));
+  } else {
+    writeMissing(root, destination, readFileSync(source));
+  }
+}
+
+function appendText(root, filename, update) {
+  const path = join(root, filename);
+  if (existsSync(path) && (lstatSync(path).isSymbolicLink() || !lstatSync(path).isFile())) {
+    throw new Error(`Expected a normal file: ${path}`);
+  }
+  const current = existsSync(path) ? readFileSync(path, 'utf8') : '';
+  const addition = update(current);
+  if (addition) writeFileSync(path, current + (current && !current.endsWith('\n') ? '\n' : '') + addition);
+}
+
+function ignoreRules(root, rules) {
+  appendText(root, '.gitignore', current => {
+    const existing = new Set(current.split(/\r?\n/).map(line => line.trim()));
+    const missing = rules.filter(rule => !existing.has(rule));
+    return missing.length ? '\n# Puppets local coordination and workspace outputs\n' + missing.join('\n') + '\n' : '';
+  });
+}
+
+function scaffoldState(root, state) {
+  ensureDirectory(root, join(root, '.orchestration/tasks'));
+  ensureDirectory(root, join(root, '.orchestration/runs'));
+  writeMissing(root, '.orchestration/state.md', state);
+}
+
+function initWorkspace(path) {
+  mkdirSync(path, { recursive: true });
+  const root = realpathSync(path);
+  if (root === packageRoot || packageRoot.startsWith(root + sep) || root.startsWith(packageRoot + sep)) {
+    throw new Error('Choose a workspace outside the installed package directory.');
+  }
+  for (const asset of ['README.md', 'AGENTS.md', 'skills-lock.json', 'docs', 'skills', '.agents/worker-skills.md']) {
+    copyMissing(root, join(packageRoot, asset), asset);
+  }
+  for (const role of roles) copyMissing(root, join(packageRoot, `.agents/${role}.md`), `.agents/${role}.md`);
+  for (const category of readdirSync(join(packageRoot, 'skills'), { withFileTypes: true }).filter(entry => entry.isDirectory())) {
+    if (category.name === 'worker') continue;
+    for (const skill of readdirSync(join(packageRoot, 'skills', category.name), { withFileTypes: true }).filter(entry => entry.isDirectory())) {
+      copyMissing(root, join(packageRoot, 'skills', category.name, skill.name), `.agents/skills/${skill.name}`);
+    }
+  }
+  scaffoldState(root, readFileSync(join(packageRoot, 'templates/state.md'), 'utf8'));
+  ignoreRules(root, ['/.orchestration/', '/repos/', '/dist/']);
+  console.log(`Workspace ready: ${root}\nShared roles, documentation, and skills installed; existing files preserved.`);
+}
+
+function git(root, args) {
+  return execFileSync('git', ['-C', root, ...args], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] }).trim();
+}
+
+function initProject(path, workspacePath) {
+  const root = realpathSync(path);
+  const workspace = realpathSync(workspacePath);
+  const gitRoot = realpathSync(git(root, ['rev-parse', '--show-toplevel']));
+  if (root !== gitRoot) throw new Error('Select the Git checkout root, not a subdirectory.');
+  if (root === workspace) throw new Error('The project and shared workspace must be separate directories.');
+  if (!existsSync(join(workspace, '.agents/orchestrator.md')) || !existsSync(join(workspace, 'AGENTS.md'))) {
+    throw new Error('Shared workspace is missing its AGENTS.md or orchestrator role. Run init first.');
+  }
+  if (git(root, ['ls-files', '--', '.orchestration'])) {
+    throw new Error('.orchestration is already tracked. Resolve its migration before running init-project; no files have been changed.');
+  }
+  let branch;
+  try { branch = git(root, ['symbolic-ref', '--quiet', '--short', 'HEAD']); }
+  catch { branch = `detached ${git(root, ['rev-parse', '--short', 'HEAD'])}`; }
+  const state = readFileSync(join(packageRoot, 'templates/state.md'), 'utf8')
+    .replace('TBD — select a project checkout and record its branch.', `- Checkout: ${root}\n- Branch: ${branch}\n- Shared workspace: ${workspace}`);
+  scaffoldState(root, state);
+  ignoreRules(root, ['/.orchestration/']);
+  const workspaceLink = relative(root, workspace).split(sep).join('/');
+  appendText(root, 'AGENTS.md', current => current.includes('<!-- puppets-orchestration -->') ? '' : `\n<!-- puppets-orchestration -->\n## Shared Orchestration Context\n\nShared workspace: ${JSON.stringify(workspaceLink)} (relative to this repo root).\nLoad its AGENTS.md, the applicable role in .agents/, and docs/engineering/project-orchestration.md explicitly.\nUse this checkout's .orchestration/ for task state and evidence; keep it ignored by Git.\nKeep durable requirements and decisions in this repo's docs/ and project rules in AGENTS.md.\nExisting project instructions remain authoritative for project-specific behavior.\n`);
+  git(root, ['check-ignore', '--', '.orchestration/state.md']);
+  console.log(`Project ready: ${root}\nLocal .orchestration is ignored; commit AGENTS.md and .gitignore after review.`);
+}
+
+try {
+  const args = process.argv.slice(2);
+  const command = args.shift();
+  if (!command || command === '--help' || command === '-h') {
+    console.log(help);
+  } else if (command === 'init') {
+    if (args.length > 1 || args[0]?.startsWith('-')) throw new Error(help);
+    initWorkspace(resolve(args[0] || '.'));
+  } else if (command === 'init-project') {
+    const workspaceIndex = args.indexOf('--workspace');
+    if (workspaceIndex < 0 || !args[workspaceIndex + 1] || args[workspaceIndex + 1].startsWith('-')) throw new Error(help);
+    const workspace = args[workspaceIndex + 1];
+    args.splice(workspaceIndex, 2);
+    if (args.length > 1 || args[0]?.startsWith('-')) throw new Error(help);
+    initProject(resolve(args[0] || '.'), resolve(workspace));
+  } else {
+    throw new Error(`Unknown command: ${command}\n${help}`);
+  }
+} catch (error) {
+  console.error(`Error: ${error.message}`);
+  process.exitCode = 1;
+}