agentic-compaction 0.0.1

package/.orchestration/orchestration.md

@@ -0,0 +1,52 @@
+# Orchestration Protocol
+
+**MANDATORY: Process BEFORE any tool usage.**
+
+## 1. CLASSIFY TASK
+
+| Signal Words | Workflow |
+|--------------|----------|
+| build, create, add, implement, new | `feature.md` |
+| fix, broken, error, crash, bug | `bugfix.md` |
+| clean up, improve, restructure, rename | `refactor.md` |
+| slow, optimize, performance, speed | `performance.md` |
+| review, check, PR, merge | `review.md` |
+| PR description, pull request title | `pr.md` |
+| document, README, explain | `docs.md` |
+| complex, multi-step, plan | `todo.md` |
+
+**Complexity:** 1-2 ops = simple | 3+ ops = complex (add `todo.md`)
+**Technology:** React (`.jsx`/`.tsx`, hooks) → `workflows/react/` | Other → `workflows/`
+
+### Selection
+- **Clear match:** Proceed to binding
+- **Ambiguous:** Use `AskUserQuestion` (header: "Workflow", options: relevant workflows)
+- **No match:** Ask user to clarify
+
+## 2. BINDING (required before ANY tool use)
+
+```
+ORCHESTRATION_BINDING:
+- Task: [description]
+- Workflow: [path]
+- Complexity: [simple/complex]
+```
+
+## 3. EXEMPT TASKS
+
+Requires ALL: single file, 1-2 ops, zero architecture impact, obvious correctness.
+
+```
+ORCHESTRATION_BINDING:
+- Task: [description]
+- Classification: EXEMPT
+```
+
+## 4. COMPLETION
+
+```
+ORCHESTRATION_COMPLETE:
+- Task: [description]
+- Workflow: [used]
+- Files: [modified]
+```

package/.orchestration/workflows/react/bugfix.md

@@ -0,0 +1,32 @@
+# React Bugfix Workflow
+
+## 1. Reproduce
+
+- Confirm bug exists | find minimal repro
+- Check Strict Mode behavior
+- Answer: Expected vs actual? React 18 concurrent issue?
+
+## 2. Locate Root Cause
+
+| Common React 18 Issues |
+|------------------------|
+| Effects missing cleanup |
+| Stale closures in effects |
+| Concurrent rendering race conditions |
+| Automatic batching changes |
+
+## 3. Fix
+
+- Keep changes within affected feature folder
+- Add cleanup: `return () => controller.abort()`
+- Fix stale closures with proper deps
+
+## 4. Verify
+
+- Confirm fix | test with Strict Mode
+- Add regression test
+
+## Constraints
+
+- Smallest fix only | NO refactoring
+- NO barrel exports | note other issues separately

package/.orchestration/workflows/react/docs.md

@@ -0,0 +1,59 @@
+# React Documentation Workflow
+
+> Document architecture correctly. See orchestration.md for patterns.
+
+## Before Writing
+
+MUST answer:
+- Who is the audience?
+- What should they be able to do after reading?
+- What existing docs need to stay in sync?
+
+## Process
+
+### 1. Understand the Subject
+- Read the code being documented
+- Try it yourself if possible
+- Identify non-obvious behavior or gotchas
+
+### 2. Check Existing Docs
+- Find related documentation
+- Identify what's missing or outdated
+- Note the existing style and format
+
+### 3. Write
+
+Adapt this template as needed:
+
+```markdown
+# {Name}
+
+Brief description.
+
+## Location
+`features/{feature}/components/{Name}/{Name}.tsx`
+
+## Import
+import { Name } from '@/features/{feature}/components/{Name}/{Name}'
+
+## Usage
+<Name prop="value" />
+
+## Props/Parameters (if applicable)
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+
+## Related
+- Links to related components/hooks
+```
+
+### 4. Validate
+- Code examples actually work
+- Import paths are direct (not barrel)
+- Links are valid
+
+## Constraints
+
+- MUST explain why, not just what
+- MUST show direct import paths in examples
+- MUST update related docs to stay consistent

package/.orchestration/workflows/react/feature.md

