@pshch/gary-the-gardener 1.2.0

package/_gs-gardener/core/workflows/maintain/workflow.md

@@ -0,0 +1,293 @@
+# Garden Workflow
+
+> Find and fix documentation issues: staleness, broken links, orphaned files, coverage gaps
+
+## Instructions
+
+### Phase 1: Brief Introduction
+
+Display quick orientation before starting scan:
+
+```markdown
+🪴 **Garden Maintenance Time!**
+
+I'll scan your documentation for 4 types of issues:
+
+1. 🐛 **Staleness** - docs don't match current code
+   Example: Tech stack lists "webpack" but you're using "vite"
+
+2. 💔 **Broken Links** - references to missing files
+   Example: AGENTS.md links to docs/API.md but file doesn't exist
+
+3. 🌱 **Orphaned Files** - files nothing links to
+   Example: docs/DEPLOYMENT.md exists but isn't in AGENTS.md
+
+4. 🪨 **Coverage Gaps** - important areas undocumented
+   Example: Authentication system exists but has no docs
+
+**What to expect:**
+- Comprehensive scan (may take a minute for large repos)
+- Categorized report: 🔴 Critical, 🟡 Medium, 🟢 Minor, 🪨 Gaps
+- I'll ask before making any changes: All/Select/No
+
+Starting scan now... 🔍
+
+---
+💡 Want details on how I fix each type? Ask "explain the process"
+```
+
+Then immediately proceed to Phase 2 (scanning).
+
+### Phase 2: Comprehensive Scan
+Scan all documentation for issues:
+
+1. **Read all documentation files:**
+   - AGENTS.md
+   - All wrapper files (CLAUDE.md, .github/copilot-instructions.md, .cursor/rules/agents.mdc, .junie/guidelines.md)
+   - All files in docs/ directory
+   - README.md (if exists)
+
+2. **Scan the codebase for context:**
+   - Current dependencies (package.json, etc.)
+   - Current directory structure
+   - Current development commands
+
+### Phase 3: Issue Detection
+Check for four types of issues:
+
+#### 1. Staleness
+Documentation that doesn't match current reality:
+- Tech stack mentions removed dependencies
+- Commands reference scripts that no longer exist
+- Entry points reference files that have moved/been deleted
+- Architecture description doesn't match current structure
+
+#### 2. Cross-Link Integrity
+Broken references between files:
+- AGENTS.md references docs/SECURITY.md, but file doesn't exist
+- Wrapper files don't reference AGENTS.md correctly
+- Dead links to external resources
+- References to non-existent sections
+
+#### 3. Orphaned Files
+Documentation files that nothing links to:
+- Files in docs/ that aren't mentioned in AGENTS.md's Further Reading
+- No way for agents to discover these files
+- Potentially outdated or forgotten documentation
+
+#### 4. Coverage Gaps
+Important areas with no documentation:
+- New major features added but not documented
+- Complex modules with no architecture docs
+- Testing setup exists but not documented
+- Deployment process exists but not documented
+
+### Phase 4: Categorize and Prioritize Findings
+Organize findings by severity with garden metaphors:
+
+```markdown
+## 🪴 Garden Inspection Report
+
+I've walked through your documentation garden with my pruning shears! ✂️
+
+### 🔴 Critical Issues (urgent weeds! 🐛)
+These issues break functionality or cause confusion:
+- AGENTS.md references docs/ARCHITECTURE.md, but file doesn't exist
+- CLAUDE.md is empty - agents have no nourishment! 🍂
+
+### 🟡 Medium Issues (needs tending 💧)
+These issues cause mild confusion or staleness:
+- AGENTS.md lists "redux" in tech stack, but it's not in package.json (dead branch!)
+- docs/API.md exists but isn't linked from AGENTS.md (orphaned seedling 🌱)
+
+### 🟢 Minor Issues (nice to tidy up)
+Small improvements:
+- README.md is very minimal, could link to AGENTS.md for AI context
+- Some external links in docs/ could be updated to latest versions
+
+### 🪨 Coverage Gaps (areas needing planting)
+Areas that could use documentation:
+- Authentication system (src/auth/) - no docs
+- New GraphQL API - AGENTS.md still mentions REST
+- Testing strategy - tests exist but not documented
+
+---
+
+**Summary:**
+- Critical: 2 🐛
+- Medium: 2 💧
+- Minor: 2 ✨
+- Coverage gaps: 3 🪨
+```
+
+Show report to user and ask: "Would you like me to fix these issues? (All/Select/No)"
+
+### Phase 5: Progressive Disclosure (Optional)
+
+**NOTE:** This phase is OPTIONAL - only show if user asks during the workflow.
+
+If user asks "how does this work?", "explain the process", "how do you fix {issue_type}", or similar:
+
+Display detailed fixing process:
+
+```markdown
+## 🛠️ How I Fix Issues (Detailed Process)
+
+### For Staleness 🐛
+1. Update docs to match current reality
+2. Remove mentions of deleted dependencies
+3. Update commands to match current scripts
+4. Fix file paths that changed
+
+### For Broken Links 💔
+1. If target should exist but doesn't → ask if I should create or remove reference
+2. If link path is wrong → fix the path
+3. If external link is dead → ask for updated link or remove
+
+### For Orphaned Files 🌱
+Ask you: "docs/API.md exists but isn't linked. Should I:
+  - Add to AGENTS.md Further Reading section?
+  - Keep unlisted (internal doc)?
+  - Delete it (outdated)?"
+
+### For Coverage Gaps 🪨
+Just report - don't invent documentation.
+Suggest workflow: "Run `/garden-extend` → Domain Knowledge to document this"
+
+---
+
+Now, back to your report...
+```
+
+Then continue with the user's response to the fix question.
+
+### Phase 6: Fix Issues
+Based on user response:
+
+#### If "All":
+Fix all critical and medium issues automatically. Report minor issues and coverage gaps for user to handle.
+
+#### If "Select":
+Present each issue and ask: "Fix this? (Yes/No/Skip remaining)"
+
+#### If "No":
+Just report findings, don't fix anything.
+
+#### Fixing Process:
+
+**For Staleness:**
+1. Update documentation to match current reality
+2. Remove mentions of deleted dependencies
+3. Update commands to match current scripts
+4. Fix file paths that have changed
+
+**For Broken Links:**
+1. If target file should exist but doesn't - ask user if it should be created or reference removed
+2. If link is wrong - fix the path
+3. If external link is dead - ask user for updated link or remove
+
+**For Orphaned Files:**
+1. Ask user: "docs/API.md exists but isn't linked from AGENTS.md. Should I:
+   - Add it to Further Reading section
+   - Keep it unlisted (internal doc)
+   - Delete it (outdated)"
+
+**For Coverage Gaps:**
+1. Just report - don't try to write documentation without user input
+2. Suggest which workflow to use: "To document the auth system, run `/garden-extend` and select Domain Knowledge"
+
+### Phase 7: Verification and Report
+After fixes:
+
+1. **Verify fixes were applied:**
+   - Re-read modified files
+   - Confirm links work
+   - Confirm staleness fixed
+
+2. **Display summary:**
+   ```markdown
+   ✨🌻 Garden Maintenance Complete!
+
+   **Fixed (weeds pulled! 🐛):**
+   - AGENTS.md - removed redux reference (stale dependency cleared) 🍂
+   - AGENTS.md - added link to docs/API.md in Further Reading (orphan adopted!) 🌱
+   - docs/ARCHITECTURE.md - created stub (filled the gap!) 🏗️
+   - .github/copilot-instructions.md - added AGENTS.md reference (connected!) 🪴
+
+   **Remaining issues (need your input):**
+   - Authentication system (src/auth/) - no documentation 🪨
+   - GraphQL API not documented (currently mentions REST) 🪨
+
+   **Suggestions:**
+   - Run `/garden-extend` → Domain Knowledge to document the auth system 🌱
+   - Run `/garden-audit` to comprehensively update tech stack and architecture 🔍
+
+   Your documentation garden is healthier! 🌿🪴
+   ```
+
+## Critical Rules
+- NEVER invent documentation content - for coverage gaps, just report and suggest workflows
+- ALWAYS show findings before fixing - gardening should be transparent
+- Ask before deleting anything - what looks orphaned might be intentional
+- Prioritize critical issues (broken references, missing files) over minor staleness
+- When fixing staleness, verify against actual codebase - don't guess
+- If uncertain about a fix, ask the user before applying
+- Keep AGENTS.md under 150 lines - if fixes would exceed this, suggest moving content to docs/
+- After fixing, suggest next steps for remaining issues
+
+## Gardening Philosophy
+Like real gardening:
+- Spot weeds (staleness, broken links) and remove them
+- Prune overgrowth (verbose docs that could be concise)
+- Plant new growth (suggest what's missing, but don't invent)
+- Water and nurture (ensure links work, references are clear)
+
+## Example Session
+```
+User: GD (selects Garden from menu)
+
+Gary: 🪴 Garden Maintenance Time!
+
+I'll scan your documentation for 4 types of issues:
+1. 🐛 Staleness - docs don't match current code
+2. 💔 Broken Links - references to missing files
+3. 🌱 Orphaned Files - files nothing links to
+4. 🪨 Coverage Gaps - important areas undocumented
+
+What to expect:
+- Comprehensive scan (may take a minute)
+- Categorized report: 🔴 Critical, 🟡 Medium, 🟢 Minor, 🪨 Gaps
+- I'll ask before making any changes: All/Select/No
+
+Starting scan now... 🔍
+
+---
+
+[Scans all documentation]
+
+Gary: I've completed my inspection. Here's what I found:
+
+## 🪴 Garden Inspection Report
+
+### 🔴 Critical Issues
+- AGENTS.md references docs/ARCHITECTURE.md, but file doesn't exist
+
+### 🟡 Medium Issues
+- Tech stack mentions "webpack", but package.json uses "vite"
+- docs/DEPLOYMENT.md exists but isn't linked from AGENTS.md
+
+Would you like me to fix these issues? (All/Select/No)
+
+User: All
+
+Gary: [Fixes critical and medium issues]
+
+✨ Garden Maintenance Complete! I've pulled the weeds and tidied up your documentation.
+
+Fixed:
+- Created docs/ARCHITECTURE.md stub (was missing)
+- Updated tech stack (webpack → vite)
+- Linked docs/DEPLOYMENT.md in AGENTS.md
+
+Your documentation garden is looking healthy! 🌱
+```

