Orchestrata Ultimate › Plans › global-toolchain-integration

Global Toolchain Integration Plan

Source: plans/global-toolchain-integration.md at 8a2cb42ad · last changed 2026-07-27 · first committed 2026-06-26 · 195 lines.

Prose pending.

Plan text

Global Toolchain Integration Plan

Date: 2026-06-25 Status: Core tools deployed, integration pending

What's Deployed

All 5 tools are globally available at ~/.local/bin/:

~/.local/bin/
├── ast-query           AST structure queries (summary, find, search, stubs, etc.)
├── orchestrata-tools   Full codebase analysis (discover, diagram, query)
├── diagram-tools       Bidirectional diagram ↔ code (delegates to orchestrata-tools)
├── review-tools        Code + test review (CodeReviewer + TestReviewer)
└── test-gen            Test generation + coverage (TestStubGenerator + CoverageAnalyzer)

Python API globally available via orchestrata-tools package (v0.3.0, installed via uv tool install):

from orchestrata_tools import (
    DiagramToCode, CodeReviewer, SourceASTParser,
    CoverageAnalyzer, TestMatcher, ClassDiagramGenerator,
    ParsedClass, MermaidDiagram, ModuleDiagramGenerator,
    ReviewReport, TestReviewer, ASTIndex, JSONASTLoader,
)

Plan: Integration Layers

Layer 1: CodeWhale Skills (for session use)

Status: Both skills created.

Layer 2: Pre-Commit / Pre-Write Hooks

Goal: Automatically run review-tools before committing, and test-gen after creating new source files.

Files to create:

1. claude/hooks/pre_commit_review.py — Runs review-tools on staged changes before git commit:

   #!/usr/bin/env python3
   """Pre-commit hook: code + test review on staged files."""
   import subprocess, sys
   result = subprocess.run(["review-tools", "."], capture_output=True, text=True)
   if "ERROR" in result.stdout:
       print(result.stdout)
       sys.exit(1)
   

2. claude/hooks/post_write_test_gen.py — Runs test-gen --coverage after creating new source files:

   #!/usr/bin/env python3
   """Post-write hook: suggest test coverage for new source files."""
   import subprocess, sys
   # Only trigger for new .py files in src/
   changed = sys.argv[1] if len(sys.argv) > 1 else ""
   if changed.endswith(".py") and "src/" in changed:
       subprocess.run(["test-gen", "--coverage"])
   

3. Registration in claude/settings.json:

   {
     "hooks": {
       "PreToolUse": [
         { "matcher": "Bash", "hooks": [{"type": "command", "command": "python3 ~/.claude/hooks/pre_commit_review.py"}] }
       ],
       "PostToolUse": [
         { "matcher": "Write|Edit", "hooks": [{"type": "command", "command": "python3 ~/.claude/hooks/post_write_test_gen.py"}] }
       ]
     }
   }
   

Layer 3: Session Auto-Logging

Goal: Every tool run during a session is automatically logged as work.

Implementation: Wrap each global tool in a session-aware launcher:

# ~/workspace/orchestrata-ultimate-architecture/scripts/session_wrapper.py
"""Run any tool and auto-log to the session if one is active."""
import subprocess, sys
from pathlib import Path

tool = sys.argv[1]
args = sys.argv[2:]

# Run the actual tool
result = subprocess.run([tool, *args])

# If in a project with session tracking, log it
root = Path.cwd()
for parent in [root, *root.parents]:
    if (parent / "context.json").exists():
        subprocess.run([
            "uv", "run", "session", "work",
            f"Ran {tool} {' '.join(args[:3])}",
            "--detail", f"Exit code: {result.returncode}"
        ], cwd=str(parent))
        break

sys.exit(result.returncode)

Layer 4: Memory File Documentation

Files to document:

Layer 5: Claude Commands

Status: Already have /ast, /session, /trace. Add:

• claude/commands/review.md — /review slash command:

  # /review — Run code + test review
  Usage: /review [src|tests|all]
  

• claude/commands/diagram.md — /diagram slash command:

  # /diagram — Generate or parse diagrams
  Usage: /diagram class <ClassName>
  Usage: /diagram from-code <file>
  Usage: /diagram to-code <file.mmd>
  

• claude/commands/test.md — /test slash command:

  # /test — Generate tests or check coverage
  Usage: /test gen <file>
  Usage: /test coverage
  

Layer 6: Kimi Skills

Status: Already have ast-query in .kimi/skills/. Add:

• .kimi/skills/orchestrata-tools/SKILL.md — Same as CodeWhale skill but adapted for Kimi's format (YAML frontmatter)

Implementation Order

1. docs/global-tools.md         ← Master reference document
2. claude/commands/review.md    ← /review slash command
3. claude/commands/diagram.md   ← /diagram slash command
4. claude/commands/test.md      ← /test slash command
5. .kimi/skills/orchestrata-tools/SKILL.md  ← Kimi skill
6. claude/hooks/pre_commit_review.py        ← Pre-commit hook
7. claude/hooks/post_write_test_gen.py      ← Post-write hook
8. claude/settings.json update              ← Hook registration

Verification

# All tools on PATH from /tmp
cd /tmp && ast-query summary 2>&1 | head -1
cd /tmp && orchestrata-tools --help 2>&1 | head -1
cd /tmp && review-tools --help 2>&1 | head -3
cd /tmp && test-gen --help 2>&1 | head -3
cd /tmp && diagram-tools --help 2>&1 | head -3

# Python API everywhere
cd /tmp && python3 -c "from orchestrata_tools import DiagramToCode, CodeReviewer; print('OK')"

# Skills loaded
ls .deepseek/skills/orchestrata-tools/SKILL.md
ls ~/.deepseek/skills/ast-query/SKILL.md
ls ~/.deepseek/skills/session/SKILL.md

Related

• Plans
• Orchestrata Ultimate — project index
• Workflow
• Tasks