convez.ai
SkillAutomaçãoAvançado
Wave-Engineering

claudecode-workflow

Wave-Engineering/claudecode-workflow

Ambiente Claude Code portável com automação de epics e CI integrado

Ver no GitHub
InicialPluginScore · de 0 a 100

Ambiente portável de desenvolvimento Claude Code com skills, scripts e template CLAUDE.md pronto para usar. Inclui automação autônoma de epics (KAHUNA), detecção de plataforma GitHub/GitLab e integração de ferramentas de CI/code-review sem configuração manual.

Instalação

$npx convez-ai Wave-Engineering/claudecode-workflow

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
1
Forks
1
Acompanhando
0
Saúde
50%
Último commit
há 3 dias
Versão
v8.24.0
Issues abertas
86
Contribuidores
2

Casos de uso

  • Configurar ambiente de desenvolvimento consistente para múltiplos agentes Claude
  • Automatizar merge de epics multi-issue com KAHUNA em CI/CD
  • Padronizar instruções de projeto (CLAUDE.md) entre repos GitHub e GitLab

Veredito

Solução robusta para quem usa Claude Code em fluxos de desenvolvimento escaláveis. KAHUNA é inovador para automação de epics, mas requer domínio de CI/CD e Git. Bem documentado, mas direcionado a equipes, não iniciantes.

README

A tradução para o português deste README ainda está na fila.

claudecode-workflow

Portable Claude Code workflow environment — skills, scripts, settings, and a drop-in CLAUDE.md template.

This repo packages the custom skills, utility scripts, and project instructions that make up a consistent Claude Code development environment. Clone it, run the installer, and you're set up on any machine.

Documentation

GuideDescription
Getting Started15-minute walkthrough of your first session
ConceptsHow the pieces fit together
Skill ReferenceDetailed docs for every skill
Cheat SheetOne-page skill + MCP tool quick reference
KAHUNA GuideRun /wavemachine autonomously on multi-issue epics
Discord SetupBot token, watcher, inter-agent messaging
Statusline IndicatorsPer-session indicator interface for skills and scripts
TroubleshootingCommon issues and fixes
New Agent OrientationDay-1 context for AI agents joining the fleet

Install via Claude Code

Paste this into a Claude Code session and watch the magic happen:

Fetch https://raw.githubusercontent.com/Wave-Engineering/claudecode-workflow/main/docs/seed-ai-install.md and follow every step in that document. It will walk you through cloning the repo, installing dependencies, running the installer, and verifying success. Execute each step — do not summarize or skip.

That's it. Your agent handles environment detection, platform-specific dependency installation, corporate proxy workarounds, and verification — all from one prompt.

Quick Start (manual)

One-liner install (no clone needed):

curl -fsSL https://raw.githubusercontent.com/Wave-Engineering/claudecode-workflow/main/scripts/install-remote.sh | bash

Or clone and install locally:

git clone https://github.com/Wave-Engineering/claudecode-workflow.git
cd claudecode-workflow
./install.sh

New here? Start with Getting Started, then Concepts.

KAHUNA

KAHUNA is a per-epic integration-branch pattern that lets /wavemachine ship a whole multi-issue epic to main in one autonomous run. Flights merge into a short-lived kahuna/<epic-id>-<slug> branch (CI-gated, no human review); a four-signal trust score (commutativity, CI, code-reviewer, trivy) gates the single kahuna→main MR/PR. Main's existing protection, required reviews, and merge rules are unchanged.

See the KAHUNA Guide for usage and the Dev Spec for architecture and rationale.

What's Included

CLAUDE.md Template

A drop-in project instructions file that works with both GitHub and GitLab projects. Auto-detects the platform from git remote -v and adapts terminology and CLI commands accordingly.

Key features:

  • Platform detection — GitHub (gh) vs GitLab (glab), auto-detected
  • Discovery-based code standards — finds the project's linters, formatters, and test runners instead of assuming a stack
  • Pre-commit checklist — enforced review protocol with mandatory verification steps
  • Agent identity system — Dev-Team (persisted per-project) + Dev-Name/Dev-Avatar (ephemeral per-session)
  • Secrets guardrail — warns before staging sensitive files, confirms with user before proceeding
  • PR/MR description format — consistent structure for pull/merge requests

