Skip to content

Instantly share code, notes, and snippets.

@robertDouglass

robertDouglass/SKILL.md

Created February 26, 2026 17:24
Show Gist options

  • Select an option

    Learn more about clone URLs
  • Save robertDouglass/c10ec58c27ef8925d9073f3cd92b3cbb to your computer and use it in GitHub Desktop.

Select an option

Learn more about clone URLs
Save robertDouglass/c10ec58c27ef8925d9073f3cd92b3cbb to your computer and use it in GitHub Desktop.
Download ZIP
spec-kitty-cli-orchestration skill
Raw
SKILL.md
name description
spec-kitty-cli-orchestration
Orchestrate SpecKitty workflows across Claude CLI, OpenCode, and Codex with slash-command-first execution, reviewer-only feedback loops, retry/backoff handling, and deterministic phase gates (specify→plan→tasks→implement→review→accept→merge).

Spec Kitty CLI Orchestration

Overview

Use this skill when you need to drive SpecKitty through external CLIs (Claude/OpenCode) while keeping Codex in reviewer-control mode. The goal is predictable throughput: slash commands first, clear gates, no direct implementer edits by the orchestrator.

When To Use

  • User asks to orchestrate Claude/OpenCode for SpecKitty execution.
  • Work spans multiple repos and must be advanced in parallel through specify, plan, and tasks.
  • You must review artifacts and provide change requests instead of editing implementation outputs directly.
  • API instability (timeouts/500s) requires resilient retries and log-backed failure diagnosis.

Core Rules

  1. Slash-command first.
  2. Orchestrator is reviewer-only for implementer artifacts.
  3. Keep a decision log for each clarification answered during generation.
  4. Treat phase completion as gated: do not start implementation until tasks artifacts are valid.
  5. For 2.x initiatives, enforce 2.x-only scope and block 1.x feature additions.

Preflight Checklist

  1. Confirm command templates exist (.claude/commands/spec-kitty.*.md or agent equivalent).
  2. Run /spec-kitty.status to determine current feature and lane state.
  3. Check branch constraints before specify (some repos require main).
  4. Confirm dashboard endpoint and open it (/spec-kitty.dashboard or spec-kitty dashboard).
  5. Confirm working tree cleanliness expectations (document any unrelated dirty files before proceeding).

Execution Workflow

1) Specify

  • Send a prompt beginning with /spec-kitty.specify.
  • Include complete team prompt scope inline.
  • If external file reads are sandbox-blocked (OpenCode), inline all requirements and explicitly forbid external reads.
  • Capture clarification Q&A as explicit decisions.

2) Plan

  • Run /spec-kitty.plan after spec exists.
  • Verify plan is not template-only.
  • Review for mission/audit policy alignment and event/materialization constraints.

3) Tasks

  • Run /spec-kitty.tasks.
  • Validate all expected WP prompt files exist under tasks/.
  • Run spec-kitty agent tasks status and confirm total WP count matches tasks.md.

4) Implement + Review (loop)

  • Use /spec-kitty.implement and /spec-kitty.review per WP.
  • Do not directly patch implementer output yourself.
  • Feed back findings as concrete, file-targeted change requests.
  • Re-run until acceptance checks are green.

5) Accept + Merge

  • Run /spec-kitty.accept then /spec-kitty.merge.
  • Confirm post-merge events/artifacts and metadata updates are emitted when policy enables audit.

Reviewer-Only Feedback Format

Use this exact structure when sending implementer corrections:

  • Finding: short severity + issue summary.
  • Evidence: file path and exact contradiction/defect.
  • Required change: unambiguous instruction.
  • Acceptance check: command/assertion that proves fix.

Parallelization Pattern

  • Safe to parallelize across repos for specify→plan→tasks.
  • Keep one active session per repo and poll independently.
  • Pause parallelism when repos become dependency-coupled for implementation.

Failure Handling

  • 500 api_error (Claude/OpenCode backend): retry with backoff and model fallback.
  • Long silent runs: treat as hung after threshold, terminate, restart with narrower scope.
  • OpenCode external-directory denial: remove path references and inline requirements.
  • Branch gate failures (specify requires main): switch workflow or pre-create feature on allowed branch intentionally.

Use script: scripts/run_cli_with_backoff.sh

Testing & Completion Gates

Before declaring done:

  1. All targeted features have non-empty spec.md, plan.md, and complete tasks/WP*.md.
  2. Implemented WPs pass repo tests and static checks.
  3. Decisions captured from clarifications are persisted in docs/artifacts.
  4. Version pin matrix updated across repos.
  5. SaaS redeploy executed and verified (health, process groups, logs).

Deployment Gate (SaaS)

Use runbook commands:

  • fly deploy --config fly.dev.toml
  • fly deploy --config fly.prod.toml
  • Verify:
    • fly status --config <config>
    • fly logs --config <config>
    • curl https://<app>.fly.dev/health/

Resources

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment