diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json new file mode 100644 index 0000000..7927780 --- /dev/null +++ b/.claude-plugin/marketplace.json @@ -0,0 +1,20 @@ +{ + "name": "praxis", + "description": "Simgreek team's coding agent SOP marketplace.", + "owner": { + "name": "Simgreek", + "url": "https://git.simgreek.com/simgreek" + }, + "plugins": [ + { + "name": "praxis", + "description": "Simgreek team's AI coding agent rulebook: SOP for Node.js projects, git hygiene, debugging, verification.", + "version": "0.1.0", + "source": "./", + "author": { + "name": "Simgreek", + "url": "https://git.simgreek.com/simgreek" + } + } + ] +} diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json new file mode 100644 index 0000000..68dafa9 --- /dev/null +++ b/.claude-plugin/plugin.json @@ -0,0 +1,20 @@ +{ + "name": "praxis", + "description": "Simgreek team's AI coding agent rulebook: SOP for Node.js projects, git hygiene, debugging, verification — practice over theory.", + "version": "0.1.0", + "author": { + "name": "Simgreek", + "url": "https://git.simgreek.com/simgreek" + }, + "homepage": "https://git.simgreek.com/simgreek/praxis", + "repository": "https://git.simgreek.com/simgreek/praxis", + "license": "Internal", + "keywords": [ + "skills", + "sop", + "nodejs", + "git", + "debugging", + "team-rules" + ] +} diff --git a/AGENTS.md b/AGENTS.md index fc19bb4..b025891 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,10 +1,13 @@ -# AGENTS.md — team-guide +# AGENTS.md — praxis -Working agreements for our 1–3 person AI-assisted development team. +Working agreements for the Simgreek team's AI-assisted development. This is the canonical spec for AI coding agents (Claude Code, Codex, and any other `AGENTS.md`-aware tool). Claude Code reads this via -`CLAUDE.md`'s `@AGENTS.md` import, so there's exactly one source of -truth. +`CLAUDE.md`'s `@AGENTS.md` import. + +If installed as a Claude Code plugin (`/plugin install praxis`), the +`SessionStart` hook also injects the `using-praxis` skill into the +session — see [`skills/using-praxis/SKILL.md`](skills/using-praxis/SKILL.md). > Human-facing entry point: [`README.md`](README.md) (Chinese, > condensed). When humans want the full ruleset, they read this file. @@ -15,14 +18,15 @@ Before starting non-trivial work in any team project, an agent should: 1. **Read this `AGENTS.md`** — general rules (vibe coding, Git, code style, planning, handoff). -2. **Scan [`library/README.md`](library/README.md)** — focused specs - for narrower topics. Read the entries that match the current task. +2. **Scan [`skills/`](skills/)** — narrower SOPs. The + [`using-praxis` skill](skills/using-praxis/SKILL.md) lists the full + catalog and tells you when to invoke each. 3. **Read the project's own `AGENTS.md`** — project-specific stuff (how to run it, architecture, project-only don'ts). Project AGENTS.md - files do **not** repeat team-guide content; they reference it. + files do **not** repeat praxis content; they reference it. -In short: team-guide is the external rulebook every project's agent -reads at task start. Project AGENTS.md files stay small and specific. +In short: praxis is the external rulebook every project's agent reads +at task start. Project AGENTS.md files stay small and specific. ## Project @@ -38,14 +42,14 @@ read the change and would have written the same." when the rule isn't self-evident. - No emoji. - Keep AGENTS.md under ~600 lines. Past that, split a section into - `library/`. + `skills/`. - Examples beat prose. A 3-line code block beats a paragraph. ## Language policy - **Human-facing**: Chinese — `README.md` only. - **AI-facing**: English — this file, `CLAUDE.md`, anything under - `library/`. + `skills/`. - **Git metadata**: English — commit messages, PR titles, branch names, tag annotations. AI tools and search work better on English. @@ -194,7 +198,7 @@ Past 100 lines → split. Skeleton: ```markdown # AGENTS.md — -> Reference: team-guide for cross-project rules. This file holds only +> Reference: praxis for cross-project rules. This file holds only > what's specific to this project. ## Project @@ -393,7 +397,7 @@ Cut a tag: ```bash git checkout main && git pull --ff-only -git tag -a -m "team-guide : " +git tag -a -m "praxis : " git push origin ``` @@ -408,7 +412,7 @@ git log --oneline .. When to cut a tag: - Rules changed in a way that affects how AI should behave on tasks. -- A `library/` entry was added, removed, or restructured. +- A skill was added, removed, or restructured. When **not** to cut a tag: @@ -517,25 +521,38 @@ Shorter than this is fine — drop sections that don't apply. --- -## 5. Team library +## 5. Skills catalog -Narrower specs that don't fit cleanly in this file live under -[`library/`](library/). Catalog: [`library/README.md`](library/README.md). +Narrower SOPs live under [`skills/`](skills/). Each `SKILL.md` has a +YAML `description` frontmatter telling the AI **when to invoke it**. +The `using-praxis` skill is the bootstrap — read it first; it lists the +catalog with full triggering criteria. -When an agent picks up a task, it should scan the catalog after reading -this file and read entries that match. Each entry leads with a "When -to read this" section so the decision is fast. +Current skills: -Current entries: - -- [`library/git-upload/`](library/git-upload/SPEC.md) — what to commit, +- [`skills/using-praxis/`](skills/using-praxis/SKILL.md) — bootstrap, + iron-law / red-flags / catalog. Loaded automatically by the + `SessionStart` hook when the praxis plugin is installed. +- [`skills/git-upload/`](skills/git-upload/SKILL.md) — what to commit, what not to, how to recover from leaked secrets. -- [`library/nodejs-project/`](library/nodejs-project/SPEC.md) — task - execution SOP for Node.js / Next.js projects (entry → frame → sync → - edit → encoding → verify → commit → push → release). +- [`skills/nodejs-project/`](skills/nodejs-project/SKILL.md) — task + execution SOP for Node.js / Next.js projects (8 phases, includes + encoding checks). +- [`skills/debugging/`](skills/debugging/SKILL.md) — root-cause + investigation before any fix; 4-phase process. +- [`skills/verification/`](skills/verification/SKILL.md) — evidence + before completion claims. -Promotion criteria, layout, and adding rules: see -[`library/README.md`](library/README.md). +A skill graduates from "this seems like a good idea" to a real entry +when **all three** hold: + +1. Done the same way 3+ times. +2. Steps stable enough to write down. +3. Someone else would do it the same way given the spec. + +Skill design rules: one skill, one job; verb-phrase name; description +field tells the model **when to invoke**, not what the skill does; +under ~300 lines. --- diff --git a/README.md b/README.md index 948b3fc..16d1411 100644 --- a/README.md +++ b/README.md @@ -1,29 +1,43 @@ -# team-guide +# praxis -我们小团队的 AI 协作开发约定。**给 AI 看的**——每个项目里 AI 开干前先读这里。 +Simgreek 团队的 AI 协作开发约定。**给 AI 看的**——每个项目里 AI 开干前先读这里。 -完整规则在 [`AGENTS.md`](AGENTS.md)(英文)。这份 README 只是入口说明。 +完整规则在 [`AGENTS.md`](AGENTS.md)(英文)。skill 库在 [`skills/`](skills/)。这份 README 是给人的入口说明。 -## 这个仓库怎么用 +## praxis 是什么 -AI 进任何团队项目前的读取顺序: +源自希腊语 *praxis*(实践)。Simgreek 团队的"踩过坑就写下来"的总和,给 AI agent 用。 -1. [`AGENTS.md`](AGENTS.md) —— 团队通用规则 -2. [`library/README.md`](library/README.md) —— 按当前任务挑相关条目读 -3. 项目自己的 `AGENTS.md` —— 只放项目特定的东西 +两种用法: -项目自己的 `AGENTS.md` **不重复** team-guide 里的内容,引用就行。 +- **作为 Claude Code 插件**(推荐)—— `/plugin install praxis` 之后,session 一开 hook 就把 `using-praxis` 强制注入 context,AI 行为受铁律约束。 +- **作为外部规范**—— 不装插件也能用:AI 进项目前读 `AGENTS.md` + 扫 `skills/`,靠自觉调用。Codex / Cursor 走这条。 -## 开新项目时丢给 AI 的提示词 +## 安装(Claude Code 插件) -复制下面这段,发给 Claude Code / Codex 当首句话——它会自己读完规则、问你必要信息、把项目脚手架(`AGENTS.md` / `CLAUDE.md` / `.gitignore` / `.gitattributes` / `.env.example`)建好,然后等你确认再开干。 +``` +/plugin marketplace add https://git.simgreek.com/simgreek/praxis +/plugin install praxis +``` + +装完之后每次开新 session,praxis 的 `SessionStart` hook 会把 `using-praxis` 内容直接灌进 system context——AI 在做任何事之前都会读到铁律和 red flags。 + +升级:`/plugin update praxis` + +卸载:`/plugin uninstall praxis` + +## 不装插件怎么用 + +把这段提示词丢给 AI 当首句话: ```text -请按以下顺序为本项目做初始化: +请按以下顺序为本项目做初始化或推进任务: -1. 拉取并阅读 https://git.simgreek.com/simgreek/team-guide 的最新内容(至少读 AGENTS.md 和 library/nodejs-project/SPEC.md,如果是 Node 项目)。 +1. 拉取并阅读 https://git.simgreek.com/simgreek/praxis 的最新内容 + (至少读 AGENTS.md 和 skills/using-praxis/SKILL.md,再扫 skills/ + 下的其他 SKILL.md,匹配当前任务的读完)。 -2. 读完后,问我以下信息(一次性问完,不要一条一条挤牙膏): +2. 读完后,如果是新项目初始化,问我以下信息(一次性问完): - 项目名 / 一句话定位 - 技术栈(Node 版本、是否 Next.js / Express / 其他) - 远端仓库地址(gitee / git.simgreek.com / 其他) @@ -31,37 +45,50 @@ AI 进任何团队项目前的读取顺序: - 是否产品项目(要发分发渠道);是的话,分发渠道是什么 - 需要哪些环境变量(只要变量名,不要值) -3. 拿到回答后,按 team-guide 的规范: - - git init(如果还没)+ 配 .gitignore(含 node_modules / .env* / 构建产物 / .claude/settings.local.json 等) - - 落 .gitattributes(强制 LF,.bat/.cmd 用 CRLF,二进制文件标 binary) +3. 拿到回答后,按 praxis 的规范: + - git init(如果还没)+ 配 .gitignore(含 node_modules / .env* + / 构建产物 / .claude/settings.local.json 等) + - 落 .gitattributes(强制 LF,.bat/.cmd 用 CRLF,二进制标 binary) - 写 .env.example(仅变量名) - - 写项目根 AGENTS.md,遵循 team-guide §2 的骨架,引用 team-guide 而不是复制规则 + - 写项目根 AGENTS.md,遵循 praxis AGENTS.md §2 的骨架,引用 praxis + 而不是复制规则 - CLAUDE.md 写一行:@AGENTS.md - 写 README.md(中文,给人看,三段:是什么 / 怎么跑 / 怎么配 .env) -4. 全部建好后,列出新增 / 修改的文件,告诉我下一步该 commit 哪些,等我确认再 git add + commit。第一个 commit 不要直接 push。 +4. 全部建好后列出改动,等我确认再 commit。第一个 commit 不直接 push。 -5. 整个过程严格遵守 team-guide 的「AI 必须停下问人」规则——任务模糊、范围敏感、远端冲突、--force、上传分发渠道,这些必须停下来确认。 +5. 整个过程严格遵守 praxis 的「AI 必须停下问人」规则——任务模糊、 + 范围敏感、远端冲突、--force、上传分发渠道,这些必须停下来确认。 ``` -老项目要补规范(已有代码、还没接入 team-guide),把第 3 步换成"补齐缺失的文件,不要覆盖现有的内容;冲突先列出来问我"。 +老项目补规范,把第 3 步换成"补齐缺失的文件,不要覆盖现有的内容;冲突先列出来问我"。 ## 语言策略 - **本 README 中文**——给人读的入口 -- **AGENTS.md / CLAUDE.md / library/ 全英文**——给 AI 读 +- **AGENTS.md / CLAUDE.md / skills/ 全英文**——给 AI 读 - **commit、PR 标题、分支名、tag 注释全英文**——AI 工具和搜索吃英文 metadata 更准 ## 目录 ``` -team-guide/ -├── README.md ← 中文入口(你正在看) -├── AGENTS.md ← 全部团队规则(英文) -├── CLAUDE.md ← 一行 @AGENTS.md import -└── library/ ← 窄主题专项规范 - ├── README.md ← catalog - └── /SPEC.md +praxis/ +├── README.md ← 中文入口(你正在看) +├── AGENTS.md ← 全部团队规则(英文) +├── CLAUDE.md ← 一行 @AGENTS.md import +├── .claude-plugin/ ← Claude Code 插件元数据 +│ ├── marketplace.json +│ └── plugin.json +├── hooks/ ← SessionStart hook,强制注入 using-praxis +│ ├── hooks.json +│ ├── session-start +│ └── run-hook.cmd +└── skills/ ← AI 行为约束 + ├── using-praxis/ ← bootstrap:铁律 / red flags / 目录 + ├── git-upload/ ← 该传 / 不该传 / 泄密恢复 + ├── nodejs-project/ ← Node 项目 8 阶段执行 SOP(含编码检查) + ├── debugging/ ← 4 阶段根因调查 + └── verification/ ← 完成前必须有证据 ``` ## 版本管理 @@ -70,9 +97,9 @@ team-guide/ 具体规则见 [`AGENTS.md`](AGENTS.md) §3 Git workflow。项目仓库自己用各自的 tag 方案(通常 semver `vX.Y.Z`),写在项目的 `AGENTS.md` 里。 -## Library 怎么扩 +## Skill 怎么扩 -碰到跨项目的具体话题、塞进 AGENTS.md 会拖肿(比如"PII 处理"、"eval 报告格式"),就在 `library//` 下写 `SPEC.md`。 +碰到跨项目的具体话题、塞进 AGENTS.md 会拖肿(比如"PII 处理"、"eval 报告格式"),就在 `skills//` 下写 `SKILL.md`。 收录标准(同时满足): @@ -80,12 +107,12 @@ team-guide/ 2. 比 AGENTS.md 通用规则窄 3. 步骤稳定到能写下来 -加一条要同时更新 [`library/README.md`](library/README.md) 的 catalog 表。 +新加的 skill 要同时更新 AGENTS.md §5 Skills catalog 和 `using-praxis/SKILL.md` 的目录表。 ## 远端 -[git.simgreek.com/simgreek/team-guide](https://git.simgreek.com/simgreek/team-guide) · -[tags 列表](https://git.simgreek.com/simgreek/team-guide/tags) +[git.simgreek.com/simgreek/praxis](https://git.simgreek.com/simgreek/praxis) · +[tags 列表](https://git.simgreek.com/simgreek/praxis/tags) ## License diff --git a/hooks/hooks.json b/hooks/hooks.json new file mode 100644 index 0000000..79d8cee --- /dev/null +++ b/hooks/hooks.json @@ -0,0 +1,16 @@ +{ + "hooks": { + "SessionStart": [ + { + "matcher": "startup|clear|compact", + "hooks": [ + { + "type": "command", + "command": "\"${CLAUDE_PLUGIN_ROOT}/hooks/run-hook.cmd\" session-start", + "async": false + } + ] + } + ] + } +} diff --git a/hooks/run-hook.cmd b/hooks/run-hook.cmd new file mode 100644 index 0000000..abbcbd3 --- /dev/null +++ b/hooks/run-hook.cmd @@ -0,0 +1,47 @@ +@echo off +REM Windows shim that invokes a bash hook script. Claude Code passes the +REM hook name as the first argument; we forward stdin and arguments to the +REM matching POSIX script under hooks/. + +setlocal + +REM Find git's bash. Required because Claude Code on Windows installations +REM does not always have a bash on PATH. +set "BASH_EXE=" +for %%P in ( + "%ProgramFiles%\Git\bin\bash.exe" + "%ProgramFiles(x86)%\Git\bin\bash.exe" + "%LocalAppData%\Programs\Git\bin\bash.exe" +) do ( + if exist "%%~P" ( + set "BASH_EXE=%%~P" + goto :found + ) +) + +REM Fallback: hope bash is on PATH. +where bash >nul 2>&1 +if %ERRORLEVEL%==0 ( + set "BASH_EXE=bash" +) + +:found +if not defined BASH_EXE ( + echo praxis hook: bash not found, skipping > nul + exit /b 0 +) + +set "HOOK_NAME=%~1" +if "%HOOK_NAME%"=="" ( + echo praxis hook: no hook name provided 1>&2 + exit /b 1 +) + +set "HOOK_SCRIPT=%~dp0%HOOK_NAME%" +if not exist "%HOOK_SCRIPT%" ( + echo praxis hook: %HOOK_NAME% script not found 1>&2 + exit /b 1 +) + +"%BASH_EXE%" "%HOOK_SCRIPT%" +exit /b %ERRORLEVEL% diff --git a/hooks/session-start b/hooks/session-start new file mode 100755 index 0000000..ed8239c --- /dev/null +++ b/hooks/session-start @@ -0,0 +1,37 @@ +#!/usr/bin/env bash +# SessionStart hook for praxis plugin. +# Loads using-praxis SKILL.md and injects it into the session context so the +# agent reads the iron-law / red-flags content before its first response. + +set -euo pipefail + +SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)" +PLUGIN_ROOT="$(cd "${SCRIPT_DIR}/.." && pwd)" + +using_praxis_content=$(cat "${PLUGIN_ROOT}/skills/using-praxis/SKILL.md" 2>&1 || echo "Error reading using-praxis skill") + +# Escape string for JSON embedding using bash parameter substitution. +escape_for_json() { + local s="$1" + s="${s//\\/\\\\}" + s="${s//\"/\\\"}" + s="${s//$'\n'/\\n}" + s="${s//$'\r'/\\r}" + s="${s//$'\t'/\\t}" + printf '%s' "$s" +} + +using_praxis_escaped=$(escape_for_json "$using_praxis_content") +session_context="\nYou are working in a Simgreek project that has the praxis plugin installed.\n\n**Below is the full content of your 'praxis:using-praxis' skill — your introduction to using praxis skills. For all other skills, use the 'Skill' tool:**\n\n${using_praxis_escaped}\n" + +# Output context injection. Claude Code expects hookSpecificOutput.additionalContext. +# Cursor expects additional_context (snake_case). Copilot CLI expects additionalContext top-level. +if [ -n "${CURSOR_PLUGIN_ROOT:-}" ]; then + printf '{\n "additional_context": "%s"\n}\n' "$session_context" +elif [ -n "${CLAUDE_PLUGIN_ROOT:-}" ] && [ -z "${COPILOT_CLI:-}" ]; then + printf '{\n "hookSpecificOutput": {\n "hookEventName": "SessionStart",\n "additionalContext": "%s"\n }\n}\n' "$session_context" +else + printf '{\n "additionalContext": "%s"\n}\n' "$session_context" +fi + +exit 0 diff --git a/library/README.md b/library/README.md deleted file mode 100644 index b3573fd..0000000 --- a/library/README.md +++ /dev/null @@ -1,51 +0,0 @@ -# Team library - -A small catalog of focused specs and reusable assets. Read the entries -that match the current task; ignore the rest. - -This directory is **not** the team's general working agreements — those -live in [`../AGENTS.md`](../AGENTS.md). The library is for narrower, -deeper specs that would bloat AGENTS.md if inlined. - -## How to use this - -When starting a non-trivial task: - -1. Read [`../AGENTS.md`](../AGENTS.md) (general rules). -2. Scan this catalog. If an entry matches your task, read its `SPEC.md`. -3. If nothing matches, proceed. - -## Catalog - -| Entry | Read it when… | -| ------------------------------------------- | -------------------------------------------------------------- | -| [`git-upload/`](git-upload/SPEC.md) | Pushing code to a remote, especially first push or new files | -| [`nodejs-project/`](nodejs-project/SPEC.md) | Working in any Node.js / Next.js project — task execution SOP | - -(More entries will be added as the team encounters recurring questions -worth standardizing.) - -## Adding to the library - -Promote a topic to a library entry when **all** are true: - -1. The topic has bitten us at least twice. -2. It's narrower than AGENTS.md general rules and would make AGENTS.md - bloated to inline. -3. Steps are stable enough to write down. - -Layout for a new entry: - -``` -library// -└── SPEC.md ← English, the actual spec -``` - -`SPEC.md` follows the same editing rules as AGENTS.md (one rule per -bullet, no emoji, examples beat prose, ~300 lines max). Lead with a -**When to read this** section so agents can decide quickly whether the -entry applies. - -If a future entry needs scripts or skill packages, add them next to -`SPEC.md`. The catalog table above gets a one-line "read it when…" for -each new entry. diff --git a/skills/debugging/SKILL.md b/skills/debugging/SKILL.md new file mode 100644 index 0000000..6ed01be --- /dev/null +++ b/skills/debugging/SKILL.md @@ -0,0 +1,202 @@ +--- +name: debugging +description: Use when encountering any bug, test failure, or unexpected behavior, before proposing a fix — requires root-cause investigation before any code change +--- + +# Debugging — root cause before fix + +## The Iron Law + +``` +NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST +``` + +Random fixes waste time and create new bugs. Quick patches mask the +real problem and the same bug shows up later in a different form. + +If you have not completed Phase 1 below, you cannot propose fixes. + +## When to invoke this skill + +Any technical issue: + +- Test failures +- Bugs in dev or production +- Unexpected behavior +- Performance problems +- Build / typecheck failures +- Integration issues + +**Especially when:** + +- Time pressure (emergencies make guessing tempting) +- "Just one quick fix" looks obvious +- You've already tried multiple fixes +- Previous fix didn't work +- You don't fully understand what broke + +**Don't skip when:** + +- Issue seems simple — simple bugs have root causes too +- You're in a hurry — systematic is faster than thrashing +- The user wants it fixed NOW — guess-and-check makes it slower + +## The four phases + +You must complete each phase before proceeding to the next. + +### Phase 1: Root cause investigation + +Before attempting any fix: + +1. **Read error messages carefully.** Don't skim past errors or + warnings. Read stack traces completely. Note line numbers, file + paths, error codes. The exact answer is often in the message. + +2. **Reproduce consistently.** Can you trigger it reliably? What are + the exact steps? Every time? If not reproducible, gather more data + — don't guess. + +3. **Check recent changes.** What changed that could cause this? + `git log --oneline -10`. New deps, config changes, environment + differences. + +4. **Multi-component systems: gather evidence at boundaries.** When + the system has layers (CI → build → signing, API → service → DB), + add diagnostic logging at each layer before proposing fixes. Run + once to see WHERE it breaks, then investigate that specific layer. + + Example layering: + + ``` + For each component boundary: + - Log what data enters + - Log what data exits + - Verify env / config propagation + - Check state at each layer + + Run once → identify failing layer → investigate that layer + ``` + +5. **Trace data flow backward.** When the error is deep in the call + stack: where does the bad value originate? What called this with + the bad value? Keep tracing up until you find the source. Fix at + the source, not at the symptom. + +### Phase 2: Pattern analysis + +1. **Find a working example.** Locate similar code in the same + codebase that works. What does it do that the broken code doesn't? + +2. **Compare against references.** If the broken code follows a + pattern (a library's example, a sister module), read the reference + completely. Don't skim. Understand it before applying it. + +3. **Identify differences.** What's different between working and + broken? List every difference, however small. Don't assume "that + can't matter" — that assumption is usually how the bug got there. + +4. **Understand dependencies.** What other components does this need? + What config / env / assumptions does it make? + +### Phase 3: Hypothesis and minimal test + +1. **Form a single hypothesis.** State it: "I think X is the root + cause because Y." Be specific. Vague hypothesis = vague fix. + +2. **Test minimally.** Make the smallest possible change to test the + hypothesis. One variable at a time. Don't bundle multiple changes + "while you're in there." + +3. **Verify before continuing.** Did it work? Yes → Phase 4. No → + form a NEW hypothesis. Don't pile fixes on top of fixes. + +4. **When you don't know, say so.** "I don't understand why X happens" + is a valid status. Don't pretend. Ask, research, or surface to the + human. + +### Phase 4: Fix and verify + +1. **Write a failing test first.** Simplest possible reproduction. + Automated if the project has a framework; one-off script otherwise. + The test must fail with the current code — that's how you know it + actually targets the bug. + +2. **Implement a single fix.** Address the root cause from Phase 1. + One change. No "while I'm here" cleanups, no bundled refactors. + +3. **Verify.** Test passes? Other tests still pass? The original + reported symptom is gone? + +4. **If the fix doesn't work:** stop. Count: how many fixes have you + tried? + - **<3**: return to Phase 1 with what you learned. + - **≥3**: stop and question the architecture (next step). Do **not** + try fix #4. + +5. **3+ fixes failed = architectural problem, not a fix problem.** + Pattern indicators: + - Each fix reveals a new shared-state / coupling issue elsewhere. + - Fixes require "massive refactoring" to land cleanly. + - Each fix creates new symptoms in different places. + + Surface to the human: "I've tried 3 approaches, each surfaces a + different downstream issue. I think the underlying pattern is wrong. + Want to discuss before I try more fixes?" + +## Red Flags — STOP and follow the process + +If you catch yourself thinking any of these, you are skipping the +process. Stop. Return to Phase 1. + +| Thought | Reality | +|---------|---------| +| "Quick fix for now, investigate later" | "Later" never comes; the bug returns | +| "Just try changing X and see if it works" | That's guess-and-check, not debugging | +| "Add multiple changes, run tests" | Can't isolate what worked | +| "Skip the test, I'll manually verify" | Manual ≠ regression-proof | +| "It's probably X, let me fix that" | "Probably" is not a hypothesis | +| "Pattern says X but I'll adapt it" | Partial pattern = bug | +| "Here are the main problems: " (without investigation) | Symptoms ≠ causes | +| Proposing fixes before tracing data flow | Always wrong | +| "One more fix attempt" (after 2+ failures) | Architectural problem | +| Each fix reveals new problem in different place | Architectural problem | + +## Common rationalizations + +| Excuse | Reality | +|--------|---------| +| "Issue is simple, no need for process" | Simple issues have root causes too. The process is fast for simple bugs. | +| "Emergency, no time for process" | Systematic debugging is **faster** than guess-and-check. | +| "Just try this first, then investigate" | First fix sets the pattern. Do it right from the start. | +| "I'll write the test after confirming the fix" | Untested fixes don't stick. Test first proves the fix. | +| "Multiple fixes at once saves time" | Can't isolate what worked. Causes new bugs. | +| "I see the problem, let me fix it" | Seeing symptoms ≠ understanding root cause. | +| "One more fix" (after 2+ failures) | Three failures = architectural problem. Don't fix again. | + +## Quick reference + +| Phase | Activity | Done when | +|-------|---------|-----------| +| 1. Root cause | Read errors, reproduce, check changes, trace data | You can describe WHAT and WHY | +| 2. Pattern | Find working example, compare, list differences | You know what to change | +| 3. Hypothesis | State theory, test minimally | Confirmed or new hypothesis | +| 4. Fix | Failing test → fix → verify | Original symptom is gone, no regressions | + +## When the process reveals "no root cause" + +If systematic investigation reveals the issue is genuinely +environmental, timing-dependent, or external: + +1. You've completed the process — that's the answer. +2. Document what you investigated. +3. Implement appropriate handling: retry, timeout, clear error + message, monitoring. + +But: 95% of "no root cause" diagnoses are incomplete investigation. +Be honest about which you're in. + +## Related skills + +- `verification` — verify the fix actually worked before claiming done +- `nodejs-project` — Phase 3 of nodejs SOP says "fail twice, invoke this skill" diff --git a/library/git-upload/SPEC.md b/skills/git-upload/SKILL.md similarity index 93% rename from library/git-upload/SPEC.md rename to skills/git-upload/SKILL.md index 9acf4a6..ed825a5 100644 --- a/library/git-upload/SPEC.md +++ b/skills/git-upload/SKILL.md @@ -1,16 +1,13 @@ +--- +name: git-upload +description: Use when pushing code to a remote, especially first push, adding a new file type the repo hasn't committed before, cleaning up .gitignore, or after suspecting a leaked secret +--- + # git-upload — what to commit, what not to -## When to read this - -- Pushing to a remote for the first time on a project. -- Adding a new file type the project hasn't committed before (data - dumps, generated artifacts, model weights, .env files, screenshots). -- About to run `git add .` or `git add -A`. -- Cleaning up a `.gitignore`. -- Suspect or confirmed a secret was committed. - -This is a focused spec, not the full Git workflow. Branch / commit / -PR / tagging rules live in [`../../AGENTS.md`](../../AGENTS.md) §3. +This is a focused spec for what belongs in version control and what +doesn't. Branch / commit message / PR / tagging rules live in praxis +AGENTS.md §3. ## The first rule @@ -262,8 +259,7 @@ A short checklist when initializing a project: - [ ] `.gitignore` covers secrets, build outputs, editor state, agent local state - [ ] No `.env` (or any `.env.*` other than `.env.example`) in the tree -- [ ] No files >5 MB in the tree (check with `find . -size +5M - -not -path "./.git/*"` or equivalent) +- [ ] No files >5 MB in the tree - [ ] `git status` shows only files you mean to commit - [ ] `git diff --cached` reads cleanly — no surprise content - [ ] Repo URL on the remote matches the one you intend; no token in diff --git a/library/nodejs-project/SPEC.md b/skills/nodejs-project/SKILL.md similarity index 84% rename from library/nodejs-project/SPEC.md rename to skills/nodejs-project/SKILL.md index 8b9c7d8..45d9d2b 100644 --- a/library/nodejs-project/SPEC.md +++ b/skills/nodejs-project/SKILL.md @@ -1,15 +1,14 @@ +--- +name: nodejs-project +description: Use in any project with a package.json — task execution SOP from project entry through release, including encoding/line-ending checks that prevent silent file corruption +--- + # nodejs-project — AI execution SOP -## When to read this - -- Working in any Node.js / Next.js project (anything with a `package.json`). -- Initializing a new Node project. -- About to commit, push, or release a Node project. - -This is the AI's task-execution sequence. Each phase is a concrete set -of commands or checks the AI runs **on its own** before declaring the -task done. The only points that pause for the human are flagged -explicitly. +This is the AI's task-execution sequence in any Node.js / Next.js +project. Each phase is a concrete set of commands or checks the AI runs +**on its own** before declaring the task done. The only points that +pause for the human are flagged explicitly. ## Phase 0 — Project entry @@ -67,12 +66,13 @@ Failure handling: - Fix the error, re-run. - **Same error twice** → stop, surface to human. Don't keep retrying. + Invoke the `debugging` skill — that's what it's for. ## Phase 4 — Encoding & line-ending checks -Run before staging any text file changes. Source code on this team is -**UTF-8 without BOM**, line endings follow the project's existing -convention (typically LF, except `.bat` / `.cmd` which need CRLF). +Run before staging any text file changes. Source code is **UTF-8 +without BOM**, line endings follow the project's existing convention +(typically LF, except `.bat` / `.cmd` which need CRLF). Detection commands: @@ -103,23 +103,18 @@ Hits → fix before commit: AI edits a Chinese-content file on a system with Windows-default encoding — symptom is "好" appearing as "濂" or similar mojibake. -Editor / tool notes for the human: +`.gitattributes` baseline (commit it once per project): -- Set editor to UTF-8 default and save without BOM. -- VSCode: status bar bottom-right shows current file's encoding; - click to "Save with Encoding → UTF-8" if needed. -- `.gitattributes` baseline (commit it once per project): +``` +* text=auto eol=lf +*.bat text eol=crlf +*.cmd text eol=crlf +*.png binary +*.jpg binary +*.zip binary +``` - ``` - * text=auto eol=lf - *.bat text eol=crlf - *.cmd text eol=crlf - *.png binary - *.jpg binary - *.zip binary - ``` - - This forces normalization on commit and prevents future drift. +This forces normalization on commit and prevents future drift. ## Phase 5 — Pre-commit verification @@ -216,20 +211,20 @@ In total, AI stops and asks the human only at: - Phase 0: missing AGENTS.md - Phase 1: vague task or scope-sensitive change - Phase 2: dirty tree or diverged history -- Phase 3: same error twice +- Phase 3: same error twice (invoke `debugging`) - Phase 4 / 5: encoding / lockfile / secret / large-file anomalies - Phase 7: push to `main`/`dev` or `--force` - Phase 8: distribution upload Everything else is self-running. -## Quick reference (for AI to scan) +## Quick reference ``` [entry] read AGENTS.md → no? stop. [frame] vague task? → spec. scope-sensitive? → confirm. [sync] git status / pull --ff-only. -[edit] npm run check / test / tsc. fail twice? stop. +[edit] npm run check / test / tsc. fail twice? invoke debugging. [encode] no BOM / LF for src / CRLF for .bat / valid UTF-8. [verify] git diff --cached → 6 questions + Node-specific 5. [commit] git add by name. : . diff --git a/skills/using-praxis/SKILL.md b/skills/using-praxis/SKILL.md new file mode 100644 index 0000000..b29615a --- /dev/null +++ b/skills/using-praxis/SKILL.md @@ -0,0 +1,117 @@ +--- +name: using-praxis +description: Use when starting any conversation in a Simgreek project — establishes how to find and use praxis skills, requiring Skill tool invocation before ANY response including clarifying questions +--- + + +If you were dispatched as a subagent to execute a specific task, skip this skill — your dispatcher already loaded praxis context. + + + +If you think there is even a 1% chance a praxis skill might apply to what you are doing, you ABSOLUTELY MUST invoke it. + +IF A SKILL APPLIES TO YOUR TASK, YOU DO NOT HAVE A CHOICE. YOU MUST USE IT. + +This is not negotiable. This is not optional. You cannot rationalize your way out of this. + + +# Using Praxis + +Praxis is the Simgreek team's coding agent rulebook — Greek for "practice." It exists because human teammates have been bitten by every shortcut you are about to take. The skills below encode those scars. + +## Instruction Priority + +Praxis skills override default agent behavior, but **the user's explicit instructions always take precedence**: + +1. **User's explicit instructions** (project AGENTS.md, CLAUDE.md, direct chat) — highest +2. **Praxis skills** — override default behavior where they conflict +3. **Default agent behavior** — lowest + +If a project's AGENTS.md says "skip the encoding check this once" and a skill says "always check encoding," follow the user. They own the project. You are a guest. + +## How to Access Skills + +**In Claude Code:** Use the `Skill` tool. When you invoke a skill, its full content is loaded — follow it directly. Never use `Read` on a skill file when `Skill` is available. + +**In Codex / Cursor / others:** Skills live as markdown files under `/skills/`. Read the relevant ones with the file-reading tool. + +# The Rule + +**Invoke relevant or requested skills BEFORE any response or action.** Even a 1% chance a skill might apply means you must check. If an invoked skill turns out to be wrong for the situation, drop it — but you have to check first. + +This includes: + +- Before answering a clarifying question +- Before exploring the codebase +- Before "just running git status" +- Before reading docs to understand the project +- Before announcing what you're going to do + +The skill check is the **first thing** that happens after you receive a message in a praxis-enabled project. Not the second. Not "after I look around real quick." First. + +## Red Flags — These Thoughts Mean STOP + +If you catch yourself thinking any of these, you are rationalizing past a skill. Stop, invoke the skill, then proceed. + +| Thought | Reality | +|---------|---------| +| "This is just a simple question" | Questions are tasks. Check for skills. | +| "I need more context first" | Skill check comes BEFORE clarifying questions. | +| "Let me explore the codebase first" | Skills tell you HOW to explore. Check first. | +| "I can just check git status / read a file quickly" | Files lack conversation context. Check for skills. | +| "Let me gather information first" | Skills tell you HOW to gather information. | +| "This doesn't need a formal skill" | If a skill exists, use it. | +| "I remember this skill" | Skills evolve. Read the current version. | +| "This is a small change" | Small changes ship the bugs. Use the skill. | +| "The skill is overkill" | Simple things become complex when skipped. | +| "I'll just do this one thing first" | "One thing first" is how skills get bypassed. | +| "This feels productive" | Undisciplined motion wastes time. Skills prevent it. | +| "The user is in a hurry" | Skipping skills makes everything slower, not faster. | +| "I know what that means" | Knowing the concept ≠ following the procedure. Invoke. | + +## The Praxis Skill Catalog + +Read the catalog before your first action in this project. Match each candidate skill against the current task. + +| Skill | When it applies | +|-------|-----------------| +| `git-upload` | Pushing to a remote, first push, adding new file types, leaked secret | +| `nodejs-project` | Any project with `package.json` — task execution SOP including encoding checks | +| `debugging` | Any bug, test failure, unexpected behavior, before proposing a fix | +| `verification` | About to claim work is complete, fixed, or passing | + +If multiple apply, use them in order: process skills (`debugging`) before implementation skills (`nodejs-project`); verification (`verification`) before declaring done. + +## Skill Priority + +When multiple skills could apply: + +1. **Process skills first** (`debugging`) — they determine HOW to approach the task +2. **Implementation skills second** (`nodejs-project`, `git-upload`) — they guide execution +3. **Verification last** (`verification`) — before declaring done + +"Fix this bug" → `debugging` first, then `nodejs-project` if Node-relevant. +"Push my changes" → `git-upload` first, then `verification` before declaring done. + +## Skill Types + +**Rigid skills** (debugging, verification): follow exactly. The discipline is the value. Don't adapt away the steps you find inconvenient. + +**Flexible skills** (nodejs-project SOP, git-upload pitfall list): adapt principles to context. The SOP is a default; deviate when the context demands and **state the deviation explicitly**. + +The skill itself tells you which type it is. + +## User Instructions + +User instructions describe **what** to do, not **how**. "Add this feature" or "fix this bug" does not mean skip the workflow. The user sets the destination; praxis sets the route. + +## What to Do Now + +Before your next action: + +1. Identify which skills in the catalog above might apply (1% threshold). +2. Invoke each one via the `Skill` tool (or read the file). +3. Follow its checklist. +4. Then proceed. + +If the task is something praxis genuinely doesn't cover (e.g., "summarize this article"), proceed without a skill — but the check itself is mandatory. diff --git a/skills/verification/SKILL.md b/skills/verification/SKILL.md new file mode 100644 index 0000000..ffc4ee0 --- /dev/null +++ b/skills/verification/SKILL.md @@ -0,0 +1,139 @@ +--- +name: verification +description: Use before claiming work is complete, fixed, or passing — requires running verification commands and reading output before making any success claim; evidence before assertions +--- + +# Verification — evidence before claims + +## The Iron Law + +``` +NO COMPLETION CLAIMS WITHOUT FRESH VERIFICATION EVIDENCE +``` + +Claiming work is complete without verification is dishonesty, not +efficiency. If you haven't run the verification command in this turn, +you cannot claim it passes. + +## The gate + +Before claiming any status or expressing satisfaction: + +1. **Identify** the command that proves the claim. +2. **Run** it (fresh and complete — not a partial check, not a + remembered previous run). +3. **Read** the full output. Check the exit code. Count failures. +4. **Verify** the output confirms the claim. + - If yes: state the claim **with the evidence**. + - If no: state the actual status with the evidence. +5. **Only then** make the claim. + +Skipping any step is lying, not verifying. + +## Common claims and what proves them + +| Claim | What proves it | What does NOT prove it | +|-------|----------------|------------------------| +| Tests pass | Test command output: 0 failures | "Should pass", a run from earlier | +| Linter clean | Linter output: 0 errors | Partial check, extrapolation | +| Build succeeds | Build command exits 0 | Linter passing, logs look good | +| Bug fixed | Test the original symptom — passes | Code changed, "assumed fixed" | +| Regression test works | Red → green: test fails before fix, passes after | Test passes once after fix | +| Sub-agent completed | VCS diff shows the changes | Sub-agent reports "success" | +| Requirements met | Line-by-line checklist | "All tests pass" | + +## Red Flags — STOP + +If you catch yourself doing any of these, you're about to make an +unverified claim. Stop, run the verification, then continue. + +- Using "should", "probably", "seems to", "I think" +- Saying "Great!", "Perfect!", "Done!" before running anything +- About to commit / push / open a PR without re-running checks in + this turn +- Trusting a sub-agent's success report without diff inspection +- Relying on partial verification (one file checked, claim covers + many) +- "Just this once" +- Tired and wanting the work over +- **Any wording implying success without evidence in this turn** + +## Rationalizations + +| Excuse | Reality | +|--------|---------| +| "Should work now" | RUN the verification | +| "I'm confident" | Confidence ≠ evidence | +| "Just this once" | No exceptions | +| "Linter passed" | Linter ≠ compiler ≠ tests | +| "Agent said success" | Verify independently | +| "I'm tired" | Exhaustion ≠ excuse | +| "Partial check is enough" | Partial proves nothing about the rest | +| "Different words, so the rule doesn't apply" | Spirit over letter | + +## Patterns + +**Tests:** + +``` +✅ Run `npm test` → output: "34 passing" → "All tests pass (34/34)." +❌ "Should pass now." / "Looks correct." +``` + +**Regression test (red-green):** + +``` +✅ Write test → run (pass) → revert fix → run (FAIL) → restore fix → run (pass) +❌ "I've added a regression test." (without red-green proof) +``` + +**Build:** + +``` +✅ Run `npm run build` → exit 0 → "Build passes." +❌ "Linter passed, build should be fine." (linter doesn't compile) +``` + +**Requirements:** + +``` +✅ Re-read the spec → check each line → report gaps or completion +❌ "Tests pass, so we're done." (tests ≠ requirements) +``` + +**Sub-agent delegation:** + +``` +✅ Sub-agent reports success → run `git diff` → confirm the changes + exist and are correct → report actual state +❌ Trust the sub-agent report +``` + +## When to apply + +Always before: + +- Any variation of "done", "complete", "fixed", "passing" +- Any expression of satisfaction about work state +- Committing, opening a PR, declaring task complete +- Moving to the next task in a multi-step plan +- Delegating verification to a sub-agent (verify their result yourself) + +The rule applies to exact phrases, paraphrases, synonyms, and any +implication of success. "Spirit over letter." + +## Why this matters + +Unverified claims: + +- Break the user's trust ("I don't believe you") +- Ship undefined functions or missing requirements +- Waste time on false completion → redirect → rework + +Honesty is a core value. The cost of running the verification command +is small. The cost of being wrong is large. + +## Bottom line + +Run the command. Read the output. **Then** claim the result. Every +time.