Skills

SkillCommandWhat it does
assesswaves/assesswavesQuick assessment of wave-pattern suitability
ccfold/ccfoldMerge upstream CLAUDE.md template updates into local project
ccwork/ccworkOnboarding hub — tour the kit, run labs, configure integrations
ddd/dddDomain-Driven Design facilitation — event storming, domain modeling, concept handoff
disc/discDiscord integration — check-in, send, read, list, resolve channels
dod/dodProject Definition of Done verification against the Deliverables Manifest
edit/editOpen file/URL in GUI editor
engage/engageLoad CLAUDE.md, confirm rules of engagement
ibm/ibmIssue-Branch-PR/MR workflow reminder
issue/issueCreate structured issues (feature, bug, chore, docs, epic) with templates and labels
jfail/jfailCI job/workflow failure analysis
man/manDisplay usage information for any installed skill
mmr/mmrMerge a PR/MR with squash
name/nameReport or pick agent session identity
nerf/nerfContext budget system — soft limits, doom modes, scope monitor
nextwave/nextwaveExecute parallel spec-driven sub-agents
ping/pingPost to #ai-dev Slack channel
pong/pongRead #ai-dev Slack channel
devspec/devspecInteractive Dev Spec creation with Deliverables Manifest and finalization checklist
precheck/precheckPre-commit gate — verify compliance, run code review, present checklist
prepwaves/prepwavesAnalyze issues and compute dependency waves
review/reviewCode review on staged/branch changes
scp/scpStage, commit, and push workflow
scpmr/scpmrStage, commit, push, and create PR/MR
scpmmr/scpmmrStage, commit, push, create PR/MR, and merge
view/viewOpen file/URL in GUI viewer (read-only)
vox/voxText-to-speech voice announcements for status updates and alerts

Scripts

ScriptDependenciesWhat it does
discord-botcurl, jq, Discord bot tokenDiscord REST API client — send, read, create channels, resolve names
discord-status-postpython3, Discord bot tokenPost/update wave-status embed in #wave-status Discord channel
slackbot-sendcurl, jq, Slack bot tokenSend Slack messages as a named Claude Code agent
job-fetchglab, python3Fetch GitLab CI job traces for analysis
file-openerxdg-open / openCross-platform file/URL opener for /view and /edit
voxaudio player (aplay/afplay/paplay/ffplay); provider of your choice (see vox --setup)Text-to-speech via user-supplied provider hook. Examples in scripts/vox-providers/; contract in that dir's README
statusline-command.shjq, gitCustom status line: git branch, dirty state, context window remaining, model
cc-inspectorpython3, mitmproxyContext window inspector — proxy + Flask UI for API payload capture
discord-lockflock, jqAdvisory lock for serializing Discord channel writes across agents
campaign-statuspython3SDLC campaign lifecycle CLI — stage tracking, gates, deferrals, and dashboard
sdlc-dashboardbrowserOrg-wide SDLC dashboard viewer — static Pages site with live state polling
generate-status-panelpython3Generate HTML status panel for wave progress
worktree-managergitManage isolated worktrees for parallel agent execution

MCP Servers

MCP servers are managed via mcps.json and installed from their own repos:

ServerRepoWhat it does
wtf-servermcp-server-wtfFlight recorder for incident troubleshooting
discord-watchermcp-server-discord-watcherDiscord channel notification server for inter-agent communication
nerf-servermcp-server-nerfDeterministic context budget management (nerf darts, modes, statusline)

Each MCP has its own install-remote.sh for standalone installation. Running ./install.sh installs all MCPs from the manifest automatically.

Settings Template

settings.template.json provides a starting point for ~/.claude/settings.json with:

  • Permissions — Granular tool allowlists for common CLIs (git, gh, glab, docker, terraform, aws, etc.)
  • Hooks — PreToolUse (push gate, secrets gate), PostToolUse (test sentinel, context tracker), PostCompact (re-read reminder)
  • Status line — Points to the custom statusline script
  • Plugins — Full plugin list (see Plugins section below)
  • Effort level — Set to high for thorough responses

Installation

Remote Install

Install everything from a GitHub Release without cloning the repo:

curl -fsSL https://raw.githubusercontent.com/Wave-Engineering/claudecode-workflow/main/scripts/install-remote.sh | bash

