Skip to content

skill-architecture.md

Latest commit

 

History

History
142 lines (113 loc) · 7.87 KB

skill-architecture.md

File metadata and controls

142 lines (113 loc) · 7.87 KB
Raw

Skill & Agent Architecture

How the project's AI skills, subagents, and GitHub automation fit together to add a new integration (a price provider or an inverter platform) and drive it from research → experimental beta → real-user validation → stable release.

Read this before working on the skills, the @claude-bot pipeline, or the autonomous integration workflow. For the staged roadmap to full autonomy, see docs/superpowers/specs/2026-06-15-autonomous-inverter-integration-design.md.

Two layers

Integration work spans two layers that meet at the lifecycle.

1. Skills (the "how", run by an agent in a session)

Skills live in .claude/skills/<name>/SKILL.md. They compose:

                       feature-lifecycle  (orchestrator)
                      /        |          \
       add-price-provider  add-inverter-platform   release
        (implementation)    (implementation)       (deploy: beta + prod)
Skill Role
add-price-provider Implementation recipe for a new electricity-price integration. Every file, in order, with the "read the integration source, never guess unique_ids" rule.
add-inverter-platform Implementation recipe for a new inverter platform. The inverter counterpart of add-price-provider. Starts by placing the inverter on the two control axes (see below).
feature-lifecycle Orchestrator. Drives either implementation skill through the 6-stage experimental→stable lifecycle, calls release, communicates in the issue/PR, and polls CI between human gates. Does not re-implement the others.
release Deploy. Owns beta vs prod remotes, version bump, CHANGELOG, tag, GitHub Release.

Composition rule: orchestrator calls implementation + deploy; implementation skills never deploy and never own the lifecycle. A new integration type adds a new implementation skill; feature-lifecycle and release are reused as-is.

2. GitHub automation (the "when", event-driven, stateless CI)

Each stage is a self-contained workflow in .github/workflows/ with an inline prompt running on anthropics/claude-code-action@v1, gated on an owner @claude-bot <cmd> comment.

Workflow Trigger Role
issue-triage.yml auto on issue open/edit classify + label (bug / question / enhancement / needs-info)
issue-analyze.yml @claude-bot analyze deep root-cause; dispatches the bess-analyst subagent
issue-fix.yml @claude-bot fix runs implement-issue in CI mode → draft PR
pr-review.yml @claude-bot on a PR review the diff against the rules
issue-integrate.yml @claude-bot integrate drive a new-integration issue through feature-lifecycle, one stage per invocation (resumes from the PR checklist)

The first four workflows are built for minimal bug fixes → one PR. Two workflows bridge into the skill layer instead of duplicating instructions (single source of truth — workflow prompts own only CI plumbing, skills own the process): issue-fix.yml runs implement-issue in its CI mode (the skill's own section mapping interactive steps — confirm gates, worktrees, background dispatch, local verify — to their pipeline equivalents), and issue-integrate.yml runs feature-lifecycle (via read-the-file), resuming from the PR-body checklist, one human-gated stage at a time. A skill edit is therefore also a bot-behavior change — review skill diffs with that in mind.

Subagents

Subagent Defined in Role
bess-analyst .claude/agents/bess-analyst.md Read-only issue analysis / debugging. Invoked by issue-analyze.yml.

The integration lifecycle (6 stages)

feature-lifecycle runs these. Two are human gates — do not fabricate logs or confirmations.

  1. Implement + ship experimental. Run the implementation skill end-to-end (incl. a source-derived regression fixture), mark the feature experimental, open a draft PR with a stage checklist in the body, ship to beta.
  2. User debug log (GATE). The user installs the beta and exports a debug report; verify the integration parses against their real registry.
  3. Lock the real config into the regression suite. The user's whole rig becomes a permanent regression scenario (backend discovery + frontend E2E).
  4. Re-ship, CI green. A loop of rapid minor fixes — batched into one consolidated beta, not a release per fix. Poll CI to green.
  5. User confirms on hardware (GATE). Never claim real-world validation before this.
  6. Graduate. Strip the experimental marker, update the maturity record, run the prod release, close the issue.

State machine: the PR-body checklist is the durable state. A resumed agent reads it to know where it is. This is what lets the multi-day, human-gated lifecycle run on stateless CI (see the grand-plan spec for the resume-trigger design).

Inverter-specific: the two control axes

Inverter control is two orthogonal axes, not a flat list of patterns (see docs/INVERTER_PLATFORMS.md → "Inverter Integration Patterns"):

  • Transport — how commands reach the inverter (TX-Cloud growatt_server service calls; TX-Modbus solax_modbus multi-brand entity writes; TX-Vendor-service e.g. huawei_solar; future TX-REST/MQTT).
  • Scheduling model — how a plan is expressed (numbered TOU slots; charge/ discharge period lists; mode-specific slots; ephemeral duration-bounded commands).

A new inverter's (transport × scheduling-model) coordinate determines which existing controller to model on and how much is new. The architecture (InverterController ABC + per-platform suffix maps + a generic /api/services/{domain}/{name} layer) absorbs new inverters additively — no core refactor required.

Running the work: two tracks

Agent work runs on two complementary tracks — pick by whether the work is unattended or hands-on. They are not competing; the interactive track is how you build the autonomous one.

Autonomous track Interactive track
Runtime GitHub Actions (claude-code-action) Local Claude Code
Trigger @claude-bot integrate on an issue You, via Agent View (claude agents)
Parallelism one runner per issue (automatic) many background sessions in Agent View
Isolation the CI checkout git worktrees — sibling or native .claude/worktrees/
Manage via issues / PRs / Actions tab the Agent View dashboard
Best for unattended, user-gated lifecycles hands-on dev you supervise

The autonomous track is the feature-lifecycle pipeline described above (issue-integrate.yml). The interactive track is Agent View (claude agents, Claude Code v2.1.139+): dispatch parallel background sessions and triage them by status (Needs input / Working / Completed) instead of juggling editor windows. Agent View is a dashboard, not an IDE — each session's worktree is a real folder you open in VS Code or cd into to run tests/scripts. Sibling and native worktrees are both first-class (siblings only drop out of the project-scoped view); see Worktree Conventions.

Where to go next

Concern File
Autonomy roadmap (Stages A–D) docs/superpowers/specs/2026-06-15-autonomous-inverter-integration-design.md
Inverter patterns + per-platform reference docs/INVERTER_PLATFORMS.md
Hard constraints docs/agents/rules.md
Commit / PR / release process docs/agents/workflow.md
Maturity conventions (experimental→stable) docs/agents/memory/