Repo Maintenance

Skill: IDS Repo Maintenance

Purpose

Help maintainers perform day-to-day tasks in the IDS monorepo — fixing bugs, managing releases, reviewing PRs, fixing CI, and keeping documentation in sync.

Triage & Prioritisation

During this period, the focus is bug fixes only — no new features, no regressions.

flowchart TD
    A[Incoming request] --> B{What type?}
    B -->|Bug report| C[Ask user to create\nGitHub issue using\nbug_report template]
    B -->|Feature request| D[Features are paused —\nask user to create issue\nusing feature_request template\nfor future prioritisation]
    B -->|New component proposal| D
    B -->|Consumer question| E[Point to Storybook docs\nor relevant agent skill]

    C --> F[Issue created with\nversion, repro steps,\nexpected vs actual]
    F --> G{Large visual\nregression?}
    G -->|Yes — layout shift,\ntheme breakage,\ncomponent redesign| H[Escalate to\nDesign team before\nany code changes]
    G -->|No — functional bug| I[Assign issue to\nGitHub Copilot]
    I --> J[Copilot bug-fixing agent\nanalyses, creates repro story,\nfixes, and opens PR]
    J --> K[Review the PR]
    K --> L{PR looks good?\nTests pass?\nNo regressions?}
    L -->|Yes| M[Merge → CI auto-releases\nif version was bumped]
    L -->|No| N[Leave review comments,\nre-assign to Copilot]
    N --> J

Key rules:

• Bug fixes are the priority — fix what's broken, prevent regressions
• Features are paused — ask requesters to file a feature_request or new-component-proposal issue so we can validate the approach when the team is at full capacity
• Large visual regressions (layout shifts, theme breakage, component redesigns) need Design team sign-off before merging
• For functional bugs: users create a GitHub issue using the bug_report template (.github/ISSUE_TEMPLATE/bug_report.md), then assign it to Copilot
• Copilot's bug-fixing agent will solve issues autonomously — see docs/COPILOT-AGENT-SETUP.md for setup and usage
• Cross-branch bugs use labels (affects-main, affects-5.x, affects-both-branches) — the Copilot agent handles this automatically, see .github/CROSS_BRANCH_LABELS.md

Issue templates available:

When to Use

• Triaging and fixing bugs reported by consumers (primary focus)
• Reviewing PRs (including Copilot-generated ones) — ensure no regressions
• Fixing CI failures or flaky tests
• Cutting a release after bug fixes are merged
• Updating dependencies (security patches, minor bumps)
• Keeping documentation and agent skills in sync after changes

Prerequisites

corepack enable
yarn
yarn prepare   # installs husky hooks, builds all packages

Node 22, Yarn 4 (Berry). The packageManager field in root package.json pins the exact Yarn version.

Monorepo Structure

Build order: tokens → theme-preset → components. Always respect this when building.

yarn build runs all package builds in topological order, then runs yarn translate which generates:

