sphere-workflow

sphere-workflow is a plugin-style workflow bundle for coding agents working in the go-sphere ecosystem. It packages the repository's bundled skills behind a single bootstrap entrypoint so agents can discover the right go-sphere workflow stage first, instead of treating the repo as a loose collection of unrelated skills.

The repository URL stays the same: https://github.com/go-sphere/skills.

What the Plugin Does

• Boots the agent into the go-sphere workflow through using-sphere-workflow
• Routes requirement shaping, specification, schema, API, and implementation work to the smallest relevant bundled skill
• Carries stage handoffs: every bundled skill names its upstream, downstream, boundary, and companion skills, so finished work moves to the next stage without re-routing from scratch
• Preserves direct skill usage for advanced users and existing installs
• Adds thin platform adapters for Claude Code, Cursor, Codex, and OpenCode

Installation

Choose the path that matches your agent. The README keeps the shortest working install flow here; platform-specific details stay in the linked docs.

Claude Code

Bootstrap Claude Code into the go-sphere workflow instead of manually picking between PRD, spec, schema, proto, and service skills. The plugin loads using-sphere-workflow first, then routes into the smallest relevant next step.

Marketplace install:

/plugin marketplace add go-sphere/skills
/plugin install sphere-workflow@sphere-workflow-marketplace

Or clone locally:

git clone https://github.com/go-sphere/skills.git ~/src/sphere-workflow

Then register the repository root in Claude Code using one of these entrypoints:

• .claude-plugin/plugin.json
• .claude-plugin/marketplace.json

Start a fresh Claude Code session after install or registration.

Detailed docs: docs/README.claude.md

Cursor

Quick start:

git clone https://github.com/go-sphere/skills.git ~/src/sphere-workflow

Then register the repository root with your normal Cursor local plugin flow using:

• .cursor-plugin/plugin.json

Start a fresh Cursor session after registration.

Detailed docs: docs/README.cursor.md

Codex

Quick install:

Tell Codex:

Fetch and follow instructions from https://raw.githubusercontent.com/go-sphere/skills/refs/heads/master/.codex/INSTALL.md

Manual install:

git clone https://github.com/go-sphere/skills.git ~/.codex/sphere-workflow
mkdir -p ~/.agents/skills
rm -f ~/.agents/skills/sphere-workflow
ln -s ~/.codex/sphere-workflow/skills ~/.agents/skills/sphere-workflow

Restart Codex after creating or updating the symlink.

Verify:

ls -la ~/.agents/skills/sphere-workflow

Detailed docs: docs/README.codex.md

OpenCode

Quick install:

Tell OpenCode:

Fetch and follow instructions from https://raw.githubusercontent.com/go-sphere/skills/refs/heads/master/.opencode/INSTALL.md

Manual install:

git clone https://github.com/go-sphere/skills.git ~/.config/opencode/sphere-workflow
mkdir -p ~/.config/opencode/plugins ~/.config/opencode/skills
rm -f ~/.config/opencode/plugins/sphere-workflow.js
rm -rf ~/.config/opencode/skills/sphere-workflow
ln -s ~/.config/opencode/sphere-workflow/.opencode/plugins/sphere-workflow.js ~/.config/opencode/plugins/sphere-workflow.js
ln -s ~/.config/opencode/sphere-workflow/skills ~/.config/opencode/skills/sphere-workflow

Restart OpenCode after creating or updating the symlinks.

Verify:

ls -l ~/.config/opencode/plugins/sphere-workflow.js
ls -l ~/.config/opencode/skills/sphere-workflow

Detailed docs: docs/README.opencode.md

Workflow Map

The plugin is meant to move work through the go-sphere lifecycle in order.

Interactive requirement interview & alignment
  -> interview-me
Scattered inputs / kickoff
  -> project-intake
PRD / product framing
  -> prd
Prototype behavior / UX semantics
  -> ux-analyst
Implementation-ready specification
  -> spec-writer
Changed spec impact analysis
  -> spec-diff-pipeline
Schema design
  -> db-schema-designer
Ent schema implementation
  -> ent-schema-implementer
Seed / fixture SQL
  -> ent-seed-sql-generator
Proto + HTTP contract design
  -> proto-api-generator
Generated service skeletons
  -> proto-service-generator
Cross-layer scaffold implementation
  -> sphere-feature-workflow
