@ivannikov-pro/ai-context-surgeon 1.0.0

package/bin/prompts.js

@@ -0,0 +1,371 @@
+#!/usr/bin/env node
+/** Category: Tool — Prompt Library for AI agents | EXPORTS: PROMPTS, listPrompts, getPrompt | DEPS: none */
+
+/**
+ * Each prompt is a self-contained instruction that an AI agent can request
+ * via `npx @ivannikov-pro/ai-context-surgeon prompt <task>`
+ * and immediately apply without reading full strategy docs.
+ *
+ * This saves ~500-2000 tokens per task vs reading full strategy files.
+ */
+
+export const PROMPTS = {
+  fnh: {
+    name: "File Navigation Header (FNH)",
+    description: "How to create an FNH header for any file",
+    prompt: `## Task: Add FNH Header to a File
+
+MANDATORY RULE: Every file MUST have a machine-readable identity descriptor on its FIRST line.
+
+### Format by File Type
+
+| Type | Line 1 Format | Example |
+|----|----|----|
+| .ts/.js | \`/** Category: Name — description | EXPORTS: ... | DEPS: ... */\` | \`/** Service: UserService — CRUD + auth | EXPORTS: create, getById | DEPS: prisma */\` |
+| .md | \`<!-- FNH: Category — description | SECTIONS: ... | DEPS: ... -->\` | \`<!-- FNH: Guide — API conventions | SECTIONS: Errors, Auth | DEPS: none -->\` |
+| .sh | Line 2 (after shebang): \`# Tool: name — description | DEPS: ...\` | \`# Tool: scan-fnh — repo map from headers | DEPS: none\` |
+| .py | \`# Category: Name — description | EXPORTS: ... | DEPS: ...\` | \`# Service: DataLoader — batch ETL | EXPORTS: load, transform | DEPS: pandas\` |
+| .css | \`/* Category: Name — description */\` | \`/* Styles: Dashboard — main layout + theme | SECTIONS: Layout, Cards, Nav */\` |
+| .yaml | \`# Config: Name — description\` | \`# Config: CI pipeline — build + test on push\` |
+| .sql | \`-- Migration: Name — description\` | \`-- Migration: 003_add_phone — adds phone column\` |
+
+### 5 Mandatory Layers
+
+1. **Category + Name + Purpose** — "Service: UserService — CRUD + auth"
+2. **Exports / Public API** — "EXPORTS: create, getById, update, delete"
+3. **Sections / Routes / Structure** — "ROUTES: GET /, POST /, DELETE /:id"
+4. **Dependencies** — "DEPS: prisma, bcrypt, @project/shared"
+5. **Gotchas** — "@throws Conflict | sends email | cached 60s"
+
+### Scaling by File Size
+
+| Size | Detail |
+|----|----|
+| <50 lines | All 5 layers in 1 line |
+| 50-150 lines | 2-3 lines |
+| 150-300 lines | 3-5 lines |
+| 300+ lines | 5-8 lines + SPLIT THE FILE |
+
+### Category Vocabulary
+
+Service, Route, Middleware, Controller, Repository, Entity, Types, Utility,
+Config, Schema, Hook, Component, Store, Factory, Adapter, Event, Guard,
+Constants, Test, Script, Migration, Barrel, Package, Guide, Role, Checklist,
+Knowledge, Architecture, Report, Skill
+
+### FNH Freshness Rule
+
+When you MODIFY a file, you MUST update its FNH:
+- ADD export/function → add to FNH
+- REMOVE export/function → remove from FNH
+- RENAME anything → update in FNH
+- A stale FNH is WORSE than no FNH`,
+  },
+
+  jsdoc: {
+    name: "JSDoc Annotation",
+    description: "How to write AI-optimized JSDoc headers",
+    prompt: `## Task: Annotate Files with AI-Optimized JSDoc
+
+CRITICAL RULE: Do NOT change any code logic. ONLY add/modify comments.
+
+### File Header (MANDATORY for every .ts/.js file)
+
+\`\`\`typescript
+/** Service: UserService — CRUD + auth for users | deps: prisma, bcrypt */
+\`\`\`
+
+### Function-Level JSDoc — ONLY for invisible information
+
+✅ DO annotate:
+- \`@throws {ErrorType}\` — every thrown error
+- \`@deprecated\` — with migration path  
+- \`@mutates\` — what state it changes
+- Side effects: "Sends email", "Writes to disk", "Clears cache"
+
+❌ DO NOT annotate (TypeScript says it already):
+- \`@param {type}\` in TypeScript files
+- \`@returns {type}\` in TypeScript files
+- \`@author\`, \`@since\`, \`@version\`, \`@fileoverview\`, \`@module\`
+
+### Example: Before → After
+
+BEFORE (220 tokens of noise):
+\`\`\`typescript
+/**
+ * @fileoverview User Service
+ * @author Jane Developer
+ * @since 2024-03-15
+ */
+export class UserService {
+  /** @param {CreateUserInput} input @returns {Promise<User>} */
+  async create(input: CreateUserInput): Promise<User> { ... }
+}
+\`\`\`
+
+AFTER (40 tokens — 82% reduction):
+\`\`\`typescript
+/** Service: UserService — CRUD + auth | deps: prisma, bcrypt */
+export class UserService {
+  /** @throws Conflict(email) | hashes pw bcrypt 12 | sends welcome email */
+  async create(input: CreateUserInput): Promise<User> { ... }
+}
+\`\`\`
+
+### JavaScript files (non-TypeScript): @param types ARE needed
+\`\`\`javascript
+/** @param {string} id @returns {Promise<User|null>} @throws {NotFoundError} */
+async function getUserById(id) { ... }
+\`\`\``,
+  },
+
+  readme: {
+    name: "Package README",
+    description: "How to write a README with Source Structure for AI agents",
+    prompt: `## Task: Create an AI-Optimized Package README
+
+### Structure Template
+
+\`\`\`markdown
+<!-- FNH: Package — @project/name description | EXPORTS: ... | DEPS: ... -->
+
+# @project/name
+
+> Package: description of what this package does
+> EXPORTS: key exports listed
+> DEPS: @project/shared, external-lib
+> SCRIPTS: dev, build, test, lint
+
+## Source Structure
+
+\\\`\\\`\\\`text
+src/
+  index.ts                    ← Public API (re-exports)
+  types.ts                    ← Type contracts
+  entities/
+    user.ts                   ← User entity (50 lines)
+    order.ts                  ← Order entity (40 lines)
+  services/
+    user.service.ts           ← User CRUD + auth (120 lines)
+    order.service.ts          ← Order lifecycle (100 lines)
+\\\`\\\`\\\`
+
+## Dependencies
+
+| Package | Purpose |
+|----|----|
+| prisma | Database ORM |
+| bcrypt | Password hashing |
+
+## Scripts
+
+| Command | Description |
+|----|----|
+| \\\`npm run dev\\\` | Start dev server |
+| \\\`npm run build\\\` | Build for production |
+| \\\`npm run test\\\` | Run tests |
+\`\`\`
+
+### Key Rules
+
+1. Source Structure uses \`←\` descriptions for EVERY file
+2. Include line counts for files >50 lines
+3. List ALL directories with their purpose
+4. Dependencies table shows WHY each dep is needed
+5. Scripts table shows ALL available npm scripts
+6. FNH blockquote after H1 lists EXPORTS and DEPS`,
+  },
+
+  "agent-rules": {
+    name: "AGENTS.md",
+    description: "How to write AGENTS.md rules file for a repository",
+    prompt: `## Task: Create AGENTS.md for a Repository
+
+AGENTS.md is the HIGHEST PRIORITY file for AI agents. Place at \`.agents/AGENTS.md\` or project root.
+
+### Mandatory Sections
+
+1. **Language** — English for code/comments, user's language for responses
+2. **Architecture Rules** — dependency direction, package boundaries
+3. **Navigation Rules** (CRITICAL):
+   - Before modifying ANY package, ALWAYS read its README.md first
+   - Do NOT scan the entire monorepo — work within target package only
+   - Do NOT read more than 5 files before starting work
+   - Use grep_search to find specific code instead of reading entire files
+4. **FNH Rules** — mandatory headers, freshness rule
+5. **Context Exclusion** — .antigravityignore rules
+6. **Code Conventions** — TS strict, validation lib, error handling
+7. **Naming Conventions** — kebab-case files, PascalCase classes
+8. **File Operations** — build/test commands
+
+### Example Navigation Rules
+
+\`\`\`markdown
+## Navigation Rules (CRITICAL for context optimization)
+- Before modifying ANY package, ALWAYS read its README.md first
+- Do NOT scan the entire monorepo — work within the target package only
+- If you need types from another package, read ONLY its src/types.ts or src/index.ts
+- Do NOT read more than 5 files before starting work
+- Use grep_search to find specific code instead of reading entire files
+\`\`\`
+
+### FNH Freshness Rule (MUST include)
+
+\`\`\`markdown
+## FNH Freshness Rule
+When you modify a file, you MUST update its FNH to reflect changes:
+- ADD a new export → add it to the FNH
+- REMOVE an export → remove it from the FNH  
+- RENAME anything → update it in the FNH
+\`\`\`
+
+### Use {{PLACEHOLDER}} for project-specific values
+\`{{BUILD_COMMAND}}\`, \`{{TEST_COMMAND}}\`, \`{{SCOPE}}\`, \`{{VALIDATION_LIB}}\``,
+  },
+
+  "context-exclusion": {
+    name: "Context Exclusion",
+    description: "How to set up .antigravityignore / .aiignore",
+    prompt: `## Task: Configure Context Exclusion for AI Agents
+
+Context Exclusion prevents AI agents from wasting tokens on irrelevant files.
+Create \`.antigravityignore\` (or \`.aiignore\`, \`.cursorignore\`) at project root.
+
+### Template
+
+\`\`\`gitignore
+# Lock files (huge, zero value in context)
+package-lock.json
+yarn.lock
+pnpm-lock.yaml
+npm-shrinkwrap.json
+
+# Build artifacts
+dist/
+build/
+.next/
+out/
+coverage/
+*.tsbuildinfo
+
+# Cache
+.turbo/
+.cache/
+.eslintcache
+
+# Generated
+*.d.ts
+*.min.js
+*.min.css
+*.map
+
+# Large binary/media
+*.png
+*.jpg
+*.gif
+*.ico
+*.woff
+*.woff2
+*.ttf
+*.eot
+
+# IDE
+.idea/
+.vscode/
+\`\`\`
+
+### Rules
+
+1. NEVER exclude source code (.ts, .js, .py, .rs)
+2. NEVER exclude test files (*.test.ts, *.spec.ts)
+3. NEVER exclude README.md or AGENTS.md
+4. ALWAYS exclude lock files (zero context value, thousands of tokens)
+5. ALWAYS exclude build artifacts (stale, generated)
+6. ALWAYS exclude binary files (can't be read as text)
+
+### Token Impact
+
+| File | Tokens | Value |
+|----|----|----|
+| package-lock.json | ~50,000 | Zero |
+| yarn.lock | ~30,000 | Zero |
+| node_modules/ | ~millions | Zero |
+| dist/ | varies | Zero (stale) |
+| README.md | ~300 | Critical |
+| src/types.ts | ~150 | Critical |`,
+  },
+
+  "god-file": {
+    name: "God File Splitting",
+    description: "How to split a god-file (>300 lines) into modules",
+    prompt: `## Task: Split a God-File into Modules
+
+A God-File is any file exceeding 300 lines of code (or 300 Context Weight).
+AI agents lose accuracy when processing files this large.
+
+### Step-by-Step Process
+
+1. **Identify boundaries**: Look for logical groups (by domain, by function type)
+2. **Extract bottom-up**: Start with leaf functions (no internal deps), then services
+3. **Build after each step**: Run build command after every extraction
+4. **Update imports**: Fix all import paths in consuming files
+5. **Add FNH**: Every new file gets an FNH header immediately
+
+### Splitting Patterns
+
+**Pattern A: Split by Domain**
+\`\`\`
+routes.ts (1200 lines) →
+  routes/users.ts (120 lines)
+  routes/orders.ts (150 lines)
+  routes/products.ts (100 lines)
+  routes/auth.ts (80 lines)
+  routes/index.ts (20 lines — re-exports)
+\`\`\`
+
+**Pattern B: Split by Layer**
+\`\`\`
+utils.ts (800 lines) →
+  utils/string.ts (60 lines)
+  utils/date.ts (40 lines)
+  utils/validation.ts (80 lines)
+  utils/response.ts (50 lines)
+  utils/index.ts (10 lines — barrel)
+\`\`\`
+
+**Pattern C: Extract Types**
+\`\`\`
+service.ts (400 lines) →
+  types.ts (80 lines — interfaces, DTOs)
+  service.ts (320 lines — logic only)
+\`\`\`
+
+### Rules
+
+1. Each extracted file MUST be <300 lines
+2. Each extracted file gets an FNH header
+3. Barrel file (index.ts) re-exports everything
+4. Build MUST pass after each extraction
+5. No circular dependencies between extracted files
+
+### Context Weight Formula
+\`\`\`
+Weight = LOC + (Local Imports × 20) + (Global Imports × 5)
+
+< 100 W: Light — easy for AI
+100-300 W: Moderate — manageable
+> 300 W: Heavy — AI will lose context, split required
+\`\`\``,
+  },
+};
+
+export function listPrompts() {
+  return Object.entries(PROMPTS).map(([key, val]) => ({
+    value: key,
+    label: `${val.name} — ${val.description}`,
+  }));
+}
+
+export function getPrompt(key) {
+  return PROMPTS[key] || null;
+}

