plan-based-agentic-workflow
mvagnon/plan-based-agentic-workflow
The agentic framework for actual engineers.
Instalação
npx convez-ai mvagnon/plan-based-agentic-workflow1 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
README
A tradução para o português deste README ainda está na fila.
Plan-Based Agentic Workflow
Agent Skills for a decision-to-delivery workflow with short skills, Plan Mode-friendly user decisions, deterministic helper scripts, and technical references kept out of the main skill body.
PBAW treats the user as the product and architecture authority, and as an experienced software engineer/architect. Questions and proposed plans should stay technical at that level, with priority on UX and database/data-model decisions; other questions should stay focused on blockers.
Workflow
Primary PM-backed path:
flowchart TD
A([Request or technical decision]) --> B["$brainstorm in Plan Mode<br/>Clarify, research, recommend"]
B --> C["$feed-pm in Plan Mode<br/>Technical Roadmap + PM task previews"]
C --> D{"User approves?"}
D -->|Revise| C
D -->|Approve| E["Create or update PM tasks"]
E --> F["Clear or compact context"]
F --> G["$implement-pm<br/>Branch + implementation"]
G --> H["Clear or compact context"]
H --> I["$create-pr<br/>Draft PR + PM links/comments"]
I --> J["$review-pr<br/>Strict review + local CI"]
J --> K{"PROD READY?"}
K -->|No| L["$fix-pr<br/>Focused remediation + push"]
L --> J
K -->|Yes| M([User-approved merge/finalization])
Direct implementation path when PM tasks are unnecessary:
flowchart TD
A([Approved strategy or roadmap]) --> B["$feed-pm direct implementation path<br/>No PM task creation or update"]
B --> C["Implement on current branch/worktree<br/>No automatic branch creation"]
C --> D["Run relevant existing checks"]
D --> E["Review diff"]
E --> F([Report implementation result])
Skills
All PBAW skills are manual-only: each SKILL.md sets disable-model-invocation: true and user-invocable: true. This keeps the skills available for explicit user invocation while preventing accidental model invocation. The workflow is intentionally heavy: it can analyze repositories, research external sources, create or update PM tasks, create branches, open PRs, run CI, and push fixes, so it should start only when the user explicitly asks for a PBAW skill.
brainstorm: ask targeted questions, analyze the repository with Serena MCP, then research with Exa, Context7, andghCLI (+ Repomix) to resolve complex technical decisions before PM planning or direct implementation.feed-pm: analyze the repository with Serena MCP, retrieve cited PM task IDs or URLs when provided, propose a Technical Roadmap with per-task Mermaid flow previews, revise it when challenged, create new execution-ready PM tasks or overwrite cited tasks after explicit approval, then recap.implement-pm: requires PM system name and exact task IDs, runs the branch script first, retrieves PM tasks, and focuses only on implementation.create-pr: create draft PRs from{pm-tool}/{task-ids}branches, attach PM task URLs in PR bodies, comment linked PM tasks with PR URLs, report every PR URL, then runreview-pr.review-pr: perform a strict production-readiness review with mandatory full local CI, post details on the PR, and return only PR URLs in chat.fix-pr: collect PR feedback, inspect cited code, apply focused fixes directly, run checks, push, then reply to handled conversations.
Prerequisites
Required:
- Git, for obvious reasons.
- A coding agent that supports skills and, ideally, plan mode.
- Exa MCP for additional technical context.
- Context7 MCP for official dependency and framework documentation, in addition to Exa.
- gh CLI for GitHub PRs, issues, and external repository queries.
- Repomix MCP to gather context from actual GitHub repositories.
- Serena MCP for accurate codebase analysis in PM planning, implementation, PR review, and PR remediation.
Good to have:
- Any PM tool MCP or CLI if needed.
mermaid-diagramsskill:
npx skills add https://github.com/softaworks/agent-toolkit --skill mermaid-diagrams
Installation
Install this workflow:
npx skills add mvagnon/plan-based-agentic-workflow --skill '*'
Expected layout:
plan-based-agentic-workflow/
|-- .claude-plugin/
| `-- plugin.json
|-- README.md
|-- scripts/
| |-- discover-checks.sh
| |-- gh-pr-context.sh
| |-- gh-review-threads.sh
| |-- validate-skills.py
| `-- validate-skills.sh
`-- skills/
|-- brainstorm/
| |-- SKILL.md
| `-- references/
|-- feed-pm/
| |-- SKILL.md
| `-- references/
|-- implement-pm/
| |-- SKILL.md
| |-- references/
| `-- scripts/
| `-- create-pm-branch.sh
|-- create-pr/
| |-- SKILL.md
| `-- references/
|-- review-pr/
| |-- SKILL.md
| `-- references/
`-- fix-pr/
|-- SKILL.md
`-- references/
Validation
After editing skills, validate the skill shape and local references:
find scripts skills -type f -name '*.sh' -print0 | xargs -0 -n1 bash -n
scripts/validate-skills.sh
git diff --check
The validator checks frontmatter descriptions, manual invocation flags, required SKILL.md headings, Mermaid diagrams, fenced code blocks, and local files referenced from each ## References section.
Test Authoring Strategy
PBAW skills do not create new tests by default. This is intentional: tests written during small implementation tasks tend to target microscopic features and can create too many false positives.
When tests are needed, write them through the dedicated journey-test skill instead:
npx skills add mvagnon/skills --skill write-tests
That workflow favors tests for user journeys and product flows rather than fragile tests around narrow implementation details.
Safety Rules
brainstormcan ask targeted clarification questions. It does not write code, create PM tasks, open PRs, or mutate external systems.feed-pmproposes a complete Technical Roadmap first, preserves it when challenged, includes one task-local Mermaid flow with material edge cases per task, and creates new execution-ready PM tasks or overwrites cited source PM tasks only after explicit approval.feed-pmcan proceed directly with implementation only throughreferences/direct-implementation.md, without creating or updating PM tasks, creating a branch, invokingimplement-pm, creating a PR, launchingreview-pr, or entering thefix-prloop.implement-pmmust run the branch script before PM retrieval, Serena analysis, or edits.- The branch script creates or switches to the target branch and pushes it immediately. It does not stash, reset, or clean local work; inspect the worktree first when unrelated local changes matter.
create-prcreates draft PRs with PM task links in the PR body, comments linked PM tasks with PR URLs, then runsreview-pr.review-prdoes not implement fixes and cannot merge or close PM tasks without passing local CI and explicit approval.fix-prdoes not merge, mark PRs ready, close PM tasks, or update PM status.- No skill should add dependencies, logs, broad refactors, or new tests by default.
Technical References
References are bundled per skill and contain commands, templates, research mechanics, and PM/Git mechanics only. Repeated deterministic mechanics live in scripts/ so agents can run them without loading long command blocks into context. The main SKILL.md files define the human workflow and expected response format.
Repository-level authoring rules live in AGENTS.md.