compact-agent 1.10.1 → 1.11.0

package/resources/ecc/commands/test-coverage.md

@@ -0,0 +1,73 @@
+---
+description: Analyze coverage, identify gaps, and generate missing tests toward the target threshold.
+---
+
+# Test Coverage
+
+Analyze test coverage, identify gaps, and generate missing tests to reach 80%+ coverage.
+
+## Step 1: Detect Test Framework
+
+| Indicator | Coverage Command |
+|-----------|-----------------|
+| `jest.config.*` or `package.json` jest | `npx jest --coverage --coverageReporters=json-summary` |
+| `vitest.config.*` | `npx vitest run --coverage` |
+| `pytest.ini` / `pyproject.toml` pytest | `pytest --cov=src --cov-report=json` |
+| `Cargo.toml` | `cargo llvm-cov --json` |
+| `pom.xml` with JaCoCo | `mvn test jacoco:report` |
+| `go.mod` | `go test -coverprofile=coverage.out ./...` |
+
+## Step 2: Analyze Coverage Report
+
+1. Run the coverage command
+2. Parse the output (JSON summary or terminal output)
+3. List files **below 80% coverage**, sorted worst-first
+4. For each under-covered file, identify:
+   - Untested functions or methods
+   - Missing branch coverage (if/else, switch, error paths)
+   - Dead code that inflates the denominator
+
+## Step 3: Generate Missing Tests
+
+For each under-covered file, generate tests following this priority:
+
+1. **Happy path** — Core functionality with valid inputs
+2. **Error handling** — Invalid inputs, missing data, network failures
+3. **Edge cases** — Empty arrays, null/undefined, boundary values (0, -1, MAX_INT)
+4. **Branch coverage** — Each if/else, switch case, ternary
+
+### Test Generation Rules
+
+- Place tests adjacent to source: `foo.ts` → `foo.test.ts` (or project convention)
+- Use existing test patterns from the project (import style, assertion library, mocking approach)
+- Mock external dependencies (database, APIs, file system)
+- Each test should be independent — no shared mutable state between tests
+- Name tests descriptively: `test_create_user_with_duplicate_email_returns_409`
+
+## Step 4: Verify
+
+1. Run the full test suite — all tests must pass
+2. Re-run coverage — verify improvement
+3. If still below 80%, repeat Step 3 for remaining gaps
+
+## Step 5: Report
+
+Show before/after comparison:
+
+```
+Coverage Report
+──────────────────────────────
+File                   Before  After
+src/services/auth.ts   45%     88%
+src/utils/validation.ts 32%    82%
+──────────────────────────────
+Overall:               67%     84%  PASS:
+```
+
+## Focus Areas
+
+- Functions with complex branching (high cyclomatic complexity)
+- Error handlers and catch blocks
+- Utility functions used across the codebase
+- API endpoint handlers (request → response flow)
+- Edge cases: null, undefined, empty string, empty array, zero, negative numbers

package/resources/ecc/commands/update-codemaps.md

