# Initialize Context Workflow

Create AGENTS.md from scratch for projects without documentation.

## Check Existing

```bash
test -f AGENTS.md && echo "exists" || echo "missing"
test -f CLAUDE.md && echo "claude exists" || echo "no claude"
```

If AGENTS.md exists: warn user, suggest update workflow instead. Allow override with `--force`.

If CLAUDE.md exists but AGENTS.md doesn't: migrate — rename to AGENTS.md, create CLAUDE.md symlink.

## Modes

**Automatic** (no arguments): derive everything from project analysis.

**Guided** (arguments provided): user describes the project focus, e.g. "PHP Laravel API with queue workers" or "Python data pipeline with scheduled jobs".

## Gather Context

Read available config files (skip missing):
- `package.json` — stack, scripts, dependencies
- `pyproject.toml` — Python project config
- `composer.json` — PHP project config
- `README.md` — project overview
- `.gitignore` — exclusion patterns
- Directory listing (2 levels deep)

Determine:
- Primary language/framework
- Project type: library, application, CLI tool, script collection
- Build/test/lint tools
- Architecture patterns

## Language Templates

### PHP / Laravel

```markdown
## Stack
- PHP 8.2+ with Laravel
- Composer for dependencies
- PHPUnit / Pest for testing

## Commands
- `composer install` — install dependencies
- `php artisan serve` — local dev server
- `php artisan test` — run tests
- `php artisan migrate` — run migrations
```

### Python

```markdown
## Stack
- Python 3.11+
- uv for dependency management

## Commands
- `uv sync` — install dependencies
- `uv run pytest` — run tests
- `uv run ruff check .` — lint
```

### JavaScript / TypeScript

```markdown
## Stack
- TypeScript with strict mode
- {detected package manager}

## Commands
- `{pm} install` — install dependencies
- `{pm} run build` — build
- `{pm} test` — run tests
```

### PineScript

```markdown
## Stack
- Pine Script v6 (TradingView)

## Development
- Edit in TradingView Pine Editor
- Test with bar replay and strategy tester
- No external build tools
```

### Bash / Shell

```markdown
## Stack
- Bash scripts for automation
- ShellCheck for linting

## Commands
- `shellcheck *.sh` — lint all scripts
- `chmod +x script.sh && ./script.sh` — run
```

## Generate Content

Sections to include (only if relevant):

- **Stack** — languages, frameworks, tools
- **Structure** — key directories and files
- **Commands** — build, test, lint, deploy
- **Code style** — naming, formatting, patterns
- **Constraints** — security, performance, environment

Style: terse, imperative, expert-to-expert. No fluff.

## Write

1. Write AGENTS.md with generated content
2. Create CLAUDE.md symlink: `ln -sf AGENTS.md CLAUDE.md`
3. Report: show file path, preview first 10 lines

```
✓ Created AGENTS.md
✓ Created CLAUDE.md → AGENTS.md symlink
  - Detected: Python project (pyproject.toml)
  - Sections: Stack, Structure, Commands, Code Style
```

# Update Context Files Workflow

Verify and fix AGENTS.md (and CLAUDE.md symlink) against actual codebase state.

## Step 1: Extract Verifiable Claims

Read AGENTS.md and extract every factual claim:

- File paths and directory structures
- Build, test, lint commands
- Dependency and tooling references
- Code conventions and patterns described
- Environment variables or configuration

## Step 2: Verify Claims

Check each claim against the codebase:

**Paths and structure:**
- `ls`, `tree` (2 levels) to verify directories exist
- If path changed: update. If deleted: remove section.

**Commands:**
- Check `package.json` scripts, `composer.json` scripts, `pyproject.toml` scripts, `Makefile`, `justfile`
- If command syntax changed: update. If removed: mark for removal.

**Code patterns:**
- Read actual files to verify described patterns still hold
- Update outdated patterns to match current code

## Step 3: Discover Undocumented Patterns

Scan for patterns not yet in AGENTS.md:

- Task runner recipes (justfile, Makefile, package.json scripts) not documented
- Lint/format configuration that exists but has no corresponding section
- Build/test/deploy commands with no documentation
- New directories or modules not mentioned in structure

## Step 4: Apply Updates

**If `--dry-run`:** show planned changes as diff without writing.

**If `--preserve`:** fix inaccuracies only, keep existing structure and phrasing.

**Otherwise:** reorganize for clarity, add missing sections, remove stale content.

## Step 5: Report

```
✓ Updated AGENTS.md
  - Fixed: build command npm → pnpm
  - Removed: stale reference to /old-dir
  - Added: new /api directory to structure

Suggested additions:
  - Consider documenting: jest test configuration
```

If no changes needed: `✓ AGENTS.md is up to date`

# Update CONTRIBUTING Workflow

