repo-maintenance

Invoke this skill when:

• Updating CHANGELOG.md after features, fixes, or deployments
• Bumping version numbers in package.json or config files
• Syncing deployment addresses after contract deploys
• Updating STATUS.md with current project state
• Preparing releases or deployments
• Managing branch workflows and conventional commits

| File | Purpose | Update Frequency |

|------|---------|------------------|

| CHANGELOG.md | Release history with breaking changes, fixes, deployments | Per release |

| STATUS.md | Live project status, current deployments, pending work | Per session |

| DECISIONS.md | Architectural Decision Records (ADRs) | Per major decision |

| apps/web/src/config/deployments.json | Canonical contract addresses (source of truth) | Per deployment |

| apps/web/src/config/markets.json | Active markets per chain | Per market creation |

| packages/contracts-evm/package.json | Contract version (semantic) | Per contract release |

1. Identify Version Type

| Change Type | Version Bump | Example |

|-------------|--------------|---------|

| Breaking API change | Major (X.0.0) | Interface signature change |

| New feature | Minor (0.X.0) | New contract function |

| Bug fix | Patch (0.0.X) | Logic correction |

2. Update Version Files

```bash

# Contract version (packages/contracts-evm/package.json)

# Update "version" field

# Frontend cache invalidation (apps/web/src/config/deployments.json)

# Bump "version" field to force browser refresh

```

3. Update CHANGELOG.md

Follow this format:

```markdown

⚠️ BREAKING CHANGE

• Description: What changed and migration steps

Fixed

• Bug Name (date): Root cause and solution

Added

• Feature Name: Description with test count

Deployed

• Network Name VX.Y.Z:

- Contract: 0xAddress

Coverage

• X tests passing (Y new)
• ContractName: XX.XX% lines, XX.XX% functions

```

After any contract deployment:

1. Verify On-Chain State (MANDATORY)

```bash

cd packages/contracts-evm

source .env

# Verify core contracts are live

cast call $LAUNCHPAD_ENGINE "owner()" --rpc-url $BASE_SEPOLIA_RPC_URL

cast call $COLLATERALIZER "usdc()" --rpc-url $BASE_SEPOLIA_RPC_URL

cast call $AMM_ENGINE "usdc()" --rpc-url $BASE_SEPOLIA_RPC_URL

# Verify market initialization

cast call $LAUNCHPAD_ENGINE "isInitialized(address)" $MARKET --rpc-url $BASE_SEPOLIA_RPC_URL

```

STOP if any check fails.

2. Update deployments.json (Canonical Source)

```json

{

"version": "9.1.0", // BUMP THIS to invalidate browser cache

"lastUpdated": "2025-12-29T00:00:00Z",

"networks": {

"84532": {

"name": "Base Sepolia",

"contracts": {

"LaunchpadEngine": "0x...",

"AMMEngine": "0x...",

"TickBookPoolManager": "0x..."

}

}

}

}

```

3. Run Sync Script

```bash

./sync-deployments.sh

```

This copies from apps/web/src/config/deployments.json to packages/contracts-evm/deployments.json.

4. Verify Frontend Build

```bash

cd apps/web

npm run build # Runs validate-config.js automatically

```

5. Update STATUS.md

Add new deployment addresses to the Active Deployment tables.

6. Commit with Conventional Format

```bash

git add apps/web/src/config/deployments.json apps/web/src/config/markets.json STATUS.md CHANGELOG.md

git commit -m "feat(deploy): V9.1.0 to Base Sepolia

• AMMEngine: 0x...
• LaunchpadEngine: 0x...

🤖 Generated with Claude Code"

```

Update STATUS.md during each work session:

Session Start

• Check "Pending Work" section for context
• Review "Active Deployment" tables for current state

During Session

• Move completed items from "Pending Work" to "Completed This Session"
• Add new pending items as discovered

Session End

• Update version badges at top if deployment occurred
• Update deployment address tables if contracts changed
• Add session summary at bottom

Format

```markdown

# Project Status

> Last Updated: YYYY-MM-DD (VX.Y.Z Description)

• ✅ FEATURE DEPLOYED — Brief description
• ⚠️ KNOWN ISSUE — Brief description with workaround

Summary: What this version adds/fixes

Contract Changes

| Contract | Change |

|----------|--------|

| ContractName | Description of change |

New Tests (N)

| Test | Priority | Status |

|------|----------|--------|

| test_Name | P0 | ✅ |

VX.Y.Z Deployed Addresses (Network)

| Contract | Address |

|----------|---------|

| ContractName | 0x... |

• [ ] Task — Description with effort estimate (S/M/L)

• ✅ Task — What was done

```

Use this format for all commits:

```

():

[optional body]

🤖 Generated with Claude Code

```

Types

| Type | Use For |

|------|---------|

| feat | New feature |

| fix | Bug fix |

| docs | Documentation only |

| refactor | Code change that neither fixes bug nor adds feature |

| test | Adding or updating tests |

| chore | Maintenance tasks |

| deploy | Deployment-related changes (often feat(deploy):) |

Scopes

| Scope | Package/Area |

|-------|--------------|

| contracts | packages/contracts-evm |

| web | apps/web |

| deploy | Deployment configuration |

| config | Configuration files |

The .husky/pre-commit hook runs when staging deployment configs:

1. Deployment Verification: Runs ./script/verify-deployment.sh when deployments.json or markets.json are staged
2. Version Bump Warning: Alerts if deployments.json changed but version not bumped

If hook fails, fix the issue before committing.

For major decisions, add to DECISIONS.md:

