convez.ai
InicialPluginScore · de 0 a 100

Engineering methodology skills for Claude Code agents — planning, TDD, diagnosis, architecture

Instalação

$npx convez-ai ninthhousestudios/vidhi

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
0
Forks
0
Acompanhando
1
Saúde
42%
Último commit
há 1 mês
Versão
—
Issues abertas
0
Contribuidores
1

README

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

vidhi

Engineering methodology skills for Claude Code agents. Forked from mattpocock/engineering and adapted for the manas ecosystem.

Skills

Grounding

SkillPurpose
vidhi-initBootstrap project context docs (domain, issue-tracker, triage-labels)
vidhi-domainEstablish/refine CONTEXT.md and ADRs — domain vocabulary
vidhi-surveyBig-picture assessment of current state
vidhi-sutra-seedSeed sutra governance for a greenfield repo from its PRD — rules.toml + enforcement ledger
vidhi-sutra-adoptAdopt an existing codebase into sutra's conventions and constraints system
vidhi-sutra-tendCheckpoint maintenance for a governed repo — fire triggers, catch drift, constrain emergent structure

Design

SkillPurpose
vidhi-brainstormCollaborative design exploration — structured dialogue to turn ideas into designs
vidhi-prdSynthesize conversation context into a PRD (user stories, modules, test strategy)

Planning

SkillPurpose
vidhi-decomposePRD → vertical slices, published to yojana with status and planning tags
vidhi-premortemStress-test a decomposition before implementation — coverage, integration, timeline risks
vidhi-planPer-task implementation planning — file map, step sequence, code sketches → yojana implementation_plan

Execution

SkillPurpose
vidhi-implementYojana-aware dispatcher — pulls task, follows plan if present, selects method, reports back
vidhi-tddRed-green-refactor loop (standalone or called by vidhi-implement)
vidhi-diagnoseBug investigation — hypothesize, isolate, confirm
vidhi-deepenRefactoring and structural improvement

Verification

SkillPurpose
vidhi-reviewPer-task code review against acceptance criteria — inline, codex, or brief mode
vidhi-release-reviewMulti-pass project review at release or checkpoint — pack + parallel subagents + synthesis

Usage

vidhi provides the methodology (opinions about how to plan and execute). yojana provides the grammar (task schema, state machine, dependencies, context shapes). sutra provides code intelligence (impact analysis, hotspots, dead code).

Full pipeline: idea → shipped feature

vidhi-brainstorm      → explore the design space, one question at a time
  ↓
vidhi-domain          → sharpen vocabulary, update CONTEXT.md (optional — skip if domain is clear)
  ↓
vidhi-prd             → capture the design as a PRD
  ↓
vidhi-sutra-seed      → (greenfield repos) seed constraints + enforcement ledger from the PRD
  ↓
vidhi-decompose       → break PRD into yojana tasks with dependencies and planning tags
  ↓
vidhi-premortem       → stress-test the decomposition for gaps and risks
  ↓
[per wave of unblocked tasks]
  vidhi-plan          → plan tasks tagged needs-plan (skip for simple tasks)
  vidhi-implement     → execute with TDD/diagnose/architecture, report back
  vidhi-review        → review completed tasks

Not every project needs every step. Small features can skip brainstorm and go straight to PRD. Bug fixes can skip everything and go straight to vidhi-diagnose. Use judgment.

Sutra governance lifecycle

Three skills keep a codebase's architecture machine-enforced through sutra, one per lifecycle moment:

SkillMomentInput → Output
vidhi-sutra-seedbirth — PRD exists, no codePRD claims → rules.toml + enforcement ledger + CLAUDE.md invariants, guard on from first commit
vidhi-sutra-adoptadoption — code exists, no governanceimport graph + doc archaeology → reviewed rules.toml
vidhi-sutra-tendcheckpoint — code and governance both existledger vs. actual graph → deltas: fire deferred triggers, catch drift, constrain emergent structure, triage conventions

The connective tissue is the enforcement ledger (docs/enforcement-ledger.md in the governed repo): every architectural claim in the PRD routed to exactly one enforcement mechanism — live sutra constraint, deferred constraint with a binding trigger, CLAUDE.md invariant, or test assertion — so silent non-enforcement is impossible. Seed creates it; tend maintains it; adopt can backfill one.

How they hook into the pipeline:

  • seed runs between vidhi-prd and vidhi-decompose. Constraints whose paths the PRD fixes go live immediately; the rest are deferred with named triggers. Binding verification ("every glob matches ≥1 real file") is handed to the scaffold task as machine-checkable acceptance criteria.
  • decompose marks which review checkpoints are tend moments (see its step 5) and keeps deferred-constraint triggers pointing at real tasks.
  • tend runs at those checkpoints — especially the first one, when module interiors exist for the first time and FCA has data for the initial convention triage. It appends deltas, never regenerates: rules derived from a drifted graph would bless the drift.
  • review (vidhi-review / vidhi-release-review) treats the ledger's not-expressible-in-sutra invariants as checklist items; per-task enforcement of live constraints is the sutra guard's job, in real time.

New track PRDs landing on a governed repo re-run seed additively — append constraints with their own provenance, never regenerate.

Planning in waves

