feat: rename to praxis, package as Claude Code plugin

Reframe team-guide as praxis (Greek for "practice"): Simgreek's coding
agent rulebook, distributed as a Claude Code plugin so SessionStart
hook can force-inject the using-praxis bootstrap.

- Add .claude-plugin/{marketplace,plugin}.json: makes this repo a
  one-plugin marketplace installable via /plugin marketplace add.
- Add hooks/{hooks.json,session-start,run-hook.cmd}: SessionStart
  hook reads using-praxis SKILL.md and injects it into context as
  hookSpecificOutput.additionalContext (Claude Code) or
  additional_context (Cursor) or additionalContext (Copilot CLI).
- Migrate library/<topic>/SPEC.md → skills/<topic>/SKILL.md with
  YAML frontmatter (name + when-to-invoke description).
- Add skills/using-praxis: bootstrap with iron law, red-flags table,
  catalog, instruction priority, sub-agent stop, Codex/Cursor fallback.
- Add skills/debugging: 4-phase root-cause investigation with
  3-fixes-failed → architectural problem rule.
- Add skills/verification: evidence-before-claims gate with
  rationalization table.
- Drop library/, references in AGENTS.md updated to skills/.
- Rename throughout: team-guide → praxis.
- README rewritten with both install paths (plugin / external spec)
  and updated bootstrap prompt.

Codex / Cursor / non-Claude users still get the spec by reading
AGENTS.md and skills/ files manually — only the auto-injection
requires Claude Code.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
This commit is contained in:
阿白叔andClaude Opus 4.7 committed 2026-05-25 18:02:48 +08:00
1 parent 161559a83d
commit ea1819f1d2
13 files changed
+739 -157

No files matched your search

