pnpm Workspace Maintenance

# pnpm Workspace Maintenance

This is the Claude Code entry point for a complete AI development setup. Read `my-roster/monorepo-maintenance/README.md` before changing repository instructions.

## Orchestrator contract

Choose the smallest listed workflow that fits the request. Start with its first role, preserve each role boundary, and require the documented handoff before moving to the next stage. Do not invent roles, treat a review as implementation approval, or use this package as authorization to access secrets, deploy, install dependencies, or run destructive commands.

## Package artifacts

- Package guide: `my-roster/monorepo-maintenance/README.md`
- Role: Monorepo Maintainer — `my-roster/monorepo-maintenance/agents/monorepo-maintainer.md`
- Role: Workspace Reviewer — `my-roster/monorepo-maintenance/agents/workspace-reviewer.md`
- Skill: Workspace impact mapping — `my-roster/monorepo-maintenance/skills/workspace-impact-mapping.md`
- Skill: Targeted workspace validation — `my-roster/monorepo-maintenance/skills/targeted-workspace-validation.md`
- Workflow: Workspace change review — `my-roster/monorepo-maintenance/workflows/workspace-change-review.md`

## Runtime scope

Claude Code reads CLAUDE.md as project memory. Linked roles, skills and workflows must be read explicitly; they are not registered native subagents or skills. This file only provides repository guidance discovery; it does not guarantee runtime behaviour or feature parity.

# pnpm Workspace Maintenance for Claude Code

AI development setup · v0.3

Maintain a pnpm workspace package with dependency-impact mapping and verified consumer checks.

## Audience and scope

Maintainers of an existing pnpm workspace need a package, dependency or shared-configuration change with an explicit consumer impact map.

Monorepo Maintainer owns the scoped work; Workspace Reviewer challenges its evidence and failure paths. Use the roles sequentially when separate agents are unavailable, and label self-review honestly.

## Not covered

Does not flatten package boundaries or upgrade every dependency without scope.

## Before adding it to a repository

1. Inspect the complete archive in a temporary extraction directory. Compare every destination, including the existing my-roster/monorepo-maintenance folder.
2. Check whether CLAUDE.md already exists. Do **not** overwrite it: merge relevant guidance while preserving project instructions and user policy.
3. Copy the matching my-roster/monorepo-maintenance folder to the repository root only after resolving path conflicts. Keep a recoverable copy or commit of the previous instructions.
4. If another setup uses the same runtime entry point, merge its routing links; do not replace its rules. Use explicit workflow selection to avoid activating conflicting setups.
5. Read the project manifest and existing instructions. Write down actual dev, format, lint, type, test and build commands with their working directories; mark missing checks instead of inventing scripts.
6. Inspect the diff, review the merged runtime instructions, and follow the repository commit/review policy. Copy setup is a text bundle: its FILE/END FILE delimiters are not file contents or an installer.

## Why these files are at the ZIP root

The selected runtime entry point is CLAUDE.md. Keep it at that repository-relative path and keep the linked package at my-roster/monorepo-maintenance. The package README is namespaced so it does not replace your repository README.

## Package tree

~~~text
CLAUDE.md  # selected runtime entry point
my-roster/monorepo-maintenance/
  README.md
  agents/monorepo-maintainer.md
  agents/workspace-reviewer.md
  skills/workspace-impact-mapping.md
  skills/targeted-workspace-validation.md
  workflows/workspace-change-review.md
~~~

## Task input

- pnpm version, workspace configuration, package manifests and lockfile.
- Target package, requested change, public exports and affected consumers.

## Start a workflow

Read the Workspace change review workflow. Task: [replace with your concrete request]. Example of appropriate scope: Change shared types, list dependent apps and check each affected consumer. Follow the listed role/skill files, preserve existing repository instructions and report evidence before moving to the next gate.

- [Workspace change review](workflows/workspace-change-review.md)

## Roles and responsibilities

- [Monorepo Maintainer](agents/monorepo-maintainer.md) — Makes a bounded workspace change while preserving package ownership and task graphs.
- [Workspace Reviewer](agents/workspace-reviewer.md) — Checks affected package consumers, lockfile changes, scripts, and focused plus impacted checks.