Options:

curl ... | bash -s -- --version v1.0.0   # Install a specific release
curl ... | bash -s -- --no-mcps           # Skip MCP server installation
curl ... | bash -s -- --check             # Verify installation status
curl ... | bash -s -- --uninstall         # Remove everything

This downloads the release tarball, installs skills, scripts, config, pre-built packages, and MCP servers -- the same result as cloning and running ./install.sh.

Full Install (from clone)

./install.sh

This will:

  • Copy skills to ~/.claude/skills/
  • Copy scripts to ~/.local/bin/
  • Install statusline to ~/.claude/statusline-command.sh
  • Smart-merge settings.template.json into ~/.claude/settings.json — missing hooks, plugins, and permissions are added while your existing customizations are preserved. If no settings file exists yet, the template is installed directly (with internal comment keys stripped).
  • Back up existing files before overwriting (.bak)
  • Skip unchanged files
  • Report missing dependencies

Options

./install.sh --dry-run     # Show what would be done
./install.sh --check       # Show drift between repo and installed versions
./install.sh --skills      # Install skills only
./install.sh --scripts     # Install scripts only
./install.sh --config      # Install config files only
./install.sh --mcps         # Install MCP servers only (via mcps.json manifest)
./install.sh --no-mcps      # Install everything except MCP servers
./install.sh --prune        # Remove installed files whose source no longer exists
./install.sh --prune --yes  # ...non-interactively

scripts/ is walked recursively: nested files like scripts/vox-providers/silent.sh are mirrored to ~/.local/bin/vox-providers/silent.sh with executable bits preserved. Subtrees named tests, fixtures, __pycache__, or .pytest_cache are excluded. --prune consults a manifest at ~/.local/bin/.cc-workflow-manifest (refreshed on every install) plus the current source set; orphans are backed up to <file>.bak before removal.

Check for Drift

After making local changes to skills or scripts, see what's out of sync:

./install.sh --check

This compares every installed file against the repo version and reports in sync, DIFFERS, or NOT INSTALLED. It also checks:

  • Settings — reports any hooks or plugins present in the template but missing from your local settings.json
  • MCPs — verifies that each MCP server from mcps.json is registered via claude mcp list

Sync Local Changes Back to Repo

When you've edited installed skills or scripts locally and want to capture those changes:

./sync.sh              # Interactive — prompt per changed file
./sync.sh --all        # Pull all changed files without prompting
./sync.sh --check      # Show drift summary only (no changes)

This is the reverse of install.sh — it copies local files into the repo working tree. After syncing, review the changes with git diff and commit through normal git workflow.

Uninstall

./uninstall.sh              # Remove everything
./uninstall.sh --dry-run    # Preview what would be removed
./uninstall.sh --skills     # Remove skills only
./uninstall.sh --scripts    # Remove scripts only

Settings and credentials are never removed by the uninstall script.

Using the CLAUDE.md Template

Copy CLAUDE.md into the root of any project:

cp /path/to/claudecode-workflow/CLAUDE.md /path/to/your-project/CLAUDE.md

On first session, Claude will:

  1. Detect the platform (GitHub/GitLab)
  2. Ask for the Dev-Team name (written into the file, only asked once)
  3. Pick a session identity (Dev-Name + Dev-Avatar)

No other configuration needed.

Plugins

The settings template enables these plugins from claude-plugins-official:

PluginPurpose
context7Up-to-date library documentation lookup
code-reviewStructured code review
githubGitHub integration
gitlabGitLab integration
feature-devGuided feature development
code-simplifierCode simplification and cleanup
commit-commandsGit commit workflow commands
pyright-lspPython language server
explanatory-output-styleEducational code explanations
claude-md-managementCLAUDE.md audit and improvement
claude-code-setupAutomation recommendations
slackSlack channel integration (MCP-based)
frontend-designFrontend interface design

MCP-Based Integrations

Some plugins provide MCP (Model Context Protocol) server integrations that require OAuth setup on first use:

PluginMCP CapabilitySetup
slackRead/write Slack channelsOAuth — prompted on first /pong or /ping use
gitlabGitLab API accessOAuth — prompted on first glab-based operation
githubGitHub API accessUses existing gh auth session

