AGENT SKILL

ISA

Articulates the ideal state of a task or project as testable criteria. Invoked at Algorithm OBSERVE for non-trivial work; produces an ISA.md the rest of the run reads from and writes back to. Use when scaffolding or extending an ISA at E3+ OBSERVE, gating `phase: complete` at VERIFY, resolving interdependent design decisions before freezing criteria, or on `/ISA scaffold`, `/ISA check`, `/ISA interview`.

License 许可
MIT
最近更新
2026-10-23
Stars
★ 0
Forks
0

01 前言 Front Matter

name
ISA
type
skill
model
inherit
description
Articulates the ideal state of a task or project as testable criteria. Invoked at Algorithm OBSERVE for non-trivial work; produces an ISA.md the rest of the run reads from and writes back to. Use when scaffolding or extending an ISA at E3+ OBSERVE, gating `phase: complete` at VERIFY, resolving interdependent design decisions before freezing criteria, or on `/ISA scaffold`, `/ISA check`, `/ISA interview`.

02 资源文件 3

03 SKILL.md 正文

ISA — Ideal State Articulation

The ISA is the system of record for a non-trivial Algorithm run. A single document holding:

  1. The ideal-state articulation (Problem / Vision / Goal)
  2. The test surface (Criteria — atomic ISCs)
  3. The verification trail (tool-probe evidence per ISC)
  4. The done condition (every ISC [x] with evidence)
  5. The persistence trail (Decisions + Changelog)

Created at OBSERVE, refined through pursuit, verified at VERIFY.

Tiers (per ALGORITHM/v1.2.0.md)

  • E2 — inline criteria checklist in the reply; no ISA document.
  • E3/E4 — ISA document required. Two homes: project ISA at <project>/ISA.md (long-lived) or task ISA at docs/tasks/<task-id>/ISA.md (per-task; auto-created by forge task add --isa). Prefer extending the project ISA for project tasks; task ISA for ad-hoc work.

Index

File or section Read when…
Workflows/Scaffold.md Algorithm OBSERVE, E3+, or /ISA scaffold "..." — create or extend the relevant ISA
Workflows/CheckCompleteness.md Algorithm VERIFY, or /ISA check <path> — gate phase: complete
Workflows/Interview.md OBSERVE at E3/E4 with unresolved interdependent design decisions, or /ISA interview <path> — dependency-ordered design interview (optional, skippable)
_shared/model-routing.md Interview step 3 — dispatching a fact lookup instead of asking the user
12-section structure · ISC quality gates · Operating rules (below) Every workflow

A plain forge task add carries no ISA — track + nudge, never enforce. task lock prints a non-blocking reminder; the consistency checker reports advisory task-without-isa findings. Attaching one stays your choice.

The 12-section structure (locked order)

# Section Role
1 Problem What's broken / missing / wanted — concrete, evidence-backed
2 Vision The world once this is done
3 Out of Scope Explicit cuts for this run
4 Principles Inviolable rules framing every decision
5 Constraints Inherited boundaries; references Tier 2 docs
6 Goal One paragraph — the deliverable in concrete terms
7 Criteria Atomic ISCs, each one nameable tool probe
8 Test Strategy Per-ISC: type / check / threshold / tool
9 Features Phased breakdown linking ISCs to delivery units
10 Decisions Timestamped — chosen, why, rejected
11 Changelog Conjecture/refutation pairs — how understanding evolved
12 Verification Tool-probe evidence per [x] ISC — closes the loop

ISC quality gates

Criterion count is judgment, not a quota — enough that every deliverable, risk, and regression path has a probe; no more. Gate each criterion with the splitting test:

  • Granularity — a single nameable tool probe (Read / Grep / Bash / curl / …)
  • Atomic — one verifiable end-state; compound "and"/"with" → split
  • Independent failure — A can pass while B fails → split
  • Scope words — "all", "every", "complete" → enumerate
  • Domain boundary — one ISC per UI / API / data boundary

Required regardless of size: ≥1 Anti: ISC — what must NOT happen, making regression-prevention and out-of-scope probe-able. (Experiential goals also carry ≥1 Antecedent: ISC — the gate the user ultimately judges by.)

