Extend dev command with turbo watch mode (task #189)

[nnoce14]

Replace root dev script to use turbo --watch for live rebuilds while developing.

Created in worktree: ../cellixjs-issue-189.

Summary by Sourcery

Introduce an autonomous Turborepo task graph optimization agent skill and enable watch-mode development builds via Turbo in the root dev workflow.

New Features:

• Add a turbo-graph-optimization agent skill for automated Turborepo task graph analysis and optimization, including GitHub Copilot discovery via symlink.

Enhancements:

• Extend the monorepo architectural documentation to describe Turborepo task graph optimization strategy, current CellixJS graph analysis, and usage of the new optimization skill.
• Document the new turbo-graph-optimization skill within the agents skills catalog with its purpose, capabilities, and references.

Build:

• Update the root dev script to run Turbo in watch mode for live rebuilds during development.

Documentation:

• Add detailed guidance on Turborepo task graph optimization, baseline analysis, and usage of the turbo-graph-optimization skill to the monorepo decisions documentation.

[sourcery-ai]

Reviewer's Guide

Introduces a new autonomous Turborepo task-graph optimization agent skill (with documentation and GitHub symlink) and updates the root dev script to run Turborepo in watch mode for live rebuilds, while extending the monorepo Turborepo ADR and skills README with guidance and references for this new capability.

Sequence diagram for turbo-graph-optimization skill end-to-end workflow

sequenceDiagram
    actor Developer
    participant Agent as AgentSkill_turbo_graph_optimization
    participant TurboQuery as Turbo_CLI_turbo_query
    participant TurboRun as Turbo_CLI_turbo_run
    participant FS as Repo_Filesystem

    Developer->>Agent: Invoke turbo-graph-optimization skill

    Agent->>TurboQuery: turbo query --schema
    TurboQuery-->>Agent: GraphQL schema

    Agent->>TurboQuery: turbo query ls (discover packages)
    TurboQuery-->>Agent: Packages and metadata

    Agent->>FS: Read turbo.json and package.json
    FS-->>Agent: Task definitions and scripts

    Agent->>TurboQuery: turbo query (capture baseline per target)
    TurboQuery-->>Agent: Baseline task graphs

    Agent->>FS: Static import analysis on source files
    FS-->>Agent: Import usage data

    Agent->>FS: Apply safe changes to turbo.json
    FS-->>Agent: Updated configuration

    Agent->>TurboRun: turbo run build_or_primary_task
    TurboRun-->>Agent: Build result

    Agent->>TurboQuery: turbo query (capture after state)
    TurboQuery-->>Agent: Updated task graphs

    Agent-->>Developer: Before_after comparison, flags, summary

Loading

Flow diagram for turbo-graph-optimization autonomous workflow

flowchart TD
    A[Start_skill_invocation] --> B[Discover_build_targets_via_turbo_query_ls]
    B --> C[Load_GraphQL_schema_with_turbo_query_schema]
    C --> D[Capture_baseline_task_graph_per_target]
    D --> E[Analyze_transitive_dependencies_and_task_types]
    E --> F[Perform_static_import_analysis_on_source]
    F --> G{Candidate_optimization_safe?}
    G -- Yes --> H[Apply_changes_to_turbo_json_and_related_config]
    G -- No --> I[Flag_change_for_human_review_and_skip_application]
    H --> J[Detect_primary_build_task]
    I --> J
    J --> K{Primary_build_task_detected?}
    K -- Yes --> L[Run_turbo_run_primary_task_for_verification]
    K -- No --> M[Skip_build_verification_document_limitation]
    L --> N{Build_succeeded?}
    N -- Yes --> O[Capture_after_state_via_turbo_query]
    N -- No --> P[Report_build_failure_and_halt]
    M --> O
    O --> Q[Compute_before_after_comparison_and_deltas]
    Q --> R[Output_formatted_results_and_flagged_items]
    R --> S[End_skill_execution]

Loading

File-Level Changes

Change	Details	Files
Enable Turborepo watch mode in the root dev workflow for live rebuilds during development.	Update the root dev npm script to invoke Turborepo with the --watch flag while preserving the existing build, proxy stop/start, and azurite/gen/dev task sequence.	package.json
Document Turborepo task graph optimization as part of the monorepo architecture decisions.	Add a Task Graph Optimization section to the Turborepo ADR explaining motivation, safety approach, current CellixJS task-graph analysis, and when to run optimizations. Describe usage of the turbo-graph-optimization agent skill and link to relevant ADRs and external docs.	apps/docs/docs/decisions/0019-monorepo-turborepo.md
Extend the agents skills catalog documentation to include the new Turborepo graph optimization skill.	Register the turbo-graph-optimization skill in the skills directory tree listing alongside existing MongoDB skills. Add a dedicated Turborepo Task Graph Optimization section that summarizes purpose, use cases, capabilities, key features, and references for the skill.	.agents/skills/README.md
Add a fully documented, repo-agnostic turbo-graph-optimization agent skill for Turborepo task graphs.	Create a new SKILL.md describing the Turborepo task graph optimization agent, including workflow, discovery strategy, safety guarantees, output format, limitations, and CellixJS-specific guidance. Declare metadata such as name, description, license, compatibility, author, and allowed tools for the skill. Detail how the skill uses turbo query GraphQL introspection and static import analysis to propose and verify optimizations autonomously.	.agents/skills/turbo-graph-optimization/SKILL.md
Expose the new turbo-graph-optimization skill to GitHub tooling via symlink.	Add a symlink entry under .github/skills pointing to the new turbo-graph-optimization skill directory for GitHub Copilot discovery.	.github/skills/turbo-graph-optimization

Possibly linked issues

• Extend dev command with turbo watch mode #189: They both target using Turborepo watch mode in the root dev script, though PR also adds extra tooling/docs.

---

Tips and commands

Interacting with Sourcery

• Trigger a new review: Comment @sourcery-ai review on the pull request.
• Continue discussions: Reply directly to Sourcery's review comments.
• Generate a GitHub issue from a review comment: Ask Sourcery to create an
  issue from a review comment by replying to it. You can also reply to a
  review comment with @sourcery-ai issue to create an issue from it.
• Generate a pull request title: Write @sourcery-ai anywhere in the pull
  request title to generate a title at any time. You can also comment
  @sourcery-ai title on the pull request to (re-)generate the title at any time.
• Generate a pull request summary: Write @sourcery-ai summary anywhere in
  the pull request body to generate a PR summary at any time exactly where you
  want it. You can also comment @sourcery-ai summary on the pull request to
  (re-)generate the summary at any time.
• Generate reviewer's guide: Comment @sourcery-ai guide on the pull
  request to (re-)generate the reviewer's guide at any time.
• Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
  pull request to resolve all Sourcery comments. Useful if you've already
  addressed all the comments and don't want to see them anymore.
• Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
  request to dismiss all existing Sourcery reviews. Especially useful if you
  want to start fresh with a new review - don't forget to comment
  @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

• Enable or disable review features such as the Sourcery-generated pull request
  summary, the reviewer's guide, and others.
• Change the review language.
• Add, remove or edit custom review instructions.
• Adjust other review settings.

Getting Help

• Contact our support team for questions or feedback.
• Visit our documentation for detailed guides and information.
• Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.

[sourcery-ai]

Hey - I've left some high level feedback:

• The updated dev script runs turbo run --watch azurite gen:watch dev, which will keep watching all three pipelines together; consider scoping --watch only to the tasks that actually benefit from incremental rebuilds (e.g. dev) or using filters to avoid long-running infra tasks like azurite being restarted unnecessarily.
• Given that pnpm run build still runs before entering watch mode, you might want to split the initial full build into a separate script or make it optional for faster feedback when repeatedly starting pnpm dev during development.

Prompt for AI Agents

Please address the comments from this code review:

## Overall Comments
- The updated `dev` script runs `turbo run --watch azurite gen:watch dev`, which will keep watching all three pipelines together; consider scoping `--watch` only to the tasks that actually benefit from incremental rebuilds (e.g. `dev`) or using filters to avoid long-running infra tasks like `azurite` being restarted unnecessarily.
- Given that `pnpm run build` still runs before entering watch mode, you might want to split the initial full build into a separate script or make it optional for faster feedback when repeatedly starting `pnpm dev` during development.

---

Sourcery is free for open source - if you like our reviews please consider sharing them ✨

• X
• Mastodon
• LinkedIn
• Facebook

_{Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.}