@piex-dev/init 0.1.0

package/README.md

@@ -0,0 +1,56 @@
+# init
+
+引导式 `AGENTS.md` 生成 — 纯 prompt 包，安装后提供 `/init`。
+
+## 深度解读
+
+- 博客：https://piex.dev/zh/blogs/init/
+- 源稿：[`docs/notes/init.md`](../../docs/notes/init.md)
+
+## 功能
+
+- **/init 命令**：扫描仓库高信号源，创建或就地改进项目根 `AGENTS.md`
+- **可选参数**：`/init focus on testing` 等，约束生成重点
+- **零运行时**：无 extension、无工具覆盖，只分发 `prompts/init.md`
+
+```
+init/
+├── package.json          # pi.prompts → ./prompts
+├── README.md
+└── prompts/
+    └── init.md           # → /init
+```
+
+## 安装
+
+```bash
+pi install npm:@piex-dev/init
+# 本地开发
+pi install -l packages/init
+```
+
+## 用法
+
+```bash
+# 交互
+/init
+/init focus on monorepo packages and test commands
+
+# 非交互
+pi -p "/init" --no-session
+```
+
+写完后执行 `/reload`（或新开 session），pi 才会把新的 `AGENTS.md` 注入上下文。
+
+## 与 opencode / omp 的差异
+
+| 能力 | opencode | oh-my-pi | @piex-dev/init |
+|------|----------|----------|----------------|
+| `/init` 生成 AGENTS.md | 内置 slash + prompt | 无 | pi prompt 包 |
+| 多格式 context 发现 | AGENTS / CLAUDE 等 | 多 provider 加载 | 依赖 pi 原生加载 |
+| 实现形态 | 内核 command 模板 | — | `prompts/init.md` only |
+| 运行时依赖 | 内置 | — | 无 |
+
+## 来源
+
+Prompt 结构借鉴 [OpenCode](https://github.com/anomalyco/opencode) 内置 `/init`（`initialize.txt`），改写为 pi 语境（`.pi/settings.json`、`/reload`、不提 `opencode.json`）。oh-my-pi 强化的是 context **加载**，不生成规则文件。

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@piex-dev/init",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Guided AGENTS.md setup for pi — /init prompt template that scans the repo and creates or improves project agent rules",
+  "license": "MIT",
+  "author": "debugtalk",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/piex-dev/piex.git",
+    "directory": "packages/init"
+  },
+  "keywords": [
+    "pi",
+    "pi-package",
+    "pi-prompt",
+    "init",
+    "agents-md",
+    "AGENTS.md"
+  ],
+  "pi": {
+    "prompts": ["./prompts"]
+  },
+  "files": [
+    "prompts",
+    "README.md"
+  ]
+}

package/prompts/init.md

@@ -0,0 +1,71 @@
+---
+description: Guided AGENTS.md setup — scan the repo and create or improve project agent rules
+argument-hint: "[focus or constraints]"
+---
+Create or update `AGENTS.md` for this repository (project root / current working directory).
+
+The goal is a compact instruction file that helps future pi sessions avoid mistakes and ramp up quickly. Every line should answer: "Would an agent likely miss this without help?" If not, leave it out.
+
+User-provided focus or constraints (honor these):
+$ARGUMENTS
+
+## How to investigate
+
+Read the highest-value sources first:
+- `README*`, root manifests, workspace config, lockfiles
+- build, test, lint, formatter, typecheck, and codegen config
+- CI workflows and pre-commit / task runner config
+- existing instruction files (`AGENTS.md`, `CLAUDE.md`, `.cursor/rules/`, `.cursorrules`, `.github/copilot-instructions.md`, `.omp/AGENTS.md`)
+- repo-local pi config such as `.pi/settings.json` and installed pi packages
+
+If architecture is still unclear after reading config and docs, inspect a small number of representative code files to find the real entrypoints, package boundaries, and execution flow. Prefer reading the files that explain how the system is wired together over random leaf files.
+
+Prefer executable sources of truth over prose. If docs conflict with config or scripts, trust the executable source and only keep what you can verify.
+
+## What to extract
+
+Look for the highest-signal facts for an agent working in this repo:
+- exact developer commands, especially non-obvious ones
+- how to run a single test, a single package, or a focused verification step
+- required command order when it matters, such as `lint -> typecheck -> test`
+- monorepo or multi-package boundaries, ownership of major directories, and the real app/library entrypoints
+- framework or toolchain quirks: generated code, migrations, codegen, build artifacts, special env loading, dev servers, infra deploy flow
+- repo-specific style or workflow conventions that differ from defaults
+- testing quirks: fixtures, integration test prerequisites, snapshot workflows, required services, flaky or expensive suites
+- important constraints from existing instruction files worth preserving
+
+Good `AGENTS.md` content is usually hard-earned context that took reading multiple files to infer.
+
+## Questions
+
+Only ask the user questions if the repo cannot answer something important. Prefer one short batch at most.
+
+Good questions:
+- undocumented team conventions
+- branch / PR / release expectations
+- missing setup or test prerequisites that are known but not written down
+
+Do not ask about anything the repo already makes clear.
+
+## Writing rules
+
+Include only high-signal, repo-specific guidance such as:
+- exact commands and shortcuts the agent would otherwise guess wrong
+- architecture notes that are not obvious from filenames
+- conventions that differ from language or framework defaults
+- setup requirements, environment quirks, and operational gotchas
+- references to existing instruction sources that matter
+
+Exclude:
+- generic software advice
+- long tutorials or exhaustive file trees
+- obvious language conventions
+- speculative claims or anything you could not verify
+
+When in doubt, omit.
+
+Prefer short sections and bullets. If the repo is simple, keep the file simple. If the repo is large, summarize the few structural facts that actually change how an agent should work.
+
+If `AGENTS.md` already exists, improve it in place rather than rewriting blindly. Preserve verified useful guidance, delete fluff or stale claims, and reconcile it with the current codebase.
+
+Write the file with the `write` or `edit` tool. After writing, tell the user to run `/reload` (or start a new session) so pi picks up the updated context file.