feat: add new skills for GitHub issue management and documentation generation

Signed-off-by: Felipe Sayão Lobato Abreu <github@mentordosnerds.com>

Author: coisa

.agents/skills/fast-forward-docs/SKILL.md

@@ -1,24 +1,10 @@
 ---
-name: fastforward-sphinx-docs
-description: Generate structured, consistent, and reusable Sphinx (reStructuredText) documentation for Fast Forward PHP framework libraries.
-version: 1.0.0
-tags:
-  - documentation
-  - sphinx
-  - rst
-  - php
-  - fast-forward
-  - technical-writing
-author: Fast Forward Ecosystem
-license: MIT
-inputs: []
-outputs:
-  - type: documentation
-    format: rst
+name: fast-forward-docs
+description: Generate or refresh Sphinx reStructuredText documentation for Fast Forward PHP packages. Use when Codex needs to create package docs in `docs/`, expand existing `.rst` sections, document APIs or workflows, or keep Fast Forward documentation structure consistent.
 ---
 
 
-# Sphinx Documentation Skill for Fast Forward Framework
+# Fast Forward Docs
 
 This skill provides a comprehensive checklist and structure for generating rich, congruent, and reusable documentation in reStructuredText (.rst) for all libraries in the Fast Forward PHP framework ecosystem. Use these guidelines to ensure consistency, depth, and usability across all package docs.
 
@@ -143,4 +129,4 @@ This skill provides a comprehensive checklist and structure for generating rich,
    - Integration with containers (PSR-11), service providers, and override/customization patterns.
    - Optional dependencies, version compatibility, and advanced troubleshooting scenarios.
 3. Always create or update sections to document any special scenario or advanced feature found in the codebase, mesmo que não esteja presente em outras libs.
-4. Follow the suggested structure, but add extra files/sections as needed to cover all the library's features and unique selling points.
+4. Follow the suggested structure, but add extra files/sections as needed to cover all the library's features and unique selling points.

.agents/skills/fast-forward-docs/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Fast Forward Docs"
+  short_description: "Generate Sphinx docs for Fast Forward packages"
+  default_prompt: "Use $fast-forward-docs to generate or revise Sphinx documentation for this Fast Forward PHP package."

.agents/skills/fast-forward-docs/agents/openai.yml

@@ -0,0 +1,138 @@
+---
+name: fast-forward-issues
+description: Transform a short feature, enhancement, or bug description into a complete production-ready GitHub issue with structured sections, acceptance criteria, and architectural quality requirements. Use when Codex needs to draft or refine an issue from a brief prompt.
+---
+
+# Create GitHub Issue from Specification
+
+This skill transforms a short feature description into a complete, production-ready GitHub issue written in clear, precise, and structured English following strict quality guidelines.
+
+## When to Use This Skill
+
+Use this skill when:
+- User provides a short feature description and asks to create a GitHub issue
+- User wants to transform a brief idea into a structured issue
+- User asks to "create issue from description" or similar
+- User provides a prompt describing a feature/enhancement/bug
+
+## Input Processing
+
+### Extract the Feature Description
+
+The user will provide a short description. Extract and analyze:
+- The core request (add, enhance, fix, improve)
+- The subject/target of the request
+- Any specific tools, libraries, or technologies mentioned
+- The context or domain
+
+### Infer Missing Details
+
+Using engineering judgment, infer:
+- Common CLI patterns for the described feature type
+- Expected file locations and naming conventions
+- Standard architectural patterns for the feature domain
+- Typical acceptance criteria for similar features
+
+## Output Generation
+
+Generate a complete GitHub issue following this structure:
+
+### 1. Title
+
+- Clear, concise, descriptive
+- Action-oriented phrasing (Add, Enhance, Introduce, Fix)
+- Reflects intent and scope
+
+### 2. Description
+
+#### Problem
+- Explain current limitation or gap
+- Focus on real-world impact (DX, CI, maintenance, consistency)
+- Avoid fluff or generic statements
+
+#### Proposal
+- Describe solution at conceptual level
+- Avoid jumping into implementation
+- Clearly state what will be introduced or changed
+
+#### Goals
+- Define success criteria
+- Focus on outcomes, not implementation
+
+#### Expected Behavior
+- Describe feature from user perspective
+- Include CLI examples when relevant
+
+#### Implementation Strategy
+- Suggest practical approach
+- Mention tools, libraries, patterns when useful
+- Keep flexible, not prescriptive
+
+#### Requirements
+- Define strict functional requirements
+- Must be testable and objective
+- Include CLI behavior, outputs, determinism, CI compatibility
+
+#### Non-goals
+- Explicitly state what is out of scope
+- Prevent feature creep
+
+#### Benefits
+- Explain why feature matters
+- Focus on developer experience, maintainability, consistency
+
+#### Additional Context (optional)
+- Relevant background, ecosystem alignment, rationale
+
+### 3. Acceptance Criteria
+
+#### Functional Criteria
+- What must work
+- What must not break
+- Output expectations
+- Error handling expectations
+
+#### Architectural/Isolation Criteria (MANDATORY)
+
+Always include this section enforcing architectural quality:
+
+```
+### Architectural / Isolation Criteria
+
+- **MUST**: The core logic MUST be isolated into dedicated classes (no business logic inside the command/controller layer)
+- **MUST**: Responsibilities MUST be clearly separated:
+  - One class for input/config resolution
+  - One class for domain logic
+  - One class for processing/transformations
+  - One class for output/rendering
+- **MUST**: The command layer MUST act only as an orchestrator
+- **MUST**: The design MUST allow future extraction into an external reusable package with minimal changes
+- **MUST**: The implementation MUST avoid tight coupling to CLI/framework-specific I/O
+- **MUST**: The system MUST be extensible without requiring major refactoring
+```
+
+## Style Guidelines
+
+- Be highly objective and precise
+- Avoid filler language
+- Avoid vague statements like "improve things"
+- Prefer deterministic, testable statements
+- Use clean Markdown formatting
+- Use code blocks for CLI examples
+- Use bullet points for clarity
+- Keep strong engineering tone (not marketing, not casual)
+
+## Output Format
+
+Output the complete, ready-to-use GitHub issue in Markdown format. Do not include:
+- Follow-up questions
+- Explanations about the prompt
+- Meta commentary
+
+## Example Transformation
+
+**Input:**
+"Add a command to analyze dependencies using composer-unused and dependency-analyser"
+
+**Output:**
+See the complete generated issue with all sections as specified above.