@@ -0,0 +1,37 @@
+# React Feature Workflow
+
+## 1. Architecture
+
+**IF not specified:** Use `AskUserQuestion` (header: "Architecture")
+
+| Architecture | Structure |
+|--------------|-----------|
+| Feature-driven | `features/{name}/components\|hooks\|utils/` |
+| Flat feature-driven | `features/{name}/` flat files |
+| Atomic design | `atoms\|molecules\|organisms\|templates/` |
+
+**IF project has patterns:** Follow existing, skip question.
+
+## 2. Context
+
+- Read related code, identify target folder
+- Check similar implementations, reusable hooks/utils
+- Answer: What problem? Minimal version? Which folder?
+
+## 3. Implement
+
+**Components:** Function only | `useState`/`useReducer` for local state
+**Hooks:** Extract logic | `hooks/{feature}/{name}.ts` | descriptive names
+**State:** Lift only as needed | composition over prop drilling
+
+## 4. Validate
+
+- Run tests for regressions
+- Add tests for new code
+- Test loading/error states
+- Remove debug code
+
+## Constraints
+
+- NO `index.ts`/`index.tsx` | import from file directly
+- Match existing style | no extra features

package/.orchestration/workflows/react/performance.md

@@ -0,0 +1,59 @@
+# React Performance Workflow
+
+> Architecture rules: See orchestration.md. Violations block merge.
+
+## Before Coding
+
+MUST answer:
+- What is the specific performance problem?
+- How will I measure improvement?
+- Is this a real bottleneck or premature optimization?
+
+## Process
+
+### 1. Measure First
+- Profile with React DevTools Profiler
+- Identify components that re-render unnecessarily
+- Check bundle size with build analyzer
+- Measure actual user-facing metrics (not just hunches)
+
+### 2. Identify Root Cause
+
+**Common issues:**
+- Components re-rendering when props haven't changed
+- Expensive calculations on every render
+- Large bundle from unused dependencies
+- Missing code splitting on routes
+
+### 3. Optimize
+
+**Prevent unnecessary re-renders:**
+```tsx
+// Memoize components that receive stable props
+const MemoizedList = memo(List)
+
+// Memoize callbacks passed to children
+const handleClick = useCallback(() => {
+  doSomething(id)
+}, [id])
+
+// Memoize expensive derived values
+const sorted = useMemo(() => sortItems(items), [items])
+```
+
+**Reduce bundle size:**
+- Lazy load routes with `React.lazy` + `Suspense`
+- Replace heavy libraries with lighter alternatives
+- Use tree-shakeable imports
+
+### 4. Verify
+- Re-profile to confirm improvement
+- Ensure no regressions in functionality
+- Document the optimization and why it helped
+
+## Constraints
+
+- NEVER optimize without measuring first
+- NEVER add memo/useMemo/useCallback everywhere "just in case"
+- MUST prove the optimization helps with real measurements
+- Keep optimizations minimal and targeted

package/.orchestration/workflows/react/pr.md

@@ -0,0 +1,19 @@
+# Pull Request Workflow
+
+## Process
+
+1. Read diff (current branch vs main/master)
+2. Analyze changes
+3. Output title + description
+
+## Output
+
+```
+PR Title: <imperative mood>
+Description: <2-3 sentences: what + why>
+```
+
+## Constraints
+
+- Imperative mood ("Add" not "Added") | mention breaking changes
+- Output only | NO branch/push/remote PR creation

package/.orchestration/workflows/react/refactor.md

@@ -0,0 +1,32 @@
+# React Refactor Workflow
+
+## 1. Safety Net
+
+- Run tests | add if coverage insufficient
+- Answer: What improvement? How verify unchanged behavior?
+
+## 2. Plan
+
+- Map imports/dependencies | identify all callers
+- Break into small, safe steps
+
+## 3. Execute
+
+One change type at a time | run tests after each:
+
+| Change Types |
+|--------------|
+| Rename files to match folders |
+| Barrel → direct imports |
+| Extract logic into hooks |
+| Split large components |
+
+## 4. Validate
+
+- All tests pass | no `index.ts`/`index.tsx`
+- Entry points match folder names
+
+## Constraints
+
+- Structure only, NOT behavior | NO bug fixes
+- One change type at a time | note issues separately

