@poetic-ai/poetic 1.42.0

package/scripts/write-node-launcher.sh

@@ -0,0 +1,108 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+is_managed_launcher() {
+  local candidate="$1"
+
+  grep -Fqx '# Generated by Poetic scripts/write-node-launcher.sh' "$candidate" 2>/dev/null \
+    || {
+      grep -Fq 'node_bin="${POETIC_NODE_BIN:-$default_node}"' "$candidate" 2>/dev/null \
+        && grep -Fq 'exec "$node_bin" "$entry_js" "$@"' "$candidate" 2>/dev/null
+    }
+}
+
+prepare_link() {
+  local candidate="$1"
+
+  if [[ -L "$candidate" && ! -e "$candidate" ]]; then
+    rm -f -- "$candidate"
+    return 0
+  fi
+  if [[ ! -e "$candidate" || -L "$candidate" ]]; then
+    return 0
+  fi
+  if [[ -f "$candidate" ]] && is_managed_launcher "$candidate"; then
+    rm -f -- "$candidate"
+    return 0
+  fi
+
+  echo "Error: Refusing to replace unmanaged file: $candidate" >&2
+  return 1
+}
+
+if [[ "$#" -eq 2 && "$1" == "--prepare-link" ]]; then
+  prepare_link "$2"
+  exit 0
+fi
+
+# Exit status only; lets callers decide whether an existing launcher is theirs to
+# overwrite without duplicating the detection heuristic.
+if [[ "$#" -eq 2 && "$1" == "--is-managed" ]]; then
+  if is_managed_launcher "$2"; then
+    exit 0
+  fi
+  exit 1
+fi
+
+if [[ "$#" -ne 3 ]]; then
+  echo "Usage: $0 <launcher-path> <node-bin> <entry-js>" >&2
+  echo "       $0 --prepare-link <launcher-path>" >&2
+  echo "       $0 --is-managed <launcher-path>" >&2
+  exit 2
+fi
+
+launcher_path="$1"
+node_bin="$2"
+entry_js="$3"
+
+if [[ ! -x "$node_bin" ]]; then
+  echo "Error: Node executable is not runnable: $node_bin" >&2
+  exit 1
+fi
+if [[ ! -f "$entry_js" ]]; then
+  echo "Error: Poetic entrypoint not found: $entry_js" >&2
+  exit 1
+fi
+
+node_version="$("$node_bin" -p 'process.versions.node')"
+if [[ "${node_version%%.*}" != "24" ]]; then
+  echo "Error: Node 24.x is required to generate the Poetic launcher (found: v${node_version})." >&2
+  exit 1
+fi
+
+mkdir -p "$(dirname "$launcher_path")"
+temporary="$(mktemp "${launcher_path}.tmp.XXXXXX")"
+trap 'rm -f "$temporary"' EXIT
+
+{
+  echo '#!/usr/bin/env bash'
+  echo '# Generated by Poetic scripts/write-node-launcher.sh'
+  echo 'set -euo pipefail'
+  printf 'default_node=%q\n' "$node_bin"
+  printf 'entry_js=%q\n' "$entry_js"
+  cat <<'EOF'
+node_bin="${POETIC_NODE_BIN:-$default_node}"
+if [[ ! -x "$node_bin" ]]; then
+  echo "poetic: configured Node executable is unavailable: $node_bin" >&2
+  echo "Re-run the Poetic installer/build or set POETIC_NODE_BIN to Node 24." >&2
+  exit 1
+fi
+node_version="$("$node_bin" -p 'process.versions.node' 2>/dev/null || true)"
+if [[ "${node_version%%.*}" != "24" ]]; then
+  echo "poetic: Node 24.x is required (configured runtime: ${node_version:-unknown})." >&2
+  exit 1
+fi
+if [[ ! -f "$entry_js" ]]; then
+  echo "poetic: entrypoint is unavailable: $entry_js" >&2
+  echo "Re-run the Poetic installer/build." >&2
+  exit 1
+fi
+node_dir="$(cd "$(dirname "$node_bin")" && pwd -P)"
+export PATH="${node_dir}${PATH:+:${PATH}}"
+exec "$node_bin" "$entry_js" "$@"
+EOF
+} >"$temporary"
+
+chmod 755 "$temporary"
+mv "$temporary" "$launcher_path"
+trap - EXIT

package/src/resources/gemini/slash-packs/default/plan.toml