package/checklists/phase-1-analysis.md

@@ -0,0 +1,58 @@
+<!-- FNH: Checklist — Phase 1 Analysis | ROLE: Scout | MODEL: Gemini 3 Flash -->
+
+# Phase 1: Analysis — Checklist
+
+> **Role:** Scout | **Model:** Gemini 3 Flash | **Mode:** Fast | **Goal:** Understand the monorepo's current state without modifying anything | **SECTIONS:** Environment, Dependencies, Structure, God Files, Circular Deps | **DEPS:** none
+
+## Pre-flight
+
+- [ ] Target repo path confirmed: `{{TARGET_REPO_PATH}}`
+- [ ] Read `roles/scout.md` for full instructions
+- [ ] No files will be modified (read-only phase)
+
+## Structure Analysis
+
+- [ ] Run `tools/analyze-structure.sh {{TARGET_REPO_PATH}}`
+- [ ] Run `tools/detect-god-files.sh {{TARGET_REPO_PATH}}`
+- [ ] Run `tools/detect-circular-deps.sh {{TARGET_REPO_PATH}}`
+- [ ] Run `tools/measure-context-cost.sh` for top 5 largest packages
+
+## Manual Inspection
+
+- [ ] Read root `README.md` (if exists) — note what's missing
+- [ ] Check if `packages/` or `apps/` structure exists
+- [ ] Check if monorepo manager exists (turbo.json, nx.json, lerna.json, pnpm-workspace.yaml)
+- [ ] Check for `.agents/` directory
+- [ ] Check for `.agents/AGENTS.md`
+- [ ] Check for `.agents/knowledge/` directory
+- [ ] Check for `.agents/skills/` directory
+- [ ] Check for `.agents/workflows/` directory
+- [ ] Identify the top 3 largest/most complex packages
+
+## Dependency Analysis
+
+- [ ] Map package-to-package dependencies
+- [ ] Check for imports bypassing `index.ts` (direct internal imports)
+- [ ] Identify shared type definitions (where do they live?)
+- [ ] Check dependency direction consistency
+
+## Naming Analysis
+
+- [ ] File naming convention (consistent? mixed?)
+- [ ] Directory naming convention
+- [ ] Package naming convention
+- [ ] Variable/function naming convention
+
+## Report Generation
+
+- [ ] Create `scout-report.md` in target repo root
+- [ ] Include all metrics from tools
+- [ ] Include problem severity classification (🔴/🟡/🟢)
+- [ ] Include per-package breakdown for top packages
+- [ ] Include recommendations (but NOT solutions — that's Architect's job)
+
+## Deliverable
+
+- [ ] `{{TARGET_REPO_PATH}}/scout-report.md` created
+- [ ] All metrics captured
+- [ ] No files modified in target repo

