Skip to content

usage-rules.md

Latest commit

 

History

History
344 lines (260 loc) · 16.2 KB

usage-rules.md

File metadata and controls

344 lines (260 loc) · 16.2 KB

Intent Usage Rules

Intent is a CLI tool for managing steel threads, work packages, project artifacts, coding rules, and LLM guidance for software projects.

This file is the prescriptive DO / NEVER contract for working with Intent. Narrative, rationale, and FAQs live in intent/docs/working-with-llms.md. Project navigation lives in AGENTS.md. Each file has one job.

Project Structure

An Intent project has this layout:

my-project/
├── AGENTS.md                  # Tool-agnostic LLM config (auto-generated by `intent agents sync`)
├── CLAUDE.md                  # Claude-specific overlay (imports AGENTS.md)
├── usage-rules.md             # Prescriptive DO / NEVER rules (this file)
├── CHANGELOG.md
├── .claude/
│   ├── settings.json          # Session hooks (SessionStart, UserPromptSubmit, Stop)
│   ├── agents/                # Installed Claude subagents
│   └── skills/                # Installed Claude skills
├── .git/hooks/pre-commit      # Critic gate (runs bin/intent_critic on staged files)
├── .intent/
│   └── config.json
├── .intent_critic.yml         # Critic config (severity threshold, disabled rules)
├── intent/
│   ├── st/                    # Steel threads
│   │   ├── ST0001/
│   │   │   ├── info.md        # Required (title, status, dates, description)
│   │   │   ├── design.md
│   │   │   ├── impl.md
│   │   │   ├── tasks.md
│   │   │   └── WP/01/info.md  # Work packages
│   │   └── CANCELLED/ST####/  # Cancelled threads with inline deprecation note
│   ├── llm/                   # Internal enforcement (human-curated)
│   │   ├── MODULES.md         # Highlander registry
│   │   └── DECISION_TREE.md   # Code placement flowchart
│   ├── docs/                  # Technical docs (including working-with-llms.md)
│   ├── .treeindex/            # Directory summaries (committed)
│   ├── wip.md                 # Current work in progress
│   └── restart.md             # Session restart context

Status values for steel threads and work packages: WIP, Completed, Not Started, On Hold, Cancelled.

Core Commands

Steel threads and work packages

intent st new "Title"
intent st list
intent st show ST0001
intent st start ST0001
intent st done ST0001
intent st cancel ST0001

intent wp new ST0001 "Title"
intent wp list ST0001
intent wp show ST0001/01
intent wp start ST0001/01
intent wp done ST0001/01

Specifiers accept bare numbers (5 = ST0005; 5/01 = ST0005/01). Leading zeros parse as octal in bash — use ST0035 or 35, never 0035.

AGENTS.md

intent agents init                              # Create AGENTS.md at project root
intent agents init --template <lang>            # Language-specific scaffold
intent agents sync                              # Update AGENTS.md from project state
intent agents validate                          # Check compliance

AGENTS.md is a real file at the project root (not a symlink). Regenerate with intent agents sync; never edit manually.

Claude subagents

intent claude subagents list
intent claude subagents install <name>
intent claude subagents install --all
intent claude subagents sync
intent claude subagents uninstall <name>
intent claude subagents show <name>
intent claude subagents status

Installs to ~/.claude/agents/<name>.md. Mid-session installs are not visible to Task() until the next Claude Code session starts — the subagent registry is read once at startup.

Claude skills

intent claude skills list
intent claude skills install <name>
intent claude skills install --all
intent claude skills sync
intent claude skills uninstall <name>
intent claude skills show <name>

Installs to ~/.claude/skills/<name>/SKILL.md. Skills auto-load into every Claude Code session.

Rule library

intent claude rules list                        # Enumerate all rules (canon + extensions)
intent claude rules show <id>                   # Print full RULE.md for an ID
intent claude rules validate                    # Schema + attribution + runnable-example check
intent claude rules index                       # Regenerate rules/index.json

Rule IDs use the form IN-<LANG>-<CAT>-<NNN> (eg IN-EX-CODE-006, IN-AG-HIGHLANDER-001). Library root: intent/plugins/claude/rules/.

Extensions

intent ext list
intent ext show <name>
intent ext validate [<name>]
intent ext new <name> --subagent | --skill | --rule-pack

User extensions live at ~/.intent/ext/<name>/ and contribute subagents, skills, or rule packs without forking Intent. Extension items shadow canon by name (subagents / skills) or by rule id: (rules), with a visible shadow warning. Set INTENT_EXT_DISABLE=1 to revert to canon-only for a command.