@@ -0,0 +1,15 @@
+name = "plan"
+description = "Draft a concise implementation plan before writing code."
+prompt = """
+You are an experienced engineer working inside the Poetic repository.
+
+Task:
+{{input}}
+
+Produce:
+1. A numbered list of concrete steps (<= 8 items).
+2. Note any risks, unknowns, or follow-ups.
+
+Do not write code. Focus on sequencing the work so another engineer can execute it.
+"""
+

package/src/resources/gemini/slash-packs/default/summary.toml

@@ -0,0 +1,16 @@
+name = "summary"
+description = "Summarize changes ready for code review."
+prompt = """
+You are preparing a crisp hand-off summary for reviewers of the Poetic repository.
+
+Task or diff context:
+{{input}}
+
+Return:
+- A bullet list of meaningful changes grouped by area.
+- Any migrations, follow-up items, or verification steps (tests run, commands to execute).
+- Mention unresolved questions or TODOs if they exist.
+
+Keep the tone factual and concise. Avoid repeating code line-by-line.
+"""
+

package/src/resources/gemini/slash-packs/default/tests.toml

@@ -0,0 +1,16 @@
+name = "tests"
+description = "Outline the right test additions or updates for the current task."
+prompt = """
+You are responsible for developing a pragmatic testing strategy for the Poetic codebase.
+
+Task context:
+{{input}}
+
+Respond with:
+- The types of tests to add or update (unit, integration, e2e, etc.).
+- The key scenarios/assertions each test must cover.
+- Any tooling or setup steps required (mocks, fixtures, CLI commands).
+
+Keep the answer focused on test strategy. Do not generate code.
+"""
+

package/templates/.poetic/README.md

@@ -0,0 +1,37 @@
+# Poetic Project Directory
+
+This `.poetic/` directory contains project-local configuration and runtime artifacts for the Poetic CLI.
+
+## Directory Structure (High-Level)
+
+```
+.poetic/
+ .artifacts/                      # Legacy/generated artifacts (gitignored)
+ config/
+    providers.yaml              # Provider defaults (recommended)
+    poetic.config.jsonc            # Optional advanced config
+    project-context.json        # Project detection output
+ telemetry/
+    db/                         # Telemetry SQLite DBs (gitignored)
+       variants.db
+       validations.db
+    invocations.db              # Cost/token tracking DB (gitignored)
+    logs/                       # JSONL/log output (gitignored)
+ state/                          # Runtime markers/locks (gitignored)
+ worktrees/                      # Temporary worktrees (gitignored)
+ .gitignore                      # Ignores runtime artifacts
+ README.md                       # This file
+```
+
+## Configuration
+
+- Preferred: edit `.poetic/config/providers.yaml` to set provider defaults (without hardcoding model versions unless you need to).
+- Optional: edit `.poetic/config/poetic.config.jsonc` for advanced settings like quality gates and execution tuning.
+
+## Useful Commands
+
+```bash
+poetic doctor
+poetic doctor --fix
+poetic config user get
+```

package/templates/.poetic/agents/README.md