package/checklists/phase-2-planning.md

@@ -0,0 +1,67 @@
+<!-- FNH: Checklist — Phase 2 Planning | ROLE: Architect | MODEL: Claude Opus 4.6 -->
+
+# Phase 2: Planning — Checklist
+
+> **Role:** Architect | **Model:** Claude Opus 4.6 | **Mode:** Planning | **Goal:** Design target structure and create migration plan | **SECTIONS:** Target Architecture, Domain Boundaries, Skill Design, Workflow Map | **DEPS:** Phase 1
+
+## Pre-flight
+
+- [ ] Read `roles/architect.md` for full instructions
+- [ ] Read `strategy/monorepo_strategy.md` for reference
+- [ ] Read `{{TARGET_REPO_PATH}}/scout-report.md` for current state
+- [ ] No files will be modified (planning-only phase)
+
+## Target Structure Design
+
+- [ ] Define package boundaries (what goes where)
+- [ ] Define public API for each package (`index.ts` exports)
+- [ ] Define shared types location (`packages/shared/types/`)
+- [ ] Define dependency direction (routes → services → repos → entities)
+- [ ] Draw dependency graph (no cycles)
+- [ ] Verify all god-files have decomposition plan
+
+## God-File Decomposition
+
+For each god-file from scout-report:
+
+- [ ] Identify logical domains within the file
+- [ ] Plan target files (name, location, responsibility)
+- [ ] Plan barrel exports (index.ts re-exports)
+- [ ] Estimate effort (simple move vs refactor)
+
+## Naming Convention Decision
+
+- [ ] Decide on file naming: `kebab-case.ts`
+- [ ] Decide on directory naming: `kebab-case`
+- [ ] Decide on class naming: `PascalCase`
+- [ ] Decide on package naming: `@scope/kebab-case`
+- [ ] Document any exceptions
+
+## Documentation Plan
+
+- [ ] List all README.md files to create
+- [ ] List all Knowledge Items to create (topics)
+- [ ] List all Skills to create (recurring tasks)
+- [ ] List all Workflows to create (routine procedures)
+- [ ] Ensure the plan requires FNH headers on ALL files (no threshold exceptions)
+
+## Migration Plan
+
+- [ ] Define migration order (leaves first → roots last)
+- [ ] Define checkpoints (build + test after each step)
+- [ ] Identify parallel-safe steps
+- [ ] Identify high-risk steps and mitigations
+- [ ] Estimate total number of Surgeon conversations needed
+
+## Risk Assessment
+
+- [ ] List breaking changes
+- [ ] List rollback strategy for each phase
+- [ ] Identify tests that must pass at each checkpoint
+- [ ] Note any external integrations affected
+
+## Deliverable
+
+- [ ] `{{TARGET_REPO_PATH}}/architecture-plan.md` created
+- [ ] All sections filled with concrete details
+- [ ] Plan reviewed and approved by human

