Skip to content

Commit 5f7773d

Browse files
wujiajunhahahclaude
wujiajunhahah
and
claude
committed
chore: OSS scaffolding (CI, templates, security, conduct, architecture)
- GitHub Actions CI: verifies every module has a README and that Apache LICENSE remains in place. - Issue templates: bug_report, feature_request, plus a config that links to focux.me and the security advisory page. - Pull request template covering module selection, status transition (planned/imported/polished), and scope guardrails. - SECURITY.md with private vulnerability reporting flow and scope. - CODE_OF_CONDUCT.md (Contributor Covenant 2.1). - CHANGELOG.md (Keep a Changelog format, initial Unreleased entry). - README badges (license, status, homepage, CI). - docs/architecture.md with a Mermaid five-layer diagram and reading order for first-time visitors. No source code imported yet. Every module remains `planned`. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
1 parent a6b4a09 commit 5f7773d

11 files changed

Lines changed: 434 additions & 2 deletions

File tree

‎.github/ISSUE_TEMPLATE/bug_report.md‎

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,53 @@
1+
---
2+
name: Bug report
3+
about: Something is broken or behaves unexpectedly
4+
title: "[bug] "
5+
labels: bug
6+
assignees: ""
7+
---
8+
9+
## What happened
10+
11+
A clear description of the bug.
12+
13+
## Which module
14+
15+
- [ ] core/sensor-module
16+
- [ ] core/context-bus
17+
- [ ] core/harness-protocol
18+
- [ ] engines/stamina
19+
- [ ] engines/vision
20+
- [ ] engines/fusion
21+
- [ ] engines/intervention
22+
- [ ] engines/breath
23+
- [ ] engines/fatigue
24+
- [ ] engines/decision
25+
- [ ] signals/emg-features
26+
- [ ] signals/canonical
27+
- [ ] models/emotion-hand-wesad
28+
- [ ] models/onnx-inference
29+
- [ ] hardware/echowrist
30+
- [ ] consumers/lelamp-listener
31+
- [ ] other
32+
33+
## Reproduction
34+
35+
Minimum steps required to reproduce.
36+
37+
```
38+
1.
39+
2.
40+
3.
41+
```
42+
43+
## What did you expect
44+
45+
## What actually happened
46+
47+
## Environment
48+
49+
- OS:
50+
- Python / firmware version:
51+
- Sensor hardware (if applicable):
52+
53+
## Logs / screenshots (optional)

‎.github/ISSUE_TEMPLATE/config.yml‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
blank_issues_enabled: false
2+
contact_links:
3+
- name: FocuX project site
4+
url: https://focux.me
5+
about: Product overview, brand, and privacy policy.
6+
- name: Security disclosure
7+
url: https://github.com/wujiajunhahah/focux-engines/security/advisories/new
8+
about: Report a security vulnerability privately.

‎.github/ISSUE_TEMPLATE/feature_request.md‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
---
2+
name: Feature request
3+
about: Suggest a new engine, protocol extension, sensor module, or consumer
4+
title: "[feature] "
5+
labels: enhancement
6+
assignees: ""
7+
---
8+
9+
## What problem does this solve
10+
11+
What is the user, researcher, or integrator trying to do that current engines don't support?
12+
13+
## Proposed direction
14+
15+
Sketch of what the new capability looks like. Interface, dataflow, or example
16+
output are more useful than implementation details.
17+
18+
## Which layer does this belong to
19+
20+
- [ ] new sensor module (`core/sensor-module` consumer)
21+
- [ ] new engine (`engines/*`)
22+
- [ ] new signal processor (`signals/*`)
23+
- [ ] new harness protocol field (extends `core/harness-protocol`)
24+
- [ ] new consumer (`consumers/*`)
25+
- [ ] new hardware (`hardware/*`)
26+
- [ ] documentation / examples
27+
- [ ] tooling / CI
28+
- [ ] other
29+
30+
## Alternatives considered
31+
32+
What existing engine, protocol field, or workflow already partially covers this?
33+
Why isn't it sufficient?
34+
35+
## Out of scope
36+
37+
What this proposal explicitly does **not** include — keeps reviewers honest about
38+
the surface area.

