How to integrate and use impeccable

Jun 10, 2026

How to integrate and use impeccable

Actually, it’s nothing special—just integrating a design tool into the HagiCode project,勉强算是个完整方案吧—including repository structure, multilingual workflows, content maintenance, and more, all gradually explored through practice.

Background

Speaking of UI/UX design quality in software development, it’s actually quite important, as it directly determines the product’s user experience and commercial success. However, in traditional development workflows, there’s always an invisible wall between designers and developers: designers create beautiful static mockups, developers strive to implement them, but there are always some discrepancies in details. This separation makes it difficult for the final product to fully match the design vision, and iteration costs rise accordingly.

When HagiCode project was working on desktop applications and Web products, it also needed professional UI/UX design support, while requiring close collaboration between design and code implementation. For this reason, we introduced the impeccable tool—a professional AI-driven front-end interface design and optimization tool. impeccable not only provides design guidance but can also directly handle code implementation, filling some of the gap between design and development.

To enable effective integration and use of impeccable in the HagiCode monorepo, we need to establish standardized integration methods, documentation processes, and maintenance specifications. This includes tool installation and configuration, skill integration, documentation site construction, and best practices for team collaboration.

About HagiCode

The solution shared in this article comes from our practical experience in the HagiCode project. HagiCode is an AI code assistant project that provides both Web and desktop versions, helping developers improve coding efficiency. During development, we needed high-quality design tools to support the product’s UI/UX construction, and impeccable was introduced into the project under this background.

Technical Architecture Analysis

impeccable’s skill-driven design

impeccable adopts a skill-driven design architecture, defining the context and behavior of different design tasks through standardized skill files. In the HagiCode project, impeccable is integrated as an npm skill package, mainly used in the following ways:

1. Skill file structure: /home/newbe36524/.agents/skills/impeccable/SKILL.md defines the complete skill configuration, including command sets, tool permissions, parameter hints, and license information.

2. Command classification system: impeccable divides design tasks into six major categories:

   • Build: Build-type commands (craft, shape, teach, document, extract)
   • Evaluate: Evaluation-type commands (critique, audit)
   • Refine: Optimization-type commands (polish, bolder, quieter, distill, harden, onboard)
   • Enhance: Enhancement-type commands (animate, colorize, typeset, layout, delight, overdrive)
   • Fix: Fix-type commands (clarify, adapt, optimize)
   • Iterate: Iteration-type commands (live)

Documentation site requirements analysis

To support team use of impeccable, HagiCode established an independent documentation site impeccable-site, which needs to meet the following requirements:

• Multilingual support: Provide complete documentation in English and Chinese to meet international team needs
• Command catalog: Unified display of all commands, including categories, descriptions, and reference links
• Localized content: Maintain HagiCode-specific usage guides and best practices
• Static generation: Use Astro to build static sites for easy deployment and access

Integration challenges

The following challenges were faced during integration:

1. Source code synchronization: The upstream impeccable repository contains complete tool code and documentation, but requires selective integration of the documentation portion to avoid depending on the entire tool codebase

2. Content maintenance: Need to maintain localized content and usage guides while keeping upstream updates synchronized

3. Build process: Establish automated content synchronization, catalog generation, and site build processes

4. Multilingual workflow: Design efficient translation and localization maintenance processes

Solution Design

Repository structure design

Integrate the upstream impeccable repository through Git submodule mechanism:

[submodule "vendor/impeccable"]
    path = vendor/impeccable
    url = https://github.com/pbakaus/impeccable.git

The advantages of this design include:

• Version control: Can precisely control upstream versions, avoiding problems caused by accidental updates
• Lightweight integration: Only fetch needed source code, avoiding introducing unnecessary dependencies
• Flexible updates: Can selectively update upstream content

Content model design

Adopt a layered content model:

1. Upstream source code: vendor/impeccable/ - Provides original command definitions and reference documentation
2. Localized content: src/content/commands/ - Maintains Chinese and English command descriptions
3. Shared UI copy: src/i18n/locales/ - Manages multilingual text for the site interface
4. Generated catalog: src/lib/generated/command-catalog.json - Command catalog generated at build time

Build process optimization

Design an automated build process, integrating each step through npm scripts:

{
  "scripts": {
    "prepare": "npm run i18n:generate && npm run catalog:generate",
    "i18n:generate": "node scripts/generate-i18n-resources.mjs",
    "catalog:generate": "node scripts/build-command-catalog.mjs",
    "content:sync:vendor": "node scripts/sync-vendor-command-content.mjs",
    "validate": "npm run i18n:check && npm run catalog:check && npm run typecheck && npm run test && npm run build"
  }
}

