Update ai context

Update AI Context — CLAUDE.md, AGENTS.md, Patterns & Rules

You are a Senior Software Engineer managing AI-assisted development documentation. Your task is to create or update:

1. CLAUDE.md files — hierarchical source-of-truth documentation for the project
2. AGENTS.md files — generated mirrors of sibling CLAUDE.md files for Codex
3. ./absolutpowers/patterns.md — discovered code patterns and conventions
4. ./absolutpowers/rules.md — project rules for code review compliance

Mode Detection

Check what exists in the project:

• No CLAUDE.md → Bootstrap mode (create everything from scratch)
• CLAUDE.md exists → Update mode (audit and refresh)

Create ./absolutpowers/ directory if it doesn't exist.

---

PHASE 1: CLAUDE.md Source Files (Bootstrap or Update)

Bootstrap (no existing CLAUDE.md)

Step 1: Analyze Project Structure

Scan the codebase to understand:

• Tech stack: Languages, frameworks, key libraries
• Architecture pattern: Monolith, microservices, modular monolith, etc.
• Package/module structure: How code is organized
• Domain boundaries: Logical separations (features, domains, layers)
• Shared code: Utils, helpers, common types
• Configuration: How settings are managed
• Testing setup: Patterns, locations, utilities
• Verification commands: How the project builds, tests, type-checks, lints, and runs formatter checks

Step 2: Identify CLAUDE.md Locations

Place CLAUDE.md files at meaningful boundaries:

Good locations:

• Project root (always)
• Feature/domain packages (src/orders/, src/payments/)
• Major architectural layers if distinct (src/api/, src/core/)
• Shared utilities (src/shared/, src/common/)
• Complex subsystems that need explanation

Avoid:

• Every single folder (too granular)
• Folders with only 1-2 simple files
• Test folders (unless complex test utilities)
• Generated code folders

Step 3: Create Root CLAUDE.md

# [Project Name]

## Stack
- **Language:** [language + version]
- **Framework:** [framework]
- **Database:** [database]
- **Key libraries:** [list main ones]

## Architecture
[2-3 sentences describing overall architecture pattern]

## Project Structure

src/ ├── [package]/ # [one-line description] ├── [package]/ # [one-line description] └── shared/ # [one-line description]

## Conventions
- **Files:** [naming convention]
- **Functions/Methods:** [naming convention]
- **Tests:** [location pattern, naming]

## Key Patterns
- [Pattern]: [one-line description]

## Getting Started
- Build: `[command]`
- Test: `[command]`
- Run: `[command]`

## Verification Commands
- Backend build/test: `[command]`
- Frontend build/typecheck: `[command]`
- Lint: `[command]`
- Formatter check: `[command]`

## AI Documentation

This project uses hierarchical AI context shared across Claude Code and Codex.
- `CLAUDE.md`: editable source of truth for this directory scope
- `AGENTS.md`: generated mirror for Codex in the same directory scope
- `./absolutpowers/patterns.md`: discovered code patterns
- `./absolutpowers/rules.md`: project rules for code review

Run the `update-ai-context` skill to refresh documentation and sync mirrors.

Step 4: Create Package CLAUDE.md Files

For each identified package/module:

# [Package Name]

## Purpose
[2-3 sentences: what this package does, its responsibility]

## Key Concepts
- **[Concept]:** [brief explanation]

## Main Components
| File | Responsibility |
|------|----------------|
| `ServiceName.ts` | [what it does] |

## Dependencies
- **Internal:** [which other packages this depends on]
- **External:** [key external libraries used here]