@@ -0,0 +1,76 @@
+---
+description: Scan project structure and generate token-lean architecture codemaps.
+---
+
+# Update Codemaps
+
+Analyze the codebase structure and generate token-lean architecture documentation.
+
+## Step 1: Scan Project Structure
+
+1. Identify the project type (monorepo, single app, library, microservice)
+2. Find all source directories (src/, lib/, app/, packages/)
+3. Map entry points (main.ts, index.ts, app.py, main.go, etc.)
+
+## Step 2: Generate Codemaps
+
+Create or update codemaps in `docs/CODEMAPS/` (or `.reports/codemaps/`):
+
+| File | Contents |
+|------|----------|
+| `architecture.md` | High-level system diagram, service boundaries, data flow |
+| `backend.md` | API routes, middleware chain, service → repository mapping |
+| `frontend.md` | Page tree, component hierarchy, state management flow |
+| `data.md` | Database tables, relationships, migration history |
+| `dependencies.md` | External services, third-party integrations, shared libraries |
+
+### Codemap Format
+
+Each codemap should be token-lean — optimized for AI context consumption:
+
+```markdown
+# Backend Architecture
+
+## Routes
+POST /api/users → UserController.create → UserService.create → UserRepo.insert
+GET  /api/users/:id → UserController.get → UserService.findById → UserRepo.findById
+
+## Key Files
+src/services/user.ts (business logic, 120 lines)
+src/repos/user.ts (database access, 80 lines)
+
+## Dependencies
+- PostgreSQL (primary data store)
+- Redis (session cache, rate limiting)
+- Stripe (payment processing)
+```
+
+## Step 3: Diff Detection
+
+1. If previous codemaps exist, calculate the diff percentage
+2. If changes > 30%, show the diff and request user approval before overwriting
+3. If changes <= 30%, update in place
+
+## Step 4: Add Metadata
+
+Add a freshness header to each codemap:
+
+```markdown
+<!-- Generated: 2026-02-11 | Files scanned: 142 | Token estimate: ~800 -->
+```
+
+## Step 5: Save Analysis Report
+
+Write a summary to `.reports/codemap-diff.txt`:
+- Files added/removed/modified since last scan
+- New dependencies detected
+- Architecture changes (new routes, new services, etc.)
+- Staleness warnings for docs not updated in 90+ days
+
+## Tips
+
+- Focus on **high-level structure**, not implementation details
+- Prefer **file paths and function signatures** over full code blocks
+- Keep each codemap under **1000 tokens** for efficient context loading
+- Use ASCII diagrams for data flow instead of verbose descriptions
+- Run after major feature additions or refactoring sessions

package/resources/ecc/commands/update-docs.md

