convez.ai
Agente
mvagnon

plan-based-agentic-workflow

mvagnon/plan-based-agentic-workflow

Ver no GitHub
InicialPluginScore · de 0 a 100

The agentic framework for actual engineers.

Instalação

$npx convez-ai mvagnon/plan-based-agentic-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
0
Acompanhando
0
Saúde
28%
Último commit
há 1 semana
Versão
—
Issues abertas
0
Contribuidores
2

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, and gh CLI (+ 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 run review-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-diagrams skill:
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

  • brainstorm can ask targeted clarification questions. It does not write code, create PM tasks, open PRs, or mutate external systems.
  • feed-pm proposes 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-pm can proceed directly with implementation only through references/direct-implementation.md, without creating or updating PM tasks, creating a branch, invoking implement-pm, creating a PR, launching review-pr, or entering the fix-pr loop.
  • implement-pm must 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-pr creates draft PRs with PM task links in the PR body, comments linked PM tasks with PR URLs, then runs review-pr.
  • review-pr does not implement fixes and cannot merge or close PM tasks without passing local CI and explicit approval.
  • fix-pr does 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.

Ver o original no GitHub

Bom para

Relacionados