convez.ai
SkillAutomaçãoIntermediário
jsiovn

Agent Workflow Template

jsiovn/workflow-template

Workflow planner→executor para agentes de IA coding com Beads e skills compartilhadas

Ver no GitHub
InicialPluginScore · de 0 a 100

Scaffold que instala um workflow planner→executor consistente para agentes de IA em codificação (Claude Code e Codex) em qualquer repositório. Fornece skills compartilhadas, subagents e rastreamento de tarefas via Beads, permitindo que Claude execute o mesmo playbook em todos os projetos.

Instalação

$npx convez-ai jsiovn/workflow-template

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
3
Forks
0
Acompanhando
0
Saúde
42%
Último commit
há 6 dias
Versão
v1.4.1
Issues abertas
0
Contribuidores
2

Casos de uso

  • Standardizar fluxo de trabalho de agentes IA em múltiplos repositórios
  • Gerenciar tarefas e PRs com rastreamento Beads integrado
  • Compartilhar skills e agents entre projetos de forma consistente

Veredito

Ferramenta especializada para equipes que usam Claude Code/Codex em escala, automatizando setup e padronizando fluxos. Curva de aprendizado moderada (requer Beads, Dolt, Python), mas retorno alto para workflows de multi-repositório.

README

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

Agent Workflow Template

A scaffold that installs a consistent planner → executor workflow for AI coding agents into any repo — a shared set of skills, subagents, and Beads-backed task tracking so that Claude Code (the primary AI) follows the same playbook in every project, with Codex as an optional opt-in. You plan once, execute one bead per PR, and ship.

This repo runs nothing itself — it's developer tooling for AI coding agents, not a CI/CD or GitHub Actions "workflow." You install it once on your machine, then run one script per project to scaffold (or refresh) the workflow inside that project.


Preinstall

You need three machine-wide tools before bootstrapping any project:

ToolWhat forVerify
bdBeads CLI (issue tracking)bd version
doltStorage backend used by bddolt version
python3Template's scaffold scripts (run from the template checkout, not downstream)python3 --version

Per-OS install instructions:

To verify everything is in place in one shot:

bash ./scripts/posix/check-prereqs.sh
# Windows:
pwsh -File .\scripts\windows\check-prereqs.ps1

How to install

1. Clone this template to a stable path on your machine

git clone https://github.com/jsiovn/workflow-template.git ~/www/workflow-template

Pick any path you like — just keep it stable, because your shell aliases (next section) and downstream update-skills invocations will point at it.

2. Bootstrap a project

Run this once per repo you want to use the workflow in:

bash ~/www/workflow-template/scripts/posix/bootstrap-new-repo.sh /path/to/your-repo myprefix

Windows:

pwsh -File "$HOME\www\workflow-template\scripts\windows\bootstrap-new-repo.ps1" -RepoPath D:\path\to\repo -Prefix myprefix

myprefix is the short tag Beads uses for issue IDs in that repo (e.g. acme → acme-1, acme-2). The bootstrap script initializes git if needed, runs bd init and bd setup claude (and bd setup codex only with --with-codex), and copies the shared skills and agents into the project — Claude Code's .claude/ surface always, and Codex's .codex/ surface only when you opt in via --with-codex.

Claude Code is the default, primary AI. To also set up Codex, add --with-codex (POSIX) or -WithCodex (PowerShell), which scaffolds the .codex/ skills+agents and the AGENTS.md instruction file alongside the Claude surface. The flag is accepted by both bootstrap-new-repo and update-skills (so you can adopt Codex later). If a .codex/ directory already exists in the downstream, it is detected and refreshed automatically.

For web/UI projects, add --with-screenshots (POSIX) or -WithScreenshots (PowerShell) to also install the attach-web-screenshots skill and its companion .github/workflows/cleanup-screenshots.yml. Omit for backend, CLI, or library repos. The flag is also accepted by update-skills if you adopt screenshots later.

3. Refresh later

When this template gets updates, refresh any downstream repo with:

bash ~/www/workflow-template/scripts/posix/update-skills.sh /path/to/your-repo