```markdown

Date: YYYY-MM-DD

Status: Proposed | Accepted | Deprecated | Superseded

Context

What is the issue that we're seeing that motivates this decision?

Decision

What is the change that we're proposing and/or doing?

Consequences

What becomes easier or more difficult because of this change?

```

```bash

# Check current versions

cat packages/contracts-evm/package.json | grep version

cat apps/web/src/config/deployments.json | grep version

# Verify deployment

cd packages/contracts-evm && source .env

cast call $LAUNCHPAD_ENGINE "owner()" --rpc-url $BASE_SEPOLIA_RPC_URL

# Sync after deployment

./sync-deployments.sh

# Build to verify config

cd apps/web && npm run build

# View recent commits for message style

git log --oneline -10

```

After deployment sync, users need to hard refresh:

• Chrome/Edge: Ctrl+Shift+R (Windows) or Cmd+Shift+R (Mac)
• Firefox: Ctrl+F5 (Windows) or Cmd+Shift+R (Mac)

The version field in deployments.json triggers automatic cache invalidation when bumped.

When deploying to multiple networks:

1. Deploy to each network separately
2. Update deployments.json with all network addresses
3. Update markets.json with markets per chain
4. Bump version once (covers all networks)
5. Document all deployments in CHANGELOG.md

Use these labels for pending work:

• S (Small): < 2 hours
• M (Medium): 2-6 hours
• L (Large): > 6 hours

When upgrading to a new major version, archive previous version files to maintain history while keeping the working directory clean.

Directory Structure

```

copan/

├── packages/contracts-evm/

│ ├── deployments/

│ │ ├── v9-latest.json # Current version

│ │ ├── v9-baseSepolia.json # Per-network current

│ │ ├── v9-monadTestnet.json

│ │ └── v8-archive/ # Previous version archive

│ │ ├── v8-latest.json

│ │ ├── v8-baseSepolia.json

│ │ └── README.md

│ │

│ ├── docs/

│ │ ├── v9/ # Active version docs

│ │ └── _archive/ # Archived docs

│ │ ├── v8/

│ │ ├── v7/

│ │ └── v6/

│ │

│ ├── test/v9/ # Active version tests

│ ├── archive_tests/ # Archived tests

│ │ └── v8/

│ │

│ ├── abi/v9/ # Active ABIs

│ └── archive_scripts/ # Deprecated scripts

│

├── apps/web/

│ ├── src/config/

│ │ ├── deployments.json # Canonical (current)

│ │ └── markets.json # Current markets

│ ├── archive/ # Frontend archives

│ │ └── v8/

│ └── docs/_archive/

│ └── v8-implementation/

```

Archive Locations by Artifact Type

| Artifact | Active Location | Archive Pattern |

|----------|-----------------|-----------------|

| Deployments | deployments/v{N}-*.json | deployments/v{N-1}-archive/ |

| Docs | docs/v{N}/ | docs/_archive/v{N-1}/ |

| Tests | test/v{N}/ | archive_tests/v{N-1}/ |

| Scripts | script/ | archive_scripts/ |

| Frontend | apps/web/src/ | apps/web/archive/v{N-1}/ |

| ABIs | abi/v{N}/ | Keep in place (small files) |

Major Version Upgrade Checklist

When releasing a new major version (e.g., V9 → V10):

1. Archive Deployments

```bash

cd packages/contracts-evm/deployments

mkdir v9-archive

mv v9-*.json v9-archive/

echo "# V9 Archive\nArchived: $(date)\nReason: V10 release" > v9-archive/README.md

```

1. Archive Version-Specific Docs

```bash

mv docs/v9 docs/_archive/v9

mkdir docs/v10

```

1. Archive Version-Specific Tests (if superseded)

```bash

mkdir -p archive_tests/v9

mv test/v9/* archive_tests/v9/ # Only if tests no longer apply

```

1. Create New Version Files

```bash

touch deployments/v10-latest.json

mkdir docs/v10

mkdir test/v10

```

1. Update package.json

```json

{

"version": "10.0.0",

"description": "Sooth Protocol V10 EVM Contracts"

}

```

1. Document in CHANGELOG.md

```markdown

## [10.0.0] - YYYY-MM-DD

### ⚠️ BREAKING CHANGE

- Major architecture change (see docs/v10/)

- V9 contracts archived to deployments/v9-archive/

```

What NOT to Archive

• CHANGELOG.md — Always append, never archive
• STATUS.md — Rolling document, clear old sessions periodically
• DECISIONS.md — Append ADRs, mark old ones as "Superseded"
• Core contracts — Keep all versions in contracts/ (git tracks history)
• Root configs — package.json, foundry.toml, etc. are versioned in git

Archive README Template

Create a README.md in each archive folder:

```markdown

# V{N} Archive

Archived: YYYY-MM-DD

Superseded By: V{N+1}

Reason: [Brief explanation]

• v{N}-latest.json — Final deployment addresses
• v{N}-baseSepolia.json — Base Sepolia deployment
• v{N}-monadTestnet.json — Monad deployment

[Brief summary of what this version implemented]

[Any notes for understanding changes to next version]

```

Quick Archive Commands

```bash

# Archive a version's deployments

VERSION=9

cd packages/contracts-evm/deployments

mkdir v${VERSION}-archive

mv v${VERSION}-*.json v${VERSION}-archive/

# Archive version docs

cd ../docs

mv v${VERSION} _archive/v${VERSION}

# Archive version tests (if applicable)

cd ../

mkdir -p archive_tests/v${VERSION}

mv test/v${VERSION}/* archive_tests/v${VERSION}/

```