amber-chang/pm-copilot-skills

1. Repository purpose

- This is not an application codebase; it is a toolkit of Markdown-based operating standards, prompts, templates, and checklists for using AI coding assistants.

- The primary goal is to standardize how a PM uses Claude Code and optionally Gemini Copilot to explore, develop, review, and hand off work.

2. Core architecture

- The repo is organized around three usage layers:

- Global assistant configuration for machine-level setup

- Project-level templates for adapting the workflow to a specific repo

- Process documentation and checklists for safe execution and quality control

- Most artifacts are consumed by copying them into the user’s home directory or into another project repo.

3. Global configuration layer

- global/CLAUDE.md and global/GEMINI.md define the baseline behavior rules for each assistant.

- global/commands/ contains shared custom commands like /explore, /dev, /handoff, and /review.

- global/agents/ provides specialized agent definitions, including a code reviewer.

- global/skills/ contains Claude Code-specific skills; currently the notable one is the Next.js development skill.

4. Assistant-specific split

- The repo supports two assistant ecosystems with a shared command/agent structure:

- Claude Code: primary, with skills support and dedicated templates

- Gemini Copilot: supported through its own global guidance file and project template

- This means the repository is effectively a cross-assistant policy and workflow layer, not a runtime service.

5. Command-driven workflow

- The custom commands are the main interaction boundary:

- /explore is for read-only architecture discovery

- /dev is for implementation mode

- /review is for self-review

- /handoff is for completion/transfer validation

- These commands encode process state transitions rather than application behavior.

6. Project template layer

- templates/ contains repo-specific starter files that are copied into an actual project as CLAUDE.md or GEMINI.md.

- There are general templates plus tech-stack-specific ones, such as:

- laravel-CLAUDE.md

- nextjs-typescript-CLAUDE.md

- This layer is the bridge between the generic assistant workflow and a real codebase.

7. Skill-based specialization

- global/skills/nextjs-development/ is a specialized workflow package for Claude Code.

- It represents a deeper architecture boundary than a command: it adapts assistant behavior to a particular stack, especially Next.js + TypeScript + React, with guidance around server/client component boundaries and API routes.

- This is the only clearly stack-specific runtime concept in the repo.

8. Quality and governance layer

- checklists/ contains pre-flight and handoff checklists:

- before coding

- before commit

- before handoff

- These are process controls for consistency, safety, and reviewability, especially important because the toolkit is designed for AI-assisted work.

9. Documentation and operating model

- docs/ explains the intended workflow, FAQ, and assistant guidelines.

- docs/workflow.md is the main process map for how the PM should move through exploration, development, review, and handoff.

- docs/ai-assistant-guidelines.md is aimed at the AI assistant itself, showing that this repo treats assistant behavior as a first-class concern.

10. Usage/data flow

- The typical flow is:

- clone this repo

- copy global config into ~/.claude or ~/.gemini-copilot

- copy a template into the target project’s root

- customize that project template with repo context

- So the main “data” moving through the system is instructional metadata: policies, prompts, checklists, and project context.

11. Operational boundary

- The toolkit’s architecture is intentionally file-based and portable: no backend, no database, no build pipeline.

- Its boundary is the local developer machine and the target project repository.

- External services only matter insofar as they are the assistant platforms themselves: Claude Code and Gemini Copilot.

12. Diagram framing

- If drawing this repo, model it as a workflow and configuration distribution system rather than an app.

- Show the repo as the source of:

- assistant policies

- reusable commands

- agent definitions

- stack-specific skills

- project templates

- checklists and documentation

- Then show those assets being copied into the local assistant environment and into downstream projects.