Update existing CONTRIBUTING.md only. Never auto-create — contribution guidelines represent intentional maintainer decisions.

## Prerequisite

```bash
test -f CONTRIBUTING.md && echo "exists" || echo "missing"
```

If missing: report to user and stop. Do not create unless explicitly requested.

## Scope of Updates

**Fix** (technical accuracy):
- Outdated CLI commands (npm → pnpm, yarn → bun)
- Incorrect file paths or directory references
- Broken links to issues, templates, or docs
- Stale branch references (master → main)
- Wrong tooling references (Jest → Vitest, ESLint → Biome)

**Preserve** (policy decisions):
- Contribution policies (CLA, DCO, licensing)
- Review processes and expectations
- Code of conduct references
- Governance and maintainer decisions
- Communication channel preferences

## Workflow

1. Read existing CONTRIBUTING.md, parse structure and code blocks
2. Detect current tooling: package manager (from lock files), available scripts, branch conventions, linter/formatter config
3. Compare documented commands, paths, links against actual codebase
4. Fix technical inaccuracies while preserving structure and policies
5. Use Edit tool for targeted replacements, not full rewrites

## Adding Acknowledgements

If requested, add or update an Acknowledgements/Credits section. Place at the end, before License if present. Keep it factual — list contributors, tools, or inspirations without embellishment.

## Report

```
✓ Updated CONTRIBUTING.md
  - Fixed package manager: npm → pnpm
  - Corrected branch reference: master → main
  - Updated test command

⊘ Policy sections preserved (CLA, review process)
```

# Update README Workflow

Generate or refresh README.md based on codebase analysis.

## Guiding Principles

- Balanced, not bloated: 200-400 lines for most projects
- Show, don't tell: code examples over prose
- Every section must add value — skip empty or trivial sections
- Readers should find what they need in under 30 seconds

Target length: `--minimal` 100-200 lines, default 200-400, `--thorough` 400-600.

## Language/Stack Detection

| Signal | Stack |
|--------|-------|
| `package.json` | Node.js / TypeScript / JavaScript |
| `pyproject.toml`, `setup.py` | Python |
| `composer.json` | PHP |
| `*.pine` files | PineScript |
| `*.sh`, `Makefile` | Bash / Shell |

**Extract from config files:** name, version, description, license, dependencies, scripts, repo URL.

**Detect package manager from lock files:**
- `package-lock.json` → npm
- `pnpm-lock.yaml` → pnpm
- `yarn.lock` → yarn
- `bun.lockb` → bun
- `composer.lock` → composer
- `uv.lock` → uv
- `poetry.lock` → poetry

## Section Order

**Libraries** (exports modules, no main entry):

1. Title + badges
2. Description
3. Features (if `--preserve` or `--thorough`)
4. Installation
5. Usage with code examples
6. API Reference (`--thorough` only)
7. License

**Applications** (has entry point, runnable):

1. Title + badges
2. Description
3. Features
4. Installation / Getting Started
5. Usage
6. Configuration (if config files found)
7. Scripts / Commands
8. Project Structure (`--thorough` only)
9. License

**PineScript indicators/strategies:**

1. Title
2. Description (what it measures/trades)
3. Inputs and parameters
4. Usage (how to add to TradingView chart)
5. Logic overview
6. Alerts (if applicable)

## Section Guidelines

**Title + Badges:** Project name from config or repo name. Add badges for CI (if `.github/workflows/` exists), license, version. Skip badges for private repos.

**Description:** 1-3 sentences. Answer "what does this do?" Extract from config file description field when available.

**Features:** 3-8 bullet points for `--thorough`. Skip if obvious from description. `--minimal` omits this.

**Installation:** Show install command for detected package manager. Include `git clone` if no registry. For PHP: `composer require` or `composer install`.

**Usage:** Minimal working example (5-15 lines). Extract from tests or examples/ directory if they exist. Use proper language tags on code blocks.

**Scripts/Commands:** List from package.json scripts, composer scripts, Makefile targets. Format as table if 5+ items.

**Project Structure:** Only for `--thorough`. Show 5-10 key directories, 2 levels deep max. Skip if structure is obvious.

**Configuration:** Document if .env.example, config files exist. Show key options. Otherwise omit.

## Preserve Mode

When `--preserve` is set and README.md exists:

**Keep** (user-written): About, Features, Why X, Background, custom sections.

**Regenerate** (likely outdated): Install, Usage, Scripts, Structure, Badges, Configuration.

Merge preserved sections with regenerated ones in standard order.

## Formatting

- Sentence case headings, no emoji headers
- `##` for main sections, `###` for subsections
- Code blocks with language tags
- Tables for commands if 5+ items
- Admonitions for important notes: `> [!NOTE]` and `> [!WARNING]`
- No git operations — user reviews and commits manually