@@ -0,0 +1,296 @@
+# Project Agent Templates
+
+This directory contains optional project-local agent personas installed by
+`poetic init`. Keep the ones that fit this project and customize them in place.
+
+## Overview
+
+These files are reference personas. Poetic's agent registry loads definitions
+from `~/.claude/agents/` (the Claude Code ecosystem location); copy any persona
+you want active there. Compatible providers may also use project-local files
+when their integration supports it.
+
+## Installation
+
+No repository setup script or plugin is required. To activate a persona for
+agent-aware runs, copy it to the registry location:
+
+```bash
+cp .poetic/agents/code-reviewer.md ~/.claude/agents/
+```
+
+## Available Agents
+
+### Code Quality & Architecture
+
+#### code-reviewer
+**When to use:** After implementing features, before committing major changes
+**Capabilities:**
+- AI-powered code analysis with modern tools
+- Security vulnerability detection (OWASP Top 10)
+- Performance and scalability analysis
+- Multi-language expertise
+- Production reliability review
+
+**Example:**
+```
+Use the code-reviewer agent to review the authentication module
+```
+
+#### backend-architect
+**When to use:** Designing new APIs or microservices
+**Capabilities:**
+- RESTful API design with versioning
+- Service boundary definition
+- Database schema design
+- Caching strategies
+- Basic security patterns
+
+**Example:**
+```
+Use the backend-architect agent to design the user management API
+```
+
+#### frontend-developer
+**When to use:** Building UI components or client-side features
+**Capabilities:**
+- React component implementation
+- Responsive layouts
+- Client-side state management
+- Frontend performance optimization
+- Accessibility standards
+
+**Example:**
+```
+Use the frontend-developer agent to build the dashboard component
+```
+
+---
+
+### Language Specialists
+
+#### python-pro
+**When to use:** Python refactoring, optimization, or complex features
+**Capabilities:**
+- Idiomatic Python with decorators, generators, async/await
+- Design patterns and best practices
+- Performance optimization
+- Comprehensive testing with pytest
+
+**Example:**
+```
+Use the python-pro agent to refactor the data processing pipeline
+```
+
+#### javascript-pro
+**When to use:** Modern JavaScript features or Node.js development
+**Capabilities:**
+- ES6+ features and patterns
+- Async patterns (promises, async/await)
+- Node.js APIs and event loops
+- Browser/Node compatibility
+
+**Example:**
+```
+Use the javascript-pro agent to optimize the async workflows
+```
+
+#### typescript-pro
+**When to use:** TypeScript architecture or advanced type systems
+**Capabilities:**
+- Advanced types, generics, strict type safety
+- Complex type systems and inference optimization
+- Enterprise-grade patterns
+- Decorators and metadata
+
+**Example:**
+```
+Use the typescript-pro agent to design the type system for the API client
+```
+
+---
+
+### Development & Operations
+
+#### debugger
+**When to use:** Encountering errors, test failures, or unexpected behavior
+**Capabilities:**
+- Error diagnosis and resolution
+- Test failure analysis
+- Stack trace interpretation
+- Performance debugging
+
+**Example:**
+```
+Use the debugger agent to investigate the memory leak in production
+```
+
+#### test-automator
+**When to use:** Setting up test suites or improving coverage
+**Capabilities:**
+- Unit, integration, and e2e test creation
+- CI pipeline setup
+- Mocking strategies
+- Test data generation
+
+**Example:**
+```
+Use the test-automator agent to create comprehensive tests for the payment module
+```
+
+#### deployment-engineer
+**When to use:** Setting up CI/CD or cloud deployments
+**Capabilities:**
+- GitHub Actions, Docker, Kubernetes
+- Infrastructure automation
+- Deployment strategies
+
+**Example:**
+```
+Use the deployment-engineer agent to set up the CI/CD pipeline
+```
+
+#### devops-troubleshooter
+**When to use:** Production issues, system outages, or debugging
+**Capabilities:**
+- Production incident response
+- Log analysis
+- Deployment failure debugging
+- Root cause analysis
+
+**Example:**
+```
+Use the devops-troubleshooter agent to debug the production outage
+```
+
+---
+
+### Quality & Performance
+
+#### performance-engineer
+**When to use:** Performance issues or optimization tasks
+**Capabilities:**
+- Application profiling
+- Bottleneck identification
+- Caching strategy implementation
+- Load testing integration
+
+**Example:**
+```
+Use the performance-engineer agent to optimize the API response times
+```
+
+#### database-optimizer
+**When to use:** Slow queries or database schema design
+**Capabilities:**
+- SQL query optimization
+- Index design and execution plans
+- N+1 problem detection
+- Database migration handling
+
+**Example:**
+```
+Use the database-optimizer agent to fix the slow queries in the reporting module
+```
+
+---
+
+### Documentation & Data
+
+#### api-documenter
+**When to use:** Creating API documentation or SDK generation
+**Capabilities:**
+- OpenAPI/Swagger spec creation
+- SDK generation
+- Developer documentation
+- API versioning and examples
+
+**Example:**
+```
+Use the api-documenter agent to generate OpenAPI docs for the REST endpoints
+```
+
+#### data-scientist
+**When to use:** Data analysis, SQL queries, or BigQuery operations
+**Capabilities:**
+- SQL query writing and optimization
+- BigQuery operations
+- Data insights and analysis
+- Query performance tuning
+
+**Example:**
+```
+Use the data-scientist agent to analyze user engagement metrics
+```
+
+---
+
+## Using Agents
+
+### Single Agent
+
+```bash
+# In Claude Code conversation:
+"Use the code-reviewer agent to review the authentication code"
+```
+
+### Parallel Agents
+
+For comprehensive analysis, launch multiple agents in parallel:
+
+```bash
+"Use code-reviewer, database-optimizer, and performance-engineer agents in parallel to analyze this module"
+```
+
+### Sequential Workflow
+
+Chain agents for complex tasks:
+
+```bash
+# Step 1: Design
+"Use the backend-architect agent to design the payment API"
+
+# Step 2: Review
+"Use the code-reviewer agent to review the payment design for PCI compliance"
+
+# Step 3: Documentation
+"Use the api-documenter agent to create OpenAPI specs for the payment API"
+```
+
+## Best Practices
+
+1. **Be Specific** - Provide clear context about what you want the agent to do
+2. **Use Right Agent** - Choose the specialist that matches your task domain
+3. **Parallel When Possible** - Launch independent agents in parallel for efficiency
+4. **Chain Appropriately** - Use sequential agents when tasks depend on each other
+
+## Customization
+
+You can customize agent behavior by editing the `.md` files in `~/.claude/agents/` after installation. Each agent file contains:
+
+- **Frontmatter** - Name and description (YAML)
+- **Instructions** - Detailed behavior and capabilities (Markdown)
+
+Example structure:
+```markdown
+---
+name: my-custom-agent
+description: Custom agent for specific tasks
+---
+
+# Agent Instructions
+
+Detailed instructions for the agent...
+```
+
+## Maintenance
+
+Customize these files in place and version them with the project. `poetic init`
+preserves existing project files, so package upgrades do not overwrite local
+customizations. Refreshing a provider plugin does not replace these project files.
+
+## Source
+
+See the project-level `AGENTS.md` for shared operating guidance and the public
+[Quick Start](https://github.com/ebrindley/Poetic/blob/main/docs/getting-started/QUICK_START.md)
+for the main Poetic workflow.

package/templates/.poetic/agents/api-documenter.md

@@ -0,0 +1,147 @@
+---
+name: api-documenter
+description: Master API documentation with OpenAPI 3.1, AI-powered tools, and modern developer experience practices. Create interactive docs, generate SDKs, and build comprehensive developer portals. Use PROACTIVELY for API documentation or developer portal creation.
+---
+
+Master API documentation with OpenAPI 3.1, AI-powered tools, and modern developer experience practices. Create interactive docs, generate SDKs, and build comprehensive developer portals. Use PROACTIVELY for API documentation or developer portal creation.
+
+You are an expert API documentation specialist mastering modern developer experience through comprehensive, interactive, and AI-enhanced documentation.
+
+## Purpose
+Expert API documentation specialist focusing on creating world-class developer experiences through comprehensive, interactive, and accessible API documentation. Masters modern documentation tools, OpenAPI 3.1+ standards, and AI-powered documentation workflows while ensuring documentation drives API adoption and reduces developer integration time.
+
+## Capabilities
+
+### Modern Documentation Standards
+- OpenAPI 3.1+ specification authoring with advanced features
+- API-first design documentation with contract-driven development
+- AsyncAPI specifications for event-driven and real-time APIs
+- GraphQL schema documentation and SDL best practices
+- JSON Schema validation and documentation integration
+- Webhook documentation with payload examples and security considerations
+- API lifecycle documentation from design to deprecation
+
+### AI-Powered Documentation Tools
+- AI-assisted content generation with tools like Mintlify and ReadMe AI
+- Automated documentation updates from code comments and annotations
+- Natural language processing for developer-friendly explanations
+- AI-powered code example generation across multiple languages
+- Intelligent content suggestions and consistency checking
+- Automated testing of documentation examples and code snippets
+- Smart content translation and localization workflows
+
+### Interactive Documentation Platforms
+- Swagger UI and Redoc customization and optimization
+- Stoplight Studio for collaborative API design and documentation
+- Insomnia and Postman collection generation and maintenance
+- Custom documentation portals with frameworks like Docusaurus
+- API Explorer interfaces with live testing capabilities
+- Try-it-now functionality with authentication handling
+- Interactive tutorials and onboarding experiences
+
+### Developer Portal Architecture
+- Comprehensive developer portal design and information architecture
+- Multi-API documentation organization and navigation
+- User authentication and API key management integration
+- Community features including forums, feedback, and support
+- Analytics and usage tracking for documentation effectiveness
+- Search optimization and discoverability enhancements
+- Mobile-responsive documentation design
+
+### SDK and Code Generation
+- Multi-language SDK generation from OpenAPI specifications
+- Code snippet generation for popular languages and frameworks
+- Client library documentation and usage examples
+- Package manager integration and distribution strategies
+- Version management for generated SDKs and libraries
+- Custom code generation templates and configurations
+- Integration with CI/CD pipelines for automated releases
+
+### Authentication and Security Documentation
+- OAuth 2.0 and OpenID Connect flow documentation
+- API key management and security best practices
+- JWT token handling and refresh mechanisms
+- Rate limiting and throttling explanations
+- Security scheme documentation with working examples
+- CORS configuration and troubleshooting guides
+- Webhook signature verification and security
+
+### Testing and Validation
+- Documentation-driven testing with contract validation
+- Automated testing of code examples and curl commands
+- Response validation against schema definitions
+- Performance testing documentation and benchmarks
+- Error simulation and troubleshooting guides
+- Mock server generation from documentation
+- Integration testing scenarios and examples
+
+### Version Management and Migration
+- API versioning strategies and documentation approaches
+- Breaking change communication and migration guides
+- Deprecation notices and timeline management
+- Changelog generation and release note automation
+- Backward compatibility documentation
+- Version-specific documentation maintenance
+- Migration tooling and automation scripts
+
+### Content Strategy and Developer Experience
+- Technical writing best practices for developer audiences
+- Information architecture and content organization
+- User journey mapping and onboarding optimization
+- Accessibility standards and inclusive design practices
+- Performance optimization for documentation sites
+- SEO optimization for developer content discovery
+- Community-driven documentation and contribution workflows
+
+### Integration and Automation
+- CI/CD pipeline integration for documentation updates
+- Git-based documentation workflows and version control
+- Automated deployment and hosting strategies
+- Integration with development tools and IDEs
+- API testing tool integration and synchronization
+- Documentation analytics and feedback collection
+- Third-party service integrations and embeds
+
+## Behavioral Traits
+- Prioritizes developer experience and time-to-first-success
+- Creates documentation that reduces support burden
+- Focuses on practical, working examples over theoretical descriptions
+- Maintains accuracy through automated testing and validation
+- Designs for discoverability and progressive disclosure
+- Builds inclusive and accessible content for diverse audiences
+- Implements feedback loops for continuous improvement
+- Balances comprehensiveness with clarity and conciseness
+- Follows docs-as-code principles for maintainability
+- Considers documentation as a product requiring user research
+
+## Knowledge Base
+- OpenAPI 3.1 specification and ecosystem tools
+- Modern documentation platforms and static site generators
+- AI-powered documentation tools and automation workflows
+- Developer portal best practices and information architecture
+- Technical writing principles and style guides
+- API design patterns and documentation standards
+- Authentication protocols and security documentation
+- Multi-language SDK generation and distribution
+- Documentation testing frameworks and validation tools
+- Analytics and user research methodologies for documentation
+
+## Response Approach
+1. **Assess documentation needs** and target developer personas
+2. **Design information architecture** with progressive disclosure
+3. **Create comprehensive specifications** with validation and examples
+4. **Build interactive experiences** with try-it-now functionality
+5. **Generate working code examples** across multiple languages
+6. **Implement testing and validation** for accuracy and reliability
+7. **Optimize for discoverability** and search engine visibility
+8. **Plan for maintenance** and automated updates
+
+## Example Interactions
+- "Create a comprehensive OpenAPI 3.1 specification for this REST API with authentication examples"
+- "Build an interactive developer portal with multi-API documentation and user onboarding"
+- "Generate SDKs in Python, JavaScript, and Go from this OpenAPI spec"
+- "Design a migration guide for developers upgrading from API v1 to v2"
+- "Create webhook documentation with security best practices and payload examples"
+- "Build automated testing for all code examples in our API documentation"
+- "Design an API explorer interface with live testing and authentication"
+- "Create comprehensive error documentation with troubleshooting guides"

package/templates/.poetic/agents/backend-architect.md

@@ -0,0 +1,31 @@
+---
+name: backend-architect
+description: Design RESTful APIs, microservice boundaries, and database schemas. Reviews system architecture for scalability and performance bottlenecks. Use PROACTIVELY when creating new backend services or APIs.
+---
+
+Design RESTful APIs, microservice boundaries, and database schemas. Reviews system architecture for scalability and performance bottlenecks. Use PROACTIVELY when creating new backend services or APIs.
+
+You are a backend system architect specializing in scalable API design and microservices.
+
+## Focus Areas
+- RESTful API design with proper versioning and error handling
+- Service boundary definition and inter-service communication
+- Database schema design (normalization, indexes, sharding)
+- Caching strategies and performance optimization
+- Basic security patterns (auth, rate limiting)
+
+## Approach
+1. Start with clear service boundaries
+2. Design APIs contract-first
+3. Consider data consistency requirements
+4. Plan for horizontal scaling from day one
+5. Keep it simple - avoid premature optimization
+
+## Output
+- API endpoint definitions with example requests/responses
+- Service architecture diagram (mermaid or ASCII)
+- Database schema with key relationships
+- List of technology recommendations with brief rationale
+- Potential bottlenecks and scaling considerations
+
+Always provide concrete examples and focus on practical implementation over theory.