• AI component docs (packages/*/.ai/)
• Token reference (token-reference.md)
• Skills translations
• llms.txt files for each package

Task Workflows

1. Adding a New Component

Each component lives in packages/components/src/components/<Name>/ with these required files:

ComponentName/
├── index.ts                    # Exports
├── ComponentName.tsx           # Implementation (Iress prefix, IressStyledProps)
├── ComponentName.styles.ts     # Panda CSS CVA recipe
├── ComponentName.stories.tsx   # Storybook stories
├── ComponentName.test.tsx      # Vitest tests
└── ComponentName.docs.mdx      # Documentation

Checklist:

1. Follow the naming convention: Iress<Name> for the component, Iress<Name>Props for the interface
2. Extend IressStyledProps (or IressUnstyledProps, IressTextProps) as appropriate
3. Include propagateTestid support
4. Add comprehensive JSDoc on all props
5. Export from packages/components/src/main.ts
6. Add .ai/components/<name>.md AI context doc
7. Update agent skills if the component introduces a new pattern (see PR Documentation Sync)

Full guide: .github/instructions/component-creation.instructions.md

2. Modifying Design Tokens

Token schemas live in packages/tokens/src/schema/ as TypeScript files.

# After modifying token schemas:
yarn workspace @iress-oss/ids-tokens run cssVars   # regenerate CSS variables
yarn workspace @iress-oss/ids-tokens run build      # full build
yarn build                                          # rebuild downstream (theme-preset → components)

Checklist:

• New token category? Add entry to packages/tokens/.ai/index.json with name, description, schemaSource, cssVariablePrefix
• CSS variables follow --iress-{category}-{name} naming
• Update .agents/skills/token-usage/references/token-reference.md if token values change
• Run yarn test:coverage in tokens package to verify transforms

3. Running Validation

# Full validation suite (what CI runs):
yarn lint                # ESLint across all packages
yarn typecheck           # TypeScript strict mode
yarn test:ci             # Vitest with coverage + coverage threshold check
yarn lint:mermaid        # Validate Mermaid diagrams in docs
yarn size                # Bundle size against budgets

# Local development (no threshold check):
yarn test:coverage       # Vitest with coverage (runs once, exits)

# Single package:
yarn workspace @iress-oss/ids-components run test:coverage
yarn workspace @iress-oss/ids-components run test:coverage Button.test.tsx

# Single file lint:
yarn workspace @iress-oss/ids-components exec npx eslint src/components/Button/Button.tsx --fix

Note: test:ci = test:coverage + check-coverage --all (enforces coverage thresholds). CI retries test:ci up to 3 times for flaky tests.

⚠️ Never run yarn dev, yarn test (without :coverage), or any watch command in automated workflows — they never exit.

Exception: yarn dev is acceptable when using Playwright CLI/MCP or Chrome DevTools with your agent to visually debug components. Be aware it starts a persistent process that never exits — you must manually stop it when done.

4. Bundle Size Management

Budgets are defined in .size-limit.json:

yarn size          # check against budgets
yarn size:check    # JSON output for scripting

If a budget is exceeded:

1. Check if the increase is justified (new component, new token category)
2. If justified, update the limit in .size-limit.json
3. If not, investigate — tree-shaking issues, unnecessary dependencies, unoptimised styles
4. Consider code-splitting or lazy loading for large additions

5. Dependency Updates

# Check outdated:
yarn upgrade-interactive

# After updating:
yarn                     # reinstall
yarn build               # verify build
yarn lint && yarn typecheck && yarn test:ci   # full validation
yarn size                # check bundle impact

Key constraints:

• React peer dependency is ^17 || ^18 || ^19 (devDependencies use React 19)
• Panda CSS version must stay compatible with @iress-oss/ids-theme-preset
• Storybook addons must match the Storybook major version (currently 10.x)
• @typescript-eslint/* packages must be on the same minor version

6. CI/CD & Releases

CI runs on every push via .github/workflows/ci-cd.yml.

Pipeline overview:

flowchart LR
    A[Push to\nany branch] --> B[setup]
    B --> C[validate\nlint / typecheck /\ntest:ci / lint:mermaid / size]
    B --> D[chromatic\nvisual regression]
    B --> E[build\nartifacts]
    C --> F[validated gate]
    D --> F
    F --> G{Branch?}
    G -->|main or 5.x| H[stable-release\npublish to npm]
    G -->|other + canary trigger| I[canary\npublish to npm]
    G -->|other| J[Done]

Pipeline stages:

1. setup — install deps, build all packages (cached)
2. validate — parallel matrix: lint, typecheck, test:ci, lint:mermaid, size
3. build — upload build artifacts
4. chromatic — visual regression testing via Chromatic (root, components, tokens). Auto-accepts changes on main and 5.x. On feature branches, visual diffs must be reviewed and approved in the Chromatic UI before the job passes
5. validated — gate job, requires validate + chromatic to pass
6. stable-release or canary — publish to npm

Branches:

• main — v6 development (current). Pushes here trigger stable releases
• 5.x — v5 maintenance only. Also triggers stable releases. v6 is never merged to 5.x — the two branches are completely independent

How to cut a stable release:

flowchart TD
    A[Bump version in\npackage.json] --> B[Merge PR to main\nor 5.x]
    B --> C[CI runs full\nvalidation + Chromatic]
    C --> D{All checks pass?}
    D -->|No| E[Fix failures,\npush again]
    D -->|Yes| F[CI compares local version\nvs npm registry]
    F --> G{Local version\nhigher?}
    G -->|No| H[No publish — version\nalready on npm]
    G -->|Yes| I[Auto-publish to npm\nwith provenance]
    I --> J[Run create-releases.sh\nmanually for GitHub release]
    J --> K[⏳ ~2 hour delay before\nprivate npm registry updates]

Steps:

1. Bump the version field in the package's package.json (e.g. 6.0.0-beta.1 → 6.0.0-beta.2)
2. Merge to main (or 5.x for v5 backports)
3. CI detects the local version is higher than what's on npm and publishes automatically
4. After publish, create a GitHub release: .github/scripts/create-releases.sh (currently run manually — the CI step is commented out pending permissions). It creates a tagged GitHub release with auto-generated notes and npm install instructions
5. ⏳ There is approximately a 2-hour delay before published packages become available in the private npm registry. Consumers won't see the new version immediately

The stableVersion field in package.json tracks the last known stable version — it is informational and does not affect the publish process.

Stable releases:

• Triggered automatically on push to main or 5.x branches
• Detects version changes via .github/scripts/publish-packages.sh (compares local version to npm registry)
• Publishes to npm with latest tag (or prerelease tag like alpha/beta based on the version string)
• Requires the npm-publishing environment approval
• Do NOT publish stable releases manually via npm publish

Canary releases (two triggers):

# Option 1: GitHub Actions workflow_dispatch
# Go to Actions → CI/CD → Run workflow → Check "Publish canary release"
# Optionally select a specific package

# Option 2: Commit message trigger (any non-main branch)
git commit -m "feat: my change [canary]"              # publishes all packages
git commit -m "feat: my change [canary:@iress-oss/ids-components]"  # single package

Troubleshooting CI failures:

flowchart TD
    A[CI failed] --> B{Which job?}
    B -->|lint| C[Run yarn lint locally\nFix errors or use --fix]
    B -->|typecheck| D[Run yarn typecheck\nFix type errors]
    B -->|test:ci| E{Failed all\n3 retries?}
    B -->|lint:mermaid| F[Fix Mermaid syntax\nin .md/.mdx files]
    B -->|size| G[Run yarn size\nUpdate budget or\nreduce bundle]
    B -->|chromatic| H{Build error or\nvisual diff?}

    E -->|Yes| I[Real failure —\nreproduce locally with\nyarn workspace pkg\nrun test:coverage file]
    E -->|No| J[Flaky test —\nre-run CI]

    H -->|Build error| K[Run yarn build-storybook\nlocally to reproduce]
    H -->|Visual diff| L[Review in Chromatic UI\nApprove if intentional]

7. PR Documentation Sync

When code changes, these docs must stay in sync. Flag missing updates as required changes in PR review.

Full PR review guide: .github/instructions/pr-review.instructions.md

8. Bug Fixing

flowchart TD
    A[Bug reported] --> B{Has GitHub issue\nwith repro steps?}
    B -->|No| C[Ask reporter to\ncreate GitHub issue]
    B -->|Yes| D{Design-related\nvisual regression?}
    D -->|Yes| E[Escalate to\nDesign team first]
    D -->|No| F[Assign issue to\nGitHub Copilot]
    F --> G[Copilot creates PR\nwith fix + tests]
    G --> H[Review PR]
    H --> I{Passes review?}
    I -->|No| J[Leave comments,\nre-assign to Copilot]
    I -->|Yes| K[Merge to main]
    K --> L[Bump version if\nready to release]

Preferred workflow — let Copilot handle it:

1. Ensure the issue is in GitHub with clear reproduction steps
2. Assign the issue to GitHub Copilot (see docs/COPILOT-AGENT-SETUP.md)
3. Copilot's bug-fixing agent will analyse, create a reproduction story, fix, and open a PR
4. Review the PR Copilot creates — check the fix is targeted and tests cover the regression
5. If the PR needs changes, leave review comments and re-assign to Copilot

Manual workflow (if Copilot can't solve it):

1. Parse the issue — extract symptoms, affected components, reproduction steps
2. Confirm understanding before investigating
3. Create a Storybook story reproducing the bug (in the root component's stories file)
4. Fix the issue with a targeted change
5. Add/update tests covering the fix
6. Run full validation before pushing

Full guide: .github/instructions/bugfixing.instructions.md

9. Running Storybook Locally

yarn dev          # starts all 3 Storybook instances + watchers

Ports:

• 6005 — root Storybook (monorepo-level docs)
• 6006 — components Storybook
• 6007 — tokens Storybook

If ports are stuck from a previous session:

yarn dev:kill     # kills processes on ports 6005, 6006, 6007

Use yarn dev when you need to visually debug with Playwright CLI/MCP or Chrome DevTools. Remember it never exits — stop it manually when done.

10. Deprecating a Component

1. Add @deprecated JSDoc tag to the component and its props interface with a migration note
2. Keep the component exported from main.ts (don't remove — that's a breaking change)
3. Update the component's .docs.mdx with a deprecation banner and migration guidance
4. Update .agents/skills/ui-doctor/ so it flags usage of the deprecated component
5. Update .agents/skills/version-migration/ if this will be removed in the next major

11. Git Hooks (Husky)

yarn prepare installs husky hooks. They run automatically:

• pre-commit — runs lint-staged (lints and formats staged files)
• pre-push — runs tests

If a commit or push is blocked, it's because lint or tests failed on your changed files. Fix the issues rather than bypassing hooks.

Code Style Quick Reference

• TypeScript strict, single quotes, semicolons, trailing commas (all), 2-space indent
• LF line endings, UTF-8
• import type { Foo } — prefer inline type imports
• Unused vars with _ prefix are allowed
• Markdown/MDX: 80 char line length
• File order: Imports → Types → Constants → Helpers → Main Exports
• Test file order: Imports → Mocks → Test Data → Helpers → Test Suites

Common Pitfalls

Related Skills

Use these sibling skills for specialised tasks:

Related Resources

• .github/instructions/component-creation.instructions.md — full component creation guide
• .github/instructions/bugfixing.instructions.md — bug fixing workflow
• .github/instructions/pr-review.instructions.md — PR review checklist
• .github/instructions/file-organization.instructions.md — file ordering conventions
• .github/instructions/eslint.instructions.md — linting commands
• .github/instructions/testing-single-files.instructions.md — running individual tests
• AGENTS.md (root) — monorepo-level agent context
• packages/components/AGENTS.md — components package context
• packages/tokens/AGENTS.md — tokens package context