package/_gs-gardener/core/workflows/references/workflow.md

@@ -0,0 +1,162 @@
+# References Workflow
+
+> Fetch and manage dependency reference documentation (llms.txt files)
+
+## Instructions
+
+### Phase 1: Discovery
+1. **Identify project dependencies:**
+   - Check package.json (Node.js) for dependencies
+   - Check Cargo.toml (Rust) for dependencies
+   - Check pyproject.toml or requirements.txt (Python) for dependencies
+   - Check go.mod (Go) for dependencies
+   - Check composer.json (PHP) for dependencies
+
+2. **Focus on key frameworks and libraries:**
+   - Not every dependency needs documentation
+   - Prioritize: frameworks, ORMs, major libraries (React, Next.js, Django, etc.)
+   - Skip: utilities, tiny packages, internal packages
+
+3. **Check existing references:**
+   - List files in docs/references/ (if directory exists)
+   - Note which dependencies already have reference docs
+
+### Phase 2: Check for llms.txt Availability
+For each key dependency identified:
+
+1. **Check if the project publishes llms.txt or AI-optimized docs:**
+   - Look for {package-website}/llms.txt
+   - Look for {package-docs-site}/llms.txt or /ai.txt
+   - Check package README for AI documentation links
+   - Example: https://nextjs.org/llms.txt
+
+2. **Create a report:**
+   ```markdown
+   ## Key Dependencies
+
+   | Package | Version | llms.txt Available | URL |
+   |---------|---------|-------------------|-----|
+   | next | 14.0.0 | ✅ | https://nextjs.org/llms.txt |
+   | react | 18.2.0 | ❌ | - |
+   | prisma | 5.0.0 | ✅ | https://prisma.io/llms.txt |
+   | tailwindcss | 3.3.0 | ❌ | - |
+   ```
+
+### Phase 3: Report Findings
+Display the report to the user:
+
+```markdown
+## 📚 Reference Documentation Report
+
+I've scanned your dependencies and checked for AI-optimized documentation.
+
+### Available References (can be fetched)
+- next (14.0.0) - https://nextjs.org/llms.txt
+- prisma (5.0.0) - https://prisma.io/llms.txt
+
+### No AI Documentation Found
+- react (18.2.0) - no llms.txt available
+- tailwindcss (3.3.0) - no llms.txt available
+
+### Already in docs/references/
+- next-llms.txt (last updated: 2024-01-15)
+
+Would you like me to fetch and store the available references? (Yes/No)
+```
+
+### Phase 4: Fetch and Store
+**Only if user approves:**
+
+For each available reference:
+
+1. **Fetch the llms.txt content:**
+   - Use WebFetch to retrieve the URL
+   - Handle errors gracefully (404, timeout, etc.)
+
+2. **Store in docs/references/:**
+   - Create docs/references/ directory if it doesn't exist
+   - Save as {package-name}-llms.txt
+   - Example: docs/references/next-llms.txt
+
+3. **Add metadata header:**
+   ```markdown
+   # Next.js Reference Documentation
+   # Source: https://nextjs.org/llms.txt
+   # Fetched: 2024-02-15
+   # Version: 14.0.0
+
+   [original llms.txt content follows]
+   ```
+
+4. **Track what was fetched:**
+   - Keep a list of successful fetches
+   - Note any failures
+
+### Phase 5: Update AGENTS.md
+1. **Check if AGENTS.md has a "Further Reading" section**
+2. **Add or update the references line:**
+   ```markdown
+   ## Further Reading
+   - `docs/references/` — AI-optimized docs for key dependencies
+   ```
+
+3. **Display summary to user:**
+   ```markdown
+   ✨📚 Reference Documentation Harvested!
+
+   Fetched and stored:
+   - docs/references/next-llms.txt (28 KB) 🥕
+   - docs/references/prisma-llms.txt (42 KB) 🥕
+
+   Failed to fetch:
+   - None
+
+   Updated:
+   - AGENTS.md - added/updated references pointer 🌱
+
+   These reference docs are now available to AI agents - fresh knowledge harvested! 🌾🪴
+   ```
+
+## Critical Rules
+- NEVER fetch documentation for ALL dependencies - only key frameworks/libraries
+- Ask user to confirm before fetching (especially if there are many references)
+- Handle fetch failures gracefully - network issues, 404s, etc.
+- Add metadata to each fetched file (source URL, fetch date, version)
+- Don't bloat AGENTS.md - just add a one-line pointer to docs/references/
+- If a reference already exists and is recent (< 30 days old), ask user before re-fetching
+- Respect rate limits - don't hammer servers with requests
+- Store files with clear naming: {package-name}-llms.txt
+
+## Maintenance Note
+References should be refreshed periodically (e.g., when dependency versions change). User can re-run this workflow to update references.
+
+## Example Session
+```
+User: RE (selects References from menu)
+
+Gary: 📚 Let me check your dependencies for AI-optimized documentation...
+
+[Scans package.json and checks for llms.txt]
+
+Gary: I've found reference documentation for 2 of your key dependencies:
+
+## 📚 Reference Documentation Report
+
+### Available References
+- next (14.0.0) - https://nextjs.org/llms.txt
+- prisma (5.0.0) - https://prisma.io/llms.txt
+
+### No AI Documentation Found
+- react (18.2.0)
+- tailwindcss (3.3.0)
+
+Would you like me to fetch and store the available references?
+
+User: Yes
+
+Gary: [Fetches and stores files]
+
+✨ Reference Documentation Updated!
+
+I've added 2 reference docs to your garden (70 KB total). These provide AI agents with detailed context about Next.js and Prisma.
+```

