agentic-workflow

Audit cross-document coherence: docs ↔ roadmap ↔ code ↔ fix index ↔ issues. Finds drift — features in docs/ not in the roadmap (or vice versa), fix-index entries already merged/closed, broken documentation-map links, dependency cycles, artifacts in the wrong language, naming-convention violations — and reports them ranked by severity, fixing only low-risk items on request. On Claude Code and want hand-tuned per-skill model/effort tiers? Install the `#claude` branch instead (`npx skills add gtrabanco/agentic-workflow#claude`) — see the README. This branch is model-agnostic: the skill inherits whatever model and effort your agent session is already using. Triggers: "check doc consistency", "are the docs in sync", "audit the docs", "doc coherence review", "did the docs drift", "validate the roadmap".

Audit a whole PR against the delivery contract and return MERGE-READY or evidenced blockers with the full URL. Consumes the current review-change REVIEW-PASS receipt instead of re-running review axes; posts a SHA-bound ready comment; never edits or merges. Triggers: "audit-pr", "is this PR ready", "merge gate".

Internal agentic-workflow maintenance: after SKILL.md edits, bump semver, lint authoring rules, and synchronize changelogs, READMEs, routing metadata, and migrations. Triggers: "bump the skill", "update the changelog", "version bump".

Turn a raw idea or existing feature into a designed product SPEC by completing entity, integration, role, and expectation closure. Upserts never destroy recorded decisions. Triggers: "design-feature", "design this feature", "define product scope".

Discover repository evidence and write a frozen Normalized Repository State. Produces verified repository evidence and keeps facts, decisions, planned work, documentation, and inference separate. It does not make recommendations or infer implementation from documentation. Triggers: "discover repository state", "normalize repository state", "freeze repository facts".

Internal shared owner of evidence-grounded authoring: the fixed claim/authority/evidence/freshness/unknown row, the ordered inventory-evidence-draft-readiness passes, `artifactRevisionId` rotation, and the no-progress rule. Consumed by `design-feature`, `plan-feature`, `plan-feature-scaffold` and `plan-fix`. Never reviews or approves. Not a menu entry.

Implement all remaining phases of a planned feature/fix by default, or one explicit P<n>, with frozen acceptance, phase-local gates, commits, recovery, and final PR close-out. Use --fix for fix SPECs; --force is user-only.

Repair persisted fix-now findings in compatible atomic batches: root-cause fixes, green gate, commit/push, and per-row `folded: yes` updates. Never reclassify or substitute backlog notes. Triggers: "fold-findings", "fix the review findings", "repair audit blockers".

Generate incremental, diff-driven developer guides through the project's detected docs adapter. Never regenerate the whole site, scaffold it, or edit source. Triggers: "generate-docs", "generate the docs", "document this unit".

Internal contract: the single owner of the bounded pre-write implementation discovery step. One read-only mapper that closes seven evidence questions, emits one fixed compact map, and routes READY | REPLAN | NEEDS-DESIGN | BLOCKED before any branch, planning, or source write. Consumed only by execute-phase on the pre-write route. Not a menu entry.

Adapt the workflow scaffold to a new repository or add only missing substrate blocks to an existing install. Every install, hook, and overwrite needs explicit consent. Triggers: "init-workspace", "set up agentic workflow", "upgrade workflow scaffold".

Append a structured entry to the project's session log (`docs/LOGS.md`): what was done this session, files touched, decisions taken, and the next step — so the next session (or another person) can pick up the thread without re-reading git history. Run it before `/clear`, before closing Claude Code, or at any natural stopping point. On Claude Code and want hand-tuned per-skill model/effort tiers? Install the `#claude` branch instead (`npx skills add gtrabanco/agentic-workflow#claude`) — see the README. This branch is model-agnostic: the skill inherits whatever model and effort your agent session is already using. Triggers: "log this session", "log-session", "write a session log", "journal what we did", "record this session before I clear", "save the session summary".

Internal machine-result contract for headless agentic-workflow drivers. The executable source is @gtrabanco/agentic-workflow-schema: strict Envelope v2 for workflow-status, compact SkillOutcome v1 for driven work, compatibility parsing, and deterministic document snapshots. Not a menu entry.

Internal contract: the single owner of the eight phase-lint rules, the fixed PASS/BLOCKED result, and the normalized phase fingerprint. Consumed by plan-feature-scaffold, plan-fix, and execute-phase. Not a menu entry.

Route designed features or issues into engineering planning and roadmap registration; undesigned work stops at design-feature. Supports `--next`, `--from-issue`, and `--scaffold`. Triggers: "plan-feature", "plan a feature", "plan the next roadmap feature", "create SPEC and TASKS".

Internal step of plan-feature: turn a feature-request issue into a scoped, sized, roadmap-mapped SPEC **product half** (capability closure satisfied) with Closes #N traceability.

Internal step of plan-feature: from an already-designed SPEC (product half `designed`), fill the **engineering half** and generate the planning artifact set scaled to the feature's size (XS/S → SPEC-only with ≥ 2 phases in the SPEC, last = Hardening & PR; M/L → full set with a hardening phase), freeze one compact ACCEPTANCE.md for every size, and register the roadmap entry. Docs only — never code.

Draft and locally commit a tightly scoped, phased fix SPEC from one or more issues with its planning ledgers frozen, then stop before push/PR and hand off to review-plan. Triggers: "plan-fix", "plan a fix for issue N", "draft the fix spec".

