import-rules

name

import-rules

description

Extract development rules from a repository's agent-instruction files (CLAUDE.md, AGENTS.md, AGENT.md), the markdown they reference, and known rule locations like .cursor/rules and CONTRIBUTING.md, then upload them via `straion import-rules`. Use when the user asks to "import rules", "analyze this repo", "extract coding standards", "scan for conventions", when starting on an unfamiliar repository, or when the `straion` CLI hands off to the agent as part of its import flow.

Import Rules

Pipe rule collections extracted from this repo's instruction files to straion import-rules. Rules describe how code is written — never what or why. Tell the user up front: "Looking for rules…"

1. Precheck

Skip if the invocation includes --skip-precheck or --force. Otherwise:

straion import-rules --precheck

• No existing rules found → continue.

• Found N rule collection(s) → ask verbatim:

  This repository already has N rule collection(s). Do you want me to re-import them? (y/n)

  On y, forward --force to step 4. Anything else, stop.

2. Discover sources

• Seed: CLAUDE.md, AGENTS.md, AGENT.md at repo root.
• Follow references (≤ 2 hops): local .md/.mdc reached via markdown links [x](path) or @path imports. Dedupe by absolute path.
• Probe siblings: .cursor/rules/*.mdc, .cursorrules, .windsurfrules, .clinerules, .github/copilot-instructions.md, CONTRIBUTING.md, STYLEGUIDE.md, CODESTYLE.md (root only).

Classify each:

• Directive (uses must/should/never/always/do not/prefer, or bulleted conventions) → include.
• Narrative (overviews, "why" docs, changelogs) → skip.
• Ambiguous (mixed, e.g. README with a Conventions section) → hold.

Print the set with ✓ / ? markers and ask which ambiguous files to include. If the final set is empty, stop — do not invent rules from source code.

3. Extract

Group rules into collections by domain ("React Patterns", "Testing", …). Split if a collection would exceed ~30 rules. Emit one collection per JSON line (step 4); omit any field you have no information for:

{
  "name": "React Patterns",
  "description": "Component, hook, and state conventions.",
  "meta": { "tags": ["style"], "frameworks": ["react"] },
  "rules": [
    {
      "statement": "MUST use function components; class components are not allowed.",
      "meta": { "tags": ["style"], "languages": ["typescript"] },
      "examples": [
        { "kind": "violating", "code": "class Btn extends React.Component {}" },
        { "kind": "compliant", "code": "const Btn = () => <button />" }
      ]
    }
  ]
}

• name: plain text ≤ 150 chars. description: GFM markdown — scope, when it applies, why it matters.
• statement: exactly one directive, beginning with the uppercase strength word MUST / MUST NOT / SHOULD / SHOULD NOT / MAY, then the imperative, ending in a period.
  • Verb-first. Source docs are subject-first ("Field names should be lowerCamelCase", "List must use GET"); drop the subject and fold it into the predicate → SHOULD use lowerCamelCase for field names. / MUST use the HTTP GET method for the List method.
  • One directive per rule — never join clauses with "and". Split every compound, including same-strength pairs and especially mixed-strength ones: validation only reads the first word, so SHOULD avoid combination, MUST NOT use allOf silently buries a MUST NOT. Emit two rules instead — a SHOULD and a MUST NOT.
  • Preserve strength exactly. Map synonyms REQUIRED/SHALL→MUST, RECOMMENDED→SHOULD, OPTIONAL→MAY. Capture MAY/optional directives too, not only MUST/SHOULD.
  • Fold any condition ("in test files, …") into the sentence.
• meta.tags: ≥ 1 on both collection and rule. Open vocab — e.g. architecture, security, performance, style, testing, documentation, accessibility, dependencies, observability.
• meta.languages / meta.frameworks: omit when language/framework-agnostic; set on the collection only when every rule shares that scope.
• examples: include when the source shows code — { "kind": "compliant"|"violating", "code": "…", "explanation"?: "…" }. Keep code minimal; omit if none shown.
• Never emit $schema, id, meta.rev, or provenance — the CLI sets those.

Extract only from the discovered sources. Skip narrative paragraphs even inside an included file.

Work one source file at a time. Scan each for every MUST / MUST NOT / SHOULD / SHOULD NOT / MAY / REQUIRED / SHALL / RECOMMENDED / OPTIONAL — each is at least one rule. Long enumerative files (header lists, field tables, status-code sections) lose tail items, so before leaving a file confirm every directive keyword in it maps to a rule. If two sources state conflicting strengths for the same rule, capture both and flag the conflict to the user instead of silently choosing one.

4. Upload

NDJSON on stdin, one collection per line. Add --force if step 1 required it.

straion import-rules <<'EOF'
{"name":"React Patterns","description":"…","meta":{"tags":["style"]},"rules":[…]}
{"name":"API Design","description":"…","meta":{"tags":["architecture"]},"rules":[…]}
EOF

The CLI validates each line and prints a per-collection summary. On failure, re-run with --force and only the failed collections.