@dedesfr/prompter 0.8.0 → 0.8.1

package/CHANGELOG.md

@@ -1,5 +1,34 @@
 # CHANGELOG
 
+## [0.8.1] - 2026-03-30
+
+### ✨ Added
+- **agents-md-generator Skill**: Generate or update `AGENTS.md` files in any project
+  - Analyzes project structure, tech stack, and conventions to create comprehensive AI agent context
+  - Automatic discovery from package manifests, config files, CI/CD pipelines, and existing docs
+  - Interactive interview mode to fill gaps in project understanding
+  - Template-based generation with 18 optional sections for maximum flexibility
+  - Support for monorepo projects with nested AGENTS.md files
+- **code-review Skill**: Automated code review with multiple report formats
+  - Analyzes code for bugs, performance issues, security concerns, and best practices
+  - Generates review reports in agent, compact, full, and human-friendly formats
+  - Leverages universal patterns from 2,500+ repositories for consistent quality standards
+- **meeting-notes Skill**: Transcribe, summarize, and organize meeting notes
+  - Captures action items, decisions, and key discussions
+  - Structures notes for easy reference and follow-up
+  - Includes evaluation framework for meeting effectiveness
+- **project-orchestrator Skill**: Plan and coordinate multi-step project initiatives
+  - Breaks down complex projects into manageable tasks and phases
+  - Generates structured project plans with dependencies and timelines
+  - Provides summaries for stakeholder communication
+- **prompter-specs Skill**: Create and manage change proposals using the Prompter specification format
+  - Guides creation of formal specs for planning, proposals, and breaking changes
+  - Ensures consistency with project architecture and guidelines
+- **ui-ux-pro Skill**: Design and improve user interfaces with professional standards
+  - Comprehensive design specification generation based on requirements
+  - Component pattern library aligned with modern design principles
+  - Best practices for accessibility, responsiveness, and design systems
+
 ## [0.8.0] - 2026-03-29
 
 ### ✨ Added

package/dist/cli/index.js

@@ -16,7 +16,7 @@ const program = new Command();
 program
     .name('prompter')
     .description('Enhance prompts directly in your AI coding workflow')
-    .version('0.8.0');
+    .version('0.8.1');
 program
     .command('init')
     .description('Initialize Prompter in your project')

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@dedesfr/prompter",
-    "version": "0.8.0",
+    "version": "0.8.1",
     "description": "Enhance prompts directly in your AI coding workflow",
     "type": "module",
     "main": "dist/index.js",

package/skills/agents-md-generator/SKILL.md

