cloudnative-co · okash1n · Jun 12, 2026 · Jun 12, 2026 · chatgpt-codex-connector · Jun 12, 2026
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -4,6 +4,17 @@ All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/), and this project adheres to [Semantic Versioning](https://semver.org/).
 
+## [0.64.0] - 2026-06-12
+
+LLM 性能監査（#121）P3 の第 1 弾（#114）。commands の旧モデル向け儀式（固定手順の強制）を成果指向に書き換えた。
+
+### Changed
+- **orchestrate（#114）**: 固定 4 エージェント直列チェーン + 定型 HANDOFF 文書 + 35 行固定レポートテンプレートを廃止。既定を「メインスレッドで計画・実装・検証し、実装後に独立レビューエージェント（code-reviewer 必須、対象に応じて security-reviewer / architect）を並列 spawn」に変更。タスク種別の固定チェーンはレビュー観点リストに格下げ。custom での直列チェーンは「次エージェントへ 1 段落で文脈を渡す」とだけ規定（定型テンプレート廃止）
+- **build-fix（#114）**: 「エラー 1 件ごとにフルビルド再実行」を「根本原因ごとにバッチ修正 + 最速の検証手段で再チェック + 最後にフルビルド 1 回」に変更。npm/pnpm ハードコードをビルドコマンド検出に一般化。「Fix one error at a time for safety!」を削除（3 回試行ルールとユーザー停止条件は保険として維持）
+- **refactor-clean（#114）**: 「削除 1 件ごとにフルテストを前後 2 回」を「green ベースライン 1 回 → SAFE 削除をバッチ適用（削除単位コミットでロールバック容易化）→ バッチごと focused tests → 最後にフル 1 回 → 失敗時はバイセクト」に変更。ツールリストを言語別に一般化。SAFE/CAUTION/DANGER 分類と「Never delete code without running tests first!」は維持
+- **learn（#114）**: 出力形式を現行スキル発見機構に適合する `~/.claude/skills/learned/<pattern-name>/SKILL.md` + YAML frontmatter（name / description / when_to_use）に修正（旧フラット .md はスキルとして自動ロードされなかった）。「ルーチンな学びは auto-memory が自動取得、/learn は activation 可能なスキルへの明示昇格専用」と棲み分けを明記
+- **update-docs（#114）**: RUNBOOK 生成を「実在する運用ソース（CI / Dockerfile / IaC / deploy スクリプト / 既存 RUNBOOK）がある場合のみ・ソースから導出できるセクションのみ」に限定し、ソースのないセクションは省略して不足として報告する方式に変更（運用手順の捏造を構造的に防止）。「Single source of truth: package.json and .env.example」の矛盾宣言を実際のソース集合に修正。タスク定義ソースの検出を一般化
+
 ## [0.63.0] - 2026-06-12
 
 LLM 性能監査（#121）P2 の最終弾（#113）。残る挙動ガード hook を整理した。

diff --git a/commands/build-fix.md b/commands/build-fix.md
@@ -1,29 +1,26 @@
 # Build and Fix
 
-Incrementally fix TypeScript and build errors:
+Fix build errors by root cause, in batches:
 
-1. Run build: npm run build or pnpm build
+1. Detect the project's build command (package.json scripts, Makefile,
+   pyproject.toml, etc.) and run it.
 
-2. Parse error output:
-   - Group by file
-   - Sort by severity
+2. Parse error output and group errors by root cause:
+   - A changed type/interface, a renamed symbol, or a missing dependency
+     often explains many downstream errors at once.
 
-3. For each error:
-   - Show error context (5 lines before/after)
-   - Explain the issue
-   - Propose fix
-   - Apply fix
-   - Re-run build
-   - Verify error resolved
+3. Fix related errors as a batch. After each batch, re-check with the
+   fastest available verification (e.g. `tsc --noEmit`, incremental build,
+   affected-package build) instead of a full rebuild.
 
-4. Stop if:
-   - Fix introduces new errors
+4. Run the full build once at the end to confirm.
+
+5. Stop if:
+   - The error count is increasing, or fixes are going in circles
    - Same error persists after 3 attempts
    - User requests pause
 
-5. Show summary:
+6. Show summary:
    - Errors fixed
    - Errors remaining
    - New errors introduced
-
-Fix one error at a time for safety!
diff --git a/commands/learn.md b/commands/learn.md
@@ -33,13 +33,18 @@ Look for:
 
 ## Output Format
 
