@elvis1513/auto-coding-skill 0.1.2 → 0.1.3

package/README.md

@@ -22,8 +22,8 @@ npm install -g git+https://github.com/elvis1513/auto-coding-skill.git
 1. Install skill into project:
 
 ```bash
-autocoding init --ai codex
-# or claude / all
+autocoding init --ai all
+# or: --ai codex / --ai claude
 ```
 
 2. Initialize docs and local scripts:
@@ -36,13 +36,13 @@ python3 .claude/skills/auto-coding-skill/scripts/ap.py --repo . install
 
 3. Fill only one file manually:
 
-- `ENGINEERING.md` frontmatter
+- `docs/ENGINEERING.md` frontmatter
 
 This frontmatter is the only manual config source (commands + deployment + docs paths).
 
 4. Start AI development by constraints:
 
-- `ENGINEERING.md`
+- `docs/ENGINEERING.md`
 - `docs/tasks/taskbook.md`
 - `docs/design/**`
 - `docs/interfaces/**`
@@ -56,12 +56,71 @@ This frontmatter is the only manual config source (commands + deployment + docs
 ## Mandatory Skill
 - Always use `auto-coding-skill` for implementation tasks.
 - Before any code change, read and obey:
-  1) ENGINEERING.md
+  1) docs/ENGINEERING.md
   2) docs/tasks/taskbook.md
 - Execute gates using `python3 scripts/autopipeline/ap.py`.
 - If required docs are missing, create/update docs first, then code.
 ```
 
+## Docs Structure and Recording Rules
+
+### 1) docs/ENGINEERING.md
+- Purpose: single source of project config + engineering gate rules.
+- How to record:
+  - Fill YAML frontmatter once (project/commands/deployment/docs fields).
+  - Keep all environment info here only (ip/username/password/service/path/health).
+  - Do not duplicate config in other docs.
+
+### 2) docs/deployment/
+- Files:
+  - `docs/deployment/deploy-runbook.md`: deployment procedure and validation checklist.
+  - `docs/deployment/deploy-records/<TASK_ID>-YYYYMMDD.md`: per-deploy execution record.
+- How to record:
+  - In deploy record, write target host, service, artifact, remote path, backup, systemctl status, smoke/regression evidence.
+
+### 3) docs/design/
+- Files:
+  - `docs/design/<TASK_ID>-<slug>.md` (from DD template).
+- Purpose:
+  - Detailed design before coding (scope,方案、时序图、ER图、接口编排、测试策略、回滚).
+- How to record:
+  - One task/subtask one DD file.
+  - Status changes: Draft -> Reviewed -> Approved.
+
+### 4) docs/interfaces/
+- Files:
+  - `docs/interfaces/api.md`: authoritative API documentation (current contract).
+  - `docs/interfaces/api-change-log.md`: append-only API changes per task.
+- How to record:
+  - API changes must update both files in the same task.
+  - `api.md` records latest endpoint contract.
+  - `api-change-log.md` appends task-level delta (新增/修改/废弃/兼容策略/影响面).
+
+### 5) docs/reviews/
+- Files:
+  - `docs/reviews/<TASK_ID>-<timestamp>.md` (from review template).
+- Purpose:
+  - Gate review evidence: static checks, code quality, test quality, risks.
+- How to record:
+  - Record commands used (lint/typecheck from docs/ENGINEERING.md frontmatter) and conclusion (Pass/Blocked).
+
+### 6) docs/tasks/
+- Files:
+  - `docs/tasks/taskbook.md`: master task ledger (all tasks appended here).
+  - `docs/tasks/summaries/<TASK_ID>.md`: end-of-task summary artifact.
+- How to record:
+  - `taskbook.md` stores task scope/acceptance/subtasks/evidence links.
+  - `summaries/<TASK_ID>.md` stores final objective result, change overview, gate evidence, risks, follow-ups.
+
+### 7) docs/testing/
+- Files:
+  - `docs/testing/regression-matrix.md`
+- Purpose:
+  - Full regression matrix; must be 0 FAIL.
+- How to record:
+  - Add/maintain rows by regression ID (R-xxx), area, steps/command, expected, status, evidence.
+  - If any FAIL exists, gate fails.
+
 ## Commands
 
 ```bash
@@ -75,9 +134,16 @@ python3 scripts/autopipeline/ap.py gen-summary T0001-1
 python3 scripts/autopipeline/ap.py commit-push T0001-1 --msg "T0001-1: <summary>" --require-matrix
 ```
 
-## Release New Version
+## Publish (NPM)
+
+1. Sync assets and basic check:
+
+```bash
+npm run sync-assets
+npm test
+```
 
-1. Bump version (cannot republish an existing version):
+2. Bump version (required before every publish):
 
 ```bash
 npm version patch
@@ -85,7 +151,9 @@ npm version patch
 # or: npm version major
 ```
 
-2. Login and pre-check:
+`npm version` will update `package.json` and create a git tag.
+
+3. Login and run release check:
 
 ```bash
 npm login
