Corgispec Install

Install, update, or verify project-local Corgi GitFlow assets.

Overview

Use this skill to set up or maintain the repo-managed Corgi workflow files inside a target project.

This installer manages:

• Project-local command dispatch files and bundled schemas (per-repo)
• User-level command dispatch files (global, so /corgi-* commands work in every repo)

corgispec-* skills must already be installed at user level before this skill runs.

When to Use

• Fresh install into a project that already ran corgispec init
• Managed update when the target project already has an installer manifest
• Legacy install migration when managed files exist but no installer manifest exists
• Verify-only when the user wants a report without mutating files

Do not use this skill to create feature artifacts, review implementation work, or archive a change.

Core Pattern

Context Gate: If session context already contains ALL of: isolation.mode, active changes with worktree paths, current branch → Gate passed — SKIP config reading below and proceed to the next step. Otherwise: read openspec/config.yaml and proceed with discovery.

1. Inspect the target project and classify state:
   • Fresh install
   • Managed update
   • Legacy install
   • Verify-only
2. Ask for required choices:
   • target project path
   • schema: gitlab-tracked or github-tracked
   • whether to enable worktree isolation
3. Sync project-local managed fileset for OpenCode, Claude, and bundled schemas.
4. Sync user-level commands — copy corgi-*.md dispatch files to:
   • OpenCode: ~/.config/opencode/commands/corgi-*.md
   • Claude Code: ~/.claude/commands/corgi/*.md
5. Record runtime artifacts:
   • openspec/.corgi-install.json
   • openspec/.corgi-install-report.md
   • openspec/.corgi-backups/<timestamp>/ when backup is needed
6. Stop instead of overwriting locally modified managed files (both project-local and user-level).

Do not overwrite locally modified managed files — stop with a diff and let the user decide.

Why user-level commands? Without them, /corgi-* commands only exist in repos where you've run the installer. User-level install makes them available in every repo after a single installation.

Quick Reference

Managed fileset (project-local):

• .opencode/commands/corgi-*.md
• .claude/commands/corgi/*.md
• openspec/schemas/{selected-schema}/**

Managed fileset (user-level):

• ~/.config/opencode/commands/corgi-*.md
• ~/.claude/commands/corgi/*.md

Required user-level skills:

• Claude Code: ~/.claude/skills/corgispec-*
• OpenCode: ~/.config/opencode/skill/corgispec-*

Runtime artifacts:

• Manifest: openspec/.corgi-install.json
• Report: openspec/.corgi-install-report.md
• Backups: openspec/.corgi-backups/<timestamp>/

Implementation

• Target projects must already contain openspec/config.yaml.
• Only patch installer-owned fields in openspec/config.yaml:
  • schema
  • isolation.mode
  • isolation.root
  • isolation.branch_prefix
• Prompt before enabling worktree isolation.
• Treat missing manifest + existing managed files as a legacy install.
• Verify-only must never write files or create backups.
• Managed update must stop if a managed file differs from the last recorded manifest hash.
• Treat missing user-level corgispec-* skills as a prerequisite failure.
• User-level commands are installed unconditionally — they are not tracked in the project manifest. On update, always refresh user-level commands from source.
• Project-local commands override user-level commands — if a project has a custom .opencode/commands/corgi-propose.md, it takes precedence over the user-level one. OpenCode and Claude resolve project-local before user-level.

Prerequisites Check

Before any mode runs, verify the required tools are available:

corgispec --version

If the user is working with a github-tracked schema:

gh auth status

If the user is working with a gitlab-tracked schema:

glab auth status

Verify the required user-level skills are already installed:

• Claude Code skills under ~/.claude/skills/corgispec-*
• OpenCode skills under ~/.config/opencode/skill/corgispec-*

If any required tool is missing, unauthenticated, or the required user-level skills are absent, stop and report the failure in the report before proceeding. Tell the user to run the repo's global installer script before retrying.

Mode Steps

Fresh Install

Use when the target project has no managed fileset and no manifest.

1. Validate prerequisites

   • Run corgispec --version — stop if not found
   • Run gh auth status or glab auth status depending on intended schema — stop if unauthenticated
   • Verify ~/.claude/skills/corgispec-* and ~/.config/opencode/skill/corgispec-* exist — stop if missing
   • Confirm openspec/config.yaml exists in the target project — stop if missing

2. Ask for target project path

   • Prompt: "What is the path to the target project?"
   • Resolve to an absolute path
   • Verify the directory exists and contains openspec/config.yaml

3. Ask for schema choice

   • Prompt: "Which schema? gitlab-tracked or github-tracked"
   • Record the choice — it determines which schema directory to copy and which CLI to verify

4. Ask whether to enable worktree isolation

   • Prompt: "Enable worktree isolation? (yes/no — default: no)"
   • If yes: ask for isolation.root (default: .worktrees) and isolation.branch_prefix (default: feat/)
   • Do NOT auto-enable worktree isolation without asking

4b. Require the v4 Memory/Wiki contract

• Memory/Wiki is mandatory; do not offer an opt-out prompt or skip path
• Record that Step 10 must verify the complete structure and startup protocol

5. Copy project-local managed fileset from source repo to target

   Copy each of the following from the source repo (this repo) to the target project:

   • .opencode/commands/corgi-*.md → target .opencode/commands/corgi-*.md
   • .claude/commands/corgi/*.md → target .claude/commands/corgi/*.md
   • openspec/schemas/{selected-schema}/** → target openspec/schemas/{selected-schema}/**

   Create destination directories as needed. Do not delete any unmanaged files in the target.

5b. Install user-level commands (global, all repos)

Copy the same `corgi-*.md` command dispatch files to user-level directories so they are available in every repo:

- `.opencode/commands/corgi-*.md` → `~/.config/opencode/commands/corgi-*.md`
- `.claude/commands/corgi/*.md` → `~/.claude/commands/corgi/*.md`

Create destination directories as needed.

> **Why both project-local and user-level?** Project-local files let individual repos override commands. User-level files provide the default so every repo has `/corgi-*` even without running the installer.

6. Patch openspec/config.yaml

   Read the existing openspec/config.yaml in the target project. Update only these keys:

   • schema — set to the chosen schema
   • isolation.mode — set to worktree or none based on user choice
   • isolation.root — set if worktree enabled
   • isolation.branch_prefix — set if worktree enabled

   Do NOT replace the whole file. Preserve all other keys (e.g., context, rules).

7. Compute SHA-256 hashes for project-local files

   For each file copied in step 5 (project-local only), compute its SHA-256 hash:

   sha256sum <file>

   User-level commands are not hashed in the manifest — they are refreshed on every update.

8. Write openspec/.corgi-install.json manifest

   Write the manifest with all copied file paths and their hashes. See Manifest Format.

9. Generate openspec/.corgi-install-report.md

   Write the report with mode, timestamp, source repo, target project, and per-check status. See Verification Report.

10. Verify mandatory Memory/Wiki

    • Invoke the corgispec-memory-init contract against the target project
    • Require the complete v4 structure and session-bridge → MEMORY → hot startup protocol
    • If initialization or migration is needed, delegate to transactional corgispec bootstrap; do not write a partial structure
    • Include created, preserved, and conflicted files in the install report

Managed Update

Use when the target project already has openspec/.corgi-install.json.

1. Validate prerequisites

   • Run corgispec --version — stop if not found
   • Run gh auth status or glab auth status as appropriate — stop if unauthenticated
   • Verify ~/.claude/skills/corgispec-* and ~/.config/opencode/skill/corgispec-* exist — stop if missing

2. Read existing openspec/.corgi-install.json

   • Parse the manifest to get the list of managed files and their recorded SHA-256 hashes
   • Note the schema and isolation settings from the manifest

3. For each managed file: compare current hash vs manifest hash

   • Compute the current SHA-256 of each managed file in the target project
   • Compare against the hash stored in the manifest

4. If ANY managed file differs from its manifest hash → abort

   • Print a diff of the changed file(s):

     diff <source-file> <target-file>

   • Do not overwrite locally modified managed files
   • Write a FAIL status to openspec/.corgi-install-report.md
   • Stop. Tell the user which files have local modifications and ask them to resolve the conflict manually before re-running

5. If all managed files are clean → proceed with update

   • Copy updated project-local files from source repo to target (same fileset as fresh install step 5)
   • Copy updated user-level commands (same fileset as fresh install step 5b) — always refresh unconditionally
   • Recompute SHA-256 hashes for all project-local files
   • Refresh openspec/.corgi-install.json with new hashes and updated updatedAt timestamp
   • Write updated openspec/.corgi-install-report.md