-Create a skill file at `~/.claude/skills/learned/[pattern-name].md`:
+Create a skill at `~/.claude/skills/learned/<pattern-name>/SKILL.md` so the
+current skill discovery mechanism (directory + SKILL.md with YAML
+frontmatter) can load it:
 
 ```markdown
-# [Descriptive Pattern Name]
+---
+name: <pattern-name>
+description: <one-line description of the problem this solves>
+when_to_use: Use when <trigger condition for this pattern>
+---
 
-**Extracted:** [Date]
-**Context:** [Brief description of when this applies]
+# [Descriptive Pattern Name]
 
 ## Problem
 [What problem this solves - be specific]
@@ -49,22 +54,21 @@ Create a skill file at `~/.claude/skills/learned/[pattern-name].md`:
 
 ## Example
 [Code example if applicable]
-
-## When to Use
-[Trigger conditions - what should activate this skill]
 ```
 
 ## Process
 
 1. Review the session for extractable patterns
 2. Identify the most valuable/reusable insight
-3. Draft the skill file
+3. Draft the SKILL.md
 4. Ask user to confirm before saving
-5. Save to `~/.claude/skills/learned/`
+5. Save to `~/.claude/skills/learned/<pattern-name>/SKILL.md`
 
 ## Notes
 
 - Don't extract trivial fixes (typos, simple syntax errors)
 - Don't extract one-time issues (specific API outages, etc.)
 - Focus on patterns that will save time in future sessions
 - Keep skills focused - one pattern per skill
+- Routine learnings are captured automatically by auto-memory; use /learn
+  only to promote a pattern into an activatable skill
diff --git a/commands/orchestrate.md b/commands/orchestrate.md
@@ -1,172 +1,53 @@
 # Orchestrate Command
 
-Sequential agent workflow for complex tasks.
+Plan, implement, and verify in the main thread; spawn independent review
+agents after implementation. Prefer parallel reviews over sequential
+agent relays.
 
 ## Usage
 
 `/orchestrate [workflow-type] [task-description]`
 
-## Workflow Types
+## Default Execution Model
 
-### feature
-Full feature implementation workflow:
-```
-planner -> tdd-guide -> code-reviewer -> security-reviewer
-```
+1. **Plan and implement in the main thread.** Keep full context; do not
+   split planning/implementation across agents unless the task genuinely
+   needs isolated exploration.
+2. **After implementation, spawn independent reviewers in parallel:**
+   - `code-reviewer` — always, before merge
+   - `security-reviewer` — when the change touches auth, payments, PII,
+     secrets, networking, or file/command boundaries
+   - `architect` — when the change alters system boundaries or major design
+3. **Reconcile findings yourself**, fix what is real, and report.
 
-### bugfix
-Bug investigation and fix workflow:
-```
-planner -> tdd-guide -> code-reviewer
-```
+## Review Focus by Task Type
 
-### refactor
-Safe refactoring workflow:
-```
-architect -> code-reviewer -> tdd-guide
-```
+These are review-lens suggestions, not required agent chains:
 
-### security
-Security-focused review:
-```
-security-reviewer -> code-reviewer -> architect
-```
+- **feature** — correctness against requirements, tests for new behavior, security surface
+- **bugfix** — root cause addressed (not symptom), regression test added
+- **refactor** — behavior preserved, test coverage before/after, no scope creep
+- **security** — input validation, authz/authn, secrets handling, injection surfaces
 
-## Execution Pattern
+## Output Requirements
 
-For each agent in the workflow:
+Report at the end (no fixed template — cover these points):
 
-1. **Invoke agent** with context from previous agent
-2. **Collect output** as structured handoff document
-3. **Pass to next agent** in chain
-4. **Aggregate results** into final report
+- Files changed
+- Test results (commands run and outcomes)
+- Review findings and how each was resolved
+- Verdict: SHIP / NEEDS WORK / BLOCKED
 
-## Handoff Document Format
+## Custom Sequences
 
