@accelerator-mzq/forge 1.4.0

package/dist/core/templates/skills/using-forge.md

@@ -0,0 +1,163 @@
+---
+name: forge:using-forge
+description: Use when starting any conversation - establishes how to find and use forge 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.
+</SUBAGENT-STOP>
+
+<EXTREMELY-IMPORTANT>
+If you think there is even a 1% chance a skill might apply to what you are doing, you ABSOLUTELY MUST invoke the skill.
+
+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>
+
+## Instruction Priority
+
+Forge skills override default system prompt behavior, but **user instructions always take precedence**:
+
+1. **User's explicit instructions** (CLAUDE.md, AGENTS.md, direct requests) — highest priority
+2. **Forge skills** — override default system behavior where they conflict
+3. **Default system prompt** — lowest priority
+
+If CLAUDE.md says "don't use TDD" and a skill says "always use TDD," follow the user's instructions. The user is in control.
+
+## How to Access Skills
+
+**In Claude Code:** Use the `Skill` tool. When you invoke a skill, its content is loaded and presented to you—follow it directly. Never use the Read tool on skill files.
+
+# Using Skills
+
+## The Rule
+
+**Invoke relevant or requested skills BEFORE any response or action.** Even a 1% chance a skill might apply means that you should invoke the skill to check. If an invoked skill turns out to be wrong for the situation, you don't need to use it.
+
+```dot
+digraph skill_flow {
+    "User message received" [shape=doublecircle];
+    "About to EnterPlanMode?" [shape=doublecircle];
+    "Already brainstormed?" [shape=diamond];
+    "Invoke brainstorming skill" [shape=box];
+    "Might any skill apply?" [shape=diamond];
+    "Invoke Skill tool" [shape=box];
+    "Announce: 'Using [skill] to [purpose]'" [shape=box];
+    "Has checklist?" [shape=diamond];
+    "Create TodoWrite todo per item" [shape=box];
+    "Follow skill exactly" [shape=box];
+    "Respond (including clarifications)" [shape=doublecircle];
+
+    "About to EnterPlanMode?" -> "Already brainstormed?";
+    "Already brainstormed?" -> "Invoke brainstorming skill" [label="no"];
+    "Already brainstormed?" -> "Might any skill apply?" [label="yes"];
+    "Invoke brainstorming skill" -> "Might any skill apply?";
+
+    "User message received" -> "Might any skill apply?";
+    "Might any skill apply?" -> "Invoke Skill tool" [label="yes, even 1%"];
+    "Might any skill apply?" -> "Respond (including clarifications)" [label="definitely not"];
+    "Invoke Skill tool" -> "Announce: 'Using [skill] to [purpose]'";
+    "Announce: 'Using [skill] to [purpose]'" -> "Has checklist?";
+    "Has checklist?" -> "Create TodoWrite todo per item" [label="yes"];
+    "Has checklist?" -> "Follow skill exactly" [label="no"];
+    "Create TodoWrite todo per item" -> "Follow skill exactly";
+}
+```
+
+## Red Flags
+
+These thoughts mean STOP—you're rationalizing:
+
+| 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 check git/files 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 current version.                   |
+| "This doesn't count as a task"      | Action = task. Check for skills.                       |
+| "The skill is overkill"             | Simple things become complex. Use it.                  |
+| "I'll just do this one thing first" | Check BEFORE doing anything.                           |
+| "This feels productive"             | Undisciplined action wastes time. Skills prevent this. |
+| "I know what that means"            | Knowing the concept ≠ using the skill. Invoke it.      |
+
+## Skill Priority
+
+When multiple skills could apply, use this order:
+
+1. **Process skills first** (brainstorming, debugging) - these determine HOW to approach the task
+2. **Implementation skills second** - these guide execution
+
+"Let's build X" → brainstorming first, then implementation skills.
+"Fix this bug" → debugging first, then domain-specific skills.
+
+## Skill Types
+
+**Rigid** (TDD, debugging): Follow exactly. Don't adapt away discipline.
+
+**Flexible** (patterns): Adapt principles to context.
+
+The skill itself tells you which.
+
+## User Instructions
+
+Instructions say WHAT, not HOW. "Add X" or "Fix Y" doesn't mean skip workflows.
+
+## v0.3 plugin 协议状态(Plan 0a + Plan 0b.1 实测,2026-05-09)
+
+forge 在三 harness 下的协议支持:
+
+| Tier | Harness     | skill auto-trigger | `/forge:*` slash commands | CLI 调用形态                                                 |
+| ---- | ----------- | ------------------ | ------------------------- | ------------------------------------------------------------ |
+| 1    | Claude Code | ✅ 全 PASS         | ✅ 全 PASS                | commands.md 调 `${CLAUDE_PLUGIN_ROOT}/scripts/run-forge.mjs` |
+| 2    | OpenCode    | ✅ PASS            | ❌ FAIL(plugin 不支持)    | skill 文本内嵌 fenced bash + must-execute 调 helper          |
+| 3    | Codex       | ✅ PASS            | ❌ FAIL(plugin 不支持)    | 同上                                                         |
+
+**OpenCode + Codex 用户提示**:即使 `/forge:*` 不可用,brainstorming / writing-plans / verify 等 skill **会按 description 自动触发**,你只需:
+
+- 输入模糊需求 → AI 自动 invoke `forge:brainstorming`
+- 输入 "完成验证 / verify" → AI 自动 invoke `forge:verification-before-completion`
+- 等等
+
+跟 Claude Code 体验一致,只是没有 `/forge:propose` 这种"显式入口"按钮。
+
+## forge slash commands(本 bootstrap 携带的 7 个工作流入口)
+
+**触发 prerequisites**:Tier 1 Claude Code 路径下可用;Tier 2/3 OpenCode/Codex 路径下不可用(实测 FAIL,见上表)— 改为 skill auto-trigger 等价路径。
+
+触发以下任一命令时,会自动调起对应 skill 链:
+
+| 命令                                               | 用途                                                   | 调起 skill                                                                                                                                     |
+| -------------------------------------------------- | ------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- |
+| `/forge:brainstorm <topic>`                        | 模糊想法 → forge/drafts/<date>-<topic>.md              | forge:brainstorming                                                                                                                            |
+| `/forge:propose <change-id> [--from-draft <name>]` | draft → 4 个 change 产物                               | forge:writing-plans                                                                                                                            |
+| `/forge:apply [--parallel]`                        | tasks.md → 实施                                        | forge:subagent-driven-development + forge:test-driven-development(--parallel 加 forge:dispatching-parallel-agents + forge:using-git-worktrees) |
+| `/forge:review`                                    | 派 review subagent + 收反馈                            | forge:requesting-code-review + forge:receiving-code-review                                                                                     |
+| `/forge:verify`                                    | 跑 forge validate + 三维度分析 + 写 verify-passed YAML | forge:verification-before-completion + forge:verifying-three-dimensions                                                                        |
+| `/forge:archive`                                   | 归档 change 到 forge/changes/archive/                  | (CLI `forge archive`,无 skill 链)                                                                                                              |
+| `/forge:explore [<topic> \| --change <id>]`        | 非线性思考空间(任何阶段,非产物驱动)                    | forge:exploring(9f 新增,沿 design §2.5)                                                                                                        |
+
+## meta-development entry — writing-skills
+
+forge 框架自身的 skill 开发流程(用户主动 invoke,不走 slash command 路径):
+
+| 触发                                                  | 调起 skill             |
+| ----------------------------------------------------- | ---------------------- |
+| 创建一个新 forge skill(`skills/<name>/SKILL.md`)      | `forge:writing-skills` |
+| 修订一个 forge skill 的 behavior(不是 typo)           | `forge:writing-skills` |
+| 跑 forge-eval baseline 重跑发现 skill 失效 → REFACTOR | `forge:writing-skills` |
+
+`forge:writing-skills` 自身的初次开发使用 superpowers 上游 writing-skills 完成(bootstrap exception,沿 design §2.9.5);后续修订使用 forge:writing-skills 自身。详 `skills/writing-skills/SKILL.md`。
+
+## forge 红旗清单(覆盖 superpowers 红旗清单的 forge 专属补充)
+
+除了 superpowers 通用红旗,forge 多以下条目:
+
+| 想法                                                               | 现实                                                                                                                                                                                                     |
+| ------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| "用户需求看起来很清晰,直接写 propose 吧"                           | 用户原话有 "大概 / 也许 / 不太确定 / 看着办" 任一关键词 → 必须先 `/forge:brainstorm`,不允许直接 `/forge:propose`                                                                                         |
+| "实施中模糊 / 觉得需要重新想想,直接改 `design.md` 或跳 forge 流程" | 错(沿 design §2.5 + plan-9f)。**开放思考**走 `/forge:explore --change <id>`(skill 强制显式收尾 + capture offer + 不写 artifacts);**阻塞 issue**走 §2.1 Fluid Pause;**都不是**在 apply 中直接改 artifacts |
+| "explore 是 thinking time,可以无限发散,不需要 capture offer"       | 错(沿 design §2.5.6 forge 反向加固第一条)。即使 OpenSpec 上游允许"不 reach conclusion",forge 加显式收尾约束 — skill 末尾必须输出 `## Exploration Summary` + 至少一个具体 `file:section` 的 capture offer |

