more changes

Author: MichaelYochpaz

.ai-workspace/README.md

@@ -21,7 +21,7 @@ This directory contains the infrastructure for the AI Workspace Template.
 | Script | Purpose |
 |--------|---------|
 | `align-workspace.py` | Pre-commit: regenerates AGENTS.md, manages feature dirs |
-| `session-sync.py` | Session start: syncs submodules, discovers tools |
+| `session-start.py` | Session start: reports repo status, discovers tools |
 | `transpile-skills.py` | Validates and distributes skills |
 | `transpile-commands.py` | Validates and distributes commands |
 | `mktmpdir.py` | Creates unique task directories under `.tmp/` |
@@ -46,7 +46,6 @@ The workspace is configured via `ai-workspace.toml` at the repository root. Key
 |---------|---------|
 | `[workspace]` | General settings (name) |
 | `[repositories]` | Repository status and sync settings |
-| `[hooks.session_start]` | Session start script config |
 | `[features]` | Enable/disable skills, commands, agent-docs |
 | `[tools]` | Tool discovery settings |
 | `[distribution]` | Where to distribute skills/commands |

.ai-workspace/docs/configuration.md

@@ -18,10 +18,6 @@ include_workspace_root = false
 template_upstream_url = "https://github.com/MichaelYochpaz/ai-workspace-template.git"
 template_upstream_git_remote = "template-upstream"
 
-[hooks.session_start]
-script = ".ai-workspace/scripts/session-start.py"
-timeout = 120
-
 [features]
 skills = true
 commands = true
@@ -93,27 +89,22 @@ Controls repository status reporting at session start. Section: `[repositories]`
 
 ---
 
-## Session start hook
-
-Configures the script that runs when an AI tool session starts. Section: `[hooks.session_start]`
-
-`script`
-:   **Type:** string -- **Default:** *(required)*
-
-    Path to the session-start script
+## Session hooks
 
-`timeout`
-:   **Type:** int -- **Default:** `120`
+Session hooks are pre-configured statically in each tool's config directory -- they're committed to the repo and work out of the box.
 
-    Timeout in seconds
-
-The default script (`.ai-workspace/scripts/session-start.py`) runs two tasks:
+The session-start script (`.ai-workspace/scripts/session-start.py`) runs two tasks:
 
 1. **Repository status** -- Reports each submodule's branch, uncommitted changes, and how far behind remote
 2. **Tool discovery** -- Detects installed CLI tools and injects usage instructions
 
 The output is wrapped in `<session-context>` XML tags that agents consume automatically.
 
+Hook configurations are stored in:
+
+- **Claude Code** -- `.claude/settings.json`
+- **OpenCode** -- `.opencode/plugins/session-sync.ts`
+
 ---
 
 ## Features
@@ -254,7 +245,6 @@ Configuration is applied at two points:
 
 1. **Pre-commit** (`align-workspace.py`) -- Reads `ai-workspace.toml` and:
     - Manages feature directories (create/remove based on `[features]`)
-    - Registers session hooks with Claude Code (`.claude/settings.json`)
     - Regenerates `schema.json`
     - Renders `AGENTS.md` from the Jinja2 template
     - Runs skill and command validators

.ai-workspace/docs/index.md

@@ -12,55 +12,65 @@ A meta-repository template that aggregates related repositories using git submod
 
     Aggregate repos as submodules with automatic git status reporting to agents
 
-    [:octicons-arrow-right-24: Learn more](repositories.md)
+    [Learn more :material-arrow-right:](repositories.md)
 
--   :material-magnify:{ .lg .middle } __Tool Discovery__
+-   :material-file-document-outline:{ .lg .middle } __Agent Docs__
 
     ---
 
-    Detect installed CLI tools and inject usage instructions into agent context
+    Modular docs that agents selectively load based on task relevance
 
-    [:octicons-arrow-right-24: Learn more](features/tool-discovery.md)
+    [Learn more :material-arrow-right:](features/agent-docs.md)
 
--   :material-file-document-outline:{ .lg .middle } __Agent Docs__
+-   :material-file-cog:{ .lg .middle } __AGENTS.md Generation__
 
     ---
 
-    Modular docs that agents selectively load based on task relevance
+    Auto-generate agent instructions from templates and config on every commit
 
-    [:octicons-arrow-right-24: Learn more](features/agent-docs.md)
+    [Learn more :material-arrow-right:](agents-md.md)
 
--   :material-file-cog:{ .lg .middle } __AGENTS.md Generation__
+-   :material-magnify:{ .lg .middle } __Tool Discovery__
 
     ---
 
-    Auto-generate agent instructions from templates and config on every commit
+    Detect installed CLI tools and inject usage instructions into agent context
 
