mirror of
https://github.com/prdlk/dotfiles.git
synced 2026-11-02 19:32:43 +00:00
shell: fish functions -> ~/.local/bin executables + bash/zsh ports; manage ~/.agents
- 16 cross-shell utilities converted to sh/bash chezmoi executables: ai c2p cp-appid extract_agents fab gdc gh-sonr-org-migrate ghg-clone ghn gho git-summary launch_omp_livediff_overlay lc-elir mdcp mdp pj (ghg-clone not named ghg: unrelated cargo binary owns that name) - cwd/history helpers stay per-shell: yy c cd clip-last + ghg/ghn/gho cd-wrappers in bash/functions/ and zsh/functions/, loaded by rc files - fish keeps only shell-state functions; converted ones now hit PATH - cp-appid ignore gating moved to .local/bin path - dot_agents/skills: 82 skills materialized from dotstate storage so dot_claude skill symlinks resolve on fresh bootstrap; dotstate profile/symlinks.json released .agents/skills .bashrc .zshrc
This commit is contained in:
Prad Nukala committed
1 parent
6776366ce6
commit
6406208b35
637 files changed
+100297
-497
No files matched your search
@@ -0,0 +1,321 @@
|
||||
---
|
||||
name: deepinit
|
||||
description: Deep codebase initialization with hierarchical AGENTS.md documentation
|
||||
level: 4
|
||||
---
|
||||
|
||||
# Deep Init Skill
|
||||
|
||||
Creates comprehensive, hierarchical AGENTS.md documentation across the entire codebase.
|
||||
|
||||
## Core Concept
|
||||
|
||||
AGENTS.md files serve as **AI-readable documentation** that helps agents understand:
|
||||
- What each directory contains
|
||||
- How components relate to each other
|
||||
- Special instructions for working in that area
|
||||
- Dependencies and relationships
|
||||
|
||||
## Hierarchical Tagging System
|
||||
|
||||
Every AGENTS.md (except root) includes a parent reference tag:
|
||||
|
||||
```markdown
|
||||
<!-- Parent: ../AGENTS.md -->
|
||||
```
|
||||
|
||||
This creates a navigable hierarchy:
|
||||
```
|
||||
/AGENTS.md ← Root (no parent tag)
|
||||
├── src/AGENTS.md ← <!-- Parent: ../AGENTS.md -->
|
||||
│ ├── src/components/AGENTS.md ← <!-- Parent: ../AGENTS.md -->
|
||||
│ └── src/utils/AGENTS.md ← <!-- Parent: ../AGENTS.md -->
|
||||
└── docs/AGENTS.md ← <!-- Parent: ../AGENTS.md -->
|
||||
```
|
||||
|
||||
## AGENTS.md Template
|
||||
|
||||
```markdown
|
||||
<!-- Parent: {relative_path_to_parent}/AGENTS.md -->
|
||||
<!-- Generated: {timestamp} | Updated: {timestamp} -->
|
||||
|
||||
# {Directory Name}
|
||||
|
||||
## Purpose
|
||||
{One-paragraph description of what this directory contains and its role}
|
||||
|
||||
## Key Files
|
||||
{List each significant file with a one-line description}
|
||||
|
||||
| File | Description |
|
||||
|------|-------------|
|
||||
| `file.ts` | Brief description of purpose |
|
||||
|
||||
## Subdirectories
|
||||
{List each subdirectory with brief purpose}
|
||||
|
||||
| Directory | Purpose |
|
||||
|-----------|---------|
|
||||
| `subdir/` | What it contains (see `subdir/AGENTS.md`) |
|
||||
|
||||
## For AI Agents
|
||||
|
||||
### Working In This Directory
|
||||
{Special instructions for AI agents modifying files here}
|
||||
|
||||
### Testing Requirements
|
||||
{How to test changes in this directory}
|
||||
|
||||
### Common Patterns
|
||||
{Code patterns or conventions used here}
|
||||
|
||||
## Dependencies
|
||||
|
||||
### Internal
|
||||
{References to other parts of the codebase this depends on}
|
||||
|
||||
### External
|
||||
{Key external packages/libraries used}
|
||||
|
||||
<!-- MANUAL: Any manually added notes below this line are preserved on regeneration -->
|
||||
```
|
||||
|
||||
## Execution Workflow
|
||||
|
||||
### Step 1: Map Directory Structure
|
||||
|
||||
```
|
||||
Task(subagent_type="explore", model="haiku",
|
||||
prompt="List all directories recursively. Exclude: node_modules, .git, dist, build, __pycache__, .venv, coverage, .next, .nuxt")
|
||||
```
|
||||
|
||||
### Step 2: Create Work Plan
|
||||
|
||||
Generate todo items for each directory, organized by depth level:
|
||||
|
||||
```
|
||||
Level 0: / (root)
|
||||
Level 1: /src, /docs, /tests
|
||||
Level 2: /src/components, /src/utils, /docs/api
|
||||
...
|
||||
```
|
||||
|
||||
### Step 3: Generate Level by Level
|
||||
|
||||
**IMPORTANT**: Generate parent levels before child levels to ensure parent references are valid.
|
||||
|
||||
For each directory:
|
||||
1. Read all files in the directory
|
||||
2. Analyze purpose and relationships
|
||||
3. Generate AGENTS.md content
|
||||
4. Write file with proper parent reference
|
||||
|
||||
### Step 4: Compare and Update (if exists)
|
||||
|
||||
When AGENTS.md already exists:
|
||||
|
||||
1. **Read existing content**
|
||||
2. **Identify sections**:
|
||||
- Auto-generated sections (can be updated)
|
||||
- Manual sections (`<!-- MANUAL -->` preserved)
|
||||
3. **Compare**:
|
||||
- New files added?
|
||||
- Files removed?
|
||||
- Structure changed?
|
||||
4. **Merge**:
|
||||
- Update auto-generated content
|
||||
- Preserve manual annotations
|
||||
- Update timestamp
|
||||
|
||||
### Step 5: Validate Hierarchy
|
||||
|
||||
After generation, run validation checks:
|
||||
|
||||
| Check | How to Verify | Corrective Action |
|
||||
|-------|--------------|-------------------|
|
||||
| Parent references resolve | Read each AGENTS.md, check `<!-- Parent: -->` path exists | Fix path or remove orphan |
|
||||
| No orphaned AGENTS.md | Compare AGENTS.md locations to directory structure | Delete orphaned files |
|
||||
| Completeness | List all directories, check for AGENTS.md | Generate missing files |
|
||||
| Timestamps current | Check `<!-- Generated: -->` dates | Regenerate outdated files |
|
||||
|
||||
Validation script pattern:
|
||||
```bash
|
||||
# Find all AGENTS.md files
|
||||
find . -name "AGENTS.md" -type f
|
||||
|
||||
# Check parent references
|
||||
grep -r "<!-- Parent:" --include="AGENTS.md" .
|
||||
```
|
||||
|
||||
## Smart Delegation
|
||||
|
||||
| Task | Agent |
|
||||
|------|-------|
|
||||
| Directory mapping | `explore` |
|
||||
| File analysis | `architect` |
|
||||
| Content generation | `writer` |
|
||||
| AGENTS.md writes | `writer` |
|
||||
|
||||
## Empty Directory Handling
|
||||
|
||||
When encountering empty or near-empty directories:
|
||||
|
||||
| Condition | Action |
|
||||
|-----------|--------|
|
||||
| No files, no subdirectories | **Skip** - do not create AGENTS.md |
|
||||
| No files, has subdirectories | Create minimal AGENTS.md with subdirectory listing only |
|
||||
| Has only generated files (*.min.js, *.map) | Skip or minimal AGENTS.md |
|
||||
| Has only config files | Create AGENTS.md describing configuration purpose |
|
||||
|
||||
Example minimal AGENTS.md for directory-only containers:
|
||||
```markdown
|
||||
<!-- Parent: ../AGENTS.md -->
|
||||
# {Directory Name}
|
||||
|
||||
## Purpose
|
||||
Container directory for organizing related modules.
|
||||
|
||||
## Subdirectories
|
||||
| Directory | Purpose |
|
||||
|-----------|---------|
|
||||
| `subdir/` | Description (see `subdir/AGENTS.md`) |
|
||||
```
|
||||
|
||||
## Parallelization Rules
|
||||
|
||||
1. **Same-level directories**: Process in parallel
|
||||
2. **Different levels**: Sequential (parent first)
|
||||
3. **Large directories**: Spawn dedicated agent per directory
|
||||
4. **Small directories**: Batch multiple into one agent
|
||||
|
||||
## Quality Standards
|
||||
|
||||
### Must Include
|
||||
- [ ] Accurate file descriptions
|
||||
- [ ] Correct parent references
|
||||
- [ ] Subdirectory links
|
||||
- [ ] AI agent instructions
|
||||
|
||||
### Must Avoid
|
||||
- [ ] Generic boilerplate
|
||||
- [ ] Incorrect file names
|
||||
- [ ] Broken parent references
|
||||
- [ ] Missing important files
|
||||
|
||||
## Example Output
|
||||
|
||||
### Root AGENTS.md
|
||||
```markdown
|
||||
<!-- Generated: 2024-01-15 | Updated: 2024-01-15 -->
|
||||
|
||||
# my-project
|
||||
|
||||
## Purpose
|
||||
A web application for managing user tasks with real-time collaboration features.
|
||||
|
||||
## Key Files
|
||||
| File | Description |
|
||||
|------|-------------|
|
||||
| `package.json` | Project dependencies and scripts |
|
||||
| `tsconfig.json` | TypeScript configuration |
|
||||
| `.env.example` | Environment variable template |
|
||||
|
||||
## Subdirectories
|
||||
| Directory | Purpose |
|
||||
|-----------|---------|
|
||||
| `src/` | Application source code (see `src/AGENTS.md`) |
|
||||
| `docs/` | Documentation (see `docs/AGENTS.md`) |
|
||||
| `tests/` | Test suites (see `tests/AGENTS.md`) |
|
||||
|
||||
## For AI Agents
|
||||
|
||||
### Working In This Directory
|
||||
- Always install dependencies after modifying the project manifest
|
||||
- Use TypeScript strict mode
|
||||
- Follow ESLint rules
|
||||
|
||||
### Testing Requirements
|
||||
- Run tests before committing
|
||||
- Ensure >80% coverage
|
||||
|
||||
### Common Patterns
|
||||
- Use barrel exports (index.ts)
|
||||
- Prefer functional components
|
||||
|
||||
## Dependencies
|
||||
|
||||
### External
|
||||
- React 18.x - UI framework
|
||||
- TypeScript 5.x - Type safety
|
||||
- Vite - Build tool
|
||||
|
||||
<!-- MANUAL: Custom project notes can be added below -->
|
||||
```
|
||||
|
||||
### Nested AGENTS.md
|
||||
```markdown
|
||||
<!-- Parent: ../AGENTS.md -->
|
||||
<!-- Generated: 2024-01-15 | Updated: 2024-01-15 -->
|
||||
|
||||
# components
|
||||
|
||||
## Purpose
|
||||
Reusable React components organized by feature and complexity.
|
||||
|
||||
## Key Files
|
||||
| File | Description |
|
||||
|------|-------------|
|
||||
| `index.ts` | Barrel export for all components |
|
||||
| `Button.tsx` | Primary button component |
|
||||
| `Modal.tsx` | Modal dialog component |
|
||||
|
||||
## Subdirectories
|
||||
| Directory | Purpose |
|
||||
|-----------|---------|
|
||||
| `forms/` | Form-related components (see `forms/AGENTS.md`) |
|
||||
| `layout/` | Layout components (see `layout/AGENTS.md`) |
|
||||
|
||||
## For AI Agents
|
||||
|
||||
### Working In This Directory
|
||||
- Each component has its own file
|
||||
- Use CSS modules for styling
|
||||
- Export via index.ts
|
||||
|
||||
### Testing Requirements
|
||||
- Unit tests in `__tests__/` subdirectory
|
||||
- Use React Testing Library
|
||||
|
||||
### Common Patterns
|
||||
- Props interfaces defined above component
|
||||
- Use forwardRef for DOM-exposing components
|
||||
|
||||
## Dependencies
|
||||
|
||||
### Internal
|
||||
- `src/hooks/` - Custom hooks used by components
|
||||
- `src/utils/` - Utility functions
|
||||
|
||||
### External
|
||||
- `clsx` - Conditional class names
|
||||
- `lucide-react` - Icons
|
||||
|
||||
<!-- MANUAL: -->
|
||||
```
|
||||
|
||||
## Triggering Update Mode
|
||||
|
||||
When running on an existing codebase with AGENTS.md files:
|
||||
|
||||
1. Detect existing files first
|
||||
2. Read and parse existing content
|
||||
3. Analyze current directory state
|
||||
4. Generate diff between existing and current
|
||||
5. Apply updates while preserving manual sections
|
||||
|
||||
## Performance Considerations
|
||||
|
||||
- **Cache directory listings** - Don't re-scan same directories
|
||||
- **Batch small directories** - Process multiple at once
|
||||
- **Skip unchanged** - If directory hasn't changed, skip regeneration
|
||||
- **Parallel writes** - Multiple agents writing different files simultaneously
|
||||
Reference in new issue
Block a user