The build process is divided into four stages:

1. Preparation stage: Generate multilingual resources and command catalog
2. Content synchronization: Synchronize command content from upstream to local
3. Validation stage: Check content integrity and build correctness
4. Build output: Generate static site files

Multilingual workflow

Establish a standardized multilingual workflow based on the hagi18n toolchain:

localesRoot: src/i18n/locales
repoRoot: .
baseLocale: en-US
targetLocales:
  - zh-CN

Provide complete maintenance scripts:

• i18n:audit - Check translation completeness
• i18n:sync - Synchronize translation entries
• i18n:prune - Clean up outdated translations
• i18n:doctor - Diagnose translation issues

Practice Guide

Initial setup

First initialize the submodule and install dependencies:

# Enter monorepo root directory
cd /home/newbe36524/repos/hagicode-mono

# Initialize submodule
git submodule update --init --recursive

# Enter impeccable-site directory
cd repos/impeccable-site

# Install dependencies
env -u NPM_CONFIG_PREFIX npm install

This step is the foundation of the entire integration process. If submodule initialization fails, all subsequent steps cannot proceed. HagiCode encountered this problem during the first integration and later clarified the initialization steps in the documentation.

Daily development workflow

Execute daily development commands in the repos/impeccable-site directory:

# Start development server
env -u NPM_CONFIG_PREFIX npm run dev

# Type checking
env -u NPM_CONFIG_PREFIX npm run typecheck

# Run tests
env -u NPM_CONFIG_PREFIX npm test

# Build site
env -u NPM_CONFIG_PREFIX npm run build

# Complete validation
env -u NPM_CONFIG_PREFIX npm run validate

The development server runs by default at http://localhost:31266, and the port can be customized through the environment variable PORT_IMPECCABLE_SITE. HagiCode team members discovered during development that when frequently switching between different language environments, using a unified prefix command can avoid environment variable pollution issues.

Content maintenance strategy

When adding or updating command documentation, you need to create corresponding files in two language directories:

# English command documentation
src/content/commands/en-US/polish.mdx

# Chinese command documentation
src/content/commands/zh-CN/polish.mdx

Each MDX file needs to contain frontmatter metadata:

---
title: "Polish"
slug: "polish"
seoTitle: "Polish Command - Impeccable"
seoDescription: "Final quality pass before shipping with impeccable polish command"
routeSlug: "polish"
highlights:
  - "Visual hierarchy review"
  - "Spacing and typography optimization"
  - "Accessibility validation"
related:
  - "audit"
  - "critique"
---

Upstream content synchronization

When upstream impeccable updates, you need to synchronize the latest command content:

# Update submodule
cd /home/newbe36524/repos/hagicode-mono/repos/impeccable-site
git submodule update --remote vendor/impeccable

# Synchronize command content
env -u NPM_CONFIG_PREFIX npm run content:sync:vendor

# Synchronize single command
env -u NPM_CONFIG_PREFIX node scripts/sync-vendor-command-content.mjs --slug polish

# Regenerate catalog
env -u NPM_CONFIG_PREFIX npm run catalog:generate

The synchronization script reads upstream command content from vendor/impeccable/site/content/skills/ and copies it to the src/content/commands/en-US/ directory. The HagiCode team discovered in practice that after each synchronization, the command catalog needs to be regenerated, otherwise content inconsistency issues will occur.

Multilingual maintenance

Maintain multilingual text for the site interface:

# Check translation completeness
env -u NPM_CONFIG_PREFIX npm run i18n:audit

# Synchronize translation entries
env -u NPM_CONFIG_PREFIX npm run i18n:sync

# Clean up outdated translations
env -u NPM_CONFIG_PREFIX npm run i18n:prune

# Diagnose translation issues
env -u NPM_CONFIG_PREFIX npm run i18n:doctor

Translation files are located in the src/i18n/locales/ directory:

src/i18n/locales/
├── en-US/
│   ├── common.yml
│   └── docs.yml
└── zh-CN/
    ├── common.yml
    └── docs.yml

YAML file example:

src/i18n/locales/en-US/docs.yml

commands:
  title: "Commands"
  subtitle: "Explore the complete command surface"
  overview: "Overview"
  related: "Related Commands"

