@synapta/skills 0.1.0 → 0.1.2

package/skills/repo-bootstrap/references/output-structure.md

@@ -0,0 +1,124 @@
+# Output Structure
+
+## Root File
+
+Root AGENTS.md (~50-80 lines) contains agent-optimized sections:
+
+| Section | Purpose | Format |
+|---------|---------|--------|
+| **Commands (verified)** | Executable commands with time estimates | Table with ~Time column |
+| **File Map** | Directory purposes for navigation | `dir/ -> purpose` format |
+| **Golden Samples** | Canonical patterns to follow | Table: For / Reference / Key patterns |
+| **Utilities List** | Existing helpers to reuse | Table: Need / Use / Location |
+| **Heuristics** | Quick decision rules | Table: When / Do |
+| **Boundaries** | Always/Ask/Never rules | Three-tier list |
+| **Codebase State** | Migrations, tech debt, known issues | Bullet list |
+| **Terminology** | Domain-specific terms | Table: Term / Means |
+| **Scope Index** | Links to scoped files | List with descriptions |
+
+## Scoped Files
+
+Scoped AGENTS.md files cover six core areas (per [GitHub best practices](https://github.blog/ai-and-ml/github-copilot/how-to-write-a-great-agents-md-lessons-from-over-2500-repositories/)):
+1. **Commands** - Executable build, test, lint commands
+2. **Testing** - Test conventions and execution
+3. **Project Structure** - Architecture and key files
+4. **Code Style** - Formatting and conventions
+5. **Git Workflow** - Commit/PR guidelines
+6. **Boundaries** - Always do / Ask first / Never do
+
+Additional recommended sections:
+- Overview
+- Setup/Prerequisites
+- Security
+- Good vs Bad examples
+- When stuck
+- House Rules (for scoped overrides)
+- **Approved learnings** — index entries linking to `docs/feedback/feedback_<slug>.md` (one line per learning, see [feedback-memory-schema.md](feedback-memory-schema.md))
+
+### AGENTS.md is an index, not a rule dump
+
+When session learnings are approved (via `/retro` or similar), the **prose lives in `docs/feedback/feedback_<slug>.md`** following the [feedback memory schema](feedback-memory-schema.md). AGENTS.md only carries a one-line link per learning under `## Approved learnings`. This keeps AGENTS.md compact (the agent-harness conformance rule) while preserving full audit trail in `docs/feedback/`.
+
+Place `## Approved learnings` **after `## Key Decisions` and before `## Boundaries`** in the section order, and put it **outside** any `<!-- AGENTS-GENERATED:START ... -->` markers — this section is managed by retro-skill, not by `generate-agents.sh`, so it must survive `--update` runs.
+
+If the approved-learnings index would push AGENTS.md over the harness 150-line cap (`AH-02`), prune inactive entries or move to a scoped `AGENTS.md` rather than letting the index grow unbounded.
+
+## When to Customize vs Auto-Generate
+
+### Auto-Generate These Sections
+
+These sections are factual and extractable - let scripts handle them:
+
+| Section | Why Auto-Generate |
+|---------|-------------------|
+| **Commands** | Extract from Makefile/package.json - always accurate |
+| **File Map** | Directory listing is objective |
+| **Scope Index** | Detectable from filesystem structure |
+| **Language/Framework** | Detectable from config files |
+| **Test Commands** | Extract from CI config |
+
+### Manually Curate These Sections
+
+These sections require human judgment - preserve them during updates:
+
+| Section | Why Manual |
+|---------|------------|
+| **Golden Samples** | Requires taste - which file exemplifies good patterns? |
+| **Heuristics** | Decision rules come from team experience |
+| **Boundaries** | Always/Ask/Never rules reflect team policy |
+| **Codebase State** | Tech debt awareness requires context |
+| **Terminology** | Domain knowledge is human insight |
+| **Architecture Decisions** | Why choices were made isn't extractable |
+
+### Override Best Practices
+
+When updating existing AGENTS.md files, preserve custom content:
+
+**1. Use `--update` flag:**
+```bash
+scripts/generate-agents.sh /path/to/project --update
+```
+This preserves content outside `<!-- GENERATED:START -->` / `<!-- GENERATED:END -->` markers.
+
+**2. Place custom content outside markers:**
+```markdown
+<!-- GENERATED:START -->
+## Commands (auto-generated)
+| Command | Purpose |
+|---------|---------|
+| `make test` | Run tests |
+<!-- GENERATED:END -->
+
+## Custom Heuristics (preserved)
+| When | Do |
+|------|-----|
+| Adding endpoint | Create OpenAPI spec first |
+```
+
+**3. Use scoped overrides for exceptions:**
+```
+project/
+├── AGENTS.md              # Global rules
+└── legacy/
+    └── AGENTS.md          # "Ignore linting in this directory"
+```
+
+**4. Review diffs before committing:**
+```bash
+# After regenerating
+git diff AGENTS.md
+# Ensure custom sections weren't overwritten
+```
+
+## Directory Coverage
+
+When creating AGENTS.md files, create them in ALL key directories:
+
+| Directory | Purpose |
+|-----------|---------|
+| Root | Precedence, architecture overview |
+| `Classes/` or `src/` | Source code patterns |
+| `Configuration/` or `config/` | Framework config |
+| `Documentation/` or `docs/` | Doc standards |
+| `Resources/` or `assets/` | Templates, assets |
+| `Tests/` | Testing patterns |

package/skills/repo-bootstrap/references/scripts-guide.md

@@ -0,0 +1,175 @@
+# Scripts Guide
+
+Complete reference for all AGENTS.md generator scripts.
+
+## Generating AGENTS.md Files
+
+```bash
+scripts/generate-agents.sh /path/to/project
+```
+
+Options:
+- `--dry-run` - Preview changes without writing files
+- `--verbose` - Show detailed output
+- `--style=thin` - Use thin root template (~30 lines, default)
+- `--style=verbose` - Use verbose root template (~100-200 lines)
+- `--update` - Update existing files only (preserves human edits outside generated markers)
+- `--claude-shim` - Generate CLAUDE.md that imports AGENTS.md (root only, use `--symlinks` instead)
+- `--symlinks` - Create CLAUDE.md and GEMINI.md symlinks at every level (root + subdirectories). Enables Claude Code on-demand loading and Gemini CLI native loading. **Recommended** for cross-agent compatibility.
+- `--force` - Regenerate even if files exist
+
+## Validating Structure
+
+```bash
+scripts/validate-structure.sh /path/to/project
+```
+
+Options:
+- `--check-freshness, -f` - Also check if files are up to date with git commits
+- `--verbose, -v` - Show detailed output
+
+## Checking Freshness
+
+```bash
+scripts/check-freshness.sh /path/to/project
+```
+
+This script:
+- Extracts the "Last updated" date from the AGENTS.md header
+- Checks git commits since that date for files in the relevant scope
+- Reports if there are commits that might require AGENTS.md updates
+
+Options:
+- `--verbose, -v` - Show commit details and changed files
+- `--threshold=DAYS` - Days threshold to consider stale (default: 7)
+
+Example with full validation:
+```bash
+scripts/validate-structure.sh /path/to/project --check-freshness --verbose
+```
+
+## Detecting Project Type
+
+```bash
+scripts/detect-project.sh /path/to/project
+```
+
+Detects project language, version, and build tools.
+
+## Detecting Scopes
+
+```bash
+scripts/detect-scopes.sh /path/to/project
+```
+
+Identifies directories that should have scoped AGENTS.md files.
+
+## Extracting Commands
+
+```bash
+scripts/extract-commands.sh /path/to/project
+```
+
+Extracts build commands from Makefile, package.json, composer.json, or go.mod.
+
+## Extracting Documentation
+
+```bash
+scripts/extract-documentation.sh /path/to/project
+```
+
+Extracts information from README.md, CONTRIBUTING.md, SECURITY.md, and other documentation.
+
+## Extracting Platform Files
+
+```bash
+scripts/extract-platform-files.sh /path/to/project
+```
+
+Extracts information from .github/, .gitlab/, CODEOWNERS, dependabot.yml, etc.
+
+## Extracting IDE Settings
+
+```bash
+scripts/extract-ide-settings.sh /path/to/project
+```
+
+Extracts information from .editorconfig, .vscode/, .idea/, etc.
+
+## Extracting AI Agent Configs
+
+```bash
+scripts/extract-agent-configs.sh /path/to/project
+```
+
+Extracts information from .cursor/, .claude/, copilot-instructions.md, etc.
+
+## Verifying Content Accuracy
+
+**CRITICAL: Always run this before considering AGENTS.md files complete.**
+
+```bash
+scripts/verify-content.sh /path/to/project
+```
+
+This script:
+- Checks if documented files actually exist
+- Verifies Makefile targets are real
+- Compares module/script counts against actual files
+- Reports undocumented files that should be added
+- Reports documented files that don't exist
+
+Options:
+- `--verbose, -v` - Show detailed verification output
+- `--fix` - Suggest fixes for common issues
+
+**This verification step is MANDATORY when updating existing AGENTS.md files.**
+
+## Verifying Commands Work
+
+To prevent "command rot" (documented commands that no longer work):
+
+```bash
+scripts/verify-commands.sh /path/to/project
+```
+
+This script:
+- Extracts commands from AGENTS.md tables and code blocks
+- Verifies npm/yarn scripts exist in package.json
+- Verifies make targets exist in Makefile
+- Verifies composer scripts exist in composer.json
+- Updates "Last verified" timestamp on success
+
+Options:
+- `VERBOSE=true` - Show detailed output
+- `DRY_RUN=true` - Don't update timestamp
+
+**Why this matters:** Research shows broken commands waste 500+ tokens as agents debug non-existent commands. Verified commands enable confident execution.
+
+## Post-Generation Validation Checklist
+
+**After generating AGENTS.md files, ALWAYS validate the output:**
+
+```bash
+# 1. Run structure validation
+scripts/validate-structure.sh /path/to/project --verbose
+
+# 2. Verify content accuracy
+scripts/verify-content.sh /path/to/project
+
+# 3. Verify commands work
+scripts/verify-commands.sh /path/to/project
+```
+
+**Validation criteria:**
+
+| Check | Pass Criteria | Common Issues |
+|-------|---------------|---------------|
+| **Thin root** | Root AGENTS.md <= 80 lines | Duplicated scope content in root |
+| **All scopes covered** | Every major directory has AGENTS.md | Missing `Tests/`, `Configuration/` |
+| **No duplication** | Content appears in ONE location | Commands duplicated in root + scope |
+| **Commands verified** | All documented commands execute | Typos, renamed targets |
+| **Files exist** | All referenced files are real | Hallucinated paths |
+| **Links valid** | All cross-references resolve | Broken relative paths |
+
+**Never consider generation complete until all checks pass.**

package/skills/repo-bootstrap/references/verification-guide.md

@@ -0,0 +1,137 @@
+# Verification Guide
+
+**NEVER trust existing AGENTS.md content as accurate.** Always verify documented information against the actual codebase.
+
+## Mandatory Verification Steps
+
+1. **Extract actual state from source files:**
+   - List all modules/files with their actual docstrings
+   - List all scripts and their actual purposes
+   - Extract actual Makefile/package.json commands
+   - List actual test files and structure
+
+2. **Compare extracted state against documented state:**
+   - Check if documented files actually exist
+   - Check if documented commands actually work
+   - Check if module descriptions match actual docstrings
+   - Check if counts (modules, scripts, tests) are accurate
+
+3. **Identify and fix discrepancies:**
+   - Remove documentation for non-existent files
+   - Add documentation for undocumented files
+   - Correct inaccurate descriptions
+   - Update outdated counts and references
+
+4. **Preserve unverifiable content:**
+   - Keep manually-written context that can't be extracted
+   - Keep subjective guidance and best practices
+   - Mark preserved content appropriately
+
+## What to Verify
+
+| Category | Verification Method |
+|----------|---------------------|
+| Module list | `ls <dir>/*.py` + read docstrings |
+| Script list | `ls scripts/*.sh` + read headers |
+| Commands | `grep` Makefile targets **AND run them** |
+| Test files | `ls tests/*.py` |
+| Data files | `ls *.json` in project root |
+| Config files | Check actual existence |
+| **File names** | **EXACT match required** (not just existence) |
+| **Numeric values** | PHPStan level, coverage %, etc. from actual configs |
+
+## Critical: Exact Name Matching
+
+File names in AGENTS.md must match actual filenames **exactly**:
+
+| Documented | Actual | Status |
+|------------|--------|--------|
+| `CowriterAjaxController.php` | `AjaxController.php` | **WRONG** - name mismatch |
+| `AjaxController.php` | `AjaxController.php` | Correct |
+
+**Real-world example from t3x-cowriter review:**
+- AGENTS.md documented `Controller/CowriterAjaxController.php`
+- Actual file was `Controller/AjaxController.php`
+- This mismatch confused agents trying to find the file
+
+## Critical: Command Verification
+
+Commands documented in AGENTS.md must actually work when run:
+
+```bash
+# BAD: Document without testing
+make test-mutation  # May not exist!
+
+# GOOD: Verify before documenting
+make -n test-mutation 2>/dev/null && echo "EXISTS" || echo "MISSING"
+```
+
+**Real-world example from t3x-cowriter review:**
+- AGENTS.md documented `make test-mutation` and `make phpstan`
+- Neither target existed (actual was `make typecheck`)
+- Agents failed when trying to run documented commands
+
+## Example Verification Commands
+
+```bash
+# Extract actual module docstrings
+for f in cli_audit/*.py; do head -20 "$f" | grep -A5 '"""'; done
+
+# List actual scripts
+ls scripts/*.sh
+
+# Extract Makefile targets
+grep -E '^[a-z_-]+:' Makefile*
+
+# List actual test files
+ls tests/*.py tests/**/*.py
+```
+
+## Anti-Patterns to Avoid
+
+- **WRONG:** Updating only dates and counts based on git commits
+- **WRONG:** Trusting that existing AGENTS.md was created correctly
+- **WRONG:** Copying file lists without verifying they exist
+- **WRONG:** Using extracted command output without running it
+- **RIGHT:** Extract -> Compare -> Fix discrepancies -> Validate
+
+## Agent-Optimized Design
+
+This skill generates AGENTS.md files optimized for AI coding agent efficiency based on:
+- [Research showing 16.58% token reduction with good AGENTS.md](https://arxiv.org/html/2601.20404)
+- [GitHub best practices from 2,500+ repositories](https://github.blog/ai-and-ml/github-copilot/how-to-write-a-great-agents-md-lessons-from-over-2500-repositories/)
+- Multi-agent collaborative design (Claude + Gemini discussion)
+
+### Key Design Principles
+
+1. **Structured over Prose** - Tables and maps parse faster than paragraphs
+2. **Verified Commands** - Commands that don't work waste 500+ tokens debugging
+3. **Pointer Principle** - Point to files, don't duplicate content
+4. **Time Estimates** - Help agents choose appropriate test scope
+5. **Golden Samples** - One example file beats pages of explanation
+6. **Heuristics Tables** - Eliminate decision ambiguity
+
+### Token-Saving Sections
+
+| Section | Saves | How |
+|---------|-------|-----|
+| Commands (verified) | 500+ tokens | No debugging broken commands |
+| File Map | 3-5 search cycles | Direct navigation |
+| Golden Samples | Full rewrites | Correct patterns first time |
+| Utilities List | Duplicate code | Reuse existing helpers |
+| Heuristics | User correction cycles | Autonomous decisions |
+| Codebase State | Breaking changes | Avoid legacy/migration code |
+
+## Capabilities
+
+- **Thin root files** (~50 lines) with precedence rules and agent-optimized tables
+- **Scoped files** for subsystems (backend/, frontend/, internal/, cmd/)
+- **Auto-extracted commands** from Makefile, package.json, composer.json, go.mod
+- **Language-specific templates** for Go, PHP, TypeScript, Python, hybrid projects
+- **Freshness checking** - Detects if AGENTS.md files are outdated by comparing their "Last updated" date with git commits
+- **Automatic timestamps** - All generated files include creation/update dates in the header
+- **Documentation extraction** - Parses README.md, CONTRIBUTING.md, SECURITY.md, CHANGELOG.md
+- **Platform file extraction** - Parses .github/, .gitlab/ templates, CODEOWNERS, dependabot.yml
+- **IDE settings extraction** - Parses .editorconfig, .vscode/, .idea/, .phpstorm/
+- **AI agent config extraction** - Parses .cursor/, .claude/, .windsurf/, copilot-instructions.md
+- **Extraction summary** - Verbose mode shows all detected settings and their sources