package/.orchestration/workflows/react/review.md

@@ -0,0 +1,46 @@
+# React Code Review Workflow
+
+## 1. Understand
+
+- Read PR description | review diff scope
+- Answer: What is the goal? What files changed?
+
+## 2. Architecture Checklist
+
+| Check | Rule |
+|-------|------|
+| Barrels | No `index.ts`/`index.tsx` |
+| Entry files | Match folder names (`Button/Button.tsx`) |
+| Imports | Direct, not barrel |
+| Colocation | Component + hooks + types + tests together |
+| Placement | Correct feature folder |
+
+## 3. React Patterns Checklist
+
+| Check | Rule |
+|-------|------|
+| Components | Function only, no class |
+| Hooks | No conditionals, proper deps |
+| Effects | Cleanup where needed |
+| Memory | No leaks (subscriptions, timers) |
+| States | Loading + error handled |
+
+## 4. Code Quality Checklist
+
+| Check | Rule |
+|-------|------|
+| Debug | No console.log/debugger |
+| Imports | No unused |
+| Types | No unjustified `any` |
+| Tests | Cover new functionality |
+| Scope | No unrelated changes |
+
+## 5. Feedback
+
+- **Blocking:** Must fix (bugs, architecture violations)
+- **Suggestion:** Improvements | **Question:** Clarification
+
+## Constraints
+
+- NO approval with violations | must understand code
+- Specific + actionable | suggest fixes, not just problems

package/ORCHESTRATION.md

@@ -0,0 +1,5 @@
+# ORCHESTRATION.md
+
+## Orchestration
+
+For complex tasks, refer to .orchestration/orchestration.md for available workflows.

package/README.md

@@ -0,0 +1,118 @@
+# codebase-compact
+
+Walks a project directory, parses JS/TS/Python files, and outputs a compact structural skeleton of the entire codebase. Designed for feeding project context into LLM prompts with minimal token usage.
+
+Typical compaction rate: **~95%** token reduction.
+
+## Install
+
+```bash
+npm install -g codebase-compact
+```
+
+Or run directly from the repo:
+
+```bash
+node src/cli.js /path/to/project
+```
+
+## CLI Usage
+
+```bash
+codebase-compact [path] [options]
+```
+
+**Options:**
+
+| Flag | Description |
+|------|-------------|
+| `--json` | Save output as JSON (includes stats) |
+| `--help`, `-h` | Show help |
+
+If no path is given, it defaults to the current directory.
+
+Output is saved to the target directory as `compacted_<project>_<date>.md`.
+
+**Example:**
+
+```bash
+$ codebase-compact ~/projects/my-app
+
+Saved to /home/user/projects/my-app/compacted_my-app_2026-02-12_15-30-00.md
+
+  Files:            96
+  Project tokens:   106.9K
+  Compacted tokens: 5.9K
+  Compaction rate:  94.4%
+```
+
+## Library Usage
+
+```js
+import { compactProject, compactFile } from 'codebase-compact';
+
+// Compact an entire directory
+const { output, stats } = compactProject('/path/to/project');
+console.log(output);
+console.log(stats); // { files, rawTokens, compactedTokens }
+
+// Compact a single file
+const { skeleton, formatted } = compactFile('app.tsx', sourceCode);
+```
+
+## Output Format
+
+Each file is rendered as a markdown heading followed by its structural skeleton:
+
+```
+## src/components/App.jsx
+imports: 3 ext, ./hooks/useAuth, ./api/client
+exports: App*
+components: App:12
+fn: handleSubmit:24, validate:40
+hooks: useState(2), useEffect([user]):18, useAuth
+```
+
+The skeleton captures:
+- **Imports** (local paths shown, externals counted)
+- **Exports** (default marked with `*`)
+- **Components** (PascalCase functions, HOC-wrapped)
+- **Functions** (with line numbers)
+- **Hooks** (counts, useEffect deps, custom hooks)
+- **Classes, interfaces, types** (TS)
+- **Python**: imports, classes (with bases/decorators), functions, constants
+
+## Supported Languages
+
+| Language | Parser | Extensions |
+|----------|--------|------------|
+| JavaScript | `@babel/parser` | `.js`, `.jsx`, `.mjs`, `.cjs` |
+| TypeScript | `@babel/parser` | `.ts`, `.tsx`, `.mts`, `.cts` |
+| Python | Regex-based (zero deps) | `.py` |
+
+## Skipped Directories
+
+`node_modules`, `dist`, `.git`, `target`, `build`, `.next`, `.turbo`, `out`, `coverage`, `.cache`, `__pycache__`, `.venv`, `venv`, `.idea`, `.vscode`, and any dotfile directories.
+
+## Project Structure
+
+```
+src/
+  cli.js            # CLI entry point
+  index.js          # Library API: compactProject, compactFile
+  walker.js         # Recursive directory walker with filtering
+  formatter.js      # Output formatting + token estimation
+  parsers/
+    babel.js        # JS/TS parsing via Babel AST
+    python.js       # Python parsing via regex (top-level only)
+```
+
+## Tests
+
+```bash
+npm test
+```
+
+## License
+
+MIT

