fireman

Imported from Eveheeero/fireman (AGENTS.md). Install upstream with npx skills add Eveheeero/fireman. Copyright stays with the author.

Fireman AI Agent Guide

Default

• Using cargo b and cargo t helps to void lag when didn't touch firebat directory.
• Formatting uses cargo +nightly fmt
• To avoid context overflow from voluminous logs, use regular expressions to filter and retrieve only the necessary segments for analysis.

.fb Pattern Policy

• COMMENT ONLY ANALYZATION NOT ALLOWED. INLINE FUNCTION ONLY OR FLAG ONLY TOO.
• Centralize predefined .fb pattern and script registration in fireball/src/abstract_syntax_tree/optimize/pattern_matching.rs.
• Instead, rewrite IR or AST to human readable structure.
• Wrtie .fb file with DSL in pattern_matching and .rs at fireball::abstract_syntax_tree::optimize::pattern_matching::embedded both.
• You can use rhai script and can modify .fb DSL to make general methods.
• If a rewrite cannot be expressed with the existing general pattern engine, keep it in Rust until a general-purpose pattern feature exists.
• Always keep patterns/examples/all_syntax.fb up to date when adding or changing .fb DSL syntax. This file is the canonical reference for all supported directives.
• Every new or changed DSL directive MUST have a test at each fireball::abstract_syntax_tree::optimize::pattern_matching::embedded.

Code Style Guidelines

General Conventions

• Persona: Adhere to the ODIN (Outline Driven INtelligence) persona defined in AGENTS.md.
  • Execute with precision and surgical accuracy.
  • No emojis in code, comments, or commit messages.
  • Reason deeply before acting using diagrams.
• File Organization:
  • Use camel_case for directory and file names (e.g., outline_driven_development, agent_heuristics.md).
  • Temporal Files: ALL temporal artifacts for outline-driven development MUST use .outline/ directory. Use /tmp for scratch work.
