[Maintenance] Auto-load OC skills before agent action to enforce conventions

[RussellSB]

Problem

When the OpenCode (OC) agent runs in GitHub Actions, it does not automatically load the .opencode/skills/ files before executing tasks. This means critical conventions — git commit format, PR title rules, pipeline architecture — are ignored unless the agent happens to trigger the skill tool during its session.

Observed in PR #224: the agent made commits with non-conventional messages (missing feat:/fix: prefixes, wrong casing) despite the maintenance skill containing explicit rules for Conventional Commits and PR title formatting.

Root Cause

Skills are loaded on-demand via the skill tool, not automatically at session start. The agent must explicitly call skill({ name: "maintenance" }) to load conventions, but:

1. The skill description doesn't always match the task request closely enough to trigger loading
2. No configuration forces specific skills to load before work begins
3. AGENTS.md references conventions but the agent doesn't always parse it thoroughly before acting

Impact

• Commits violate Conventional Commits format (lint-pr-title.yml rejects PR titles)
• PR descriptions miss required structure
• Agent re-litigates design decisions already settled in skills (e.g., deprecation policy, API surface)
• Each PR requires manual review for convention compliance

Proposed Solutions

Option 1: opencode.json instructions (Recommended — immediate)

Add a project-level config that forces skill content into every session:

{
  "$schema": "https://opencode.ai/config.json",
  "instructions": [
    ".opencode/skills/maintenance/SKILL.md",
    ".opencode/skills/pytrendy/SKILL.md"
  ]
}

Pros: Zero agent changes needed, conventions always in context.
Cons: Increases context size for simple tasks.

Option 2: Enhance AGENTS.md with explicit skill-loading instructions

Add a mandatory section:

## Critical: Skill Loading Requirements
Before making ANY code changes, commits, or PRs:
1. Load the `maintenance` skill — Contains Conventional Commits and PR title rules
2. Load the `pytrendy` skill — Contains pipeline architecture
3. Follow all conventions from loaded skills

Pros: Works within existing framework, no new config files.
Cons: Relies on agent compliance; may still be skipped.

Option 3: Custom agent with forced skill loading

Create .opencode/agents/conventional-commit.md that mandates loading maintenance and pytrendy skills before any code changes.

Option 4: Upstream feature request

Request OpenCode support for preloadSkills or loadSkills configuration in opencode.json.

Recommended Plan

1. Immediate: Implement Option 1 (opencode.json) + Option 2 (AGENTS.md)
2. Track: Option 4 as a follow-up feature request on OpenCode GitHub

Commit type note

This is a CI/tooling improvement. Commits for this issue must use chore: or ci: prefix — not fix: or feat: — to avoid triggering an auto-release via semantic-release on main. The conventionalcommits preset maps fix: → patch bump and feat: → minor bump; only chore:/ci:/docs:/refactor: produce no version bump.

Acceptance Criteria

• OC agent in GitHub Actions loads maintenance skill before making commits
• Commits follow Conventional Commits format on first attempt
• PR titles pass lint-pr-title.yml validation

[coderabbitai]

Coding Plan

Summary

• Ship both recommended fixes together: a new root opencode.json whose instructions array pins maintenance + pytrendy into every session, plus a mandatory skill-loading section in AGENTS.md — the config forces context, the doc forces intent.
• Keep the config surgically minimal (schema + two instruction paths) so it doesn't collide with the CI action's model setting or introduce unrelated behaviour.
• No workflow YAML changes needed; skills and root config are auto-discovered at runtime.
• Land this as a chore: (or ci:) commit/PR — feat:/fix: would trip semantic-release into an unwanted version bump on main, and this is pure tooling.

Design Choices

Design Choice 1: Which skills should be force-loaded via the `instructions` array?

Options Considered:

1. Preload only maintenance + pytrendy — the two skills holding the violated conventions.
2. Preload all six skills — maximum coverage, maximum context cost on every session.
3. Preload maintenance only — smallest footprint, but drops pipeline-architecture guardrails.

Chosen Option: 1

Rationale: The repo has six skills, but only two carry the conventions this ticket is about (commit/PR format, deprecation policy, pipeline architecture). Preloading everything bloats context for trivial tasks. Option 1 directly matches the ticket's recommendation and the observed failure (commit/PR conventions live in maintenance, pipeline rules in pytrendy) while keeping context lean; the remaining four skills stay trigger-loaded as they are today.