@@ -0,0 +1,238 @@
+---
+name: agents-md-generator
+description: Generate or update an AGENTS.md file in any project's root directory. Creates a comprehensive, well-structured AGENTS.md following industry best practices from analysis of 2,500+ repositories. Works from existing project docs (README, package.json, config files), codebase analysis, or direct user input. Use this skill whenever the user wants to create an AGENTS.md, update an existing one, improve AI agent instructions for a project, or mentions setting up agent context for any codebase. Also trigger when users mention wanting better AI coding assistant results, agent configuration, or project onboarding for AI tools.
+---
+
+# AGENTS.md Generator
+
+Generate or update a project's AGENTS.md file — the standard open-format file that gives AI coding agents the context they need to work effectively in a codebase.
+
+## Why AGENTS.md matters
+
+AGENTS.md is the "README for AI agents." Unlike README files written for humans, AGENTS.md provides the specific, structured context that AI coding agents need: exact commands with flags, concrete code examples, clear boundaries on what to never touch, and project-specific conventions that aren't obvious from the code alone. A well-written AGENTS.md dramatically improves the quality of AI-generated code by reducing hallucinated endpoints, mismatched coding styles, and violations of project constraints.
+
+## Step 0: Determine Mode
+
+Present these options to the user:
+
+**What would you like to do?**
+
+1. **Generate new AGENTS.md** — Create from scratch by analyzing the project
+2. **Update existing AGENTS.md** — Improve or add sections to an existing file
+3. **Generate from docs** — Build AGENTS.md from existing documentation (README, wiki, docs/)
+
+Wait for the user's selection before proceeding.
+
+## Step 1: Gather Project Context
+
+The quality of the AGENTS.md depends entirely on understanding the project. Collect context from these sources, in priority order:
+
+### 1.1 Automatic Discovery (always do this)
+
+Scan the project root for context signals:
+
+- **Package manifest**: `package.json`, `Cargo.toml`, `pyproject.toml`, `go.mod`, `composer.json`, `Gemfile`, `pom.xml`, `build.gradle`
+- **Config files**: `tsconfig.json`, `.eslintrc*`, `.prettierrc*`, `tailwind.config.*`, `vite.config.*`, `webpack.config.*`, `docker-compose.yml`
+- **CI/CD**: `.github/workflows/`, `.gitlab-ci.yml`, `Jenkinsfile`
+- **Existing docs**: `README.md`, `CONTRIBUTING.md`, `docs/`, `wiki/`
+- **Existing AI config**: `CLAUDE.md`, `.cursorrules`, `.github/copilot-instructions.md`, `.windsurfrules`
+- **Test setup**: test directories, test config files, test scripts in package manifest
+- **Git history**: recent commit patterns, active contributors
+
+Read these files to extract:
+- Tech stack and versions
+- Build/test/lint commands
+- Project structure patterns
+- Coding conventions
+- Architecture decisions
+
+### 1.2 User-Provided Docs (if mode is "Generate from docs")
+
+Ask the user to point to their documentation:
+- "Which docs should I use as source material? (paths, URLs, or paste content directly)"
+
+Read and synthesize the provided documentation into AGENTS.md sections.
+
+### 1.3 Interactive Interview (fill gaps)
+
+After automatic discovery, identify what's still missing and ask the user targeted questions. Don't ask about things you already know from the codebase. Focus on:
+
+- **Project purpose**: What does this project do? (if not clear from README)
+- **Architecture decisions**: Any non-obvious patterns or constraints?
+- **Boundaries**: What should AI agents never touch? (secrets, vendor dirs, generated files, production configs)
+- **Domain vocabulary**: Any project-specific terms agents need to know?
+- **Common pitfalls**: What mistakes do new contributors (or AI agents) commonly make?
+- **Testing requirements**: Any specific testing patterns or requirements?
+
+Keep the interview short — 3-5 questions max, focused on what you genuinely couldn't determine from the code.
+
+## Step 2: Structure the AGENTS.md
+
+Use the template at `assets/agents-md-template.md` as a starting point. The template has 18 sections — not all are required for every project. Include a section only if you have substantive content for it. An empty or placeholder section ("Not specified") is worse than omitting it entirely.
+
+### Section Priority
+
+**Always include** (these are the highest-value sections based on empirical analysis):
+1. **Project Summary** — What this project does, in 2-3 sentences
+2. **Tech Stack** — Languages, frameworks, runtime versions
+3. **Commands** — Build, test, lint, deploy commands with exact flags
+4. **Folder Structure** — Key directories and their purposes
+5. **Coding Conventions** — Real code examples, not verbal descriptions
+6. **Development Rules for AI Agents** — Boundaries and constraints
+
+**Include when relevant:**
+7. **Architecture Overview** — Module structure, data flow
+8. **Core Business Logic** — Domain rules that aren't obvious from code
+9. **Data Models** — Key entities and relationships
+10. **Domain Vocabulary** — Project-specific terms
+11. **Security/Privacy Rules** — Auth flows, sensitive data handling
+12. **Testing Strategy** — Frameworks, patterns, coverage expectations
+13. **Integration Map** — External services, APIs, third-party tools
+
+**Include only if substantive:**
+14. **Target Users** — Who uses this and how
+15. **UI/UX Principles** — Design patterns and constraints
+16. **Roadmap** — Active initiatives
+17. **Known Issues** — Current limitations
+18. **Troubleshooting** — Common problems and fixes
+19. **Ownership Map** — Who owns what
+
+### Writing Guidelines
+
+Follow these principles — they come from analysis of what actually makes AGENTS.md effective:
+
+**Be specific, not vague.**
+```markdown
+# Bad
+- Use TypeScript
+- Follow best practices
+
+# Good
+- TypeScript 5.4 with strict mode enabled
+- ESM imports with explicit `.js` extensions in compiled output
+- Prefer `interface` over `type` for object shapes
+```
+
+**Lead with executable commands.**
+```markdown
+# Commands
+npm run build          # Compile TypeScript to dist/
+npm test               # Run vitest test suite
+npm run lint           # ESLint with --fix
+npm run typecheck      # tsc --noEmit
+```
+
+**Show code examples for conventions.**
+```markdown
+# Component pattern
+export function UserCard({ user }: { user: User }) {
+  // Components use named exports, PascalCase
+  // Props defined inline for simple cases
+}
+```
+
+**Use three-tier boundaries.**
+```markdown
+## Development Rules for AI Agents
+### Always do:
+- Run `npm run typecheck` before committing
+- Use existing utility functions from `src/utils/`
+
+### Ask first:
+- Adding new dependencies
+- Modifying database schemas
+- Changes to CI/CD pipelines
+
+### Never do:
+- Commit `.env` files or secrets
+- Modify `vendor/` or generated files
+- Run destructive database commands
+- Invent API endpoints that don't exist
+```
+
+**Include file-scoped commands** for common per-file operations:
+```markdown
+# File-scoped commands
+npx vitest run src/utils/parse.test.ts    # Run single test file
+npx eslint --fix src/components/Card.tsx   # Lint single file
+npx tsc --noEmit src/types.ts              # Type-check single file
+```
+
+## Step 3: Generate or Update
+
+### For new AGENTS.md (Mode 1 or 3)
+
+1. Read the template from `assets/agents-md-template.md`
+2. Fill in each section with discovered and user-provided content
+3. Remove sections that have no substantive content
+4. Write to `AGENTS.md` in the project root
+
+### For updating existing AGENTS.md (Mode 2)
+
+1. Read the existing `AGENTS.md`
+2. Identify which sections exist and their quality
+3. Ask the user what they want to improve:
+   - "Add missing sections"
+   - "Update outdated information"
+   - "Improve specific sections" (let them pick)
+   - "Full refresh" (regenerate while preserving custom content)
+4. Make targeted updates, preserving any custom content the user has added
+5. If the file has managed markers (like `<!-- PROMPTER:START -->`), preserve those sections untouched
+
+### Monorepo Support
+
+For monorepos or multi-package projects, offer to create nested AGENTS.md files:
+
+```
+project-root/
+├── AGENTS.md              # Project-wide context
+├── packages/
+│   ├── frontend/
+│   │   └── AGENTS.md      # Frontend-specific context
+│   └── backend/
+│       └── AGENTS.md      # Backend-specific context
+```
+
+The root AGENTS.md should reference subdirectory files and provide shared context. Subdirectory files should focus on package-specific details.
+
+## Step 4: Validate and Review
+
+Before finalizing, check:
+
+- [ ] No placeholder text remains ("Not specified", "TODO", "TBD")
+- [ ] Commands are accurate and runnable
+- [ ] File paths referenced actually exist in the project
+- [ ] Tech stack versions match what's in config files
+- [ ] No sensitive information included (API keys, internal URLs, credentials)
+- [ ] Sections are ordered by value (most useful first)
+- [ ] Code examples match the project's actual coding style
+
+Present a summary to the user:
+- Which sections were generated
+- Any sections skipped (and why)
+- Suggestions for sections they could add later
+
+## Step 5: Save
+
+Save the AGENTS.md to the project root path (or the path the user specifies).
+
+Print a summary:
+```
+AGENTS.md generated at <path>
+Sections: <count> of 18
+Sources used: <list of files analyzed>
+Suggested improvements: <any sections that could be enhanced with more info>
+```
+
+## Edge Cases
+
+- **No package manifest found**: Ask the user about the tech stack directly
+- **Multiple languages**: Create sections for each, clearly labeled
+- **Existing CLAUDE.md / .cursorrules**: Offer to consolidate into AGENTS.md (which is the cross-tool standard) or keep both
+- **Very large project**: Focus on the most important directories and patterns rather than trying to document everything
+- **No README**: The interview step becomes more important — ask more questions
+
+## Resources
+
+- Template: `assets/agents-md-template.md`
+- Best practices reference: `references/best-practices.md`