-Between agents, create handoff document:
-
-```markdown
-## HANDOFF: [previous-agent] -> [next-agent]
-
-### Context
-[Summary of what was done]
-
-### Findings
-[Key discoveries or decisions]
-
-### Files Modified
-[List of files touched]
-
-### Open Questions
-[Unresolved items for next agent]
-
-### Recommendations
-[Suggested next steps]
-```
-
-## Example: Feature Workflow
-
-```
-/orchestrate feature "Add user authentication"
-```
-
-Executes:
-
-1. **Planner Agent**
-   - Analyzes requirements
-   - Creates implementation plan
-   - Identifies dependencies
-   - Output: `HANDOFF: planner -> tdd-guide`
-
-2. **TDD Guide Agent**
-   - Reads planner handoff
-   - Writes tests first
-   - Implements to pass tests
-   - Output: `HANDOFF: tdd-guide -> code-reviewer`
-
-3. **Code Reviewer Agent**
-   - Reviews implementation
-   - Checks for issues
-   - Suggests improvements
-   - Output: `HANDOFF: code-reviewer -> security-reviewer`
-
-4. **Security Reviewer Agent**
-   - Security audit
-   - Vulnerability check
-   - Final approval
-   - Output: Final Report
-
-## Final Report Format
-
-```
-ORCHESTRATION REPORT
-====================
-Workflow: feature
-Task: Add user authentication
-Agents: planner -> tdd-guide -> code-reviewer -> security-reviewer
-
-SUMMARY
--------
-[One paragraph summary]
-
-AGENT OUTPUTS
--------------
-Planner: [summary]
-TDD Guide: [summary]
-Code Reviewer: [summary]
-Security Reviewer: [summary]
-
-FILES CHANGED
--------------
-[List all files modified]
-
-TEST RESULTS
-------------
-[Test pass/fail summary]
-
-SECURITY STATUS
----------------
-[Security findings]
-
-RECOMMENDATION
---------------
-[SHIP / NEEDS WORK / BLOCKED]
-```
-
-## Parallel Execution
-
-For independent checks, run agents in parallel:
-
-```markdown
-### Parallel Phase
-Run simultaneously:
-- code-reviewer (quality)
-- security-reviewer (security)
-- architect (design)
-
-### Merge Results
-Combine outputs into single report
-```
-
-## Arguments
-
-$ARGUMENTS:
-- `feature <description>` - Full feature workflow
-- `bugfix <description>` - Bug fix workflow
-- `refactor <description>` - Refactoring workflow
-- `security <description>` - Security review workflow
-- `custom <agents> <description>` - Custom agent sequence
-
-## Custom Workflow Example
-
-```
-/orchestrate custom "architect,tdd-guide,code-reviewer" "Redesign caching layer"
-```
+`/orchestrate custom "<agents>" "<description>"` runs an explicit agent
+sequence when you really need one. Sub-agents do not share context: when
+chaining, pass the next agent a one-paragraph summary of what was done,
+key decisions, and open questions — no fixed handoff template.
 
 ## Tips
 
-1. **Start with planner** for complex features
-2. **Always include code-reviewer** before merge
-3. **Use security-reviewer** for auth/payment/PII
-4. **Keep handoffs concise** - focus on what next agent needs
-5. **Run verification** between agents if needed
+1. **Always include code-reviewer** before merge
+2. **Use security-reviewer** for auth/payment/PII surfaces
+3. Prefer parallel reviews over sequential chains — faster and no
+   information loss between agents
diff --git a/commands/refactor-clean.md b/commands/refactor-clean.md
@@ -2,27 +2,26 @@
 
 Safely identify and remove dead code with test verification:
 
-1. Run dead code analysis tools:
-   - knip: Find unused exports and files
-   - depcheck: Find unused dependencies
-   - ts-prune: Find unused TypeScript exports
+1. Run dead-code analysis appropriate to the project language
+   (e.g. knip/depcheck/ts-prune for JS/TS, vulture for Python,
+   deadcode for Go, shellcheck + reference grep for shell).
 
-2. Generate comprehensive report in .reports/dead-code-analysis.md
+2. Generate a report (e.g. .reports/dead-code-analysis.md).
 
 3. Categorize findings by severity:
-   - SAFE: Test files, unused utilities
-   - CAUTION: API routes, components
+   - SAFE: Test files, unused internal utilities
+   - CAUTION: Public APIs / exported interfaces, route handlers, UI components
    - DANGER: Config files, main entry points
 
-4. Propose safe deletions only
+4. Verification flow:
+   - Run the full test suite once to establish a green baseline
+   - Apply SAFE deletions as a batch, one commit per deletion or logical
+     group (easy rollback)
+   - Run focused tests per batch, then the full suite once at the end
+   - On failure, bisect the batch and revert only the offending deletion
+   - Handle CAUTION items individually with focused tests
+   - DANGER items are report-only — do not delete
 
-5. Before each deletion:
-   - Run full test suite
-   - Verify tests pass
-   - Apply change
-   - Re-run tests
-   - Rollback if tests fail
-
-6. Show summary of cleaned items
+5. Show summary of cleaned items
 
 Never delete code without running tests first!