scribe-ai copilot-instructions.md

Scribe AI - Copilot Instructions

Package identity

• Composer name: badrshs/scribe-ai | PHP namespace: Badr\ScribeAi
• Laravel package (no standalone entrypoint). All classes are registered as singletons in ScribeAiServiceProvider.
• Targets Laravel 11/12 and PHP 8.2+.

Testing Workflow - The "done" Command Loop Veru crocial

Before completing ANY task, you MUST:

1. Run php artisan done command and wait for approval
2. user will test, check your code and potentially modify the command with the next instructions
3. If user modifies the command, address their feedback
4. Then Run php .\artisan done again
5. Repeat until the command runs successfully without user modifications

Core architecture

1. Content Pipeline

ContentPipeline sends an immutable ContentPayload DTO through an ordered list of stages using Laravel's Illuminate\Pipeline\Pipeline. Default stage order (configured in config/scribe-ai.php → pipeline.stages):

ScrapeStage → AiRewriteStage → GenerateImageStage → OptimizeImageStage → CreateArticleStage → PublishStage

Writing a stage - implement Contracts\Pipe:

public function handle(ContentPayload $payload, Closure $next): mixed
{
    // Transform and continue:
    return $next($payload->with(['title' => $newTitle]));
    // Or reject (halt pipeline without calling $next):
    return $payload->with(['rejected' => true, 'rejectionReason' => 'duplicate']);
}

Mutating the payload - ContentPayload has readonly properties. Always use $payload->with([...]) to produce a new instance; never try to assign properties directly.

One-off custom stage order:

app(ContentPipeline::class)->through([ScrapeStage::class, MyStage::class])->process($payload);

customStages is consumed and cleared after a single process() call.

2. Publisher Manager

PublisherManager is a Strategy + Manager pattern. Built-in drivers: log, facebook, telegram, blogger, wordpress.

Adding a custom driver (in a service provider):

app(PublisherManager::class)->extend('medium', fn(array $config) => new MediumDriver($config));