package/skills/agents-md-generator/assets/agents-md-template.md

@@ -0,0 +1,81 @@
+# AGENTS — Project Knowledge Base
+
+## 1. Project Summary
+{{PROJECT_SUMMARY}}
+
+## 2. Tech Stack
+{{TECH_STACK}}
+
+## 3. Architecture Overview
+{{ARCHITECTURE_OVERVIEW}}
+
+## 4. Folder Structure & Important Files
+{{FOLDER_STRUCTURE}}
+
+## 5. Commands
+```bash
+# Build
+{{BUILD_COMMAND}}
+
+# Test
+{{TEST_COMMAND}}
+
+# Lint / Format
+{{LINT_COMMAND}}
+
+# Type check
+{{TYPECHECK_COMMAND}}
+
+# File-scoped commands
+{{FILE_SCOPED_COMMANDS}}
+```
+
+## 6. Core Business Logic & Domain Rules
+{{BUSINESS_LOGIC}}
+
+## 7. Data Models / Entities
+{{DATA_MODELS}}
+
+## 8. Domain Vocabulary / Glossary
+{{DOMAIN_VOCABULARY}}
+
+## 9. Target Users & Personas
+{{TARGET_USERS}}
+
+## 10. UI/UX Principles
+{{UI_UX_PRINCIPLES}}
+
+## 11. Security / Privacy Rules
+{{SECURITY_RULES}}
+
+## 12. Coding Conventions & Standards
+{{CODING_CONVENTIONS}}
+
+## 13. Development Rules for AI Agents
+
+### Always do:
+{{ALWAYS_DO_RULES}}
+
+### Ask first:
+{{ASK_FIRST_RULES}}
+
+### Never do:
+{{NEVER_DO_RULES}}
+
+## 14. Integration Map
+{{INTEGRATION_MAP}}
+
+## 15. Testing Strategy
+{{TESTING_STRATEGY}}
+
+## 16. Roadmap & Future Plans
+{{ROADMAP}}
+
+## 17. Known Issues / Limitations
+{{KNOWN_ISSUES}}
+
+## 18. Troubleshooting Guide
+{{TROUBLESHOOTING}}
+
+## 19. Ownership / Responsibility Map
+{{OWNERSHIP_MAP}}