.agents/skills/fast-forward-github-issues/agents/openai.yml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Fast Forward Issues"
+  short_description: "Turn brief prompts into production-ready GitHub issues"
+  default_prompt: "Use $fast-forward-issues to turn this repository idea into a complete GitHub issue with acceptance criteria."

.agents/skills/fast-forward-issues/SKILL.md

@@ -1,6 +1,6 @@
 ---
-name: fast-forward-github-issues
-description: Iterates through all open GitHub issues in the repository and implements them one by one following a structured workflow. For each issue: creates a feature branch from main, implements the solution, creates or updates tests using fast-forward-tests, updates README with fast-forward-readme, updates docs with fast-forward-docs if applicable, and opens a pull request with Closes #<issue-number>. Triggers on requests like "implement issues", "work on issues", "handle all issues", "iterate through issues", "process issues", "implement all open issues".
+name: fast-forward-pull-request
+description: Implement open GitHub issues in a repository one by one with isolated branches, tests, documentation updates, and pull requests. Use when Codex is asked to work through issue queues, implement repository issues sequentially, or manage the full issue-to-PR flow in Fast Forward projects.
 ---
 
 # Implement GitHub Issues
@@ -16,8 +16,8 @@ For each open issue:
 3. **Commits**: Create well-structured commits with clear messages
 4. **Tests**: Create or update tests using the `fast-forward-tests` skill
 5. **Documentation**: Update README using `fast-forward-readme`, update docs using `fast-forward-docs` if applicable
-6. **Pull Request**: Open a PR targeting `main` with `Closes #<issue-number>` in the description
-7. **Issue Handling**: Never close issues directly; only reference via `Closes #<issue-number>` in PR
+6. **Pull Request**: Open a PR targeting `main` with `Closes #123` style closing text in the description
+7. **Issue Handling**: Never close issues directly; only reference them via `Closes #123` style text in the PR
 
 ## Global Rules
 
@@ -154,7 +154,7 @@ Create a pull request:
   Closes #{issue-number}
   ```
 
-**Important**: Include `Closes #<issue-number>` in the PR description so the issue is automatically closed only after the PR is merged.
+**Important**: Include `Closes #{issue-number}` in the PR description so the issue is automatically closed only after the PR is merged.
 
 #### 2.10 Wait for Merge
 

.agents/skills/fast-forward-issues/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Fast Forward Pull Request"
+  short_description: "Implement GitHub issues with tests, docs, and PR flow"
+  default_prompt: "Use $fast-forward-pull-request to implement open GitHub issues one by one with branches, tests, docs, and pull requests."

…ills/fast-forward-github-issues/SKILL.md …kills/fast-forward-pull-request/SKILL.md.agents/skills/fast-forward-github-issues/SKILL.md renamed to .agents/skills/fast-forward-pull-request/SKILL.md .agents/skills/fast-forward-github-issues/SKILL.md renamed to .agents/skills/fast-forward-pull-request/SKILL.md

@@ -1,23 +1,9 @@
 ---
-name: fastforward-readme
-description: Generate high-quality, consistent, and discoverable README.md files for Fast Forward PHP framework components.
-version: 1.0.0
-tags:
-  - documentation
-  - readme
-  - markdown
-  - php
-  - fast-forward
-  - developer-experience
-author: Fast Forward Ecosystem
-license: MIT
-inputs: []
-outputs:
-  - type: documentation
-    format: markdown
+name: fast-forward-readme
+description: Generate or refresh README.md files for Fast Forward PHP packages. Use when Codex needs to create a new package README, reorganize an existing README, improve onboarding and discoverability, or align README structure with the Fast Forward ecosystem.
 ---
 
-# SKILL.md — Fast Forward Framework README Skill
+# Fast Forward README
 
 ## Purpose
 This skill provides a comprehensive, reusable checklist and structure for creating high-quality, consistent, and discoverable `README.md` files for any component in the Fast Forward PHP framework ecosystem. It ensures:
@@ -266,4 +252,4 @@ This skill provides a comprehensive, reusable checklist and structure for creati
 
 ---
 
-This skill is workspace-scoped and intended for maintainers and contributors of Fast Forward PHP libraries.
+This skill is workspace-scoped and intended for maintainers and contributors of Fast Forward PHP libraries.

.agents/skills/fast-forward-pull-request/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Fast Forward README"
+  short_description: "Generate consistent README files for Fast Forward packages"
+  default_prompt: "Use $fast-forward-readme to write or refresh a README.md for this Fast Forward PHP package."