package/compacted_2026-02-12_15-24-24.txt

@@ -0,0 +1,34 @@
+## src/cli.js
+imports: 2 ext, ./index.js, ./formatter.js
+fn: getDateStamp:8, pad:10
+## src/formatter.js
+imports: ./parsers/python.js, ./parsers/babel.js, ./parsers/python.js
+exports: estimateTokens, formatTokenCount, formatOutput
+fn: estimateTokens:5, formatTokenCount:10, formatOutput:16
+## src/index.js
+imports: 1 ext, ./walker.js, ./formatter.js, ./parsers/babel.js, ./parsers/python.js
+exports: isBabelParseable, isPythonParseable, estimateTokens, formatTokenCount, compactFile, compactProject
+fn: compactFile:17, compactProject:38
+## src/parsers/babel.js
+imports: 2 ext
+exports: isBabelParseable, extractSignatures, extractSkeleton, formatSignaturesForPrompt, formatSkeletonForPrompt
+fn: isBabelParseable:9, isPascalCase:13, getReactHOCInfo:17, isCreateContext:52, extractDependencyArray:69, getParamsString:97, getTypeName:123, getReturnType:141, extractSignatures:146, extractSkeleton:242, formatSignaturesForPrompt:402, formatSkeletonForPrompt:407
+## src/parsers/python.js
+exports: isPythonParseable, extractSkeleton, formatSkeletonForPrompt
+fn: isPythonParseable:3, extractSkeleton:14, formatSkeletonForPrompt:148
+## src/walker.js
+imports: 2 ext, ./parsers/babel.js, ./parsers/python.js
+exports: collectFiles
+fn: collectFiles:24, SKIP_DIRS_OR_DOT:48, isParseable:52
+## test/fixtures/sample.js
+imports: 1 ext, ./api
+exports: MyComponent, MyComponent*
+components: MyComponent:6
+fn: helper:16
+hooks: useState(1), useEffect([id]):9
+## test/fixtures/sample.py
+imports: 4 ext
+classes: BaseProcessor:9, Config @dataclass (BaseProcessor):13
+fn: process_data:17, fetch_remote:20, @app.route api_handler:24
+## test/test.js
+imports: 5 ext, ../src/index.js, ../src/parsers/babel.js, ../src/parsers/python.js, ../src/walker.js

package/compacted_standalonecompaction_2026-02-12_15-26-38.md

