forge-core

Create and validate skills for forge modules. USE WHEN create skill, new skill, write skill, validate skill, check skill, skill structure, skill conventions.

Create, validate, evaluate, and iterate skills for forge modules. USE WHEN create skill, new skill, write skill, validate skill, check skill, skill structure, skill conventions, test a skill, run skill evals, benchmark a skill, skill not triggering, optimize skill description. Not for adopting community skills (AdoptArtifact) or shipping artifacts downstream (PublishArtifact).

Create, validate, or place behavioral rules in forge modules. USE WHEN create rule, new rule, write rule, capture rule, add a rule, graduate a correction or convention to a rule, validate rule, rule conventions, where does this rule belong, or the user runs /Rule.

Scaffold a workshop project: a VCS spine (git + jj colocate + entire + forge hooks), the private/public/assets flow layout with a .tlp manifest, a .claude/ that mounts the knowledge vault, and on-demand satellites (vault folder-note, data dir, private remote). USE WHEN starting a new project, initializing a folder for work, adding a vault note or data dir or remote to a project, archiving a project, or the user runs `project` / `atlas`.

Collaborative ideation before implementation — explore context, clarify intent, propose approaches. USE WHEN starting creative work, new features, design decisions, or modifying behavior.

Write a formal design spec from brainstorming output or requirements. USE WHEN design approved, write spec, formalize design, spec document.

Execute an implementation plan inline — task by task in a single session — then finish the work: verify, present integration options (merge, PR, keep, discard), and clean up the workspace. USE WHEN executing plan, run plan, implement plan, inline execution, implementation complete, deciding merge strategy, finishing a feature branch or workspace.

Plan implementation work in two modes: bite-sized task-list plans written in plan mode, and reviewable plans published as commentable HTML artifacts with review rounds and delta refreshes. USE WHEN write implementation plan, plan implementation, create plan, spec approved, reviewable plan, commentable html plan, plan review round, refresh plan artifact, actioning an exported plan-review digest. Not for executing an approved plan (ExecutePlan).

Git best practices: conventional commits, staging, push policy, pre-commit checks, repo governance, plus Jujutsu (jj) colocated repos (commit and push discipline, push-batched signing, secret scans relocated to pre-push). USE WHEN committing, pushing, creating PRs, branch protection, rulesets, CODEOWNERS, pre-commit hooks, blocking known-dangerous strings, or working in a jj / jujutsu / colocated repo.

Run prompts against a local LLM backend (LM Studio, Ollama, or MLX) with privacy-preserving output guardrails — drop reasoning_content, enforce structured output schemas, and post-redact identifiers. USE WHEN sending sensitive content to a model, classifying private data on-machine, scanning dotfiles or configs for leaks via local LLM, content audit that must not touch cloud APIs.

Safety guardrails: runtime overrides for AI-safety plugin blocks, and per-language security review for python, javascript/typescript, and go. USE WHEN a safety plugin blocks a command, sandbox blocked, git reset --hard blocked, rm -rf blocked, workaround for a blocked command, safety plugin configuration, security review, secure-by-default coding, vulnerability report.

Revise an existing file as discrete reviewable hunks, never a wholesale overwrite. USE WHEN editing, rewriting, or revising a document, note, config, or file the user will review, especially one they have already hand-edited.

Audit forge module provenance and deployment integrity — inspect deployed sidecars, detect drift, clean stale artifacts after renames, trace adoption chains. USE WHEN running forge provenance, auditing a deployed target, debugging drift, cleaning up after a skill rename, or investigating sidecar state.

Search past agent sessions and checkpoints — semantic + keyword recall across repos, branches, authors, and time windows. USE WHEN have we done this before, search past work, find the previous implementation, look for checkpoints about X, recover a prior prompt. Not for the current active session — use SessionHandoff for that.

Audit and clean AI coding tool settings — permissions, plugins, hooks, cross-layer conflicts. USE WHEN review permissions, clean settings, audit config, plugin conflicts, hook audit, settings cruft.

Check the forge ecosystem for staleness — installed skills vs source, binary freshness, lib consistency, version drift, submodule pointers, hook config, install-source freshness vs trunk. USE WHEN stale, freshness, out of date, check staleness, need to rebuild, make install needed, install reverted merged changes, system check.

Reactive correction and root-cause fix. USE WHEN something went wrong, user is frustrated, demands a correction, says wtf, what the hell, why did you, that's wrong, this is broken, no not that, stop. Executes the immediate fix, then hunts the upstream artifact that caused it and creates a corrective change.

Adopt a community skill from an upstream URL into forge. Fetches the source, applies transforms, produces a working SKILL.md with SLSA provenance. USE WHEN adopting a community skill from aitmpl, anthropics/skills, or a similar catalog.