package/checklists/phase-3-restructuring.md

@@ -0,0 +1,77 @@
+<!-- FNH: Checklist — Phase 3 Restructuring | ROLE: Surgeon | MODEL: Gemini 3.1 Pro -->
+
+# Phase 3: Restructuring — Checklist
+
+> **Role:** Surgeon | **Model:** Gemini 3.1 Pro (High) | **Mode:** Fast | **Goal:** Execute restructuring strictly per architecture-plan.md | **SECTIONS:** Move Files, Update Imports, Cleanup, Naming Consistency | **DEPS:** Phase 2
+
+## Pre-flight
+
+- [ ] Read `roles/surgeon.md` for full instructions
+- [ ] Read `{{TARGET_REPO_PATH}}/architecture-plan.md`
+- [ ] Ensure build passes BEFORE starting: `{{BUILD_COMMAND}}`
+- [ ] Ensure tests pass BEFORE starting: `{{TEST_COMMAND}}`
+- [ ] Create git branch: `git checkout -b ai-context-surgeon/restructure`
+
+## Phase 3a: Foundation (Shared Types & Entities)
+
+- [ ] Create `packages/shared/` structure (if needed)
+- [ ] Move shared types to `packages/shared/src/types/`
+- [ ] Create `packages/shared/src/index.ts` with exports
+- [ ] Update all imports across the monorepo
+- [ ] **Checkpoint:** `{{BUILD_COMMAND}}` ✅
+
+## Phase 3b: Core Logic
+
+- [ ] Restructure `packages/core/` per plan
+- [ ] Decompose god-files per plan
+- [ ] Create `packages/core/src/index.ts` with public API
+- [ ] Create `packages/core/src/types.ts` with contracts
+- [ ] Update all imports
+- [ ] **Checkpoint:** `{{BUILD_COMMAND}}` ✅
+
+## Phase 3c: Service Layer
+
+- [ ] Restructure service packages per plan
+- [ ] Ensure services import from core via `index.ts` only
+- [ ] Create `src/index.ts` and `src/types.ts` for each
+- [ ] Update all imports
+- [ ] **Checkpoint:** `{{BUILD_COMMAND}}` ✅
+
+## Phase 3d: API / Presentation Layer
+
+- [ ] Restructure API/web packages per plan
+- [ ] Ensure routes/pages import from services via `index.ts` only
+- [ ] Create `src/index.ts` for each
+- [ ] Update all imports
+- [ ] **Checkpoint:** `{{BUILD_COMMAND}}` ✅
+
+## Phase 3e: Apps Layer
+
+- [ ] Restructure apps per plan
+- [ ] Verify all apps build
+- [ ] **Checkpoint:** `{{BUILD_COMMAND}} && {{TEST_COMMAND}}` ✅
+
+## Post-restructuring
+
+- [ ] Full build: `{{BUILD_COMMAND}}` ✅
+- [ ] Full tests: `{{TEST_COMMAND}}` ✅
+- [ ] Type check: `tsc --noEmit` ✅
+- [ ] No files left in wrong locations
+- [ ] All god-files decomposed
+- [ ] No circular dependencies: `tools/detect-circular-deps.sh`
+- [ ] Git commit: `git add -A && git commit -m "ai-context-surgeon: restructure complete"`
+
+## Rules During Restructuring
+
+- ⚠️ After EVERY file move → update imports → build check
+- ⚠️ If build breaks → fix IMMEDIATELY, don't proceed
+- ⚠️ Never change business logic — only move and rename
+- ⚠️ One logical step per conversation (if large)
+- ⚠️ Follow plan exactly — no improvisation
+
+## Deliverable
+
+- [ ] All files restructured per architecture-plan.md
+- [ ] Build passes
+- [ ] Tests pass
+- [ ] Clean git history on `ai-context-surgeon/restructure` branch

