myproject/
├── infra/                    # Infrastructure repo (git)
│   ├── .devcontainer-template/   # Templates for workspace creation
│   │   ├── dev.template          # Dev script template
│   │   ├── compose.infra.yml.template
│   │   └── docker-compose.devcontainer.yml.template
│   ├── new-feature              # Script to create workspaces
│   ├── remove-feature           # Script to clean up workspaces
│   ├── certs/                   # SSL certificates
│   └── traefik/                 # Traefik config
├── frontend/                 # Frontend repo (git)
├── backend/                  # Backend repo (git)
└── workspaces/               # Feature workspaces (git worktrees)
    └── feature-xxx/
        ├── fe/               # Worktree of frontend
        ├── api/              # Worktree of backend
        └── .devcontainer/    # Generated from templates

projects:
  myapp:
    name: "My App"
    path: /home/user/projects/myapp
    issue_prefix: APP

    workspace:
      type: polyrepo
      workspaces_dir: workspaces
      # Default branch for all repos (optional, defaults to 'main')
      default_branch: main

      # Git repositories to include in each workspace
      # Each repo is a SEPARATE git repository with its own .git
      repos:
        - name: fe
          path: frontend           # Relative to project root
          branch_prefix: "feature/"
          # default_branch: main   # Can override workspace default per-repo
        - name: api
          path: backend
          branch_prefix: "feature/"
          # default_branch: develop  # Example: API uses 'develop' as default

      # DNS entries for local development
      dns:
        domain: myapp.test
        entries:
          - "{{FEATURE_FOLDER}}.{{DOMAIN}}"
          - "api-{{FEATURE_FOLDER}}.{{DOMAIN}}"
        sync_method: wsl2hosts  # or: hosts_file, dnsmasq

      # Port assignments for services
      ports:
        redis:
          range: [6380, 6499]

      # Service definitions - how to start each service
      services:
        - name: api
          path: api
          start_command: ./mvnw spring-boot:run
          docker_command: ./mvnw spring-boot:run
          health_url: "https://api-{{FEATURE_FOLDER}}.{{DOMAIN}}/actuator/health"
          port: 8080
        - name: frontend
          path: fe
          start_command: pnpm start
          docker_command: pnpm start
          health_url: "https://{{FEATURE_FOLDER}}.{{DOMAIN}}"
          port: 3000

      # Docker configuration
      docker:
        traefik: infra/docker-compose.traefik.yml
        compose_template: infra/.devcontainer-template

      # Agent configuration templates
      agent:
        template_dir: infra/.agent-template
        templates:
          - source: CLAUDE.md.template
            target: CLAUDE.md
        symlinks:
          - .claude/commands
          - .claude/skills

      # Environment template
      env:
        template: |
          COMPOSE_PROJECT_NAME={{COMPOSE_PROJECT}}
          FRONTEND_URL=https://{{FEATURE_FOLDER}}.{{DOMAIN}}

services:
  - name: api
    template: spring-boot-maven
    path: api
    health_url: "https://api-{{FEATURE_FOLDER}}.myapp.test/health"

your-project/
├── infra/
│   └── .devcontainer-template/      # Template for workspace containers
│       ├── docker-compose.devcontainer.yml.template
│       ├── compose.infra.yml.template   # Optional: separate infra services
│       ├── Dockerfile
│       └── devcontainer.json.template
└── ...

# docker-compose.devcontainer.yml.template
services:
  api:
    build: ./api
    user: vscode  # Run as non-root to avoid permission issues
    labels:
      - "traefik.http.routers.{{FEATURE_FOLDER}}-api.rule=Host(`api-{{FEATURE_FOLDER}}.{{DOMAIN}}`)"
    environment:
      - DATABASE_URL=postgres://app:app@postgres:5432/mydb

  frontend:
    build: ./fe
    user: vscode  # Run as non-root to avoid permission issues
    labels:
      - "traefik.http.routers.{{FEATURE_FOLDER}}.rule=Host(`{{FEATURE_FOLDER}}.{{DOMAIN}}`)"

your-project/
├── infra/
│   └── docker-compose.traefik.yml   # Traefik reverse proxy
└── ...

# infra/docker-compose.traefik.yml
services:
  traefik:
    image: traefik:v2.10
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
      - ~/.panopticon/traefik/certs:/certs:ro
    command:
      - --providers.docker=true
      - --entrypoints.web.address=:80
      - --entrypoints.websecure.address=:443

your-project/
├── infra/
│   └── seed/
│       └── seed.sql              # Sanitized production data
└── ...

services:
  postgres:
    image: postgres:16
    volumes:
      - /path/to/project/infra/seed:/docker-entrypoint-initdb.d:ro

your-project/
├── infra/
│   └── .agent-template/
│       ├── CLAUDE.md.template    # Project-specific AI instructions
│       └── .mcp.json.template    # MCP server configuration
└── .claude/
    └── skills/                   # Project-specific skills
        └── my-project-standards/
            └── SKILL.md

# ~/.panopticon/projects.yaml
projects:
  simple-app:
    name: "Simple App"
    path: /home/user/projects/simple-app
    issue_prefix: APP
    # No workspace config needed - uses git worktrees

# WRONG - causes Maven startup failure
environment:
  - MAVEN_CONFIG=/maven-cache

# CORRECT - use command line argument
command: ./mvnw spring-boot:run -Dmaven.repo.local=/maven-cache/repository
volumes:
  - ~/.m2:/maven-cache:cached

projects:
  myapp:
    name: "My App"
    path: /home/user/projects/myapp

    quality_gates:
      # Runs only when merging the frontend repo
      fe-lint:
        command: pnpm lint
        path: frontend
        required: true
        phase: pre_push

      # Runs only when merging the backend repo
      api-checkstyle:
        command: ./mvnw checkstyle:check
        path: backend
        required: true
        phase: pre_push

      # Global gate — runs in monorepo context only (no path = skipped in polyrepo)
      integration-tests:
        command: make integration-test
        required: false
        phase: post_push

    workspace:
      type: polyrepo
      repos:
        - name: fe
          path: frontend       # Must match gate.path exactly
          branch_prefix: "feature/"
        - name: api
          path: backend        # Must match gate.path exactly
          branch_prefix: "feature/"