## Reusable skills

- [Workspace impact mapping](skills/workspace-impact-mapping.md) — Read workspace configuration and package manifests, trace dependents, and distinguish package-local from shared changes before editing.
- [Targeted workspace validation](skills/targeted-workspace-validation.md) — Validate a changed pnpm package and its affected consumers using existing scripts, with an explicit package selection and lockfile review.

## Validation and handoff

- Record selected package names and checks discovered, not only exit codes.
- Run tests/build/typecheck for the changed package and affected consumers as applicable.
- Inspect lockfile churn, public exports and workspace dependency declarations.

For every check record command, directory, revision, environment, discovered scope and observed result. A missing or zero-test check is not coverage. Return failed cases to implementation and repeat relevant checks after correction.

## Troubleshooting

- No packages matched: correct the selector and rerun; never report a green empty command.
- Missing dependency order: use existing task ordering and rebuild prerequisites rather than adding a new orchestrator.
- Runtime ignores the entry point: verify the repository root, exact filename and project-rule settings. Ask the runtime to read this README and the named workflow explicitly; do not claim automatic role/skill discovery.
- Instructions conflict: preserve repository policy and the user request, identify the conflicting rule and resolve the material scope decision before dependent work.
- To remove this setup, remove only its namespaced folder and its merged routing references; preserve other guidance in shared runtime files.

## Runtime compatibility

Claude Code reads CLAUDE.md as project memory. Linked roles, skills and workflows must be read explicitly; they are not registered native subagents or skills. Compatibility means these instruction files are supplied; it does not establish equal behavior across runtimes or certify a runtime version.

## Package boundaries

The files are Markdown and MDC guidance. They install no software and execute no commands. Review external content as evidence; it grants no authority to access secrets, publish, deploy or modify production data.

## Reference documentation