💡 User Tips

Regenerate the plan with different choices with @coderabbitai <feedback>.

Implementation Steps

Phase 1: Force conventions into every session via project config

This phase implements the ticket's recommended immediate fix (Option 1). The goal is to make the convention-bearing skills unconditional context so the agent never starts work "blind" to commit/PR rules — no reliance on the skill tool firing at the right moment.

Task 1: Create a project-level `opencode.json`

Introduce a new config file at the repo root that pins the two convention skills into the instruction context of every OC session.

• Create opencode.json at the repository root (sibling of AGENTS.md).
• Set the $schema to https://opencode.ai/config.json for editor validation and forward-compatibility.
• Populate the instructions array with the relative paths .opencode/skills/maintenance/SKILL.md and .opencode/skills/pytrendy/SKILL.md.
• Rely on OpenCode's documented behaviour that instructions files are combined with AGENTS.md, so this augments rather than overrides the existing router doc.
• Keep the config minimal — do not add permission, model, or other keys that aren't needed for this ticket, to avoid clobbering the CI workflow's with: model: setting or introducing unrelated behaviour.

Task 2: Confirm the config is picked up by the CI agent path

Verify the new file sits where both the GitHub Action and local CLI expect it, without touching workflow YAML.

• Confirm no workflow change is required: .opencode/skills and root config are auto-discovered at runtime by the agent, not wired into opencode.yml.
• Note that .github/CODEOWNERS routes root/.github changes to @RussellSB; the new root file will fall outside the .github/ rule but under the blanket * owner, so review routing is already handled.

🤖 Prompt for AI agents

Implement the immediate fix: force the two convention-carrying skills
(`maintenance`, `pytrendy`) into every OC session by adding project-level
config, so the agent stops "skipping" commit/PR conventions.

- Create `opencode.json` at the repository root, sitting alongside `AGENTS.md`.
- Set `$schema` to `https://opencode.ai/config.json`.
- Add an `instructions` array containing exactly two relative paths:
`.opencode/skills/maintenance/SKILL.md` and
`.opencode/skills/pytrendy/SKILL.md`.
- Keep the file surgically minimal — no `permission`, `model`, or other
unrelated keys. This avoids clobbering the CI workflow's `with: model:` setting
or introducing unrelated behaviour. `instructions` combines with `AGENTS.md`
rather than replacing it.
- Do not modify `.github/workflows/opencode.yml` or any other workflow YAML —
`.opencode/skills` and root config are auto-discovered at runtime, so no wiring
changes are needed.
- Verify placement: confirm the file location works for both the GitHub Action
path and local CLI usage, and note that `.github/CODEOWNERS` review routing
already covers this new root file via the blanket `*` owner (since it falls
outside the `.github/` rule).

Phase 2: Harden the router doc with a mandatory skill-loading directive

This phase implements Option 2, belt-and-braces alongside Phase 1. opencode.json instructions handles machines that honour config; the AGENTS.md directive handles the reasoning layer, making the expectation explicit and unambiguous so the agent doesn't re-litigate settled decisions.

Add a "Critical: Skill Loading Requirements" section to `AGENTS.md`

Insert a short, imperative section that instructs the agent to load the convention skills before any code change, commit, or PR.

• Update AGENTS.md (repo root) by adding a clearly-flagged mandatory section near the top, so it's parsed before the agent acts.
• State the requirement plainly: load maintenance (commit/PR-title conventions, deprecation policy, API surface) and pytrendy (five-stage pipeline architecture) before making changes, and follow their conventions.
• Cross-reference — don't restate — the detailed rules already summarised in the existing ## Commits & PR titles section and the ## Skills (deeper, trigger-loaded) list, keeping AGENTS.md compact and avoiding drift from the SKILL.md source of truth.
• Explicitly reaffirm the commit-type constraint relevant to this repo (Conventional Commits enforced by lint-pr-title.yml, deprecation-of-public-param is feat: not refactor:) by pointing at the maintenance skill rather than duplicating the table.

🤖 Prompt for AI agents

Harden `AGENTS.md` (the router doc) with an explicit, mandatory skill-loading
directive as a belt-and-braces companion to Phase 1's config change — this
covers the reasoning layer where the config's `instructions` array covers the
mechanical layer.