These authenticate automatically through Claude Code's OAuth flow. No manual token configuration is needed — just approve the OAuth prompt when it appears.

Exception: The slackbot-send script uses a separate bot token (not the MCP OAuth). See Slack Setup below.

Slack Setup (for /ping)

The /ping skill uses slackbot-send, which requires a Slack bot token:

mkdir -p ~/secrets
echo "xoxb-your-token" > ~/secrets/slack-bot-token
chmod 600 ~/secrets/slack-bot-token

This is separate from the Slack MCP plugin OAuth — slackbot-send posts as a custom bot identity (with Dev-Name and Dev-Avatar), while the MCP plugin uses your Slack user identity.

Discord Setup

The /disc skill and discord-watcher channel server require a Discord bot token and server (guild).

1. Bot Token

mkdir -p ~/secrets
echo "your-bot-token" > ~/secrets/discord-bot-token
chmod 600 ~/secrets/discord-bot-token

The bot needs these permissions in your Discord server:

  • Send Messages and Read Message History in target channels
  • Message Content Intent enabled in the Discord Developer Portal (Settings → Bot → Privileged Gateway Intents)

2. Discord-Watcher Channel Server

The discord-watcher is an MCP channel server that polls Discord and pushes real-time notifications into Claude Code sessions. It requires Bun.

# Install bun (if not already installed)
curl -fsSL https://bun.sh/install | bash

./install.sh installs MCP servers from the mcps.json manifest via each server's install-remote.sh. You can also install them individually:

curl -fsSL https://raw.githubusercontent.com/Wave-Engineering/mcp-server-discord-watcher/main/scripts/install-remote.sh | bash

3. Start with Channels

claude --dangerously-load-development-channels server:discord-watcher

Or set up an alias:

alias ccode='claude --dangerously-load-development-channels server:discord-watcher'

The watcher monitors all text channels on the configured Discord server. Messages are filtered by addressing — agents only receive notifications for messages containing @all, @<dev-team>, or @<dev-name>. Self-echoes are suppressed via signature matching.

Inter-Agent Communication

With the discord-watcher running in multiple Claude Code sessions, agents can talk to each other:

  • Address a specific team: @cc-workflow check the build status
  • Address a specific agent: @beacon what's your current task?
  • Address all agents: @all report your current status
  • Unaddressed messages are silently dropped (agents don't receive them)

Dev-Names must be kebab-case (e.g., beacon, null-pointer) so they work as routing keys for @ addressing.

Each agent signs messages with its Dev-Name signature (e.g., — **beacon** 📡 (cc-workflow)), which the watcher uses to filter self-echoes while allowing messages from other agents through.

Wave Status Channel

The discord-status-post script posts a rich embed to #wave-status whenever the wave state machine transitions. One message per project, edited in place — no spam.

The embed includes phase, wave, action, flight, a Unicode progress bar, and deferrals, with a color-coded sidebar that maps to the current action state. It's invoked automatically by wave-status after every state change (best-effort — skipped silently if not installed or Discord is unreachable).

STT Configuration:

  • STT_ENDPOINT — Whisper-compatible endpoint (default: http://archer:8300/v1/audio/transcriptions)
  • STT_MODEL — Model name (default: deepdml/faster-whisper-large-v3-turbo-ct2)

Verbose Mode

To bypass filtering and receive all messages (useful for monitoring/debugging):

DISCORD_WATCHER_VERBOSE=1 claude --dangerously-load-development-channels server:discord-watcher

Dependencies

ToolRequired byInstall
bundiscord-watcherbun.sh
ghGitHub skillscli.github.com
glabGitLab skillsgitlab.com/gitlab-org/cli
curlslackbot-send, discord-botUsually pre-installed
jqslackbot-send, discord-bot, statuslineapt install jq / brew install jq
python3job-fetchUsually pre-installed
shellcheckValidationapt install shellcheck / brew install shellcheck
shfmtValidationgo install mvdan.cc/sh/v3/cmd/shfmt@latest

Validation

./scripts/ci/validate.sh

Runs shellcheck, shfmt, and SKILL.md frontmatter validation. Also runs automatically on PRs via GitHub Actions.

License

MIT

Ver o original no GitHub

Bom para

Relacionados