Randify.pro/.sisyphus/plans/init-deep.md

# init-deep: Generate Hierarchical AGENTS.md

## TL;DR

> Generate hierarchical AGENTS.md knowledge base for Randify.pro codebase.
>
> **Deliverables**:
> - `./AGENTS.md` (root knowledge base)
> - `src/components/generators/AGENTS.md` (generators domain)
>
> **Estimated Effort**: Short
> **Parallel Execution**: YES - 2 files in parallel

---

## Context

Randify.pro is a bilingual (EN/RU) static site on Astro 4 + Tailwind CSS 4 with 30 random-value generators. The codebase has specific architectural constraints documented in `CLAUDE.md` and discovered through comprehensive audit.

### Research Findings (from explore agents)

**Project Structure:**
- 270 total files, depth 4, 5 large files (>500 lines)
- 30 generators (not 10 as stated in CLAUDE.md — documentation drift)
- 62 page files (EN + RU duplicates)
- Content collection defined but bypassed (import.meta.glob used instead)

**Entry Points:**
- `astro.config.mjs` — Astro 4, i18n routing, Tailwind v4 Vite plugin, sitemap
- `src/pages/index.astro` — homepage
- `src/layouts/BaseLayout.astro` — root layout with theme, analytics, SW registration
- `src/layouts/GeneratorLayout.astro` — generator wrapper (breadcrumb, ad, SEO, FAQ)

**Key Conventions:**
- ESM only, `@/*` → `src/*`
- i18n: `Astro.currentLocale` / `document.documentElement.lang` + `useT(lang)`
- Tailwind v4 theme in `BaseLayout.astro` global style (no tailwind.config)
- Dark theme: `bg-zinc-950`, accent `#534AB7`
- Generator JSON validated by strict Zod schema (`.strict()` — unknown fields fail build)
- Tests co-located: `src/**/*.test.ts` (only 1 test exists: `dice-engine.test.ts`)

**Anti-Patterns from CLAUDE.md:**
1. Never use shared dynamic `[slug].astro` for Russian pages (bundling issue)
2. Every generator must be created in EN + RU simultaneously
3. All UI strings in `translations.ts` — no hardcoding
4. No client-side router
5. No unknown fields in generator JSON

**Build/CI:**
- GitHub Actions + rsync to reg.ru
- No tests/lint in CI despite scripts existing
- Dockerfile for local preview only (not used in CI)
- nginx:alpine, no HEALTHCHECK

---

## Work Objectives

### Core Objective
Generate concise, telegraphic AGENTS.md files that capture project-specific knowledge without generic advice.

### Concrete Deliverables
- `./AGENTS.md` (root, 50-150 lines)
- `src/components/generators/AGENTS.md` (subdirectory, 30-80 lines)

### Must Have
- Project overview with stack
- Directory structure tree
- "WHERE TO LOOK" table mapping tasks to locations
- Conventions (deviations from standard only)
- Anti-patterns specific to this project
- Commands (dev/test/build)
- Notes with known issues

### Must NOT Have
- Generic advice applicable to all projects
- Redundancy between parent and child AGENTS.md
- Boilerplate that doesn't help navigate the codebase

---

## Verification Strategy

### QA Scenarios

**Scenario: Root AGENTS.md completeness**
Tool: Read
Steps:
  1. Read `./AGENTS.md`
  2. Verify it contains: OVERVIEW, STRUCTURE, WHERE TO LOOK, CONVENTIONS, ANTI-PATTERNS, COMMANDS, NOTES
  3. Verify length is 50-150 lines
  4. Verify no generic advice (e.g., "use version control", "write tests")
Expected Result: File exists with all required sections, telegraphic style, project-specific content only
Evidence: .sisyphus/evidence/init-deep-root-agents.md