‎.github/PULL_REQUEST_TEMPLATE.md‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
## Summary
2+
3+
What does this change do, in one or two sentences.
4+
5+
## Which module
6+
7+
- [ ] core/sensor-module
8+
- [ ] core/context-bus
9+
- [ ] core/harness-protocol
10+
- [ ] engines/* (specify):
11+
- [ ] signals/*
12+
- [ ] models/*
13+
- [ ] hardware/echowrist
14+
- [ ] consumers/lelamp-listener
15+
- [ ] docs / CI / tooling
16+
17+
## Status transition
18+
19+
If this PR changes a module's status, declare it:
20+
21+
- [ ] `planned` → `imported`
22+
- [ ] `imported` → `polished`
23+
- [ ] (no status change)
24+
25+
## Checklist
26+
27+
- [ ] Module README still reflects what's inside this directory
28+
- [ ] No application-layer code (FastAPI server, dashboards, UI) introduced
29+
- [ ] No user-specific identifiers, paths, or tokens hardcoded
30+
- [ ] Public APIs have type hints (Python) or signatures (firmware)
31+
- [ ] Added or updated minimal example / test
32+
33+
## Linked issues
34+
35+
Closes #

‎.github/workflows/ci.yml‎

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,53 @@
1+
name: CI
2+
3+
on:
4+
push:
5+
branches: [main]
6+
pull_request:
7+
branches: [main]
8+
9+
jobs:
10+
structure:
11+
name: Structure check
12+
runs-on: ubuntu-latest
13+
steps:
14+
- uses: actions/checkout@v4
15+
16+
- name: Verify every module has a README
17+
run: |
18+
set -e
19+
missing=0
20+
for d in core/* engines/* signals/* models/* hardware/* consumers/* docs; do
21+
if [ -d "$d" ] && [ ! -f "$d/README.md" ]; then
22+
echo "::error::Missing README in $d"
23+
missing=1
24+
fi
25+
done
26+
exit $missing
27+
28+
- name: Verify LICENSE present
29+
run: test -f LICENSE && head -5 LICENSE | grep -q "Apache License"
30+
31+
- name: Lint Markdown links (informational)
32+
uses: gaurav-nelson/github-action-markdown-link-check@v1
33+
continue-on-error: true
34+
with:
35+
use-quiet-mode: 'yes'
36+
use-verbose-mode: 'yes'
37+
38+
python:
39+
name: Python (placeholder — wires in once modules are imported)
40+
runs-on: ubuntu-latest
41+
if: ${{ hashFiles('**/pyproject.toml') != '' }}
42+
steps:
43+
- uses: actions/checkout@v4
44+
- uses: actions/setup-python@v5
45+
with:
46+
python-version: '3.11'
47+
- run: |
48+
python -m pip install --upgrade pip
49+
if compgen -G "**/pyproject.toml" > /dev/null; then
50+
for f in $(find . -name pyproject.toml -not -path './.venv/*'); do
51+
echo "Found $f"
52+
done
53+
fi

‎CHANGELOG.md‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
# Changelog
2+
3+
All notable changes to focux-engines will be documented in this file.
4+
5+
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
6+
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
7+
8+
## [Unreleased]
9+
10+
### Added
11+
12+
- Repository scaffolding: directory tree for `core/`, `engines/`, `signals/`,
13+
`models/`, `hardware/`, `consumers/`, `docs/` with a placeholder README in
14+
every module.
15+
- Apache License 2.0.
16+
- Contribution guide, code of conduct, security policy.
17+
- GitHub issue and pull request templates.
18+
- Initial CI workflow that verifies module READMEs exist and the license is
19+
in place.
20+
- Architecture overview in `docs/architecture.md`.
21+
22+
### Status
23+
24+
Every module is currently marked `planned`. No source code has been imported
25+
yet.
26+
27+
[Unreleased]: https://github.com/wujiajunhahah/focux-engines/commits/main

‎CODE_OF_CONDUCT.md‎

