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/                  the 29 skills (15 user-facing + 14 internal) — the installable source
.claude/skills           symlink → ../skills, so this repo dogfoods them in Claude Code
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

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 skills

15 user-facing skills (one menu entry each) + 14 internal ones composed for you: the plan-feature router's two planning steps, 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 — so no external review skill is ever required, on any agent, with any model. One disciplined path: design → plan → execute → review → 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 the template/ scaffold and adapts it to your project by interview (gate, doc map, architecture); seeds the capability inventory (docs/CAPABILITIES.md — roles + cross-cutting subsystems, proposed from what the code actually shows); suggests the companion review skills your platform needs; offers to install the skills; seeds the injection-safe urgent/fix-next labels. On a repo that already has the scaffold, detects it and switches to upgrade mode — diffs against the current template and proposes only the blocks you're missing (plus any missing urgency labels), never clobbering a tailored one

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). 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, 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 The fix-flow counterpart: architect-drafts a tightly-scoped fix SPEC from one or more issues (/plan-fix <n> [<n2> …] — multiple numbers merge into ONE unit only when a fixed shared-root-cause checklist ticks, else it refuses and prints the split) — always with a ## Phases ledger (≥ 2 phases, last = Hardening & PR) — commits on a fix branch, stops for review.

design-feature (product definition, folds in the raw-idea interview) must mark a feature designed before plan-feature will plan it — plan-feature refuses and redirects otherwise, no bypass flag. Once designed, you only ever call plan-feature; it composes the internal steps plan-feature-from-issue and plan-feature-scaffold (hidden from the menu).

Execute

Skill What it does
execute-phase Implements one phase per invocation — of a feature (default), of a small XS/S feature, or of a fix (--fix); XS/S and fix phases live in the SPEC's ## Phases (≥ 2 phases, the final one always Hardening & PR — the close-out chain in its own turn), and a legacy SPEC without ## Phases runs end-to-end in a single pass. Dependency gate first: the unit's transitive Depends on: closure must be merged, or it stops with the unmet chain and build order (--force overrides, logged); an own-status precondition then redirects a sub-planned unit (idea → /design-feature, defined → /plan-feature); a phase-lint pre-flight guard then runs the canonical 8-box atomicity checklist against the target phase, STOPping with a fixed block on any FAIL (--force overrides, logged). Tests-first on domain/orchestration work, never commits red, gate-verified, one commit per phase; recommends a review-change checkpoint on a trigger-based cadence — layer boundary, accumulation, or sensitivity (skippable) — and hands off once at the end (mandatory). Descope guard: before creating any issue, classifies it discovered-work (file freely) vs. descope (overlaps an unmet acceptance criterion/task) — a descope STOPs for a user-approved, dated ## Amendments entry before the issue may exist; an issue is never the first record of a descope. One phase = one session on non-frontier models (never two phases per conversation — the /loop batch shape already re-invokes per phase). A finished unit always opens its PR, prints the PR URL in the chat, and flips to done (built, not merged); no turn ends with a dirty tree, and once the PR exists every commit is pushed immediately.

Review & audit — change → PR → product

