Imported from jpolvora/ws-skills (AGENTS.md). Install upstream with npx skills add jpolvora/ws-skills. Copyright stays with the author.

AGENTS.md

What this repo is

From-scratch reimplementation of "Workflow Skills" — an agent- and IDE-neutral skill hub + FSM framework. SPEC.prd.md is the sole source of truth. It was written only from features observable on the public site (https://jpolvora.github.io/workflow-skills); no upstream source was inspected, and there is no upstream git remote configured here. Do not assume upstream internals exist or match.

Currently the repo contains SPEC.prd.md plus the implemented skill pack: 39 skills under .agents/skills/, the ws-shared/ hub templates, the data-driven bin/skill-dependencies.json, and the npx installer CLI (bin/workflow-skills.js). Any code, skills, or installer you build must be derived from the PRD.

Key facts from the PRD (agent needs these)

• Skills live at .agents/skills/<name>/SKILL.md (YAML frontmatter: name, description, version) — plain Markdown any harness can load.
• Consumer-owned hub .agents/skills/ws-shared/ holds config.json, STACK.md, MEMORY.md, CHANGELOG.md, gates.md, installed-skills.json. These are strictly preserved on update/uninstall — never overwrite them.
• Artifacts: *.spec.md, step-01-*.plan.md, *.exec.dag.json, index.PRD; batch state persists under {plansDir}/ws-multi-spec/.
• Three orchestrators: ws-spec-to-pr (Standard, steps 0–9, 27 deps), ws-spec-to-pr-lite (steps 0–5, 19 deps), ws-multi-spec (batch, 7 deps). Dependency graph is in SPEC §8 — reproduce those edges exactly.
• Dual-mode routing via config.json dagThresholds (file count, layer depth, estimated tasks): simple → lite, complex → standard.
• 39 skills across 5 layers; package composition is data-driven via bin/skill-dependencies.json.
• Canonical install form: npx --yes github:jpolvora/workflow-skills (interactive menu: f full, w workflows, e extra; update, update --include-new, --check, --version subcommands).

Skill routing

• Invoke by trigger. Match a task to a skill's description frontmatter (trigger conditions and intent only). When several skills match, prefer the one whose description names the action; orchestrators dispatch to declared sub-skills by name.
• Autoload & command-invoked skills. A few skills fire from a slash command, a config rule, or a workflow call instead of the discovery index. Load them only when that branch fires:
  • ws-senior-developer — via rules.seniorDeveloper or /senior-developer.
  • ws-tdah — via /ws-tdah, /tdah, or autoload.
  • ws-activity-report — via the activity-report {date} trigger.
  • ws-changelog — invoked by orchestrators after a task completes.
• Dual-mode routing. ws-classify-complexity estimates files touched, layers crossed, and tasks for a spec, then compares each to dagThresholds in config.json (maxFiles, maxLayers, maxEstimatedTasks). Any estimate above its threshold routes to standard (ws-spec-to-pr); all at or below routes to lite (ws-spec-to-pr-lite). Routing is decided once, before implementation; never reclassify mid-run.
• Config entry gates. Two skill classes:
  • Config-dependent (orchestrators, pipeline, planning, providers, delivery — e.g. ws-spec-to-pr, ws-spec-to-pr-lite, ws-multi-spec, ws-write-plan, ws-implement-tasks, ws-code-review, ws-testing, ws-ship-pr, ws-fix-pr, ws-github-provider, ws-azure-devops-provider, ws-configure-project): before executing, verify $PWD/.agents/skills/ws-shared/config.json exists. If missing or unconfigured, stop at a user-gate and run ws-configure-project to seed it.
  • Config-independent (utility and governance — e.g. ws-secrets-leak-review, ws-karpathy-guidelines, ws-tdah, ws-write-a-skill, ws-spec-format, ws-check-harness): execute directly in any repository without the config check.
• Dependency edges are invocations. A step calls its declared sub-skill; bin/skill-dependencies.json is the edge catalog. A referenced skill that is not installed is a harness integrity failure, not a runtime retry.

Progressive disclosure (3-tier)

• Tier 1 — SKILL.md loads on invocation: frontmatter triggers, entry gate, state machine steps, verifiable "Done when" per step. Keep it ≤ ~100– 150 lines.
• Tier 2 — references/*.md is read on demand when the step that needs it is reached: detailed schemas, complex examples, edge cases, domain rules.
• Tier 3 — scripts/* is executed via shell: deterministic validators, linters, schema checkers, generators.
• Mandatory rule: never load Tier 2 documentation into context until the specific step that requires it. Loading it early wastes the token budget the tiers exist to protect.
• Frontmatter description is trigger-and-intent only (it is injected into the discovery index before invocation); it never carries execution rules or step protocols.
• Current status: the whole pack ships as Tier 1 only (zero tier-2/tier-3 companions, per SPEC §12.1 portability). If a skill grows past ~150 lines, push detail to references/*.md before trimming the body — never inline it.

Section 14 still unresolved

SPEC.prd.md §14 lists open reimplementation questions (execution substrate, gates.md schema, dagThresholds semantics, multi-spec state schema, index.PRD sync rules). Resolve these before locking designs; record decisions in the PRD.

Conventions

• Documentation contract from SPEC §11: agents → AGENTS.md (full routing contract); humans → README.md (install & contribution).
• No CI, build, lint, or test tooling exists yet. If you add any, prefer standard Markdown + JSON, zero platform-specific code (SPEC §12.1), and make commands/harness-neutral.

Agentic Code Reviewers (PR review pipeline)

PR agentic review via jpolvora/agentic-code-reviewers. Review-only: the auto-fix option is intentionally not installed. The bot is read-only; it posts review threads on the PR and never modifies the repo.

How it works here

• Workflow: .github/workflows/code-review.yml — runs the reviewer (engine opencode, model opencode/deepseek-v4-flash) on every PR (opened/synchronize/reopened), then a merge-block gate that fails the check while any review thread is unresolved.
• Hard block on master requires a branch rule. On the GitHub free plan a private repo cannot enforce native branch rules, so the gate is the failing check itself (red = do not merge). To make it a hard merge block, apply the ruleset in .github/rulesets/agentic-code-review.json (required_review_thread_resolution) after upgrading to GitHub Pro: gh api -X POST repos/jpolvora/ws-skills/rulesets --input .github/rulesets/agentic-code-review.json.
• Secrets: OPENCODE_API_KEY (required — review engine). Optional AGENTIC_CODE_REVIEWERS_GITHUB_TOKEN (PAT with pull-requests: write so the agent can auto-resolve threads it fixed; without it threads stay open and must be resolved manually).

Setup

1. Add the workflow .github/workflows/code-review.yml (see above).
2. Set the secret(s) in the GitHub repo (Settings → Secrets and variables → Actions):

   gh secret set OPENCODE_API_KEY -R <owner>/<repo>
   gh secret set AGENTIC_CODE_REVIEWERS_GITHUB_TOKEN -R <owner>/<repo>  # optional

3. Configure the model by editing AGENTIC_CODE_REVIEWERS_MODEL / with.model in the workflow (canonical opencode IDs come from opencode models, e.g. opencode/deepseek-v4-flash).

Local dry-run (no PR, no publishing)

Requires the reviewer source checkout and an OPENCODE_API_KEY (or opencode auth.json); prints the JSON reviews + thread previews, changes nothing:

# from the agentic-code-reviewers checkout
npm run review -- --dry-run --engine opencode --model opencode/deepseek-v4-flash

# against a specific target branch / include uncommitted changes
npm run review -- --dry-run --engine opencode --model opencode/deepseek-v4-flash \
  --target-branch refs/heads/master --include-uncommitted

# remote runner without a full checkout (from any repo dir)
curl -fsSL https://raw.githubusercontent.com/jpolvora/agentic-code-reviewers/release/run.sh \
  | bash -s -- --dry-run --engine opencode --model opencode/deepseek-v4-flash

Update

The workflow consumes the pinned release branch of the runner (raw.githubusercontent.com/jpolvora/agentic-code-reviewers/release/run.sh). To pick up a new runner version, update that repo's release branch (the upstream release.yml does this automatically on merge to main) — no local change is required. If a breaking config rename lands upstream, refresh the AGENTIC_CODE_REVIEWERS_* env names in this workflow to match.

Configure (knobs)

• Engine/model: AGENTIC_CODE_REVIEWERS_ENGINE (cursor-sdk | opencode) and AGENTIC_CODE_REVIEWERS_MODEL (provider/model).
• AGENTIC_CODE_REVIEWERS_SCORE_MIN — minimum score (0–10) to publish a finding as a thread (default 6); continue-on-error: true keeps agent failures non-blocking so only real unresolved threads fail the gate.
• Target branch: --target-branch / AGENTIC_CODE_REVIEWERS_TARGET_BRANCH (default refs/heads/master).