Internal planning gate: consumes the normalized repository state and makes the ONE final architectural classification, using a two-stage contract that allows a lightweight NRS read during planning and a full architectural classification after the plan is cut. Used by plan-feature, plan-feature-from-issue, plan-feature-scaffold, and plan-fix. Not a menu entry.

Internal owner of the pre-execution review cycle and the planning ledgers: independence, unioned findings, counter-evidence dismissal, no-progress, `CONVERGENCE-ANOMALY`, and the evidence/obligation/findings tables. Consumed by `review-spec`, `review-plan`, and the authoring skills. Not a menu entry.

Audit the whole product across code, quality, process, docs, roadmap, and tooling. Persist one severity-ranked, F-numbered report with proposals; never fix or file work. Triggers: "product-audit", "audit the product", "full health check", "are we product-ready", "CTO review".

Internal contract: the conditional replan entry. Loaded only when `scripts/unit-route.mjs` prints `route: replan`; turns the router's bounded read set into appended SPEC phases without the full planning preflight. Consumed by plan-feature and plan-fix. Not a menu entry.

Resolve an explicit Normalized Repository State contradiction. This is the sole writer allowed to update frozen repository facts or accepted decisions. Triggers: "resolve repository state", "resolve contradiction", "update a frozen repository fact".

Internal accessibility review pass of the agentic-workflow review pack — composed in-turn by review-change and product-audit; not a menu entry. Checks the changed user-facing surface for accessibility: semantics, keyboard, focus, contrast, and ARIA correctness — applies only to user-facing surfaces. Findings only; never edits code.

Internal brand & copy review pass of the agentic-workflow review pack — composed in-turn by review-change and product-audit; not a menu entry. Checks changed user-facing copy against the project's brand doc: voice, terminology, and honesty of claims — applies only to surfaces with user-facing text. Findings only; never edits code.

Review a change with only applicable internal axes, classify every finding, persist fix-now work, and return one evidence-backed decision. Findings only; --adversarial N uses isolated reviewers; --synthesize fuses supplied reviewer tables. Triggers: "review-change", "review this change", "adversarial review".

Internal correctness + simplification review pass of the agentic-workflow review pack — composed in-turn by review-change and product-audit; not a menu entry. Checks correctness, error handling, duplication, dead code, and simplification opportunities against the project's own conventions. Findings only; never edits code.

Internal tech-debt transform pass of the agentic-workflow review pack — composed in-turn by review-change and product-audit; not a menu entry. Transforms the synthesized findings table into explicit debt items, each with a re-trigger condition; it does not rescan the diff. Findings only; never edits code.

Internal UI/UX design review pass of the agentic-workflow review pack — composed in-turn by review-change and product-audit; not a menu entry. Checks the changed UI against the project's design doc: consistency, states, responsiveness, and reuse — applies only when the project has a UI and the change touches it. Findings only; never edits code.

Internal scope/classification engine composed by review-change (and reused by the audit skills): consumes the synthesized findings table, verifies every applicable axis is represented, and classifies each finding into a decision table (fix-now / replan-in-unit / decision-required / proposal / ignore). Findings only — never refactors.

Internal performance review pass of the agentic-workflow review pack — composed in-turn by review-change and product-audit; not a menu entry. Checks the changed paths for algorithmic and resource regressions: N+1s, hot-path allocations, asset weight, and leaks. Findings only; never edits code.

Independent read-only review of a frozen Engineering plan before execution, in a context that did not cut it: feature or fix snapshot, obligation ledger sweep, phase and validator checks. Returns only PLAN-REVIEW-PASS or PLAN-REVIEW-FAIL with a snapshot-bound receipt (a product-intent gap is PLAN-REVIEW-FAIL with `class: product`). Never edits a plan artifact. Triggers: "review-plan", "review the plan", "review the phases".

Internal security review pass of the agentic-workflow review pack — composed in-turn by review-change and product-audit; not a menu entry. Checks secrets, input validation, injection, authn/authz, PII exposure, and dependency risk on the changed surface. Findings only; never edits code.

Internal SEO review pass of the agentic-workflow review pack — composed in-turn by review-change and product-audit; not a menu entry. Checks changed web pages/routes for indexability, metadata, and structured data — applies only to public web surfaces. Findings only; never edits code.

Independent read-only review of a frozen Product half before engineering planning. Runs the exact Product checks in a clean context and returns only SPEC-REVIEW-PASS, SPEC-REVIEW-FAIL, or NEEDS-DESIGN with a content-bound receipt. Never edits the reviewed SPEC. Triggers: "review-spec", "review the spec", "review product design".

Internal run-it verification review pass of the agentic-workflow review pack — composed in-turn by review-change and product-audit; not a menu entry. Runs the project's gate and the changed behavior for real — commands, exit codes, observed output — instead of assuming; what cannot be executed goes to the manual checklist. Findings only; never edits code.

Found or continue a roadmap autopilot one stage per invocation. Default: human merge. --fullauto is invocation-scoped and uses the transient wrapper only after a fresh audit. Triggers: "ship-roadmap", "ship the roadmap", "autopilot this project".

Verify an issue, persisted audit finding, or unresolved review finding against current code, classify it, and write only the contracted forge/ledger outcome. Supports independent batches and an immediate-fix review-finding route. Triggers: "triage-issue", "triage issue N", "triage this finding", "is this trigger met".

Internal contract: one compact frozen ACCEPTANCE.md per delivery unit, its validation ladder, anti-weakening rules, and blob-bound execution receipt. Consumed by planners, execute-phase, and review-change.

Read-only workflow sensor: run the deterministic script, read the fixed machine envelope, interpret the recommendation. Never edits. Triggers: "workflow-status", "workflow status", "what can I build next".