Reverse engineer anything with agents, from app behavior down to native binaries.
TypeScript agent-skillsai-agentsbinary-analysisclaude-codeclicodexcordisdecompilerdeveloper-toolsdshdsh-pluginghidrahopperllmmcpmodel-context-protocolreareverse-engineeringstatic-analysistouhou
docs: improve GitHub issue and pull request templates
morlutoc490d85045de
diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.mddeleted file mode 100644index 3b45b027c..000000000--- a/.github/ISSUE_TEMPLATE/bug_report.md+++ /dev/null@@ -1,39 +0,0 @@-----name: Bug Report-about: Report a bug in REA-title: "[Bug] "-labels: ["bug", "triage"]-assignees: []------## Bug Description--A clear and concise description of what the bug is.--## Steps to Reproduce--1.-2.-3.--## Expected Behavior--What you expected to happen.--## Actual Behavior--What actually happened, including any error messages or unexpected output.--## Environment--- REA version (`rea --version` or `npm list @morluto/rea`):-- Node.js version (`node --version`):-- macOS version:-- Hopper Disassembler version:-- Target binary format (Mach-O, ELF, PE, .hop):--## Additional Context--- MCP client and version (if applicable):-- Any relevant logs or stack traces:-- Does the issue reproduce with a different target binary?diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.ymlnew file mode 100644index 000000000..f93e9f7bd--- /dev/null+++ b/.github/ISSUE_TEMPLATE/bug_report.yml@@ -0,0 +1,155 @@+name: Bug report+description: Report a reproducible problem in REA+title: "[Bug] "+labels:+ - bug+ - triage+body:+ - type: markdown+ attributes:+ value: |+ Please report one primary behavior per issue. Keep observed behavior+ separate from suspected causes, and remove credentials and private paths.++ - type: checkboxes+ id: before-submitting+ attributes:+ label: Before submitting+ options:+ - label: I searched the open and closed issues for a related report.+ required: true+ - label: I removed credentials, tokens, private paths, and sensitive target data.+ required: true++ - type: dropdown+ id: area+ attributes:+ label: Area+ options:+ - Setup, packaging, or upgrade+ - Provider or capability discovery+ - Process capture or runtime observation+ - Native analysis or decompilation+ - Evidence, artifacts, or reconstruction+ - CLI+ - MCP or agent integration+ - Documentation+ - Other+ validations:+ required: true++ - type: textarea+ id: observed-behavior+ attributes:+ label: Observed behavior+ description: What happened? Include the command, MCP tool, provider, target type, and conditions that matter.+ validations:+ required: true++ - type: textarea+ id: reproduction+ attributes:+ label: Reproduction+ description: Give the smallest realistic command, configuration, input, or event sequence that demonstrates the problem.+ placeholder: |+ 1. Configure or start ...+ 2. Run ...+ 3. Observe ...+ validations:+ required: true++ - type: textarea+ id: expected-behavior+ attributes:+ label: Expected behavior+ description: What result, contract, invariant, recovery action, or state transition should have occurred?+ validations:+ required: true++ - type: textarea+ id: impact-scope+ attributes:+ label: Impact and scope+ description: What is affected, what is not affected, and does this affect evidence integrity, process isolation, compatibility, or recovery?+ validations:+ required: true++ - type: input+ id: rea-version+ attributes:+ label: REA version+ description: Use `rea --version` or provide the source revision.+ placeholder: 3.1.0 or git revision+ validations:+ required: true++ - type: input+ id: runtime+ attributes:+ label: Runtime and platform+ description: Include Node.js, OS, architecture, and Hopper/Ghidra version when relevant.+ placeholder: Node 24.18; macOS 15 arm64; Hopper 5.15+ validations:+ required: true++ - type: input+ id: target+ attributes:+ label: Target and artifact context+ description: Include binary format, app/container type, artifact kind, or workload details when relevant.+ placeholder: Mach-O arm64 app; Evidence v2 bundle; not applicable++ - type: dropdown+ id: interface+ attributes:+ label: Interface+ options:+ - CLI+ - MCP+ - Python bridge+ - Package or setup+ - Other+ validations:+ required: true++ - type: dropdown+ id: failure-stage+ attributes:+ label: Earliest failure stage+ description: Select where the incorrect behavior first becomes observable.+ options:+ - Request parsing or validation+ - Setup or provider admission+ - Capture or observation+ - Artifact or evidence registration+ - Native analysis or reconstruction+ - Transport or result projection+ - Cleanup, cancellation, or lifecycle+ - Unknown+ validations:+ required: true++ - type: textarea+ id: relevant-evidence+ attributes:+ label: Relevant output or evidence+ description: Paste the smallest useful CLI output, MCP result, error, trace, or evidence excerpt. Redact sensitive values.+ render: text++ - type: textarea+ id: typed-outcome+ attributes:+ label: Typed outcome or recovery expected+ description: Optional. What typed result, error, next tool, cleanup state, or limitation should the caller have received?++ - type: textarea+ id: analysis+ attributes:+ label: Analysis or suspected cause+ description: Optional. Clearly mark source-derived reasoning or a hypothesis; do not present an unverified cause as fact.++ - type: textarea+ id: additional-context+ attributes:+ label: Additional context+ description: Add links, reduced fixtures, screenshots, or a proposed regression test.diff --git a/.github/ISSUE_TEMPLATE/design_discussion.yml b/.github/ISSUE_TEMPLATE/design_discussion.ymlnew file mode 100644index 000000000..912e18c44--- /dev/null+++ b/.github/ISSUE_TEMPLATE/design_discussion.yml@@ -0,0 +1,69 @@+name: Design discussion+description: Resolve an REA architecture, provider, or contract question before implementation+title: "[Design] "+labels:+ - enhancement+ - triage+body:+ - type: markdown+ attributes:+ value: |+ Use this for a substantial provider, public/persisted contract, or+ authority-boundary decision. Keep one decision per discussion.++ - type: checkboxes+ id: before-submitting+ attributes:+ label: Before submitting+ options:+ - label: I searched the open and closed issues and pull requests for a related discussion.+ required: true+ - label: I removed credentials, tokens, private paths, and sensitive target data.+ required: true++ - type: textarea+ id: decision+ attributes:+ label: Decision needed+ description: State the exact question maintainers need to resolve.+ placeholder: Should REA ... or ...?+ validations:+ required: true++ - type: textarea+ id: context-evidence+ attributes:+ label: Context and evidence+ description: Explain why the decision is needed now. Separate observed behavior, derived evidence, and inference.+ validations:+ required: true++ - type: textarea+ id: boundary-invariants+ attributes:+ label: Boundary and invariants+ description: Identify the owning layer, provider/bridge boundary, artifact or evidence invariants, and any process or authorization constraints.+ validations:+ required: true++ - type: textarea+ id: options+ attributes:+ label: Options and tradeoffs+ description: Compare a small number of viable approaches, including platform, compatibility, safety, evidence, and maintenance costs.+ validations:+ required: true++ - type: textarea+ id: success-criteria+ attributes:+ label: Success criteria and open questions+ description: State what outcome would settle the decision and list only unresolved questions that could change the choice.+ validations:+ required: true++ - type: textarea+ id: references+ attributes:+ label: References+ description: Link relevant contracts, upstream provider documentation, tests, measurements, or prior discussions.diff --git a/.github/ISSUE_TEMPLATE/documentation.md b/.github/ISSUE_TEMPLATE/documentation.mddeleted file mode 100644index 38602f41a..000000000--- a/.github/ISSUE_TEMPLATE/documentation.md+++ /dev/null@@ -1,24 +0,0 @@-----name: Documentation-about: Suggest improvements to REA documentation-title: "[Docs] "-labels: ["documentation", "triage"]-assignees: []------## Documentation Area--Which documentation needs improvement? (README, AGENTS.md, API docs, inline JSDoc, skill files)--## Problem--What is unclear, missing, or incorrect in the current documentation?--## Suggested Improvement--Describe the change you would like to see.--## Additional Context--- Link to the relevant documentation file or section:-- Any examples or references that would help:diff --git a/.github/ISSUE_TEMPLATE/documentation.yml b/.github/ISSUE_TEMPLATE/documentation.ymlnew file mode 100644index 000000000..fa2bc024e--- /dev/null+++ b/.github/ISSUE_TEMPLATE/documentation.yml@@ -0,0 +1,53 @@+name: Documentation+description: Report unclear, missing, or incorrect REA documentation+title: "[Docs] "+labels:+ - documentation+ - triage+body:+ - type: checkboxes+ id: before-submitting+ attributes:+ label: Before submitting+ options:+ - label: I searched the existing issues for a related documentation report.+ required: true+ - label: I removed credentials, tokens, private paths, and sensitive target data.+ required: true++ - type: input+ id: location+ attributes:+ label: Documentation location+ description: Link the page, section, command, API, skill, or inline comment.+ placeholder: README.md#quick-start or docs/mcp-contracts.md+ validations:+ required: true++ - type: textarea+ id: problem+ attributes:+ label: Problem+ description: What is unclear, missing, outdated, or incorrect, and who is affected?+ validations:+ required: true++ - type: textarea+ id: expected-content+ attributes:+ label: Expected content+ description: Describe the accurate behavior or example that should be documented.+ validations:+ required: true++ - type: textarea+ id: evidence+ attributes:+ label: Supporting evidence+ description: Add source, command output, provider documentation, or a link that supports the correction.++ - type: textarea+ id: additional-context+ attributes:+ label: Additional context+ description: Include screenshots, affected translations, or related issues.diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.mddeleted file mode 100644index 97d2d892e..000000000--- a/.github/ISSUE_TEMPLATE/feature_request.md+++ /dev/null@@ -1,29 +0,0 @@-----name: Feature Request-about: Propose a new feature or enhancement for REA-title: "[Feature] "-labels: ["enhancement", "triage"]-assignees: []------## Problem Statement--What problem does this feature solve? Describe the use case and why existing tools are insufficient.--## Proposed Solution--Describe the feature or enhancement you would like to see. Include:--- Which REA tool(s) this affects (direct, enhanced, or session tools)-- Expected inputs and outputs-- How it integrates with the existing MCP workflow--## Alternatives Considered--Any alternative approaches or workarounds you have tried.--## Additional Context--- Relevant Hopper API methods or concepts:-- Links to related issues or discussions:-- Would this require changes to the bridge (`bridge/hopper_bridge.py`)?diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.ymlnew file mode 100644index 000000000..7b0767b27--- /dev/null+++ b/.github/ISSUE_TEMPLATE/feature_request.yml@@ -0,0 +1,88 @@+name: Feature request+description: Propose a focused improvement to REA+title: "[Feature] "+labels:+ - enhancement+ - triage+body:+ - type: markdown+ attributes:+ value: |+ Keep one primary capability or workflow outcome per request. For a+ substantial provider, public contract, or architecture change, explain+ the decision maintainers need to make before implementation.++ - type: checkboxes+ id: before-submitting+ attributes:+ label: Before submitting+ options:+ - label: I searched the open and closed issues and pull requests for a related proposal.+ required: true+ - label: I removed credentials, tokens, private paths, and sensitive target data.+ required: true++ - type: dropdown+ id: area+ attributes:+ label: Area+ options:+ - Setup, packaging, or upgrade+ - Provider or capability discovery+ - Process capture or runtime observation+ - Native analysis or decompilation+ - Evidence, artifacts, or reconstruction+ - CLI+ - MCP or agent integration+ - Documentation+ - Other+ validations:+ required: true++ - type: textarea+ id: current-limitation+ attributes:+ label: Current limitation+ description: What user or agent workflow is blocked, ambiguous, or unnecessarily difficult today?+ validations:+ required: true++ - type: textarea+ id: use-cases+ attributes:+ label: Use cases+ description: Give concrete applications, targets, callers, or investigation workflows. Explain why current tools are insufficient.+ validations:+ required: true++ - type: textarea+ id: desired-outcome+ attributes:+ label: Desired outcome and success criteria+ description: Describe observable behavior, inputs, outputs, evidence, and compatibility criteria that would make this useful.+ validations:+ required: true++ - type: textarea+ id: boundaries+ attributes:+ label: Authority boundaries and non-goals+ description: Call out process execution, target mutation, provider licensing, evidence provenance, supported platforms, and work that should remain out of scope.++ - type: textarea+ id: alternatives+ attributes:+ label: Alternatives considered+ description: Describe existing REA operations, upstream tools, or workarounds considered and why they do not meet the need.++ - type: textarea+ id: possible-direction+ attributes:+ label: Possible direction+ description: Optional implementation or integration idea. Treat it as a proposal, not a requirement.++ - type: textarea+ id: references+ attributes:+ label: References+ description: Link relevant provider documentation, source, measurements, artifacts, issues, or discussions.diff --git a/.github/pull_request_template.md b/.github/pull_request_template.mdindex 8c3078530..9fd1c2086 100644--- a/.github/pull_request_template.md+++ b/.github/pull_request_template.md@@ -1,34 +1,73 @@-## Description+<!--+PR title: type(optional-scope): imperative outcome+The title becomes the squash-merge commit subject and generated changelog entry.+-->-<!-- What does this change do? Why is it needed? -->+## Summary-## Type of Change+<!-- What user, agent, or maintainer problem does this solve? Link the issue+with "Fixes #123" when applicable. Keep the prior behavior, expected contract,+and new behavior understandable without private context. -->-- [ ] Bug fix-- [ ] New feature-- [ ] Documentation update-- [ ] Performance improvement-- [ ] Refactoring (no functional change)-- [ ] Tool contract change (MCP schema modification)+## Problem and expected behavior-## Testing Performed+<!-- For fixes, give the smallest trigger and violated invariant. For features,+describe the use case and observable outcome. -->-<!-- Describe the testing you have done to verify this change. -->+## Change and scope-- [ ] Unit tests added or updated-- [ ] TypeScript typecheck passes (`npm run typecheck`)-- [ ] Linting passes (`npm run lint`)-- [ ] Full test suite passes (`npm test`)-- [ ] Real Hopper verification performed (`npm run verify:hopper`)-- [ ] Linux real Hopper verification performed (`npm run verify:hopper:linux`) or unavailability explained-- [ ] Real browser verification performed (`npm run verify:browser`) or unavailability explained-- [ ] Package verification performed (`npm run verify:package`)+<!-- Explain the chosen approach, why it fits REA's architecture, and what is+intentionally not included. -->-## Tool Contract Impact+## Contract and boundary impact-<!-- If this PR adds, removes, or modifies MCP tools, list them here. -->-<!-- Canonical inventory and family counts are generated in docs/product-catalog.json. -->+<!-- Complete the applicable lines; use "none" or "not applicable" explicitly. -->-## Related Issues+- Semantic owner and earliest changed stage:+- CLI and MCP/tool-catalog contract:+- Provider, bridge, target-format, or platform compatibility:+- Evidence, artifact, provenance, or reconstruction contract:+- Process execution, authorization, cleanup, or containment impact:+- Generated metadata, package, or installation impact:-<!-- Link issues this PR closes or relates to. Use "Closes #123" syntax. -->+## Evidence and regression coverage++<!-- State whether evidence is executed, source-derived, or proposed. For fixes,+explain how the regression would fail on the affected base revision when practical. -->++- Tests added or updated:+- Base reproduction or other evidence:+- User-visible CLI/MCP output (if applicable):+- Remaining proof gaps:++For evidence-bearing changes:++- [ ] Observed, derived, and inferred claims remain distinguishable.+- [ ] Artifact identity, source provenance, and failed attempts remain preserved.+- [ ] Unsupported, incomplete, unavailable, or uncertain outcomes remain visible.++## Validation performed++<!-- List only commands that actually ran, with observed results. Include the+relevant real-provider or platform workflow, or explain why it was unavailable. -->++- `command` — result++## Compatibility, safety, and release++<!-- Call out breaking changes, migrations, package effects, platform/provider+limits, security/privacy/containment implications, and meaningful proof gaps. -->++- Breaking changes or migration steps:+- Real Hopper/Ghidra, browser, or OS coverage:+- Package or release metadata impact:+- Security, privacy, process, or containment review:++## Review checklist++- [ ] The PR has one focused outcome and the title follows `type(scope): outcome`.+- [ ] Related issue is linked, or the reason for not linking one is stated above.+- [ ] Tests cover changed observable behavior and meaningful failure paths.+- [ ] Owning docs, contracts, and generated metadata are updated where needed.+- [ ] User-visible CLI/MCP changes include representative output.+- [ ] I checked the final diff for secrets, unrelated cleanup, and unsupported claims.