@@ -0,0 +1,34 @@
+## src/cli.js
+imports: 2 ext, ./index.js, ./formatter.js
+fn: getDateStamp:8, pad:10
+## src/formatter.js
+imports: ./parsers/python.js, ./parsers/babel.js, ./parsers/python.js
+exports: estimateTokens, formatTokenCount, formatOutput
+fn: estimateTokens:5, formatTokenCount:10, formatOutput:16
+## src/index.js
+imports: 1 ext, ./walker.js, ./formatter.js, ./parsers/babel.js, ./parsers/python.js
+exports: isBabelParseable, isPythonParseable, estimateTokens, formatTokenCount, compactFile, compactProject
+fn: compactFile:17, compactProject:38
+## src/parsers/babel.js
+imports: 2 ext
+exports: isBabelParseable, extractSignatures, extractSkeleton, formatSignaturesForPrompt, formatSkeletonForPrompt
+fn: isBabelParseable:9, isPascalCase:13, getReactHOCInfo:17, isCreateContext:52, extractDependencyArray:69, getParamsString:97, getTypeName:123, getReturnType:141, extractSignatures:146, extractSkeleton:242, formatSignaturesForPrompt:402, formatSkeletonForPrompt:407
+## src/parsers/python.js
+exports: isPythonParseable, extractSkeleton, formatSkeletonForPrompt
+fn: isPythonParseable:3, extractSkeleton:14, formatSkeletonForPrompt:148
+## src/walker.js
+imports: 2 ext, ./parsers/babel.js, ./parsers/python.js
+exports: collectFiles
+fn: collectFiles:24, SKIP_DIRS_OR_DOT:48, isParseable:52
+## test/fixtures/sample.js
+imports: 1 ext, ./api
+exports: MyComponent, MyComponent*
+components: MyComponent:6
+fn: helper:16
+hooks: useState(1), useEffect([id]):9
+## test/fixtures/sample.py
+imports: 4 ext
+classes: BaseProcessor:9, Config @dataclass (BaseProcessor):13
+fn: process_data:17, fetch_remote:20, @app.route api_handler:24
+## test/test.js
+imports: 5 ext, ../src/index.js, ../src/parsers/babel.js, ../src/parsers/python.js, ../src/walker.js

package/compacted_standalonecompaction_2026-02-12_15-28-25.md

@@ -0,0 +1,34 @@
+## src/cli.js
+imports: 2 ext, ./index.js, ./formatter.js
+fn: getDateStamp:8, pad:10
+## src/formatter.js
+imports: ./parsers/python.js, ./parsers/babel.js, ./parsers/python.js
+exports: estimateTokens, formatTokenCount, formatOutput
+fn: estimateTokens:5, formatTokenCount:10, formatOutput:16
+## src/index.js
+imports: 1 ext, ./walker.js, ./formatter.js, ./parsers/babel.js, ./parsers/python.js
+exports: isBabelParseable, isPythonParseable, estimateTokens, formatTokenCount, compactFile, compactProject
+fn: compactFile:17, compactProject:38
+## src/parsers/babel.js
+imports: 2 ext
+exports: isBabelParseable, extractSignatures, extractSkeleton, formatSignaturesForPrompt, formatSkeletonForPrompt
+fn: isBabelParseable:9, isPascalCase:13, getReactHOCInfo:17, isCreateContext:52, extractDependencyArray:69, getParamsString:97, getTypeName:123, getReturnType:141, extractSignatures:146, extractSkeleton:242, formatSignaturesForPrompt:402, formatSkeletonForPrompt:407
+## src/parsers/python.js
+exports: isPythonParseable, extractSkeleton, formatSkeletonForPrompt
+fn: isPythonParseable:3, extractSkeleton:14, formatSkeletonForPrompt:148
+## src/walker.js
+imports: 2 ext, ./parsers/babel.js, ./parsers/python.js
+exports: collectFiles
+fn: collectFiles:24, SKIP_DIRS_OR_DOT:48, isParseable:52
+## test/fixtures/sample.js
+imports: 1 ext, ./api
+exports: MyComponent, MyComponent*
+components: MyComponent:6
+fn: helper:16
+hooks: useState(1), useEffect([id]):9
+## test/fixtures/sample.py
+imports: 4 ext
+classes: BaseProcessor:9, Config @dataclass (BaseProcessor):13
+fn: process_data:17, fetch_remote:20, @app.route api_handler:24
+## test/test.js
+imports: 5 ext, ../src/index.js, ../src/parsers/babel.js, ../src/parsers/python.js, ../src/walker.js

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "agentic-compaction",
+  "version": "0.0.1",
+  "description": "Walk a project directory and output a compact structural skeleton of the entire codebase",
+  "type": "module",
+  "main": "./src/index.js",
+  "bin": {
+    "codebase-compact": "./src/cli.js"
+  },
+  "scripts": {
+    "test": "node --test test/"
+  },
+  "keywords": [
+    "codebase",
+    "compact",
+    "skeleton",
+    "parser",
+    "ast"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "@babel/parser": "^7.24.0",
+    "@babel/traverse": "^7.24.0"
+  }
+}