Skill Scope What it does
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 on the PR branch are fix-now workflow findings. 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. --merge 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. 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 each fix-now finding from review-change/audit-pr for real, one at a time — frozen classification (never reclassifies; a genuine objection produces DISPUTED → triage-issue) and a fixed forbidden list closing the known-issues-dump/severity-downgrade/test-loosening/lint-suppression/TODO-stub escape hatches, ending in a per-finding FOLDED | DISPUTED | BLOCKED | REPLAN verdict + tally (REPLAN hands a too-large in-scope finding off to user-confirmed SPEC phase(s) + execute-phase on the same branch). After an audit-pr BLOCKED verdict with a missing/incomplete ledger it reconstructs the rows from the verdict itself — never "no findings" while blockers are listed. execute-phase's embedded fold-cycle checklist remains the in-context/portability fallback
audit-pr the PR Merge gate: acceptance met, all phases done, docs/tests/CI green, Closes #N, review axes clean, closure integrity (a feature SPEC's ## Capability closure has zero blank rows; absent on a legacy SPEC → dated design-debt warning, not a blocker; n/a on fix PRs), scope integrity (descope) (an issue born during the unit that maps to an unmet acceptance criterion/task must have a matching, user-approved, dated ## Amendments entry — else BLOCKER; applies to feature and fix PRs alike; detected either by a slug/issue-number text match or by the issue being linked from an ## Amendments row, so a generic-titled descoped issue that is linked from an amendments row isn't invisible to the gate) → merge-ready or a list of blockers, always with the PR's full URL; on MERGE-READY it posts a dated, SHA-bound comment on the PR itself. A BLOCKED verdict persists every blocker to the unit's fix-now fold ledger (review-findings.md, severity high), the same ledger review-change writes. Opt-in auto-merge: with a documented policy it merges MERGE-READY PRs after a fail-closed cleanliness checklist (anything pending → push, wait for CI, re-audit)
product-audit the product Periodic full-spectrum health check, persisted as docs/audits/<id>-<date>.md (incremental audit id, findings numbered F1, F2, … → addressable later as triage-issue <id> F<k>); mines feature docs → proposes issues + roadmap add/remove (always present) + installed-tooling to register/re-design; checks capability-inventory freshness (docs/CAPABILITIES.md ↔ code drift); scope-export recurrence (≥ 2 consecutive units exporting scope via ## Amendments/descope issues → planning-quality finding routed to the atomicity/split rules) (never auto-fixes)
audit-docs the docs Audits docs ↔ roadmap ↔ code ↔ fix index for drift

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 (triage-issue <audit-id> F<k>), opening the issue only if the verdict warrants it

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 separately as design candidates, open PRs + audit state, pending fixes and findings awaiting triage, 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 upfront interview (product, features, stack, architecture — recommended proportionally, never defaulting to a named pattern — quality bars, ops, autonomy, budget) is batch design: founding writes feature rows at idea (the founding-scaffolded skeleton feature lands at planned), founds the project if needed, creates or adopts the complete roadmap, then a driver-fired build loop (/loop on Claude Code, an external orchestrator, or manual re-invocation — every iteration says why it ended) ships it feature by feature through the skills above — with no further questions; a mid-run idea unit gets a DESIGN stage that JIT-designs it strictly from the locked interview record (undesignable → parked, never re-asked). After the last feature it keeps going: an issue sweep inventories open issues plus the run's documented residue (known-issues, trade-offs, postponed findings), triages everything, and ships the fix-now issues through the same stages. SELECT checks the injection-safe urgent/fix-next labels first (fix-next → head of queue; urgent → runs ORCHESTRATION.md's pause-vs-finish judge against the in-flight unit). Default: opens PRs, you merge; --fullauto merges MERGE-READY PRs under non-negotiable safety floors. Ends with a final report: issues to open, discovered feature proposals, manual checks, product-audit cadence.

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 the merges, under non-negotiable safety floors.

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
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 — one phase per invocation (Opus if the 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): fixed checklists instead of judgment calls, the Phase-lint and Spec-lint presence gates, a fixed progress.md handoff schema with a fresh conversation per phase, per-phase/per-pass context budgets, 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 phase per conversation, handoff via progress.md, at most 10 full-file reads per phase.
  • Planning, review, and audit (design-feature, plan-feature, plan-fix, review-change, audit-pr, product-audit) still get the strongest model you have, even if that model isn't frontier-class — and never one weaker than the model that wrote the change.
  • Reviews: keep the per-axis isolation default (each pass a fresh context, table-only return) and prefer --adversarial 2 on L or sensitive changes — N cheap, decorrelated reviewers recover part of what a single small reviewer misses.
  • Split more. The mandatory-split rule (≤ ~5 phases, one layer per phase) is the main lever: smaller phases are what make cheap execution reliable. When in doubt, cut smaller.

Running on NaN.builders

NaN Cloud serves the open-weight frontier (full catalog: GLM-5.2 ~753B MoE · Mimo V2.5 310B · DeepSeek V4 Flash 284B · Qwen3.6 35B · Gemma4 26B) behind an OpenAI-compatible API (https://api.nan.builders/v1). Reasoning control is per-model, not a uniform dial — see the matrix below for how each model maps onto this workflow's effort: tiers. Sign up via this referral link.

Two profiles, not one primary. GLM-5.2 is no longer available on the basic plan — it's the €200-plan primary (practically unlimited there; caps only bite very heavy use). On the basic plan it's simply unavailable, so the picks below split into an €200-plan column and a basic-plan ladder.

Verify your catalog first. The public API reference's /v1/models listing names only deepseek-v4-flash, mimo-v2.5, qwen3.6 and gemma4 for chat — GLM-5.2 does not appear in it. Run GET /v1/models with your own key a