From cb950b59ff0858fda2d6bf61327ad1ee493029e8 Mon Sep 17 00:00:00 2001 From: tikankika Date: Tue, 7 Jul 2026 13:51:31 +0200 Subject: [PATCH 1/2] docs: move architecture reference to docs/ARCHITECTURE.md, untrack CLAUDE.md (ADR-017) Per ACDM ADR-017, agent-instruction files are local dev-tooling and stay out of the public artefact. Teaching-suite was the last public repo in the family still shipping its root CLAUDE.md. - docs/ARCHITECTURE.md: the architecture and tool reference, now in a conventional human-facing home (content carried over, agent framing dropped) - CLAUDE.md untracked (git rm --cached) and gitignored (/CLAUDE.md, root-anchored); it remains on disk locally as a thin pointer that imports docs/ARCHITECTURE.md - All references updated: README's developer door and docs list, TEACHER_GUIDE, EXAMPLES_POLICY scope list, examples/README language note, methodology/shared_principles Full test suite green (657), including the process-name guard over the touched docs. Co-Authored-By: Claude Opus 4.8 (1M context) --- .gitignore | 3 ++ CHANGELOG.md | 6 +++ EXAMPLES_POLICY.md | 2 +- README.md | 4 +- CLAUDE.md => docs/ARCHITECTURE.md | 63 +++++++++++++++---------------- docs/TEACHER_GUIDE.md | 2 +- examples/README.md | 2 +- methodology/shared_principles.md | 2 +- 8 files changed, 45 insertions(+), 39 deletions(-) rename CLAUDE.md => docs/ARCHITECTURE.md (89%) diff --git a/.gitignore b/.gitignore index 63777ea..c32cd2d 100644 --- a/.gitignore +++ b/.gitignore @@ -23,6 +23,9 @@ Thumbs.db # Claude Code dev-support — local only, never published (B7 exclusion: .claude/ stays out of the public artifact) .claude/ +# Root agent-instruction file — dev-tooling, untracked per ACDM ADR-017; the public +# architecture reference lives in docs/ARCHITECTURE.md +/CLAUDE.md # Local MCP server config (contains absolute paths) .mcp.json diff --git a/CHANGELOG.md b/CHANGELOG.md index 9a95835..49a579b 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,6 +4,12 @@ All notable changes to Teaching Suite are documented here. The format follows [Keep a Changelog](https://keepachangelog.com/), and the project uses [Semantic Versioning](https://semver.org/). +## [Unreleased] + +### Changed + +- **The architecture and tool reference moved from `CLAUDE.md` to `docs/ARCHITECTURE.md`.** Per ACDM ADR-017's dev-tooling boundary, agent-instruction files are local tooling and stay out of the public artefact — teaching-suite was the last public repo in the family still shipping its root `CLAUDE.md`. The content now lives in a human-facing `docs/ARCHITECTURE.md` (same reference, conventional home); `CLAUDE.md` is untracked and gitignored, and all links (README's developer door, TEACHER_GUIDE, EXAMPLES_POLICY, examples, methodology) point at the new location. + ## [0.6.0] - 2026-07-07 ### Added diff --git a/EXAMPLES_POLICY.md b/EXAMPLES_POLICY.md index 406a1cc..c7ce76b 100644 --- a/EXAMPLES_POLICY.md +++ b/EXAMPLES_POLICY.md @@ -16,7 +16,7 @@ documented answer: **no**. This applies to all illustrative and sample content, including: - `examples/` — worked walkthroughs and the artefacts they produce -- Code and tool examples in `README.md`, `CLAUDE.md`, and `docs/` +- Code and tool examples in `README.md` and `docs/` - Illustrative snippets inside the methodology documents (`methodology/`) - Test fixtures and sample inputs under `tests/` diff --git a/README.md b/README.md index a9dc3c3..f162574 100644 --- a/README.md +++ b/README.md @@ -129,7 +129,7 @@ The interesting part is the **methodology**, not the plumbing — three nested c Clone, build, and point it at a folder. It is an MCP server (Node.js) that runs inside Claude Desktop. - [Quick start](#quick-start) — install, build, test, and the Claude Desktop configuration -- [CLAUDE.md](CLAUDE.md) — architecture and the full tool reference +- [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) — architecture and the full tool reference ## Features @@ -270,7 +270,7 @@ The real privacy guarantees are the `--workspace` lockdown and the absence of ne ## Documentation - [docs/TEACHER_GUIDE.md](docs/TEACHER_GUIDE.md) - How to work with Teaching Suite as a teacher -- [CLAUDE.md](CLAUDE.md) - Architecture and tool reference +- [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) - Architecture and tool reference - [ROADMAP.md](ROADMAP.md) - Direction towards 1.0 - [CHANGELOG.md](CHANGELOG.md) - Release history - [CONTRIBUTING.md](CONTRIBUTING.md) - How to contribute diff --git a/CLAUDE.md b/docs/ARCHITECTURE.md similarity index 89% rename from CLAUDE.md rename to docs/ARCHITECTURE.md index 690b19d..99814ea 100644 --- a/CLAUDE.md +++ b/docs/ARCHITECTURE.md @@ -1,6 +1,4 @@ -# CLAUDE.md - Teaching Suite - -## Project Overview +# Architecture Teaching Suite is an MCP (Model Context Protocol) server that scaffolds guided processes for teachers. It helps capture ideas, reflect on lessons, plan teaching, and track pedagogical goals. @@ -8,7 +6,7 @@ Teaching Suite is an MCP (Model Context Protocol) server that scaffolds guided p **Version:** 0.6.0 -## Architecture +## Repository layout ``` teaching-suite/ @@ -16,7 +14,7 @@ teaching-suite/ │ ├── index.ts # MCP server entry point │ │ │ ├── tools/ -│ │ ├── core/ # Core Tools (4 tools) +│ │ ├── core/ # Core tools (4 tools) │ │ │ ├── index.ts │ │ │ ├── workspace.ts # Path validation, security │ │ │ ├── file-read.ts @@ -24,7 +22,7 @@ teaching-suite/ │ │ │ ├── file-edit.ts │ │ │ └── file-search.ts │ │ │ -│ │ ├── composite/ # Composite Tools (6 tools) +│ │ ├── composite/ # Composite tools (6 tools) │ │ │ ├── index.ts │ │ │ ├── capture-idea.ts # Quick idea capture │ │ │ ├── intelligent-save.ts # Smart file saving @@ -33,7 +31,7 @@ teaching-suite/ │ │ │ ├── quick-save-session.ts │ │ │ └── log-process-event.ts # Append event to course process log │ │ │ -│ │ ├── mechanical/ # Mechanical Tools (7 tools) +│ │ ├── mechanical/ # Mechanical tools (7 tools) │ │ │ ├── load-methodology.ts # Load methodology docs │ │ │ ├── find-context.ts # Search workspace for files (types derived from registry; Material/ recursive) │ │ │ ├── context-load.ts # Load _config/ at session start @@ -42,11 +40,11 @@ teaching-suite/ │ │ │ ├── parse-lesson-plan-yaml.ts # Parse lesson-plan YAML │ │ │ └── aggregate-logs.ts # Cross-server chronological timeline │ │ │ -│ │ ├── setup/ # Setup Tools (2 tools) +│ │ ├── setup/ # Setup tools (2 tools) │ │ │ ├── project-init.ts # Initialise course structure │ │ │ └── init-profession.ts # Initialise Profession/Manifest/ │ │ │ -│ │ └── sources/ # Source Tools (5 tools) +│ │ └── sources/ # Source tools (5 tools) │ │ ├── index.ts │ │ ├── scan.ts │ │ └── track.ts @@ -61,7 +59,7 @@ teaching-suite/ │ ├── methodology/ # Pedagogical guides (for Claude Desktop) │ ├── README.md # Top-level operative guide (v3) -│ ├── pedagogisk_arkitektur.md # Conceptual spine (v3) +│ ├── pedagogisk_arkitektur.md # Conceptual spine (v3) │ ├── synlighetsprincip.md # Visibility principle (v3) │ ├── tensions.md # Pedagogical tensions (v3) │ ├── lesson/ # Lesson cycle (v3): pre_lesson, post_lesson_auto, post_lesson_refl, bridge @@ -79,13 +77,12 @@ teaching-suite/ │ ├── tests/ # Test suite (Vitest) │ -├── CLAUDE.md # This file └── package.json ``` -## Tool Inventory (24 tools) +## Tool inventory (24 tools) -### Core Tools (4) +### Core tools (4) | Tool | Purpose | |------|---------| @@ -94,9 +91,9 @@ teaching-suite/ | `file_edit` | Edit existing files (replace, insert, append, delete) | | `file_search` | Search text across files in workspace | -All core tools enforce **workspace validation** via `--workspace` flag. +All core tools enforce **workspace validation** via the `--workspace` flag. -### Composite Tools (6) +### Composite tools (6) | Tool | Purpose | |------|---------| @@ -107,7 +104,7 @@ All core tools enforce **workspace validation** via `--workspace` flag. | `quick_save_session` | Full workflow: capture → format → save | | `log_process_event` | Append a structured event to the course process log | -### Mechanical Tools (7) +### Mechanical tools (7) | Tool | Purpose | |------|---------| @@ -119,14 +116,14 @@ All core tools enforce **workspace validation** via `--workspace` flag. | `parse_lesson_plan_yaml` | Parse a lesson plan's YAML frontmatter and body | | `aggregate_logs` | Unified chronological timeline across Teaching Suite, QuestionForge, Assessment Suite | -### Setup Tools (2) +### Setup tools (2) | Tool | Purpose | |------|---------| | `project_init` | Create folder structure, copy methodology docs, initialise project state | | `init_profession` | Initialise workspace-level `Profession/Manifest/` (sibling to course folders) | -### Source Tools (5) +### Source tools (5) | Tool | Purpose | |------|---------| @@ -136,7 +133,7 @@ All core tools enforce **workspace validation** via `--workspace` flag. | `source_remove` | Remove source by role | | `source_update_usage` | Track source usage | -## Course Workspace Structure +## Course workspace structure When `project_init` is called with `type: 'course'`, it creates this structure in the workspace: @@ -165,12 +162,12 @@ When `project_init` is called with `type: 'course'`, it creates this structure i │ — Course material — ├── Styrdokument/ # Syllabus, curriculum, commentary ├── Material/ # Course material (own + imported) -│ ├── WIP/ # Work in progress (drafts) -│ ├── Klart/ # Ready for lesson -│ │ ├── Presentationer/ # .pptx, .pdf -│ │ ├── Övningar/ # Exercises, lab instructions -│ │ └── Övrigt/ # Films, links, handouts -│ └── Resurser/ # Imported (others' material, references) +│ ├── WIP/ # Work in progress (drafts) +│ ├── Klart/ # Ready for lesson +│ │ ├── Presentationer/ # .pptx, .pdf +│ │ ├── Övningar/ # Exercises, lab instructions +│ │ └── Övrigt/ # Films, links, handouts +│ └── Resurser/ # Imported (others' material, references) ├── Exams/ # Exams, QuestionForge material │ │ — System — @@ -182,7 +179,7 @@ When `project_init` is called with `type: 'course'`, it creates this structure i For non-course types (e.g., `lesson`), the legacy flat structure is used: `Reflections/`, `Lesson_Plans/`, `Ideas/`, etc. -## MCP Ecosystem +## MCP ecosystem Teaching Suite is one of several MCP servers that share the same Nextcloud workspace: @@ -208,7 +205,7 @@ QuestionForge (qf-scaffolding-v2, qf-pipeline-v2) **Separation principle:** Teaching Suite handles the teacher's professional processes. Assessment data (student work, grades) stays in Assessment Suite's own workspace. Only *insights about teaching* flow back. -## Workspace Security +## Workspace security All file operations require a `--workspace` flag at server startup: @@ -227,7 +224,7 @@ All file operations require a `--workspace` flag at server startup: - Path traversal attempts (e.g., `../../etc/passwd`) are blocked - The content scanner (`content-scanner.ts`) is an **advisory** keyword matcher: it flags a small set of Swedish privacy/exam-related terms in content and surfaces a warning. It does **not** detect names or personal numbers, does not anonymise, and never blocks an operation. It is a reminder, not a guarantee — anonymise sensitive data before importing it. -## Key Commands +## Key commands ```bash npm install # Install dependencies @@ -236,15 +233,15 @@ npm test # Run the full test suite npm start # Start MCP server ``` -## Design Principles +## Design principles 1. **Methodology = Pedagogik** (markdown files for Claude Desktop) -2. **Core Tools = Teknik** (generic MCP tools) +2. **Core tools = Teknik** (generic MCP tools) 3. **Claude Desktop = Orkestrering** (reads methodology, uses tools) 4. **Teacher THINKS, MCP STRUCTURES** 5. **Never start from scratch** (build on history) -## Language Policy +## Language policy This project is **deliberately bilingual**. Swedish teachers are the primary audience, so teacher-facing content stays in Swedish; the code stays in English @@ -256,9 +253,9 @@ for international contributors. This is a design choice, not a translation backl - **English-language content** (README, CONTRIBUTING, international-facing docs): British English — see ADR-007 (`docs/decisions/ADR-007-bilingual-language-policy.md`) - **Why**: English code lowers the barrier for international contributors; Swedish UX and methodology because the teachers who use this tool think and work in Swedish. Translating the methodology to English would not serve the primary audience. -## Session Workflow +## Session workflow -When to use session capture tools: +When to use the session capture tools: 1. **During conversation** — ideas emerge naturally 2. **At session end** — `quick_save_session` to persist everything diff --git a/docs/TEACHER_GUIDE.md b/docs/TEACHER_GUIDE.md index 040fa28..8154de2 100644 --- a/docs/TEACHER_GUIDE.md +++ b/docs/TEACHER_GUIDE.md @@ -251,4 +251,4 @@ not to automate the thinking away. --- *For the methodology, see the cycle folders in `methodology/` (`lesson/`, `course/`, -`profession/`); for architecture and the full tool reference, see `CLAUDE.md`.* +`profession/`); for architecture and the full tool reference, see `docs/ARCHITECTURE.md`.* diff --git a/examples/README.md b/examples/README.md index 009d90e..a2c6c71 100644 --- a/examples/README.md +++ b/examples/README.md @@ -27,5 +27,5 @@ Start with the walkthrough README. > **Note on language.** The reflection content is in Swedish — Teaching Suite's > primary audience is Swedish teachers, and teacher-facing artifacts stay in -> Swedish (see the Language Policy in the root `CLAUDE.md`). The walkthrough +> Swedish (see the Language policy in `docs/ARCHITECTURE.md`). The walkthrough > prose is in English. diff --git a/methodology/shared_principles.md b/methodology/shared_principles.md index 6a1c8fd..96e3474 100644 --- a/methodology/shared_principles.md +++ b/methodology/shared_principles.md @@ -301,7 +301,7 @@ Extraktion (auto-pipeline) och tolkning (Gibbs) är kategoriskt olika kognitiva - Auto-pipeline = "vad hände" (data, timing, begrepp, uppgifter — mekaniskt) - Gibbs = "vad betyder det" (meningsskapande, känslor, pedagogiska beslut — manuellt) -Att bunta ihop dem skulle tvinga läraren genom hela pipelinen varje gång, och skulle blurra att de är olika saker. Separeringen respekterar `Teacher THINKS, MCP STRUCTURES`-principen från CLAUDE.md. +Att bunta ihop dem skulle tvinga läraren genom hela pipelinen varje gång, och skulle blurra att de är olika saker. Separeringen respekterar `Teacher THINKS, MCP STRUCTURES`-principen från `docs/ARCHITECTURE.md`. --- From cfcf2df655d68cdf2903c24f734efd6a81c10a62 Mon Sep 17 00:00:00 2001 From: tikankika Date: Tue, 7 Jul 2026 13:53:04 +0200 Subject: [PATCH 2/2] =?UTF-8?q?docs(decisions):=20ADR-009=20=E2=80=94=20ro?= =?UTF-8?q?ot=20CLAUDE.md=20exclusion=20and=20docs/ARCHITECTURE.md?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Records the decision, the alternatives considered (keep public / documented exception / exclude and relocate), and the consequences. Co-Authored-By: Claude Opus 4.8 (1M context) --- docs/decisions/ADR-009-claude-md-exclusion.md | 63 +++++++++++++++++++ docs/decisions/README.md | 1 + 2 files changed, 64 insertions(+) create mode 100644 docs/decisions/ADR-009-claude-md-exclusion.md diff --git a/docs/decisions/ADR-009-claude-md-exclusion.md b/docs/decisions/ADR-009-claude-md-exclusion.md new file mode 100644 index 0000000..464741f --- /dev/null +++ b/docs/decisions/ADR-009-claude-md-exclusion.md @@ -0,0 +1,63 @@ +--- +type: decision +status: active +created: 2026-07-07 +origin: code +project: teaching-suite +relates_to: [ADR-007] +--- + +# ADR-009: Root `CLAUDE.md` is dev-tooling — the public reference lives in `docs/ARCHITECTURE.md` + +## Context + +ACDM ADR-017 (2026-06-24) settled that `.claude/` is local dev-tooling and is +gitignored in every downstream repo; the public form of any policy lives in +conventional docs. It left one artefact undecided for this repo: the root +`CLAUDE.md`, which teaching-suite alone in the family still shipped publicly +(QuestionForge and Assessment Suite never tracked theirs; edusafe-pipeline +excludes it at its public flip). The file doubled as the project's architecture +and tool reference, and README's developer door linked to it. + +## Problem + +Should teaching-suite keep shipping its root `CLAUDE.md` publicly, or align +with the family boundary — and if it aligns, where does the architecture +reference go? + +## Alternatives considered + +1. **Keep `CLAUDE.md` public.** It contained nothing sensitive and served as + the developer reference. Rejected: it is an agent-instruction file by name + and convention, and keeping it tracked leaves the family inconsistent — + the same rationale ADR-017 rejected for `.claude/rules/`. +2. **Keep it public and document the exception.** Rejected: the exception has + no benefit over a conventional docs file; readers expect architecture in + `docs/`, not in an agent file. +3. **Exclude it; move the reference to `docs/ARCHITECTURE.md`. (chosen)** + The content is architecture documentation and gets a human-facing home; + the agent file becomes local dev-tooling like everything else under + `.claude/`. + +## Decision + +- The architecture and full tool reference lives in **`docs/ARCHITECTURE.md`** + (tracked, public, human-facing). +- Root **`CLAUDE.md` is untracked and gitignored** (`/CLAUDE.md`, + root-anchored). It remains on disk as a thin local pointer that imports + `docs/ARCHITECTURE.md`, so agent sessions and public readers share one + source of truth — the architecture is edited in `docs/ARCHITECTURE.md`, + never in the pointer. + +## Consequences + +- No public repo in the family ships agent-instruction files; the B7 + exclusion (`.claude/` out of the public artefact) extends to root + `CLAUDE.md`. +- All public links (README developer door, TEACHER_GUIDE, EXAMPLES_POLICY, + examples, methodology) point at `docs/ARCHITECTURE.md`. +- The historical `CLAUDE.md` revisions remain in git history; nothing + sensitive was in them (reviewed — architecture reference only). +- A fresh clone has no root `CLAUDE.md`; contributors read + `docs/ARCHITECTURE.md`, and ACDM's `init_project` can seed a local pointer + where needed. diff --git a/docs/decisions/README.md b/docs/decisions/README.md index 163572d..e5d848d 100644 --- a/docs/decisions/README.md +++ b/docs/decisions/README.md @@ -12,6 +12,7 @@ point-in-time records of significant design decisions and why they were made. | [ADR-005](ADR-005-parse-lesson-transcript-mode-parameter.md) | `parse_lesson_transcript` mode parameter | | [ADR-007](ADR-007-bilingual-language-policy.md) | Bilingual language policy | | [ADR-008](ADR-008-license-polyform-noncommercial.md) | Licence — PolyForm Noncommercial | +| [ADR-009](ADR-009-claude-md-exclusion.md) | Root `CLAUDE.md` is dev-tooling — public reference in `docs/ARCHITECTURE.md` | (ADR-006 was never issued; the numbering gap is intentional.)