**Scenario: Generators AGENTS.md completeness**
Tool: Read
Steps:
  1. Read `src/components/generators/AGENTS.md`
  2. Verify it contains: OVERVIEW, STRUCTURE, WHERE TO LOOK, CONVENTIONS, ANTI-PATTERNS, NOTES
  3. Verify length is 30-80 lines
  4. Verify no duplication of parent content (e.g., doesn't repeat stack overview)
Expected Result: File exists with generator-specific content, no parent redundancy
Evidence: .sisyphus/evidence/init-deep-generators-agents.md

**Scenario: No drift from actual codebase**
Tool: Bash (grep)
Steps:
  1. grep -c "generators" ./AGENTS.md → should reference 30 generators
  2. grep "Math.random" ./AGENTS.md → should note known discrepancy
  3. grep "dice-engine" src/components/generators/AGENTS.md → should mention import pattern
Expected Result: AGENTS.md reflects actual codebase state, not outdated docs
Evidence: .sisyphus/evidence/init-deep-drift-check.txt

---

## Execution Strategy

### Parallel Execution Waves

```
Wave 1 (Start Immediately - 2 tasks in parallel):
├── Task 1: Generate root AGENTS.md
└── Task 2: Generate generators/AGENTS.md
```

### Agent Dispatch Summary

- **T1**: `writing` category — Generate root AGENTS.md
- **T2**: `writing` category — Generate generators/AGENTS.md

---

## TODOs

- [ ] 1. Generate root AGENTS.md

  **What to do**:
  - Create `./AGENTS.md` with all required sections
  - Include project-specific knowledge from research findings
  - Maintain telegraphic style (50-150 lines)
  - Include known issues: 30 generators (not 10), Math.random discrepancy, dice engine duplication, CI doesn't run tests

  **Recommended Agent Profile**:
  - **Category**: `writing`
  - **Skills**: []

  **Parallelization**:
  - **Can Run In Parallel**: YES (with Task 2)
  - **Blocks**: Task 3 (review)

  **Acceptance Criteria**:
  - [ ] File created: `./AGENTS.md`
  - [ ] Contains all sections: OVERVIEW, STRUCTURE, WHERE TO LOOK, CONVENTIONS, ANTI-PATTERNS, COMMANDS, NOTES
  - [ ] Length: 50-150 lines
  - [ ] No generic advice
  - [ ] References 30 generators (not outdated 10)
  - [ ] Notes Privacy Policy / Math.random discrepancy

  **QA Scenarios**:
  ```
  Scenario: Root AGENTS.md structure
    Tool: Read
    Steps:
      1. Read ./AGENTS.md
      2. Count lines (should be 50-150)
      3. Verify all required sections present
    Expected Result: Complete, concise, project-specific
    Evidence: .sisyphus/evidence/init-deep-root-check.txt
  ```

- [ ] 2. Generate generators/AGENTS.md

  **What to do**:
  - Create `src/components/generators/AGENTS.md` with generator-domain knowledge
  - Focus on: conventions for creating generators, anti-patterns specific to generator components
  - Maintain telegraphic style (30-80 lines)
  - Never repeat parent content (no stack overview, no global commands)

  **Recommended Agent Profile**:
  - **Category**: `writing`
  - **Skills**: []

  **Parallelization**:
  - **Can Run In Parallel**: YES (with Task 1)
  - **Blocks**: Task 3 (review)

  **Acceptance Criteria**:
  - [ ] File created: `src/components/generators/AGENTS.md`
  - [ ] Contains: OVERVIEW, STRUCTURE, WHERE TO LOOK, CONVENTIONS, ANTI-PATTERNS, NOTES
  - [ ] Length: 30-80 lines
  - [ ] No duplication of parent AGENTS.md content
  - [ ] Mentions dice-engine import pattern
  - [ ] Mentions 4-artifact requirement for new generators

  **QA Scenarios**:
  ```
  Scenario: Generators AGENTS.md structure
    Tool: Read
    Steps:
      1. Read src/components/generators/AGENTS.md
      2. Count lines (should be 30-80)
      3. Verify no parent content duplication
    Expected Result: Domain-specific, concise
    Evidence: .sisyphus/evidence/init-deep-generators-check.txt
  ```

- [ ] 3. Review and validate both files

  **What to do**:
  - Read both AGENTS.md files
  - Check for redundancy between parent and child
  - Verify telegraphic style
  - Verify no generic advice
  - Trim if necessary

  **Recommended Agent Profile**:
  - **Category**: `quick`
  - **Skills**: []

  **Parallelization**:
  - **Can Run In Parallel**: NO (depends on Tasks 1, 2)

  **Acceptance Criteria**:
  - [ ] Both files pass review
  - [ ] No cross-file redundancy
  - [ ] Both within line limits

  **QA Scenarios**:
  ```
  Scenario: Cross-file redundancy check
    Tool: Bash (grep)
    Steps:
      1. grep "Astro 4" src/components/generators/AGENTS.md → should be empty (parent covers this)
      2. grep "npm run" src/components/generators/AGENTS.md → should be empty
    Expected Result: Child file doesn't repeat parent knowledge
    Evidence: .sisyphus/evidence/init-deep-redundancy-check.txt
  ```

---

## Final Verification Wave

- [ ] F1. **Plan Compliance Audit** — `oracle`
  Verify both AGENTS.md files exist, contain required sections, and reflect actual codebase state. Check line limits. Verify no generic advice.
  Output: `Files [2/2] | Sections [PASS/FAIL] | Line Limits [PASS/FAIL] | VERDICT`

---

## Commit Strategy

- **1**: `docs: add AGENTS.md knowledge base`
  - Files: `AGENTS.md`, `src/components/generators/AGENTS.md`

---

## Success Criteria

- [ ] Root AGENTS.md exists (50-150 lines, all sections, no generic advice)
- [ ] Generators AGENTS.md exists (30-80 lines, no parent redundancy)
- [ ] Both files reflect actual codebase state (30 generators, known issues)
- [ ] No drift from discovered conventions and anti-patterns