Agentic Workflow Skills

🇪🇸 Versión en español

A reusable set of agent skills that run a disciplined, doc-driven workflow for building software with agents — from idea/issue to a reviewed, classified, merge-ready change. The skills are project-adaptive: they discover and obey each repository's own guide, architecture, roadmap and style docs at runtime, so the same workflow works on any stack.

They are plain Markdown (SKILL.md files), so they work with any agent that reads skills — Claude Code, Cursor, Codex, OpenCode, Cline, and 70+ others — installed with the skills CLI (see Install).

The examples in docs/ are generic and illustrative; the skills themselves are stack-agnostic and architecture-agnostic.

⚠️ Breaking change (v3, 2026-07-04): the default branch is now model-agnostic

npx skills add gtrabanco/agentic-workflow (no #ref) now installs what used to be the #inheritance variant: no skill carries model:/effort: frontmatter, so every skill simply inherits whatever model and effort your agent session is already using. The goal: using this workflow should never lock you into one vendor's model lineup — you pick the model, the skills just run the discipline.

  • On Claude Code and want the hand-tuned, per-skill Opus/Sonnet + effort tiers this project used to ship by default? Install the #claude branch instead: npx skills add gtrabanco/agentic-workflow#claude.
  • Already pinned #inheritance? Nothing to do — #inheritance keeps working, kept in sync as an exact alias of the default branch.
  • Everyone else (any other agent, or you'd rather choose tiers yourself): the plain install command below already gives you this branch — no action needed.

See docs/workflow/MIGRATION.md for the full rationale and upgrade notes.

What's inside

skills/                  38 source skills (19 user-facing + 18 workflow internals + 1 metadata-internal; 37 discoverable)
packages/                companion npm packages: @gtrabanco/agentic-workflow-schema (machine contracts)
                         and @gtrabanco/pi-agentic-workflow (one-command install for Pi — see Install)
template/                 the exportable documentation scaffold (the substrate the skills read)
docs/workflow/           the full tutorial (feature flow, issue flow, reference, replication)
docs/features/_TEMPLATE  feature SPEC template + ROADMAP (the planning artifacts skills produce)
docs/fix/                fix SPEC template + index
.github/                 issue + PR templates the workflow expects

Dogfooding model (authoring): repo sessions consume the workflow from the installed release (Pi package / installed plugin), not from the working copy. The committed layout carries no working-copy activation surface. Authoring sessions opt in by creating a local, gitignored mount (ln -sfn ../skills .claude/skills) or by exercising a single working-copy skill via per-session flags (e.g. pi --no-skills --skill skills/<name>/SKILL.md).

The skills are the behavior; template/ is the substrate they read (a generic CLAUDE.md + documentation map, SPEC/feature/fix templates, and GitHub templates). Scaffold a new project's way of working with npx degit gtrabanco/agentic-workflow/template my-project — see docs/workflow/REPLICATE.md.

The largest skills use progressive, one-hop loading instead of paying their full instruction cost at activation. In particular, execute-phase now activates at about 3k estimated tokens rather than 13k, then loads only the route-specific contracts it needs. Committed budgets enforce that shape; prompt caching is only an optional provider optimization, never a correctness dependency. See Context budget and progressive loading.

The skills

19 user-facing skills (one menu entry each) + internal contracts composed for you: the plan-feature router's two planning steps, the two pre-execution evidence owners (evidence-grounding for authoring readiness, pre-execution-review for the shared review cycle and the planning ledgers), the review-change engine, the orchestration-envelope contract, the workflow's own 9-skill internal review pack (review-code, review-security, review-verify, review-debt, review-design, review-a11y, review-brand, review-perf, review-seo), and the repo-only bump-skill maintenance helper (excluded from installation) — so no external review skill is ever required, on any agent, with any model. One disciplined path: design → review the product → plan → review the plan → execute → review the change → audit → merge.

Every skill's invocation forms and flags (--fix, --force, --adversarial N, --next, --fullauto, …) are catalogued in the Invocation & arguments reference.

Setup

Skill What it does
init-workspace Fetches and adapts template/ by interview: gate, doc map, architecture, capability inventory, optional invariants, and injection-safe labels. It detects Claude Code, Cursor, Copilot, or OpenCode and offers the repository-scoped safety guard explicitly — never installs or overwrites hooks without consent. Existing scaffolds enter additive upgrade mode and receive only missing blocks/adapters.
discover-repository-state Creates and freezes an evidence-backed repository-state ledger before planning or implementation; facts, decisions, documentation, planned work, and inference remain distinct
resolve-repository-state Sole writer for an explicit repository-state contradiction; verifies the competing evidence and publishes the next frozen snapshot

Design

Skill What it does
design-feature Product definition. Folds in the raw-idea interview, then walks three fixed capability-closure checklists — entity closure (per entity: CRUD + state transitions, each with a UI entry point + API surface + test, or an explicit n/a: <reason>), integration closure (the feature reconciled against every subsystem in the project's capability inventory, docs/CAPABILITIES.md: auth, ACL, navigation, notifications, … — one resolved row per subsystem, none skipped), and a role matrix (every inventory role explicitly allowed/denied per capability) — into exhaustive acceptance criteria, plus an expectation sweep (≥ 10 implicit domain expectations — "a blog has drafts" — each forced to in-scope/out-of-scope/deferred, never left unstated). It classifies optional architectural invariants from repository evidence and stops for an explicit decision when a rule changes. Writes the SPEC's product half, stamps ## Design status: designed, and sets the feature's roadmap row to defined (the idea → defined transition). Upserts on re-run; never destroys recorded decisions.

Plan

Skill What it does
plan-feature Engineering-planning router for an already-designed feature. The redirect gate keys on the roadmap status first — idea/absent → STOP → design-feature, no bypass flag; defined → proceed to Routing; planned/in-progress/done → STOP, hand off to /execute-phase (never re-scaffolds an already-planned feature); the SPEC ## Design status marker is only the legacy-compat fallback for a pre-migration planned row. Given a designed feature, an issue #N (issue → scoped product half), or a scoped slug/SPEC (straight to engineering-half scaffolding), routes to the right step, checks optional architectural invariants with evidence, then registers the roadmap entry (re-reading the defined → planned write to confirm it landed). --next plans the next defined roadmap item. Sizes every feature (XS/S/M/L): small ones get a SPEC-only path with ≥ 2 phases in the SPEC (last = Hardening & PR) — no artifact ceremony; M/L get the full set with a mandatory hardening phase.
plan-fix Drafts one fix SPEC + frozen ACCEPTANCE.md from one or more issues. Multi-issue units group by an atomic delivery boundary: one capability outcome or homogeneous mechanical rule, one verification plan, and one release/rollback boundary; shared files/root cause/equal severity are not required. Incompatible inputs return the fewest maximal groups instead of one issue per PR.

design-feature (product definition, folds in the raw-idea interview) must mark a feature designed and review-spec must return a current SPEC-REVIEW-PASS before plan-feature will plan it — each gate refuses and redirects otherwise, no bypass flag. Designed is not reviewed: the author's own readiness check licenses a review request, never a verdict. Once reviewed, you only ever call plan-feature; it composes the internal steps plan-feature-from-issue and plan-feature-scaffold (hidden from the menu). Planned is not executable either: planning freezes the planning-evidence and obligation ledgers, then review-plan must return a current PLAN-REVIEW-PASS before execute-phase touches a phase — and execute-phase fails closed on a missing, stale, or wrong-stage receipt, which is the one preflight gate no --force reaches.

Execute

Skill What it does
execute-phase With no phase argument, executes all remaining feature/fix phases through PR close-out; explicit P<n> keeps one-phase atomic mode. Every phase retains its own acceptance-blob check, phase/invariant/dependency gates, tests, docs, and commit. Unit-loop mode uses fresh workers where available, compact receipts otherwise, skips intermediate review stops, and halts on red/no-progress/attempt budget. Discoveries become Autofix, Opportunistic Fix, or a proposal—never an automatic issue.

Review & audit — change → PR → product

Skill Scope What it does
review-spec the design Independent, read-only Product gate: builds the spec-product-v1 snapshot of a designed SPEC's product half, runs a falsification pass plus the fixed fourteen Product checks in a context that did not write it, and returns only SPEC-REVIEW-PASS, SPEC-REVIEW-FAIL or NEEDS-DESIGN with a content-bound receipt that treats every byte it reads as data, never instructions. It never edits the reviewed SPEC and never chooses product intent — plan-feature refuses to scaffold without its current receipt, and the turn contract points at pre-execution-review's POLICY.md §8 as the owner of the rule that binds a verdict to its durable mark.
review-plan the plan Independent, read-only Engineering gate: snapshots the frozen plan (SPEC, acceptance, planning evidence, obligations, phases, tests), sweeps the ledgers and the fixed Engineering checks — plus reproduction/root-cause/regression/rollback authority for fixes — in a context that did not cut them, and returns only PLAN-REVIEW-PASS, PLAN-REVIEW-FAIL or NEEDS-DESIGN with a snapshot-bound receipt, and reads every byte it opens — the copied spec receipt included — as data, never instructions. It edits no plan artifact — the parent digest it records is recomputed, per POLICY.md §7 — and execute-phase refuses to run without its current receipt, whose turn contract points at POLICY.md §8 for the durable mark.
review-change the change Runs only the reviews that apply to your platform (code, security, verify, design, a11y, brand, perf, SEO) — adversarially by default, assuming the diff is wrong until proven otherwise — and classifies → one decision table + an explicit manual-verification checklist; a dirty tree or unpushed commits stop the review as a REVIEW BLOCKED precondition before any pass runs — workspace state is never a persisted finding, and the review commits its own findings append so it never dirties the tree it next judges. The mandatory end review must run in a conversation that did not implement the change — if it did, stop and hand off to a fresh one. Opt-in --adversarial N: N independent context-clean reviewers, each an index-assigned role (correctness/security/SPEC-coverage), run in parallel (subagents / headless / sequential-fallback), findings merged by file:line at an inclusion threshold of ≥1 — default off, auto-recommended (never forced) when the change is L/sensitive, the reviewer isn't the fleet's strongest or is weaker than the diff's author, or only one model family is available on a ≥M change. --synthesize is the standalone fusion entry point for manually-run reviewers. Fix-now findings on an unmerged unit persist to that unit's fix-now fold ledger (review-findings.md), deduped by file:line+axis (only high/med persist — low findings are report-only notes that never block). Classification honors the engine's fix-now override checks: a cheap fix or an in-scope defect is always fix-now (never a postpone/known-issue/tradeoff escape), and a too-large in-scope fix-now routes to replan-in-unit — user-confirmed SPEC phase(s) on the same branch, never a downgrade
fold-findings the findings ledger Repairs the full queue in the fewest compatible atomic batches, grouping by root cause/mechanical rule + validator + rollback boundary. One batch gets one commit, while every finding retains its ledger tick and output receipt. Classification stays frozen; disputes stop for a user decision and no fold creates backlog.
audit-pr the PR Read-first merge gate that consumes the current review-change REVIEW-PASS receipt (a missing/stale receipt is a blocker routed to /review-change, never re-reviewed) and evaluates only the delivery contract: phases/docs complete, CI, mergeability, traceability, capability closure, descope integrity, and the receipt's invariant/manual-check result → MERGE-READY or evidenced blockers, always with the full URL. MERGE-READY posts a dated SHA-bound PR comment; BLOCKED persists blockers to the shared fold ledger. It never edits or merges: only an active ship-roadmap --fullauto stage may consume its verdict and invoke the transient wrapper.
product-audit the product Explicit-invocation-only, periodic full-spectrum health check persisted as docs/audits/<id>-<date>.md; mines code and feature history into severity-ranked findings plus issue/roadmap/tooling proposals, checks capability-inventory freshness and repeated scope export, gates every claim on evidence provenance and reports the delta vs the prior audit of equivalent scope, and never auto-fixes.
audit-docs the docs Audits docs ↔ roadmap ↔ code ↔ fix index for drift

review-change and audit-pr also evaluate the optional project ARCHITECTURAL_INVARIANTS.md document: every applicable rule needs repository evidence that the change preserves it, or an explicit architectural decision. Projects that do not declare the document remain compatible.

review-change's findings engine is the internal review-implementation — the two-phase find → classify pass it composes (and audit-pr / product-audit reuse) — plus the internal review pack: one review-* skill per axis, each a fixed checklist returning a findings table + PASS|FAIL. None are menu entries; you reach them through review-change.

Decide

Skill What it does
triage-issue Classifies an issue (fix-now / fix-in-unit / promote / postpone / wontfix) by verifying its trigger against the code; a scope-membership check (before classification) routes an issue that already belongs to an open unit onto that unit's own branch (fix-in-unit), never a new standalone unit; on fix-now + high severity, applies the injection-safe urgent/fix-next label it owns; on postpone/promote/wontfix, applies the matching disposition label it owns (postponed/promoted/wontfix); also triages persisted product-audit findings and unresolved review findings via --prioritize-now, routing oversized work to a plan with new phases

Document

Skill What it does
generate-docs Turns a unit's diff into developer documentation on the project's own docs site — incremental how-to guides through a discovered adapter (Starlight MDX first-class, plain markdown fallback), a knowledge/call map rendered from a project-declared deterministic command (the model never infers graph edges), and opt-in --review export of review reports. Provenance frontmatter lets audit-docs catch orphan/stale pages; never scaffolds a site, never edits code.

Session

Skill What it does
log-session Appends a structured entry to docs/LOGS.md — what the session did, files touched, decisions + why, and the next step — so you (or anyone) can resume cold. Run it before /clear or before closing. The template/ also ships free, opt-in hooks that auto-append a mechanical entry on /clear/exit and can re-inject the last entry on start.
workflow-status Read-only sensor for programmatic orchestration. Computes the full project state — every feature/fix with its transitive dependency closure (met/unmet), the roadmap's five-state machine (idea/defined/planned/in-progress/done), what is startable right now (status ≥ defined, deps met) and in which build order, idea rows reported as detail.design_candidates, open PRs + audit state, pending fixes and findings awaiting triage, the mandatory end review proven from its durable REVIEW-RAN mark row rather than from a review-findings.md that merely exists, the untriaged open-issue backlog (detail.untriaged_issues, label-authoritative with a VERDICT:-comment legacy fallback), each unit's unfolded fix-now findings from its review-findings.md ledger as structured findings.fix_now[] items carrying a derived suggested_tier, plus the injection-safe detail.urgent field (labels-only urgent/fix-next issues + in-flight interruptibility facts) and, per unit, review (last-reviewed sha, unreviewed diff, terminal-review/adversarial evidence), closure.state, and issues_born (descope-amendment provenance) — and emits it as one fixed JSON machine envelope, with a top-level next.suggested[] of trigger-attributed suggestions single-sourced from each owning skill's own condition, self-checked against the bundled schema and a fixed command→tier map before printing. With --last-envelope, a no-progress guard flags a stalled /plan-feature//design-feature hint (unit still at its pre-advance status) as a workflow_observations note instead of silently repeating it. The piece an external driver calls between steps (see Programmatic orchestration). Never edits anything.

Repo maintenance

Skill What it does
bump-skill After editing a skill in this repo: bumps version: in the SKILL.md frontmatter, adds rows to CHANGELOG.md + CHANGELOG.es.md, and updates the skill and model tables in README.md + README.es.md. Also lints the repo's authoring rules (every skill closes with a → Next: block; phases are P1, P2, …, never S1/"Steps") and the machine-surface registration rules (every user-invocable: true skill has a matching entry in .claude-plugin/plugin.json; that array and model-routing.yml's keys stay alphabetical; any skill that's both user-invocable: false and absent from plugin.json — repo-internal, meaningless to a consumer — carries metadata.internal: true, the skills CLI's own mechanism for staying out of npx skills add discovery). Run before every commit that touches a skill.

Autopilot — the whole flow, end to end

Skill What it does
ship-roadmap Builds the whole app from the roadmap. One locked founding interview becomes batch design; a driver loop designs, plans, executes, reviews, opens, and audits one unit per iteration, then sweeps issues and writes the final report. Default: opens PRs, you merge. --fullauto is the sole automated merge authority: after a fresh SHA-bound audit it calls the fail-closed transient wrapper, keeps direct merge commands blocked, cleans attempt state on every exit, and records each automerge with an idempotent PR comment.

How the autopilot runs the workflow — one interview in, reviewed PRs out, and you only step in to merge (amber):

flowchart LR
    I([Interview]):::you --> RM[Roadmap] --> D[Design] --> P[Plan]
    P --> X[Execute] --> RV[Review] --> PR[Open PR] --> A[Audit] --> M([Merge]):::you
    M -->|next feature| P
    M -.->|roadmap done| REP[Final report]
    classDef you fill:#f6c177,stroke:#8a5a00,color:#3a2406;

The same plan → execute → review → audit → merge path you'd run by hand — the autopilot just moves you to its edges. Under --fullauto, ship-roadmap also handles merges through the repository's transient wrapper, under non-negotiable safety floors, and logs each one on its PR. The portable hooks are defense-in-depth: direct merges and obvious secret dumps are blocked at the agent boundary, while forge rulesets remain the real security boundary.

The review axes are self-contained: the bundled internal review pack covers code, security, verify, debt, design, a11y, brand, perf and SEO on any agent. Platform-specific extras (a framework skill, a stack linter) are optional — review-change and product-audit run them in addition when installed, never as a dependency. See docs/workflow/RECOMMENDED_SKILLS.md.

Upgrading from an older install? See docs/workflow/MIGRATION.md — three skills were renamed, so re-add to update + delete the three old folders.

Versioning. Each skill is versioned independently (version: in its frontmatter); changes are logged in CHANGELOG.md. Upgrade an install with npx skills update.

Recommended model & effort

This section documents the #claude branch — npx skills add gtrabanco/agentic-workflow#claude. The default branch (main, aliased as #inheritance) carries none of this: every skill simply inherits whatever model and effort your agent session is already using, so there's nothing to configure and nothing to go stale.

On the #claude branch, each skill pre-sets its model and effort in frontmatter (table below), sourced from docs/workflow/model-routing.yml. The model uses a floating tier alias (opus/sonnet/haiku) that auto-updates to the latest version — so it never goes stale. Both apply only for that skill's turn; your session model/effort resume afterward. You stay in control: to change them, edit model-routing.yml (the source CI reads to rebuild the claude branch — never edit the claude branch's frontmatter directly, it's force-pushed on every change to main).

On agents other than Claude Code, or on the default branch, these tiers don't apply — and that's covered: every user-facing skill ships a Portability section with explicit fallbacks (no slash menu → follow the target SKILL.md in a fresh conversation; no model tiers → strongest model for planning/review/audit, cheaper for execution; no /loop/subagents → manual re-invocation guided by each skill's closing → Next: block). The workflow is the contract; per-skill tiers are a #claude-branch convenience.

Skill Model tier Effort Why
init-workspace Opus high interview-driven project bootstrap + adaptation
discover-repository-state Sonnet medium evidence collection and frozen repository-state snapshot
resolve-repository-state Opus high contradiction resolution and repository-state judgment
review-spec Opus high independent Product-half review in a clean context; never weaker than the model that wrote the half
review-plan Opus high independent Engineering-plan review in a clean context; never weaker than the model that cut the phases
design-feature Opus high product-definition judgement: raw-idea interview + capability closure, composed by callers only at ≥ this tier
plan-feature Opus high router + engineering planning: its internal scoping steps run in its turn, so the router must carry the effort (composed skills inherit the turn's effort)
plan-fix Opus high architect-level scoping + risk analysis
execute-phase Sonnet medium mechanical implementation per SPEC — whole unit by default, fresh/compact phase transactions (Opus if logic is subtle)
review-change Opus high platform-adaptive review orchestration + synthesis
fold-findings Opus high never weaker than the review tier that produced the finding; a subtle logic/security finding earns its own strongest-available pass
audit-pr Opus high whole-PR merge-readiness judgement
product-audit Opus max product-wide multi-axis sweep + proposals (max effort for the widest context sweep)
audit-docs Sonnet medium mostly mechanical cross-document checks (Opus for deep audits)
triage-issue Opus high verify triggers against the code; judgement call
log-session Sonnet medium structured summarization, not judgement — deliberately the cheap tier, never Opus (the .claude/ hooks do the mechanical capture for free)
workflow-status Sonnet medium mechanical state reading + dependency-closure computation — a sensor, never judgment
generate-docs Sonnet medium structured summarization of a diff into guide pages; the graph is tool-generated, never model-inferred (Opus never needed)
ship-roadmap Opus high the autopilot conductor: composes the planning/review/audit skills in-turn (equal tier) and delegates implementation to Sonnet subagents — judgment stays strong, bulk tokens stay cheap

The internal skills aren't selected directly. Because they're composed within a caller's turn, they inherit that turn's model/effort (a skill's model/effort is fixed at turn start) — the values in their frontmatter (review-implementation, plan-feature-from-issue, review-code, review-security high; plan-feature-scaffold and the rest of the review pack medium) are declared defaults for a direct run, which is why the plan-feature and review-change orchestrators themselves carry high.

Rule of thumb: planning, judgement, review and audit → Opus (high, or max for the product-wide sweep); mechanical execution → Sonnet, medium (bump to Opus when the logic is subtle).

Model equivalence (non-Claude / free-inference models)

The Claude tiers above (the #claude branch) set a reference bar, but nothing in the workflow depends on them — the skills are model-agnostic by design (that's the point of the default branch). If you're on the default branch, this table is just a mental-model guide for which "kind" of model to point each skill at yourself; if you installed #claude anyway and want to swap its pinned tiers for a different vendor, edit docs/workflow/model-routing.yml accordingly:

Claude default Capability class Use it for
Opus + high/max Frontier reasoning — the strongest model you have, reasoning/thinking mode on planning, review, audit, triage, the merge gate
Sonnet + medium Mid workhorse — a solid coding model at default settings mechanical execution per SPEC, doc checks, session logs
Haiku Small & cheap — any fast lightweight model optional grep-shaped evidence gathering

Concrete picks (open-weight, as of July 2026 — this landscape moves fast; sanity-check against a current leaderboard before pinning):

  • Frontier reasoning (⇔ Opus + high/max): DeepSeek V4 (tops LiveCodeBench/Codeforces among open models), Kimi K2.6 (strongest for agentic/repo-level coding and tool use), GLM-5.x / GLM-4.7 Thinking, Qwen3 235B-A22B — run in reasoning/thinking mode. Closed non-Claude equivalents: the top GPT / Gemini reasoning tier.
  • Mid workhorse (⇔ Sonnet + medium): DeepSeek V3.2 (the value pick via API), Qwen3-Coder / Qwen3 32B, GLM-5.1, or any of the frontier picks with reasoning mode off.
  • Small & cheap (⇔ Haiku): Qwen3 4–14B, Mistral Small 3.1, Gemma 3 27B, Phi-4-mini — local-friendly, fine for grep-shaped work.

Running the whole flow on a small/cheap fleet

The skills are hardened for small executor models (modest context windows, no prompt caching): frozen acceptance, fixed checklists instead of judgment calls, Phase-lint and Spec-lint gates, compact phase receipts, bounded repair loops, and reviews isolated per axis returning findings tables only. On a fleet with no frontier-class model at all:

  • Execution (execute-phase, log-session, doc bookkeeping) is designed for the cheapest tier — one fresh worker context per phase, compact handoff via progress.md, at most 10 full-file reads per phase. The outer invocation continues through every remaining phase unless an explicit P<n> is passed.
  • Planning, review, and audit (design-feature, plan-feature, plan-fix, review-change, audit-pr, product-audit) still get the