-    [:octicons-arrow-right-24: Learn more](agents-md.md)
+    [Learn more :material-arrow-right:](features/tool-discovery.md)
 
 -   :material-lightning-bolt:{ .lg .middle } __Skills__
 
     ---
 
     Distribute skill directories to tool-specific paths via symlinks
 
-    [:octicons-arrow-right-24: Learn more](features/skills.md)
+    [Learn more :material-arrow-right:](features/skills.md)
 
 -   :material-console:{ .lg .middle } __Commands__
 
     ---
 
     Distribute command files across tools, converting formats where needed
 
-    [:octicons-arrow-right-24: Learn more](features/commands.md)
+    [Learn more :material-arrow-right:](features/commands.md)
+
+-   :material-folder-clock:{ .lg .middle } __Temporary Files__
+
+    ---
+
+    Git-ignored workspace for agent artifacts, organized by task
+
+    [Learn more :material-arrow-right:](features/temporary-files.md)
 
 </div>
 
 ## How it works
 
-### Session start
+### Session hooks
+
+Some AI tools support **hooks** -- scripts that run automatically at specific lifecycle points (e.g., session start, pre-prompt). This workspace uses a session-start hook to inject context into the agent before it begins work.
 
-For tools with hook support ([Claude Code](https://code.claude.com/docs/en/hooks), [OpenCode](https://opencode.ai/docs/plugins/)), a session-start script runs automatically when an AI session begins:
+For tools with hook support ([Claude Code](https://code.claude.com/docs/en/hooks), [OpenCode](https://opencode.ai/docs/plugins/)), the session-start script runs automatically when an AI session begins:
 
 ``` mermaid
 graph LR
@@ -78,8 +88,8 @@ The agent immediately knows which repos exist, what branch each is on, whether t
 Separately, on every commit, pre-commit hooks keep the workspace aligned:
 
 - Regenerate `AGENTS.md` from templates and config
-- Validate skill and command frontmatter
-- Manage feature directories
+- Validate skill and command definitions
+- Sync workspace structure with config
 
 These are two independent flows -- session hooks handle runtime context, pre-commit handles workspace integrity.
 

.ai-workspace/docs/stylesheets/custom.css

@@ -0,0 +1,6 @@
+/* Center the last card when there's an odd number in a 2-column grid */
+.grid.cards > ul > li:last-child:nth-child(odd) {
+  grid-column: 1 / -1;
+  max-width: 50%;
+  justify-self: center;
+}

.ai-workspace/schema.json

@@ -68,46 +68,6 @@
       "title": "FeaturesConfig",
       "type": "object"
     },
-    "HookConfig": {
-      "description": "Configuration for a single hook.",
-      "properties": {
-        "script": {
-          "description": "Path to the script to run",
-          "title": "Script",
-          "type": "string"
-        },
-        "timeout": {
-          "default": 120,
-          "description": "Timeout in seconds",
-          "title": "Timeout",
-          "type": "integer"
-        }
-      },
-      "required": [
-        "script"
-      ],
-      "title": "HookConfig",
-      "type": "object"
-    },
-    "HooksConfig": {
-      "description": "Hook definitions.",
-      "properties": {
-        "session_start": {
-          "anyOf": [
-            {
-              "$ref": "#/$defs/HookConfig"
-            },
-            {
-              "type": "null"
-            }
-          ],
-          "default": null,
-          "description": "Hook that runs when AI tool sessions start"
-        }
-      },
-      "title": "HooksConfig",
-      "type": "object"
-    },
     "RepositoriesConfig": {
       "description": "Repository status and sync configuration.",
       "properties": {
@@ -173,9 +133,6 @@
     "features": {
       "$ref": "#/$defs/FeaturesConfig"
     },
-    "hooks": {
-      "$ref": "#/$defs/HooksConfig"
-    },
     "repositories": {
       "$ref": "#/$defs/RepositoriesConfig"
     },

.ai-workspace/scripts/align-workspace.py

@@ -1,7 +1,6 @@
 #!/usr/bin/env python3
 """Align workspace configuration with ai-workspace.toml."""
 
-import json
 import shutil
 import subprocess
 import sys
@@ -16,7 +15,6 @@
 sys.path.insert(0, str(Path(__file__).parent.parent / "lib"))
 from config import AIWorkspaceConfig, export_schema, load_config
 
-MANAGED_SIGNATURE = ".ai-workspace/scripts/"
 PLACEHOLDER_TAG = "<placeholder>"
 
 
@@ -30,52 +28,6 @@ class AgentDoc:
     doc_path: str
 
 
-def load_json(path: Path) -> dict[str, Any]:
-    """Load JSON file, returning empty dict if missing or invalid."""
-    if not path.exists():
-        return {}
-    try:
-        with open(path, "r", encoding="utf-8") as f:
-            return json.load(f)
-    except json.JSONDecodeError:
-        print(f"Warning: {path} contains invalid JSON. Starting fresh.")
-        return {}
-
-
-def save_deterministic_json(data: dict[str, Any], path: Path) -> None:
-    """Save JSON with deterministic key ordering for minimal diffs."""
-    path.parent.mkdir(parents=True, exist_ok=True)
-    with open(path, "w", encoding="utf-8") as f:
-        json.dump(data, f, indent=2, sort_keys=True)
-        f.write("\n")  # POSIX trailing newline
-
-
-def is_managed_hook(hook: dict[str, Any]) -> bool:
-    """Check if a hook is managed by ai-workspace."""
-    if "hooks" in hook:
-        for subhook in hook["hooks"]:
-            if subhook.get("type") == "command":
-                command = subhook.get("command", "")
-                if MANAGED_SIGNATURE in command:
-                    return True
-    return False
-
-
-def merge_claude_settings(
-    existing: dict[str, Any],
-    managed_hooks: list[dict[str, Any]],
-) -> dict[str, Any]:
-    """Merge managed hooks into existing settings, preserving user hooks."""
-    if "hooks" not in existing:
-        existing["hooks"] = {}
-
-    current_hooks = existing["hooks"].get("SessionStart", [])
-    user_hooks = [h for h in current_hooks if not is_managed_hook(h)]
-    existing["hooks"]["SessionStart"] = user_hooks + managed_hooks
-
-    return existing
-
-
 def is_safe_to_remove(dir_path: Path, readme_name: str = "README.md") -> bool:
     """Check if directory can be safely removed (only has template files)."""
     if not dir_path.exists():
@@ -120,31 +72,6 @@ def manage_features(config: AIWorkspaceConfig, base_dir: Path) -> None:
                     )
 
 
-def register_claude_hooks(config: AIWorkspaceConfig, base_dir: Path) -> None:
-    """Register hooks with Claude Code."""
-    if not config.hooks.session_start:
-        return
-
-    settings_path = base_dir / ".claude/settings.json"
-    existing = load_json(settings_path)
-
-    managed_hooks = [
-        {
-            "matcher": "startup|resume",
-            "hooks": [
-                {
-                    "type": "command",
-                    "command": f'uv run "$CLAUDE_PROJECT_DIR/{config.hooks.session_start.script}"',
-                    "timeout": config.hooks.session_start.timeout,
-                    "statusMessage": "Initializing session...",
-                }
-            ],
-        }
-    ]
-
-    merged = merge_claude_settings(existing, managed_hooks)
-    save_deterministic_json(merged, settings_path)
-    print(f"Updated {settings_path}")
 
 
 def sync_schema(base_dir: Path) -> bool:
@@ -460,19 +387,16 @@ def main():
         print(f"Error: {e}")
         sys.exit(1)
 
-    # 3. Register hooks
-    register_claude_hooks(config, base_dir)
-
-    # 4. Sync schema
+    # 3. Sync schema
     sync_schema(base_dir)
 
-    # 5. Render AGENTS.md
+    # 4. Render AGENTS.md
     render_agents_md(config, base_dir)
 
-    # 6. Run validators
+    # 5. Run validators
     run_validators(config, base_dir)
 
-    # 7. Check for template updates (non-blocking notice)
+    # 6. Check for template updates (non-blocking notice)
     check_template_updates(config, base_dir)
 
     print()

.ai-workspace/zensical.toml

@@ -20,6 +20,8 @@ nav = [
 
 ]
 
+extra_css = ["stylesheets/custom.css"]
+
 [project.repo]
 url = "https://github.com/MichaelYochpaz/ai-workspace-template"
 name = "MichaelYochpaz/ai-workspace-template"

.opencode/plugins/session-sync.ts

@@ -1,33 +1,12 @@
 // Injects session-start script output into the system prompt.
-// Reads configuration from ai-workspace.toml at runtime.
 
 import type { Plugin } from "@opencode-ai/plugin";
 
-const CONFIG = "ai-workspace.toml";
+const SCRIPT = ".ai-workspace/scripts/session-start.py";
 const SERVICE = "SessionStartPlugin";
 
-interface Config {
-  hooks?: {
-    session_start?: {
-      script?: string;
-    };
-  };
-}
-
 export const SessionStartPlugin: Plugin = async (ctx) => {
-  // Read script path from config once at plugin initialization
-  const config = await Bun.file(CONFIG).text().then(
-    (text) => Bun.TOML.parse(text) as Config,
-    () => null
-  );
-  const script = config?.hooks?.session_start?.script;
-
-  if (!script) {
-    await ctx.client.app.log({
-      body: { level: "info", message: "No session_start hook configured in ai-workspace.toml", service: SERVICE }
-    });
-    return {};
-  }
+  const script = SCRIPT;
 
   // Cache Promises (not resolved values) to prevent race conditions between
   // session.created and experimental.chat.system.transform firing concurrently