@exelalfanso/puppets-orchestration 0.1.0

package/docs/README.md

@@ -0,0 +1,64 @@
+# Project Documentation
+
+These documents are the source of truth for product and engineering information. The repository currently provides a foundation; no product application has been implemented. Technology preferences exist, but the application stack has not been selected.
+
+## Sources of Truth
+
+| Information | Document | Status |
+| --- | --- | --- |
+| Product problem, users, goals, scope, and outcomes | [PRD](product/PRD.md) | Draft; product decisions TBD |
+| Software behavior and acceptance criteria | [SRS](requirements/SRS.md) | Draft; no accepted product requirements |
+| System boundaries and responsibilities | [Architecture overview](architecture/overview.md) | Repository baseline recorded; product architecture TBD |
+| Technology preferences | [JavaScript/TypeScript stack](javascript-typescript-stack.md) | Includes Rust/Tauri backends for large desktop applications; application stack undecided |
+| Technical decision rationale | [ADR index](architecture/decisions/README.md) | No application ADRs yet |
+| Code structure and engineering standards | [Conventions](engineering/conventions.md) | Baseline for initial implementation |
+| Verification approach | [Testing strategy](engineering/testing-strategy.md) | Strategy available; product tooling and CI TBD |
+| Coordination setup per repository/checkout | [Project orchestration](engineering/project-orchestration.md) | Local state per project, required to be ignored by Git |
+
+Flow: PRD goals → SRS requirements → architecture boundaries and ADRs → implementation → tests → operations. Technology decisions belong in architecture and ADRs rather than product requirements.
+
+## Documents Created When Needed
+
+| Document | Create when | Implementation source to reference |
+| --- | --- | --- |
+| `requirements/glossary.md` | Domain terms require shared definitions | PRD and SRS |
+| `architecture/api-contract.md` | An interface will be consumed by another component | Machine-readable specification or contract types/schemas; select during architecture design |
+| `architecture/erd.md` | Persistent domain entities and relationships are defined | Migrations for exact schema details |
+| `engineering/security.md` | Data boundaries, authentication, authorization, or sensitive integrations are defined | Security requirements in SRS; initial rules are in conventions |
+| `operations/deployment.md` | Deployment targets and release procedures are selected | Actual build/IaC configuration and migration/rollback procedures |
+| `operations/runbook.md` | Services are operated and diagnosis/recovery procedures exist | Available health checks, logs, metrics, and recovery procedures |
+
+Do not infer endpoints, entities, staging/production environments, queues, or recovery procedures from documentation examples. Mark unknown information as **TBD** or **Open Question** in its owning document.
+
+## IDs and Traceability
+
+- Product goals: `PG-001`, `PG-002`, and so on, owned by the PRD.
+- Requirements: `FR-<DOMAIN>-001` or `NFR-<AREA>-001`; use `SEC`, `PERF`, `REL`, and `OBS` for specific categories when useful.
+- Decisions: `ADR-001`, `ADR-002`, and so on, following the [ADR rules](architecture/decisions/README.md).
+- IDs remain stable when titles or details change. Retired IDs are not reused.
+- Implementation tasks in `.orchestration/tasks/` reference requirement IDs, acceptance criteria, and relevant documents. Maintenance tasks such as documentation setup may state that product requirements do not yet apply.
+- The SRS links requirements to PRD goals and implementation/test evidence when available. Avoid duplicating that matrix elsewhere.
+
+## Loading Context for Humans and Agents
+
+Use [AGENTS.md](../AGENTS.md) and roles in `.agents/` for agent working rules. Then select documentation according to the task:
+
+| Work | Documentation context |
+| --- | --- |
+| Product/planning | PRD, SRS, glossary when available |
+| Architecture | SRS, overview, relevant ADRs, stack preferences |
+| Backend/data | Relevant requirements, API contract/ERD when available, ADRs, conventions, related source/migrations |
+| Frontend | Relevant requirements, API contract and UI specification when available, conventions, related source |
+| Testing/review | Task, requirement IDs, acceptance criteria, relevant constraints/ADRs, diff, verification results |
+
+Progress, assignments, and run records belong only in `.orchestration/`. Documentation retains facts and decisions that remain useful after a task ends.
+
+## Update Policy
+
+Update each source of truth with its implementation change: behavior → SRS and tests; interfaces → contracts and tests; boundaries → overview and ADRs when trade-offs matter; data relationships → migrations and ERD; release/recovery → operations documentation.
+
+When documents conflict, record the inconsistency, resolve it through the owning document, and correct affected documents. Do not silently select one account. Review changes for valid links and consistency with the implementation.
+
+## Next Step
+
+Answer the [PRD open questions](product/PRD.md#open-questions) about the user problem and MVP scope. Translate agreed goals into SRS requirements with acceptance criteria before selecting the application architecture.

package/docs/architecture/decisions/README.md

@@ -0,0 +1,36 @@
+# Architecture Decision Records
+
+ADRs explain technical choices with meaningful trade-offs, effects across several boundaries, costly reversals, or reasoning future developers need to understand. User preferences in the [stack guide](../../javascript-typescript-stack.md) remain decision inputs; no application stack choice has become an Accepted ADR.
+
+## Register
+
+No application ADRs exist yet. Examples are not treated as actual decisions.
+
+## Recording Rules
+
+- Use sequential filenames such as `ADR-001-title.md`; never reuse IDs.
+- Status: Proposed, Accepted, Rejected, or Superseded.
+- Include Context, Decision, Alternatives Considered, and Consequences. Link to the relevant requirements or boundaries.
+- Explain why alternatives were rejected and the costs/risks of the choice, beyond naming a library.
+- Replace an Accepted decision with a new ADR. Mark the original Superseded, link both records, and preserve the historical reasoning.
+- Link each ADR from this register and from the overview when it changes system boundaries.
+
+## Format
+
+```md
+# ADR-XXX — Decision Title
+
+Status: Proposed
+
+## Context
+The problem, requirements, constraints, and conditions requiring a decision.
+
+## Decision
+The proposed or accepted choice and its scope.
+
+## Alternatives Considered
+Actual alternatives, their advantages and limitations, and the reasons for selection.
+
+## Consequences
+Benefits, costs, risks, and required changes.
+```

package/docs/architecture/overview.md

@@ -0,0 +1,41 @@
+# Architecture Overview
+
+Status: Repository baseline — application architecture TBD. This document records existing boundaries and will describe product boundaries once the [SRS](../requirements/SRS.md) is agreed.
+
+## System Context
+
+Human developers and AI coding agents use this repository to prepare software work. No product client, API service, database, or application runtime workload has been implemented.
+
+Workspace tooling is available as the npm package `@exelalfanso/puppets-orchestration`: its CLI creates a shared workspace and local state in a target repository. See the [workspace README](../../README.md) for usage.
+
+## Major Components and Responsibilities
+
+| Repository boundary | Responsibility |
+| --- | --- |
+| `AGENTS.md` and `.agents/*.md` | Shared rules and agent roles |
+| `docs/` | Durable product intent, requirements, architecture, decisions, and engineering guidance |
+| `.orchestration/` | Temporary tasks, dependencies, progress, and run records |
+| `skills/` | Categorized skill references |
+| `bin/` and `templates/` | Bootstrap CLI with no external runtime dependencies and fresh state templates for npm distribution |
+
+Application boundaries, service ownership, and communication are TBD. Agent roles do not define the product architecture.
+
+## Data Flow
+
+Application data flow: TBD. The [documentation index](../README.md) describes the documentation and implementation flow.
+
+## External Dependencies
+
+Application dependencies have not been installed or selected. Use the [stack preferences](../javascript-typescript-stack.md) as input and record choices with meaningful trade-offs in [ADRs](decisions/README.md).
+
+## Trust Boundaries
+
+Client/server boundaries, identity, access permissions, data classification, and external integrations are TBD until product scope is defined. Initial engineering rules are in [conventions](../engineering/conventions.md).
+
+## Deployment Model
+
+TBD: hosting targets, application processes, and environments. No staging, production, or deployment pipeline is documented as available.
+
+## Important Constraints
+
+Keep the repository foundation small and file-based, following [AGENTS.md](../../AGENTS.md). Create the API contract and ERD when interfaces and persistent entities are defined, following the [documentation triggers](../README.md#documents-created-when-needed).

package/docs/engineering/conventions.md

@@ -0,0 +1,30 @@
+# Engineering Conventions
+
+Status: Baseline for initial implementation. Application source structure, formatter, lint tooling, and script names have not been selected. This document governs project code; [AGENTS.md](../../AGENTS.md) governs agent working rules.
+
+## Repository and Module Boundaries
+
+Follow the [architecture boundaries](../architecture/overview.md) and [documentation ownership](../README.md). Select application source structure once boundaries are known; add layers or services only when needed.
+
+Shared contract types and schemas must not import secrets, database connections, or server implementations into the frontend. Give application modules clear responsibilities and connect dependencies across boundaries through agreed contracts.
+
+## Naming and Dependencies
+
+Use consistent domain terminology; create a glossary when shared definitions are needed. Technology choices follow the [stack guide](../javascript-typescript-stack.md). Link to it rather than duplicating the stack list. Commit dependency lockfiles and document scripts once tooling is available.
+
+## Validation and Error Handling
+
+Validate external input at system boundaries. TypeScript types alone do not establish runtime validity. Keep shared schemas at contract boundaries and link their implementations from the API contract when available.
+
+Distinguish expected input/domain errors from internal failures. Contracts define public error shapes; internal details and stack traces are not sent to users. Select effects/error patterns according to project needs and technical decisions.
+
+## Initial Security and Logging Rules
+
+- Keep secrets out of source, documentation, logs, and test artifacts. Document configuration names and provisioning methods when integrations exist.
+- Do not log credentials, session tokens, or sensitive payloads. Select diagnostic metadata according to agreed data classification.
+- Private-access features must enforce authorization at the server boundary for each resource. UI restrictions alone are insufficient.
+- Authentication, access models, auditing, retention, and sensitive integrations are TBD. Move details to `security.md` when those boundaries are defined, keeping a single source of rules.
+
+## Code Review
+
+Behavior changes include requirement IDs and verification evidence following the [testing strategy](testing-strategy.md). Review covers contracts across boundaries, sensitive data, dependency changes, and updates to owning documents. Project-specific branch/release workflows are TBD; no CI or merge rules are claimed active.

package/docs/engineering/project-orchestration.md

@@ -0,0 +1,118 @@
+# Orchestration per Repository/Project
+
+The central workspace holds shared rules and agent roles. Each project repository keeps its own orchestration state at the active checkout root. The agent selects the target repository from the user's instructions and uses that directory for the project's tasks and runs.
+
+## Minimal Structure
+
+```text
+workspace/
+├── AGENTS.md
+├── .agents/                 # Shared roles
+├── skills/                  # Shared skill references
+└── repos/
+    └── project-a/           # Separate Git repository
+        ├── AGENTS.md        # Project rules, committed
+        ├── .gitignore       # Ignore rules, committed
+        ├── docs/            # Project requirements/decisions, committed
+        └── .orchestration/  # Local coordination, ignored
+            ├── state.md
+            ├── tasks/
+            └── runs/
+```
+
+Repositories may live outside `repos/`; always specify the target path. Shared roles and skills do not need to be copied into every project. When a repository is opened independently or outside the central workspace, the orchestrator explicitly loads shared rules/roles rather than assuming parent instructions are available.
+
+| Content | Purpose |
+| --- | --- |
+| `state.md` | Target repository/checkout, branch, active goal, phase, tasks, and blockers |
+| `tasks/<ID>.md` | Scope, dependencies, related requirements, acceptance criteria, and outcome report for one task |
+| `runs/` | Command evidence, attempts, failures, and review results useful to the active run |
+
+Follow the task protocol in [AGENTS.md](../../AGENTS.md). Task IDs are local to each repository/checkout. Include the repository name and task ID in communication across projects.
+
+## Setting Up the Selected Repository
+
+The npm CLI can perform the initial setup:
+
+```sh
+npx @exelalfanso/puppets-orchestration init-project <repo-path> --workspace <shared-workspace-path>
+```
+
+This registry command becomes available after publication; see the [workspace README](../../README.md) for local tarball usage. The command preserves existing state and adds project guidance and ignore rules. It rejects already-tracked orchestration state before modifying the repository.
+
+For manual setup or ongoing work:
+
+1. Confirm the absolute target path, Git root, branch, and checkout/worktree. Run implementation commands from that checkout.
+2. Read its `AGENTS.md` and existing documentation, then load relevant shared roles.
+3. Add `/.orchestration/` to the target's `.gitignore`, preserving existing rules.
+4. Create `.orchestration/state.md`, `tasks/`, and `runs/` if missing. Preserve existing state and reconcile it against the branch, code, and current goal before continuing.
+5. Record the target identity in state. Create local tasks before delegation and follow the shared dependency and acceptance protocol.
+6. When switching projects, read the destination project's state. Keep each project's tasks and progress in its own checkout.
+
+Each worktree has its own local `.orchestration/`. Keep state separate for parallel checkouts and verify older checkout state against the current branch.
+
+Initial `state.md` example:
+
+```md
+# Project State
+
+## Target
+- Project: <repository name>
+- Checkout: <absolute path>
+- Branch: <current branch>
+
+## Goal
+TBD — set from the user's instructions.
+
+## Phase
+Ready for task planning.
+
+## Active Tasks
+None.
+
+## Blockers
+None identified; reassess when the goal is defined.
+```
+
+## Required Git Ignore Rule
+
+Add this rule to `.gitignore` at each project repository root:
+
+```gitignore
+# Local agent coordination state
+/.orchestration/
+```
+
+State, assignments, attempts, and run evidence change during agent work and belong to a local checkout. Ignoring the directory keeps temporary progress out of commits, diffs, and merge conflicts. Commit `.gitignore` so the rule applies to all clones. Bootstrap `.orchestration/` when work begins in a new clone or checkout.
+
+Durable requirements, technical decisions, contracts, and operational guidance belong in the project's `docs/`. Stable project rules belong in `AGENTS.md`. Commit both. Record verification evidence needed by collaborators in a PR or CI; durable documentation must remain useful without ignored local files.
+
+Verify from the target repository root:
+
+```sh
+git check-ignore -v -- .orchestration/state.md
+git ls-files -- .orchestration
+```
+
+The first command must show the ignore rule; the second must return no files. `.gitignore` does not untrack existing files. If state is already tracked, report it. Migrate it out of the index as a separately agreed change, preserving local files and first moving durable decisions into `docs/`.
+
+For projects under `repos/`, add `/repos/` to the central workspace's `.gitignore` so project repositories are excluded from its Git history. Each project still needs its own `/.orchestration/` rule. This bootstrap guide does not automatically change the tracked orchestration foundation in the source workspace.
+
+## Ready-to-Use Agent Context
+
+```text
+Target project: <absolute repository/checkout path>
+Shared orchestration workspace: <absolute shared workspace path>
+
+Read the shared AGENTS.md and relevant role, then the target's AGENTS.md and docs.
+Confirm the Git root, branch, and target checkout before changing files.
+Bootstrap .orchestration/state.md, tasks/, and runs/ at the target root if missing.
+Preserve existing content and reconcile state against the code and user goal.
+Add /.orchestration/ to the target's .gitignore without replacing other rules.
+Verify the ignore rule and confirm no .orchestration files are tracked.
+Report tracked state; do not automatically remove files or index entries.
+Use only the target's .orchestration for tasks, dependencies, progress, and run evidence.
+Keep durable requirements, decisions, and conventions in the target's docs/ or AGENTS.md,
+and commit them with related changes.
+Keep target project implementation state separate from shared workspace coordination.
+```

package/docs/engineering/testing-strategy.md

@@ -0,0 +1,41 @@
+# Testing Strategy
+
+Status: Initial product strategy; no application or CI checks exist. Workspace CLI tooling has tests using Node.js's built-in test runner. Product test tooling has not been selected.
+
+## Workspace Tooling Verification
+
+Run `npm test` from the source repository. CLI tests cover workspace bootstrap without Git history, preservation of existing files/progress on repeat setup, per-repository state isolation, ignore rules, and rejection of tracked coordination state. Tests use temporary directories rather than user project repositories.
+
+Run `npm run pack:local` to build a tarball. Check the package allowlist and smoke-test `init`/`init-project` from the tarball before distributing a new version. See the [workspace README](../../README.md) for local commands.
+
+## Testing Goals
+
+Verify [SRS acceptance criteria](../requirements/SRS.md) deterministically and according to risk. Focus on observable behavior, error paths, and data/access boundaries. Avoid tests that merely repeat implementation details.
+
+## Selecting Test Types
+
+| Type | Use for |
+| --- | --- |
+| Unit | Pure domain logic and boundary cases that need no real services |
+| Integration | Behavior between modules and database/auth interactions when those components exist |
+| Contract | Schema, request/response, and error consistency across client/server boundaries; API typing does not replace runtime validation |
+| End-to-end | Primary user flows and important failures agreed in the PRD/SRS |
+| Performance | Measurable performance requirements; establish budgets and load profiles from actual needs |
+
+Not every change needs every test type. Select verification that provides evidence for affected requirements.
+
+## Traceability
+
+The SRS stores requirement → task/code/test links when available. Test names or descriptions may include requirement IDs to make evidence easy to find. Update acceptance criteria and related tests with implementation when requirements change.
+
+## Test Environment
+
+Product test tooling and configuration are TBD after framework selection. Isolate test data, control time/randomness when relevant, and clean up state. Fixtures must not contain production data or secrets.
+
+## Required CI Checks
+
+No CI is configured. During initial application implementation, select available lint/format, typecheck, build, and test commands and record their passing criteria here. Mark checks required/active only once their workflows exist.
+
+## Documentation Verification
+
+For documentation changes, check local links, source-of-truth consistency, IDs, and accuracy against the repository. Documentation-only changes do not require runtime tests. Keep temporary evidence in `.orchestration/` rather than treating it as a permanent product fact.

package/docs/javascript-typescript-stack.md

@@ -0,0 +1,59 @@
+# JavaScript and TypeScript Stack
+
+Status: user preferences for JavaScript/TypeScript projects, with Rust through Tauri as the backend for large desktop applications. This project's application stack has not been selected. Record final decisions with meaningful trade-offs in [ADRs](architecture/decisions/README.md). The [architecture overview](architecture/overview.md) owns application boundaries.
+
+Choose frameworks according to project size and complexity. Not every project needs every component below.
+
+## Rust Backend Through Tauri
+
+For large desktop projects, use Tauri with Rust as the application backend. The frontend uses JavaScript/TypeScript with React or Vue. This covers backend logic and native capabilities through Tauri; frontend choices follow the desktop application's needs.
+
+The frontend/Tauri backend communication contract is TBD during architecture design. ElysiaJS and Eden Treaty apply when a project has a TypeScript API server. Bun and pnpm serve the JavaScript/TypeScript parts; Rust/Tauri build configuration is selected during implementation.
+
+## Core Tools
+
+| Area | Choice | Notes |
+| --- | --- | --- |
+| Runtime | Bun | Runtime for server-side JavaScript and TypeScript. |
+| Package manager | pnpm | Install and manage project dependencies with pnpm. |
+| API server backend | ElysiaJS | Build TypeScript APIs, especially when running on Bun. |
+| Large desktop backend | Rust + Tauri | Desktop application backend with a JavaScript/TypeScript frontend. |
+| Frontend/backend API types | Eden Treaty | Share Elysia route types with the frontend for typed API calls. |
+| Validation | Zod | Define schemas at input boundaries and share schemas or inferred types where needed. |
+| Authentication | Better Auth | Preferred authentication library. |
+| Infrastructure as code | Alchemy | Preferred IaC tool. |
+| Effects | Effect TS | Use for typed effects and structured error handling when helpful; keep simple code direct. |
+| Event/job delivery to workers | BullMQ | Queue events as jobs for background workers. |
+| Queue storage | Redis | BullMQ dependency for queue and job state storage. |
+
+## Events and Background Workers
+
+Use BullMQ for asynchronous event/job delivery to workers when background processing is needed. A producer adds an event as a job to a BullMQ queue stored in Redis; a worker picks up and processes the job. This follows the [BullMQ queue model](https://docs.bullmq.io/guide/queues/).
+
+Flow: producer → BullMQ/Redis queue → worker.
+
+Payload schemas, queue names, retry/backoff, idempotency, concurrency, and failed-job handling are TBD according to product needs. If the producer runs in the Rust/Tauri backend, define its integration boundary with BullMQ during architecture design. Record event contracts in the API contract and integration decisions with meaningful trade-offs in ADRs.
+
+## UI Libraries
+
+- React: shadcn/ui.
+- Vue: VUX.
+
+Open Question: confirm the intended VUX package and version before implementing Vue. This preference is retained as requested by the user.
+
+## Database Selection
+
+- SQLite for small, uncomplicated projects with limited relational needs.
+- PostgreSQL for complex projects, many related entities, or substantial relational queries.
+
+## Frameworks by Project Size
+
+| Project size | React | Vue | Build/framework direction |
+| --- | --- | --- | --- |
+| Small to medium | React + TanStack Router | Vue + Vue Router | Vite |
+| Large web application | TanStack Start | Nuxt | Select the full-stack framework for the chosen UI ecosystem. |
+| Large desktop application | React | Vue | JavaScript/TypeScript frontend + Rust backend through Tauri; build/router integration TBD. |
+
+## Selection Guidance
+
+Start with the smallest setup that meets product needs. For small or medium client-focused applications, use Vite and the router for the chosen framework. For large web applications that need server rendering and full-stack conventions, use TanStack Start for React or Nuxt for Vue.

package/docs/product/PRD.md

@@ -0,0 +1,56 @@
+# Product Requirements Document
+
+Status: Draft — product intent has not been defined. The repository name and agent roles do not establish product features. Use this document to agree on goals before implementation.
+
+## Overview
+
+TBD: product summary and the value it provides. The repository is being prepared for product work; see the [technical baseline](../architecture/overview.md).
+
+## Problem Statement
+
+TBD: the user problem, its impact, and how it is currently addressed.
+
+## Target Users
+
+TBD: primary users, their usage context, and decision makers.
+
+## User Needs
+
+TBD: needs supported by evidence or product owner approval.
+
+## Product Goals
+
+No product goals have been accepted. Assign agreed goals IDs such as `PG-001` according to the [ID rules](../README.md#ids-and-traceability).
+
+## Non-Goals
+
+TBD: scope boundaries explicitly agreed for the first release.
+
+## Core Features
+
+TBD: features needed to achieve the goals, their priorities, and related goal IDs.
+
+## User Flows
+
+TBD: primary flows, starting conditions, successful outcomes, and relevant failure outcomes.
+
+## Success Criteria
+
+TBD: measurable outcomes for each goal, including the measure, target, and evaluation method.
+
+## Constraints
+
+TBD: deadlines, budget, user needs, or business limits. Architecture and ADRs own technical choices.
+
+## Assumptions
+
+No product assumptions have been accepted. Record assumptions and how to validate them before using them to define scope.
+
+## Open Questions
+
+- What problem should be solved, and who are the primary users?
+- Which primary flow must succeed in the MVP?
+- What belongs in the first release, and which features are deferred?
+- How will success be measured, and are there deadlines or budget limits?
+
+Translate the answers into [SRS](../requirements/SRS.md) requirements. Keep endpoint and database schema decisions in their owning technical documents.

package/docs/requirements/SRS.md

@@ -0,0 +1,35 @@
+# Software Requirements Specification
+
+Status: Draft — no product requirements have been accepted. The SRS translates [PRD goals](../product/PRD.md) into verifiable software behavior.
+
+## Functional Requirements
+
+TBD: software behavior based on agreed product goals. Do not infer authentication, task execution, or other features from installed skills or agent roles.
+
+## Non-Functional Requirements
+
+TBD: measurable quality targets appropriate to product risk, including security, performance, reliability, and observability when relevant. Latency, capacity, availability, and retention targets have not been selected.
+
+## Constraints
+
+TBD: required operational or compatibility limits. [Stack preferences](../javascript-typescript-stack.md) inform technical decisions; they do not define software behavior requirements.
+
+## Requirement Format and Traceability
+
+Follow the [ID rules](../README.md#ids-and-traceability). Each requirement includes:
+
+| Field | Content |
+| --- | --- |
+| ID and title | Stable ID and a short description of the behavior |
+| Status | Draft, Accepted, or Retired |
+| Basis | Link to a `PG-*` goal or an accepted constraint |
+| Behavior | Required software behavior, including trigger conditions and outcomes |
+| Acceptance criteria | Observable results for success, errors, and relevant boundaries |
+| Verification | Test type and passing criteria; link to files/results when available |
+| Implementation | Related tasks, code, and contracts when available; TBD until implemented |
+
+Non-functional requirements must specify a measure, target, measurement conditions, and verification method. Define ambiguous domain terms in a glossary when needed.
+
+## Open Questions
+
+Behavior and priorities await answers to the [PRD questions](../product/PRD.md#open-questions). Quality targets and data/access boundaries follow the primary flow definition. See the [testing strategy](../engineering/testing-strategy.md) for verification guidance.

package/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "@exelalfanso/puppets-orchestration",
+  "version": "0.1.0",
+  "description": "File-based orchestration workspace and per-repository agent coordination setup",
+  "type": "module",
+  "license": "UNLICENSED",
+  "author": "ExelAlfanso",
+  "repository": { "type": "git", "url": "git+https://github.com/ExelAlfanso/puppets.git" },
+  "homepage": "https://github.com/ExelAlfanso/puppets#readme",
+  "bugs": { "url": "https://github.com/ExelAlfanso/puppets/issues" },
+  "publishConfig": { "access": "public", "registry": "https://registry.npmjs.org/" },
+  "engines": { "node": ">=20" },
+  "bin": { "puppets-orchestration": "bin/puppets.mjs" },
+  "files": ["bin/", "templates/", "AGENTS.md", ".agents/*.md", "docs/", "skills/", "skills-lock.json"],
+  "scripts": {
+    "test": "node --test tests/cli.test.mjs",
+    "prepack": "node -e \"require('node:fs').mkdirSync('dist', {recursive:true})\"",
+    "pack:local": "npm pack --pack-destination dist"
+  }
+}

package/skills/README.md

@@ -0,0 +1,12 @@
+# Skill Catalog
+
+Skills are grouped by topic for browsing. The installed copies in `.agents/skills/` are the active project skills; `npx skills` manages those. Most categorized folders mirror them for an easy overview. `worker/` is an exception: its snapshots are loaded explicitly by implementation workers and are not mirrored into `.agents/skills/`.
+
+- `vue/`: Vue and Vue ecosystem
+- `react/`: React and composition patterns
+- `fe/`: General frontend design and interface guidelines
+- `be/`: Backend architecture, feature delivery, Node.js patterns, and security
+- `qa/`: QA skills for reviewing tests, coverage, risks, and release evidence; role guidance is in `.agents/reviewer.md`
+- `worker/`: Ponytail and Caveman for implementation workers only; see [worker policy](../.agents/worker-skills.md)
+
+Sources include `vuejs-ai/skills`, `vercel-labs/agent-skills`, `anthropics/skills`, `agent-skills-hub/agent-skills-hub`, and `petrkindlmann/qa-skills`.