package/checklists/phase-4-documentation.md

@@ -0,0 +1,111 @@
+<!-- FNH: Checklist — Phase 4 Documentation | ROLE: Librarian / Tuner | MODEL: Claude Sonnet / Opus -->
+
+# Phase 4: Documentation — Checklist
+
+> **Role:** Librarian / Tuner | **Model:** Claude Sonnet / Opus 4.6 | **Mode:** Planning | **Goal:** Create complete documentation and configuration | **SECTIONS:** FNH Headers, JSDoc, package.json, Strategy Docs, Templates | **DEPS:** Phase 3
+
+## Pre-flight
+
+- [ ] Read `roles/librarian.md` for documentation instructions
+- [ ] Read `roles/tuner.md` for configuration instructions
+- [ ] Read `{{TARGET_REPO_PATH}}/architecture-plan.md` "Documentation Plan" section
+- [ ] Have templates from `ai-context-surgeon/templates/` ready
+
+## 4a: READMEs (Librarian)
+
+### Root README
+
+- [ ] Create/update root `README.md`
+- [ ] Include project description (2–3 sentences)
+- [ ] Include architecture map (tree with `←` descriptions)
+- [ ] Include key technology decisions
+- [ ] Include getting started instructions
+
+### Package READMEs
+
+For each package in `packages/` and `apps/`:
+
+- [ ] Create `README.md` using `templates/package-readme.template`
+- [ ] Include Source Structure section with `←` descriptions
+- [ ] Include dependencies table
+- [ ] Include public API summary
+- [ ] Include relevant environment variables
+- [ ] Include build/test scripts
+
+## 4b: Knowledge Items (Librarian)
+
+- [ ] Create `.agents/knowledge/` directory structure
+- [ ] Create KI: `database-schema` (if DB exists)
+- [ ] Create KI: `api-conventions` (if API exists)
+- [ ] Create KI: `auth-flow` (if auth exists)
+- [ ] Create KI: `error-handling` (error patterns)
+- [ ] Create KI: `deployment` (deploy process)
+- [ ] Each KI has `metadata.json` + `artifacts/*.md`
+- [ ] Each KI follows atomicity principle (one topic)
+- [ ] Each KI is concrete and actionable (not vague)
+- [ ] Content must be entirely in English
+
+## 4c: Skills (Librarian)
+
+- [ ] Create `.agents/skills/` directory structure
+- [ ] Create Skill: `create-endpoint` (if API project)
+- [ ] Create Skill: `create-package` (for new packages)
+- [ ] Create Skill: `db-migration` (if DB exists)
+- [ ] Each Skill has `SKILL.md` with frontmatter
+- [ ] Each Skill has "When to Use" / "When NOT to Use"
+- [ ] Each Skill has step-by-step instructions
+- [ ] Each Skill has template code
+- [ ] Content must be entirely in English
+
+## 4d: Workflows (Librarian)
+
+- [ ] Create `.agents/workflows/` directory structure
+- [ ] Create Workflow: `test.md` — run tests for a package
+- [ ] Create Workflow: `build.md` — build verification
+- [ ] Create Workflow: `lint-fix.md` — auto-fix lint issues
+- [ ] Each Workflow has `description:` frontmatter
+- [ ] Each Workflow has explicit commands
+- [ ] Appropriate `// turbo` annotations
+- [ ] Content must be entirely in English
+
+## 4e: FNH Headers (Librarian)
+
+- [ ] Ensure EVERY source file has an FNH header
+- [ ] Run `tools/check-fnh-freshness.sh` to preview gaps
+- [ ] Headers must all be in English
+- [ ] Headers must follow the 5 mandatory layers
+
+## 4f: AGENTS.md (Tuner)
+
+- [ ] Create `.agents/AGENTS.md` using `templates/AGENTS.md.template`
+- [ ] Fill all placeholders with project-specific values
+- [ ] Include "Read README first" rule
+- [ ] Include "Stay within package" rule
+- [ ] Include "Max 5 files before work" rule
+- [ ] Include FNH freshness rule
+- [ ] Include English-only content rule
+- [ ] Include dependency direction rules
+- [ ] Include naming conventions
+- [ ] Include build/test commands
+- [ ] Include package ownership table
+- [ ] Review for contradictions or ambiguity
+
+## 4g: Config Tuning (Tuner)
+
+- [ ] Create root `.antigravityignore` excluding lock files and build artifacts
+- [ ] Verify/update `turbo.json` or `nx.json` pipeline
+- [ ] Verify/update root `tsconfig.json` project references
+- [ ] Verify `.gitignore` includes ai-context-surgeon temp files
+- [ ] Verify `package.json` scripts are correct
+
+## Deliverable
+
+- [ ] Root README.md ✅
+- [ ] All package READMEs ✅
+- [ ] Knowledge Items created ✅
+- [ ] Skills created ✅
+- [ ] Workflows created ✅
+- [ ] FNH headers present on all files ✅
+- [ ] AGENTS.md configured ✅
+- [ ] .antigravityignore created ✅
+- [ ] Build configs verified ✅