# amber-chang/pm-copilot-skills architecture

> Architecture diagram of the GitHub repository amber-chang/pm-copilot-skills, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/amber-chang/pm-copilot-skills
- Repository: https://github.com/amber-chang/pm-copilot-skills

## Overview

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.

Main entry points: [`global/commands`](https://github.com/amber-chang/pm-copilot-skills/tree/main/global/commands) (Commands), [`templates`](https://github.com/amber-chang/pm-copilot-skills/tree/main/templates) (Templates), [`global/CLAUDE.md`](https://github.com/amber-chang/pm-copilot-skills/blob/main/global/CLAUDE.md) (Claude rules), [`SETUP.md`](https://github.com/amber-chang/pm-copilot-skills/blob/main/SETUP.md) (Setup)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_repo["Repository"]
  node_readme["README<br/>entry guide<br/>[README.md]"]
  node_setup["Setup<br/>[SETUP.md]"]
end

subgraph group_assistant["Assistant Layer"]
  node_global_claude["Claude rules<br/>assistant policy<br/>[CLAUDE.md]"]
  node_global_gemini["Gemini rules<br/>assistant policy<br/>[GEMINI.md]"]
  node_commands["Commands"]
  node_agents["Agents<br/>agent defs"]
  node_skills["Skills"]
  node_explore_cmd["Explore<br/>command<br/>[explore.md]"]
  node_dev_cmd["Dev<br/>command<br/>[dev.md]"]
  node_review_cmd["Review<br/>command<br/>[review.md]"]
  node_handoff_cmd["Handoff<br/>command<br/>[handoff.md]"]
  node_code_reviewer["Code reviewer<br/>review agent<br/>[code-reviewer.md]"]
  node_nextjs_skill["Next.js skill<br/>stack skill<br/>[SKILL.md]"]
end

subgraph group_project["Project Layer"]
  node_templates["Templates"]
  node_general_claude_tpl["Claude template<br/>project template<br/>[general-CLAUDE.md]"]
  node_general_gemini_tpl["Gemini template<br/>project template<br/>[general-GEMINI.md]"]
  node_laravel_tpl["Laravel template<br/>stack template<br/>[laravel-CLAUDE.md]"]
  node_nextjs_tpl["Next.js template<br/>stack template"]
end

subgraph group_governance["Governance"]
  node_checklists["Checklists<br/>quality gates"]
  node_before_coding["Before coding<br/>checklist<br/>[before-coding.md]"]
  node_before_commit["Before commit<br/>checklist<br/>[before-commit.md]"]
  node_before_handoff["Before handoff<br/>checklist<br/>[before-handoff.md]"]
  node_workflow_doc["Workflow<br/>process map<br/>[workflow.md]"]
  node_guidelines["Guidelines<br/>assistant guidance"]
end

node_readme -->|"start with"| node_setup
node_setup -->|"installs"| node_global_claude
node_setup -->|"installs"| node_global_gemini
node_setup -->|"copies"| node_templates
node_global_claude -->|"uses"| node_commands
node_global_claude -->|"uses"| node_agents
node_global_claude -->|"extends"| node_skills
node_global_gemini -->|"uses"| node_commands
node_commands -->|"includes"| node_explore_cmd
node_commands -->|"includes"| node_dev_cmd
node_commands -->|"includes"| node_review_cmd
node_commands -->|"includes"| node_handoff_cmd
node_commands -->|"maps to"| node_workflow_doc
node_agents -->|"includes"| node_code_reviewer
node_skills -->|"includes"| node_nextjs_skill
node_templates -->|"includes"| node_general_claude_tpl
node_templates -->|"includes"| node_general_gemini_tpl
node_templates -->|"includes"| node_laravel_tpl
node_templates -->|"includes"| node_nextjs_tpl
node_nextjs_tpl -->|"aligns with"| node_nextjs_skill
node_checklists -->|"includes"| node_before_coding
node_checklists -->|"includes"| node_before_commit
node_checklists -->|"includes"| node_before_handoff
node_workflow_doc -->|"supports"| node_guidelines
node_global_claude -->|"consults"| node_checklists
node_dev_cmd -->|"checks"| node_before_coding
node_handoff_cmd -->|"checks"| node_before_handoff
node_review_cmd -->|"delegates to"| node_code_reviewer
node_templates -->|"reflects"| node_workflow_doc

click node_readme "https://github.com/amber-chang/pm-copilot-skills/blob/main/README.md"
click node_setup "https://github.com/amber-chang/pm-copilot-skills/blob/main/SETUP.md"
click node_global_claude "https://github.com/amber-chang/pm-copilot-skills/blob/main/global/CLAUDE.md"
click node_global_gemini "https://github.com/amber-chang/pm-copilot-skills/blob/main/global/GEMINI.md"
click node_commands "https://github.com/amber-chang/pm-copilot-skills/tree/main/global/commands"
click node_agents "https://github.com/amber-chang/pm-copilot-skills/tree/main/global/agents"
click node_skills "https://github.com/amber-chang/pm-copilot-skills/tree/main/global/skills"
click node_explore_cmd "https://github.com/amber-chang/pm-copilot-skills/blob/main/global/commands/explore.md"
click node_dev_cmd "https://github.com/amber-chang/pm-copilot-skills/blob/main/global/commands/dev.md"
click node_review_cmd "https://github.com/amber-chang/pm-copilot-skills/blob/main/global/commands/review.md"
click node_handoff_cmd "https://github.com/amber-chang/pm-copilot-skills/blob/main/global/commands/handoff.md"
click node_code_reviewer "https://github.com/amber-chang/pm-copilot-skills/blob/main/global/agents/code-reviewer.md"
click node_nextjs_skill "https://github.com/amber-chang/pm-copilot-skills/blob/main/global/skills/nextjs-development/SKILL.md"
click node_templates "https://github.com/amber-chang/pm-copilot-skills/tree/main/templates"
click node_general_claude_tpl "https://github.com/amber-chang/pm-copilot-skills/blob/main/templates/general-CLAUDE.md"
click node_general_gemini_tpl "https://github.com/amber-chang/pm-copilot-skills/blob/main/templates/general-GEMINI.md"
click node_laravel_tpl "https://github.com/amber-chang/pm-copilot-skills/blob/main/templates/laravel-CLAUDE.md"
click node_nextjs_tpl "https://github.com/amber-chang/pm-copilot-skills/blob/main/templates/nextjs-typescript-CLAUDE.md"
click node_checklists "https://github.com/amber-chang/pm-copilot-skills/tree/main/checklists"
click node_before_coding "https://github.com/amber-chang/pm-copilot-skills/blob/main/checklists/before-coding.md"
click node_before_commit "https://github.com/amber-chang/pm-copilot-skills/blob/main/checklists/before-commit.md"
click node_before_handoff "https://github.com/amber-chang/pm-copilot-skills/blob/main/checklists/before-handoff.md"
click node_workflow_doc "https://github.com/amber-chang/pm-copilot-skills/blob/main/docs/workflow.md"
click node_guidelines "https://github.com/amber-chang/pm-copilot-skills/blob/main/docs/ai-assistant-guidelines.md"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_readme,node_setup toneBlue
class node_global_claude,node_global_gemini,node_commands,node_agents,node_skills,node_explore_cmd,node_dev_cmd,node_review_cmd,node_handoff_cmd,node_code_reviewer,node_nextjs_skill toneAmber
class node_templates,node_general_claude_tpl,node_general_gemini_tpl,node_laravel_tpl,node_nextjs_tpl toneMint
class node_checklists,node_before_coding,node_before_commit,node_before_handoff,node_workflow_doc,node_guidelines toneRose
```

## Components

### Repository

Source toolkit of policies, prompts, templates, and process docs.

- [README](https://github.com/amber-chang/pm-copilot-skills/blob/main/README.md): entry guide · Top-level orientation for using the toolkit. · `README.md`
- [Setup](https://github.com/amber-chang/pm-copilot-skills/blob/main/SETUP.md): setup guide · Instructions for installing global files and project templates. · `SETUP.md`

### Assistant Layer

Global assistant configuration and command surface for Claude Code and Gemini Copilot.

- [Claude rules](https://github.com/amber-chang/pm-copilot-skills/blob/main/global/CLAUDE.md): assistant policy · Baseline behavior rules for Claude Code. · `global/CLAUDE.md`
- [Gemini rules](https://github.com/amber-chang/pm-copilot-skills/blob/main/global/GEMINI.md): assistant policy · Baseline behavior rules for Gemini Copilot. · `global/GEMINI.md`
- [Commands](https://github.com/amber-chang/pm-copilot-skills/tree/main/global/commands): workflow commands · Shared custom commands for explore, dev, review, and handoff. · `global/commands`
- [Agents](https://github.com/amber-chang/pm-copilot-skills/tree/main/global/agents): agent defs · Specialized agent roles, including code review. · `global/agents`
- [Skills](https://github.com/amber-chang/pm-copilot-skills/tree/main/global/skills): claude skills · Claude Code skill packages for stack-specific behavior. · `global/skills`
- [Explore](https://github.com/amber-chang/pm-copilot-skills/blob/main/global/commands/explore.md): command · Read-only architecture discovery workflow. · `global/commands/explore.md`
- [Dev](https://github.com/amber-chang/pm-copilot-skills/blob/main/global/commands/dev.md): command · Implementation workflow and active coding mode. · `global/commands/dev.md`
- [Review](https://github.com/amber-chang/pm-copilot-skills/blob/main/global/commands/review.md): command · Self-review workflow for quality checks. · `global/commands/review.md`
- [Handoff](https://github.com/amber-chang/pm-copilot-skills/blob/main/global/commands/handoff.md): command · Completion and transfer validation workflow. · `global/commands/handoff.md`
- [Code reviewer](https://github.com/amber-chang/pm-copilot-skills/blob/main/global/agents/code-reviewer.md): review agent · Specialized reviewer agent for code quality and correctness. · `global/agents/code-reviewer.md`
- [Next.js skill](https://github.com/amber-chang/pm-copilot-skills/blob/main/global/skills/nextjs-development/SKILL.md): stack skill · Next.js + TypeScript + React guidance with component and API boundary rules. · `global/skills/nextjs-development/SKILL.md`

### Project Layer

Templates and stack-specific guidance copied into a target codebase.

- [Templates](https://github.com/amber-chang/pm-copilot-skills/tree/main/templates): project templates · Copy-into-project starter files for assistant guidance. · `templates`
- [Claude template](https://github.com/amber-chang/pm-copilot-skills/blob/main/templates/general-CLAUDE.md): project template · General CLAUDE.md starter for downstream projects. · `templates/general-CLAUDE.md`
- [Gemini template](https://github.com/amber-chang/pm-copilot-skills/blob/main/templates/general-GEMINI.md): project template · General GEMINI.md starter for downstream projects. · `templates/general-GEMINI.md`
- [Laravel template](https://github.com/amber-chang/pm-copilot-skills/blob/main/templates/laravel-CLAUDE.md): stack template · Claude template tailored for Laravel projects. · `templates/laravel-CLAUDE.md`
- [Next.js template](https://github.com/amber-chang/pm-copilot-skills/blob/main/templates/nextjs-typescript-CLAUDE.md): stack template · Claude template tailored for Next.js and TypeScript projects. · `templates/nextjs-typescript-CLAUDE.md`

### Governance

Checklists and docs that control safe usage and workflow.

- [Checklists](https://github.com/amber-chang/pm-copilot-skills/tree/main/checklists): quality gates · Pre-flight and handoff checklists for safe execution. · `checklists`
- [Before coding](https://github.com/amber-chang/pm-copilot-skills/blob/main/checklists/before-coding.md): checklist · Pre-flight checks before starting implementation. · `checklists/before-coding.md`
- [Before commit](https://github.com/amber-chang/pm-copilot-skills/blob/main/checklists/before-commit.md): checklist · Checks to complete before committing changes. · `checklists/before-commit.md`
- [Before handoff](https://github.com/amber-chang/pm-copilot-skills/blob/main/checklists/before-handoff.md): checklist · Validation steps before transferring work. · `checklists/before-handoff.md`
- [Workflow](https://github.com/amber-chang/pm-copilot-skills/blob/main/docs/workflow.md): process map · Main process map for explore, develop, review, and handoff. · `docs/workflow.md`
- [Guidelines](https://github.com/amber-chang/pm-copilot-skills/blob/main/docs/ai-assistant-guidelines.md): assistant guidance · Guidance aimed at the AI assistant as a first-class actor. · `docs/ai-assistant-guidelines.md`

## Connections

- README → Setup: start with · Repository entry points users into setup instructions.
- Setup → Claude rules: installs · Copies Claude baseline guidance into the local assistant environment.
- Setup → Gemini rules: installs · Copies Gemini baseline guidance into the local assistant environment.
- Setup → Templates: copies · Moves project templates into downstream repositories.
- Claude rules → Commands: uses · Claude baseline behavior is driven by shared commands.
- Claude rules → Agents: uses · Claude baseline behavior can invoke specialized agents.
- Claude rules → Skills: extends · Claude baseline can be specialized through skills.
- Gemini rules → Commands: uses · Gemini guidance shares the command-driven workflow.
- Commands → Explore: includes · Read-only discovery command.
- Commands → Dev: includes · Implementation command.
- Commands → Review: includes · Self-review command.
- Commands → Handoff: includes · Transfer and completion command.
- Commands → Workflow: maps to · Commands encode the main workflow stages.
- Agents → Code reviewer: includes · Reviewer agent definition.
- Skills → Next.js skill: includes · Stack-specific Claude skill package.
- Templates → Claude template: includes · Generic Claude project starter.
- Templates → Gemini template: includes · Generic Gemini project starter.
- Templates → Laravel template: includes · Laravel-specific Claude starter.
- Templates → Next.js template: includes · Next.js/TypeScript Claude starter.
- Next.js template → Next.js skill: aligns with · Template and skill both encode Next.js workflow boundaries.
- Checklists → Before coding: includes · Pre-flight checklist.
- Checklists → Before commit: includes · Pre-commit checklist.
- Checklists → Before handoff: includes · Handoff checklist.
- Workflow → Guidelines: supports · Process map is reinforced by assistant-facing guidance.
- Claude rules → Checklists: consults · Quality gates complement the global workflow.
- Dev → Before coding: checks · Implementation should begin with the pre-coding checklist.
- Handoff → Before handoff: checks · Handoff is validated against the handoff checklist.
- Review → Code reviewer: delegates to · Self-review can use the dedicated reviewer agent.
- Templates → Workflow: reflects · Project templates operationalize the documented workflow.