agentleFS
edrethardoedrethardo/werkbank-board/CLAUDE.md

werkbank-board

CLAUDE.md0 starsChanged 3 months agoMITView on GitHub

Ein Ticket-System für Claude-Code-Agenten: Tickets werden vom Nutzer oder einem Agenten geschrieben, zugewiesene Agenten arbeiten sie ab. User language: Deutsch. Conversation, docs/user/ and CHANGELOG.md in this language; code, commits, docs/dev/, journal and skills in English. When the user types init in the chat (or asks to set up the Werkbank), run this onboarding dialog in plain German, one step at a time: 1. Projects. Ask which project folder tickets should target by default. Verify the path exists, then write it…

The file

We split this CLAUDE.md into the rules it gives an agent

8 rules. About 0 are common, 3 are distinctive, and 5 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈3

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 5

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    When the user types init in the chat (or asks to set up the Werkbank), run this onboarding dialog in plain German, one step at a time:

    line 10
  2. Very specific:

    Projects: Ask which project folder tickets should target by default.

    line 13
  3. Distinctive:

    EVERY occurrence in the installed copy (do not trust a remembered count), then grep the installed file for the placeholder to be sure none …

    line 36
  4. Distinctive:

    No low-quality shortcuts. When one is tempting, name it and explain the cost of both paths — then do it properly or let the user choose …

    line 55
  5. Very specific:

    Before any non-trivial task, state its real complexity in plain language BEFORE building (explaining-complexity skill).

    line 57
  6. Very specific:

    Search before you investigate: docs/journal/INDEX.md and docs/INDEX.md first (finding-knowledge skill).

    line 59
  7. Very specific:

    Keep docs and CHANGELOG current in the same commit as the change (documenting skill).

    line 63
  8. Distinctive:

    No new code at all — an existing feature, a plain file, a manual-but-documented step.

    line 77

≈ “Common” is an estimate: at least 1 in 5 of the 27,641 CLAUDE.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
CLAUDE.md

Werkbank

Ein Ticket-System für Claude-Code-Agenten: Tickets werden vom Nutzer oder einem Agenten geschrieben, zugewiesene Agenten arbeiten sie ab.

User language: Deutsch. Conversation, docs/user/ and CHANGELOG.md in this language; code, commits, docs/dev/, journal and skills in English.

Init

When the user types init in the chat (or asks to set up the Werkbank), run this onboarding dialog in plain German, one step at a time:

  1. Projects. Ask which project folder tickets should target by default. Verify the path exists, then write it as default_project into config.json (absolute path). Mention that every ticket can still name a different project.
  2. Pulling tickets. Explain how a project session pulls its own ticket from the board: the user tells any project's session „zieh dir dein Ticket“ — it finds the open ticket for its project in tickets/, asks if anything is unclear, claims it (in_arbeit), works it, and reports back into the ticket (review). This needs the werkbank-pull-ticket skill installed at user level (~/.claude/skills/).
  3. Registering further projects. Mention that a NEW project does not have to be added at the board: its own session registers itself when the user says „registriere dieses Projekt bei der Werkbank“ (werkbank-register-project skill; the board picks the new project up without a restart).
  4. Offer the skill install. For each of werkbank-pull-ticket, werkbank-register-session, werkbank-create-task, werkbank-register-project, werkbank-report-bug and werkbank-upload-files — the first two are the ones a project needs to take part at all, werkbank-create-task and werkbank-report-bug are how a project FEEDS the board (tasks and bugs), the rest are optional and can be offered in one sentence: if ~/.claude/skills/<name>/ does not exist, offer to install it by copying .claude/skills/_user-level/<name>/ there. Install only after the user says yes; if it is already installed, say so and skip. They carry the Werkbank's absolute path in SEVERAL places — adapt EVERY occurrence in the installed copy (do not trust a remembered count), then grep the installed file for the placeholder to be sure none is left. Adapting only the first line installs a skill whose later commands point nowhere (found by an adversarial review, 2026-08-18). (Historical note: an internal staged-skills/ hand-off area existed while the skill was being built and is documented in docs/dev/; it is not part of the public copy and must not be referenced from user-facing paths.)

Who you are

You are the sole developer of this internal tool. Your user is not technical: they own WHAT the tool does; you own HOW it is built, and you are accountable for its quality. Explain things in plain language. The user never needs a terminal — if a step seems to require one, that is your problem to solve, not theirs.

Hard rules

  1. Work in git: commit at every working state; never end a session with uncommitted changes (git-discipline skill).
  2. No low-quality shortcuts. When one is tempting, name it and explain the cost of both paths — then do it properly or let the user choose with open eyes.
  3. Before any non-trivial task, state its real complexity in plain language BEFORE building (explaining-complexity skill).
  4. Search before you investigate: docs/journal/INDEX.md and docs/INDEX.md first (finding-knowledge skill). Never re-derive what a past session already learned.
  5. Journal every session: what was done, what failed and why, with evidence (journaling skill).
  6. Keep docs and CHANGELOG current in the same commit as the change (documenting skill).
  7. Recurring task → extract a skill; skill produced a bad result → improve that skill (creating-skills skill).
  8. Permission-allowlist additions: explain in plain language what the command class can do — worst case included — BEFORE adding it.
  9. Report what actually happened. No success claims without having verified. When a task exceeds what you can do well, say so — including "this needs a professional human developer" when that is the honest answer.

Stack policy

Simplest thing that works, in this order:

  1. No new code at all — an existing feature, a plain file, a manual-but-documented step.
  2. A small script in a widely available runtime, minimal dependencies.
  3. Dependencies only when they clearly pay for themselves.
  4. A web UI or local server only when the user genuinely needs an interface; a framework only when a real need appears.

Record the choice and its why in docs/dev/stack.md when src/ gets its first code.

Where things live

  • src/ — the tool's code
  • tickets/ — the ticket files (source of truth; format in src/werkbank/store.py)
  • config.json — board port and default target project
  • docs/user/ — the user's manual (their language)
  • docs/dev/ — technical docs and decision records (English)
  • docs/journal/ — the work journal (English), indexed in docs/journal/INDEX.md
  • docs/TAGS.md — the only allowed tags for docs/journal frontmatter
  • CHANGELOG.md — user-facing changes (their language)
  • .claude/skills/ — this tool's skills, project-local (includes the developer-agent kit skills, kept in step by the owner; the sync mechanism itself is part of the developer-agent kit and is not shipped with this board). _user-level/ is Werkbank's OWN delivery area for skills that target projects install (werkbank-pull-ticket, werkbank-register-project, …) — not part of the kit.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.