Don't plan all tasks upfront. Plan and implement in waves following the dependency graph:

  1. After decompose + premortem, plan the first batch of unblocked needs-plan tasks
  2. Implement them (simple tasks without needs-plan go straight to implement)
  3. Plan the next batch — now informed by what you learned implementing the first wave
  4. Repeat until done

Plans also serve as session bookmarks. If a task spans sessions, the plan tracks which steps are complete so the next session picks up where you left off.

Executing tasks

yojana_ready project="my-project"    → find next unblocked task
vidhi-implement project/N            → pull context, execute with TDD/diagnose/architecture, report back

Or standalone (no yojana):

vidhi-tdd                            → ad-hoc TDD on whatever you're building
vidhi-diagnose                       → investigate a bug without a tracked task

Reviewing code

vidhi has two review skills for different scopes.

Per-task review (vidhi-review)

Review code changes for one or more yojana tasks. Checks the diff against the task's acceptance criteria, project invariants, and blast radius from sutra.

vidhi-review chitta/32                           → inline review (claude, default)
vidhi-review chitta/32 --reviewer codex          → dispatch to codex
vidhi-review chitta/32 --reviewer brief          → produce review brief for any external model
vidhi-review chitta/32 chitta/33                 → review multiple related tasks together

Reviewers:

ReviewerWhat happens
claude (default)Reviews inline in the current session. Produces findings in conversation, updates yojana.
codexCalls codex companion script directly with task context as focus text. Records codex output on the yojana task.
briefWrites a self-contained directory to /tmp/review-brief-<project>-<date>/ with instructions, task context, diff, impact analysis, and project context. Feed it to any model.

Diff resolution (automatic, in priority order):

  1. git:commit context refs on the task(s) — uses recorded SHAs
  2. User-specified range — vidhi-review chitta/32 --range main..feature
  3. Asks if neither is available

Outputs:

  • Findings in YAML schema (same as vidhi-release-review — interchangeable)
  • Verdict: approve / approve with notes / request changes
  • Yojana comment on the task with verdict and summary
  • Follow-up tasks filed for new work surfaced during review (with user confirmation)

Release review (vidhi-release-review)

Full project audit at release or checkpoint moments. Builds a review pack with code intelligence, runs two parallel subagent passes (architecture + code review), and synthesizes findings into an action plan.

vidhi-release-review                             → review current project at HEAD
vidhi-release-review --scope wm-1..wm-12         → review a specific commit range

Process:

  1. Verify project state (clean working tree, confirm scope with user)
  2. Build review pack at /tmp/review-pack-<project>-<date>/
    • 00-meta.md — scope, versions, review type
    • 10-context/ — README, CLAUDE.md, CONTEXT.md, ADRs, manifests
    • 20-code-intel/SUMMARY.md — curated hotspots, file health, filtered dead code (from sutra)
    • 30-verification/SUMMARY.md — build, test, lint, format results
  3. Curate code-intel SUMMARY (don't dump raw sutra JSON — reviewer attention is the constraint)
  4. Run verification (language-appropriate build/test/lint/fmt)
  5. Launch two parallel subagents:
    • Architecture pass — vidhi-deepen skill, produces deepening candidates
    • Code review pass — reviewer-prompt.md, produces findings with YAML schema
  6. Synthesize both reviews into a single action plan with fix-order waves
  7. Triage findings to yojana (with user confirmation)

Outputs (three files in docs/reviews/):

  • <date>-<scope>-architecture.md — architecture pass
  • <date>-<scope>-review.md — code review pass
  • <date>-<scope>.md — synthesis (read this first)

Checkpoint mode: for mid-upgrade reviews, substitute the verdict with continue as planned / continue with adjustments / pause and address issues.

Multi-model support: the review pack and reviewer prompt are model-agnostic. Hand the pack directory + reviewer-prompt.md to codex, opencode, gemini, or any model. The synthesis step reconciles N reviews instead of 2.

Choosing between review skills

SituationSkill
Just finished a task, want to check correctnessvidhi-review
Reviewing 2-3 related tasks togethervidhi-review (multi-task)
Want a second opinion from codex on a taskvidhi-review --reviewer codex
About to tag a releasevidhi-release-review
Mid-upgrade checkpointvidhi-release-review (checkpoint mode)
Handing project to external reviewersvidhi-release-review (pack is the handoff)
Forward-looking refactor planningvidhi-deepen (not a review skill)

Finding schema

Both review skills use the same YAML finding format, so findings are interchangeable and can be reconciled across reviewers:

- id: <stable-slug>
  severity: critical | high | medium | low
  category: correctness | contract | design | slop | performance
  title: <one line>
  location: <file:line | file | "project-wide">
  evidence: |
    <what's there now>
  why: |
    <why it matters>
  recommendation: |
    <one approach>
  confidence: high | medium | low

Severity:

LevelMeaningBlocks merge?
CriticalBreaks correctness, loses data, violates securityYes
HighWill cause production problems or hurt the next person hereYes
MediumReal issue, bounded blast radiusNo — fix soon
LowCleanup, naming, styleNo — batch into follow-up

Installation

Add each skill directory to your Claude Code slash commands, or reference them via the skill index in ~/.claude/skill-index.md.

License

MIT — see LICENSE. Originally by Matt Pocock; adapted by Josh Harper.

Ver o original no GitHub

Bom para

Relacionados