For a guided walkthrough of a brand-new project, see docs/SETUP-NEW-REPO.md.


How to setup aliases

Typing the full path every time is annoying. Add aliases to your shell:

bash / zsh (~/.bashrc or ~/.zshrc):

alias w-bootstrap='bash ~/www/workflow-template/scripts/posix/bootstrap-new-repo.sh'
alias w-update='bash ~/www/workflow-template/scripts/posix/update-skills.sh'

PowerShell ($PROFILE):

function w-bootstrap { pwsh -File "$HOME\www\workflow-template\scripts\windows\bootstrap-new-repo.ps1" @args }
function w-update    { pwsh -File "$HOME\www\workflow-template\scripts\windows\update-skills.ps1" @args }

Reload the shell, then:

w-bootstrap /path/to/your-repo myprefix
w-update    /path/to/your-repo

How to use skills and agents

Once a repo is bootstrapped, your AI tool — Claude Code by default, or Codex if you opted in with --with-codex — sees two kinds of building blocks:

  • Skills — runnable workflows. You invoke a skill by name (e.g. plan-beads, executor-task) and the model executes the whole workflow end-to-end.
  • Agents — focused single-purpose roles (PM, architect, reviewer, …). You invoke an agent when you want that specific perspective on the current work.

The two flows you'll run most often

Planning — turn an idea into Beads tasks:

plan-beads → brainstorming → (planner-research, optional) → beads-planner → validate-beads

Execution — pick up one bead, ship one PR:

executor-task                # default: PR into main
executor-task-worktree       # same, in an isolated worktree (parallel-safe)
executor-epic-task           # bead belongs to an epic — PR into the epic branch
executor-epic-sequential <epic-id>   # run a WHOLE epic on one branch, fresh session per bead, one PR
executor-rework-in-place <bead-id>   # bead was reopened, amend the existing PR

Other useful skills you'll reach for:

  • address-pr-comments — when a reviewer left comments on your PR
  • finishing-a-development-branch — push and open the PR
  • audit-backlog-rules — re-check the backlog after editing project rules
  • requesting-code-review — get a review of the current change before merging

Full skills catalog

SkillWhat it doesWhen to use
plan-beadsFull planner-only session: brainstorm → confirm → create beads → stopYou have a problem and want to convert it into Beads tasks
brainstormingExplores user intent, requirements, and design before any codingBefore any creative work — required by plan-beads and good as a standalone
planner-researchResolves factual unknowns after brainstormingOnly when uncertainty would weaken the plan
beads-plannerTurns a settled plan into Beads epics + tasks with explicit dependenciesAfter brainstorming/research, when ready to materialize the plan
validate-beadsQuality-gates an epic (size, contracts, fresh-session safety)After beads-planner, before claiming any of its beads for execution
writing-plansProduces a per-bead execution plan with explicit ## VerificationInside an executor session, after a bead is claimed — never in a planner session
audit-backlog-rulesAudits ready/blocked beads for drift after CLAUDE.md or AGENTS.md rules changeRight after editing project rules / conventions
SkillWhat it doesWhen to use
beads-claimFinds and claims a ready bead at the start of an executor sessionStart of an executor session
executor-taskFull cycle for one bead on a fresh feat/<bead-id> branch off main + opens a PR into mainOne-bead-per-PR delivery rhythm
executor-task-worktreeSame as executor-task but runs in an isolated git worktreeWhen you need to run multiple beads in parallel without branch interference
executor-epic-taskSame as executor-task but branches off (and PRs into) the bead's parent epic branchEpic delivered as one merge to main; each child bead ships as its own PR into the epic
executor-epic-task-worktreeSame as executor-epic-task but runs in an isolated git worktreeEpic flow + parallel beads + main tree must stay untouched
executor-epic-sequentialRuns every ready bead of one epic sequentially on a single epic/<epic-bead-id> branch — each bead in a fresh headless claude -p session (clean context per task); blocked beads are skipped; ends with one PR to the default branchDeliver a whole epic unattended as one branch + one PR, instead of one bead at a time
executor-rework-in-placeRe-execute a reopened bead on the current feature branch; push commits into the existing open PR (no new branch, no new PR); requires bead_idBead was already executed but the task was wrong — user reopened the bead, updated its requirements, and wants to amend the existing PR
beads-closeCloses the bead, creates follow-ups, commits .beads/ stateFinal step of an executor cycle
SkillWhat it doesWhen to use
systematic-debuggingStructured root-cause investigation before proposing a fixAny bug, test failure, or unexpected behavior
verification-before-completionForces real verification commands before claiming "done"Before committing, opening a PR, or asserting success
build-and-testRuns the literal ## Verification section of the current execution planAfter implementing changes; specialize per repo in stage 2
SkillWhat it doesWhen to use
requesting-code-reviewDispatches the code-reviewer subagent against the current changeAfter implementing a major task, before merging
address-pr-commentsPulls unresolved PR threads → fixes via pr-comment-fixer → verifies → push → replyWhen new review comments arrive on the current PR
attach-web-screenshotsTakes screenshots of a running web app and attaches them to the open PRAfter implementing a UI feature, before or alongside review
finishing-a-development-branchPushes the branch and opens a PRWhen all work on a feature branch is done and verified

