imperatives

SKILL.md

/imperatives

Extract atomic imperatives (MUST/SHOULD/MAY) from markdown instruction files into JSONL.

Usage

/imperatives                                # default: ai-workspace/rules/*.md + AGENTS.md
/imperatives .claude/rules/*.md             # specific globs
/imperatives --output imperatives.jsonl     # write to file

Steps

Resolve files. Default: ai-workspace/rules/*.md and AGENTS.md. Expand globs to absolute paths. Zero matches → error, stop.

Pass 1 — Script extraction (fast, deterministic).

node --import tsx "${SKILL_DIR}/scripts/extract-imperatives.ts" <files...> --output /tmp/imperatives-pass1.jsonl

${SKILL_DIR} = this skill's base directory (shown in the "Base directory for this skill:" header above). Keyword-based: catches RFC 2119 terms + imperative verbs. ~80% coverage, <1s.

Pass 2 — Subagent reasoning (catches implicit imperatives).
For each file, dispatch a subagent to identify imperatives the regex missed — contextual rules, implicit constraints, prose-embedded obligations.

Subagent prompt:

Read <file>. Here are the imperatives already extracted by the script for this file:

<pass 1 JSONL lines where source.file matches>

Identify additional imperative statements the regex missed. Look for:

Implicit obligations hidden in prose (e.g., "The workflow is a menu, not a pipeline" implies MUST NOT enforce order)

Contextual constraints (e.g., section context that makes a statement imperative)

Conditional rules not triggered by keyword patterns

For each new imperative found, output one JSON line (same schema — id, level, polarity, subject, predicate, when, source, tool_scope, tags, raw).
Do NOT duplicate entries already in pass 1. If none found, output nothing.

Use subagent_type: "explorer" (Haiku) for most files. If a file had zero pass-1 imperatives OR contains dense prose (>50 lines without a keyword match), escalate that file to Sonnet for deeper reasoning.

Merge passes. Concatenate pass 1 + pass 2 outputs. Deduplicate by raw text. Write final output to --output <path> or present inline.

Present summary. Report in a table:

Total count (pass 1 baseline + pass 2 additions)

Breakdown by level and tool_scope

Files with zero imperatives after both passes

Pass 2 additions highlighted separately

Downstream callers. If invoked by /policy-algebra or /distill, return the JSONL path directly — skip the summary.

Failure modes

Condition
Behavior

No files matched
Error message. Stop.

File not found
Script warns on stderr, continues with remaining files.

Zero imperatives
Report zero. Not an error.

Script exits non-zero
Surface stderr to user.

Cross-tool notes

Codex / Cursor: run the script directly — it's tool-agnostic.