package/src/cli.js

@@ -0,0 +1,59 @@
+#!/usr/bin/env node
+
+import { resolve, join, basename } from 'path';
+import { writeFileSync } from 'fs';
+import { compactProject } from './index.js';
+import { formatTokenCount } from './formatter.js';
+
+function getDateStamp() {
+  const now = new Date();
+  const pad = (n) => String(n).padStart(2, '0');
+  return `${now.getFullYear()}-${pad(now.getMonth() + 1)}-${pad(now.getDate())}_${pad(now.getHours())}-${pad(now.getMinutes())}-${pad(now.getSeconds())}`;
+}
+
+const args = process.argv.slice(2);
+
+let targetPath = process.cwd();
+let jsonOutput = false;
+
+for (let i = 0; i < args.length; i++) {
+  const arg = args[i];
+  if (arg === '--json') {
+    jsonOutput = true;
+  } else if (arg === '--help' || arg === '-h') {
+    console.log(`Usage: codebase-compact [path] [options]
+
+Options:
+  --json         Output as JSON instead of text
+  --help, -h     Show this help message
+
+Output is saved to compacted_<name>_<date>.md in the target directory.`);
+    process.exit(0);
+  } else if (!arg.startsWith('-')) {
+    targetPath = arg;
+  }
+}
+
+targetPath = resolve(targetPath);
+
+const { output, stats } = compactProject(targetPath);
+
+const dirName = basename(targetPath);
+const filename = `compacted_${dirName}_${getDateStamp()}.md`;
+const outputPath = join(targetPath, filename);
+
+if (jsonOutput) {
+  writeFileSync(outputPath, JSON.stringify({ output, stats }, null, 2));
+} else {
+  writeFileSync(outputPath, output);
+}
+
+const compactionRate = stats.rawTokens > 0
+  ? ((1 - stats.compactedTokens / stats.rawTokens) * 100).toFixed(1)
+  : '0';
+
+console.log(`\nSaved to ${outputPath}\n`);
+console.log(`  Files:            ${stats.files}`);
+console.log(`  Project tokens:   ${formatTokenCount(stats.rawTokens)}`);
+console.log(`  Compacted tokens: ${formatTokenCount(stats.compactedTokens)}`);
+console.log(`  Compaction rate:  ${compactionRate}%`);

package/src/formatter.js

@@ -0,0 +1,33 @@
+import { isPythonParseable } from './parsers/python.js';
+import { formatSkeletonForPrompt as formatBabelSkeleton } from './parsers/babel.js';
+import { formatSkeletonForPrompt as formatPythonSkeleton } from './parsers/python.js';
+
+export const estimateTokens = (text) => {
+  if (!text) return 0;
+  return Math.ceil(text.length / 4);
+};
+
+export const formatTokenCount = (count) => {
+  if (count >= 1000000) return `${(count / 1000000).toFixed(1)}M`;
+  if (count >= 1000) return `${(count / 1000).toFixed(1)}K`;
+  return count.toString();
+};
+
+export function formatOutput(results) {
+  const lines = [];
+
+  results.sort((a, b) => a.relativePath.localeCompare(b.relativePath));
+
+  for (const result of results) {
+    lines.push(`## ${result.relativePath}`);
+
+    if (result.skeleton) {
+      const output = isPythonParseable(result.relativePath)
+        ? formatPythonSkeleton(result.skeleton)
+        : formatBabelSkeleton(result.skeleton);
+      if (output) lines.push(output);
+    }
+  }
+
+  return lines.join('\n');
+}