Skip to content

Turn any idea, plan, or codebase into a beautiful interactive diagram. An agent skill for Claude Code, Codex, and more.

docs: clarify contribution readiness and proposal intake

tt-a1i524fd6915b45
diff --git a/.github/ISSUE_TEMPLATE/bug-report.yml b/.github/ISSUE_TEMPLATE/bug-report.yml
index cfb3e64f..598e411a 100644
--- a/.github/ISSUE_TEMPLATE/bug-report.yml
+++ b/.github/ISSUE_TEMPLATE/bug-report.yml
@@ -7,7 +7,7 @@ body:
- type: markdown
attributes:
value: |
- Stability comes first. A small typed JSON reproduction and the machine-readable validation receipt are the fastest path to a safe fix.
+ Stability comes first. For diagram defects, include a small typed JSON reproduction and validation receipt when available. For installation or Viewer problems, provide the relevant steps and error; explain when a command, JSON, or receipt does not apply.
- type: input
id: archify_version
@@ -54,7 +54,7 @@ body:
id: command
attributes:
label: Exact command
- description: Include flags and paths, replacing private path segments with neutral placeholders.
+ description: Include flags and paths, replacing private path segments with neutral placeholders. For a UI-only problem, describe the actions instead.
render: shell
validations:
required: true
@@ -63,7 +63,7 @@ body:
id: minimal_json
attributes:
label: Minimal redacted JSON reproduction
- description: Remove unrelated nodes and facts while preserving the failure.
+ description: Remove unrelated nodes and facts while preserving the failure. If JSON does not apply or cannot be produced, explain why and provide reproduction steps.
render: json
validations:
required: true
@@ -72,7 +72,7 @@ body:
id: validation_receipt
attributes:
label: Validation receipt or exact error
- description: Prefer the complete JSON produced by `validate --json` or `deliver --json`.
+ description: Prefer the complete JSON produced by `validate --json` or `deliver --json`. If no receipt or error exists, say so and describe the observed failure.
render: json
validations:
required: true
diff --git a/.github/ISSUE_TEMPLATE/improvement.yml b/.github/ISSUE_TEMPLATE/improvement.yml
new file mode 100644
index 00000000..b25c1c03
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/improvement.yml
@@ -0,0 +1,43 @@
+name: Propose an improvement
+description: Discuss a feature or substantial change before implementation.
+title: "[Proposal]: "
+body:
+ - type: markdown
+ attributes:
+ value: |
+ Thanks for proposing an improvement. Describe the problem and intended benefit before investing in implementation. Maintainers will discuss scope and compatibility; agreement on direction is not a promise to merge. Small fixes may go directly to a PR under CONTRIBUTING.md.
+ - type: textarea
+ id: problem
+ attributes:
+ label: What practical problem are you trying to solve?
+ description: Who encounters it? Include a concrete example when possible.
+ validations:
+ required: true
+ - type: textarea
+ id: current_limit
+ attributes:
+ label: Why are the current capabilities insufficient?
+ description: Mention the version and any existing controls or alternatives you considered.
+ validations:
+ required: true
+ - type: textarea
+ id: improvement
+ attributes:
+ label: What outcome would improve this?
+ description: Describe the desired result, likely scope, and known tradeoffs. A detailed design or implementation is not required.
+ validations:
+ required: true
+ - type: textarea
+ id: related
+ attributes:
+ label: Related issues or PRs
+ description: Search existing discussions and contributions; link related work or state that none was found.
+ validations:
+ required: true
+ - type: checkboxes
+ id: privacy
+ attributes:
+ label: Safe to share
+ options:
+ - label: I removed secrets, private source, and personal or customer data.
+ required: true
diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md
index 99037060..445d5f86 100644
--- a/.github/PULL_REQUEST_TEMPLATE.md
+++ b/.github/PULL_REQUEST_TEMPLATE.md
@@ -2,7 +2,9 @@
## Problem and value
-Current-base trigger or rationale, intended outcome, why the approach is worth maintaining, and linked issue/agreed scope:
+- Related issue / agreed discussion, or why this is a small fix that needs no prior issue:
+- Actual problem on the current base, intended outcome, and why it is worth maintaining:
+- Before/after evidence entry point: <!-- Link the relevant evidence below or an existing report; explain when not applicable. -->
## Stability impact
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 2438a530..dee42ef9 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -7,10 +7,12 @@ Archify is Agent-first: people describe systems, and the Skill, typed JSON, rend
- Renderer, validator, package, or Viewer defect: use the [bug report form](.github/ISSUE_TEMPLATE/bug-report.yml).
- Standalone community package: follow the [submission guide](community/README.md#submitting-a-package) and submit one metadata file to `dev`.
- Reproducible real-world diagram: use the [showcase form](.github/ISSUE_TEMPLATE/showcase.yml).
-- New schema fields, defaults, acceptance rules, installation/export contracts, or broad product behavior: agree on value, compatibility, and non-goals before substantial implementation. Link the issue or recorded maintainer decision; reuse an existing agreed scope.
+- New features, layout/routing rules, schema fields, defaults, acceptance rules, installation/export contracts, or substantial refactors: open an [improvement proposal](.github/ISSUE_TEMPLATE/improvement.yml) and obtain explicit maintainer agreement on the problem, value, scope, and compatibility before substantial implementation. Link an existing issue or PR discussion with that agreement when available; a second approval thread is unnecessary.
- Narrow fixes and small documentation or test corrections can proceed with a concrete reproduction or rationale; a separate planning issue is unnecessary.
- Security vulnerabilities: follow [SECURITY.md](SECURITY.md).
+Agreement on direction allows implementation to proceed; final acceptance still depends on the implementation, user-visible results, and maintenance cost. Draft PRs may support early discussion but do not replace scope agreement.
+
Do not include secrets, access tokens, credentials, private repository content, personal data, or customer data in fixtures, logs, screenshots, artifacts, or package tests.
## Coordinate related work
diff --git a/REVIEWING.md b/REVIEWING.md
index 7f262007..d74ee60b 100644
--- a/REVIEWING.md
+++ b/REVIEWING.md
@@ -2,6 +2,14 @@
Use this guide for initial and revised PR reviews. Judge the user value, implementation and ongoing maintenance cost, and impact on existing behavior. [Contributing](CONTRIBUTING.md#choose-evidence-by-impact) describes contribution and evidence requirements.
+## Check readiness before detailed review
+
+Apply [Choose the right path](CONTRIBUTING.md#choose-the-right-path) first. When prior scope agreement is required but missing, thank the contributor, point to the relevant issue or proposal form, and defer detailed code review until the direction is agreed. Small fixes with a concrete reproduction or rationale can proceed directly.
+
+For missing evidence, describe the material gaps together and request the smallest comparison that resolves them. Resume review when the contributor supplies it; reuse valid existing evidence. Maintainers review and sample the submitted evidence rather than routinely reconstructing every contribution's test run. An issue link alone does not establish scope agreement or review readiness.
+
+For existing PRs, reuse earlier maintainer decisions and evidence; request discussion only for unresolved direction, rather than requiring a new issue as paperwork.
+
## Understand the problem and approach
Record the current target base and candidate head. Read the linked issue or agreed scope and check the current-base behavior where feasible. Separate the reported problem from the proposed implementation.