package/dist/core/templates/skills/using-git-worktrees.md

@@ -0,0 +1,229 @@
+---
+name: forge:using-git-worktrees
+description: Use when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallback
+---
+
+# Using Git Worktrees
+
+## Overview
+
+Git worktrees create isolated workspaces sharing the same repository, allowing work on multiple branches simultaneously without switching.
+
+**Core principle:** Systematic directory selection + safety verification = reliable isolation.
+
+**Announce at start:** "I'm using the forge:using-git-worktrees skill to set up an isolated workspace."
+
+## Directory Selection Process
+
+Follow this priority order:
+
+### 1. Check Existing Directories
+
+```bash
+# Check in priority order
+ls -d .worktrees 2>/dev/null     # Preferred (hidden)
+ls -d worktrees 2>/dev/null      # Alternative
+```
+
+**If found:** Use that directory. If both exist, `.worktrees` wins.
+
+### 2. Check CLAUDE.md / AGENTS.md
+
+```bash
+grep -i "worktree.*director" CLAUDE.md 2>/dev/null
+grep -i "worktree.*director" AGENTS.md 2>/dev/null
+```
+
+**If preference specified:** Use it without asking.
+
+### 3. Ask User
+
+If no directory exists and no preference file:
+
+```
+No worktree directory found. Where should I create worktrees?
+
+1. .worktrees/ (project-local, hidden)
+2. ~/.config/forge/worktrees/<project-name>/ (global location)
+
+Which would you prefer?
+```
+
+## Safety Verification
+
+### For Project-Local Directories (.worktrees or worktrees)
+
+**MUST verify directory is ignored before creating worktree:**
+
+```bash
+# Check if directory is ignored (respects local, global, and system gitignore)
+git check-ignore -q .worktrees 2>/dev/null || git check-ignore -q worktrees 2>/dev/null
+```
+
+**If NOT ignored:**
+
+Per "Fix broken things immediately" rule:
+
+1. Add appropriate line to .gitignore
+2. Commit the change
+3. Proceed with worktree creation
+
+**Why critical:** Prevents accidentally committing worktree contents to repository.
+
+### For Global Directory (~/.config/forge/worktrees)
+
+No .gitignore verification needed - outside project entirely.
+
+## Creation Steps
+
+### 1. Detect Project Name
+
+```bash
+project=$(basename "$(git rev-parse --show-toplevel)")
+```
+
+### 2. Create Worktree
+
+```bash
+# Determine full path
+case $LOCATION in
+  .worktrees|worktrees)
+    path="$LOCATION/$BRANCH_NAME"
+    ;;
+  ~/.config/forge/worktrees/*)
+    path="~/.config/forge/worktrees/$project/$BRANCH_NAME"
+    ;;
+esac
+
+# Create worktree with new branch
+git worktree add "$path" -b "$BRANCH_NAME"
+cd "$path"
+```
+
+### 3. Run Project Setup
+
+Auto-detect and run appropriate setup:
+
+```bash
+# Node.js
+if [ -f package.json ]; then npm install; fi
+
+# Rust
+if [ -f Cargo.toml ]; then cargo build; fi
+
+# Python
+if [ -f requirements.txt ]; then pip install -r requirements.txt; fi
+if [ -f pyproject.toml ]; then poetry install; fi
+
+# Go
+if [ -f go.mod ]; then go mod download; fi
+```
+
+### 4. Verify Clean Baseline
+
+Run tests to ensure worktree starts clean:
+
+```bash
+# Examples - use project-appropriate command
+npm test
+cargo test
+pytest
+go test ./...
+```
+
+**If tests fail:** Report failures, ask whether to proceed or investigate.
+
+**If tests pass:** Report ready.
+
+### 5. Report Location
+
+```
+Worktree ready at <full-path>
+Tests passing (<N> tests, 0 failures)
+Ready to implement <feature-name>
+```
+
+## forge Worktree Naming Convention
+
+forge --parallel 默认 worktree 名 `forge-<change-id>-<task-id>`,放在 `.git/forge-worktrees/` 下,与 forge change 一一对应。
+
+例如:`forge-ch-001-task-3` 对应 change `ch-001` 的 task 3。
+
+## Quick Reference
+
+| Situation                  | Action                               |
+| -------------------------- | ------------------------------------ |
+| `.worktrees/` exists       | Use it (verify ignored)              |
+| `worktrees/` exists        | Use it (verify ignored)              |
+| Both exist                 | Use `.worktrees/`                    |
+| Neither exists             | Check CLAUDE.md/AGENTS.md → Ask user |
+| Directory not ignored      | Add to .gitignore + commit           |
+| Tests fail during baseline | Report failures + ask                |
+| No package.json/Cargo.toml | Skip dependency install              |
+
+## Common Mistakes
+
+### Skipping ignore verification
+
+- **Problem:** Worktree contents get tracked, pollute git status
+- **Fix:** Always use `git check-ignore` before creating project-local worktree
+
+### Assuming directory location
+
+- **Problem:** Creates inconsistency, violates project conventions
+- **Fix:** Follow priority: existing > CLAUDE.md/AGENTS.md > ask
+
+### Proceeding with failing tests
+
+- **Problem:** Can't distinguish new bugs from pre-existing issues
+- **Fix:** Report failures, get explicit permission to proceed
+
+### Hardcoding setup commands
+
+- **Problem:** Breaks on projects using different tools
+- **Fix:** Auto-detect from project files (package.json, etc.)
+
+## Example Workflow
+
+```
+You: I'm using the forge:using-git-worktrees skill to set up an isolated workspace.
+
+[Check .worktrees/ - exists]
+[Verify ignored - git check-ignore confirms .worktrees/ is ignored]
+[Create worktree: git worktree add .worktrees/auth -b feature/auth]
+[Run npm install]
+[Run npm test - 47 passing]
+
+Worktree ready at /Users/jesse/myproject/.worktrees/auth
+Tests passing (47 tests, 0 failures)
+Ready to implement auth feature
+```
+
+## Red Flags
+
+**Never:**
+
+- Create worktree without verifying it's ignored (project-local)
+- Skip baseline test verification
+- Proceed with failing tests without asking
+- Assume directory location when ambiguous
+- Skip CLAUDE.md/AGENTS.md check
+
+**Always:**
+
+- Follow directory priority: existing > CLAUDE.md/AGENTS.md > ask
+- Verify directory is ignored for project-local
+- Auto-detect and run project setup
+- Verify clean test baseline
+
+## Integration
+
+**Called by:**
+
+- **forge:brainstorming** (Phase 4) - REQUIRED when design is approved and implementation follows
+- **forge:subagent-driven-development** - REQUIRED before executing any tasks
+- Any skill needing isolated workspace
+
+**Pairs with:**
+
+- **forge:finishing-a-development-branch** - REQUIRED for cleanup after work complete

