Compare commits
3
Commits
20260521-3
..
main
| Author | SHA1 | Date | |
|---|---|---|---|
|
|
eafd46a8ba | ||
|
|
4fa489691f | ||
|
|
ea1819f1d2 |
No files matched your search
@@ -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.2.0",
|
||||
"source": "./",
|
||||
"author": {
|
||||
"name": "Simgreek",
|
||||
"url": "https://git.simgreek.com/simgreek"
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
@@ -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.2.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"
|
||||
]
|
||||
}
|
||||
@@ -0,0 +1,38 @@
|
||||
{
|
||||
"name": "praxis",
|
||||
"version": "0.2.0",
|
||||
"description": "Simgreek team's AI coding agent rulebook: SOP for Node.js projects, git hygiene, debugging, verification.",
|
||||
"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"
|
||||
],
|
||||
"skills": "./skills/",
|
||||
"interface": {
|
||||
"displayName": "Praxis",
|
||||
"shortDescription": "Simgreek team's AI coding agent SOP",
|
||||
"longDescription": "Use Praxis to make AI coding agents follow Simgreek team conventions: project entry, task framing, git workflow, encoding checks, root-cause debugging, and verification before completion.",
|
||||
"developerName": "Simgreek",
|
||||
"category": "Coding",
|
||||
"capabilities": [
|
||||
"Interactive",
|
||||
"Read",
|
||||
"Write"
|
||||
],
|
||||
"defaultPrompt": [
|
||||
"I'm starting a new task in this project — what should I check first?",
|
||||
"Help me bootstrap this project to follow Praxis conventions."
|
||||
],
|
||||
"websiteURL": "https://git.simgreek.com/simgreek/praxis"
|
||||
}
|
||||
}
|
||||
@@ -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 — <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.
|
||||
|
||||
## Project
|
||||
@@ -393,7 +397,7 @@ Cut a tag:
|
||||
|
||||
```bash
|
||||
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>
|
||||
```
|
||||
|
||||
@@ -408,7 +412,7 @@ git log --oneline <prev-tag>..<this-tag>
|
||||
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.
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -1,29 +1,85 @@
|
||||
# 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 一开 SessionStart hook 就把 `using-praxis` 强制注入 context,AI 行为受铁律约束。
|
||||
- **作为 Codex / Codex++ 插件** —— `/plugin add <praxis-url>` 装上,Codex 把 skills/ 里的 SKILL.md 注册成可调用的 skill。Codex 没有 SessionStart hook,但 skill 的 description 会让模型按需 invoke。
|
||||
- **作为外部规范**—— 不装插件也能用:AI 进项目前读 `AGENTS.md` + 扫 `skills/`,靠提示词显式调用。Cursor / 其他工具走这条。
|
||||
|
||||
## 开新项目时丢给 AI 的提示词
|
||||
## 安装(Claude Code)
|
||||
|
||||
复制下面这段,发给 Claude Code / Codex 当首句话——它会自己读完规则、问你必要信息、把项目脚手架(`AGENTS.md` / `CLAUDE.md` / `.gitignore` / `.gitattributes` / `.env.example`)建好,然后等你确认再开干。
|
||||
simgreek 仓库要求登录访问,所以 plugin URL 里要带个人 access token。每个团队成员一次性配一下。
|
||||
|
||||
**第 1 步**:在 Gitea 生成 token
|
||||
|
||||
登录 [git.simgreek.com](https://git.simgreek.com) → 右上角头像 → Settings → Applications → 「Manage Access Tokens」 → 生成一个新 token:
|
||||
|
||||
- Token 名字:`claude-code-plugin`(或你喜欢的)
|
||||
- 权限只勾 `repository: read` 就够,越小越好
|
||||
- **生成后立刻复制保存**——离开页面就看不到了
|
||||
|
||||
**第 2 步**:在 Claude Code 装
|
||||
|
||||
把下面的 `<YOUR_USERNAME>` 和 `<YOUR_TOKEN>` 替换掉:
|
||||
|
||||
```
|
||||
/plugin marketplace add https://<YOUR_USERNAME>:<YOUR_TOKEN>@git.simgreek.com/simgreek/praxis
|
||||
/plugin install praxis
|
||||
```
|
||||
|
||||
装完之后每次开新 session,praxis 的 `SessionStart` hook 会把 `using-praxis` 内容直接灌进 system context——AI 在做任何事之前都会读到铁律和 red flags。
|
||||
|
||||
升级:`/plugin update praxis`(自动用同一个 token 拉新版本)
|
||||
|
||||
卸载:`/plugin uninstall praxis`
|
||||
|
||||
## 安装(Codex / Codex++)
|
||||
|
||||
token 准备方式与 Claude Code 一致(上面第 1 步)。
|
||||
|
||||
**在 Codex CLI 或 Codex++ 里**:
|
||||
|
||||
```
|
||||
/plugin add https://<YOUR_USERNAME>:<YOUR_TOKEN>@git.simgreek.com/simgreek/praxis
|
||||
```
|
||||
|
||||
Codex 拉取仓库后会读 `.codex-plugin/plugin.json`,把 `skills/` 下所有带 frontmatter 的 SKILL.md 注册成可调用 skill。需要时 AI 自己 invoke。
|
||||
|
||||
**和 Claude 的差别**:Codex 没有 SessionStart hook,所以 `using-praxis` 不会被强制注入。AI 进项目时,建议你**第一句话**说:
|
||||
|
||||
```
|
||||
先读 using-praxis skill,了解我们团队的 SOP 再开始。
|
||||
```
|
||||
|
||||
让 Codex 主动 invoke 一次,铁律就在 context 里了。后续任务正常用。
|
||||
|
||||
**安全提醒(两边都适用)**:
|
||||
|
||||
- token 会被工具写进本地配置——别让别人翻你电脑、别把 config 分享出去
|
||||
- token 不要提交进任何仓库
|
||||
- 共用电脑 / 临时机器装完用完,去 Gitea token 页面 revoke 掉
|
||||
- token 失效或换了,重新跑 install 命令用新 URL
|
||||
|
||||
## 不装插件怎么用
|
||||
|
||||
把这段提示词丢给 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 +87,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
|
||||
└── <topic>/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 +139,9 @@ team-guide/
|
||||
|
||||
具体规则见 [`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 +149,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
|
||||
|
||||
|
||||
@@ -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
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
@@ -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%
|
||||
Executable
+37
@@ -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
|
||||
@@ -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.
|
||||
@@ -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
|
||||
|
||||
## 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
|
||||
@@ -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. <area>: <imperative>.
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
Reference in new issue
Block a user