# src/i18n/locales/zh-CN/docs.yml
commands:
  title: "命令"
  subtitle: "探索完整的命令集"
  overview: "概览"
  related: "相关命令"

Using impeccable commands

In the HagiCode project, you can call impeccable commands in the following ways:

# Design new features
npx impeccable craft "user settings page"

# Plan UI/UX
npx impeccable shape "checkout flow"

# Set project context
npx impeccable teach

# Generate design documentation
npx impeccable document

# Review design quality
npx impeccable critique "landing page"

# Technical quality check
npx impeccable audit "navigation component"

# Final optimization
npx impeccable polish "onboarding flow"

# Real-time iterative design
npx impeccable live

Each command has specific purposes and reference documentation. For example, the craft command is used for end-to-end feature building, including UX/UI planning and code implementation; the audit command is used for technical quality checking, including accessibility, performance, and responsive design. In the HagiCode team’s development process, these commands have become part of the daily development workflow.

Deployment validation

Perform complete validation before deployment:

# Run complete validation process
env -u NPM_CONFIG_PREFIX npm run validate

The validation process will check:

• Whether the vendor path is correct
• All commands have corresponding content in both Chinese and English directories
• Generated multilingual resources are up to date
• Command catalog is up to date
• Astro routes compile correctly
• Static output builds successfully

Important Notes and Best Practices

Important notes

1. Submodule updates: After updating the submodule, you need to regenerate derived resources and commit. The HagiCode team once encountered a situation where they committed directly without regenerating resources, causing content inconsistency issues on the production site.

2. Language equivalence: Ensure all commands have corresponding content in both Chinese and English directories, otherwise the build will fail. This check has been integrated into the validation process, allowing issues to be discovered early in development.

3. Frontend proxy: impeccable-site is proxied through the static site development script in the monorepo root directory:

# Start from monorepo root directory
npm run dev:static-sites

4. Production deployment: The production site is deployed to https://impeccable.hagicode.com, automated through GitHub Actions. HagiCode adopts a fully automated CI/CD process to ensure each commit is automatically deployed.

5. Command documentation links: When selecting an impeccable command in the Web frontend’s UI Master, the corresponding documentation link will be displayed, with the link format:

https://impeccable.hagicode.com/{lang}/commands/{command-name}

Best practices summary

1. Regularly synchronize upstream: Pay attention to upstream impeccable updates and regularly synchronize new commands and improvements. The HagiCode team adopts a weekly synchronization frequency to ensure important updates are not missed.

2. Maintain localized content: After synchronizing upstream content, update Chinese and English documentation in a timely manner to ensure content accuracy and timeliness.

3. Version control: After submodule updates, verify build results before committing to the version control system.

4. Team collaboration: Support team members in collaboratively maintaining documentation content through standardized multilingual workflows.

5. Quality assurance: Run complete validation processes after each content update to ensure site correctness.

6. Command classification usage: Choose appropriate command categories based on different stages of design tasks:

   • Use craft or shape when designing new features
   • Use critique or audit when reviewing existing designs
   • Use polish, bolder, or quieter when optimizing design quality
   • Use animate, colorize, or delight when enhancing visual effects
   • Use clarify, adapt, or optimize when fixing issues
   • Use live for real-time iteration

7. Context management: Before using the craft command, ensure that the project’s PRODUCT.md and DESIGN.md context files have been set up through the teach command.

Summary

Through the above integration and usage methods, the HagiCode project can effectively leverage impeccable’s professional design capabilities to improve product UI/UX quality, while establishing standardized documentation maintenance processes to support long-term team collaboration and development.

The solution shared in this article was optimized through multiple iterations in HagiCode’s actual development. It not only solved the design-development collaboration problem but also established an extensible documentation system, providing a reference for integrating other tools.

If you also face similar design-development collaboration issues in your team, I hope the practices in this article provide you with some inspiration. The core idea of this solution is: establish standardized processes, maintain synchronization with upstream, focus on localized maintenance, and support team collaboration.

Summary

Regarding “how to integrate and use impeccable,” a more prudent approach is to gradually get the key configurations, dependency boundaries, and implementation paths working first, then fill in the optimization details.

When goals, steps, and acceptance criteria are clearly defined, such solutions can usually proceed more smoothly into actual delivery.

Tags:

• impeccable
• design
• integration
• workflow

How Electron Desktop Apps Integrate Microsoft Store Subscription and Perpetual Licenses

From Zero: How to Integrate Reasonix CLI into HagiCode System