Treeindex

intent treeindex <dir>                          # Generate directory summary
intent treeindex <dir> --check                  # CI-friendly staleness check
intent treeindex <dir> --prune                  # Remove orphaned summaries
intent treeindex <dir> --depth 3                # Control depth (default 2)
intent treeindex <dir> --force                  # Regenerate unconditionally

Treeindex files live at intent/.treeindex/<dir>/.treeindex. Check .treeindex before exploring an unfamiliar directory. Never run on project root — target subdirectories.

Other

intent init                                     # Initialise new Intent project
intent doctor                                   # Config + dependency health check
intent info
intent version
intent upgrade                                  # Apply pending migration(s)
intent claude upgrade [--apply]                 # Install/refresh canon LLM config
intent plugin                                   # Discover plugins and their commands
intent help [<command>]

Skills

All skills install to ~/.claude/skills/<name>/SKILL.md and auto-load into every Claude Code session.

Skill Purpose
/in-session Session bootstrap — loads language-appropriate skills after /compact
/in-essentials Intent workflow rules (CLI discipline, tracking hygiene)
/in-standards Agnostic coding discipline (Highlander, PFIC, Thin Coordinator)
/in-start Start a new steel thread from an idea
/in-next Pick the next WP/task by scanning wip.md and open STs
/in-plan Produce a plan before touching code
/in-review Two-stage review — general reviewer + language-specific critic
/in-verify Verification gate before declaring a task done
/in-debug Systematic debugging flow
/in-finish Session wrap-up — updates wip.md, restart.md, prompts for commit
/in-handoff Hand session context off for a future session
/in-detrope Trope detection and remediation
/in-autopsy Post-session autopsy for recurring corrections
/in-cost-analysis Analyse session costs
/in-elixir-essentials Elixir code rules
/in-elixir-testing Elixir test rules
/in-ash-ecto-essentials Ash + Ecto conventions
/in-phoenix-liveview Phoenix + LiveView patterns
/in-tca-init TCA (Targeted Codebase Audit) provisioning
/in-tca-audit TCA audit execution
/in-tca-synthesize TCA synthesis step
/in-tca-remediate TCA remediation step
/in-tca-finish TCA wrap-up

Run /in-session immediately after /compact, any context reset, or at session start.

Subagents

All subagents install to ~/.claude/agents/<name>.md and run in separate context windows via the Task() tool.

Subagent Role
intent Intent methodology and CLI usage
socrates CTO Review Mode — Socratic dialog between CTO (Socrates) + Tech Lead (Plato)
diogenes Elixir Test Architect — Aristotle + Diogenes; spec generation / validation
critic-elixir Elixir rule-library critic (code + test modes)
critic-rust Rust rule-library critic (code + test modes)
critic-swift Swift rule-library critic (code + test modes)
critic-lua Lua rule-library critic (code + test modes)
critic-shell Shell (bash + zsh) rule-library critic (code mode only)

Socrates and Diogenes are disjoint agents — different domains, different personas. Socrates is architectural; Diogenes is test-specification. See intent/docs/working-with-llms.md for the FAQ.

Extension subagents (not canon): worker-bee — install via intent claude subagents install worker-bee after upgrading to v2.9.0 (the seed is staged automatically).

Rule Library

Single source of truth for coding rules. Critic subagents read the library at invocation time, apply each rule's Detection heuristic to target files, and report findings by severity. Rules never autofix.

  • Library root: intent/plugins/claude/rules/<lang>/<category>/<slug>/RULE.md.
  • Categories: code, test, plus Elixir-specific ash, phoenix, lv.
  • Agnostic rules apply everywhere: intent/plugins/claude/rules/agnostic/ (Highlander, PFIC, Thin Coordinator, No Silent Errors).
  • Schema: intent/plugins/claude/rules/_schema/rule-schema.md.
  • Authoring guide: intent/docs/rules.md.
  • Critic contract: intent/docs/critics.md.