package/_gs-gardener/core/workflows/scaffold/workflow.md

@@ -0,0 +1,225 @@
+# Scaffold Workflow
+
+> Set up the docs/ knowledge base directory structure
+
+## Instructions
+
+### Phase 1: Check Current State
+1. **Check if docs/ directory exists:**
+   - If yes: list existing files
+   - If no: prepare to create
+
+2. **Check if any documentation already exists:**
+   - docs/ARCHITECTURE.md
+   - docs/core-beliefs.md
+   - docs/SECURITY.md
+   - docs/STYLE.md
+   - docs/DOMAIN.md
+   - docs/references/ directory
+
+3. **Read AGENTS.md to understand if scaffold is needed:**
+   - Does AGENTS.md have a "Further Reading" section?
+   - Are there pointers to docs/ files that don't exist?
+
+### Phase 2: Plan the Scaffold
+Determine what needs to be created:
+
+```markdown
+## 🏗️  Scaffold Plan
+
+**Will create:**
+- docs/ - main documentation directory
+- docs/ARCHITECTURE.md - detailed architecture and domain boundaries
+- docs/core-beliefs.md - golden principles stub
+- docs/references/ - directory for llms.txt files
+
+**Already exists:**
+- AGENTS.md - source of truth (no changes needed)
+
+**Purpose:**
+This structure supports progressive disclosure - AGENTS.md stays compact (~150 lines),
+deep content lives in docs/, and reference documentation is organized separately.
+```
+
+Show plan to user and ask: "Ready to scaffold your documentation structure? (Yes/No)"
+
+### Phase 3: Create Directory and Files
+**Only if user approves:**
+
+1. **Create directories:**
+   ```bash
+   mkdir -p docs/references
+   ```
+
+2. **Create docs/ARCHITECTURE.md:**
+   ```markdown
+   # Architecture
+
+   > Detailed architecture, domain boundaries, and system design
+
+   ## Overview
+   {Extract relevant architecture details from AGENTS.md if they exist, or create stub}
+
+   ## Entry Points
+   {List main entry files, server startup, etc.}
+
+   ## Domain Boundaries
+   {Describe how the codebase is organized - features, layers, modules}
+
+   ## Key Patterns
+   {Document architectural patterns - MVC, hexagonal, microservices, etc.}
+
+   ## Data Flow
+   {Describe how data moves through the system}
+
+   ## External Dependencies
+   {Document third-party integrations, APIs, databases}
+
+   ---
+   *This file contains detailed architecture that doesn't fit in AGENTS.md's 150-line budget.*
+   *Keep this updated as the architecture evolves.*
+   ```
+
+3. **Create docs/core-beliefs.md:**
+   ```markdown
+   # Core Beliefs
+
+   > Golden principles and operating rules for this repository
+
+   ## Purpose
+   This file captures the "always do it this way" mechanical rules that keep the codebase
+   consistent and agent-legible.
+
+   ## How to Populate
+   Use `/gardener` → [EX] Extend → Golden Principles to populate this file through a guided interview.
+
+   ## Examples of Golden Principles
+   - "Prefer shared utility packages over hand-rolled helpers"
+   - "Validate data at boundaries, never probe shapes"
+   - "Tests live alongside source files as *.test.ts"
+   - "New features require documentation before merge"
+
+   ---
+   *To add your golden principles, run: `/gs-extend` and select "Golden Principles"*
+   ```
+
+4. **Create docs/references/ directory:**
+   - Create empty directory with README
+   - Add docs/references/README.md:
+   ```markdown
+   # Reference Documentation
+
+   This directory contains AI-optimized documentation (llms.txt files) for key dependencies.
+
+   ## How to Populate
+   Use `/gardener` → [RE] References to fetch and store llms.txt files for your frameworks and libraries.
+
+   ## Structure
+   Files are named: `{package-name}-llms.txt`
+
+   Examples:
+   - next-llms.txt
+   - react-query-llms.txt
+   - prisma-llms.txt
+
+   ---
+   *To fetch reference docs, run: `/gs-references`*
+   ```
+
+### Phase 4: Update AGENTS.md
+Add or update the "Further Reading" section in AGENTS.md:
+
+```markdown
+## Further Reading
+- `docs/ARCHITECTURE.md` — detailed architecture and domain boundaries
+- `docs/core-beliefs.md` — golden principles and operating rules
+- `docs/references/` — AI-optimized docs for key dependencies
+```
+
+If "Further Reading" section doesn't exist, add it at the end of AGENTS.md.
+
+Keep additions concise - just pointers, not content.
+
+### Phase 5: Verification and Report
+1. **Verify all files were created:**
+   - Check docs/ directory exists
+   - Check each file exists and has content
+   - Check docs/references/ directory exists
+
+2. **Display summary:**
+   ```markdown
+   ✨🌱 Documentation Garden Scaffolded!
+
+   I've planted the foundation for your documentation:
+   ```
+   docs/
+   ├── ARCHITECTURE.md (for detailed architecture) 🏗️
+   ├── core-beliefs.md (for golden principles) 💎
+   └── references/ (for dependency docs) 📚
+   ```
+
+   Updated:
+   - AGENTS.md - added Further Reading section with pointers 🌱
+
+   **Next steps:**
+   1. Run `/garden-extend` to plant golden principles, guardrails, or domain knowledge 🌱
+   2. Run `/garden-references` to harvest llms.txt files for your dependencies 🥕
+   3. Expand docs/ARCHITECTURE.md with detailed architecture (if needed beyond AGENTS.md)
+
+   Your garden bed is prepared and ready for planting! 🌿🪴
+   ```
+
+## Critical Rules
+- NEVER bloat AGENTS.md with content - just add pointers in Further Reading
+- Create stub files with clear "how to populate" instructions, not invented content
+- If docs/ already exists with files, don't overwrite - report what exists and ask user
+- Keep ARCHITECTURE.md focused on architecture, not general repo information (that's in AGENTS.md)
+- docs/references/ README should explain the pattern, not list every possible dependency
+- After scaffolding, suggest next steps (extend, references) so user knows what to do
+
+## If Docs Already Exist
+If user runs scaffold when docs/ already exists:
+
+```markdown
+I see you already have a docs/ directory with some files:
+- docs/README.md
+- docs/setup-guide.md
+
+Would you like me to:
+1. Add missing recommended files (ARCHITECTURE.md, core-beliefs.md, references/)
+2. Skip (your documentation structure is custom)
+
+Choose: 1 or 2
+```
+
+Respect user's existing structure - don't force the pattern if they have their own.
+
+## Example Session
+```
+User: SC (selects Scaffold from menu)
+
+Gary: 🏗️  Let me help you set up a documentation foundation!
+
+Currently, your project has:
+- AGENTS.md (compact index)
+- No docs/ directory
+
+I'll create a docs/ structure following the progressive disclosure pattern - AGENTS.md stays compact, deep content lives in docs/.
+
+Ready to scaffold your documentation structure?
+
+User: Yes
+
+Gary: [Creates directories and files]
+
+✨ Documentation Garden Scaffolded!
+
+I've planted the foundation for your documentation:
+- docs/ARCHITECTURE.md (for detailed architecture)
+- docs/core-beliefs.md (for golden principles)
+- docs/references/ (for dependency docs)
+
+Next, run `/gs-extend` to populate golden principles, or `/gs-references` to fetch dependency documentation.
+
+Your garden is taking shape! 🌱
+```