package/dist/core/templates/skills/verification-before-completion.md

@@ -0,0 +1,175 @@
+---
+name: forge:verification-before-completion
+description: Use when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always
+---
+
+# Verification Before Completion
+
+## Overview
+
+Claiming work is complete without verification is dishonesty, not efficiency.
+
+**Core principle:** Evidence before claims, always.
+
+**Violating the letter of this rule is violating the spirit of this rule.**
+
+## The Iron Law
+
+```
+NO COMPLETION CLAIMS WITHOUT FRESH VERIFICATION EVIDENCE
+```
+
+If you haven't run the verification command in this message, you cannot claim it passes.
+
+## The Gate Function
+
+```
+BEFORE claiming any status or expressing satisfaction:
+
+1. IDENTIFY: What command proves this claim?
+2. RUN: Execute the FULL command (fresh, complete)
+3. READ: Full output, check exit code, count failures
+4. VERIFY: Does output confirm the claim?
+   - If NO: State actual status with evidence
+   - If YES: State claim WITH evidence
+5. ONLY THEN: Make the claim
+
+Skip any step = lying, not verifying
+```
+
+## Common Failures
+
+| Claim                 | Requires                        | Not Sufficient                 |
+| --------------------- | ------------------------------- | ------------------------------ |
+| Tests pass            | Test command output: 0 failures | Previous run, "should pass"    |
+| Linter clean          | Linter output: 0 errors         | Partial check, extrapolation   |
+| Build succeeds        | Build command: exit 0           | Linter passing, logs look good |
+| Bug fixed             | Test original symptom: passes   | Code changed, assumed fixed    |
+| Regression test works | Red-green cycle verified        | Test passes once               |
+| Agent completed       | VCS diff shows changes          | Agent reports "success"        |
+| Requirements met      | Line-by-line checklist          | Tests passing                  |
+
+## Red Flags - STOP
+
+- Using "should", "probably", "seems to"
+- Expressing satisfaction before verification ("Great!", "Perfect!", "Done!", etc.)
+- About to commit/push/PR without verification
+- Trusting agent success reports
+- Relying on partial verification
+- Thinking "just this once"
+- Tired and wanting work over
+- **ANY wording implying success without having run verification**
+
+## Rationalization Prevention
+
+| Excuse                                  | Reality                |
+| --------------------------------------- | ---------------------- |
+| "Should work now"                       | RUN the verification   |
+| "I'm confident"                         | Confidence ≠ evidence  |
+| "Just this once"                        | No exceptions          |
+| "Linter passed"                         | Linter ≠ compiler      |
+| "Agent said success"                    | Verify independently   |
+| "I'm tired"                             | Exhaustion ≠ excuse    |
+| "Partial check is enough"               | Partial proves nothing |
+| "Different words so rule doesn't apply" | Spirit over letter     |
+
+## Key Patterns
+
+**Tests:**
+
+```
+✅ [Run test command] [See: 34/34 pass] "All tests pass"
+❌ "Should pass now" / "Looks correct"
+```
+
+**Regression tests (TDD Red-Green):**
+
+```
+✅ Write → Run (pass) → Revert fix → Run (MUST FAIL) → Restore → Run (pass)
+❌ "I've written a regression test" (without red-green verification)
+```
+
+**Build:**
+
+```
+✅ [Run build] [See: exit 0] "Build passes"
+❌ "Linter passed" (linter doesn't check compilation)
+```
+
+**Requirements:**
+
+```
+✅ Re-read plan → Create checklist → Verify each → Report gaps or completion
+❌ "Tests pass, phase complete"
+```
+
+**Agent delegation:**
+
+```
+✅ Agent reports success → Check VCS diff → Verify changes → Report actual state
+❌ Trust agent report
+```
+
+## Evidence Storage (forge-specific)
+
+forge:verify 命令模板会把证据 log 写到 `forge/changes/<change-id>/.evidence/<task-id>.log`,SHA256 由 `.verify-passed` YAML 的 `evidence[i].log_hash` 字段绑定(spec §3.4)。
+
+当声称某个 change 已通过验证时,必须能指向对应的 `.evidence/` 目录和 `.verify-passed` 文件。
+
+## Why This Matters
+
+From 24 failure memories:
+
+- your human partner said "I don't believe you" - trust broken
+- Undefined functions shipped - would crash
+- Missing requirements shipped - incomplete features
+- Time wasted on false completion → redirect → rework
+- Violates: "Honesty is a core value. If you lie, you'll be replaced."
+
+## When To Apply
+
+**ALWAYS before:**
+
+- ANY variation of success/completion claims
+- ANY expression of satisfaction
+- ANY positive statement about work state
+- Committing, PR creation, task completion
+- Moving to next task
+- Delegating to agents
+
+**Rule applies to:**
+
+- Exact phrases
+- Paraphrases and synonyms
+- Implications of success
+- ANY communication suggesting completion/correctness
+
+## forge strict gate step (Tier 2/3 OpenCode/Codex 路径用,Plan 0a 实测 Variant B PASS)
+
+**仅 OpenCode + Codex 路径**(Tier 1 Claude Code 路径走 commands.md `/forge:verify` 调 helper)。
+
+When user says "verify" / "/forge:verify" / "完成验证" or similar, you **MUST** execute:
+
+```bash
+node "${FORGE_HELPER}" validate <change-id>
+```
+
+(`FORGE_HELPER` 解析见 forge:writing-plans skill 末尾 "CLI validation step" 段)
+
+**Result handling**:
+
+- exit 0 → forge CLI 自动写 `forge/changes/<id>/.verify-passed`(YAML schema + tasks_hash + content_hash + pass=true);report "verify PASS"
+- exit 非零 → forge CLI 自动:
+  1. 写 `forge/changes/<id>/.verify-failed`(YAML schema + fake_completions 列表)
+  2. **append 修复 task** 到 `forge/changes/<id>/tasks.md`(每 fake_completion 一条 `- [ ] verify-fix-N: ...`)
+  3. **不修改原已勾 task**(spec §3.3 不变量 2)
+
+  Tell user "Verify FAIL,请处理 verify-fix-\* 新 tasks 后重跑 verify"
+
+## The Bottom Line
+
+**No shortcuts for verification.**
+
+Run the command. Read the output. THEN claim the result.
+
+This is non-negotiable.