diff --git a/CHANGELOG.md b/CHANGELOG.md index a77dfc1..3c18f50 100644 --- 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//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 index d3a051b..8f12762 100644 --- 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 index 9899af1..218261b 100644 --- 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//SKILL.md` so the +current skill discovery mechanism (directory + SKILL.md with YAML +frontmatter) can load it: ```markdown -# [Descriptive Pattern Name] +--- +name: +description: +when_to_use: Use when +--- -**Extracted:** [Date] -**Context:** [Brief description of when this applies] +# [Descriptive Pattern Name] ## Problem [What problem this solves - be specific] @@ -49,18 +54,15 @@ 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//SKILL.md` ## Notes @@ -68,3 +70,5 @@ Create a skill file at `~/.claude/skills/learned/[pattern-name].md`: - 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 index 3a629ec..8dc9041 100644 --- 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 ` - Full feature workflow -- `bugfix ` - Bug fix workflow -- `refactor ` - Refactoring workflow -- `security ` - Security review workflow -- `custom ` - Custom agent sequence - -## Custom Workflow Example - -``` -/orchestrate custom "architect,tdd-guide,code-reviewer" "Redesign caching layer" -``` +`/orchestrate custom "" ""` 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 index 6f5e250..7bfb399 100644 --- 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! diff --git a/commands/update-docs.md b/commands/update-docs.md index 3dd0f89..416ba7e 100644 --- a/commands/update-docs.md +++ b/commands/update-docs.md @@ -1,12 +1,13 @@ # Update Documentation -Sync documentation from source-of-truth: +Sync documentation from real sources of truth: -1. Read package.json scripts section - - Generate scripts reference table +1. Detect the project's task definition source (package.json scripts, + Makefile, pyproject.toml, etc.) + - Generate a scripts/tasks reference table - Include descriptions from comments -2. Read .env.example +2. Read .env.example (if present) - Extract all environment variables - Document purpose and format @@ -16,16 +17,18 @@ Sync documentation from source-of-truth: - Environment setup - Testing procedures -4. Generate docs/RUNBOOK.md with: - - Deployment procedures - - Monitoring and alerts - - Common issues and fixes - - Rollback procedures +4. Update docs/RUNBOOK.md **only when real operational sources exist** + (CI workflow definitions, Dockerfile/compose, IaC, deploy scripts, or + an existing docs/RUNBOOK.md). Derive content from those sources only. + Omit any section (Deployment / Monitoring / Rollback / ...) that has + no source — never invent procedures. List the missing sections in the + report instead. 5. Identify obsolete documentation: - - Find docs not modified in 90+ days + - Find docs that look stale (e.g. not modified in ~90 days) - List for manual review 6. Show diff summary -Single source of truth: package.json and .env.example +Sources of truth: task definitions and .env.example for scripts/env; +CI / IaC / deploy configs for operational procedures. diff --git a/tests/unit/test-content-cleanup.sh b/tests/unit/test-content-cleanup.sh index d6a9807..8cfc31d 100644 --- a/tests/unit/test-content-cleanup.sh +++ b/tests/unit/test-content-cleanup.sh @@ -78,9 +78,10 @@ } { - test_name="content-cleanup: orchestrate uses existing agents" + test_name="content-cleanup: orchestrate prefers parallel reviews over fixed chains" if ! grep -q 'explorer ->' "$PROJECT_DIR/commands/orchestrate.md" \ - && grep -q 'planner -> tdd-guide -> code-reviewer' "$PROJECT_DIR/commands/orchestrate.md"; then + && ! grep -q 'planner -> tdd-guide -> code-reviewer' "$PROJECT_DIR/commands/orchestrate.md" \ + && grep -q 'spawn independent reviewers in parallel' "$PROJECT_DIR/commands/orchestrate.md"; then pass "$test_name" else fail "$test_name" diff --git a/tests/unit/test-doc-blocker.sh b/tests/unit/test-doc-blocker.sh index 0d8498d..b4c7b02 100644 --- a/tests/unit/test-doc-blocker.sh +++ b/tests/unit/test-doc-blocker.sh @@ -28,7 +28,7 @@ _doc_blocker_decision() { "$PROJECT_DIR/.reports/SUMMARY.md" "$PROJECT_DIR/docs/CODEMAPS/ANALYSIS.md" "$PROJECT_DIR/.claude/evals/feature-name.md" - "$HOME/.claude/skills/learned/pattern.md" + "$HOME/.claude/skills/learned/pattern/SKILL.md" "$PROJECT_DIR/.specify/memory/constitution.md" ) ok_all=true