Lines changed: 63 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,63 @@
1+
# Contributor Covenant Code of Conduct
2+
3+
## Our pledge
4+
5+
We as members, contributors, and maintainers pledge to make participation in
6+
our community a harassment-free experience for everyone, regardless of age,
7+
body size, visible or invisible disability, ethnicity, sex characteristics,
8+
gender identity and expression, level of experience, education, socio-economic
9+
status, nationality, personal appearance, race, religion, or sexual identity
10+
and orientation.
11+
12+
We pledge to act and interact in ways that contribute to an open, welcoming,
13+
diverse, inclusive, and healthy community.
14+
15+
## Our standards
16+
17+
Examples of behavior that contributes to a positive environment:
18+
19+
- Demonstrating empathy and kindness toward other people
20+
- Being respectful of differing opinions, viewpoints, and experiences
21+
- Giving and gracefully accepting constructive feedback
22+
- Accepting responsibility and apologizing to those affected by our mistakes,
23+
and learning from the experience
24+
- Focusing on what is best not just for us as individuals, but for the overall
25+
community
26+
27+
Examples of unacceptable behavior:
28+
29+
- The use of sexualized language or imagery, and sexual attention or advances
30+
of any kind
31+
- Trolling, insulting or derogatory comments, and personal or political attacks
32+
- Public or private harassment
33+
- Publishing others' private information, such as a physical or email address,
34+
without their explicit permission
35+
- Other conduct which could reasonably be considered inappropriate in a
36+
professional setting
37+
38+
## Enforcement responsibilities
39+
40+
Maintainers are responsible for clarifying and enforcing our standards of
41+
acceptable behavior and will take appropriate and fair corrective action in
42+
response to any behavior they deem inappropriate, threatening, offensive, or
43+
harmful.
44+
45+
## Scope
46+
47+
This Code of Conduct applies within all community spaces, and also applies when
48+
an individual is officially representing the community in public spaces.
49+
50+
## Enforcement
51+
52+
Instances of abusive, harassing, or otherwise unacceptable behavior may be
53+
reported to the maintainers responsible for enforcement via the contact link
54+
in [SECURITY.md](SECURITY.md). All complaints will be reviewed and investigated
55+
promptly and fairly.
56+
57+
## Attribution
58+
59+
This Code of Conduct is adapted from the [Contributor Covenant][homepage],
60+
version 2.1, available at
61+
https://www.contributor-covenant.org/version/2/1/code_of_conduct.html.
62+
63+
[homepage]: https://www.contributor-covenant.org

‎README.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,10 @@
11
# focux-engines
22

3+
[![License](https://img.shields.io/badge/license-Apache_2.0-0A0A0A.svg)](LICENSE)
4+
[![Status](https://img.shields.io/badge/status-research_prototype-555555.svg)](#status)
5+
[![Homepage](https://img.shields.io/badge/homepage-focux.me-0A0A0A.svg)](https://focux.me)
6+
[![CI](https://github.com/wujiajunhahah/focux-engines/actions/workflows/ci.yml/badge.svg)](https://github.com/wujiajunhahah/focux-engines/actions/workflows/ci.yml)
7+
38
> Open-sourced engines, protocols, and signal processing for state-aware embodied interaction.
49
510
This repository collects the technical core of [FocuX](https://focux.me) — a research prototype

‎SECURITY.md‎

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
# Security policy
2+
3+
## Reporting a vulnerability
4+
5+
If you find a security vulnerability in any module of this repository, please
6+
**do not open a public GitHub issue**.
7+
8+
Instead, open a private security advisory:
9+
https://github.com/wujiajunhahah/focux-engines/security/advisories/new
10+
11+
Include:
12+
13+
- The affected module (`engines/*`, `core/harness-protocol`, `hardware/echowrist`, …)
14+
- A description of the vulnerability and its impact
15+
- Reproduction steps or proof-of-concept
16+
- Any suggested mitigation
17+
18+
We aim to acknowledge reports within 7 days and provide a more substantive
19+
update within 30 days.
20+
21+
## Scope
22+
23+
This repository contains research-prototype code. The threat model in scope
24+
covers:
25+
26+
- Information leakage from sensor data pipelines
27+
- Insecure defaults in `core/harness-protocol` WebSocket transport
28+
- Vulnerabilities in `hardware/echowrist` firmware that could expose users
29+
- Supply-chain risks in dependencies declared by modules under this repo
30+
31+
Out of scope:
32+
33+
- Vulnerabilities in third-party hardware (LeLamp, WAVELETECH wristband, etc.)
34+
- Vulnerabilities in the FocuX iOS application or the focux.me website (those
35+
live in separate repositories)
36+
- Issues that require physical access to the device beyond what is already
37+
required to attach a sensor
38+
39+
## Coordinated disclosure
40+
41+
We follow a 90-day coordinated disclosure timeline by default. If you need a
42+
longer or shorter window, mention it in the report and we will discuss.

‎docs/README.md‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,9 +2,11 @@
22

33
Cross-cutting design notes that don't belong to any single subdirectory.
44

5-
Planned documents:
5+
Documents:
66

7-
- `architecture.md` — Five-layer system overview (sensing → fusion → harness → consumer → memory)
7+
- [`architecture.md`](architecture.md) — Five-layer system overview (sensing → fusion → harness → consumer → memory) — **available**
8+
9+
Planned:
810
- `design-stance.md` — The five design positions, with worked examples
911
- `protocol-reference.md` — Full `SubjectStateFrame` v0 specification, longer-form companion to
1012
`core/harness-protocol/README.md`

0 commit comments

Comments
 (0)