- Edit `AGENTS.md` at the repo root, adding a clearly-flagged "Critical: Skill
Loading Requirements" section near the top of the file so it's parsed before the
agent acts.
- State plainly that the agent must load the `maintenance` skill
(commit/PR-title conventions, deprecation policy, API surface) and the
`pytrendy` skill (five-stage pipeline architecture) before making any changes,
and must follow their conventions.
- Cross-reference rather than duplicate: point at the existing `## Commits & PR
titles` section and the `## Skills (deeper, trigger-loaded)` list instead of
restating their content, keeping `AGENTS.md` compact and avoiding drift from the
SKILL.md source of truth.
- Explicitly reaffirm the commit-type constraint relevant to this repo —
Conventional Commits are enforced by `lint-pr-title.yml`, and deprecating a
public parameter is a `feat:` commit, not `refactor:` — by pointing at the
`maintenance` skill rather than duplicating the table inline.

Research

PyTrendy splits its agent context into two layers: a compact root-level AGENTS.md (the "router" doc) and six trigger-loaded deep-dives under .opencode/skills/*/SKILL.md (maintenance, pytrendy, cicd, debug, test, pr-plots). The agent gets invoked in CI by .github/workflows/opencode.yml (via anomalyco/opencode/github@latest on /oc comments), and its output is policed by .github/workflows/lint-pr-title.yml, which enforces the Conventional Commits regex.

There is currently no opencode.json anywhere in the repo, and .opencode/ contains only the skills/ directory. Per OpenCode docs, the instructions field in opencode.json accepts file paths/globs and is combined with (not a replacement for) AGENTS.md — which makes Options 1 and 2 complementary rather than redundant.

---

🚀 Next Steps

🤖 All AI agent prompts combined

Task: 1

Implement the immediate fix: force the two convention-carrying skills
(`maintenance`, `pytrendy`) into every OC session by adding project-level
config, so the agent stops "skipping" commit/PR conventions.

- Create `opencode.json` at the repository root, sitting alongside `AGENTS.md`.
- Set `$schema` to `https://opencode.ai/config.json`.
- Add an `instructions` array containing exactly two relative paths:
`.opencode/skills/maintenance/SKILL.md` and
`.opencode/skills/pytrendy/SKILL.md`.
- Keep the file surgically minimal — no `permission`, `model`, or other
unrelated keys. This avoids clobbering the CI workflow's `with: model:` setting
or introducing unrelated behaviour. `instructions` combines with `AGENTS.md`
rather than replacing it.
- Do not modify `.github/workflows/opencode.yml` or any other workflow YAML —
`.opencode/skills` and root config are auto-discovered at runtime, so no wiring
changes are needed.
- Verify placement: confirm the file location works for both the GitHub Action
path and local CLI usage, and note that `.github/CODEOWNERS` review routing
already covers this new root file via the blanket `*` owner (since it falls
outside the `.github/` rule).
===============================================================================

Task: 2

Harden `AGENTS.md` (the router doc) with an explicit, mandatory skill-loading
directive as a belt-and-braces companion to Phase 1's config change — this
covers the reasoning layer where the config's `instructions` array covers the
mechanical layer.

- Edit `AGENTS.md` at the repo root, adding a clearly-flagged "Critical: Skill
Loading Requirements" section near the top of the file so it's parsed before the
agent acts.
- State plainly that the agent must load the `maintenance` skill
(commit/PR-title conventions, deprecation policy, API surface) and the
`pytrendy` skill (five-stage pipeline architecture) before making any changes,
and must follow their conventions.
- Cross-reference rather than duplicate: point at the existing `## Commits & PR
titles` section and the `## Skills (deeper, trigger-loaded)` list instead of
restating their content, keeping `AGENTS.md` compact and avoiding drift from the
SKILL.md source of truth.
- Explicitly reaffirm the commit-type constraint relevant to this repo —
Conventional Commits are enforced by `lint-pr-title.yml`, and deprecating a
public parameter is a `feat:` commit, not `refactor:` — by pointing at the
`maintenance` skill rather than duplicating the table inline.

💡 Iterate on the plan with: `@coderabbitai` <feedback>

Example Feedback
- `@coderabbitai` You can skip phase 3. Add a simple unit test case for phase 2.
- `@coderabbitai` For design choice 1 go ahead with option 3 and replan.

---

💬 Have feedback or questions? Drop into our discord!