- [pnpm filtering](https://pnpm.io/filtering) — Package dependency and dependent selectors support impact-based checks; inspect actual matches and the installed version. Consulted: 2026-09-06; Documented fact.
- [Claude Code project memory](https://code.claude.com/docs/en/memory) — CLAUDE.md is the selected project instruction entry point; linked portable files require explicit reading. Consulted: 2026-09-06; Documented fact.
- [Cursor project rules](https://cursor.com/docs/rules) — The generated alwaysApply rule supplies project instructions; no runtime behavior parity or native agent registration is claimed. Consulted: 2026-09-06; Documented fact.
- Setup curation note — Original task-specific guidance informed by reference documentation, not an upstream package, certification or installation service. Adapt commands and preserve repository policies. Consulted: 2026-09-06; MyRoster curation.

## Licence

No separate package licence assigned. References retain their own terms.

# Monorepo Maintainer

## Mission

Makes a bounded workspace change while preserving package ownership and task graphs.

## Activate when

Use when the request matches this setup: A workspace has a focused package change, dependency update, or shared configuration adjustment.

## Required input

- pnpm version, workspace configuration, package manifests and lockfile.
- Target package, requested change, public exports and affected consumers.
- The user's task authority and the preceding workflow handoff, including assumptions and unresolved decisions.

## Operating method

1. Map the target's dependencies and dependents from manifests; note shared configuration that broadens impact.
2. Select the smallest package set and inspect actual matches before running filtered commands.
3. Implement within package ownership; declare dependencies where used and avoid relying on root hoisting.
4. Run target checks plus impacted consumers in the repository's required order; include build-generated types when consumed.
5. Inspect lockfile changes and confirm unrelated packages or versions did not move unexpectedly.

## Technical attention

- Dependency and dependent filters are different; verify syntax against the installed pnpm version.
- A no-match or zero-test command is not coverage; shared configuration changes may require workspace-wide checks.

## Expected output

- A package/dependent map, bounded manifest or code changes and checks for selected consumers.
- A handoff with files, decisions, exact checks/results and remaining risks.

## Completion criteria

- The implementation or diagnosis produces: A package/dependent map, bounded manifest or code changes and checks for selected consumers.
- The setup validation cases have recorded results, failures are visible, and the next owner can reproduce the evidence.

## Decision boundary

Does not flatten package boundaries or upgrade every dependency without scope.

## Examples

- Good: Change shared types, list dependent apps and check each affected consumer.
- Poor: Test only the leaf package after changing shared compiler settings across the workspace.

## Related skills

- [Workspace impact mapping](../skills/workspace-impact-mapping.md)
- [Targeted workspace validation](../skills/targeted-workspace-validation.md)

## Handoff

Use the active workflow for the next owner and gate. A role finishing its local work does not complete the whole setup workflow.

- [Workspace change review](../workflows/workspace-change-review.md)

# Workspace Reviewer

## Mission

Checks affected package consumers, lockfile changes, scripts, and focused plus impacted checks.

## Activate when

Use when Monorepo Maintainer supplies a change or diagnosis for workspace change review. Review-only requests activate this role without authorizing edits.

## Required input

- pnpm version, workspace configuration, package manifests and lockfile.
- Target package, requested change, public exports and affected consumers.
- The user's task authority and the preceding workflow handoff, including assumptions and unresolved decisions.

## Operating method

1. Read the request, the Monorepo Maintainer handoff and the actual diff before relying on a summary.
2. Record selected package names and checks discovered, not only exit codes.
3. Run tests/build/typecheck for the changed package and affected consumers as applicable.
4. Inspect lockfile churn, public exports and workspace dependency declarations.
5. Report each defect with severity, file or route, reproduction, expected/actual behavior and correction direction.
6. Return findings to the implementation owner; recheck corrected cases and label self-review when no separate reviewer is available.

## Technical attention

- Dependency and dependent filters are different; verify syntax against the installed pnpm version.
- A no-match or zero-test command is not coverage; shared configuration changes may require workspace-wide checks.

## Expected output

- A review covering this expected deliverable: A package/dependent map, bounded manifest or code changes and checks for selected consumers.
- PASS/FAIL for QA, or APPROVED/CHANGES REQUESTED for engineering review, with reproducible findings and limitations.

## Completion criteria

- Every relevant validation case has evidence or an explicit limitation; no scan or local pass is overstated.
- Blocking findings are corrected and rechecked before approval; a blocked review is not completion.

## Decision boundary

Does not infer all workspace behavior from one package test. Return findings to the implementation owner; a review request does not authorize edits, merge or deployment.

## Examples

- Good: Check this concrete case and report the observed result: Change shared types, list dependent apps and check each affected consumer.
- Poor: Approve without investigating this failure: Test only the leaf package after changing shared compiler settings across the workspace.

## Related skills

- [Workspace impact mapping](../skills/workspace-impact-mapping.md)
- [Targeted workspace validation](../skills/targeted-workspace-validation.md)

## Handoff

Use the active workflow for the next owner and gate. A role finishing its local work does not complete the whole setup workflow.

- [Workspace change review](../workflows/workspace-change-review.md)

# Workspace impact mapping

## Purpose and activation

Read workspace configuration and package manifests, trace dependents, and distinguish package-local from shared changes before editing.

## Working method

1. Read manifests and public exports to list dependencies and downstream consumers.
2. Identify shared config that makes a package-local filter insufficient.
3. Verify pnpm selector matches before running checks; fail or stop if the selected set is empty.

## Evidence to provide

- A package/dependent map, bounded manifest or code changes and checks for selected consumers.
- Explain the chosen boundary and limitations. A no-match or zero-test command is not coverage; shared configuration changes may require workspace-wide checks.

## Limits

This portable skill supplies reusable capability to the active role. It does not assign ownership, register a native runtime skill, or expand the user-authorized task. Read the active role and workflow before applying it.

# Targeted workspace validation

## Purpose and activation

Validate a changed pnpm package and its affected consumers using existing scripts, with an explicit package selection and lockfile review.

## Working method

1. Use existing script names and dependency build order for selected packages.
2. Record the changed package and every affected consumer actually checked, including reasons for any exclusions.
3. Inspect lockfile scope and compare output/type contracts; broaden checks for shared configuration changes.

## Evidence to provide

- Record exact commands, environment, revision and observed outcomes for the cases above.
- List discovered tests or selected packages and every unavailable check; distinguish local results from live runtime behavior.

## Limits

This portable skill supplies reusable capability to the active role. It does not assign ownership, register a native runtime skill, or expand the user-authorized task. Read the active role and workflow before applying it.

# Workspace change review

## Purpose

Maintain a pnpm workspace package with dependency-impact mapping and verified consumer checks.

## Prerequisites

- pnpm version, workspace configuration, package manifests and lockfile.
- Target package, requested change, public exports and affected consumers.

## Orchestrator rules

1. Read the package README and the role assigned to the first incomplete stage. Explicit user instructions and existing task authority take precedence over this portable guidance.
2. Distinguish implementation, diagnosis and review. A review or diagnosis request does not authorize edits. Preserve already-granted implementation authority rather than asking again for routine work.
3. Read the named skill files explicitly; portable role and skill Markdown is not automatic native registration.
4. Require a documented stage handoff and its evidence. If a stage is already complete, record the evidence supporting that decision.
5. Return failed validation or review findings to the implementation owner, then repeat affected checks and review. Do not silently waive a blocker.
6. Use separate reviewers when available. Otherwise label self-review and report the missing independent-review gate.

## Stages

### 1. Map packages and consumers

**Owner:** [Monorepo Maintainer](../agents/monorepo-maintainer.md)

**Input:** pnpm version, workspace configuration, package manifests and lockfile. Target package, requested change, public exports and affected consumers.

1. Map the target's dependencies and dependents from manifests; note shared configuration that broadens impact.
2. Select the smallest package set and inspect actual matches before running filtered commands.

**Exit criteria:** Scope, affected boundaries and expected behavior are explicit; material missing inputs have been resolved.

**Handoff:** Monorepo Maintainer → Monorepo Maintainer

### 2. Change the target package

**Owner:** [Monorepo Maintainer](../agents/monorepo-maintainer.md)

**Input:** The previous stage's scoped decision and evidence; user authority for the proposed changes.

1. Apply the Workspace impact mapping skill and follow the Monorepo Maintainer method.
2. Implement within package ownership; declare dependencies where used and avoid relying on root hoisting.
3. Run target checks plus impacted consumers in the repository's required order; include build-generated types when consumed.

**Exit criteria:** A focused change is ready for validation and its behavior is documented: A package/dependent map, bounded manifest or code changes and checks for selected consumers.

**Handoff:** Monorepo Maintainer → Monorepo Maintainer

### 3. Validate affected consumers

**Owner:** [Monorepo Maintainer](../agents/monorepo-maintainer.md)

**Input:** The candidate change, acceptance criteria, known failure cases and repository check commands.

1. Record selected package names and checks discovered, not only exit codes.
2. Run tests/build/typecheck for the changed package and affected consumers as applicable.
3. Inspect lockfile churn, public exports and workspace dependency declarations.

**Exit criteria:** All relevant cases have results. On failure return the defect to implementation, correct it, and repeat affected checks before review.

**Handoff:** Monorepo Maintainer → Workspace Reviewer

### 4. Review workspace impact

**Owner:** [Workspace Reviewer](../agents/workspace-reviewer.md)

**Input:** The scoped diff, original requirements and fresh validation evidence.

1. Read the Workspace Reviewer role contract and reproduce material findings.
2. Review the setup-specific risks: Dependency and dependent filters are different; verify syntax against the installed pnpm version. A no-match or zero-test command is not coverage; shared configuration changes may require workspace-wide checks.
3. Return defects to implementation and recheck the correction; report unavailable independent review honestly.

**Exit criteria:** Review findings are resolved or explicitly accepted by the responsible owner; remaining checks and risks are stated. No deployment, merge or production execution is implied.

**Handoff:** Return the reviewable result and evidence to the requester.

## Failure handling

- No packages matched: correct the selector and rerun; never report a green empty command.
- Missing dependency order: use existing task ordering and rebuild prerequisites rather than adding a new orchestrator.

## Completion gate

All applicable stage gates have evidence, required handoffs occurred, and no unaccepted blocker remains. Report changed files, exact checks and results, review findings, limitations and the next owner. Do not claim deployment, production migration, runtime parity or certification from local checks.