cc-discipline 2.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 TechHU
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,153 @@
+# cc-discipline
+
+Guardrails for Claude Code. Shell hooks that **actually block** bad behavior, not just markdown that asks nicely.
+
+[中文文档](README.zh-CN.md)
+
+## The Problem
+
+Claude Code in long sessions tends to:
+- Edit the same file 5+ times chasing symptoms instead of finding root cause
+- See an error and immediately change code without understanding it
+- Lose track of what it was doing after context compaction
+
+Markdown rules help, but Claude can ignore them. **Hooks can't be ignored** — they run as shell scripts and `exit 2` physically blocks the operation.
+
+## What This Does
+
+### Hooks (the enforcer)
+
+Three shell scripts that run automatically before/after Claude's actions:
+
+**`streak-breaker.sh`** — Tracks per-file edit counts. Warns at 3, **hard-blocks at 5**. Forces Claude to stop and find the root cause instead of endlessly patching.
+
+```
+MOLE-WHACKING ALERT (hard stop)
+File src/auth.py has been edited 5 times.
+You are repeatedly patching symptoms instead of solving the root cause.
+Required actions:
+  1. Stop editing this file immediately
+  2. Review the purpose of all 5 edits
+  3. Look for the common root cause
+  4. Report findings to the user and wait for guidance
+```
+
+**`pre-edit-guard.sh`** — Checks `docs/debug-log.md` for unverified hypotheses. If you're debugging and haven't finished the process, it blocks source code edits until you do.
+
+**`post-error-remind.sh`** — Detects error patterns (test failures, crashes, build errors) in command output and injects a debugging discipline reminder before Claude can react impulsively.
+
+### Rules (the reminders)
+
+Auto-injected markdown in `.claude/rules/` — Claude sees them when operating on matching files. Not as strong as hooks, but provides structure:
+
+- Debugging process: gather → hypothesize → verify → fix (no skipping)
+- Pre-edit checklist: understand the file, know the impact, fix root cause
+- Mole-whacking detection: recognize the pattern, stop, report
+- Phase discipline: stay in research/plan/implement, don't jump ahead
+- Multi-task gates: complete tasks in order, confirm each before moving on
+- Tech stack rules for Python, JS/TS, embedded, RTL, mobile
+
+### Subagents (the auditors)
+
+- **reviewer** — Reviews your modification plan in a separate context. Challenges assumptions, suggests alternatives, checks for missing edge cases.
+- **investigator** — Researches the codebase in isolation. Returns structured findings without polluting your main conversation.
+
+## Install
+
+```bash
+git clone https://github.com/TechHU-GS/cc-discipline.git ~/.cc-discipline
+cd your-project
+bash ~/.cc-discipline/init.sh
+```
+
+The installer is interactive — pick your tech stack, name your project, done.
+
+**Already have a `.claude/` setup?** The installer detects this and runs in append mode:
+- Your `CLAUDE.md` is **never overwritten**
+- Your `settings.json` hooks are **preserved** (cc-discipline hooks are merged in via `jq`)
+- Your custom rules, agents, and docs are **untouched**
+- A timestamped backup is created before any changes
+
+**Upgrading?** Just run `init.sh` again. It detects the existing installation and updates framework files while preserving your configuration.
+
+## What Gets Installed
+
+```
+.claude/
+├── rules/                    # Auto-injected when Claude operates on matching files
+│   ├── 00-core-principles.md
+│   ├── 01-debugging.md
+│   ├── 02-before-edit.md
+│   ├── 03-context-mgmt.md
+│   ├── 04-no-mole-whacking.md
+│   ├── 05-phase-discipline.md
+│   ├── 06-multi-task.md
+│   └── stacks/               # Picked during install
+├── hooks/                    # Shell scripts, exit 2 = block operation
+│   ├── streak-breaker.sh
+│   ├── pre-edit-guard.sh
+│   └── post-error-remind.sh
+├── agents/
+│   ├── reviewer.md
+│   └── investigator.md
+├── skills/
+│   └── commit/SKILL.md       # /commit: test → update docs → commit
+└── settings.json             # Hook registration
+docs/
+├── progress.md               # Claude maintains this, read after compact
+└── debug-log.md              # Debug session tracking
+CLAUDE.md                     # Your project info (you fill this in)
+```
+
+## Customization
+
+**Adjust hook strictness:**
+
+```bash
+# In .claude/hooks/streak-breaker.sh
+WARN_THRESHOLD=3    # Warn after N edits to same file
+STOP_THRESHOLD=5    # Hard block after N edits
+```
+
+**Add your own rules:**
+
+```bash
+cat > .claude/rules/my-rule.md << 'EOF'
+---
+globs: "src/api/**/*"
+description: "API layer rules"
+---
+- All API changes must be backwards-compatible
+- New endpoints need OpenAPI spec updates
+EOF
+```
+
+**Write your own hooks:**
+
+Any script in `.claude/hooks/` can be registered in `settings.json`. The key behaviors:
+- `exit 0` = allow (stdout can inject context via JSON for PreToolUse hooks)
+- `exit 2` + stderr = block operation, stderr message shown to Claude
+
+See [Claude Code hooks docs](https://docs.anthropic.com/en/docs/claude-code/hooks) for the full spec.
+
+## FAQ
+
+**Is this just markdown rules?**
+No. The hooks are the real enforcement — they're shell scripts that physically block operations. The rules are supplementary structure.
+
+**Does it slow things down?**
+No. Hooks are lightweight shell scripts, typically <100ms. Rules add ~8KB to context (~2%).
+
+**Should I commit `.claude/` to git?**
+Yes. Team members get the same guardrails. Hook paths use `$CLAUDE_PROJECT_DIR`, so they work across machines.
+
+**Does it work with existing projects?**
+Yes. The installer has an append mode that merges with your existing `.claude/` configuration without overwriting anything. Run `init.sh` and it auto-detects.
+
+## Contributing
+
+PRs welcome — especially new hooks. The hooks are where the real value is.
+
+## License
+
+[MIT](LICENSE)

package/README.zh-CN.md

@@ -0,0 +1,207 @@
+# cc-discipline
+
+**Claude Code 项目纪律框架** — 让 AI 编码助手在复杂任务中保持专注和纪律。
+
+解决 Claude Code 在长对话、复杂任务中常见的问题：
+- 🎯 思路跑偏、丢失主线目标
+- 🔨 打地鼠式修补症状
+- ⚡ 急于锁定第一个解释
+- 🧠 compact 后丢失关键上下文和原则
+- 🔄 反复犯同样的错误
+
+## 架构：三层防线
+
+```
+┌─────────────────────────────────────────┐
+│  Layer 3: Subagents（独立判断）          │
+│  reviewer — 独立 context 审查方案       │
+│  investigator — 隔离调研不污染主对话    │
+├─────────────────────────────────────────┤
+│  Layer 2: Hooks（代码强制）             │
+│  pre-edit-guard — 编辑前检查纪律       │
+│  streak-breaker — 检测打地鼠模式       │
+│  post-error-remind — 错误后提醒流程    │
+├─────────────────────────────────────────┤
+│  Layer 1: Rules（自动注入）             │
+│  core-principles — 核心原则            │
+│  debugging — 调试纪律                  │
+│  before-edit — 修改前检查              │
+│  context-mgmt — 上下文管理             │
+│  no-mole-whacking — 反打地鼠           │
+│  stacks/* — 技术栈特有规则             │
+├─────────────────────────────────────────┤
+│  Foundation: CLAUDE.md + docs/          │
+│  项目信息 + 进度记录 + 调试日志         │
+└─────────────────────────────────────────┘
+```
+
+**Rules** = 贴在它眼前（自动注入，按路径触发）  
+**Hooks** = 锁住它的手（代码级强制，可阻止操作）  
+**Subagents** = 派人盯着它（独立 context 审查，不被主对话惯性影响）
+
+## 快速开始
+
+### 方法 1: 克隆 + 初始化脚本
+
+```bash
+git clone https://github.com/TechHU-GS/cc-discipline.git ~/.cc-discipline
+
+# In your project directory:
+cd your-project
+bash ~/.cc-discipline/init.sh
+```
+
+### 方法 2: GitHub Template
+
+1. 点击本仓库的 **Use this template** 按钮
+2. 创建新项目后，编辑 `CLAUDE.md` 填写项目信息
+
+### 方法 3: 只安装全局规则
+
+```bash
+git clone https://github.com/TechHU-GS/cc-discipline.git /tmp/cc-discipline
+cp /tmp/cc-discipline/global/CLAUDE.md ~/.claude/CLAUDE.md
+```
+
+## 文件结构
+
+```
+your-project/
+├── CLAUDE.md                          # 项目特有信息（你维护）
+├── .claude/
+│   ├── settings.json                  # Hooks 配置
+│   ├── rules/
+│   │   ├── 00-core-principles.md      # 核心工作原则
+│   │   ├── 01-debugging.md            # 调试纪律
+│   │   ├── 02-before-edit.md          # 修改前检查
+│   │   ├── 03-context-mgmt.md         # 上下文管理
+│   │   ├── 04-no-mole-whacking.md     # 反打地鼠
+│   │   └── stacks/                    # 技术栈特有规则
+│   │       ├── rtl.md                 #   RTL / IC 设计
+│   │       ├── embedded.md            #   嵌入式 C/C++
+│   │       ├── python.md              #   Python
+│   │       ├── js-ts.md               #   JavaScript/TypeScript
+│   │       └── mobile.md              #   移动端
+│   ├── hooks/
+│   │   ├── pre-edit-guard.sh          # 编辑前纪律检查
+│   │   ├── streak-breaker.sh          # 打地鼠检测（同文件编辑≥5次硬停止）
+│   │   └── post-error-remind.sh       # 错误后调试流程提醒
+│   ├── agents/
+│   │   ├── reviewer.md                # 代码审查员（独立 context）
+│   │   └── investigator.md            # 代码调查员（隔离调研）
+│   └── skills/
+│       └── commit/SKILL.md            # /commit 智能提交
+├── docs/
+│   ├── progress.md                    # 进度记录（Claude 维护）
+│   └── debug-log.md                   # 调试日志（Claude 维护）
+└── ~/.claude/
+    └── CLAUDE.md                      # 全局通用纪律（可选）
+```
+
+## 各层详解
+
+### Rules（自动注入）
+
+放在 `.claude/rules/` 下的 Markdown 文件会根据 `globs` 匹配自动注入到 Claude 的上下文中。
+Claude 无法选择性忽略这些规则——它们在操作匹配文件时会自动出现。
+
+**核心规则**（对所有文件生效）：
+- `00-core-principles.md` — 先理解再动手、不锁定第一解释、连续3次失败必须停下
+- `01-debugging.md` — 四阶段调试流程（收集→假设→验证→修复）
+- `03-context-mgmt.md` — 主动检查点、调研隔离、compact 策略
+- `04-no-mole-whacking.md` — 打地鼠检测和汇报模板
+
+**源码规则**（编辑 src/ 等目录时生效）：
+- `02-before-edit.md` — 修改前的 5 项强制检查
+
+**技术栈规则**（按文件类型触发）：
+- `.v/.sv/.vhd` → RTL 规则（时序意识、CDC 检查、综合/仿真区分）
+- `.c/.h` → 嵌入式规则（资源意识、中断安全、volatile）
+- `.py` → Python 规则（类型标注、依赖管理、测试）
+- `.js/.ts/.tsx` → JS/TS 规则（类型安全、异步处理）
+- `.swift/.kt/.dart` → 移动端规则（主线程、生命周期、权限）
+
+### Hooks（代码强制）
+
+Hooks 是在 Claude 执行操作前/后自动运行的 shell 脚本。**exit 2 可以直接阻止操作**。
+
+| Hook | 触发时机 | 作用 |
+|------|---------|------|
+| `pre-edit-guard.sh` | 编辑文件前 | 检查是否有未完成的调试流程 |
+| `streak-breaker.sh` | 编辑文件前 | 同文件编辑 ≥3 次警告，≥5 次硬停止 |
+| `post-error-remind.sh` | 执行命令后 | 检测到错误输出时提醒遵守调试纪律 |
+
+**调整硬度**：编辑 hook 脚本中的 `exit` 返回值：
+- `exit 0` = 允许操作（可附带提醒信息）
+- `exit 1` = 报错但不阻止操作（hook 执行失败）
+- `exit 2` = 阻止操作，Claude 看到消息后会调整行为（硬停止）
+
+### Subagents（独立判断）
+
+| Agent | 用途 | 权限 |
+|-------|------|------|
+| `reviewer` | 审查修改方案是否合理 | 只读（Read, Grep, Glob） |
+| `investigator` | 深入调研代码库 | 只读 + Bash（仅限查询命令） |
+
+使用方式：
+```
+让 reviewer 审查我的修改方案
+让 investigator 调查 src/auth/ 模块的实现
+```
+
+## 自定义
+
+### 添加项目特有规则
+
+```bash
+# Create a new rule
+cat > .claude/rules/my-rule.md << 'EOF'
+---
+globs: "src/api/**/*"
+description: "API 层特有规则"
+---
+## API 修改规则
+- 所有 API 变更必须向后兼容
+- 新增 endpoint 必须有对应的 OpenAPI spec 更新
+EOF
+```
+
+### 调整 Hook 灵敏度
+
+编辑 `.claude/hooks/streak-breaker.sh`：
+```bash
+WARN_THRESHOLD=3    # Warning after N edits to same file
+STOP_THRESHOLD=5    # Hard block after N edits to same file
+```
+
+### 添加新的子代理
+
+```bash
+cat > .claude/agents/my-agent.md << 'EOF'
+---
+name: my-agent
+description: "描述这个子代理做什么"
+model: sonnet
+tools: Read, Grep, Glob
+---
+你是 [角色描述]。你的职责是...
+EOF
+```
+
+## FAQ
+
+**Q: Rules 和 CLAUDE.md 有什么区别？**  
+A: CLAUDE.md 在对话开始时读取一次。Rules 是按文件路径匹配自动注入的——当 Claude 操作匹配 glob 的文件时，对应规则会自动出现在它的上下文中。Rules 更可靠，因为它们不依赖 Claude "记得去看"。
+
+**Q: Hooks 会影响性能吗？**  
+A: 几乎不会。它们是轻量的 shell 脚本，执行时间通常 <100ms。
+
+**Q: 可以把 .claude/ 提交到 git 吗？**  
+A: 强烈建议提交。这样团队成员都能共享同一套纪律。注意 `.claude/settings.json` 中的 hooks 路径是相对路径，团队成员不需要额外配置。
+
+**Q: 和 devpace 等第三方工具冲突吗？**  
+A: 不冲突。本框架是纯文件级别的，不依赖任何第三方工具。可以和 devpace、Claude MPM 等工具并行使用。
+
+## License
+
+MIT — 自由使用、修改、分发。

package/bin/cli.sh

@@ -0,0 +1,96 @@
+#!/usr/bin/env bash
+# cc-discipline CLI entry point
+# Resolves symlinks (npm bin creates symlinks) to find the real package directory
+
+set -e
+
+# Resolve the real path of this script (works through npm symlinks)
+SOURCE="${BASH_SOURCE[0]}"
+while [ -L "$SOURCE" ]; do
+    DIR="$(cd "$(dirname "$SOURCE")" && pwd)"
+    SOURCE="$(readlink "$SOURCE")"
+    # If SOURCE is relative, resolve it relative to DIR
+    [[ "$SOURCE" != /* ]] && SOURCE="$DIR/$SOURCE"
+done
+BIN_DIR="$(cd "$(dirname "$SOURCE")" && pwd)"
+PKG_DIR="$(cd "$BIN_DIR/.." && pwd)"
+
+export CC_DISCIPLINE_PKG_DIR="$PKG_DIR"
+
+# ─── Version ───
+VERSION=$(node -p "require('$PKG_DIR/package.json').version" 2>/dev/null || echo "unknown")
+
+# ─── Route subcommands ───
+COMMAND="${1:-init}"
+
+case "$COMMAND" in
+    init)
+        shift 2>/dev/null || true
+        bash "$PKG_DIR/init.sh" "$@"
+        ;;
+    upgrade)
+        shift
+        bash "$PKG_DIR/init.sh" --auto "$@"
+        ;;
+    status)
+        bash "$PKG_DIR/lib/status.sh"
+        ;;
+    doctor)
+        bash "$PKG_DIR/lib/doctor.sh"
+        ;;
+    add-stack)
+        shift
+        if [ -z "$1" ]; then
+            echo "Usage: cc-discipline add-stack <numbers>"
+            echo "  e.g.: cc-discipline add-stack 3 4"
+            exit 1
+        fi
+        bash "$PKG_DIR/init.sh" --stack "$*" --no-global
+        ;;
+    remove-stack)
+        shift
+        bash "$PKG_DIR/lib/stack-remove.sh" "$@"
+        ;;
+    -v|--version|version)
+        echo "cc-discipline v${VERSION}"
+        ;;
+    -h|--help|help)
+        cat <<EOF
+cc-discipline v${VERSION} — Discipline framework for Claude Code
+
+Usage: cc-discipline <command> [options]
+
+Commands:
+  init [options]        Install discipline into current project (default)
+  upgrade               Upgrade rules/hooks (shortcut for init --auto)
+  add-stack <numbers>   Add stack rules (e.g., add-stack 3 4)
+  remove-stack <numbers> Remove stack rules
+  status                Show installed version, stacks, and hooks
+  doctor                Check installation integrity
+  version               Show version
+
+Init options:
+  --auto                Non-interactive with defaults
+  --stack <choices>     Stack selection: 1-7, space-separated
+  --name <name>         Project name (default: directory name)
+  --global              Install global rules to ~/.claude/CLAUDE.md
+  --no-global           Skip global rules install
+
+Stacks:
+  1=RTL  2=Embedded  3=Python  4=JS/TS  5=Mobile  6=Fullstack  7=General
+
+Examples:
+  npx cc-discipline                           # Interactive setup
+  npx cc-discipline init --auto               # Non-interactive defaults
+  npx cc-discipline init --auto --stack "3 4"  # Python + JS/TS
+  npx cc-discipline upgrade                   # Upgrade to latest
+  npx cc-discipline status                    # Check what's installed
+  npx cc-discipline doctor                    # Diagnose issues
+EOF
+        ;;
+    *)
+        echo "Unknown command: $COMMAND"
+        echo "Run 'cc-discipline --help' for usage"
+        exit 1
+        ;;
+esac

package/global/CLAUDE.md

@@ -0,0 +1,43 @@
+# Global Discipline — applies to all projects
+
+> This file is placed at ~/.claude/CLAUDE.md and applies to all projects.
+> Project-specific rules go in each project's CLAUDE.md and .claude/rules/.
+
+---
+
+## Mindset
+
+You are an **engineer**, not a **code generator**.
+An engineer's core competency is: understand the problem → analyze approaches → weigh trade-offs → execute precisely.
+Don't skip the first three steps and jump straight to the fourth.
+
+---
+
+## Universal Principles
+
+1. **Understand before acting** — If unsure, ask. Don't guess.
+2. **Minimal changes** — Do what is asked. Don't do what isn't asked.
+3. **One thing at a time** — Don't mix unrelated changes in a single modification.
+4. **Explain your reasoning** — Especially when making trade-off judgments.
+5. **Admit uncertainty** — "I'm not sure because..." is 100x better than a confident wrong answer.
+
+<!-- Anti-pattern checks moved to .claude/rules/00-core-principles.md and 04-no-mole-whacking.md,
+     project-level rules are auto-injected, no need to repeat here. -->
+
+---
+
+## Collaboration with Humans
+
+- When human says "stop", stop immediately. Don't say "let me try one more thing".
+- When human corrects you, first understand why you were wrong. Don't just change to what human said and move on.
+- When unsure of human's intent, confirm before acting.
+- Provide options for human to decide, rather than making decisions for them.
+
+---
+
+## Context Hygiene
+
+- Use subagents for research. Don't read large volumes of files in the main conversation.
+- Update docs/progress.md after completing each milestone.
+- Proactively warn when context is nearly full. Don't wait for auto-compact.
+- First thing after compact: read `docs/progress.md` and `docs/debug-log.md`.