pan-stack-cli

Global CLI for PAN Stack workspaces. Install once, use in any project that has .project.yaml.

npm i -g pan-stack-cli
# or from source before npm publish:
npm i -g /path/to/pan-stack-cli

What is PAN Stack?

PAN Stack is a workspace shell for coding with AI agents — not a monorepo that contains every product repository. The stack repo holds:

• Agent skills and prompts (.claude, .cursor, .codex)
• Workspace manifests (.project.yaml, .pan.yaml)
• Team docs and coordination files

Product source code lives in separate repositories listed in .project.yaml. The pan CLI ties them together: clone all repos, run git ops across the workspace, and execute project commands defined in .pan.yaml.

bookshop-stack/                 # PAN Stack workspace (shell)
  .project.yaml                 # Which repos belong to this workspace
  .pan.yaml                     # Workspace-level pan commands
  .claude/skills/               # Claude Code skills
  .cursor/skills/               # Cursor agent skills
  .codex/skills/                # Codex agent skills
  apps/
    web/                        # bookshop-web (cloned product repo)
    api/                        # bookshop-api (cloned product repo)

Run pan create to scaffold this layout with the shared writing-guidelines skill pre-installed for all three agent folders.

Requirements

• Node.js 18+
• Git (for pan clone, pull, sync-main, fetch, push, grv, gst)

Windows support

Built-in commands (create, clone, pull, sync-main, push, fetch, grv, gst) run on Windows, macOS, and Linux. Notes for Windows:

• shell: blocks in .pan.yaml run through bash on all platforms (Git Bash on Windows, system bash on macOS/Linux). Use exec: for simple one-liners (npm test) when possible; those work without Bash.
• Install Git for Windows if bash is not already on PATH.
• Set PAN_PROJECT_ROOTS with semicolon separators (C:\work\a;C:\work\b). Do not use : — it conflicts with drive letters.
• Optional: set PAN_GIT_BASH to the full path of bash.exe if Git is installed in a non-standard location.

Bootstrap a new workspace

mkdir ~/work && cd ~/work
pan create                    # prompts for folder name
# or
pan create bookshop-stack     # non-interactive

cd bookshop-stack
# Edit .project.yaml — replace repo_url_to_be_filled with real URLs
pan clone
pan install

pan create fails if the target folder already exists.

Configuration files

Two files drive the CLI. Keep responsibilities separate:

| File | Role | |------|------| | .project.yaml | Workspace manifest — lists repositories (name, url, path). No commands. | | .pan.yaml | pan commands — at workspace root and/or inside each child repo |

.project.yaml example

project: bookshop-stack
managed_by: your-team

stack:
  repo: https://github.com/example/bookshop-stack.git

repositories:
  - name: bookshop-web
    description: Customer-facing web application
    url: https://github.com/example/bookshop-web.git
    path: apps/web
  - name: bookshop-api
    description: REST API service
    url: https://github.com/example/bookshop-api.git
    path: apps/api

.pan.yaml — workspace root

Orchestration commands. Paths are relative to the workspace root. Use PAN_WORKSPACE_ROOT in shell blocks:

commands:
  install:
    alias: i
    description: Install dependencies across cloned repositories
    shell: |
      set -euo pipefail
      root="${PAN_WORKSPACE_ROOT}"
      for dir in apps/web apps/api; do
        [[ -d "$root/$dir" ]] || { echo "Missing: $root/$dir" >&2; exit 1; }
        (cd "$root/$dir" && npm install)
      done

  test:
    default: web
    description: Run tests (web | api)
    targets:
      web:
        cwd: apps/web
        exec: npm test
      api:
        cwd: apps/api
        exec: npm test

.pan.yaml — child repo

Place a .pan.yaml inside a cloned repo. cwd / exec are relative to that repo's root:

commands:
  dev:
    description: Start local dev server
    exec: npm run dev

  lint:
    shell: |
      set -euo pipefail
      npm run lint

Aliases: alias: i or aliases: i, ins (comma-separated).

Built-in git commands

Read repositories from the nearest .project.yaml (walk-up from cwd):

| Command | Action | |---------|--------| | pan clone | Clone all repositories in the manifest | | pan pull | Pull all cloned repositories | | pan sync-main [repo\|all] (pan sm) | Fetch + merge origin/main into current branch (interactive picker; conflict summary) | | pan fetch | Fetch all remotes | | pan push | Push all repos (-u origin HEAD by default) | | pan grv | git remote -v for workspace + each child repo | | pan gst | git status for workspace + each child repo |

Git options:

• --base-dir DIR — base for relative repo paths (default: directory containing .project.yaml)
• --dry-run — print commands only
• [manifest] — manifest path (default: .project.yaml)

Works from child repo directories — the CLI walks up to find .project.yaml.

Project commands

The CLI loads all .pan.yaml files in the workspace (root + each repositories[].path). When the same command name appears in multiple repos, use --project <name> or pick interactively.

Environment variables

| Variable | Meaning | |----------|---------| | PAN_WORKSPACE_ROOT | Directory containing .project.yaml | | PAN_REPO_ROOT | Directory containing the active .pan.yaml | | PAN_PROJECT_ROOT | Alias of PAN_WORKSPACE_ROOT | | PAN_ARG_1, … | Arguments after the command name |

Registry (optional)

• PAN_PROJECT_ROOTS — extra workspace roots (; on Windows, : or ; on Unix)
• ~/.pan/projects — one workspace root per line

Package layout

pan-stack-cli/
  bin/pan.js              # CLI entry
  lib/
    create.js             # pan create scaffold
    discover.js             # workspace discovery
    platform.js             # Windows/cross-platform helpers
    manifest.js             # YAML parsing
    run-command.js        # command execution
    git/                  # clone, pull, sync-main, push, fetch, grv, gst
  templates/workspace/    # pan create template
  references/             # npm publish docs

Local development

Install globally from source: references/npm-development.md.

Publish to npm

See references/npm-release.md.