now
Skill0 starsChanged 3 months agoMITView on GitHub
Review current project state and suggest next action
1 other project uses a version of this.
Adopted by
Most recently taken up by
- talal-ai/handoff-nowtheir own version, first seen Oct 20, 2026
Other versions1 project uses a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 1
- talal-ai/handoff-now★ 0same name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
The file
Show its rules and text
We split this skill into the rules it gives an agent
99 rules. About 0 are common, 37 are distinctive, and 62 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈37
Distinctive · estimate
This author's own choices. Worth a look.
62
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 23
If $ARGUMENTS is ? or help: Print:
- Distinctive: line 38
Stop — do not execute any further steps.
- Very specific: line 44
If $ARGUMENTS contains --watch, run /now as a self-pacing surveyor loop instead of a single pass.
- Very specific: line 77
Read docs/sessions/context-snapshot.md.
- Very specific: line 78
If generated within the last 10 minutes AND no ## Active implementation section shows a step change: use snapshot data directly for steps …
- Distinctive: line 79
If stale (>10 minutes), missing, or an active implementation is in progress: proceed with full file reads (steps 1-8) and write a fresh …
- Very specific: line 82
Check forge.context.session_briefing in AGENTS.md (default: true if absent).
- Very specific: line 83
If false: skip this step entirely.
- Very specific: line 85
If true (or absent): a. JSON sidecar check (Spec 119): Before reading markdown session logs, check if .json sidecar files exist alongside …
- Very specific: line 87
If a JSON sidecar exists: parse it directly for summary, decisions, specs_touched, open_items, next_actions, error_autopsies, and …
- Distinctive: line 88
If no JSON sidecar exists: fall back to reading the markdown session log as before.
- Distinctive: line 91
If no session logs exist: skip this step (new project — first session).
- Very specific: line 98
Check docs/sessions/context-snapshot.md for a ## Session identity section — use the name stored there.
- Very specific: line 99
If not found: check .copier-answers.yml for default_owner — use that value.
- Distinctive: line 100
If not found: use literal "operator".
- Distinctive: line 102
If the user confirms (or does not object): proceed with the resolved name.
- Very specific: line 103
If the user provides a different name: use that name instead.
- Distinctive: line 107
Use the methodology value to adapt terminology in this command's output:
- Distinctive: line 137
Keep the entire brief to ≤15 lines (summarize aggressively — one line per session, one line per signal)
- Distinctive: line 138
If a section has no items, omit that section entirely (don't show empty headers)
- Distinctive: line 139
Read only the Summary and Pain Points sections from session logs (not the full files) to minimize token cost
- Very specific: line 143
Read .forge/onboarding.yaml if it exists.
- Very specific: line 145
If the file parses and status: complete AND configure_nudge_shown is false or absent:
- Very specific: line 151
After emitting the line, set configure_nudge_shown: true in .forge/onboarding.yaml (preserve all other keys and formatting.
- Very specific: line 153
If status is not complete OR configure_nudge_shown: true: skip this step silently.
- Distinctive: line 155
Do not add any further prompts, choice blocks, or follow-up interaction — this is a one-line advisory only.
- Very specific: line 157
If .forge/onboarding.yaml lacks the configure_nudge_shown key entirely (pre-existing projects), treat that as "not shown" — the nudge will …
- Distinctive: line 183
Do not add follow-up prompts or detail — the one-line posture is the entire output of this step.
- Very specific: line 185
Autopilot-envelope posture (Spec 531): when AGENTS.md contains a forge.autopilot: block, append · autopilot envelope: scheduled <off|on> to …
- Very specific: line 202
If the helper prints a line (one or more workflows' latest main run concluded failure): surface that line verbatim.
- Very specific: line 204
If the helper prints nothing: skip silently — green main, no GitHub remote, or gh unavailable/unauthenticated all look identical by design …
- Very specific: line 216
Read .mcp.json (project root).
- Very specific: line 221
Check .mcp-lock/npm/package-lock.json exists → if missing: emit ⚠ MCP integrity: context7 lockfile missing at …
- Very specific: line 222
Check npm is on PATH (shell command -v npm) → if missing: emit ⚠ MCP integrity: npm not installed — context7 server will fail-closed.
- Distinctive: line 223
If both checks pass: no line emitted (silent pass).
- Very specific: line 227
Check pip (or python -m pip) is on PATH → if missing: emit ⚠ MCP integrity: pip not installed — fetch server will fail-closed.
- Distinctive: line 228
If both checks pass: no line emitted.
- Very specific: line 231
Read Last verified: from the top of docs/process-kit/mcp-pinning-policy.md.
- Distinctive: line 234
If all pins fresh: silent.
- Very specific: line 238
If any probe in steps 1–4 emits an advisory, include a trailing line: Run /configure and choose MCP servers (#8) to disable servers without …
- Very specific: line 244
Validation queue (priority check, Spec 399): Run ${CLAUDE_PLUGIN_ROOT:-.}/.forge/bin/forge-py …
- Very specific: line 245
If any implemented specs exist, present them as the priority recommended action:
- Distinctive: line 261
If user selects "review NNN":
- Very specific: line 304
If count == 0: skip this step silently.
- Very specific: line 307
Cap warning: if count > cap, emit a warning line (never suppressed, even in lean mode):
- Distinctive: line 314
If no pair overlaps: silent on this sub-point.
- Very specific: line 348
Cost note: all three probes are local-filesystem/git reads (two small JSON reads plus one bounded reconcile_classify probe, itself bounded …
- Very specific: line 374
Read docs/sessions/ and find the most recent session log.
- Distinctive: line 375
Read CLAUDE.md post-implementation checklist and identify any items that appear outstanding based on recent session context.
- Very specific: line 376
Spec index — stale drafts (Spec 399): Run ${CLAUDE_PLUGIN_ROOT:-.}/.forge/bin/forge-py ${CLAUDE_PLUGIN_ROOT:-.}/.forge/lib/derived_state.py …
- Very specific: line 377
Session log auto-create: Check docs/sessions/ for a log file matching today's date.
- Very specific: line 378
Scratchpad review: Read docs/sessions/scratchpad.md for any open notes — list all unresolved items grouped by tag ([validate], [session], …
- Distinctive: line 384
If no proposed explorations exist or the directory is absent, skip silently.
- Distinctive: line 388
malformed/unreadable: treat as not-active (skip the file.
- Very specific: line 391
If active count N == 0: emit nothing (suppress line — single-tab/solo sessions see zero noise, regardless of stale count).
- Very specific: line 392
If N >= 1 and stale count M == 0: emit Tabs: N active.
- Very specific: line 393
If N >= 1 and M >= 1: emit Tabs: N active, M stale (run /tab close to clean stale).
- Distinctive: line 402
If all runbooks are current, skip silently.
- Very specific: line 405
If count N >= 1: emit one line Aging drafts: N past validity — run /matrix to triage via strategic-fit flow.
- Very specific: line 406
If count N == 0 (zero populated-and-expired) OR no drafts have valid-until: populated yet: emit nothing.
- Very specific: line 410
If today is on or after 2026-06-02 AND N >= 1 vet-pending drafts exist: emit one line N drafts vet-pending past 2026-06-02 SLA — …
- Very specific: line 413
Sunset reminder: read Spec 395 frontmatter for Provisional-Until: <date>.
- Very specific: line 419
If the count is greater than zero, emit exactly one line in this format: N optional capability(ies) available — /configure → Capabilities.
- Distinctive: line 426
If any flagged: report
- Distinctive: line 439
If none flagged, skip silently.
- Very specific: line 442
Write context snapshot: After gathering all data above, write docs/sessions/context-snapshot.md (gitignored) with the following structured …
- Very specific: line 482
If no outstanding items exist and the backlog is current, recommend the single highest-value next action.
- Very specific: line 503
Read docs/sessions/signals.md.
- Distinctive: line 506
If count is 0: skip silently.
- Distinctive: line 507
If count is ≥ 1: emit a single one-line advisory:
- Very specific: line 527
If .claude/commands/ is absent: skip Surface 2 silently.
- Very specific: line 536
Check docs/sessions/ for the most recent session log.
- Distinctive: line 537
If >2 hours since the session log was last modified (or no log exists for today): flag as stale.
- Distinctive: line 538
If 3+ specs have been closed since the last session log update (check CHANGELOG.md for close entries after the log date): flag as stale.
- Very specific: line 539
Spec 157 enhancement: If stale AND accumulated entries exist (structured entries appended by /implement and /close in today's session log), …
- Very specific: line 544
If stale but no accumulated entries: fall back to "Session log is stale — run /session to update."
- Very specific: line 548
If docs/.generated/ directory exists (project has migrated to split-file mode per Spec 398), surface the Phase 2 #3 dual-write retirement …
- Very specific: line 557
If N < 10 OR M > 0: Spec 254 Phase 2 #3 burn-in: N/10 closes accrued, M operator-reported renderer bugs (see docs/specs/398-*.md).
- Very specific: line 558
If N >= 10 AND M == 0: Phase 2 #3 burn-in: COMPLETE — eligible for /spec.
- Distinctive: line 564
Check whether any session-log EA/CI entries are missing from the persistent logs (the drift class Spec 452 closed — signals.md drift makes …
- Very specific: line 574
Read the final DONE | dry-run: summary line:
- Very specific: line 575
If 0 would be appended: skip silently — no drift.
- Distinctive: line 576
If N > 0: emit one advisory line:
- Very specific: line 582
Check signal-based triggers for the evolve loop.
- Very specific: line 595
Soft time fallback (recommendation only — Spec 500 R3/R5): if the last review date is older than forge.evolve.time_fallback_days (default …
- Very specific: line 600
Single last-review source (Spec 500 R6a): read the last review date from docs/sessions/evolve-state.md last_evolve_loop_run: — the one …
- Distinctive: line 605
If any threshold is crossed: report which triggers fired:
- Very specific: line 611
Add to the choice block: "Evolve loop triggered — run /evolve."
- Distinctive: line 612
If no thresholds crossed: skip silently.
- Distinctive: line 619
Update the overdue count in context-snapshot.md.
- Distinctive: line 633
Always include these options (numbered dynamically based on which apply).
- Distinctive: line 647
After the choice block, include the footer:
- Distinctive: line 653
Before emitting any next-action choice block in this command, consult the active-tab marker (Spec 353 primitive):
- Very specific: line 655
Read .forge/state/active-tab-*.json (primary).
- Very specific: line 656
If no marker, fall back to docs/sessions/registry.md rows with Status = active for the current session.
- Distinctive: line 657
If neither yields an active lane: emit the choice block as today.
- Very specific: line 658
If an active lane is detected: emit the one-line preamble (Tab lane: <lane>.
- Very specific: line 667
If .forge/state/reconcile-pending.json exists: emit one line in the report —
- Distinctive: line 669
Delete nothing automatically.
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
<!-- forge:paths-note (Spec 575): process-state paths in this command (docs/specs,
docs/sessions, docs/decisions, docs/research, docs/process-kit, docs/backlog.md) are the
CLASSIC-DEFAULT spellings, not fixed locations. When the project configures forge.paths
(e.g. the `contained` layout), resolve each key before use — bash: `forge_path <key>`
(source ${CLAUDE_PLUGIN_ROOT:-.}/.forge/lib/config.sh, forge_config_load AGENTS.md);
python: `${CLAUDE_PLUGIN_ROOT:-.}/.forge/bin/forge-py .../runtime_config.py path <key>`. -->Framework: FORGE
Model-Tier: haiku
<!-- multi-block mode: serialized — choice blocks fire at distinct mechanical steps (validation queue at Step 1, exit gate at Step 13). They do not co-present in the same agent message. See docs/process-kit/implementation-patterns.md § Multi-block disambiguation rule. -->Output verbosity (Spec 225): At the start of execution, read forge.output.verbosity from AGENTS.md (default: lean). In lean mode, suppress non-actionable diagnostic output (passing-gate confirmations, KPI tables, calibration deltas, MCP pin status, deprecation scans, signal-by-signal pattern dumps, root-cause groupings, deferred-scope aging when none aged, score-rubric details when unchanged) — write the full content to its file artifact (session log, pattern-analysis.md, etc.) and emit a one-line pointer in chat (or omit entirely if purely informational). In verbose mode, emit full detail as before. Never suppressed in either mode: choice blocks, FAILed gates, push-confirmation prompts, Review Brief "Needs Your Review" items, operator-input prompts, error/abort messages. See docs/process-kit/output-verbosity-guide.md for the full rules and worked examples.
Review the current project state and tell me what should happen next.
If $ARGUMENTS is ? or help:
Print:
/now — Review project state and recommend the next action.
Usage: /now [--watch]
Arguments:
(none) — single pass: review state once and recommend the next action.
--watch — open a model-paced /loop dynamic over /now that re-runs until a
meaningful state change or /loop end (Spec 464). Status cue at arming + each wake.
Reads: ${CLAUDE_PLUGIN_ROOT:-.}/.forge/lib/derived_state.py --get-backlog (live frontmatter source), docs/sessions/ (latest log + JSON sidecar), CLAUDE.md, docs/specs/README.md
Reports: validation queue, active work, next recommended spec, evolve loop status, blockers.
Also: count of drafts past `valid-until:` (Spec 363) — silent on zero.
Prefers JSON handoff sidecars for structured context; falls back to markdown parsing.
See: CLAUDE.md (operating loop, spec lifecycle), ${CLAUDE_PLUGIN_ROOT:-.}/.forge/lib/derived_state.py (canonical programmatic source — Spec 439), docs/backlog.md (operator-visible artifact)Stop — do not execute any further steps.
[mechanical] Watch mode — --watch (Spec 464)
If $ARGUMENTS contains --watch, run /now as a self-pacing surveyor loop instead of a single pass.
Primitive: open a /loop dynamic over /now. The model selects each next-check delay
(it does NOT take a fixed interval); the underlying ScheduleWakeup / native scheduling re-invokes
/now at model-paced intervals. The chosen delay is bounded:
- Lower bound:
forge.now.watch_default_min_delayfromAGENTS.md(default60seconds). - Upper bound:
3600seconds. The model picks each delay from observed activity cadence and respects the ~5-minute Anthropic prompt-cache window where workload allows (seedocs/process-kit/native-loop-adoption-guide.md§ Cache-window guidance).
Status cue (COO R1 — emit verbatim shape at watch arming AND at each wake):
- At arming, print exactly:
[watch armed] next check in ~Xs; /loop end to terminate - At each subsequent wake, print exactly one line of the form:
watch wake N — active spec NNN still in-progress; no new digests; next ~Ys(substitute the live N / spec / digest / delay values; thewatch wake Nandnext ~Ystokens are fixed).
Termination: the /now --watch loop MUST terminate on any of:
- (a) any user prompt;
- (b) a detected state change since the last wake — active spec advanced, a new spec was drafted,
/evolvefired, or the session log was updated; - (c) explicit
/loop end.
Audit-scope note (CISO R1): --watch creates a persistent filesystem-survey loop visible in
operator transcripts. At each wake it reads .forge/state/, docs/specs/, and docs/digests/.
See the guide's "Audit-scope note for /now --watch" section.
Each wake runs the normal /now Steps below, then emits the one-line status cue and computes the
next delay. Without --watch, run a single pass (the normal steps) and stop.
[mechanical] Step 0 — Snapshot freshness check (Spec 091)
Read docs/sessions/context-snapshot.md. Check the Generated: timestamp.
- If generated within the last 10 minutes AND no
## Active implementationsection shows a step change: use snapshot data directly for steps 1-8. Report: "Using recent context snapshot (generated<time>)." Skip to step 9 (write updated snapshot with refreshed timestamp). - If stale (>10 minutes), missing, or an active implementation is in progress: proceed with full file reads (steps 1-8) and write a fresh snapshot.
[mechanical] Step 0b — Session Brief (Spec 105)
Check forge.context.session_briefing in AGENTS.md (default: true if absent).
If false: skip this step entirely.
If true (or absent):
a. JSON sidecar check (Spec 119): Before reading markdown session logs, check if .json sidecar files exist alongside the 3 most recent session logs. For each session log docs/sessions/YYYY-MM-DD-NNN.md, look for docs/sessions/YYYY-MM-DD-NNN.json.
- If a JSON sidecar exists: parse it directly for
summary,decisions,specs_touched,open_items,next_actions,error_autopsies, andchat_insights. This is faster and more structured than parsing markdown. - If no JSON sidecar exists: fall back to reading the markdown session log as before.
- Report which method was used: "Loaded session context from JSON sidecar" or "Parsed session context from markdown (no JSON sidecar)."
b. Read the 3 most recent session logs from
docs/sessions/(by filename date, excluding_template.md,context-snapshot.md,scratchpad.md,signals.md,registry.md,error-log.md,insights-log.md). - If no session logs exist: skip this step (new project — first session).
- For logs without a JSON sidecar: extract from markdown: Summary section content, Decisions made entries, unresolved Process pain points, unchecked Process improvement items.
c. Read
docs/sessions/signals.md— extract signal entries from the last 7 days (by section date header). d. Readdocs/sessions/scratchpad.md— list items NOT marked[resolved]or checked off. e. Readdocs/sessions/context-snapshot.md— check for specs listed as in-progress or active that have not been closed (stale > 24h from session log date).
f. Session identity check (Spec 133): Resolve the current operator identity using this fallback chain:
- Check
docs/sessions/context-snapshot.mdfor a## Session identitysection — use the name stored there. - If not found: check
.copier-answers.ymlfordefault_owner— use that value. - If not found: use literal "operator".
Display: "Session identity:
<resolved name>. Confirm or type a new name."
- If the user confirms (or does not object): proceed with the resolved name.
- If the user provides a different name: use that name instead.
Store the confirmed identity in the context snapshot under
## Session identity(written in Step 9).
g. Methodology resolution (Spec 187): Read forge.methodology from AGENTS.md (default: none).
Use the methodology value to adapt terminology in this command's output:
scrum: "Daily standup" headers, "Sprint backlog" for next spec, "Definition of Done" for validationsafe: "Iteration sync" headers, "PI backlog" for next spec, "Iteration demo" for validationkanban: "Board review" headers, "Pull queue" for next spec, "Done column" for validationdevops: "Status check" headers, "Pipeline queue" for next spec, "Release validation" for validationsafety-critical: "Safety status review" headers, "Hazard log" for next spec, "V&V gate" for validationnone(default): "Project status" headers, standard FORGE terminology Store asmethodology_labelfor use in output sections below.
Present a Session Brief section before the main output:
## <methodology_label.header> — "Last time on [project]"
**Recent sessions** (last 3):
- <date>: <1-line summary from each session>
**Open decisions/blockers**:
- <unresolved pain points or open process items from recent logs>
**Recent signals** (last 7 days):
- <signal IDs and 1-line summaries>
**Unresolved scratchpad**:
- <open items from scratchpad>
**Stale work**:
- <any in-progress specs not closed within 24h, or "none">Constraints:
- Keep the entire brief to ≤15 lines (summarize aggressively — one line per session, one line per signal)
- If a section has no items, omit that section entirely (don't show empty headers)
- Read only the Summary and Pain Points sections from session logs (not the full files) to minimize token cost
[mechanical] Step 0c — /configure first-use nudge (Spec 286)
Read .forge/onboarding.yaml if it exists. If the file is missing, unreadable, or unparseable: skip this step silently (do not block /now execution).
If the file parses and status: complete AND configure_nudge_shown is false or absent:
- Extract at least one defaulted setting value from the parsed yaml (prefer
project.primary_stack; fall back tofeatures.devcontaineror the literalautonomy=L1+agents=Claude Codepair if stack is null/deferred). - Emit a single one-line nudge immediately after the Session Brief (or at the top of output if the Session Brief was skipped):
Defaults applied: stack=<primary_stack or "deferred">, autonomy=L1, agents=Claude Code. Adjust any setting via `/configure`. - After emitting the line, set
configure_nudge_shown: truein.forge/onboarding.yaml(preserve all other keys and formatting; add the key under thestatus:line if absent). Write the file.
If status is not complete OR configure_nudge_shown: true: skip this step silently.
Do not add any further prompts, choice blocks, or follow-up interaction — this is a one-line advisory only. The nudge must never appear again after the first emission (dismissal persists via the flag).
If .forge/onboarding.yaml lacks the configure_nudge_shown key entirely (pre-existing projects), treat that as "not shown" — the nudge will appear once on the next /now, then dismiss.
[mechanical] Step 0f — Authority trust-root posture (Spec 469)
Emit a single read-only one-line posture for the Authority Constitution autonomy/budget
enforcement trust root (ADR-046 / ADR-453). This is observability, never enforcement — it
derives the active tier from filesystem checks and never blocks. Skip silently if
.forge/config/authority.yaml is absent (consumer has not adopted slice 2).
Derive the tier (in priority order):
managed-settings— an OS-level managed-settings file is installed at the platform path (/Library/Application Support/ClaudeCode/managed-settings.jsonmacOS,/etc/claude-code/managed-settings.jsonLinux,C:\Program Files\ClaudeCode\managed-settings.jsonWindows) AND it denies edits to.forge/config/authority.yaml. The ceiling is the immutable trust root: the ADR-046 invariant is enforced at the trust-root tier.hooks-only— no managed-settings install, but.claude/settings.jsonwirescheck-authority-guard.shas a PreToolUse hook. The invariant is enforced for L0–L2 and is bypassable at L3 (an agent atbypassPermissionscan edit.claude/settings.jsonto remove the hook). Defense-in-depth, not a trust root.prose-only— neither installed: AGENTS.md prose only; no mechanical enforcement.
Emit exactly one line:
Authority: <managed-settings | hooks-only | prose-only>On FORGE-self (no operator-installed managed settings) the expected value is hooks-only.
Do not add follow-up prompts or detail — the one-line posture is the entire output of this step.
Autopilot-envelope posture (Spec 531): when AGENTS.md contains a forge.autopilot: block,
append · autopilot envelope: scheduled <off|on> to the Authority line (read the
scheduled.enabled value; read-only — never validate here, /close owns the gate). When the
block is absent (consumer projects that never adopted autopilot), print nothing extra —
silent-when-absent is the contract.
[mechanical] Step 0g — Red-main CI advisory (Spec 549)
Surface a one-line advisory when the latest main-branch run of any GitHub workflow is red, so closes cannot silently merge past a red main (the SIG-526-01 defect: five specs closed and pushed onto a main that had been red since 2026-07-10).
Run:
${CLAUDE_PLUGIN_ROOT:-.}/.forge/bin/forge-py ${CLAUDE_PLUGIN_ROOT:-.}/.forge/lib/ci_status.py- If the helper prints a line (one or more workflows' latest main run concluded
failure): surface that line verbatim. It is never suppressed in lean mode (red main is operator-actionable). - If the helper prints nothing: skip silently — green main, no GitHub remote, or
ghunavailable/unauthenticated all look identical by design (fail-silent contract: /now is the highest-frequency command and must not surface external-dependency errors; the helper always exits 0).
This surface is read-only and advisory — it never blocks. Fixtures: tests/fixtures/549/{red,green}.json
via --from-file (red emits the line; green and any error path emit nothing).
[mechanical] Step 0d — MCP integrity probe (Spec 284)
Persistent fail-closed visibility for the hash-verified MCP server lockfiles. Runs on every /now invocation — if any probe fails, the advisory re-appears until resolved (not one-shot).
Read .mcp.json (project root). If absent: skip this step silently (consumer project has no MCP config yet). If present but has no mcpServers entries: skip silently.
For each MCP server referenced in .mcp.json:
- context7 probe (if
mcpServers.context7exists):- Check
.mcp-lock/npm/package-lock.jsonexists → if missing: emit⚠ MCP integrity: context7 lockfile missing at .mcp-lock/npm/package-lock.json — server will fail-closed on activation. Restore via /forge stoke or remove server from .mcp.json. - Check
npmis on PATH (shellcommand -v npm) → if missing: emit⚠ MCP integrity: npm not installed — context7 server will fail-closed. Install npm ≥ 7 or remove server from .mcp.json. - If both checks pass: no line emitted (silent pass).
- Check
- fetch probe (if
mcpServers.fetchexists):- Check
.mcp-lock/python/requirements.lockexists → if missing: emit⚠ MCP integrity: fetch lockfile missing at .mcp-lock/python/requirements.lock — server will fail-closed on activation. - Check
pip(orpython -m pip) is on PATH → if missing: emit⚠ MCP integrity: pip not installed — fetch server will fail-closed. Install Python ≥ 3.10 with pip ≥ 22.3 or remove server. - If both checks pass: no line emitted.
- Check
- Staleness probe (only runs if
.mcp-lock/is present ANDdocs/process-kit/mcp-pinning-policy.mdexists):- Read
Last verified:from the top ofdocs/process-kit/mcp-pinning-policy.md. Compute days since that date. - For
context7: threshold = 60 days. If age > threshold: emitMCP pin stale: @upstash/context7-mcp verified <N> days ago (threshold 60). Bump-verification checklist: docs/process-kit/mcp-pinning-policy.md. - For
mcp-server-fetch: threshold = 365 days. If age > threshold: emit similar one-line advisory. - If all pins fresh: silent.
- Read
- Generic tooling check (even when lockfiles present and PATH-tools available): if
npm --versionreports < 7, orpip --versionreports < 22.3, emit⚠ MCP integrity: <tool> version <v> is below minimum — MCP server will fail-closed. Upgrade to <min>+.
If any probe in steps 1–4 emits an advisory, include a trailing line: Run /configure and choose MCP servers (#8) to disable servers without lockfiles, or see docs/process-kit/mcp-pinning-policy.md.
This step is silent on clean pass. It is NOT dismissible by a flag — the advisory surfaces on every /now run until the underlying condition is fixed (that is the persistent fail-closed design).
- Validation queue (priority check, Spec 399): Run
${CLAUDE_PLUGIN_ROOT:-.}/.forge/bin/forge-py ${CLAUDE_PLUGIN_ROOT:-.}/.forge/lib/derived_state.py --get-spec-index --format=jsonand scan the parsed JSON for any specs with statusimplemented(not yetclosed). For each one found, list it as needing human validation.If any
implementedspecs exist, present them as the priority recommended action:## Validation queue The following specs are implemented but not yet validated by a human: - Spec NNN — <title>: <objective>For each implemented spec, read its spec file (
docs/specs/NNN-*.md) and extract the first sentence of the## Objectivesection. Include it as<objective>in the listing above. Then offer a choice for each implemented spec:> **Choose** — type a number or keyword: > | # | Rank | Action | Rationale | What happens | > |---|------|--------|-----------|--------------| > | **1** | 2 | `review NNN` | Inspect first; reduces accidental approvals | Display full validation checklist from human-validation-runbook.md | > | **2** | 1 | `close NNN` | Closure path; default after operator review | Run /close NNN to validate and close the spec | > | **3** | — | `skip` | Defer validation; pick up other work | Defer validation — continue to backlog recommendations |If user selects "review NNN":
Part 1 — Spec-specific checklist (Spec 232): Read the spec file (
docs/specs/NNN-*.md) and generate a targeted validation checklist:a. From Acceptance Criteria: For each AC in the spec, create a numbered validation item:
## Spec-Specific Validation — Spec NNN ### Acceptance Criteria 1. [ ] AC1: "<AC text>" — Verify: <concrete check instruction based on the AC> 2. [ ] AC2: "<AC text>" — Verify: <concrete check instruction> ...b. From Test Plan: For each test plan item, create a verification step:
### Test Plan Verification 1. [ ] <test plan item> — Run/check: <how to verify> ...c. From Implementation Summary: List changed files for visual inspection:
### Changed Files (visual inspection) - [ ] `<file path>` — spot-check changes ...Part 2 — Generic runbook sections: Then read
docs/process-kit/human-validation-runbook.md, identify applicable sections (A–G) based on the spec's changes, and display the Quick Check list for each applicable section under a### General Checksheading.Footer: End with: "Run
/close NNNwhen validation is complete."- This takes priority over recommending new implementation work.
[mechanical] Step 1b — Unclosed-spec cap + file-overlap surfacing (Spec 498)
Deferred-close chaining (implement -> implement_next) accumulates specs at implemented
without an intervening /close. This step surfaces that pile-up so it cannot grow silently and
mechanically flags the riskiest case — a later spec building on an earlier spec's unreviewed
output (declared-file overlap). Read the cap from forge.now.unclosed_spec_cap in AGENTS.md
(default: 3 if absent).
- List implemented-but-unclosed specs: reuse the Step 1 set (specs at status
implemented, notclosed). LetU= that set andcount = |U|.- If
count == 0: skip this step silently. - Else emit exactly one line with the count AND the IDs (Req 6 — never count-only here):
Unclosed (implemented, awaiting /close): <count> — <comma-separated spec IDs>.
- If
- Cap warning: if
count > cap, emit a warning line (never suppressed, even in lean mode):⚠ Unclosed-spec cap exceeded: <count> implemented specs await /close (cap = <cap>). Deferred-close chaining stacks unreviewed specs on a moving baseline — clear the validation queue with /close before chaining further (Spec 498). - File-overlap surfacing (chained hazard — AC7, the case that must be mechanical, not only the count):
for each pair of specs in
U, read each spec's## Implementation SummaryChanged fileslist and intersect the declared paths. If two unclosed specs share ANY changed-file path, emit one line per overlapping pair:⚠ File overlap among unclosed specs: Spec <A> and Spec <B> both touch <path(s)> — <B> may build on <A>'s unreviewed output. Validate /close <A> before relying on <B>.- If no pair overlaps: silent on this sub-point.
This step is read-only and advisory — it never blocks. It complements Step 1 (which offers the close/review choice) by quantifying the pile-up and surfacing the file-overlap risk that deferred-close chaining introduces.
[mechanical] Step 0h — Housekeeping synthesis (Spec 610)
Three read-only probes that surface post-4.0 migration/housekeeping state the operator would
otherwise only discover by accident. Detect-and-surface ONLY — this step never runs
/forge doctor, stoke --to-plugin, or /reconcile; it reuses their existing logic
read-only and reports. Each probe is silent when it does not apply; when ALL are silent this
step emits nothing at all.
- Plugin/runtime version skew — reuse
/forge doctor's existing skew check (the D-INSTALLED-VERSION check in.forge/bin/forge-doctor.sh, orforge.md's skew probe): payloadplugin.jsonversion vs the resolved runtime/checkout version. Same marketplace/tier ONLY — the reused checks are single-installation comparisons by construction and MUST NOT be extended to take a second marketplace's version as input (a customer-tier fork install is never compared against the public marketplace's numbering, or vice versa). Report both versions when they differ. - Pending classic-mode migration —
.copier-answers.ymlpresent AND no FORGE plugin detected (the same detectionstoke.py'sapplyuses post-Spec-558) → surface thestoke --to-pluginrecommendation. Never runs it. - Un-reconciled history — reuse
/reconcile's ownstub_min_files/stub_min_linesthresholds (forge.reconcilein AGENTS.md) as a read-only probe. Report a count only, matching the count-only convention this command already uses for watchlist and digest items. Never auto-runs/reconcile.
Integration (R4): findings feed /now's existing "Recommended next action" ranking and
the Step 13 choice block — they are NOT emitted as a separate orphaned section. A skew or
pending-migration finding ranks alongside the other housekeeping recommendations; the
un-reconciled count is informational unless it crosses the reconcile thresholds.
Cost note: all three probes are local-filesystem/git reads (two small JSON reads plus
one bounded reconcile_classify probe, itself bounded by its marker/50-commit fallback) —
consistent with this command's Model-Tier: haiku budget and the existing Step-0-lettered
probes.
[mechanical] Step 1c — Dormant in-progress detector (Spec 621)
Disjoint sibling of Step 1b by status: Step 1b counts implemented-awaiting-/close; this
step counts in-progress specs that have stopped moving (consumer field case: five specs sat
at in-progress for 142–148 days while /now reported a clean queue — stalling also exempts
them from ranked-backlog scoring). Read the threshold from forge.now.dormant_in_progress_days
in AGENTS.md (default: 21 if absent), then run the delegate:
bash ${CLAUDE_PLUGIN_ROOT:-.}/.forge/lib/dormant-in-progress.sh "" <threshold-days>- Non-zero count → the delegate prints exactly one advisory line
(
Dormant in-progress: <count> spec(s) untouched >Nd — <comma-separated spec IDs>); surface it verbatim adjacent to the Step 1b output. - Zero count, missing/unparseable
Last updated:fields, or delegate absent (consumer mid-template-sync) → silent; this line is advisory, never a gate. Strictly read-only — the check never writes to any spec file and never auto-transitions anything.
<!-- parallel: steps 2-5 are independent reads — run them simultaneously -->- Backlog top-of-queue (Spec 399): Run
${CLAUDE_PLUGIN_ROOT:-.}/.forge/bin/forge-py ${CLAUDE_PLUGIN_ROOT:-.}/.forge/lib/derived_state.py --get-backlog --format=json. Parse the stdout as JSON; the array contains one row per backlog entry with keysrank, spec_id, title, bv, e, r, sr, score, depends, status. Identify the highest-ranked spec with statusdraftorapproved. (Helper internalizes mode-detection + parsing — Spec 399 helper-as-contract; do NOT open canonical files directly in any rendering mode.) - Read docs/sessions/ and find the most recent session log. Check its "Spec triggers" and "Process improvement items" sections for any open items (unchecked boxes).
- Read CLAUDE.md post-implementation checklist and identify any items that appear outstanding based on recent session context.
- Spec index — stale drafts (Spec 399): Run
${CLAUDE_PLUGIN_ROOT:-.}/.forge/bin/forge-py ${CLAUDE_PLUGIN_ROOT:-.}/.forge/lib/derived_state.py --get-spec-index --format=json. Parse the stdout as JSON; identify any spec listed asdraftthat has been sitting without movement. - Session log auto-create: Check
docs/sessions/for a log file matching today's date. If none exists, create a stub fromdocs/sessions/_template.mdwith today's date and the next session number (scan existing files to determine NNN). Report: "Created session log:docs/sessions/YYYY-MM-DD-NNN.md." - Scratchpad review: Read
docs/sessions/scratchpad.mdfor any open notes — list all unresolved items grouped by tag ([validate],[session],[evolve], untagged). 7b. Pending explorations: Scandocs/research/for files matchingexplore-*.md. For each file, check theStatus:field. If any haveStatus: proposed, report:
If no proposed explorations exist or the directory is absent, skip silently.**Pending explorations**: N proposed research artifact(s) in docs/research/ - explore-<topic>.md (proposed, <date>) Active tabs check (Spec 352): Glob
.forge/state/active-tab-*.json(Spec 353 marker primitive). For each marker file, parse the JSON and readlast_command_at. Classify:- active:
last_command_atwithin 30 minutes of now. - stale:
last_command_atolder than 30 minutes. - malformed/unreadable: treat as not-active (skip the file; do not error).
Emit a single one-line surface based on the counts:
- If active count
N == 0: emit nothing (suppress line — single-tab/solo sessions see zero noise, regardless of stale count). - If
N >= 1and stale countM == 0: emitTabs: N active. - If
N >= 1andM >= 1: emitTabs: N active, M stale (run /tab close to clean stale).
This surface is read-only —
/nowdoes not modify, delete, or prompt against marker files. The visibility nudge drives/tab initadoption without imposing per-command friction. 8b. Runbook staleness check (Spec 107): Read all.mdfiles indocs/process-kit/. For each file, look for a<!-- Last updated: YYYY-MM-DD -->comment. If the date is more than 30 days ago (or the comment is missing), flag the runbook as potentially stale:## Stale runbooks The following runbooks have not been updated in 30+ days: - docs/process-kit/<filename>.md — last updated: <date> (<N> days ago)If all runbooks are current, skip silently.
- active:
8d. Aging drafts count surface (Spec 363): Read every docs/specs/[0-9][0-9][0-9]-*.md file with Status: draft in frontmatter. Parse the valid-until: YYYY-MM-DD field, if present. Count drafts whose valid-until: is populated AND past today. Drafts lacking valid-until: (pre-backfill state, missing field, or commented-out) are silent — not counted, not warned.
- If count
N >= 1: emit one lineAging drafts: N past validity — run /matrix to triage via strategic-fit flow. - If count
N == 0(zero populated-and-expired) OR no drafts havevalid-until:populated yet: emit nothing. This surface is read-only and additive./nowdoes not modify any spec frontmatter. Renewal happens via/revise NNN(refreshesvalid-until:) or operator direct edit. Triage of expired drafts happens via/matrixStep 8 strategic-fit flow.
8d2. Vet-pending advisory (Spec 395 AC 12): Scan docs/specs/[0-9][0-9][0-9]-*.md files for frontmatter containing Consensus-Status: vet-pending. Compare today's date against the universal SLA date 2026-06-02 (set by Spec 395 Backfill section).
- If today is on or after 2026-06-02 AND
N >= 1vet-pending drafts exist: emit one lineN drafts vet-pending past 2026-06-02 SLA — vet-now-or-set-Consensus-Exempt at /implement. - Pre-SLA (before 2026-06-02): silent regardless of count.
- Zero vet-pending drafts: silent.
- Sunset reminder: read Spec 395 frontmatter for
Provisional-Until: <date>. Starting D-7 (date − 7 ≤ today ≤ date), emitSpec 395 sunset review due in <N> days — see /evolve.Past the date, the review is overdue; emitSpec 395 sunset review overdue (<N> days) — run /evolve to evaluate the gate.This advisory is read-only and additive — it does not modify any spec frontmatter or block subsequent commands.
Capability surfacing (Spec 471)
8e. Optional-capability count surface (Spec 471): Call bash ${CLAUDE_PLUGIN_ROOT:-.}/.forge/bin/forge-capability.sh pending. This prints a bare integer — the number of registry capabilities that are inactive AND not dismissed (the single source /now quotes; do not recompute it here).
- If the count is greater than zero, emit exactly one line in this format:
N optional capability(ies) available — /configure → Capabilities. - Emit nothing otherwise (count zero, or the helper unavailable).
- This surface is count-only — never enumerate individual capabilities, never emit a per-capability row. It mirrors the unreviewed-digests / aging-drafts count pattern. Activation and dismissal happen via
/configure → Capabilities(the sole write path);/nownever edits.claude/settings.jsonor the registry.
8c. Process-kit external-source freshness check (Spec 278): Read forge.process_kit.freshness_threshold_days from AGENTS.md (default: 180 if absent or unset). Scan .md files under docs/process-kit/ for a <!-- Last verified: YYYY-MM-DD against <source-url> --> marker within the first 10 lines.
- For each file carrying the marker: compare the date to today. If the date is older than the threshold, flag the guide as stale.
- Files without the marker are skipped silently (not every guide needs one — the convention applies only to guides that cite external authorities; see
docs/process-kit/runbook.md§ Process-Kit Doc Freshness Convention). - If any flagged: report
Include a trailing hint: "Revalidate by reading## Stale process-kit guides The following guides cite external authorities but have not been re-verified in <threshold>+ days: - <path> — last verified: <date> (<N> days ago) against <source-url>docs/process-kit/runbook.md§ Process-Kit Doc Freshness Convention." - Public-doc stamp check (Spec 509): additionally run
bash ${CLAUDE_PLUGIN_ROOT:-.}/.forge/lib/freshness.sh check(skip silently if the helper is absent). Each emitted line is a public doc whose Spec 278 marker was stamped STALE at/closebecause a closing spec changed a documented surface (the surface→doc resolution is the Spec 511 canonical mapping, owned by the helper — do not re-inline it here). If any lines emitted, append to the same report:
Re-verify by refreshing the doc and updating its marker (generated docs clear the stamp on regeneration — see the helper header for the generated-doc interaction).## Public docs stamped stale at /close - <doc>:<line> — <stale annotation> - If none flagged, skip silently.
- This is advisory only — it does not block subsequent commands.
- Write context snapshot: After gathering all data above, write
docs/sessions/context-snapshot.md(gitignored) with the following structured sections. This snapshot is used by subsequent commands for display-only lookups, reducing redundant file reads.# Session Context Snapshot Generated: YYYY-MM-DD HH:MM ## Validation queue <list of implemented specs or "empty"> ## Next recommended spec <spec ID, title, score, lane, or "none"> ## Open scratchpad notes <count and summary, or "none"> ## Active tabs <registry summary or "none"> ## Last session log <file path> ## Evolve loop status <last review date, overdue flag> ## Consensus acceptance rate (30d) <one-line figure from forge-py ${CLAUDE_PLUGIN_ROOT:-.}/.forge/lib/acceptance_rate.py, or "n/a"> ## Session identity <confirmed operator name from Step 0b.f>
Then report:
- Validation queue: specs at
implementedawaiting/close(from step 1) — this is the top priority - Active work: any open spec triggers or process improvement items from the last session log that haven't been converted to specs yet
- Agent activity (Spec 134): If
docs/sessions/activity-log.jsonlexists and has entries, read it and summarize events since the last operator session log. Group by agent_id. For each agent: list specs started, specs closed, gates failed, errors. If no activity log or empty, skip silently. - Next recommended spec: the highest-ranked backlog item with status
draftorapprovedthat is ready to implement — state its spec ID, file path, score, and the first implementation step. Only recommend new implementation if the validation queue is empty or the user has deferred validation. - Evolve loop check: state the date of the last evolve loop review (from the most recent session log's
Last evolve loop review:field) and flag if it's overdue (> 30 days) - Active tabs: any other Claude Code tabs with active claims (from step 8) — warn about potential conflicts
- Blockers: anything that must be resolved before the next spec can start
- Consensus acceptance rate (Spec 497 — read side of Spec 495 / Spec 258 AC#5): run
forge-py ${CLAUDE_PLUGIN_ROOT:-.}/.forge/lib/acceptance_rate.pyand surface its one-line rolling-30-day figure (e.g.,Consensus acceptance rate (last 30d): 80% (4/5 accepted; 1 modified, 0 rejected)). When it reportsn/a(no rated decisions in the window), surface that verbatim — never a divide error. This is the rate the operator'sconsensus_trackingconfig (AGENTS.md) defines:accepted / (accepted + modified + rejected).
If no outstanding items exist and the backlog is current, recommend the single highest-value next action. Frame the recommendation as the four-part operator summary (Spec 497 — lean by default; honors forge.output.verbosity; see docs/process-kit/operator-summary-guide.md):
## Recommended next action
### 1. Accomplished & machine-verified
<current state: validation-queue depth, most recent close, acceptance-rate figure from above>
### 2. Needs human validation
<bullet checklist of implemented specs awaiting /close, or "Nothing pending validation.">
### 3. Why it matters
<link the recommended action to the top-ranked backlog objective / roadmap value, using the scoring rubric>
### 4. Recommended next actions
<When a real choice exists (e.g., validate-first vs implement-next): ≥2 options each with pros/cons, then a named recommendation. Otherwise: the single highest-value next step.>The Step 13 context-aware choice block follows this summary.
[mechanical] Step 0e — Release-eligible + deprecation surfacing (Spec 291)
Surface two release-policy signals so they cannot decay silently between tag cuts (see the release policy — FORGE-maintainer reference, not shipped to consumers).
Release-eligible count
Read docs/sessions/signals.md. Count entries matching ^### SIG-[0-9]+-RE
(emitted by /close Step 3d). If the file is missing, count is 0.
- If count is 0: skip silently.
- If count is ≥ 1: emit a single one-line advisory:
N release-eligible spec(s) pending tag cut. See the live release-audit doc (FORGE-maintainer, not shipped) before running scripts/cut-release.sh.
Deprecation warnings
Scan two surfaces for machine-readable deprecation markers (per release-policy.md § Deprecation policy):
- Surface 1 — retired (Spec 558):
copier.ymland its variable-deprecation markers were deleted with the Copier surface in v4.0.0 — nothing to scan. - Surface 2 — slash command files: scan
.claude/commands/*.mdfor files whose YAML frontmatter (between---markers at the top) or first 10 lines containdeprecated: true. Emit one line per match:⚠ Deprecated command: /<name> (deprecated_in: <ver>, removed_in: <ver>) — see release-policy.md.
If .claude/commands/ is absent: skip Surface 2 silently.
These advisories are read-only and non-blocking. They surface twice — once at
/now (for daily visibility) and again at /evolve (during periodic review).
[mechanical] Step 11 — Session log staleness detection (Spec 131, enhanced by Spec 157)
Check docs/sessions/ for the most recent session log. Compare its date to the current time:
- If >2 hours since the session log was last modified (or no log exists for today): flag as stale.
- If 3+ specs have been closed since the last session log update (check CHANGELOG.md for close entries after the log date): flag as stale.
- Spec 157 enhancement: If stale AND accumulated entries exist (structured entries appended by /implement and /close in today's session log), offer "Draft session log?" as a choice block option that triggers
/sessionauto-draft directly — not just "run/session":Session log is stale with N accumulated entries. → **Draft session log?** — `/session` will generate a pre-populated draft for your review. - If stale but no accumulated entries: fall back to "Session log is stale — run
/sessionto update."
[mechanical] Step 11b — Spec 254 Phase 2 #3 burn-in counter (Spec 398)
If docs/.generated/ directory exists (project has migrated to split-file mode per Spec 398), surface the Phase 2 #3 dual-write retirement burn-in status:
- Locate the close date for Spec 398 in
docs/specs/CHANGELOG.md(line- YYYY-MM-DD: Spec 398 closed.). If absent, skip silently — burn-in starts after close. - Count
closed (YYYY-MM-DD …)entries indocs/specs/CHANGELOG.mdwhose date is strictly after the Spec 398 close date. Cap at 10. Call thisN. - Count operator-reported renderer-output bugs:
- Session-log
## Error autopsiesentries taggedrenderer-outputacross alldocs/sessions/*.md. - Specs with
Trigger: error found in chatwhose body references a renderer or assembler bug (string match:render_backlog,render_changelog,render_spec_index,assemble_view). Sum isM.
- Session-log
- Emit a one-line status:
- If
N < 10ORM > 0:Spec 254 Phase 2 #3 burn-in: N/10 closes accrued, M operator-reported renderer bugs (see docs/specs/398-*.md). - If
N >= 10ANDM == 0:Phase 2 #3 burn-in: COMPLETE — eligible for /spec.
- If
Skip silently if docs/.generated/ is absent.
[mechanical] Step 11c — Session-log signal-propagation drift detector (Spec 452, advisory)
Check whether any session-log EA/CI entries are missing from the persistent logs (the drift class Spec 452 closed — signals.md drift makes /evolve pattern analysis blind to session-log signals):
# Spec 473 recency cap: scan only the last 30 days of session logs so this
# advisory check on the highest-frequency command stays O(recent), not
# O(project age). Compute the cutoff as today minus 30 days (ISO YYYY-MM-DD).
SINCE=$(${CLAUDE_PLUGIN_ROOT:-.}/.forge/bin/forge-py -c "import datetime; print((datetime.date.today() - datetime.timedelta(days=30)).isoformat())")
${CLAUDE_PLUGIN_ROOT:-.}/.forge/bin/forge-py scripts/migrate-spec-452-backfill-orphaned-signals.py --dry-run --since="$SINCE"Read the final DONE | dry-run: summary line:
- If
0 would be appended: skip silently — no drift. - If N > 0: emit one advisory line:
Signal-propagation drift: N orphaned EA/CI entries/stubs in session logs not yet in the persistent logs (scanned last 30 days; run the script unscoped with --dry-run for a full audit). Run the Spec 452 migration script with --apply, or let the next /close Step 5d propagate today's entries.
This is advisory only — never blocks, never auto-applies. The 30-day recency cap (Spec 473) scopes only this advisory invocation; bare --dry-run / --apply and the one-shot backfill remain unscoped. Skip silently if the script is absent (pre-Spec-452 consumer project).
[mechanical] Step 12 — Evolve loop trigger detection (Spec 131, enhanced by Specs 157, 193)
Check signal-based triggers for the evolve loop. Thresholds are read from the canonical source
forge.evolve.signal_thresholds in AGENTS.md (Spec 500 R8 — the SAME source /evolve --auto
admission reads; do NOT re-inline the numbers here). docs/sessions/evolve-config.yaml, if present,
may still override per-project.
Signal-based triggers (composable — ANY threshold crossed fires the recommendation). Each count is measured since the last review date (see below) and compared to its canonical threshold:
- Unreviewed signals: entries in
docs/sessions/signals.mdadded after the last review date →signal_thresholds.unreviewed_signals. - Open scratchpad notes: unchecked
[evolve](or[outer-loop]) items indocs/sessions/scratchpad.md→signal_thresholds.open_evolve_scratchpad. - Error autopsies: error-autopsy entries in session logs since the last review →
signal_thresholds.error_autopsies. - Deferred scope items: "Out of scope" items across closed specs since the last review dispositioned "deferred" (not "dropped") →
signal_thresholds.deferred_scope_items. - Spec velocity: specs closed since the last review (from CHANGELOG.md) →
signal_thresholds.spec_velocity.
Soft time fallback (recommendation only — Spec 500 R3/R5): if the last review date is older than
forge.evolve.time_fallback_days (default 30) or blank, include the evolve recommendation as a safety
net. This is a recommendation, never a hard "overdue" admission block — /now does not block on it and
it never contradicts an admitted /evolve (the calendar review-gate was retired by Spec 500 / ADR-500).
Single last-review source (Spec 500 R6a): read the last review date from
docs/sessions/evolve-state.md last_evolve_loop_run: — the one canonical source. Do NOT also read
.forge/state/evolve-cool-down.json (retired) as a second source; reading two divergent date sources was
the EA-431 drift defect this spec fixes.
- If any threshold is crossed: report which triggers fired:
Add to the choice block: "Evolve loop triggered — runEvolve loop recommended — <N> trigger(s) crossed: - Unreviewed signals: <count>/<threshold> - Spec velocity: <count>/<threshold>/evolve." - If no thresholds crossed: skip silently.
- Spec 157 escalation: Track how many consecutive
/nowinvocations have flagged the evolve loop (check context-snapshot.md for a## Evolve loop overdue countfield). If flagged 2+ times without action:- Escalate visibility: present the warning in bold at the top of /now output, not just in the choice block:
**EVOLVE LOOP OVERDUE** — last review: <date> (<N> days ago). Flagged <M> times without action. Run `/evolve --full` to address. - Update the overdue count in context-snapshot.md.
- Escalate visibility: present the warning in bold at the top of /now output, not just in the choice block:
[mechanical] Step 13 — Context-aware choice block (Spec 131; convention v2.0 per Spec 320)
<!-- safety-rule: session-data — if today's session log has unsynthesized spec activity AND ## Summary is unpopulated, /session is inserted at rank 1 and stop is downgraded to —. See docs/process-kit/implementation-patterns.md § Session-data safety rule. -->At the end of every /now invocation, present a numbered choice block based on current context. Build the options dynamically using the v2.0 convention (Rank + Rationale columns; ≤80 char rationale; — for unranked):
> **Choose** — type a number or keyword:
> | # | Rank | Action | Rationale | What happens |
> |---|------|--------|-----------|--------------|Always include these options (numbered dynamically based on which apply). Default ranks (override per session-data safety rule):
- If implemented specs exist:
close NNN— rank1, rationale "Closure first; clears the validation queue" — Run/close NNNto validate and close - If draft/approved specs exist in backlog:
implement— rank1if no validation queue else2, rationale "Top-of-backlog ready; clean transition" — Run/implement nextfor the top-ranked spec. Read the top-ranked spec file (docs/specs/NNN-*.md) and append its objective as a sub-line: "<first sentence from the spec's ## Objective section>" - If session log is stale (from Step 11):
session— rank1if safety rule fires (see above) else2, rationale "Synthesize before next work" — Run/sessionto update the session log - If evolve loop is overdue (from Step 12):
evolve— rank2, rationale "Process review; cumulative signal threshold crossed" — Run/evolvefor process review - If backlog is empty or has no draft specs:
brainstorm— rank2, rationale "Discover next work when backlog is dry" — Run/brainstormto discover new spec opportunities - If evolve loop is overdue OR knowledge consolidation may help (Spec 328):
synthesize --postmortem— rank—, rationale "Consolidate accumulated knowledge into a refined reference doc" — Run/synthesize --postmortem(default mode hint; operator can pick--decisions,--topic <theme>,--architecture, or--allinstead) - Always:
stop— rank—(always unranked; session-data safety rule may further downgrade), rationale "No action needed right now" — End the /now invocation
Session-data safety rule (Spec 320 Req 4): Before emitting the choice block, evaluate today's session log per the positive "populated Summary" definition (heading present + ≥1 non-placeholder body line). If the rule fires (unsynthesized spec activity AND Summary unpopulated): insert session at rank 1, downgrade stop to —. The dynamic options above are the normal presentation; when the rule fires, prepend a session row at rank 1.
Present only the options that apply to the current context. Number them sequentially starting from 1. Each option carries an explicit Rank cell (1, 2, …, or —) and a Rationale cell ≤80 chars (use — if it would echo the Action label).
After the choice block, include the footer:
(See Command Reference for all commands)
[mechanical] Tab-lane awareness directive (Spec 351)
Before emitting any next-action choice block in this command, consult the active-tab marker (Spec 353 primitive):
- Read
.forge/state/active-tab-*.json(primary). If present, extractlane. Iflast_command_at> 30 minutes ago, treat marker as stale. - If no marker, fall back to
docs/sessions/registry.mdrows withStatus = activefor the current session. Use the row'sLanecolumn. - If neither yields an active lane: emit the choice block as today. No preamble, no filtering, no annotation. Skip the rest of this directive.
- If an active lane is detected: emit the one-line preamble (
Tab lane: <lane>. Options below filtered to lane scope./... Cross-lane options annotated./... (stale ~Nm)...) and apply the filter/annotate decision rules fromdocs/process-kit/tab-lane-awareness-guide.md§ Per-lane decision rules. - Filtered rows are struck through with rank
—(not silently dropped) so the operator can override by typing the keyword directly.
The guide is the single source of truth for which rows filter vs annotate per lane. This directive is intentionally short — the central guide encodes the rules so every emitter stays consistent.
[mechanical] Reconcile-pending surfacing (Spec 577)
If .forge/state/reconcile-pending.json exists: emit one line in the report —
Reconcile pending (planted by <planted>): seed the spec corpus with /reconcile (scopes: last-90-days | last-200-commits | full-history), or dismiss by deleting .forge/state/reconcile-pending.json.
Delete nothing automatically; /reconcile completion removes the marker (or the operator dismisses).
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