Frontend pages and routes
  -> frontend-crud-generator
Layout upgrade, drift, or legacy adoption
  -> sphere-layout-sync
protoc-gen-* plugin authoring and review
  -> protoc-plugin-engineering
Go test review, repair, and authoring
  -> go-test-engineering
Go API documentation and verified usage examples for agents
  -> godoc
Go code leanness audit and safe simplification
  -> go-simplify
Migrating a non-Go codebase to Go
  -> migrate-to-golang
Makefile and Make-driven CI standardization
  -> go-sphere-makefiles
One headless task for another coding agent
  -> delegate
Several live coding agents in Rex tabs
  -> rex-desktop

The bootstrap rule is simple:

• If the user explicitly names a skill, use it.
• If the task spans multiple stages, start at the earliest missing artifact.
• If the task touches proto, schema, service, or generation boundaries, route into sphere-feature-workflow.
• If the task is about updating a project to a newer layout revision, route into sphere-layout-sync.
• If the task is about the protoc-gen-* plugins themselves rather than the .proto files they consume, route into protoc-plugin-engineering.
• If the task is auditing or simplifying existing Go code for over-design, over-optimization, or over-defensive checks rather than adding a feature, route into go-simplify.
• If the task is migrating or porting a codebase in another language to Go, route into migrate-to-golang.
• After a stage skill finishes, honor the handoff in its ## Related Skills block before starting a new classification pass.

Bundled Skills

Discovery and Requirements

• interview-me deeply interviews the user through a decision tree until reaching shared technical and product consensus.
• project-intake organizes rough inputs into a structured kickoff document.
• prd turns agreed direction into a high-quality PRD.
• ux-analyst translates demos and mockups into behavioral UX flows.

Specification and Planning

• spec-writer produces implementation-ready specifications.
• spec-diff-pipeline traces downstream impact after spec changes.

Data and Contract Design

• db-schema-designer designs review-ready schemas before coding.
• ent-schema-implementer converts approved designs into Ent schema files.
• ent-seed-sql-generator creates deterministic seed SQL for development and test.
• proto-api-generator designs scaffold-safe proto3 + HTTP contracts.
• proto-service-generator generates or completes service skeletons.

Implementation and Surfaces

• sphere-feature-workflow handles end-to-end scaffold feature delivery.
• frontend-crud-generator generates admin pages and route registration from a sphere-generated TypeScript swagger client, following the project's own framework conventions.

Layout and Toolchain Maintenance

• sphere-layout-sync updates a generated project to a newer layout revision, resolves layout drift, and adopts pre-contract projects into the .sphere/layout.lock.json model.
• protoc-plugin-engineering covers authoring, refactoring, and reviewing the protoc-gen-* plugins themselves, including config immutability, read-only templates, output determinism, and golden-file discipline.

Quality and Verification

• godoc writes self-contained Go API comments and verified usage examples so consumers and AI agents can get started through go doc.
• go-test-engineering audits, repairs, and writes behavior-focused Go tests, reusable interface contract suites, and justified golden tests.
• migrate-to-golang migrates a legacy or foreign-language codebase to idiomatic Go on the latest stable release, proving behavior parity with a differential A/B harness and recording telemetry, benchmarks, Go PGO results, and an HTML infographic.
• go-simplify audits Go code for over-design, over-optimization, and over-defensive checks, then applies behavior-neutral cleanups against a green test baseline while never breaking the exported API.
• go-sphere-makefiles standardizes common Make targets, root batch orchestration, and Make-driven CI without flattening multi-module, generator, or layout-specific behavior.

Agent Orchestration

• delegate runs one task headless in claude, codex, kimi, agy, or pi, returns a structured result, resumes the session, and owns every agent-specific flag and executable lookup.
• rex-desktop coordinates several live agents as workers in Rex tabs: spawn, wait until done, follow up, and verify. It launches agents through delegate.

Legacy Direct Install

The repository still works as a direct skill source for compatibility:

# Install a single skill
npx skills add https://github.com/go-sphere/skills --skill db-schema-designer

# Install multiple skills
npx skills add https://github.com/go-sphere/skills \
  --skill db-schema-designer \
  --skill ent-schema-implementer \
  --skill proto-api-generator \
  --skill sphere-feature-workflow

# Install all bundled skills
npx skills add https://github.com/go-sphere/skills

You can also invoke a specific skill directly after installation, for example:

