agentic-workflow

Agentic Workflow Skills

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/                  39 source skills (19 user-facing + 19 workflow internals + 1 metadata-internal; 38 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). The raw-idea interview is a bounded form protocol — one compact form-turn over the ≤ 6 fixed rubric slots with one-word defaults, then at most 2 ambiguity follow-ups, never one-question-per-turn. 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. Phase linting is deterministic: run bun scripts/phase-lint.mjs <plan> and paste its output (exit 1 → re-cut).

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