Find, read, create, validate, and capture Architecture Decision Records. USE WHEN ADR lookup, architecture decision, project context, decision history, create ADR, new ADR, validate ADR, capture ADRs, decisions directory, or editing any ADR file.

Create, validate, or audit agent definitions. USE WHEN create agent, new agent, build agent, scaffold agent, validate agent, audit agents, agent conventions, agent frontmatter.

Create and validate module hooks. USE WHEN create hook, new hook, write hook, scaffold hook, validate hook, check hook, hook conventions, hook events, hook structure.

Design, build, and validate forge modules. USE WHEN create module, new module, scaffold module, validate module, check module, audit module, module structure, module conventions, module architecture.

Create, validate, and publish Claude Code plugins from forge modules. USE WHEN create plugin, validate plugin, publish plugin, marketplace, plugin.json, cowork plugin.

Generate single-file HTML demos comparing techniques side-by-side. USE WHEN preview css, compare css, css demo, show options, visual comparison, html playground, render demo.

Extract session learnings and apply them as updates to rules, skills, and agents. USE WHEN session produced reusable patterns, corrections, or conventions worth capturing.

Markdown authoring and linting conventions for forge — fence tags, table alignment, link paths, reference-style labels, README language switchers, and the Linting workflow. USE WHEN editing any markdown file, or invoking lint.

Evaluate the currently loaded memory, rules, and skills against the running model's baseline and offload instructions the model already follows unprompted into model qualifier directories. USE WHEN optimize context, trim my context, simplify memory, trim loaded rules, model already knows this, is this rule still needed, rules the model no longer needs, what can we remove now that the model is smarter, offload rules, context bloat. For static provenance or staleness scans and ablation testing use PromptAnalysis instead.

Capture, list, update, and close repo-local backlog items as Obsidian Tasks lines in dated daily files under docs/todos/. USE WHEN capture todo, project todo, project backlog, repo backlog, backlog item, list todos, todo capture, new todo, close todo, or local issue tracking without GitHub.

Apply targeted transforms to prompt-shaped documents: align conventions, debrand vendor references, minimize filler, rescope tool grants, extract bulk reference, adapt for downstream repos. USE WHEN refining an adopted skill, polishing an authored skill/rule/agent, removing rot, or porting prompts across repos.

Decompose a research question into sub-queries, spawn parallel WebResearcher agents per angle, synthesize findings with citations and explicit confidence. USE WHEN the user asks to research, investigate, look online, look up, dig into, find sources, gather evidence, or survey what's known about a topic. Single-pass; for multi-round adversarial research use ResearchCouncil in forge-council.

RTK (Rust Token Killer) — token-optimized CLI proxy for Claude Code. USE WHEN rtk, token savings, optimize tokens, reduce tokens, command optimization.

Commit-time secret scanning with gitleaks — prevent credentials from entering git history. USE WHEN scanning for leaked secrets, setting up pre-commit hooks, auditing repositories for credentials, configuring gitleaks allowlists, or encrypting user-specific module data with git-crypt.

Review your own staged changes via a code-review TUI before triggering a commit. USE WHEN about to commit, walking through your own staged diff, self-reviewing before approval, tuicr, revdiff, git diff cached.

Explain the intent behind source code by tracing it to the agent session transcript that created it. USE WHEN why does this function exist, what is this file for, why was this line added, explain this code's history, trace code to its originating conversation.

Continue work from another agent's session — auto-detect the most relevant saved session, read its transcript, summarize, and pick up the work. USE WHEN continue from another agent, hand off a session, pick up where codex or gemini left off, summarize a saved session or checkpoint, inspect recent sessions. Not for searching old work by topic — use SessionSearch for that.

Author project documentation that future humans (and AI sessions) actually read. Covers TLDRs for tools, READMEs, runbooks, journals. USE WHEN write documentation, create tldr, tool one-pager, document a cli, write readme, runbook, journal entry, capture knowledge about a tool, distill a session into reusable notes.

Build distinctive, production-grade frontend interfaces that avoid generic AI aesthetics. USE WHEN the user asks for web components, pages, landing pages, dashboards, React / HTML / CSS layouts, or styling of any web UI. Not for backend or non-UI work.

Ship artifacts (rules, skills, agents) from forge into downstream repos with provenance tracking and sync. USE WHEN drift, sync, publish artifact, publish prompts, publish skills, publish agents, inheritance, upstream, propagate, check provenance.

Create, derive, and validate .mdschema files for markdown documents. USE WHEN create schema, add schema, derive schema, validate schema, check schema, mdschema, lint schema, heading rules, frontmatter validation, or editing any markdown file in a directory that contains a .mdschema.

Validate and minimize prompts — provenance, targeting, staleness, redundancy, ablation testing, perplexity scoring. USE WHEN audit rules, check provenance, minimize prompts, prompt cleanup, validate targeting, find redundant rules, prompt audit, prompt analysis, stale rules.