You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
feat(webapp): strengthen public landing experience
The landing page, README and documentation site now open with one definition that names the
category, the audience and the licence, and state the problem plainly: mentoring depends on
attention that is scarce, and the developers who need it most usually get none.
The hero walks one change through a project — issue, pull request, review, merge — where each
failure is caused by the one before it, and closes with the mentor naming the root cause upstream.
The work cards use the state pills, diffstats, comment bubbles and thread counters a developer
already recognises; the feedback cards use the product's own vocabulary, wearing each practice
group's colour and icon from the curated catalog and the strength/needs-improvement marks from
`assessment-defs`. The "how it works" section moves to different groups and different kinds of
work, so the hero shows depth and it shows range.
Each scene is one DOM in narrative order — a figure with a screen-reader caption and a list of
clusters. Above its breakpoint the list becomes a grid sharing a row with the hero copy, so the
scattered and stacked forms cannot drift apart and text that grows pushes what is below it down
instead of overlapping it or spilling onto the next section.
The README leads with its pre-1.0 status, describes delivery as the three places feedback can
reach a developer rather than one configured destination, and names its core maintainer. Its
self-host version is now rewritten by `sync-release-version` with the other release-owned
references, so it cannot drift.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
The landing and about pages now say plainly what Hephaestus is, show the kind of gap it points out, name the practice groups a workspace can turn on, and credit Applied Education Technologies at TUM.
Copy file name to clipboardExpand all lines: README.md
+87-52Lines changed: 87 additions & 52 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -6,80 +6,106 @@
6
6
</picture>
7
7
8
8
<h1>Hephaestus</h1>
9
-
<p><strong>Feedback on how you work</strong></p>
9
+
<p><strong>Learn from the work you're already doing</strong></p>
10
10
11
11
<p>
12
-
<a href="https://hephaestus.aet.cit.tum.de"><img alt="Open the TUM-operated Hephaestus web app" src="https://img.shields.io/badge/web_app-open-493C83"></a>
12
+
<a href="https://hephaestus.aet.cit.tum.de"><img alt="Open the TUM-operated Hephaestus web app" src="https://img.shields.io/badge/web_app-try_it-493C83"></a>
13
13
<a href="https://ls1intum.github.io/Hephaestus/"><img alt="Read the Hephaestus documentation" src="https://img.shields.io/badge/docs-read_online-1F75CB?logo=docusaurus&logoColor=white"></a>
14
-
<a href="https://main--66a8981a27ced8fef3190d41.chromatic.com/"><img alt="Open the Hephaestus Storybook" src="https://cdn.jsdelivr.net/gh/storybookjs/brand@main/badge/badge-storybook.svg"></a>
Hephaestus gives developers feedback on the engineering practices they use in software projects. It draws on evidence from tools the team already uses — including GitHub or GitLab activity, selected Slack channels, and Outline documents — to explain what worked, what could improve, and what to try next.
20
+
Hephaestus is an open-source AI mentor for software teams. It reads the work developers already do —
21
+
issues, pull requests, reviews and the discussion around them — against the engineering practices
22
+
their project cares about, then says what went well, what could be better, and a way to get there.
23
+
Every piece of feedback names the practice it came from and points back to the work it saw, and
24
+
developers can ask why, push back, or talk through the next step.
25
+
26
+
Developers learn to work well in a team by doing the work and getting feedback on it. That feedback is
27
+
a mentor's job, whether that is a coach on a university capstone or an experienced maintainer on an
28
+
open-source project, and there is never enough of that attention to go round. The developers who need
29
+
it most often get none. Hephaestus carries the routine part so that everyone gets some. It does not
30
+
replace mentors: the harder judgement and the relationships stay with people.
25
31
26
32
<divalign="center">
27
33
<picture>
28
-
<source media="(max-width: 520px) and (prefers-color-scheme: dark)" srcset="./docs/images/readme/landing-feedback-preview-mobile-dark.png">
29
-
<source media="(max-width: 520px) and (prefers-color-scheme: light)" srcset="./docs/images/readme/landing-feedback-preview-mobile-light.png">
<img alt="Example practice feedback on a focused change: Hephaestus notes that the change is easy to review and suggests explaining why it matters; the developer asks what to write, and Heph suggests a concise sentence." src="./docs/images/readme/landing-feedback-preview-light.png" width="744">
<img alt="An illustration of one change through a project: issue #412 has no acceptance criteria, the pull request grew to 34 files and picked up an unrelated rename, a reviewer asks a good question, and it merges with that thread unresolved. Hephaestus points back to the issue." src="./docs/images/readme/landing-hero-light.png" width="1280">
33
37
</picture>
34
-
<p><sub>One example of practice feedback and a follow-up with Heph.</sub></p>
38
+
<p><sub>An illustration of the kind of feedback Hephaestus writes. See the <ahref="https://ls1intum.github.io/Hephaestus/user/ai-code-review">user guide</a> for the real interface.</sub></p>
35
39
</div>
36
40
37
-
Hephaestus is built for software engineering courses, open-source projects, and teams where mentors and maintainers cannot review every contribution themselves.
41
+
> [!IMPORTANT]
42
+
> **Hephaestus is pre-1.0.** It is released continuously and only the
43
+
> [latest release](https://github.com/ls1intum/Hephaestus/releases/latest) is supported — no
44
+
> maintenance branches, no backports. Until 1.0, a *minor* release can change configuration or the
45
+
> API in ways that need you to act, so read the release notes before every upgrade.
46
+
> Version 1.0 is what makes upgrades, configuration, Compose and the REST API predictable:
-**Practice feedback.** Hephaestus uses AI to review pull requests, merge requests, and issues against the engineering practices configured for a workspace. It can post the feedback as comments on the work.
42
-
-**Heph, the AI mentor.** Developers can talk with Heph about feedback and recent issues, commits, reviews, and pull or merge requests. Heph is available in the web app and, when connected, in Slack.
43
-
-**Project context.** Workspace admins can let Hephaestus use messages from selected, visibly monitored Slack channels and documents from selected Outline collections. Outline is a source of context; Hephaestus does not write to it.
44
-
-**Workspaces.** Each workspace connects its own repositories, chooses its practice catalog, connects an AI model through any OpenAI-compatible endpoint, sets a monthly spending cap, and manages its members and teams.
45
-
-**Optional recognition.** Workspace admins can enable achievements, leagues, a weekly leaderboard, and Slack digests of review activity.
52
+
-**Reviews contributions against engineering practices.** A curated catalog ships with it, covering
53
+
how work is scoped and described, how issues are written, how reviews are given and answered,
54
+
testing, failure handling, security, maintainability, recorded decisions, version control, planning
55
+
and communicating in the open. A workspace adopts the groups it cares about and can rewrite any
56
+
practice inside them.
57
+
-**Gets the feedback to the developer.** It can land on the work itself, on the developer's own
58
+
practice pages, or in their next conversation with Hephaestus — whichever stands the best chance of
59
+
being read and acted on. Every piece names the practice it came from and points at the evidence
60
+
behind it.
61
+
-**Answers follow-up questions.** Developers can ask why a suggestion matters or supply the context
62
+
it did not have. In chat Hephaestus goes by Heph, in the web app and, when Slack is connected, in a
63
+
direct message.
64
+
-**Uses only the project context you connect.** GitHub and GitLab repositories, plus optional
65
+
selected Slack channels and Outline collections.
66
+
-**Puts admins in control.** They configure repositories, practices, members, integrations, the AI
67
+
model through any OpenAI-compatible endpoint, and a monthly spending cap.
68
+
-**Ships optional recognition features.** Achievements, leagues, a weekly leaderboard, and a Slack
69
+
digest of review activity, all separate from practice feedback.
46
70
47
71
## How feedback works
48
72
49
-
The loop starts with a developer's project work and the context around it. Hephaestus reviews the work against the engineering practices configured for the workspace, turns what it finds into feedback, and delivers that feedback where it can help.
73
+
1. A workspace connects its GitHub or GitLab repositories and adopts the practices it cares about.
74
+
2. Hephaestus gathers a contribution together with the work around it: the issue, the change, the
75
+
review thread, the conversation.
76
+
3. It records what it observed against those practices, and writes feedback from those observations.
77
+
4. The feedback goes where the developer will actually see it — on the work, on their own practice
78
+
pages, or in conversation.
79
+
5. They act on it, push back with a reason, or let it pass. Their next contribution is read the same
80
+
way.
50
81
51
-
<picture>
52
-
<sourcemedia="(max-width: 640px) and (prefers-color-scheme: dark)"srcset="./docs/images/readme/feedback-loop-mobile-dark.png">
53
-
<sourcemedia="(max-width: 640px) and (prefers-color-scheme: light)"srcset="./docs/images/readme/feedback-loop-mobile-light.png">
54
-
<sourcemedia="(max-width: 1024px) and (prefers-color-scheme: dark)"srcset="./docs/images/readme/feedback-loop-tablet-dark.png">
55
-
<sourcemedia="(max-width: 1024px) and (prefers-color-scheme: light)"srcset="./docs/images/readme/feedback-loop-tablet-light.png">
<imgalt="Hephaestus feedback loop: project work and context are reviewed against workspace practices; practice feedback explains what worked, what could improve, and what to try next; it can appear alongside the work or in conversation with Heph; the developer decides whether to use, question, or skip it before their next piece of project work."src="./docs/images/readme/feedback-loop-light.png"width="1224">
59
-
</picture>
60
-
61
-
Developers decide what helps: use the feedback, question it, or skip it. The cycle continues with their next piece of project work. Hephaestus supports mentors, teachers, and maintainers by covering routine feedback. It does not replace their judgement or the relationships they build with developers.
62
-
63
-
## Project status
64
-
65
-
> [!IMPORTANT]
66
-
> **Hephaestus is still pre-1.0.** Until 1.0, a minor release can change configuration or APIs in ways that require action. If you self-host it, use the [latest release](https://github.com/ls1intum/Hephaestus/releases/latest), read its release notes and the [migration guide](./MIGRATION.md), and test upgrades in staging.
67
-
>
68
-
> We are aiming for a stable **v1.0.0 in mid-September 2026**. Here, stable means [predictable rules](./docs/admin/compatibility-policy.mdx) for upgrades, configuration, Docker Compose, and the REST API — not that development stops.
69
-
>
70
-
> Parts of this model already ship. For v1.0, the goal is to support them together as a stable product:
71
-
>
72
-
> -**Project context:** work in GitHub and GitLab, selected Slack channels, and selected Outline documents.
73
-
> -**Feedback delivery:** alongside work in GitHub or GitLab, in a personal view across projects, and in conversation with Heph in the web app or Slack.
74
-
>
75
-
> Release gates take priority over the date. Follow the [v1.0 milestone](https://github.com/ls1intum/Hephaestus/milestone/5) and [release plan](https://github.com/ls1intum/Hephaestus/issues/1377) for current scope and progress.
82
+
The feedback is advisory. It does not approve a change for merge or grade anyone. Developers decide
83
+
whether it fits their work.
76
84
77
85
## Get started
78
86
79
-
-**TUM deployment:**[open the web app](https://hephaestus.aet.cit.tum.de).
80
-
-**Documentation:** read the [user, administrator, and contributor guides](https://ls1intum.github.io/Hephaestus/).
81
-
-**Self-hosting:** follow the [install guide](https://ls1intum.github.io/Hephaestus/admin/install) ([INSTALL.md](INSTALL.md)) for the supported Docker Compose path.
82
-
-**Development:** use the [local development guide](https://ls1intum.github.io/Hephaestus/contributor/local-development), and explore the web interface in [Storybook](https://main--66a8981a27ced8fef3190d41.chromatic.com/).
87
+
-**Try the hosted app:** open the [TUM deployment](https://hephaestus.aet.cit.tum.de).
88
+
-**Learn how it works:** read the [user guide](https://ls1intum.github.io/Hephaestus/user/overview).
89
+
-**Run your own deployment.** One 64-bit Linux host, 4 vCPUs / 8 GB RAM / 40 GB SSD recommended:
90
+
91
+
```bash
92
+
VERSION=0.74.0 # the release you are installing, without the leading "v"
@@ -89,8 +115,17 @@ Developers decide what helps: use the feedback, question it, or skip it. The cyc
89
115
90
116
## Contributing
91
117
92
-
Contributions are welcome. Before you start, read [CONTRIBUTING.md](./CONTRIBUTING.md) and the [Code of Conduct](./CODE_OF_CONDUCT.md). They cover the development workflow, pull request requirements, community expectations, and the project's identity requirements for contributors.
118
+
Contributions are welcome. Hephaestus is a research project and
119
+
[@FelixTJDietrich](https://github.com/FelixTJDietrich) is its core maintainer, so issues and pull
120
+
requests are triaged on a best-effort basis; security reports get priority.
121
+
[CONTRIBUTING.md](./CONTRIBUTING.md) explains how to set up the project, propose a change, run the
122
+
quality checks, and open a pull request. Participation in the project is governed by the
123
+
[Code of Conduct](./CODE_OF_CONDUCT.md).
93
124
94
-
The project follows a pull request contribution model and GitHub's [Acceptable Use Policies](https://docs.github.com/en/site-policy/acceptable-use-policies).
125
+
## Project origins
95
126
96
-
The project is named after Hephaestus, the Greek god of blacksmiths and craftsmen.
127
+
Hephaestus is an [MIT-licensed](./LICENSE) open-source project developed by
128
+
[Applied Education Technologies](https://aet.cit.tum.de/) at the
129
+
[Technical University of Munich](https://www.tum.de/en/). It is named after the Greek god of the
130
+
forge. In the myth Plato tells, his craft was carried out of the workshop and handed to people so
131
+
they could build for themselves — which is roughly the idea here.
0 commit comments