How to Optimize Performance with Arc-Kit: Enterprise Architecture Tuning Guide

Optimize performance with Arc-Kit by keeping context-injection hooks synchronous, delegating research-heavy commands to autonomous agents, using the Write tool for large artefacts, and enabling lazy loading for generated documentation sites.

ArcKit is an open-source framework designed to help architects generate and manage large-scale enterprise architecture artefacts while maintaining responsive interactive sessions. As implemented in the tractorjuice/arc-kit repository, the toolkit provides specific architectural patterns to prevent latency and token-limit issues during heavy workloads.

Core Runtime – Synchronous Hook Design

The foundation of ArcKit performance lies in its hook system, which injects project context via SessionStart and UserPromptSubmit hooks that run on every incoming message. According to the ArcKit source code in README.md (lines 1190-1194), the arckit-context.mjs hook must be synchronous because the command needs the project inventory in the same turn.

Why Async Hooks Fail for Context Injection

When hooks are marked async: true, they execute in the background and cannot inject context into the current response. This architectural constraint was discovered in version 2.21.2 when context injection silently stopped working after switching to async. Synchronous execution ensures the inventory data is available immediately without blocking subsequent operations.

Lightweight Hook Implementation

Keep the context-injection hook minimal by reading only small JSON files. Move any heavyweight work—such as scanning large directories or network calls—to a separate async hook or an autonomous agent.

// .arckit/hooks/arckit-context.mjs
export default async function(context) {
  // Fast, synchronous read of the project inventory
  const inventory = await readJSON('.arckit/project-inventory.json');
  return { inventory };
}

Limit the matcher scope to avoid overhead. A global .* matcher adds approximately 30 seconds of overhead per message, whereas command-specific matchers run significantly faster.

Command Execution – Agents and Write Tool

Heavy computational work should never block the interactive session. ArcKit isolates expensive operations through autonomous agents and prevents token-limit stalls using the Write tool.

Delegate Research-Heavy Commands to Agents

Commands that trigger more than 10 WebSearch or WebFetch calls—such as /arckit.research, /arckit.datascout, or comprehensive requirements gathering—should be implemented as thin wrappers that launch autonomous agents via the Task tool. As documented in CLAUDE.md in the Agent System section, agents run in their own subprocess, isolating the main session from network traffic and latency.

---
name: arckit-requirements
description: Generate comprehensive requirements
---

You are a requirements-generation assistant.  
If the command mentions "Launch the agent" or references the Task tool, defer to the agent defined in `arckit-claude/agents/arckit-requirements.md`.  
Otherwise, read the template and write the output with the Write tool.

The corresponding agent file in arckit-claude/agents/arckit-requirements.md contains all the web calls and heavy processing, keeping the main conversation responsive.

Use the Write Tool for Large Artefacts

When generating substantial documents like full requirements specifications, always use the Write tool rather than returning content as model output. According to CLAUDE.md in the Adding a New Slash Command section, this approach avoids the 32 KB token limit and prevents response stalls.

tool: Write
path: projects/001-my-project/ARC-001-REQ-v1.0.md
content: |
  <filled-template-content>

After writing the file, return only a brief summary to the user, such as "Requirements document written to ARC-001-REQ-v1.0.md".

Content Delivery – Lazy Loading and Caching

The documentation generated by ArcKit can be served as a static site using the /arckit.pages command. Performance at this layer depends on lazy loading strategies and asset caching.

Enable Lazy Loading for Documentation

As documented in docs/guides/pages.md at line 222, the static site employs lazy loading so that large markdown files are fetched only when the user navigates to them. This significantly reduces initial page weight.

Generate the site with:

/arckit.pages

The resulting docs/index.html includes JavaScript that requests individual artefacts on demand rather than loading everything upfront.

Cache Static Assets

All scripts in .arckit/scripts/bash/ are pure Bash utilities copied during arckit init. Because they are small and deterministic, the OS caches them automatically. For larger generated artefacts, store them on disk using the Write tool and serve them via the static site only when requested.

Performance Templates and NFRs

ArcKit embeds performance considerations directly into its templates, ensuring architects define measurable targets early in the process.

Requirements Template Performance Fields

The arckit-paperclip/templates/requirements-template.md at line 214 contains a specific placeholder: "Requirement: [Specific performance metric]". This forces explicit definition of performance requirements during the architecture phase.

Evaluation Criteria for Scalability

The arckit-paperclip/templates/evaluation-criteria-template.md at line 172 includes "1.3 Scalability & Performance – Does solution meet performance requirements? ..." This ensures performance is scored during option evaluation.

Fill these fields with concrete numbers (e.g., "99.9% request latency < 200 ms under 5k RPS") so downstream agents can automatically verify them during testing phases.

Role-Based Performance Guidance

ArcKit includes role-specific guides that assign performance responsibilities to specific stakeholders.

Technical Architect Responsibilities

According to docs/guides/roles/technical-architect.md at line 26, technical architects must "Review NFR requirements (performance, scalability, availability) – /arckit.requirements." This ensures performance is checked during requirements gathering.

Performance Analyst Integration

The docs/guides/roles/performance-analyst.md at line 29 instructs analysts to "Provide performance data for service assessments – /arckit.service-assessment." This creates a feedback loop where real performance data informs architecture decisions.

Use these role guides to ensure the right stakeholder supplies performance numbers early, avoiding later rework.

Summary

• Keep the context-injection hook (arckit-context.mjs) synchronous to avoid blocking the main turn, as required by the ArcKit runtime in README.md lines 1190-1194.
• Delegate research-heavy commands (those with >10 web calls) to autonomous agents via the Task tool, isolating network latency from the interactive session.
• Use the Write tool for large artefacts to avoid the 32 KB token limit and prevent response stalls.
• Enable lazy loading in generated documentation sites using /arckit.pages, fetching large markdown files only on demand as documented in docs/guides/pages.md line 222.
• Define concrete performance NFRs early using the placeholders in requirements-template.md line 214 and evaluation-criteria-template.md line 172.
• Follow role-specific guidance in technical-architect.md and performance-analyst.md to ensure performance data is collected and reviewed at the correct stages.

Frequently Asked Questions

Why must the arckit-context.mjs hook be synchronous?

According to the ArcKit source code in README.md lines 1190-1194, the context-injection hook must be synchronous because the command needs the project inventory data in the same turn. When hooks are marked async: true, they execute in the background and cannot inject context into the current response, which caused context injection to silently fail in version 2.21.2.

How do I handle commands that need to search the web multiple times?

Commands that trigger more than 10 WebSearch or WebFetch calls should be implemented as thin wrappers that launch autonomous agents via the Task tool. As documented in CLAUDE.md, these agents run in their own subprocess, isolating the main interactive session from network latency and heavy computation. The agent files are located in arckit-claude/agents/.

What is the Write tool and when should I use it?

The Write tool is a native capability that writes content directly to disk rather than returning it as model output. According to CLAUDE.md, you should use it when generating large artefacts like full requirements specifications to avoid hitting the 32 KB token limit and causing response stalls. Always return only a brief summary to the user after writing the file.

How does lazy loading work in ArcKit documentation?

When you run /arckit.pages, ArcKit generates a static documentation site that employs lazy loading for large markdown files. As documented in docs/guides/pages.md line 222, JavaScript in the generated docs/index.html fetches individual artefacts only when the user navigates to them, reducing initial page weight and improving load times.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}