attach-web-screenshots is opt-in — pass --with-screenshots to bootstrap-new-repo (or update-skills to adopt later). It ships a companion CI workflow (.github/workflows/cleanup-screenshots.yml) that prunes stale screenshot folders for merged branches.

SkillWhat it doesWhen to use
project-auditorFull-repo audit: naming, folder layout, tech-stack consistency, light architectureProject health check (not per-PR — use requesting-code-review for diffs)
prune-local-branchesRemoves stale local branches whose PRs are merged or closedPeriodic cleanup
AgentWhat it doesWhen to use
product-managerProduces acceptance criteria + done checklistEarly planning, when "done" is fuzzy
engineering-managerCritically reviews the PM's spec for feasibility, scope creep, hidden costRight after product-manager, before engineering commits
solution-designHigh-level solution design — components, contracts, data flow, alternativesAfter acceptance criteria are pinned, before implementation plan
junior-engineerAsks clarifying questions until nothing is ambiguous; returns a numbered listBefore starting work on cross-cutting / under-specified tasks
backend-architectReviews plans + diffs for backend work against opinionated standardsPlan touches APIs, services, persistence, queues, jobs
frontend-architectReviews plans + diffs for frontend work against opinionated standardsPlan touches UI, components, styling, client state
testing-strategistProduces the test list required to ship a plan/diff with confidenceAfter a plan is settled, before coding — or before opening a PR
AgentWhat it doesCalled by
code-reviewerReviews a completed change against its plan/requirements, reports by severityrequesting-code-review
project-auditorFull-repo audit (naming, folders, tech stack, architecture hotspots, dead code)project-auditor skill
pr-comment-fixerReads unresolved PR threads, applies fixes, returns reply plan (does not push/post)address-pr-comments

For the internal "who calls whom" graph view of the skills, see docs/SKILLS_RELATIONSHIPS.md.


Browse beads visually with bdtui

bdtui screenshot

bdtui is a terminal UI for browsing the Beads backlog — ready vs. blocked beads, dependencies, status, the lot. Install once:

npm install -g bdtui

Then run bdtui from inside any bootstrapped repo.


Command reference

PurposePOSIXWindows
Bootstrap a new downstream reposcripts/posix/bootstrap-new-repo.sh <repo> <prefix> [--with-codex]scripts/windows/bootstrap-new-repo.ps1 [-WithCodex]
Refresh shared workflow surfacescripts/posix/update-skills.sh <repo> [--with-codex]scripts/windows/update-skills.ps1 [-WithCodex]
Prerequisite checkscripts/posix/check-prereqs.shscripts/windows/check-prereqs.ps1

More docs


Attribution

The bundled execution-quality skills are curated copies derived from obra/superpowers, adapted to a Beads-native planning/execution flow with selected ideas from GSD and Khuym. See ATTRIBUTION.md.

Ver o original no GitHub

Bom para

Relacionados