Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
45 changes: 45 additions & 0 deletions .github/ISSUE_TEMPLATE/bug_report.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,45 @@
name: Bug report
description: Report a reproducible problem in a mechub project.
title: "[Bug]: "
labels: ["bug"]
body:
- type: markdown
attributes:
value: |
**Do not paste real device data.** Redact hostnames, IP addresses, serial numbers, usernames, credentials, keys, SNMP communities, and free-text descriptions from configs, logs, and error output before posting. Security problems go through [SECURITY.md](https://github.com/mechubsec/.github/blob/main/SECURITY.md), not public issues.
- type: checkboxes
id: redaction
attributes:
label: Data hygiene
options:
- label: I have removed real hostnames, IPs, serials, credentials, and other device data from this report.
required: true
- type: textarea
id: what-happened
attributes:
label: What happened?
description: Tell us what went wrong and include relevant context only after redacting hostnames, IPs, serials, credentials, and other real device data.
validations:
required: true
- type: input
id: version
attributes:
label: Version
description: Which project version or commit are you using?
placeholder: e.g. 1.2.3 or abc1234
validations:
required: true
- type: textarea
id: steps
attributes:
label: Steps to reproduce
description: List the smallest set of steps that reproduces the problem, after redacting hostnames, IPs, serials, credentials, and other real device data.
validations:
required: true
- type: textarea
id: expected
attributes:
label: Expected result
description: What did you expect to happen?
validations:
required: true
8 changes: 8 additions & 0 deletions .github/ISSUE_TEMPLATE/config.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,8 @@
blank_issues_enabled: false
contact_links:
- name: Security issue
url: https://github.com/mechubsec/.github/blob/main/SECURITY.md
about: Report vulnerabilities privately; please do not open a public issue.
- name: Questions and community discussion
url: https://github.com/orgs/mechubsec/discussions
about: Ask questions, share ideas, and connect with the mechub community.
19 changes: 19 additions & 0 deletions .github/ISSUE_TEMPLATE/feature_request.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,19 @@
name: Feature request
description: Suggest an improvement for a mechub project.
title: "[Feature]: "
labels: ["enhancement"]
body:
- type: textarea
id: problem
attributes:
label: What problem would this solve?
description: Describe the user or operator problem.
validations:
required: true
- type: textarea
id: proposal
attributes:
label: What do you propose?
description: Describe the behavior or outcome you would like.
validations:
required: true
17 changes: 17 additions & 0 deletions .github/PULL_REQUEST_TEMPLATE.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,17 @@
## Summary

<!-- What does this change do? -->

## Linked issue

Closes #

## Tests run

<!-- List the commands and relevant results. -->

## Checklist

- [ ] Security changes use class-level public text.
- [ ] No secrets, credentials, customer data, or lab data are included.
- [ ] CHANGELOG.md is updated when applicable.
2 changes: 2 additions & 0 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -21,6 +21,8 @@ inspectable, and honest are very welcome.
- Match the surrounding code's style; explain the "why" in the description.
- Include tests where the project has them, and note how you verified the change.
- Label maturity honestly: if something is partial or unverified, say so.
- For README changes, follow the [repository style guide](STYLE_GUIDE.md) and
[README opening template](README-TEMPLATE.md).

## Ground rules
- Deterministic decides, the model explains, a human approves — don't add an
Expand Down
62 changes: 62 additions & 0 deletions README-TEMPLATE.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,62 @@
# README opening template

Use this opening for every mechub repository. Keep the first screen useful to
an operator: state the value, show the maturity, explain the project, and give
the shortest safe path to a first local run.

```markdown
# <project name>

<One sentence describing the value this project provides.>

![Status: <Planned|Alpha|Beta|Stable>](https://img.shields.io/badge/status-<planned|alpha|beta|stable>-<color>)

a mechub project — sovereign AI operations for network and security teams

<Two or three sentences explaining what the project does, who it is for, and
what it connects to or produces.>

## Quick start

<The smallest offline-capable setup and first useful command. Link to
prerequisites or configuration details when needed.>
```

## Status vocabulary

Use exactly one of these maturity labels in the status badge:

| Status | Badge | Use when |
| --- | --- | --- |
| Planned | `status-planned-lightgrey` | The project is proposed or not yet usable. |
| Alpha | `status-alpha-orange` | An early usable version exists; interfaces and behaviour may change. |
| Beta | `status-beta-yellow` | The project is usable for evaluation; interfaces are stabilising. |
| Stable | `status-stable-brightgreen` | The supported path is established and maintained. |

Use the matching Shields.io status segment in the opening badge; do not create
additional maturity labels or colors:

```markdown
![Status: Planned](https://img.shields.io/badge/status-planned-lightgrey)
![Status: Alpha](https://img.shields.io/badge/status-alpha-orange)
![Status: Beta](https://img.shields.io/badge/status-beta-yellow)
![Status: Stable](https://img.shields.io/badge/status-stable-brightgreen)
```

Do not use `In production` to describe a maintainer's own homelab or lab
deployment. Say `running in the maintainer's lab` in prose instead. Reserve
production claims for deployments and evidence that the project can actually
support.

## README maintenance rules

- Keep the value statement to one sentence and put it before the badge.
- Keep the canonical subtitle exactly as shown in the template.
- Put release history and release narrative in `CHANGELOG.md`.
- Put lab notes, experiments, and deployment observations in `docs/`.
- Tool-count badges must match the release they describe. If a count is from
the unreleased branch, label it `unreleased` rather than presenting it as a
released capability. Reconcile the count whenever a release changes the
available tools.
- Keep the quick start deterministic and offline-capable where the project
permits; do not imply that model output performs an unreviewed change.
41 changes: 41 additions & 0 deletions STYLE_GUIDE.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,41 @@
# mechub repository style guide

Use this guide when creating or updating a mechub repository README, subtitle,
or GitHub repository metadata. It keeps the organization recognizable without
overstating maturity or vendor relationships.

## README opening

- The first H1 must equal the exact repository name. Preserve names such as
`rustjunosmcp`; do not insert a dash to make `rust-junosmcp`.
- Use the subtitle `sovereign AI operations for network and security teams` in
every repository README.
- Use one status label only: `Planned`, `Alpha`, `Beta`, or `Stable`.
- Do not use `In production` for a maintainer's homelab. Write `running in the
maintainer's lab` when that is the evidence available.
- Include the canonical disclaimer exactly once in each README, replacing
`{Vendor}` with the relevant vendor name:

> This is an independent, community project. It is not affiliated with, endorsed by, or supported by {Vendor}.

## Naming

Use these fuller forms everywhere, including headings, prose, and metadata:

- `HPE Juniper Mist`
- `Junos SRX`

## Repository metadata

- Append `— a mechub project` to every GitHub repository description. The
description is maintained in GitHub; this suffix is the organization
standard.
- Keep repository descriptions concise and factual. Do not imply vendor
endorsement, production readiness, or capabilities that are not available.

## Pull requests

- Keep the PR focused on one change and state the verification performed.
- Apply this guide to README edits in the same PR when practical.
- Preserve the project rule: deterministic code decides, the model explains,
and a human approves.
9 changes: 9 additions & 0 deletions profile/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -59,6 +59,15 @@ the version, not instead of it.
No server in the family is tagged `stable` yet; all are running in the
maintainer's lab, not production, regardless of version number.

## Start here

- **Foundation:** Start with [`mecmcp`](https://github.com/mechubsec/mecmcp) for shared MCP orchestration and deterministic change-control foundations.
- **MCP servers:** Try [`rustjunosmcp`](https://github.com/mechubsec/rustjunosmcp) first, or [`rustunifimcp`](https://github.com/mechubsec/rustunifimcp) as a second released vendor-facing example.
- **Data:** Explore [`ssdf`](https://github.com/mechubsec/ssdf) for the sovereign security data fabric.
- **Skills & tools:** Use [`fwskillsshare`](https://github.com/mechubsec/fwskillsshare), [`firewallintentconverter`](https://github.com/mechubsec/firewallintentconverter), [`fwconfigsanitizer`](https://github.com/mechubsec/fwconfigsanitizer), or [`srxsync`](https://github.com/mechubsec/srxsync) for focused operator utilities.

Get in touch / testers wanted: for questions, ideas, or testing feedback, join the [mechub Discussions](https://github.com/orgs/mechubsec/discussions). Report vulnerabilities privately via [SECURITY.md](https://github.com/mechubsec/.github/blob/main/SECURITY.md).

## Principles

- **Self-hosted by default.** Your realm, your models, your rules.
Expand Down
Loading