@@ -0,0 +1,88 @@
+---
+description: Sync documentation from source-of-truth files such as scripts, schemas, routes, and exports.
+---
+
+# Update Documentation
+
+Sync documentation with the codebase, generating from source-of-truth files.
+
+## Step 1: Identify Sources of Truth
+
+| Source | Generates |
+|--------|-----------|
+| `package.json` scripts | Available commands reference |
+| `.env.example` | Environment variable documentation |
+| `openapi.yaml` / route files | API endpoint reference |
+| Source code exports | Public API documentation |
+| `Dockerfile` / `docker-compose.yml` | Infrastructure setup docs |
+
+## Step 2: Generate Script Reference
+
+1. Read `package.json` (or `Makefile`, `Cargo.toml`, `pyproject.toml`)
+2. Extract all scripts/commands with their descriptions
+3. Generate a reference table:
+
+```markdown
+| Command | Description |
+|---------|-------------|
+| `npm run dev` | Start development server with hot reload |
+| `npm run build` | Production build with type checking |
+| `npm test` | Run test suite with coverage |
+```
+
+## Step 3: Generate Environment Documentation
+
+1. Read `.env.example` (or `.env.template`, `.env.sample`)
+2. Extract all variables with their purposes
+3. Categorize as required vs optional
+4. Document expected format and valid values
+
+```markdown
+| Variable | Required | Description | Example |
+|----------|----------|-------------|---------|
+| `DATABASE_URL` | Yes | PostgreSQL connection string | `postgres://user:pass@host:5432/db` |
+| `LOG_LEVEL` | No | Logging verbosity (default: info) | `debug`, `info`, `warn`, `error` |
+```
+
+## Step 4: Update Contributing Guide
+
+Generate or update `docs/CONTRIBUTING.md` with:
+- Development environment setup (prerequisites, install steps)
+- Available scripts and their purposes
+- Testing procedures (how to run, how to write new tests)
+- Code style enforcement (linter, formatter, pre-commit hooks)
+- PR submission checklist
+
+## Step 5: Update Runbook
+
+Generate or update `docs/RUNBOOK.md` with:
+- Deployment procedures (step-by-step)
+- Health check endpoints and monitoring
+- Common issues and their fixes
+- Rollback procedures
+- Alerting and escalation paths
+
+## Step 6: Staleness Check
+
+1. Find documentation files not modified in 90+ days
+2. Cross-reference with recent source code changes
+3. Flag potentially outdated docs for manual review
+
+## Step 7: Show Summary
+
+```
+Documentation Update
+──────────────────────────────
+Updated:  docs/CONTRIBUTING.md (scripts table)
+Updated:  docs/ENV.md (3 new variables)
+Flagged:  docs/DEPLOY.md (142 days stale)
+Skipped:  docs/API.md (no changes detected)
+──────────────────────────────
+```
+
+## Rules
+
+- **Single source of truth**: Always generate from code, never manually edit generated sections
+- **Preserve manual sections**: Only update generated sections; leave hand-written prose intact
+- **Mark generated content**: Use `<!-- AUTO-GENERATED -->` markers around generated sections
+- **Don't create docs unprompted**: Only create new doc files if the command explicitly requests it

package/resources/ecc/rules/README.md

@@ -0,0 +1,120 @@
+# Rules
+## Structure
+
+Rules are organized into a **common** layer plus **language-specific** directories:
+
+```
+rules/
+├── common/          # Language-agnostic principles (always install)
+│   ├── coding-style.md
+│   ├── git-workflow.md
+│   ├── testing.md
+│   ├── performance.md
+│   ├── patterns.md
+│   ├── hooks.md
+│   ├── agents.md
+│   └── security.md
+├── typescript/      # TypeScript/JavaScript specific
+├── angular/         # Angular specific
+├── python/          # Python specific
+├── golang/          # Go specific
+├── web/             # Web and frontend specific
+├── swift/           # Swift specific
+├── php/             # PHP specific
+├── ruby/            # Ruby / Rails specific
+└── arkts/           # HarmonyOS / ArkTS specific
+```
+
+- **common/** contains universal principles — no language-specific code examples.
+- **Language directories** extend the common rules with framework-specific patterns, tools, and code examples. Each file references its common counterpart.
+
+## Installation
+
+### Option 1: Install Script (Recommended)
+
+```bash
+# Install common + one or more language-specific rule sets
+./install.sh typescript
+./install.sh angular
+./install.sh python
+./install.sh golang
+./install.sh web
+./install.sh swift
+./install.sh php
+./install.sh ruby
+./install.sh arkts
+
+# Install multiple languages at once
+./install.sh typescript python
+```
+
+### Option 2: Manual Installation
+
+> **Important:** Copy entire directories — do NOT flatten with `/*`.
+> Common and language-specific directories contain files with the same names.
+> Flattening them into one directory causes language-specific files to overwrite
+> common rules, and breaks the relative `../common/` references used by
+> language-specific files.
+
+```bash
+# Install common rules (required for all projects)
+cp -r rules/common ~/.claude/rules/common
+
+# Install language-specific rules based on your project's tech stack
+cp -r rules/typescript ~/.claude/rules/typescript
+cp -r rules/angular ~/.claude/rules/angular
+cp -r rules/python ~/.claude/rules/python
+cp -r rules/golang ~/.claude/rules/golang
+cp -r rules/web ~/.claude/rules/web
+cp -r rules/swift ~/.claude/rules/swift
+cp -r rules/php ~/.claude/rules/php
+cp -r rules/ruby ~/.claude/rules/ruby
+cp -r rules/arkts ~/.claude/rules/arkts
+
+# Attention ! ! ! Configure according to your actual project requirements; the configuration here is for reference only.
+```
+
+## Rules vs Skills
+
+- **Rules** define standards, conventions, and checklists that apply broadly (e.g., "80% test coverage", "no hardcoded secrets").
+- **Skills** (`skills/` directory) provide deep, actionable reference material for specific tasks (e.g., `python-patterns`, `golang-testing`).
+
+Language-specific rule files reference relevant skills where appropriate. Rules tell you *what* to do; skills tell you *how* to do it.
+
+## Adding a New Language
+
+To add support for a new language (e.g., `rust/`):
+
+1. Create a `rules/rust/` directory
+2. Add files that extend the common rules:
+   - `coding-style.md` — formatting tools, idioms, error handling patterns
+   - `testing.md` — test framework, coverage tools, test organization
+   - `patterns.md` — language-specific design patterns
+   - `hooks.md` — PostToolUse hooks for formatters, linters, type checkers
+   - `security.md` — secret management, security scanning tools
+3. Each file should start with:
+   ```
+   > This file extends [common/xxx.md](../common/xxx.md) with <Language> specific content.
+   ```
+4. Reference existing skills if available, or create new ones under `skills/`.
+
+For non-language domains like `web/`, follow the same layered pattern when there is enough reusable domain-specific guidance to justify a standalone ruleset.
+
+## Rule Priority
+
+When language-specific rules and common rules conflict, **language-specific rules take precedence** (specific overrides general). This follows the standard layered configuration pattern (similar to CSS specificity or `.gitignore` precedence).
+
+- `rules/common/` defines universal defaults applicable to all projects.
+- `rules/golang/`, `rules/python/`, `rules/swift/`, `rules/php/`, `rules/typescript/`, etc. override those defaults where language idioms differ.
+
+### Example
+
+`common/coding-style.md` recommends immutability as a default principle. A language-specific `golang/coding-style.md` can override this:
+
+> Idiomatic Go uses pointer receivers for struct mutation — see [common/coding-style.md](../common/coding-style.md) for the general principle, but Go-idiomatic mutation is preferred here.
+
+### Common rules with override notes
+
+Rules in `rules/common/` that may be overridden by language-specific files are marked with:
+
+> **Language note**: This rule may be overridden by language-specific rules for languages where this pattern is not idiomatic.

package/resources/ecc/rules/angular/coding-style.md

@@ -0,0 +1,182 @@
+---
+paths:
+  - "**/*.component.ts"
+  - "**/*.component.html"
+  - "**/*.service.ts"
+  - "**/*.directive.ts"
+  - "**/*.pipe.ts"
+  - "**/*.guard.ts"
+  - "**/*.resolver.ts"
+  - "**/*.module.ts"
+---
+# Angular Coding Style
+
+> This file extends [common/coding-style.md](../common/coding-style.md) with Angular specific content.
+
+## Version Awareness
+
+Always check the project's Angular version before writing code — features differ significantly between versions. Run `ng version` or inspect `package.json`. When creating a new project, do not pin a version unless the user specifies one.
+
+After generating or modifying Angular code, always run `ng build` to catch errors before finishing.
+
+## File Naming
+
+Follow Angular CLI conventions — one artifact per file:
+
+- `user-profile.component.ts` + `user-profile.component.html` + `user-profile.component.spec.ts`
+- `user.service.ts`, `auth.guard.ts`, `date-format.pipe.ts`
+- Feature folders: `features/users/`, `features/auth/`
+- Generate with the CLI: `ng generate component features/users/user-card`
+
+## Components
+
+Prefer standalone components (v17+ default). Use `OnPush` change detection on all new components.
+
+```typescript
+@Component({
+  selector: 'app-user-card',
+  standalone: true,
+  imports: [RouterModule],
+  templateUrl: './user-card.component.html',
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class UserCardComponent {
+  user = input.required<User>();
+  select = output<string>();
+}
+```
+
+## Dependency Injection
+
+Use `inject()` over constructor injection. Keep constructors empty or remove them entirely.
+
+```typescript
+// CORRECT
+@Injectable({ providedIn: 'root' })
+export class UserService {
+  private http = inject(HttpClient);
+  private router = inject(Router);
+}
+
+// WRONG: Constructor injection is verbose and harder to tree-shake
+constructor(private http: HttpClient, private router: Router) {}
+```
+
+Use `InjectionToken` for non-class dependencies:
+
+```typescript
+const API_URL = new InjectionToken<string>('API_URL');
+
+// Provide:
+{ provide: API_URL, useValue: 'https://api.example.com' }
+
+// Consume:
+private apiUrl = inject(API_URL);
+```
+
+## Signals
+
+### Core Primitives
+
+```typescript
+count = signal(0);
+doubled = computed(() => this.count() * 2);
+
+increment() {
+  this.count.update(n => n + 1);
+}
+```
+
+### `linkedSignal` — Writable Derived State
+
+Use `linkedSignal` when a signal must reset or adapt when a source changes, but also be independently writable:
+
+```typescript
+selectedOption = linkedSignal(() => this.options()[0]);
+// Resets to first option when options changes, but user can override
+```
+
+### `resource` — Async Data into Signals
+
+Use `resource()` to fetch async data reactively without manual subscriptions:
+
+```typescript
+userResource = resource({
+  request: () => ({ id: this.userId() }),
+  loader: ({ request }) => fetch(`/api/users/${request.id}`).then(r => r.json()),
+});
+
+// Access: userResource.value(), userResource.isLoading(), userResource.error()
+```
+
+### `effect` Usage
+
+Use `effect()` only for side effects that must react to signal changes (logging, third-party DOM manipulation). Never use effects to synchronize signals — use `computed` or `linkedSignal` instead. For DOM work after render, use `afterRenderEffect`.
+
+```typescript
+// CORRECT: Side effect
+effect(() => console.log('User changed:', this.user()));
+
+// WRONG: Use computed instead
+effect(() => { this.fullName.set(`${this.first()} ${this.last()}`); });
+```
+
+## Templates
+
+Use v17+ block syntax. Always provide `track` in `@for`:
+
+```html
+@for (item of items(); track item.id) {
+  <app-item [item]="item" />
+}
+
+@if (isLoading()) {
+  <app-spinner />
+} @else if (error()) {
+  <app-error [message]="error()" />
+} @else {
+  <app-content [data]="data()" />
+}
+```
+
+No logic in templates beyond simple conditionals — move to component methods or pipes.
+
+## Forms
+
+Choose the form strategy that matches the project's existing approach:
+
+- **Signal Forms** (v21+): Preferred for new projects on v21+. Signal-based form state.
+- **Reactive Forms**: `FormBuilder` + `FormGroup` + `FormControl`. Best for complex forms with dynamic validation.
+- **Template-Driven Forms**: `ngModel`. Suitable for simple forms only.
+
+```typescript
+// Reactive Forms — standard approach for most apps
+export class LoginComponent {
+  private fb = inject(FormBuilder);
+
+  form = this.fb.group({
+    email: ['', [Validators.required, Validators.email]],
+    password: ['', [Validators.required, Validators.minLength(8)]],
+  });
+
+  submit() {
+    if (this.form.valid) {
+      // use this.form.value
+    }
+  }
+}
+```
+
+## Component Styles
+
+Use component-level styles with `ViewEncapsulation.Emulated` (default). Avoid `ViewEncapsulation.None` unless building a design system that intentionally bleeds styles.
+
+- Scope styles to the component — do not use global class names inside component stylesheets
+- Use `:host` for host element styling
+- Prefer CSS custom properties for themeable values
+
+## Change Detection
+
+- Default to `ChangeDetectionStrategy.OnPush` on all new components
+- Signals and `async` pipe handle detection automatically — avoid `markForCheck()` and `detectChanges()`
+- Never mutate `@Input()` objects in place when using OnPush

package/resources/ecc/rules/angular/hooks.md

@@ -0,0 +1,25 @@
+---
+paths:
+  - "**/*.component.ts"
+  - "**/*.component.html"
+  - "**/*.service.ts"
+  - "**/*.directive.ts"
+  - "**/*.pipe.ts"
+  - "**/*.spec.ts"
+---
+# Angular Hooks
+
+> This file extends [common/hooks.md](../common/hooks.md) with Angular specific content.
+
+## PostToolUse Hooks
+
+Configure in `~/.claude/settings.json`:
+
+- **Prettier**: Auto-format `.ts` and `.html` files after edit
+- **ESLint / ng lint**: Run `ng lint` after editing Angular source files to catch decorator misuse, template errors, and style violations
+- **TypeScript check**: Run `tsc --noEmit` after editing `.ts` files
+- **Build check**: Run `ng build` after generating or significantly changing Angular code to catch template and type errors early
+
+## Stop Hooks
+
+- **Lint audit**: Run `ng lint` across modified files before session ends to catch any outstanding violations