+20
View File
@@ -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"
}
}
]
}
+20
View File
@@ -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"
]
}
+45 -28
View File
@@ -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, This is the canonical spec for AI coding agents (Claude Code, Codex,
and any other `AGENTS.md`-aware tool). Claude Code reads this via 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 `CLAUDE.md`'s `@AGENTS.md` import.
truth.
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, > Human-facing entry point: [`README.md`](README.md) (Chinese,
> condensed). When humans want the full ruleset, they read this file. > 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 1. **Read this `AGENTS.md`** — general rules (vibe coding, Git, code
style, planning, handoff). style, planning, handoff).
2. **Scan [`library/README.md`](library/README.md)** — focused specs 2. **Scan [`skills/`](skills/)** — narrower SOPs. The
for narrower topics. Read the entries that match the current task. [`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 3. **Read the project's own `AGENTS.md`** — project-specific stuff
(how to run it, architecture, project-only don'ts). Project AGENTS.md (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 In short: praxis is the external rulebook every project's agent reads
reads at task start. Project AGENTS.md files stay small and specific. at task start. Project AGENTS.md files stay small and specific.
## Project ## Project
@@ -38,14 +42,14 @@ read the change and would have written the same."
when the rule isn't self-evident. when the rule isn't self-evident.
- No emoji. - No emoji.
- Keep AGENTS.md under ~600 lines. Past that, split a section into - 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. - Examples beat prose. A 3-line code block beats a paragraph.
## Language policy ## Language policy
- **Human-facing**: Chinese — `README.md` only. - **Human-facing**: Chinese — `README.md` only.
- **AI-facing**: English — this file, `CLAUDE.md`, anything under - **AI-facing**: English — this file, `CLAUDE.md`, anything under
`library/`. `skills/`.
- **Git metadata**: English — commit messages, PR titles, branch - **Git metadata**: English — commit messages, PR titles, branch
names, tag annotations. AI tools and search work better on English. names, tag annotations. AI tools and search work better on English.
@@ -194,7 +198,7 @@ Past 100 lines → split. Skeleton:
```markdown ```markdown
# AGENTS.md — <project name> # AGENTS.md — <project name>
> 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. > what's specific to this project.
## Project ## Project
@@ -393,7 +397,7 @@ Cut a tag:
```bash ```bash
git checkout main && git pull --ff-only git checkout main && git pull --ff-only
git tag -a <YYYYMMDD> -m "team-guide <YYYYMMDD>: <summary>" git tag -a <YYYYMMDD> -m "praxis <YYYYMMDD>: <summary>"
git push origin <YYYYMMDD> git push origin <YYYYMMDD>
``` ```
@@ -408,7 +412,7 @@ git log --oneline <prev-tag>..<this-tag>
When to cut a tag: When to cut a tag:
- Rules changed in a way that affects how AI should behave on tasks. - 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: 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 Narrower SOPs live under [`skills/`](skills/). Each `SKILL.md` has a
[`library/`](library/). Catalog: [`library/README.md`](library/README.md). 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 Current skills:
this file and read entries that match. Each entry leads with a "When
to read this" section so the decision is fast.
Current entries: - [`skills/using-praxis/`](skills/using-praxis/SKILL.md) — bootstrap,
iron-law / red-flags / catalog. Loaded automatically by the
- [`library/git-upload/`](library/git-upload/SPEC.md) — what to commit, `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. what not to, how to recover from leaked secrets.
- [`library/nodejs-project/`](library/nodejs-project/SPEC.md) — task - [`skills/nodejs-project/`](skills/nodejs-project/SKILL.md) — task
execution SOP for Node.js / Next.js projects (entry → frame → sync → execution SOP for Node.js / Next.js projects (8 phases, includes
edit → encoding → verify → commit → push → release). 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 A skill graduates from "this seems like a good idea" to a real entry
[`library/README.md`](library/README.md). 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.
--- ---
+61 -34
View File
@@ -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 ```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 / 其他) - 技术栈(Node 版本、是否 Next.js / Express / 其他)
- 远端仓库地址(gitee / git.simgreek.com / 其他) - 远端仓库地址(gitee / git.simgreek.com / 其他)
@@ -31,37 +45,50 @@ AI 进任何团队项目前的读取顺序:
- 是否产品项目(要发分发渠道);是的话,分发渠道是什么 - 是否产品项目(要发分发渠道);是的话,分发渠道是什么
- 需要哪些环境变量(只要变量名,不要值) - 需要哪些环境变量(只要变量名,不要值)
3. 拿到回答后,按 team-guide 的规范: 3. 拿到回答后,按 praxis 的规范:
- git init(如果还没)+ 配 .gitignore(含 node_modules / .env* / 构建产物 / .claude/settings.local.json 等) - git init(如果还没)+ 配 .gitignore(含 node_modules / .env*
- 落 .gitattributes(强制 LF,.bat/.cmd 用 CRLF,二进制文件标 binary) / 构建产物 / .claude/settings.local.json 等)
- 落 .gitattributes(强制 LF,.bat/.cmd 用 CRLF,二进制标 binary)
- 写 .env.example(仅变量名) - 写 .env.example(仅变量名)
- 写项目根 AGENTS.md,遵循 team-guide §2 的骨架,引用 team-guide 而不是复制规则 - 写项目根 AGENTS.md,遵循 praxis AGENTS.md §2 的骨架,引用 praxis
而不是复制规则
- CLAUDE.md 写一行:@AGENTS.md - CLAUDE.md 写一行:@AGENTS.md
- 写 README.md(中文,给人看,三段:是什么 / 怎么跑 / 怎么配 .env) - 写 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 中文**——给人读的入口 - **本 README 中文**——给人读的入口
- **AGENTS.md / CLAUDE.md / library/ 全英文**——给 AI 读 - **AGENTS.md / CLAUDE.md / skills/ 全英文**——给 AI 读
- **commit、PR 标题、分支名、tag 注释全英文**——AI 工具和搜索吃英文 metadata 更准 - **commit、PR 标题、分支名、tag 注释全英文**——AI 工具和搜索吃英文 metadata 更准
## 目录 ## 目录
``` ```
team-guide/ praxis/
├── README.md ← 中文入口(你正在看) ├── README.md ← 中文入口(你正在看)
├── AGENTS.md ← 全部团队规则(英文) ├── AGENTS.md ← 全部团队规则(英文)
├── CLAUDE.md ← 一行 @AGENTS.md import ├── CLAUDE.md ← 一行 @AGENTS.md import
└── library/ ← 窄主题专项规范 ├── .claude-plugin/ ← Claude Code 插件元数据
├── README.md ← catalog │ ├── marketplace.json
└── <topic>/SPEC.md │ └── 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` 里。 具体规则见 [`AGENTS.md`](AGENTS.md) §3 Git workflow。项目仓库自己用各自的 tag 方案(通常 semver `vX.Y.Z`),写在项目的 `AGENTS.md` 里。
## Library 怎么扩 ## Skill 怎么扩
碰到跨项目的具体话题、塞进 AGENTS.md 会拖肿(比如"PII 处理"、"eval 报告格式"),就在 `library/<topic>/` 下写 `SPEC.md`。 碰到跨项目的具体话题、塞进 AGENTS.md 会拖肿(比如"PII 处理"、"eval 报告格式"),就在 `skills/<topic>/` 下写 `SKILL.md`。
收录标准(同时满足): 收录标准(同时满足):
@@ -80,12 +107,12 @@ team-guide/
2. 比 AGENTS.md 通用规则窄 2. 比 AGENTS.md 通用规则窄
3. 步骤稳定到能写下来 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) · [git.simgreek.com/simgreek/praxis](https://git.simgreek.com/simgreek/praxis) ·
[tags 列表](https://git.simgreek.com/simgreek/team-guide/tags) [tags 列表](https://git.simgreek.com/simgreek/praxis/tags)
## License ## License
+16
View File
@@ -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
}
]
}
]
}
}
+47
View File
@@ -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%
+37
View File
@@ -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="<EXTREMELY_IMPORTANT>\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</EXTREMELY_IMPORTANT>"
# 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
-51
View File
@@ -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/<entry-name>/
└── 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.
+202
View File
@@ -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: <list>" (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"
@@ -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 # git-upload — what to commit, what not to
## When to read this This is a focused spec for what belongs in version control and what
doesn't. Branch / commit message / PR / tagging rules live in praxis
- Pushing to a remote for the first time on a project. AGENTS.md §3.
- 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.
## The first rule ## The first rule
@@ -262,8 +259,7 @@ A short checklist when initializing a project:
- [ ] `.gitignore` covers secrets, build outputs, editor state, agent - [ ] `.gitignore` covers secrets, build outputs, editor state, agent
local state local state
- [ ] No `.env` (or any `.env.*` other than `.env.example`) in the tree - [ ] No `.env` (or any `.env.*` other than `.env.example`) in the tree
- [ ] No files >5 MB in the tree (check with `find . -size +5M - [ ] No files >5 MB in the tree
-not -path "./.git/*"` or equivalent)
- [ ] `git status` shows only files you mean to commit - [ ] `git status` shows only files you mean to commit
- [ ] `git diff --cached` reads cleanly — no surprise content - [ ] `git diff --cached` reads cleanly — no surprise content
- [ ] Repo URL on the remote matches the one you intend; no token in - [ ] Repo URL on the remote matches the one you intend; no token in
@@ -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 # nodejs-project — AI execution SOP
## When to read this 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
- Working in any Node.js / Next.js project (anything with a `package.json`). **on its own** before declaring the task done. The only points that
- Initializing a new Node project. pause for the human are flagged explicitly.
- 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.
## Phase 0 — Project entry ## Phase 0 — Project entry
@@ -67,12 +66,13 @@ Failure handling:
- Fix the error, re-run. - Fix the error, re-run.
- **Same error twice** → stop, surface to human. Don't keep retrying. - **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 ## Phase 4 — Encoding & line-ending checks
Run before staging any text file changes. Source code on this team is Run before staging any text file changes. Source code is **UTF-8
**UTF-8 without BOM**, line endings follow the project's existing without BOM**, line endings follow the project's existing convention
convention (typically LF, except `.bat` / `.cmd` which need CRLF). (typically LF, except `.bat` / `.cmd` which need CRLF).
Detection commands: Detection commands:
@@ -103,23 +103,18 @@ Hits → fix before commit:
AI edits a Chinese-content file on a system with Windows-default AI edits a Chinese-content file on a system with Windows-default
encoding — symptom is "好" appearing as "濂" or similar mojibake. 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; * text=auto eol=lf
click to "Save with Encoding → UTF-8" if needed. *.bat text eol=crlf
- `.gitattributes` baseline (commit it once per project): *.cmd text eol=crlf
*.png binary
*.jpg binary
*.zip binary
```
``` This forces normalization on commit and prevents future drift.
* 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.
## Phase 5 — Pre-commit verification ## 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 0: missing AGENTS.md
- Phase 1: vague task or scope-sensitive change - Phase 1: vague task or scope-sensitive change
- Phase 2: dirty tree or diverged history - 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 4 / 5: encoding / lockfile / secret / large-file anomalies
- Phase 7: push to `main`/`dev` or `--force` - Phase 7: push to `main`/`dev` or `--force`
- Phase 8: distribution upload - Phase 8: distribution upload
Everything else is self-running. Everything else is self-running.
## Quick reference (for AI to scan) ## Quick reference
``` ```
[entry] read AGENTS.md → no? stop. [entry] read AGENTS.md → no? stop.
[frame] vague task? → spec. scope-sensitive? → confirm. [frame] vague task? → spec. scope-sensitive? → confirm.
[sync] git status / pull --ff-only. [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. [encode] no BOM / LF for src / CRLF for .bat / valid UTF-8.
[verify] git diff --cached → 6 questions + Node-specific 5. [verify] git diff --cached → 6 questions + Node-specific 5.
[commit] git add by name. <area>: <imperative>. [commit] git add by name. <area>: <imperative>.
+117
View File
@@ -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
---
<SUBAGENT-STOP>
If you were dispatched as a subagent to execute a specific task, skip this skill — your dispatcher already loaded praxis context.
</SUBAGENT-STOP>
<EXTREMELY-IMPORTANT>
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.
</EXTREMELY-IMPORTANT>
# 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 `<plugin-root>/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.
+139
View File
@@ -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.