## Patterns Used
- [Pattern]: [how it's applied here]

## Important Rules
- [Business rule or constraint]

## Last Verified
- **Date:** YYYY-MM-DD
- **Commit:** [short hash]

Update (CLAUDE.md exists)

1. Find all existing CLAUDE.md files, note location and last modified date
2. Detect drift: files that no longer exist, renamed packages, changed dependencies, shifted commands
3. Detect gaps: new folders with 3+ files lacking CLAUDE.md, new major dependencies
4. Update existing CLAUDE.md files — preserve structure, fix inaccuracies, add new components
5. Create missing CLAUDE.md files where warranted
6. Update ## Last Verified sections
7. After all CLAUDE.md edits, refresh sibling AGENTS.md mirrors

---

PHASE 2: Patterns Discovery → ./absolutpowers/patterns.md

Scan the entire codebase for recurring patterns. This file is read by generate-tasks and implement skills to ensure new code follows established conventions.

What to look for:

• Structural patterns: Repository, Service, Factory, Controller, etc.
• Custom abstractions: Result types, Either monads, custom hooks, base classes
• Error handling: Exception hierarchy, error response format, logging approach
• Data validation: Schema validation, input sanitization, guard clauses
• API conventions: Response format, pagination, error codes, auth patterns
• Testing patterns: Fixtures, mocks, builders, test utilities, naming
• Configuration: Env vars, config files, feature flags
• Verification commands: build, typecheck, lint, formatter checks, project wrappers
• Naming conventions: Files, functions, variables, constants (what is ACTUALLY followed)

Pattern must have proof

Only document patterns used 3+ times in the codebase. Each pattern MUST include a concrete code reference.

Format for ./absolutpowers/patterns.md:

# Project Patterns

> Auto-generated by `/absolutpowers:update-ai-context` on YYYY-MM-DD.
> Read by `generate-tasks` and `implement` skills.

## Structural Patterns

### [Pattern Name]
**What:** [one-line description]
**Where:** [which layer/packages use this]
**Example:** `path/to/file.ts:L15-45`
**Convention:**
- [specific rule 1]
- [specific rule 2]

## Error Handling

### [Pattern Name]
**What:** [description]
**Example:** `path/to/file.ts:L10-30`
**Convention:**
- [rules]

## Testing

### [Pattern Name]
**What:** [description]
**Example:** `path/to/test.ts:L5-25`
**Convention:**
- [rules]

## Naming Conventions

| What | Convention | Example |
|------|-----------|---------|
| Files | [convention] | `user-service.ts` |
| Components | [convention] | `UserProfile.tsx` |
| Tests | [convention] | `user-service.spec.ts` |

Update mode

If ./absolutpowers/patterns.md already exists:

• Check if documented patterns still exist in code (remove dead ones)
• Discover new patterns that emerged since last scan
• Update code references if files moved
• Mark file with new scan date

---

PHASE 3: Rules → ./absolutpowers/rules.md

Rules are prescriptive constraints used by /absolutpowers:review during code review (Phase 3: Rules Check).

Bootstrap (no ./absolutpowers/rules.md)

Based on patterns discovered in Phase 2 and project analysis, propose a draft rules file. Present the proposed rules to the user and ask for confirmation before saving.

# Project Rules

> Used by `/absolutpowers:review` for automated rules checking.
> Last updated: YYYY-MM-DD

## Required Libraries
- [library]: used for [purpose] (not [alternative])

## Forbidden Patterns
- [pattern]: [why it's forbidden]

## Architecture
- [rule]: [description]

## Conventions
- [rule]: [description]

## Testing
- [rule]: [description]

Tell the user: "Proponuję następujące rules na bazie analizy kodu — przejrzyj i powiedz co zmienić."

Update (./absolutpowers/rules.md exists)

1. Read existing rules
2. Compare against current codebase — are any rules systematically violated? (might be outdated)
3. Are there new conventions not yet captured as rules?
4. Report findings but do not auto-modify — rules require human approval
5. Propose additions/removals and ask for confirmation

Demarcation: rules.md vs constitution.md

This phase produces only mechanical lint-level rules in rules.md (formatting, naming, forbidden patterns, required libraries). Pryncypia (osąd, wartości, granice projektu) belong in absolutpowers/constitution.md via the constitution skill.

Konstytucja = pryncypia/osąd. Mechanika = rules.md / update-ai-context.

When a proposed rule is really a principle (e.g., "always prefer readability over cleverness"), redirect it to the constitution skill instead of adding it here. A proposed mechanical rule MAY reference an existing Artykuł it derives from (e.g., "Rule: max 80 chars per line — per Artykuł 3 Norma"), but do NOT auto-generate rules from constitution articles.

---

PHASE 4: Sync Mirrored AGENTS.md Files

After all CLAUDE.md edits are complete, create or update a sibling AGENTS.md for every CLAUDE.md in scope.

Rules for the mirror:

• CLAUDE.md is the editable source of truth
• AGENTS.md must live in the same directory as its sibling CLAUDE.md
• Keep scope identical: root-to-subtree and package-level mirrors stay aligned 1:1
• Mirror the content faithfully; only an autogenerated banner is allowed in AGENTS.md
• If a CLAUDE.md file is deleted because the package no longer exists, remove the stale sibling AGENTS.md too

If a bundled helper script is available, prefer using it to refresh the mirrors for the target project. Otherwise perform the mirroring directly.

---

PHASE 5: Change Report

Output a summary of ALL changes across all areas:

## AI Context Update Report

### CLAUDE.md Changes
| File | Action | Details |
|------|--------|---------|
| `CLAUDE.md` | updated | Updated stack, added 2 patterns |
| `src/payments/CLAUDE.md` | created | New payment processing module |

### AGENTS.md Sync
- **Mirrored files updated:** [count]
- **Mirrored files created:** [count]
- **Mirrored files removed:** [count]

### Patterns (./absolutpowers/patterns.md)
- **New patterns found:** [count]
- **Removed (dead) patterns:** [count]
- **Updated references:** [count]

### Rules (./absolutpowers/rules.md)
- **Status:** [created draft / no changes / proposed updates]
- **Proposed additions:** [list if any]
- **Potentially outdated:** [list if any]

### Requires Manual Review
- [ ] [items needing human decision]

---

Guidelines

Content principles:

• Write for AI agents, not humans - be factual and precise
• Focus on WHAT and WHERE, less on WHY
• Include concrete file names and paths
• Patterns need proof — link to real code, not assumptions
• Rules need human approval — propose, don't impose

Size guidelines:

• Root CLAUDE.md: 50-100 lines
• Package CLAUDE.md: 30-60 lines
• patterns.md: as long as needed, but each pattern stays concise
• rules.md: focused, actionable constraints

Conflict resolution:

1. Code wins — update documentation to match reality
2. Note oddities — if code seems wrong, flag it but document actual behavior
3. Don't assume intent — describe what IS, not what SHOULD BE

---

Begin

1. Check what exists → determine mode per area
2. Analyze project structure
3. Phase 1: Bootstrap or update CLAUDE.md files
4. Phase 2: Discover and save patterns
5. Phase 3: Propose or audit rules
6. Phase 4: Sync mirrored AGENTS.md files
7. Phase 5: Output change report