Use the proto-api-generator skill to generate API definitions

Default CLAUDE.md

CLAUDE.TEMPLATE.md is a starting CLAUDE.md for a go-sphere project: general coding-behavior guidelines plus go-sphere conventions. Copy it to the project root as CLAUDE.md (or AGENTS.md) and fill in the project-specific section.

Updating

Codex

cd ~/.codex/sphere-workflow && git pull

OpenCode

cd ~/.config/opencode/sphere-workflow && git pull

Claude Code / Cursor Local Plugin

cd /path/to/your/sphere-workflow-clone && git pull

Direct Skill Install

Re-run your npx skills add ... command when you want to refresh the installed skills from this repository.

Uninstalling

Codex

rm ~/.agents/skills/sphere-workflow
rm -rf ~/.codex/sphere-workflow

OpenCode

rm ~/.config/opencode/plugins/sphere-workflow.js
rm -rf ~/.config/opencode/skills/sphere-workflow
rm -rf ~/.config/opencode/sphere-workflow

Claude Code Local Plugin

Remove the local plugin or local marketplace registration that points at this repository clone, then delete the clone if you no longer need it.

Cursor Local Plugin

Remove the local Cursor plugin registration that points at this repository clone, then delete the clone if you no longer need it.

Troubleshooting

Codex cannot see the plugin

• Verify ~/.agents/skills/sphere-workflow exists and points to the cloned skills/ directory.
• Restart Codex after creating or updating the symlink.
• Check that skills/using-sphere-workflow/SKILL.md exists in the clone.

OpenCode plugin does not load

• Verify ~/.config/opencode/plugins/sphere-workflow.js points to .opencode/plugins/sphere-workflow.js.
• Verify ~/.config/opencode/skills/sphere-workflow points to the cloned skills/ directory.
• Restart OpenCode after creating or updating the symlinks.

Claude Code does not inject the bootstrap

• Verify .claude-plugin/plugin.json exists in the clone.
• Verify .claude-plugin/marketplace.json exists in the clone if you use a local marketplace flow.
• Verify the repository is registered as a local plugin root.
• Check that hooks/hooks.json and hooks/session-start are present in the clone.
• Confirm the plugin root still points at the same repository checkout.

Cursor does not inject the bootstrap

• Verify .cursor-plugin/plugin.json exists in the clone.
• Verify the repository is registered as a local Cursor plugin root.
• Check that hooks/hooks.json and hooks/session-start are present in the clone.
• Confirm the plugin root still points at the same repository checkout.

I still want a single skill directly

Use the compatibility install path with npx skills add https://github.com/go-sphere/skills and install only the skills you need.

Tech Stack

• Backend framework: go-sphere
• ORM: ent (Bun in the bun layout)
• Protocol: Protocol Buffers (proto3)
• Frontend: Vue 3 + Element Plus (pure-admin-thin); the frontend generator follows whatever framework a project actually uses
• Code generation: protoc-gen-sphere, protoc-gen-sphere-binding, protoc-gen-sphere-errors, and protoc-gen-route (Telegram layout only)
• Project layouts: standard, simple, bun, telegram — created by sphere-cli create --layout, each carrying .sphere/layout.json ownership rules

Progressive Loading

Every bundled skill is written for staged disclosure, so an agent reads only what the current decision needs:

• The description is the only part always in context. It stays under 400 characters and names the neighbouring skill it should not be used for.
• SKILL.md stays under 150 lines: inputs, a numbered path, the reference map, the rules, and the output contract.
• Detail lives in references/*.md, each under 200 lines and each introduced exactly once, in that skill's ## Reference Map table, with the condition that makes it worth reading.

tests/run-tests.sh enforces these budgets, and fails when a reference file is orphaned from its skill's Reference Map.

Authoring and Documentation

• references/skill-authoring.md — the authoring contract for skills in this repository: size budgets, description formula, section order, and the plain-language rules that keep skills readable for smaller models.
• references/dev.md — the AI-agent collaboration workflow guide (indexed, with per-stage chapters under references/dev/).
• references/prompt.md — per-round prompt templates (indexed, with chapters under references/prompt/).

Contributing

Issues and pull requests are welcome. The plugin shell lives beside the bundled skills, so changes may affect both platform adapters and the skills themselves. Run bash tests/run-tests.sh before opening a pull request.

License

MIT