Per-project rule overrides go in extensions (~/.intent/ext/*/rules/), not by editing canon.

Critics and pre-commit

Critics enforce rules at two points:

  1. Pre-commit hook (.git/hooks/pre-commit) — runs bin/intent_critic <lang> <staged-files> on every commit. Blocks on severity at or above threshold.
  2. On-demand — Task(subagent_type="critic-<lang>", prompt="review <targets>") from Claude Code. prompt="test-check <targets>" for test-mode.

Per-project config at project root: .intent_critic.yml:

Key Value Default
severity_min critical | warning | recommendation | style warning
disabled List of rule IDs to suppress []
show_all Shorthand for severity_min: style false

Full contract in intent/docs/critics.md.

Session Hooks

.claude/settings.json wires Claude Code lifecycle hooks:

  • SessionStart (startup, resume, clear, compact) — injects a brief project context reminder.
  • UserPromptSubmit (strict gate) — blocks the first user prompt until /in-session has run in the conversation.
  • Stop — injects a /in-finish reminder at session end.
  • PostToolUse on Write|Edit — optional advisory critic (off by default; opt-in via .intent_critic.yml).

Hook templates ship with Intent (lib/templates/.claude/settings.json) and are applied to target projects via intent claude upgrade --apply.

LLM Guidance Files (the three-file canon)

Every Intent project has three root-level LLM config files:

AGENTS.md — tool-agnostic, auto-generated

Read by every agentic tool (Claude Code, Codex, Cursor, Aider, Continue, Gemini CLI, ...). Contains project overview, build/test commands, coding conventions summary, steel-thread process, installed skills/subagents, rule-library pointer, critic-invocation example. Auto-generated by intent agents sync; never edit manually.

CLAUDE.md — Claude-specific overlay

Short. Imports AGENTS.md by reference; adds Claude-specific directives: memory dirs, /in-session auto-load pointer, .claude/settings.json hook pointer. Hand-edited after initial scaffold.

usage-rules.md — prescriptive DO / NEVER

This file. Elixir-ecosystem-aligned (mix usage_rules.sync discoverable). Terse and imperative. Narrative content belongs in intent/docs/working-with-llms.md.

Internal (in intent/llm/)

  • MODULES.md — Highlander module registry (where every concern lives).
  • DECISION_TREE.md — code-placement flowchart.

Steel Thread Methodology

Creating a steel thread

  1. intent st new "Title" — CLI creates the directory and info.md.
  2. Fill in objective, context, related threads in info.md.
  3. For work-packaged STs: intent wp new <STID> "Title" per WP.
  4. Track tasks in tasks.md; design in design.md; as-built in impl.md.

Working a steel thread

  1. intent st start <STID> — flips status to WIP.
  2. Work through WPs in tasks.md dependency order.
  3. intent wp start <STID/NN> and intent wp done <STID/NN> per WP.
  4. On completion: intent st done <STID>.

Frontmatter

---
verblock: "DD Mon YYYY:vX.Y: author - Description"
intent_version: 2.9.1
status: WIP
created: YYYYMMDD
completed:
---

Common Workflows

Start a new project

intent init
intent agents init --template <lang>
intent claude skills install --all
intent claude subagents install --all
intent claude upgrade --apply                   # Install hooks, pre-commit, critic config

Start a coding session

/in-session                                      (auto-loads language-appropriate skills)

Review code before commit

/in-review                                       (Stage 1 reviewer + Stage 2 language critic)

Session wrap-up

/in-finish                                       (updates wip.md + restart.md, prompts commit)

See also

  • AGENTS.md — project navigation (auto-generated)
  • CLAUDE.md — Claude-specific scaffold
  • intent/docs/working-with-llms.md — LLM workflow narrative (rationale, FAQs, long-form)
  • intent/docs/rules.md — rule authoring guide
  • intent/docs/critics.md — Critic contract and report format
  • intent/docs/writing-extensions.md — extension authoring
  • intent/llm/MODULES.md — Highlander module registry
  • intent/llm/DECISION_TREE.md — code-placement flowchart

NEVER DO

  • Never edit AGENTS.md directly — it is auto-generated by intent agents sync.
  • Never run intent treeindex on the project root — target subdirectories.
  • Never create steel thread or work package directories manually — use intent st new and intent wp new.
  • Never manually edit status: fields in info.md frontmatter — use intent st start | done | cancel and intent wp start | done.
  • Never modify .intent/config.json manually — use intent commands.
  • Never delete .treeindex files without running --prune first.
  • Never edit .claude/settings.json hook stanzas directly — update lib/templates/.claude/settings.json and re-run intent claude upgrade --apply.
  • Never bypass .git/hooks/pre-commit with --no-verify on shared branches without an explicit justification in the commit message.
  • Never use leading zeros for ST or WP specifiers (ST0035 or 35, never 0035) — leading zeros parse as octal in bash.
  • Never manually wrap lines in markdown files — let the renderer handle it.