Usages:
  conventions: .goga/usages/conventions.md

Annotations: |
  Apply the `conventions` practice during development and testing.
  Use urllib.request from the standard library for HTTP requests.
  Use shutil for file copying.
  Route all output through sys.stderr (click is not used).

---

"connect(agents: list[str], force_overwrite: bool = False) -> exit_code:int":
  location: connect.py
  annotations: |
    Install goga skills and commands for one or more AI agents,
    including skills from installed tool packages.

    `agents`: list of target AI agents (required, non-empty). Supported: claude, codex, cursor
    `force_overwrite`: allow overwriting existing skills. Defaults to False
    `exit_code`: return code (0 success, 1 error)

    Algorithm:
    1. Validate that `agents` is non-empty; otherwise exit with code 1
    2. For each agent in `agents`:
       a. Resolve the target directory for the agent:
          - claude → ~/.claude/
          - codex → ~/.codex/
          - cursor → ~/.cursor/
       b. Purge stale goga installations:
          - Scan target_directory/skills/ for goga-* subdirectories
          - Delete all matches
       c. Copy assets from source to target directory (commands only for AGENTS_WITH_COMMANDS):
          - Execute only when the agent is in AGENTS_WITH_COMMANDS (claude)
          - For codex and cursor, skip commands entirely (commands = [])
          - goga/agent/commands/* → <target>/commands/goga/
          - goga/agent/skills/* → <target>/skills/
       d. Fetch the DSL specification:
          - URL: https://raw.githubusercontent.com/qarium/codemanifest/refs/heads/0.0.x/specs/en.md
          - Perform HTTP GET via urllib.request
          - Write response to <target>/skills/goga-cell/dsl.md
          - On network failure, exit with code 1
       e. Install skills from tool packages:
          i. Discover all installed Python packages with the goga_tool_ prefix
             via importlib.metadata.packages_distributions()
          ii. For each discovered package goga_tool_<tool_name>:
              - Resolve the package path
              - Validate entry point: verify <package>/skills/<tool_name>/SKILL.md exists
                - If absent, log warning to stderr and skip the package
              - Copy all skills from <package>/skills/* to <target>/skills/,
                prepending goga-tool- to each skill directory name
              - If the target skill already exists and force_overwrite=False,
                skip with a warning to stderr
              - If force_overwrite=True, overwrite the target skill
       f. Print the list of installed skills and commands
    3. Return 0 if all agents processed successfully, otherwise 1

    Requirements:
    - Fully recreate goga directories at step 2b (delete + copy)
    - Do not modify content belonging to other extensions
    - Do not touch CLAUDE.md, settings.json, README.md in the target directory
    - Download dsl.md from the external repository on every installation
    - Use urllib.request exclusively (no external dependencies)
    - Use importlib.metadata from the standard library
    - Abort with code 1 if dsl.md download fails
    - Derive tool skill names as goga-tool-<skill_dir_name>
    - Skip any tool package that lacks an entry-point skill entirely

---

Author: Mikhail Trifonov
CreatedAt: 15/05/26

Description: |
  Manifest describing the goga skill and command connection logic,
  including skill installation from goga_tool_* tool packages
