AGENT SKILL

audit-task-status

Reconciles Forge Flow task and epic files with the task registry (docs/tasks/registry.json, the single source of truth): fixes status drift in task-file frontmatter and epic files, and surfaces registry tasks with no body file on disk. Use when task or epic statuses look out of sync with the registry ("the epic file is stale", "are the statuses in sync"), after a batch of merges or completions, or as a pre-release consistency check.

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

01 前言 Front Matter

name
audit-task-status
description
Reconciles Forge Flow task and epic files with the task registry (docs/tasks/registry.json, the single source of truth): fixes status drift in task-file frontmatter and epic files, and surfaces registry tasks with no body file on disk. Use when task or epic statuses look out of sync with the registry ("the epic file is stale", "are the statuses in sync"), after a batch of merges or completions, or as a pre-release consistency check.

02 资源文件 3

03 SKILL.md 正文

Audit & align task status

Makes task-file frontmatter and epic files tell the same truth as docs/tasks/registry.json, and reports registry-health gaps (tasks with no body file). The forge CLI is the only sanctioned writer of the registry; never hand-edit it.

Index

File or section Read when…
WHY.md Explaining to the user why epic files drifted, or deciding which of the three layers to trust
The authority rule (below) Before any edit — which layer wins
Workflow (below) Every invocation — steps 1–5
scripts/audit_status.py Run it (step 2 and step 5) — read-only detector
What "aligned" means (below) Deciding you are done

The authority rule

The registry is ground truth. Always reconcile the other layers TO it, never the reverse. If a task file or epic file disagrees with the registry, the registry wins — fix the doc. The only exception is if the registry itself looks wrong (a status that contradicts a merged PR); in that case stop and surface it to the user, because changing the registry means a forge task state transition, not a doc edit.

Workflow

1. Sync the machine layer (registry ↔ task-file frontmatter)

Run the consistency hook with --fix — it auto-corrects trivial registry/task-file drift and reports anything it can't fix:

python3 .claude/hooks/forge/consistency-banner.py --fix --json

rc=0 with no findings means layers 1↔2 agree. If it reports blocking drift it can't auto-fix, resolve that first (it usually means a task file was hand-edited to a status the registry disagrees with — fix the file to match the registry).

Do not trust rc=0 alone as proof of full alignment — this hook only checks registry↔task-file. It is blind to epic files. The next steps are where the value is.

2. Independently verify task-file frontmatter (don't just trust the hook)

The hook is informational and has been wrong before. Confirm independently — for every registry task, the body file's status: frontmatter must equal the registry status. Use the bundled script:

python3 .claude/skills/audit-task-status/scripts/audit_status.py

It reads the registry, locates each task's body file, and reports three things:

  • task-file status mismatches (frontmatter status: ≠ registry status),
  • epic-file drift (see step 3),
  • registry tasks with no body file on disk.

Read its output before editing anything — it tells you the exact scope.

3. Reconcile epic files (the layer the framework forgets)

For each epic with open or recently-changed work, the epic file (<epic>/<epic>.md) has up to four things that drift — the bundled script reports the first three; you verify and fix:

  • The progress counter — a prose line like **Tasks:** N total — M completed, …. Recompute from the registry and rewrite it. Refresh any "as of <date>" stamp.
  • The per-task status — in TWO idioms, depending on the epic:
    • Pipe tables: | T### | … | <status> | … |. Column position varies between epics (some add columns before Status), so locate the Status header rather than counting columns. Cells may carry annotations after the status (completed (PR #N), closed — phantom). Fix any cell whose leading status token disagrees with the registry.
    • Checklists: - [x] T###: … ✅ / - [~] T###a: … superseded. The checkbox alone is ambiguous, so the script only flags a row when an explicit status word in the line contradicts the registry. Verify these by hand — a [x] next to a task the registry calls superseded is real drift; a [x] that's merely annotated (commit pending) while the registry says completed is cosmetic, not a status mismatch.
  • The prose **Status:** header (and the epic's status: frontmatter). An epic whose every task is terminal (completed/superseded/closed) but whose prose header still says in_progress/pending is contradicting itself — fix the header to match the rollup. (This is distinct from the counter; an epic can have a right counter and a stale header, or vice-versa.)

Watch for internal contradictions — a counter saying "1 ready" while the table row for the same task says completed, or a **Status:** in_progress header on an all-terminal epic. Make every layer (header, counter, rows) AND the registry agree.

Scope discipline — do NOT backfill missing table rows by default. Epic files routinely list only a subset of their tasks (the headline ones); the registry holds the complete per-task detail. Many Forge epic files explicitly say "registry is authoritative — counts drift as tasks are added". Adding a row for every registry task is a large rewrite that fights the file's design. Fix the counters and the statuses of rows that already exist; only backfill individual rows if the user explicitly asks. When you skip a backfill, say so plainly (e.g. "counter now reflects all N tasks; 35 of them don't have individual table rows, by design").

4. Report the registry-health extras

Beyond status, surface (don't fix unless asked):

  • Tasks with no body file — registry entries created with --no-file, or whose body was later deleted/moved. The script lists them. These aren't a status problem, but they break resume/lock for those tasks. Offer the fix rather than doing it silently: python3 .claude/scripts/forge/forge.py task reconcile-files (dry-run) → --apply to create stub bodies.

5. Verify and commit

Re-run the audit script — every layer should now report 0 mismatches. Re-run the consistency hook (rc=0) to confirm your epic-file edits didn't disturb the machine layer (they shouldn't — you only touched epic prose). Then commit the epic files (and any task files the hook fixed) together:

docs(epics): align <epics> statuses with registry

Spell out in the commit what drifted and what you deliberately left (e.g. "fixed counters + N stale rows + the T### contradiction; did NOT backfill the M missing rows — epic defers per-task detail to the registry").

What "aligned" means (the done condition)

  • Registry ↔ task-file frontmatter: 0 status mismatches.
  • Every epic-file counter matches the registry's completed/total for that epic.
  • Every epic-file row that exists (table OR checklist) matches the registry status.
  • Every epic's prose **Status:** header agrees with its task rollup.
  • No internal contradictions within an epic file (header vs counter vs rows).
  • Registry-tasks-without-body-files reported (and fixed only if the user opted in).

Verify the script's findings — it is a first pass, not an oracle

The bundled audit_status.py is a fast detector, but it resolves body files by the registry file field with a glob fallback, and parses heterogeneous human prose — so it can mis-report at the edges. Treat its output as candidates to confirm, not gospel. Two false-positive classes it has produced before (now guarded, but stay alert): a T###-*.md file outside a /tasks/-or-/orphan/ dir (e.g. a docs/debug/ triage note) shadowing the real body file; and a cosmetic annotation ([x] … (commit pending)) read as a status. Before you edit anything, spot-check each flagged item against the registry and the actual file line — the same empirical-premise discipline any audit finding deserves.

Notes

  • This is a deterministic audit, not a judgment call — the registry decides every status. The only place judgment enters is the scope of epic-file backfill (step 3) and whether to create missing body files (step 4); both default to "ask, don't silently expand scope".
  • The bundled scripts/audit_status.py does the read-only detection; the fixes are small targeted edits you apply by hand (epic prose is human-authored — an Edit-per-fix keeps the change reviewable). Don't try to regex-rewrite whole tables.

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