Operating rules

  • ISC IDs are stable — never renumber. Splits become ISC-N.M; drops become tombstones with a note.
  • [x] requires evidence in ## Verification — never just "tests pass" or "looks fine".
  • Tier 2 docs win on conflict — .claude/reference/02-architecture-and-tech-stack.md is authoritative over ## Constraints until reconciled via ADR.
  • phase: complete is gated — CheckCompleteness must pass first.

See also

  • .claude/ALGORITHM/v1.2.0.md — phase doctrine that drives ISA usage (LATEST)
  • .claude/reference/06-architecture-decisions.md — where significant Decisions land long-term as ADRs
  • .claude/scripts/forge/forge.py task add --isa "..." — auto-creates the task ISA

Project-specific overrides: if SKILL.local.md exists in this directory, read it — it is consumer-owned, survives framework refresh, and wins on conflict. A sidecar that relaxes a gate defined above must state how to prove the gate is wrong in that case. Doctrine: rules/framework-vs-project-root.md.

04 同仓库更多 Skills

rynhardt81
rynhardt81/forgeFlow

wizard

Generates an interactive bash wizard that walks a human through steps only they can perform — opens each URL, says what to click and copy, captures values (hidden entry for secrets), writes .env and GitHub secrets, confirms before irreversible actions. Use when provisioning infrastructure, setting up credentials or CI secrets, walking an unfamiliar third-party dashboard, or running a one-off migration or cutover. Don't invoke this for steps the agent can perform itself.

★ 0
rynhardt81
rynhardt81/forgeFlow

vet-idea

Vets an idea, decision, or plan BEFORE it is built. Runs a single model through five fixed adversarial advisor roles, a peer-review pass, and a chairman synthesis that emits a halt-capable GO / NO-GO / RECONSIDER verdict. Advisory and non-mutating — outputs a report, never writes task state. Use when an idea, feature, or costly hard-to-reverse decision is of uncertain worth and the question is whether to build it at all. NOT FOR settled work (bug fixes, approved features) or for shaping how to build it (the ISA Interview workflow).

★ 0
rynhardt81
rynhardt81/forgeFlow

triage-incident

Production incident triage — from "something is broken for users" to fixed, verified, and learned-from. Pulls the error signal (Sentry/logs/user report), reproduces before touching code, routes the fix through /fix-bug's prod fast path, and closes with a postmortem entry. Use when something is broken for users in production — an outage, data corruption, a Sentry spike, or a crash-rate alert. NOT FOR bugs found in development (use /fix-bug directly) or CI failures (use /diagnose-ci).

★ 0
rynhardt81
rynhardt81/forgeFlow

setup-review-bot

Configures a repo's AI code reviewers — the post-PR mention bot and the pre-push local reviewer — and writes the AGENTS.md the reviewers read. Interviews the user for what the reviewer should weight, then sets git config forge.reviewBot / forge.localReview and populates AGENTS.md at the project root. Use when a repo has no reviewer configured, when review findings are consistently off-target, or when onboarding a new project.

★ 0
rynhardt81
rynhardt81/forgeFlow

security-review

Portable security review for a feature, endpoint, or change before it ships. Orchestrates the existing OWASP review (@security-boss) and secrets scan (security_secrets validator), then adds the pass they miss — an explicit business-logic-flaw walkthrough (IDOR, race/TOCTOU, state-machine bypass, privilege escalation, price/quantity tampering). Advisory and non-mutating — produces a findings report; real findings are filed as tasks. Use when a change touching money, access control, or multi-step state is about to ship, or when the auth looks fine but the flow could be abused. NOT FOR SAST or dependency-CVE scanning (consumer CI owns those).

★ 0
rynhardt81
rynhardt81/forgeFlow

run-epic

Autonomously drains every open task in a single epic. Pulls ready tasks via the forge CLI, executes the work in-context using the matching discipline (fix-bug / new-feature / refactor), files newly-discovered work as follow-up tasks without stopping to ask, opens a PR per completed task via /create-pr, and repeats until the epic has zero ready/in-progress/pending tasks. Use when the user says `/run-epic E##`, "run epic autonomously", "finish all remaining tasks for epic X", or "drive epic X to completion".

★ 0