@@ -93,24 +161,36 @@ npm whoami
 npm run release:check
 ```
 
-3. Publish:
+4. Publish package:
 
 ```bash
+npm publish --access public
+# if your account requires 2FA OTP:
 npm publish --access public --otp <6-digit-otp>
 ```
 
-4. Verify release:
+5. Verify and update clients:
 
 ```bash
 npm view @elvis1513/auto-coding-skill version
-```
-
-5. Update installed clients:
-
-```bash
 npm install -g @elvis1513/auto-coding-skill@latest
 ```
 
+### Common Publish Errors
+
+- `403 You cannot publish over the previously published versions`
+  - Cause: same version already exists.
+  - Fix: run `npm version patch` (or `minor`/`major`) then publish again.
+- `403 Two-factor authentication ... is required to publish`
+  - Cause: publish requires 2FA.
+  - Fix: use `npm publish --access public --otp <6-digit-otp>`.
+- `404 Not Found` when install
+  - Cause: package not published successfully, or scope/name mismatch.
+  - Fix: verify with `npm view @elvis1513/auto-coding-skill version` first.
+- `Access token expired or revoked`
+  - Cause: npm auth token expired.
+  - Fix: run `npm login` again and retry publish/install.
+
 ## License
 
 MIT

package/cli/assets/skill/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: auto-coding-skill
-description: Use for strict project engineering workflow in Claude/Codex. Initialize docs, fill ENGINEERING.md frontmatter once, then execute design->implement->gates->summary->commit/push.
+description: Use for strict project engineering workflow in Claude/Codex. Initialize docs, fill docs/ENGINEERING.md frontmatter once, then execute design->implement->gates->summary->commit/push.
 ---
 
 # Auto Coding Skill (Claude + Codex)
@@ -36,7 +36,7 @@ pip install pyyaml requests
 
 Fill only:
 
-- `ENGINEERING.md` frontmatter
+- `docs/ENGINEERING.md` frontmatter
 
 This contains all manual fields:
 - `commands.*`
@@ -47,7 +47,7 @@ Do not duplicate config in other md/yaml files.
 
 ## Execution order
 
-1) `ENGINEERING.md`
+1) `docs/ENGINEERING.md`
 2) `docs/tasks/taskbook.md`
 3) `docs/design/**`
 4) implementation

package/cli/assets/skill/data/templates/ENGINEERING.md

@@ -37,7 +37,7 @@ docs:
   summary_dir: "docs/tasks/summaries"
 ---
 
-# ENGINEERING.md — AutoPipeline Gates (Source of Truth)
+# docs/ENGINEERING.md — AutoPipeline Gates (Source of Truth)
 
 目标：把一次任务固化为不可跳过的流水线：  
 读任务 → 写DD → 实现 → 本地测试通过 → 静态分析+Review落盘 → 更新API Markdown+接口变更清单 →  
@@ -50,14 +50,14 @@ docs:
 
 ## 0. 配置填写（必须）
 
-先填写本文件 frontmatter 中的所有空值（例如 ip/用户名/密码/服务名/路径/命令）。  
+先填写 `docs/ENGINEERING.md` frontmatter 中的所有空值（例如 ip/用户名/密码/服务名/路径/命令）。  
 禁止在其他 md/yaml 重复维护这些配置。
 
 ---
 
 ## 1. 权威输入与冲突裁决（优先级）
 
-1) ENGINEERING.md（本文件）  
+1) docs/ENGINEERING.md（本文件）  
 2) docs/tasks/taskbook.md  
 3) docs/design/**  
 4) docs/interfaces/api.md  

package/cli/assets/skill/data/templates/bridges/CLAUDE.md

@@ -1 +1 @@
-Follow ENGINEERING.md strictly. Source of truth: ENGINEERING.md.
+Follow docs/ENGINEERING.md strictly. Source of truth: docs/ENGINEERING.md.

package/cli/assets/skill/data/templates/bridges/CODEX.md

@@ -1 +1 @@
-Follow ENGINEERING.md strictly. Source of truth: ENGINEERING.md.
+Follow docs/ENGINEERING.md strictly. Source of truth: docs/ENGINEERING.md.

package/cli/assets/skill/data/templates/docs/deployment/deploy-runbook.md

@@ -1,6 +1,6 @@
 # Deploy Runbook（单机 systemd / jar）
 
-部署参数统一读取：`ENGINEERING.md` frontmatter
+部署参数统一读取：`docs/ENGINEERING.md` frontmatter
 - deployment.host / deployment.ssh_port / deployment.username / deployment.password
 - deployment.service_name / deployment.systemd_dir
 - deployment.remote_app_root / deployment.remote_jar_path / deployment.remote_config_dir / deployment.remote_bin_dir

package/cli/assets/skill/data/templates/docs/reviews/_TEMPLATE-REVIEW.md

@@ -1,7 +1,7 @@
 # Review — <Task ID> — YYYY-MM-DD HH:MM
 
 ## 1. 静态分析结果（必须）
-- Command：lint + typecheck（来自 ENGINEERING.md frontmatter）
+- Command：lint + typecheck（来自 docs/ENGINEERING.md frontmatter）
 - Summary：
 - Issues：
 - Resolved/Deferred（deferred 必须给出后续任务）：

package/cli/assets/skill/data/templates/docs/tasks/summaries/_TEMPLATE-TASK-SUMMARY.md

@@ -28,7 +28,7 @@
 - 回滚方式：
 
 ## 5. 质量门禁证据（必须可追溯）
-- 项目配置：`ENGINEERING.md`（frontmatter）
+- 项目配置：`docs/ENGINEERING.md`（frontmatter）
 - 本地CI：`ci-local`
 - 静态分析：`static`
 - Review 文档：`docs/reviews/<TASK_ID>-<timestamp>.md`

package/cli/assets/skill/data/templates/docs/tasks/taskbook.md

@@ -18,7 +18,7 @@
   - [ ] T0001-2 <subtask>
 
 ### 证据（完成后填写）
-- 项目配置：`ENGINEERING.md`（frontmatter）
+- 项目配置：`docs/ENGINEERING.md`（frontmatter）
 - DD：`docs/design/T0001-<slug>.md`
 - Review：`docs/reviews/T0001-YYYYMMDD-HHMM.md`
 - API 文档：`docs/interfaces/api.md`

package/cli/assets/skill/scripts/ap.py

@@ -21,7 +21,7 @@ def cmd_install(args: argparse.Namespace) -> None:
     templates = _skill_root() / "data" / "templates"
 
     copy_tree(templates / "docs", repo / "docs")
-    copy_tree(templates / "ENGINEERING.md", repo / "ENGINEERING.md")
+    copy_tree(templates / "ENGINEERING.md", repo / "docs" / "ENGINEERING.md")
 
     if args.bridges:
         copy_tree(templates / "bridges", repo)
@@ -32,7 +32,7 @@ def cmd_install(args: argparse.Namespace) -> None:
     copy_tree(Path(__file__).resolve().parent / "core.py", scripts_dir / "core.py")
 
     gi = repo / ".gitignore"
-    secret_line = "ENGINEERING.md"
+    secret_line = "docs/ENGINEERING.md"
     if gi.exists():
         txt = gi.read_text(encoding="utf-8")
         if secret_line not in txt:
@@ -41,7 +41,7 @@ def cmd_install(args: argparse.Namespace) -> None:
         gi.write_text(secret_line + "\n", encoding="utf-8")
 
     print(f"[install] OK: scaffold installed into {repo}")
-    print("[install] Next: edit ENGINEERING.md frontmatter and fill all project/env fields")
+    print("[install] Next: edit docs/ENGINEERING.md frontmatter and fill all project/env fields")
 
 
 def _infer_title(taskbook: Path, task_id: str) -> str:
@@ -164,7 +164,7 @@ def cmd_run(args: argparse.Namespace) -> None:
     """
     Run a configured gate command:
       build | test | lint | typecheck | format | smoke | regression
-    Commands are read from ENGINEERING.md frontmatter.
+    Commands are read from docs/ENGINEERING.md frontmatter.
     """
     repo = Path(args.repo).resolve()
     cfg = _load_cfg(repo)
@@ -173,7 +173,7 @@ def cmd_run(args: argparse.Namespace) -> None:
     if name not in commands:
         raise APError(
             f"Command not configured: commands.{name}. "
-            "Edit ENGINEERING.md frontmatter. "
+            "Edit docs/ENGINEERING.md frontmatter. "
             f"Available: {', '.join(commands.keys()) or '(none)'}"
         )
     cmd = str(commands[name])

package/cli/assets/skill/scripts/core.py

@@ -97,13 +97,13 @@ def http_get_status(url: str, timeout_s: int = 5) -> int:
 def find_config(repo: Path) -> Path:
     """Find single source project config file."""
     candidates = [
-        repo / "ENGINEERING.md",
+        repo / "docs" / "ENGINEERING.md",
     ]
     for c in candidates:
         if c.exists():
             return c
     raise APError(
-        "Project config not found. Create ENGINEERING.md "
+        "Project config not found. Create docs/ENGINEERING.md "
         "and put commands + deployment fields in YAML frontmatter."
     )
 

package/cli/src/index.js

@@ -64,7 +64,7 @@ function resolveTargetDir(ai, mode, destOverride){
 
 function ensureGitignore(projectDir){
   const gi = path.join(projectDir, ".gitignore");
-  const line = "ENGINEERING.md";
+  const line = "docs/ENGINEERING.md";
   if (!exists(gi)) {
     fs.writeFileSync(gi, `${line}\n`, "utf-8");
     return;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@elvis1513/auto-coding-skill",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "CLI installer for auto-coding-skill (Claude Code + Codex CLI).",
   "type": "module",
   "bin": {