• Indentation & Formatting:
  • Markdown: Use ATX headers (#, ##). Max line length 100 characters where feasible.

Operational Rules

Diagram-First Reasoning

MANDATORY: Before complex implementation, reason through:

1. Architecture: Components, interfaces, contracts.
2. Data Flow: Sources, transformations, sinks.
3. Concurrency: Threads, sync, race prevention.
4. Memory: Ownership, lifetimes, safety.
5. Optimization: Bottlenecks, complexity targets.
6. Tidiness: Naming, structure, minimal complexity.

Tool Selection Strategy

• Search/Discovery: Use fd (Primary) and ripgrep (rg).
• Code Edit: Use ast-grep (Structure) and srgn (Grammar-Regex).
• Context: Use repomix to pack/analyze codebases.
• Banned Tools:
  • ls → USE eza
  • find → USE fd
  • grep → USE rg or ast-grep
  • cat → USE bat
  • sed → USE srgn or ast-grep

Git Protocol (Branchless)

• Strategy: Git = Source of Truth. Work in detached HEAD for anonymous commits.
• Atomic Commits: One logical change per commit. Tests pass in isolation.

Verification & Refinement

Three-Stage Protocol:

1. Pre-Action: Verify file locations, patterns, and scope.
2. Mid-Action: Verify state consistency and ability to rollback.
3. Post-Action: Verify changes applied correctly, tests pass, no regressions.

Risk Scoring:

• Low: Standard verification.
• Medium: Progressive refinement (MVC → 10% → 100%).
• High: Plan first, extensive testing.

Post-Transform Check:

• Run ast-grep -U to apply changes.
• Use difft --display inline to verify diffs.

UI/UX Design Guidelines

• Design Tokens: MUST use design system tokens, not hardcoded values.
• Density: Target 2-3x denser layouts. Use spacing scales (4/8/12/16/24px).
• Paradigms: Post-minimalism, Neo-brutalism, Glassmorphism. Avoid boring minimalism.
• Forbidden:
  • Purple-blue/purple-pink colors.
  • transition: all.
  • font-family: system-ui.
  • Gradients on buttons/titles (unless requested).
• Quality Gate: Design excellence ≥ 95% (compliance, accessibility, performance).

Good Coding Paradigms

• Contract-first Development: Define preconditions, postconditions, and invariants explicitly.
• Immutable-first Data: Default to immutable data structures. Mutations explicit and localized.
• Zero-allocation/Zero-copy: Prefer zero-allocation hot paths. Use arena allocators, object pools.
• Fail-Fast: Detect errors early, fail immediately with context. Typed error domains.
• Principle of Least Surprise: Code should behave as readers expect. Explicit over implicit.

Structure Paths (fireball)

Major Structs (quick reference)

• Address - fireball/src/core/address.rs
• Instruction - fireball/src/core/instruction.rs
• Section / Sections - fireball/src/core/section.rs, fireball/src/core/sections.rs
• Block / Blocks - fireball/src/core/block.rs, fireball/src/core/blocks.rs
• Relation / Relations - fireball/src/core/relation.rs, fireball/src/core/relations.rs
• PreDefinedOffset / PreDefinedOffsets - fireball/src/core/pre_defined_offset.rs, fireball/src/core/pre_defined_offsets.rs
• Pe - fireball/src/pe/mod.rs
• VirtualMachine, IrBlock, Ir - fireball/src/ir/mod.rs
• Register - fireball/src/ir/register.rs
• IrDataAccess - fireball/src/ir/data.rs
• IrStatementDescriptor / IrStatementDescriptorMap<T> - fireball/src/ir/utils.rs
• IrVariable, BlockGrouper, BlockGroup, KnownDataType, IrFunction, IrFunctionVariable - fireball/src/ir/analyze/...
• Ast, AstFunction, AstVariable, AstParameter - fireball/src/abstract_syntax_tree/objects/...
• AstPrintConfig, AstOptimizationConfig - fireball/src/abstract_syntax_tree/objects/...
• WrappedAstStatement, Wrapped<T>, AstDescriptor - fireball/src/abstract_syntax_tree/objects/wrapper.rs
• AstPattern, AstPatternRule, AstPatternIrReplacement, AstPatternAsmData, AstPatternAstData, AstPatternIrData, AstPatternScript, AstPatternRange - fireball/src/abstract_syntax_tree/optimize/pattern_matching.rs
• VersionMap<..> - fireball/src/utils/version_map.rs
• AstFunction - fireball/src/abstract_syntax_tree/objects/function.rs

Entry points

• Fireball (enum) - fireball/src/lib.rs
• Common imports - fireball/src/prelude.rs

Core (fireball/src/core)

• Module exports - fireball/src/core/mod.rs
• Fire (trait) - fireball/src/core/fire.rs
• FireRaw (trait) - fireball/src/core/fire_raw.rs
• Address - fireball/src/core/address.rs
• Instruction - fireball/src/core/instruction.rs
• Section - fireball/src/core/section.rs
• Sections - fireball/src/core/sections.rs
• Block - fireball/src/core/block.rs
• Blocks - fireball/src/core/blocks.rs
• Relation - fireball/src/core/relation.rs
• Relations - fireball/src/core/relations.rs
• DestinationType (enum) - fireball/src/core/relation.rs
• RelationType (enum) - fireball/src/core/relation.rs
• PreDefinedOffset - fireball/src/core/pre_defined_offset.rs
• PreDefinedOffsets - fireball/src/core/pre_defined_offsets.rs

PE (fireball/src/pe)

• Pe - fireball/src/pe/mod.rs

Arch -> IR (fireball/src/arch)

• asm to IrStatement conversion - fireball/src/arch/x86_64/instruction_analyze.rs
• statement/data shortcuts - fireball/src/arch/x86_64/instruction_analyze_shortcuts/...

IR (fireball/src/ir)

• Module exports - fireball/src/ir/mod.rs
• VirtualMachine - fireball/src/ir/mod.rs
• IrBlock - fireball/src/ir/mod.rs
• Ir - fireball/src/ir/mod.rs
• Architecture (enum) - fireball/src/ir/mod.rs
• Register - fireball/src/ir/register.rs
• IrStatement (enum) - fireball/src/ir/statements.rs
• IrStatementSpecial (enum) - fireball/src/ir/statements.rs
• IrUnaryOperator (enum) - fireball/src/ir/operator.rs
• IrBinaryOperator (enum) - fireball/src/ir/operator.rs
• IrStatementDescriptor - fireball/src/ir/utils.rs
• IrStatementDescriptorMap<T> - fireball/src/ir/utils.rs
• IrData (enum) - fireball/src/ir/data.rs
• IrDataAccess - fireball/src/ir/data.rs
• IrIntrinsic (enum) - fireball/src/ir/data.rs
• NumCondition (enum) - fireball/src/ir/data.rs
• IrDataAccessType (enum) - fireball/src/ir/data.rs
• IrDataOperation (enum) - fireball/src/ir/data.rs
• IrAccessSize (enum) - fireball/src/ir/data.rs
• IrDataContainable (trait) - fireball/src/ir/data.rs
• ARM (trait) - fireball/src/ir/arm/mod.rs
• X64 (trait) - fireball/src/ir/x86_64/mod.rs
• X64Mut (trait) - fireball/src/ir/x86_64/mod.rs

IR analysis (fireball/src/ir/analyze)

• IrVariable - fireball/src/ir/analyze/variables.rs
• BlockGrouper - fireball/src/ir/analyze/block_grouper.rs
• BlockGroup - fireball/src/ir/analyze/block_grouper.rs
• KnownDataType - fireball/src/ir/analyze/datatype.rs
• DataType (enum) - fireball/src/ir/analyze/datatype.rs

AST (fireball/src/abstract_syntax_tree)

• Module exports - fireball/src/abstract_syntax_tree/mod.rs
• Ast - fireball/src/abstract_syntax_tree/objects/ast.rs
• AstFunction - fireball/src/abstract_syntax_tree/objects/function.rs
• AstStatement (enum) - fireball/src/abstract_syntax_tree/objects/statement.rs
• AstExpression (enum) - fireball/src/abstract_syntax_tree/objects/expression.rs
• AstValueType (enum) - fireball/src/abstract_syntax_tree/objects/value.rs
• AstValue (enum) - fireball/src/abstract_syntax_tree/objects/value.rs
• AstLiteral (enum) - fireball/src/abstract_syntax_tree/objects/value.rs
• AstVariable - fireball/src/abstract_syntax_tree/objects/variable.rs
• AstVariableId - fireball/src/abstract_syntax_tree/objects/tags.rs
• AstFunctionId - fireball/src/abstract_syntax_tree/objects/tags.rs
• AstFunctionVersion - fireball/src/abstract_syntax_tree/objects/tags.rs
• AstParameter - fireball/src/abstract_syntax_tree/objects/parameter.rs
• AstParameterLocation (enum) - fireball/src/abstract_syntax_tree/objects/parameter.rs
• AstUnaryOperator (enum) - fireball/src/abstract_syntax_tree/objects/operator.rs
• AstBinaryOperator (enum) - fireball/src/abstract_syntax_tree/objects/operator.rs
• AstJumpTarget (enum) - fireball/src/abstract_syntax_tree/objects/etc.rs
• AstCall (enum) - fireball/src/abstract_syntax_tree/objects/etc.rs
• AstBuiltinFunctionArgument (enum) - fireball/src/abstract_syntax_tree/objects/etc.rs
• AstBuiltinFunction (enum) - fireball/src/abstract_syntax_tree/objects/etc.rs
• ArcAstFunctionMap (type) - fireball/src/abstract_syntax_tree/objects/etc.rs
• ArcAstVariableMap (type) - fireball/src/abstract_syntax_tree/objects/etc.rs
• AstPrintConfig - fireball/src/abstract_syntax_tree/objects/print_config.rs
• AstOptimizationConfig - fireball/src/abstract_syntax_tree/objects/optimization.rs
• AstOptimizationKind (enum) - fireball/src/abstract_syntax_tree/objects/optimization.rs
• WrappedAstStatement - fireball/src/abstract_syntax_tree/objects/wrapper.rs
• Wrapped<T> - fireball/src/abstract_syntax_tree/objects/wrapper.rs
• AstDescriptor - fireball/src/abstract_syntax_tree/objects/wrapper.rs
• AstStatementOrigin (enum) - fireball/src/abstract_syntax_tree/objects/wrapper.rs
• AstValueOrigin (enum) - fireball/src/abstract_syntax_tree/objects/wrapper.rs
• PrintWithConfig (trait) - fireball/src/abstract_syntax_tree/traits.rs
• GetRelatedVariables (trait) - fireball/src/abstract_syntax_tree/traits.rs
• AstVariableAccessType (enum) - fireball/src/abstract_syntax_tree/traits.rs

AST Analyzation (AST Optimization) (fireball/src/abstract_syntax_tree/optimize)

• AstPattern - fireball/src/abstract_syntax_tree/optimize/pattern_matching.rs
• AstPatternOrigin (enum) - fireball/src/abstract_syntax_tree/optimize/pattern_matching.rs
• AstPatternArgType (enum) - fireball/src/abstract_syntax_tree/optimize/pattern_matching.rs

Pattern Matching Engine (fireball/src/abstract_syntax_tree/optimize/pattern_matching/)

• mod.rs — Core types: AstPatternRule, AstPatternClauseGroup, AstPatternInBlock (enum), AstPatternOutAction (enum), AstPatternScript (stores pre-compiled rhai::AST, no source text), AstPatternAsmData, AstPatternAstData, AstPatternIrData, AstPatternRange, IgnoreCommentFilter (enum), ClearIgnoreTarget (enum)
• apply.rs — Execution engine: AstPatternScriptContext (holds &[WrappedAstStatement], &[IrStatement], &[AstPatternNormalizedAsmLine]), AstPatternLoadedRule, Rhai engine/scope setup, if/do script evaluation, ignore filter application, asm/ast/ir matching
• fb_parser.rs — .fb DSL parser: parse_pattern_file(), parse_rhai_script(), all if:/do: directive parsing
• rhai_types.rs — Rhai wrapper types.
• stmt_pattern/ — PatTree matching: parser.rs (PatTree parser), matcher.rs (statement/expression matching), construct.rs (emit construction from PatTree), predicate.rs (where predicates)
• ir_parser.rs — IR/asm text parsing for pattern conditions

Utils / errors (fireball/src/utils)

• VersionMap<..> - fireball/src/utils/version_map.rs
• Aos<T> (enum) - fireball/src/utils/arc_or_static.rs
• FireballError (enum) - fireball/src/utils/error.rs
• DecompileError (enum) - fireball/src/utils/error/decompile_error.rs
• DisassembleError (enum) - fireball/src/utils/error/disassemble_error.rs
• IoError (enum) - fireball/src/utils/error/io_error.rs
• IrAnalyzeAssertionFailure (enum) - fireball/src/utils/error/ir_analyze_assertion_error.rs

If you want to find another struct/enum/trait/type, search by regex (e.g. rg "^\\s*pub\\s+(struct|enum|trait|type)\\s+Name").

Testing

Never add tests for firebat or the Fireman TUI. This is a hard rule.

Due to the difficulty of setting up AST and IR environments, agents must refrain from writing internal tests for them and instead conduct testing using reversing results from tests/resources/hello_world.exe. To verify and compare disassembly and decompiled outputs during testing, use the radare (r2) CLI. After tests succeed, analyze log files to confirm the decompilation results are normal and match the expected output.