package/skills/agents-md-generator/references/best-practices.md

@@ -0,0 +1,215 @@
+# AGENTS.md Best Practices Reference
+
+Compiled from analysis of 2,500+ repositories and official documentation from GitHub, GitLab, Windsurf, and the agents.md specification.
+
+## Table of Contents
+
+1. [Six Essential Areas](#six-essential-areas)
+2. [Writing Principles](#writing-principles)
+3. [Common Anti-Patterns](#common-anti-patterns)
+4. [Monorepo Patterns](#monorepo-patterns)
+5. [Cross-Tool Compatibility](#cross-tool-compatibility)
+6. [Section-Specific Guidance](#section-specific-guidance)
+
+---
+
+## Six Essential Areas
+
+The highest-impact sections, based on empirical analysis of what actually improves AI agent output:
+
+| Area | Why It Matters | Example |
+|------|---------------|---------|
+| **Commands** | Agents need exact executable commands, not descriptions | `npm test -- --watch` not "run the tests" |
+| **Testing** | Framework-specific practices prevent wrong test patterns | `vitest` vs `jest` syntax differences |
+| **Project Structure** | Agents need exact file locations, not guesses | `src/api/routes/` not "the API folder" |
+| **Code Style** | Real examples prevent style drift | Show actual component code |
+| **Git Workflow** | Prevents wrong branching, commit, and PR patterns | `feat/`, `fix/` branch prefixes |
+| **Boundaries** | Clear "never do" rules prevent the worst mistakes | Never commit `.env`, never modify `vendor/` |
+
+## Writing Principles
+
+### Specificity Over Generality
+
+The #1 predictor of AGENTS.md effectiveness is specificity. Vague instructions get vague results.
+
+**Versions matter:**
+```markdown
+# Vague
+- Uses React and TypeScript
+
+# Specific
+- React 18.3 with TypeScript 5.4
+- Node.js >= 20 (uses native fetch)
+- Tailwind CSS 3.4 with custom design tokens in tailwind.config.ts
+```
+
+**Commands must be copy-pasteable:**
+```markdown
+# Vague
+- Run the tests before committing
+
+# Specific
+- npm test                              # Full test suite
+- npx vitest run src/utils/parse.test.ts  # Single test file
+- npx vitest --reporter=verbose           # Detailed output
+```
+
+### Show, Don't Tell
+
+Real code examples are 3-5x more effective than verbal descriptions for coding conventions.
+
+```markdown
+# Verbal (less effective)
+- Use functional components with TypeScript props
+
+# Example (more effective)
+## Component Pattern
+export function UserCard({ user, onSelect }: UserCardProps) {
+  const [isHovered, setIsHovered] = useState(false);
+  // Named exports, PascalCase, destructured props
+  // State hooks at top, handlers below
+}
+```
+
+### Three-Tier Boundaries
+
+The most impactful part of any AGENTS.md. Structure as:
+
+1. **Always do** — Required behaviors (run typecheck, use existing utils)
+2. **Ask first** — Needs human approval (new deps, schema changes, CI changes)
+3. **Never do** — Absolute prohibitions (commit secrets, modify generated files, invent APIs)
+
+"Never commit secrets" was identified as the single most helpful boundary rule across all analyzed repositories.
+
+### Progressive Disclosure
+
+Don't dump everything upfront. Structure information so agents encounter what they need when they need it:
+
+- Put the most frequently needed info (commands, structure) at the top
+- Put specialized info (troubleshooting, edge cases) at the bottom
+- For complex topics, link to separate docs rather than inlining everything
+
+## Common Anti-Patterns
+
+### 1. Placeholder Sections
+```markdown
+# Bad — worse than omitting the section entirely
+## Roadmap
+- TBD
+
+## Ownership
+- Not specified
+```
+Empty sections signal that the document is incomplete and may be untrustworthy. Omit sections you can't fill meaningfully.
+
+### 2. Vague Boundaries
+```markdown
+# Bad
+- Be careful with the database
+- Follow best practices
+
+# Good
+- Never run DROP, TRUNCATE, or DELETE without WHERE clause
+- Always use parameterized queries, never string interpolation for SQL
+```
+
+### 3. Describing Style Without Examples
+```markdown
+# Bad
+- Use consistent naming conventions
+- Follow the project's component pattern
+
+# Good
+- Variables: camelCase (userId, isActive)
+- Components: PascalCase (UserCard, NavBar)
+- Files: kebab-case (user-card.tsx, nav-bar.tsx)
+- Constants: UPPER_SNAKE (MAX_RETRIES, API_BASE_URL)
+```
+
+### 4. Duplicating README Content
+AGENTS.md should contain agent-specific guidance that would clutter a human README. Don't copy your README — reference it and add the agent-specific context.
+
+### 5. One-Time Setup, Never Updated
+AGENTS.md should evolve with the project. After each time an AI agent makes a mistake that better instructions would have prevented, update the AGENTS.md.
+
+## Monorepo Patterns
+
+Place AGENTS.md files at multiple levels:
+
+```
+project/
+├── AGENTS.md                    # Shared: monorepo conventions, CI, tooling
+├── packages/
+│   ├── api/
+│   │   └── AGENTS.md            # API-specific: routes, middleware, DB patterns
+│   ├── web/
+│   │   └── AGENTS.md            # Frontend-specific: components, state, styling
+│   └── shared/
+│       └── AGENTS.md            # Shared lib: export patterns, versioning
+```
+
+**Rules:**
+- The closest AGENTS.md to the working file takes precedence
+- Root AGENTS.md should contain cross-cutting concerns only
+- Subdirectory files should not repeat root-level content
+
+## Cross-Tool Compatibility
+
+AGENTS.md is recognized by multiple AI coding tools:
+
+| Tool | File | Precedence |
+|------|------|-----------|
+| GitHub Copilot | `AGENTS.md` | Standard |
+| OpenAI Codex | `AGENTS.md`, `AGENTS.override.md` | Override > Standard |
+| Claude Code | `CLAUDE.md`, `AGENTS.md` | Both read |
+| Windsurf | `AGENTS.md`, `.windsurfrules` | Both read |
+| Cursor | `.cursorrules`, `AGENTS.md` | Tool-specific first |
+| GitLab Duo | `AGENTS.md` | Standard |
+| Android Studio (Gemini) | `AGENTS.md` | Standard |
+
+When a project has both AGENTS.md and tool-specific files (CLAUDE.md, .cursorrules), the tool-specific file typically takes precedence for that tool. AGENTS.md serves as the cross-tool baseline.
+
+## Section-Specific Guidance
+
+### Commands Section
+- Include every command a developer might need
+- Show exact flags, not just the base command
+- Group by purpose (build, test, lint, deploy)
+- Include file-scoped variants where applicable
+- Note any required environment variables
+
+### Project Structure Section
+- Focus on directories agents will actually work in
+- Explain naming conventions for files within each directory
+- Call out generated or auto-maintained files (don't edit these)
+- Note any files with special significance (entry points, config)
+
+### Coding Conventions Section
+- Show 2-3 real examples from the codebase for each convention
+- Include import ordering rules
+- Document error handling patterns
+- Show preferred patterns for common operations (API calls, state management, etc.)
+
+### Testing Section
+- Include the exact test command with all needed flags
+- Show the test file naming convention
+- Provide a minimal test example in the project's style
+- Document any test utilities or helpers available
+- Note coverage thresholds if enforced
+
+### Security Section
+- List all files/directories that must never be committed
+- Document authentication/authorization patterns
+- Note any data handling requirements (PII, encryption)
+- Call out environment-specific configurations
+
+---
+
+## Sources
+
+- [agents.md — Official Specification](https://agents.md/)
+- [GitHub Blog — Lessons from 2,500+ Repositories](https://github.blog/ai-and-ml/github-copilot/how-to-write-a-great-agents-md-lessons-from-over-2500-repositories/)
+- [Builder.io — Best Tips for AGENTS.md](https://www.builder.io/blog/agents-md)
+- [Factory Documentation](https://docs.factory.ai/cli/configuration/agents-md)
+- [Windsurf Documentation](https://docs.windsurf.com/windsurf/cascade/agents-md)
+- [GitLab Documentation](https://docs.gitlab.com/user/duo_agent_platform/customize/agents_md/)