Next.js Small Feature

# Next.js Small Feature

This is the Claude Code entry point for a complete AI development setup. Read `my-roster/nextjs-small-feature/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/nextjs-small-feature/README.md`
- Role: Next.js Developer — `my-roster/nextjs-small-feature/agents/next-js-developer.md`
- Role: Code Reviewer — `my-roster/nextjs-small-feature/agents/code-reviewer.md`
- Skill: Server and client boundaries — `my-roster/nextjs-small-feature/skills/server-and-client-boundaries.md`
- Skill: Feature review — `my-roster/nextjs-small-feature/skills/feature-review.md`
- Workflow: App Router change review — `my-roster/nextjs-small-feature/workflows/app-router-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.

# Next.js Small Feature for Claude Code

AI development setup · v0.3

Deliver a Next.js App Router feature with explicit data ownership, client boundaries and route-state checks.

## Audience and scope

You already use the Next.js App Router and need a small page or component change.

Next.js Developer owns the scoped work; Code 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 migrate routers, introduce a state library, or change caching policy beyond the requested feature.

## Before adding it to a repository

1. Inspect the complete archive in a temporary extraction directory. Compare every destination, including the existing my-roster/nextjs-small-feature 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/nextjs-small-feature 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/nextjs-small-feature. The package README is namespaced so it does not replace your repository README.

## Package tree

~~~text
CLAUDE.md  # selected runtime entry point
my-roster/nextjs-small-feature/
  README.md
  agents/next-js-developer.md
  agents/code-reviewer.md
  skills/server-and-client-boundaries.md
  skills/feature-review.md
  workflows/app-router-change-review.md
~~~

## Task input

- Installed Next.js version, app route and adjacent Server/Client Components.
- One user outcome, data contract, authorization assumptions and existing validation scripts.

## Start a workflow

Read the App Router change review workflow. Task: [replace with your concrete request]. Example of appropriate scope: Keep a product query on the server and isolate a quantity selector as a small client component. Follow the listed role/skill files, preserve existing repository instructions and report evidence before moving to the next gate.

- [App Router change review](workflows/app-router-change-review.md)

## Roles and responsibilities

- [Next.js Developer](agents/next-js-developer.md) — Implements a scoped App Router change using the installed Next.js version and repository conventions.
- [Code Reviewer](agents/code-reviewer.md) — Reviews the scoped diff and check results; reports blockers with file locations.

## Reusable skills

- [Server and client boundaries](skills/server-and-client-boundaries.md) — Keep server-side data access in Server Components. Add a small Client Component for state, event handlers, or browser APIs; pass serializable props across the boundary and keep secrets on the server. Check documentation for the installed Next.js version.
- [Feature review](skills/feature-review.md) — Read package.json for existing lint, typecheck, test, and build commands. Check the changed route, loading/error states, and keyboard interaction. Record results and limitations; avoid adding a test framework or changing caching defaults solely for this setup.

## Validation and handoff

- Run existing typecheck, lint, tests and production build for the feature.
- Test loading, missing resource, denied access and failed mutation where relevant.
- Check keyboard use, refresh/client navigation parity and that private data is absent from client payloads.

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

- Framework behavior unclear: inspect installed-version documentation before selecting caching APIs.
- Missing backend contract: state the dependency and use approved fixtures without inventing live behavior.
- 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

- [Next.js Server and Client Components](https://nextjs.org/docs/app/getting-started/server-and-client-components) — Rendering environment, client boundaries and serializable props inform the feature method. 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.

# Next.js Developer

## Mission

Implements a scoped App Router change using the installed Next.js version and repository conventions.

## Activate when

Use when the request matches this setup: You already use the Next.js App Router and need a small page or component change.

## Required input

- Installed Next.js version, app route and adjacent Server/Client Components.
- One user outcome, data contract, authorization assumptions and existing validation scripts.
- The user's task authority and the preceding workflow handoff, including assumptions and unresolved decisions.

## Operating method

1. Trace the route's data access and identify which rendering environment owns each operation.
2. Keep data and secrets server-side; put event handlers and browser state in the smallest Client Component.
3. Define serializable boundary props and success, loading, error and not-found behavior.
4. Review existing caching and mutation revalidation for this route against the installed version; change only what the task requires.
5. Check direct navigation, refresh and client transitions, including recovery after a rejected action.

## Technical attention

- Server execution does not replace authorization checks at data access or mutation.
- Avoid turning a layout into a Client Component for one button; do not migrate routers or prescribe new caching defaults.

## Expected output

- An App Router diff with a server/client data map and route-state test evidence.
- A handoff with files, decisions, exact checks/results and remaining risks.

## Completion criteria

- The implementation or diagnosis produces: An App Router diff with a server/client data map and route-state test evidence.
- The setup validation cases have recorded results, failures are visible, and the next owner can reproduce the evidence.

## Decision boundary

Does not migrate routers, introduce a state library, or change caching policy beyond the requested feature.

## Examples

- Good: Keep a product query on the server and isolate a quantity selector as a small client component.
- Poor: Pass credentials through props or add use client to a whole layout to fix one event handler.

## Related skills

- [Server and client boundaries](../skills/server-and-client-boundaries.md)
- [Feature review](../skills/feature-review.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.

- [App Router change review](../workflows/app-router-change-review.md)

# Code Reviewer

## Mission

Reviews the scoped diff and check results; reports blockers with file locations.

## Activate when

Use when Next.js Developer supplies a change or diagnosis for app router change review. Review-only requests activate this role without authorizing edits.

## Required input

- Installed Next.js version, app route and adjacent Server/Client Components.
- One user outcome, data contract, authorization assumptions and existing validation scripts.
- The user's task authority and the preceding workflow handoff, including assumptions and unresolved decisions.

## Operating method

1. Read the request, the Next.js Developer handoff and the actual diff before relying on a summary.
2. Run existing typecheck, lint, tests and production build for the feature.
3. Test loading, missing resource, denied access and failed mutation where relevant.
4. Check keyboard use, refresh/client navigation parity and that private data is absent from client payloads.
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

- Server execution does not replace authorization checks at data access or mutation.
- Avoid turning a layout into a Client Component for one button; do not migrate routers or prescribe new caching defaults.

## Expected output

- A review covering this expected deliverable: An App Router diff with a server/client data map and route-state test evidence.
- 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 claim independent review when reviewing its own work or merge without owner approval. 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: Keep a product query on the server and isolate a quantity selector as a small client component.
- Poor: Approve without investigating this failure: Pass credentials through props or add use client to a whole layout to fix one event handler.

## Related skills

- [Server and client boundaries](../skills/server-and-client-boundaries.md)
- [Feature review](../skills/feature-review.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.

- [App Router change review](../workflows/app-router-change-review.md)

# Server and client boundaries

## Purpose and activation

Keep server-side data access in Server Components. Add a small Client Component for state, event handlers, or browser APIs; pass serializable props across the boundary and keep secrets on the server. Check documentation for the installed Next.js version.

## Working method

1. Map every new import and prop across the Server/Client Component boundary.
2. Keep secret/data access on the server and isolate browser state/events in a small client entry.
3. Verify serialized values and installed-version caching behavior before changing data freshness.

## Evidence to provide

- An App Router diff with a server/client data map and route-state test evidence.
- Explain the chosen boundary and limitations. Avoid turning a layout into a Client Component for one button; do not migrate routers or prescribe new caching defaults.

## 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.

# Feature review

## Purpose and activation

Read package.json for existing lint, typecheck, test, and build commands. Check the changed route, loading/error states, and keyboard interaction. Record results and limitations; avoid adding a test framework or changing caching defaults solely for this setup.

## Working method

1. List direct-load, client-transition, loading, error and missing-resource cases.
2. Run repository checks and inspect affected keyboard interactions.
3. Review access control on reads/mutations and confirm client payloads omit private fields.

## 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.

# App Router change review

## Purpose

Deliver a Next.js App Router feature with explicit data ownership, client boundaries and route-state checks.

## Prerequisites

- Installed Next.js version, app route and adjacent Server/Client Components.
- One user outcome, data contract, authorization assumptions and existing validation scripts.

## 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 route data ownership

**Owner:** [Next.js Developer](../agents/next-js-developer.md)

**Input:** Installed Next.js version, app route and adjacent Server/Client Components. One user outcome, data contract, authorization assumptions and existing validation scripts.

1. Trace the route's data access and identify which rendering environment owns each operation.
2. Keep data and secrets server-side; put event handlers and browser state in the smallest Client Component.

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

**Handoff:** Next.js Developer → Next.js Developer

### 2. Implement the App Router feature

**Owner:** [Next.js Developer](../agents/next-js-developer.md)

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

1. Apply the Server and client boundaries skill and follow the Next.js Developer method.
2. Define serializable boundary props and success, loading, error and not-found behavior.
3. Review existing caching and mutation revalidation for this route against the installed version; change only what the task requires.

**Exit criteria:** A focused change is ready for validation and its behavior is documented: An App Router diff with a server/client data map and route-state test evidence.

**Handoff:** Next.js Developer → Next.js Developer

### 3. Validate route states

**Owner:** [Next.js Developer](../agents/next-js-developer.md)

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

1. Run existing typecheck, lint, tests and production build for the feature.
2. Test loading, missing resource, denied access and failed mutation where relevant.
3. Check keyboard use, refresh/client navigation parity and that private data is absent from client payloads.

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

**Handoff:** Next.js Developer → Code Reviewer

### 4. Review boundaries and user behavior

**Owner:** [Code Reviewer](../agents/code-reviewer.md)

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

1. Read the Code Reviewer role contract and reproduce material findings.
2. Review the setup-specific risks: Server execution does not replace authorization checks at data access or mutation. Avoid turning a layout into a Client Component for one button; do not migrate routers or prescribe new caching defaults.
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

- Framework behavior unclear: inspect installed-version documentation before selecting caching APIs.
- Missing backend contract: state the dependency and use approved fixtures without inventing live behavior.

## 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.